Recorder Component

The Recorder is the component that will transmit audio stream. Using this component you choose what to stream (Input Audio Source), how to stream it (Audio Quality), when to start and stop transmission (Transmission Toggles) and to whom we transmit (Receiver Target). Also the Recorder requires initialization

Contents

Input Audio Source

The Recorder supports various types of input audio feed to stream. The most obvious one is the microphone which is used for voice chat. However, the Recorder supports two other types of input source.

Microphone Selection

If the Recorder.SourceType is set to Recorder.InputSourceType.Microphone there is another option that determines the type of the microphone API to be used. Each Recorder can have its own type of microphone input device that can be set using Recorder.MicrophoneType. The two different values are:

Unity

By default, we make use of Unity's Microphone API on all platforms. Unity exposes all available audio input devices using Microphone.devices array of strings. The mircophone device can be identified using its string name or its index in that array. By default the first element of that array will be used. If you want to set another device explicitly, do it using Recorder.PhotonMicrophoneDeviceId.

To use Unity's Microphone API simply set the Recorder.MicrophoneType to Recorder.MicType.Unity.

Photon

Unity is great for making it easier to target multiple platforms using almost same code base. However, in some ways, Unity's Microphone API is limited or present some issues here and there. That is why we introduced our own way of directly interacting with audio input devices and bypassing Unity's Microphone API. One of the major reasons for this is to make use of devices' hardware built-in echo cancellation. We have implemented native plugins for four major platforms: Android, iOS, Windows and macOS.

However, enumerating the list of available microphones is available only for macOS and Windows. On Android and iOS we use the default audio input device used by the system. You can check the list of available "Photon microphones" using Recorder.PhotonMicrophoneEnumerator as follows:

var enumerator = Recorder.PhotonMicrophoneEnumerator;
if (enumerator.IsSupported) 
{
    for (int i = 0; i < enumerator.Count; i++) 
    {
        Debug.LogFormat("PhotonMicrophone Index={0} ID={1} Name={2}", i, enumerator.IDAtIndex(i), 
            enumerator.NameAtIndex(i));
    }
}

You can set a microphone using Recorder.PhotonMicrophoneDeviceId.

To use Photon's Microphone API simply set the Recorder.MicrophoneType to Recorder.MicType.Photon.

Microphone Access: Recording And Muting

By design, the Recorder component will start recording automatically once initialized.

Since Photon Voice version 2.5 we have introduced a new property Recorder.IsRecording. This value can be set at runtime (play mode) once the recorder is initialized.

So if you want to stop recording and "release" the microphone you can set Recorder.IsRecording to false. Set it back to true to resume recording.

By design, when recording is disabled the voice stream is completely gone.

If you are looking for options to mute the microphone 'locally' ('self-muting'), you can use either Recorder.TransmitEnabled or Recorder.IsRecording.

Streaming Audio Clips

This option was introduced to test Photon Voice transmission. However, you may use it for other purposes. In order to broadcast an audio clip to other players joined to the same room, you need to assign an audio media file supported by Unity to Recorder.AudioClip. This can be done by a drag and drop to the Inspector from Unity Editor. If you want the audio clip to be replayed every time make sure Recorder.LoopAudioClip is set to true or tick "Loop" from Unity Editor for the Recorder's inspector.

Custom Factory

Photon Recorder allows you to have your own custom audio source for whatever use case you have in mind. To know more, read "How to use custom audio source?".

Audio Quality

Codec parameters are the main factor here:

  • SamplingRate: a frequency of how many times audio is measured per second. Generally, this defines the audio quality you want. Possible values are: 8, 12, 16, 24 and 48 kHz. Default is 24 kHz.
  • FrameDuration: outgoing audio stream encoder delay in milliseconds (buffer size in terms of time). Possible values are 5, 10, 20, 40, 80 and 120 ms. Default is 20 ms.
  • Bitrate: the amount of data (the number of bits) that are processed over a certain amount of time (second). Generally, this defines the compression quality. Default value is 30000 b/s.

Other Stream Settings

  • Encrypt: if true, all outgoing voice streams will be encrypted. Default is false. Read more about "Encryption" here.
  • ReliableMode: if true, all outgoing voice streams will be in reliable mode. Default is false.

Transmission Toggles

You can toggle transmission using Recorder.TransmitEnabled. There is also VoiceDetection that can be used to make sure we don't transmit useless background noise.

Push-to-Talk

It is easy to have a push-to-talk feature with Photon Voice. You need to manually toggle voice recording and transmission. It's like turning microphone mute on and off. To start push-to-talk just set Recorder.TransmitEnabled to true. To stop it just set the value back to false. You can achieve this by binding the property to a user input (UI button or keyboard shortcut).

