Developer Documentation

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 survives 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 survice 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.

SettingDescription
Playback MixerCreate a Unity AudioMixer asset and drag it into this field.
Playback Mixer GroupCreate 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 that distinguishes this setting to 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 voice is 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 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 and handles the lifetime of it.

However, you are responsible to attach the PlaybackComponent to a GameObject representing the player (in space) and thus allowing you to implement 3D audio with ease.

Check out these guides on how to get notified of 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. Shows the basic workflow and basic event handling.
  • Unity with Mirror Networking: Shows how to implement ODIN into a multiplayer game built with mirror networking. Create a simple multi-player game and add ODIN to it in under 20 minutes.

What you basically have to do is to listen on 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 joined the room and added a media object or removed it (i.e. muted their audio). Please note, that users can join a room without adding their own media stream (i.e. spectators).

You’ll need to call AddPlaybackComponent method which will create a PlaybackComponent and attach it to the Game Object that you provide. Of course, you’ll need to have some logic to find the correct player GameObject for the ODIN. Every ODIN user (peer) has it’s 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 on how to handle the event. More examples can be found in the reference documentation of 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 fill 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 a couple of events that allows you to react on 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 infos about that.

These are standard Unity events. Click on the + button to add a listener and than 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 on these in your own scripts by attaching callbacks.

Event TypeDescription
Room JoinCalled before a player joins a room: OnRoomJoin
Room JoinedCalled after a player joined a room: OnRoomJoined
Room LeaveCalled before a player leaves a room: OnRoomLeave
Room LeftCalled after a player left 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 his user data, these events are triggered and allow you to react on those in your own scripts.

PropertyDescription
Peer JoinedCalled when another player joined the room: OnPeerJoined
Peer LeftCalled when another player left the room: OnPeerLeft
Peer UpdatedWhen the user data of a peer changes, this callback is called: 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 sending media into the room. A typical use case for this is a spectator or in a podcast, only the podcaster is able to say something while the others are just listening.

It’s the same in ODIN: If a player connects a room, the Peer Joined event is triggered. Now, the player listens to the audio streams in this room. If the Odin Handler 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 notifying all other peers, that there is an additional audio stream they need to listen to now.

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

Media events

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

PropertyDescription
Media AddedCalled when the microphone stream of another user is joining the room: OnMediaAdded
Media State ChangedCalled when the medias state changed: OnMediaActiveStateChanged
Media RemovedWhen one of the peers removes his microphone stream of the room, this callback is triggered: OnMediaRemoved

Microphone Reader settings

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