Odin Handler

Switch to scripting

The

OdinHandler

component class is the global manager (singleton) for ODIN inside your game. You can use it to connect your own callbacks.

info

ODIN uses DontDestroyOnLoad in this class to make sure that this component and game object survive scene changes.

Microphone

The first option provided in the Odin Handler Inspector is the microphone setting:

Drag & Drop the Game Object within your scene that has the Microphone Reader component attached. If you have created a standard ODIN Manager Game Object by following our manual, then this will be the same game object that the Odin Handler is attached to.

warning

If you put the Microphone Reader component on a different game object than the Odin Handler, you need to make sure that the other game object also uses DontDestroyOnLoad to survive scene changes. Otherwise, your players will not be able to talk to other players as their microphone game object got removed. Of course, you can also use that as a feature to disable microphone input in specific scenes. But you need to be careful with lifecycle management of your game objects if you separate Odin Handler and Microphone Reader into different game objects.

Mixer Settings

Another set of options is playback mixer settings.

Sometimes you want to apply some audio effects to voice, like cell broadcast interferences or noise. Create a Unity

AudioMixerGroup

or AudioMixer and assign it to one of these options.

Setting	Description
Playback Mixer	Create a Unity AudioMixer asset and drag it into this field.
Playback Mixer Group	Create a Unity AudioMixerGroup asset and drag it into this field.

Playback Creation

In this section, you can activate some SDK automations that make your life easier. In some special cases, you might take control of various aspects yourself, but for most use cases, you can make use of these automations.

info

Please note: You should only select one of these checkboxes. We'll change that to a drop-down field in the next version of the SDK.

If both settings are unchecked, you'll need to handle the events like

OnMediaAdded

yourself and you'll also need to create audio pipeline elements yourself. See the source code of the SDK on how to do that.

Playback auto creation

If you check this box, the ODIN SDK will automatically create an AudioSource and link that to the ODIN server for you, and will handle the lifetime for you.

In addition to that, and what distinguishes this setting from Manual Positional Audio, is that the

PlaybackComponent

will be automatically attached to the GameObject with the

OdinHandler

attached.

This is the easiest way to implement a simple "video conferencing"-like use case where you don't have positional audio or specific teams.

info

As all users' voices are attached to one GameObject automatically, you cannot implement any form of 3D audio this way. If you want to have 3D audio, you need to deactivate this setting and activate Manual Positional Audio instead (see the description below).

Manual Positional Audio

If you check this box (and uncheck the other setting), ODIN will automatically create an AudioSource for you and link that to the ODIN server, handling the lifetime of it.

However, you are responsible for attaching the

PlaybackComponent

to a GameObject representing the player (in space), thus allowing you to implement 3D audio with ease.

Check out these guides on how to get notified by the SDK once an audio stream has been prepared and how to handle the event:

• Getting Started with Unity: Create a simple Unity project and add ODIN to it. This guide shows the basic workflow and event handling.
• Unity with Mirror Networking: Shows how to implement ODIN into a multiplayer game built with Mirror Networking. Create a simple multiplayer game and add ODIN to it in under 20 minutes.

What you essentially need to do is listen for the

OnCreatedMediaObject

and

OnDeleteMediaObject

events of the

OdinHandler

instance like this:

void Start()
{
    OdinHandler.Instance.OnCreatedMediaObject.AddListener(OnCreatedMediaObject);
    OdinHandler.Instance.OnDeleteMediaObject.AddListener(OnDeleteMediaObject);
}

ODIN will call these events once a user joins the room and adds a media object or removes it (i.e., mutes their audio). Please note that users can join a room without adding their own media stream (i.e., spectators).

You'll need to call the

AddPlaybackComponent

method, which will create a

PlaybackComponent

and attach it to the GameObject that you provide. Of course, you'll need some logic to find the correct player GameObject for ODIN. Every ODIN user (peer) has its own user data, which you can use to link your GameObjects to ODIN. The best place to learn how to do that is our guide Unity with Mirror Networking.

Here is a simple example of how to handle the event. More examples can be found in the reference documentation of the

PlaybackComponent

, the

OnMediaAdded

event, and the guides linked above.

private void OnCreatedMediaObject(string roomName, ulong peerId, int mediaId)
{
    Room room = OdinHandler.Instance.Rooms[roomName];
    if (room == null || room.Self == null || room.Self.Id == peerId) return;

    // Create or find a player object in the scene
    var peerContainer = CreateOrFindGameObject(peerId, roomName);

    // Create PlaybackComponent and add to the players' GameObject
    PlaybackComponent playback = OdinHandler.Instance.AddPlaybackComponent(peerContainer, room.Config.Name, peerId, mediaId);

    // Set spatialBlend to 1.0f to activate full 3D audio and adjust some 3D audio settings
    // This is basic Unity stuff. PlaybackSource is an AudioSource object. See Unity documentation for more info 
    playback.PlaybackSource.spatialBlend = 1.0f;
    playback.PlaybackSource.rolloffMode = AudioRolloffMode.Linear;
    playback.PlaybackSource.minDistance = 1;
    playback.PlaybackSource.maxDistance = 10;
}

Events

ODIN has several events that allow you to react to things that happen within the ODIN runtime. Use these settings to connect your own game objects and scripts to ODIN. You can also do that in code if you like. Have a look at the

OdinHandler

class for more information.

These are standard Unity events. Click on the + button to add a listener and then drag & drop the game object that has your handler script attached, exposing public callbacks for the events you want to listen to.

Read more about the events available in our scripting documentation:

Room events

These events are sent if anything happens with the rooms the player has joined. Use the

JoinRoom

method of the

OdinHandler

class to connect the player to one or more rooms. These events will then trigger and allow you to react in your own scripts by attaching callbacks.

Event Type	Description
Room Join	Called before a player joins a room: OnRoomJoin
Room Joined	Called after a player joins a room: OnRoomJoined
Room Leave	Called before a player leaves a room: OnRoomLeave
Room Left	Called after a player leaves a room: OnRoomLeft

Peer events

Whenever something happens in the room the player is connected to (i.e., another player joins the room or updates their user data), these events are triggered and allow you to react in your own scripts.

Property	Description
Peer Joined	Called when another player joins the room: OnPeerJoined
Peer Left	Called when another player leaves the room: OnPeerLeft
Peer Updated	Called when the user data of a peer changes: OnPeerUserDataChanged

warning

It's important to understand the difference between a peer and a media stream. In ODIN, it's possible to join a room as a listener but not send media into the room. A typical use case for this is a spectator or in a podcast where only the podcaster can speak while others just listen.

It's the same in ODIN: If a player connects to a room, the Peer Joined event is triggered. Now, the player listens to the audio streams in this room. If the OdinHandler of the other player has a Microphone Reader attached and is active and recording, a Media Added event will be triggered once the audio stream of the other player is added, notifying all other peers that there is an additional audio stream they need to listen to.

If the other player disables their microphone, a Media Removed event is triggered, and all other peers will stop listening to this audio source.

Media events

When media streams are added or removed, you'll receive these events.

Property	Description
Media Added	Called when the microphone stream of another user joins the room: OnMediaAdded
Media State Changed	Called when the media's state changes: OnMediaActiveStateChanged
Media Removed	Called when one of the peers removes their microphone stream from the room: OnMediaRemoved

Microphone Reader settings

In a typical ODIN Manager Game Object, a Microphone Reader component is attached, which handles the player's microphone and audio input. Let's dig through these settings here: Microphone Reader.