Voice Detection

Voice detection is an optional feature that will filter recorded sound and transmits only when a predefined threshold of signal level is exceeded. This means that voice transmission is automatically paused when you stop speaking and it is resumed when you start talking. This will also help you avoid sending useless noise and thus reduce traffic.

The default value of VoiceDetectionThreshold is 0,01. It is the recommended value for common environments as a result of experiments with voice detection calibration and noise level measurements.

Voice Calibration

If you still experience issues when recording your voice even with voice detection is on, you may need voice calibration. Photon Voice offers an auto calibration mode which is limited in time. To start calibration mode you should call Recorder.VoiceDetectorCalibrate(period). The default calibration period is 2000 milliseconds but you can always change it. Using calibration, Photon Voice automatically adjusts silence and loudness thresholds.

Receiver Target

This is done via Audio Groups. Optionally you could receive your own streams if DebugEchoMode is enabled.

Interest Groups

Photon Voice is not for broadcast only. You can offer your players the possibility to have multiple conversations going on at the same time without interfering with each other. This can be done using "Interest Groups". An "Interest Groups" is identified by a number (byte). You can subscribe and unsubscribe from multiple groups. However, you can only transmit audio to one group at a time.

By default, the recorder's interest group is set to 0 : each player can talk to everyone else. To set the target interst group, set Recorder.InterestGroup which 0 by default.

You can select more than one group you want to listen to. By default, all voice clients are subscribed to the group 0 only. To update the list of groups you're registered to, you can use the following method:

VoiceConnection.Client.OpChangeGroups(byte[] groupsToRemove, byte[] groupsToAdd);

You should take into consideration the following notes when changing audio groups:

  • It can be done only when joined to a "voice room".
  • If you don't want to add or remove any group pass a null in the respective parameter.
  • If you want to add or remove all existing groups pass an empty array (byte[0]) in the respective parameter.
  • You cannot unsubscribe from default audio group (0).

Audio groups can be combined with Push-to-Talk to obtain nice features for your game.

Debug Echo Mode

This mode, when enabled, allows audio streams transmitted by local Recorder to be received by the same voice client. This is useful for debugging purposes, some use cases:

  • testing audio quality, delays or setup with one actor only joined to a room, especially during early development phase
  • testing one's microphone or speakers
  • other scenarios that involve need for own echo or true broadcast

Debug Echo Mode works only with Interest Group 0.

Primary Recorder

Since in most cases, a single Recorder component is used, we have provided a shortcut for a single default Recorder called "Primary Recorder" which can be accessed from VoiceConnection.PrimaryRecorder (or PhotonVoiceNetwork.PrimaryRecorder). You can set it in the Unity Editor or via code.

Initialization

In order to work the Recorder needs to be initialized once using a VoiceClient object and optional custom UserData object. By default the Recoder will automatically start recording when initialized. To disable this behaviour and manually start recording using Recorder.StartRecording() after initiliazation, set Recorder.AutoStart to false. You can stop recording using Recorder.StopRecording().

Restart

You need to set the Recorder settings you want before recording is started, otherwise you will need to restart using Recorder.RestartRecording().

To know if the Recorder needs to be restarted, you can check the 'IsDirty' like flag Recorder.RequiresRestart.

Here is the list of things that require restart when changed in order for them to take effect:

  • Recorder.UserData
  • Recorder.AudioSourceFactory
  • Recorder.UnityMicrophoneDevice
  • Recorder.PhotonMicrophoneDeviceId
  • Recorder.Source
  • Recorder.MicrophoneType
  • Recorder.TypeConvert
  • Recorder.AudioClip
  • Recorder.SamplingRate
  • Recorder.FrameDuration
  • Recorder.Bitrate

Here is the list of things that do not require restart and will take effect immediately if the transmission is enabled:

  • Recorder.TransmitEnabled
  • Recorder.Encrypt
  • Recorder.ReliableMode
  • Recorder.DebugEchoMode
  • Recorder.VoiceDetection
  • Recorder.VoiceDetectionThreshold
  • Recorder.VoiceDetectionDelayMs
  • Recorder.AudioGroup
  • Recorder.LoopAudioClip (if conditions are met)

React On System Changes

Sometimes if you add or remove input or output audio device(s) from the system settings or if you switch the default one, Photon Voice can stop working properly. Since Photon Voice 2.5 we have introduced a new property Recorder.ReactOnSystemChanges that, once enabled, will make the Recorder automatically reinitializes itself to recover from such system changes. The default value is false for backward compatibility. You can set this value in edit mode or in play mode.

To Document Top