ODIN Voice Web SDK
ODIN is our cross-platform immersive voice SDK with best-in-class quality and noise suppression technologies. You can integrate it with ease in your TypeScript/JavaScript-based applications. The SDK gets initialized by providing a compatible Voice Plugin.
The ODIN web SDK is fully compatible with our other client SDKs, so you can communicate between your favorite web browser and any native app or game that integrates ODIN.
While next-gen browsers and native ODIN SDKs use WebTransport over HTTP/3 to talk to an ODIN server using a secure and reliable multiplexed transport, we've also implemented a fallback mechanism over WebRTC data channels for browsers without HTTP/3 support.
Installation
You can install the ODIN web SDK in your NodeJS project to use it with any modern JavaScript framework or include it directly in your HTML.
NPM
Install the web SDK and Plugin via npm
in your project like this:
HTML
If you want to include ODIN in your website, you can add ODIN with this script tag to your website:
You can now use the code as shown in the samples.
Usage
To use and interact with the ODIN WebSDK, there are a few general steps that every implementation will need.
- Initializing the Voice Plugin (@4players/odin-plugin-web)
- Fetching the
Token
from your backend - Creating a room and registering
EventHandlers
- Joining a
Room
with the providedToken
- Starting an
AudioInput
to be able to talk
Below, these steps are explained in detail.
The following guideline is built upon each other. Imports of JavaScript code are not included because they might differ on how the implementation was done. For more complete examples, please check our respective examples.
Initializing the Audio Plugin
Fetching a token and creating a room
Before a client can join a room, two things need to happen: the room instance itself must be created, and an authentication token must be fetched from your backend server.
It's crucial that these tokens are generated and served by your backend. This is because the accessKey
required to create valid ODIN tokens is a sensitive credential that should never be exposed directly to the public (e.g., in client-side code). To simplify the process of generating these tokens on your backend, we provide an npm package specifically for this purpose.
Handling Events
The ODIN server will automatically notify you about relevant updates, and the ODIN web SDK uses the JavaScript
EventTarget API to dispatch custom events based on
the OdinEventTargetaddEventListener
methods to set up a function that will be called whenever the specified event is delivered to the target.
To prevent memory leaks when reusing a room instance for multiple connections, ensure that EventListeners
are handled correctly. You should either:
- Remove event listeners when leaving the room.
- Ensure that event listeners are registered only once.
Alternatively, you can use the room.onPeerJoined
syntax. This assigns a callback directly, overwriting any previous assignment, which can simplify event management and help avoid unintended multiple registrations.
Besides using room.addEventListener
, there's a simpler, alternative method for handling events. For every available event, you can assign a callback function directly to a corresponding property, similar to how events are handled on many standard Web API objects in the browser.
Events are available in the following scopes:
Room
->RoomEvents
LocalPeer
andRemotePeer
->PeerEvents
AudioInput
andAudioOutput
->MediaEvents
This allows fine-grained control over which events you want to receive on any specific class instance, most notably
Room
All Events are available as on the instances via properties too.
Joining a room
Once the token was fetched, the room instance created and room events registered, we can join the room.
EventHandlers (Callbacks) like room.onJoined
, room.onPeerJoined
, room.onStatusChanged
will get called when joining a room.
Starting Audio
The ODIN SDK uses instances of AudioInput
While an AudioInputAudioInput
can be created at any point, this example demonstrates creating it after successfully joining a room for simplicity. To be able to speak in a room, an room.addAudioInput(audioInput)
.
To hear other peers in the room, you must configure an output device. This is done once by calling audioPlugin.setOutputDevice({})
on the AudioPlugin
instance. Since the output device setting is global to the audio plugin, the method is called directly on the plugin object.
Important Note: Both audioPlugin.setOutputDevice({})
and room.AddAudioInput()
will attempt to start the browser's AudioContext
. Modern browsers require a direct user interaction (like a click or tap) to allow an AudioContext
to start. Therefore, it's best practice to call these methods from within a function that is triggered by a user action. For instance, invoking them in the same function that handles the user's action to join a room, as demonstrated in the example, is a recommended approach.
Important Note: Audio is only transmitted, after an AudioInput was attached to a room by using room.addAudioInput(audioInput)
.
Leaving a room
To disconnect a player from an Odin room, you can call:
While a Room
instance can technically be reused for multiple connections, it is often simpler to create a new Room
instance each time you connect.
In contrast, an AudioInput
instance is independent of the Room
's lifecycle and should typically be reused across connections.