Recorder Component

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.

Contents

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.

Microphone Types

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.

Back To Top

Microphone Type Fallback

If 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.

Back To Top

Microphone Selection

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.

Back To Top

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 Recorder.AudioClip. This can be done by a drag and drop to the Inspector from Unity Editor.

Back To Top

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 Photon.Voice.IAudioReader or Photon.Voice.IAudioPusher interfaces. 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?".

Back To Top

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.

Back To Top

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.

Back To Top

Recording And Transmission

Both properties below must be set to true in order to successfully broadcast audio.

  • Recorder.RecordingEnabled property 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.TransmitEnabled property defines if the Recorder sends the compressed audio data to the room. Use it to temporarily mute the stream.

Other properties can update Recorder.RecordingEnabled automatically:

  • If Recorder.RecordWhenJoined is true, the Recorder starts recording (sets Recorder.RecordingEnabled to true) when VoiceConnection joins the room and stops when it leaves.

  • If Recorder.StopRecordingWhenPaused is true, the Recorder pauses recording while the application is paused (handled in OnApplicationPause).

Back To Top

Interest Groups

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 Recorder.InterestGroup.

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 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 the default audio group (0).

Back To Top

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.

Back To Top

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 Recorder.VoiceDetectorCalibrate(period) where period is the time during which the audio signal is analyzed.

Back To Top

Automatic Restart

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:

  • Recorder.UserData
  • Recorder.InputFactory
  • Recorder.SourceType
  • Recorder.MicrophoneType
  • Recorder.MicrophoneDevice
  • Recorder.AudioClip
  • Recorder.SamplingRate
  • Recorder.FrameDuration
  • Recorder.Bitrate
  • Recorder.UseOnAudioFilterRead
  • Recorder.IsRecording

Back To Top

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

If PUN's 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 Primary Recorder.

Back To Top

More Recorders

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 VoiceConnection.AddRecorder(Recorder) method.

Back To Top

AudioChangesHandler Component

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.HandleDeviceChangeIOS or AudioChangesHandler.HandleDeviceChangeAndroid properties are set to true. AudioChangesHandler.HandleDeviceChange property applies to all other platforms.

Back To Top

WebRTCAudioDsp Component

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.

To Document Top