The Recorder is the component that captures the audio source, compresses audio data and broadcasts it in the room.
In most cases, you only need 1 active Recorder in the scene which is set up via
VoiceConnection.PrimaryRecorder or as part of PUN or Fusion network object prefab.
- Input Audio Source
- Audio Codec Parameters
- Recording And Transmission
- Primary Recorder
- More Recorders
- AudioChangesHandler Component
- WebRTCAudioDsp Component
Input Audio Source
Set the source you'd like to stream in
Recorder.SourceType field in the Editor or from code.
Microphone Audio Source
One of the microphones available in the system is used as a source.
Set which microphone API you'd like to use in
Recorder.MicrophoneType field in the Editor or from code.
Unity: by default, the Recorder makes use of Unity Microphone API on all platforms. This API is available on a variety of platforms but lacks control over audio capture hardware features, most notably Acoustic Echo Cancellation (AEC).
Photon: use native audio capture modules provided by Poton Voice 2 provides for major platforms: Windows, UWP/Hololens, macOS, iOS, Android. Built-in hardware audio processing is enabled, including AEC.
Microphone Type Fallback
Recorder.UseMicrophoneTypeFallback true when recording fails to start with Unity microphone type, the Recorder tries to use Photon microphone type as a fallback and vice versa.
If you have multiple microphones in the system, you may want to switch from the default microphone by updating
Recorder.MicrophoneDevice property from code.
For Unity Microphone Type, use
UnityEngine.Microphone.devices Unity API property to get a list of devices and set
Recorder.MicrophoneDevice property to the name of selected device wrapped in
new Voice.DeviceInfo(device). You can also use
Voice.Unity.AudioInEnumerator wrapper around
UnityEngine.Microphone.devices. It returns a list of DeviceInfo objects.
For Photon Microphone Type, create a device enumerator with
Voice.Platform.CreateAudioInEnumerator() call, iterate it and set
Recorder.MicrophoneDevice property to the selected device.
Note that enumerating the list of available microphones is available only for Windows, UWP and macOS. On Android and iOS, Photon Microphone Type uses the microphone selected by the system.
Audio Clip Audio Source
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
This can be done by a drag and drop to the Inspector from Unity Editor.
Factory Audio Source
Photon Recorder allows you to have your own custom audio source for whatever use case you have in mind.
Set Recorder's 'InputFactory' property to the function returning an object implementing
If you do not assign 'InputFactory', the factory returning a tone generator will be used by default.
To know more, read "how to use custom audio source?".
Audio Codec Parameters
Recorder.SamplingRate: the sampling rate of streaming audio. Possible values are: 8, 12, 16, 24 and 48 kHz. 16 Hz is enough for speech but setting it higher doesn't hurt. Default is 24 kHz.
Recorder.FrameDuration: the length of an audio fragment in ms transmitted in one network packet. Possible values are 20, 40 and 60 ms. Higher values slightly increase the latency while reducing the number of outgoing packets and therefore the bandwidth due to packet overhead. Default is 20 ms.
Recorder.Bitrate: the maximum amount of data in bits per second that the audio codec produces. This defines the bandwidth of the output stream and affects the audio quality on the receiver end. Default is 30000 b/s.
Other Stream Settings
Recorder.Encrypt: if true, the outgoing audio stream is encrypted. Default is false. read more about "encryption" here.
Recorder.ReliableMode: if true, the outgoing audio stream is transmitted in reliable mode. This may introduce significant delays due to retransmission and may require increasing speaker jitter buffer. Default is false.
Recording And Transmission
Both properties below must be set to true in order to successfully broadcast audio.
Recorder.RecordingEnabledproperty defines if the Recorder is recording, processing audio and compressing it. Resources for the streaming are allocated on both sending and receiving sides as long as the property is true.
Recorder.TransmitEnabledproperty defines if the Recorder sends the compressed audio data to the room. Use it to temporarily mute the stream.
Other properties can update
Recorder.RecordWhenJoinedis true, the Recorder starts recording (sets
Recorder.RecordingEnabledto true) when VoiceConnection joins the room and stops when it leaves.
Recorder.StopRecordingWhenPausedis true, the Recorder pauses recording while the application is paused (handled in OnApplicationPause).
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 group 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 interest group, set
You can select more than one group you want to listen to. By default, all voice clients are subscribed to group 0 only. To update the list of groups you're registered to, you can use the following method from Realtimne API:
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
nullin the respective parameter.
- If you want to add or remove all existing groups, pass an empty array (
byte) in the respective parameter.
- You cannot unsubscribe from the default audio group (0).
Debug Echo Mode
This mode, when enabled via
Recorder.DebugEchoMode property, allows the audio stream transmitted by the client to be received by the same client.
This is useful for quickly testing an application with only one client joined to the room.
Debug Echo Mode works only with Interest Group 0.
Threshold-based Voice Detection
Voice detection, enabled with
Recorder.VoiceDetection property, pauses the transmission if the audio signal level is below a predefined threshold which usually happens when you stop speaking. This will help to avoid sending useless noise and thus reduce traffic.
The threshold is controlled with
Recorder.VoiceDetectionThreshold property, the default value is 0,01.
To adjust the threshold automatically to the actual background noise level, call
period is the time during which the audio signal is analyzed.
Changing specific properties of the Recorder during recording will induce restart of the recording (which causes stopping and restarting the recorder in the next frame). Here is the list of public fields or properties that cause restart when changed in order for them to take effect:
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 property in the Unity Editor or via code.
If the property is set, unityvoiceclient always engages it: initializes and starts recording depending on Recorder settings.
In contrast, punvoiceclient and fusionvoiceclient only use
Primary Recorder directly if
VoiceConnection.UsePrimaryRecorder is true which is useful when you just follow PUN or Fusion state with a single outgoing stream not bound to any network object.
PhotonVoiceView or Fusion's
VoiceNetworkObject is instantiated in the scene and its prefab doesn't have a Recorder, the
Primary Recorder is automatically engaged and bound to the network object. Make sure that only one such network object is instantiated per client to avoid sharing the
If, due to any reason, you would need to use more than just one Recorder, instantiate it if required, set it up, and start using it with
This component detects changes in audio hardware and automatically restarts the Recorder with which it shares the object. Add it manually or using
Add Audio Changes Handler component button in the Recorder Inspector.
On mobile platforms, changes are handled if
AudioChangesHandler.HandleDeviceChangeAndroid properties are set to true.
AudioChangesHandler.HandleDeviceChange property applies to all other platforms.
The wrapper around WebRTC Audio native library available for all major platforms. Most of the effects are recommended to be used with Unity Microphone Type since the audio stream captured with Photon Microphone Type is usually already processed by the hardware. Although
WebRTCAudioDsp.VAD (Voice Auto Detection), pausing the transmission when no speech is detected in the input signal, is useful for any microphone source.
The component is active only if
WebRTCAudioDsp.enabled is true when the outgoing stream is created.
WebRTCAudioDsp.Bypass property can be used to temporarily disable all processing while the component is active.