Show Sidebar

Photon Voice For PUN

Getting Started

Photon Voice for PUN is an add-on that brings voice and audio streaming to PUN. It depends on PUN and it requires a separate Photon Realtime application.

Photon Voice for PUN should be imported into a Unity project where PUN is already present and configured.

"Voice room" refers to the room joined by Photon Voice client. It will be used often in this document to avoid confusion with the room joined by PUN client. On the other hand, "PUN room" will refer to the room joined by PUN client.

When PUN client is in state "Joined" (in a "PUN room"), it is possible to connect or disconnect Photon Voice application from cloud. Other than that, users do not have to explicitly interact with the Photon Voice application. Photon Voice client automatically handles connection workflow. It will create or join a "voice room" with the same name as the joined "PUN room".

Supported Platforms

  • Standalone: Windows, Mac, Linux
  • Windows Store Universal 10
  • iOS (not in simulator)
  • Android

Configure

Once you import Photon Voice to the project, a "Photon Voice Settings" section should appear to PhotonServerSettings just below PUN settings. There you can enter the AppId of your Photon Voice application. Remember that you can always reopen the PhotonServerSettings in the Unity Inspector by following these steps: "Window" -> "Photon Unity Networking" -> "Highlight Server Settings".

To tweak advanced audio and voice related settings, make sure a PhotonVoiceSettings script is attached to one object in the scene. The available settings are described as follows:

  1. PUN related settings:
    • AutoConnect: auto join Photon Voice client to a "voice room" when PUN client is joined to a "PUN room".
    • AutoDisconnect: auto disconnects Photon Voice client when PUN client is disconnected.
    • AutoTransmit: starts transmitting audio as soon as Photon Voice client is joined to a "voice room".
  2. Microphone and "local" audio recording settings that will be applied to every "recorder" instance created:
    • 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.
    • Delay: 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.
  3. "Remote" audio streaming settings that will be applied to every "speaker" instance created:
    • PlayDelayMs: playback delay in milliseconds. Used to compensate incoming packets latency variations.
  4. Voice detection feature (will be applied to every "recorder" instance created):
    • VoiceDetection: toggle voice detection feature.
    • VoiceDetectionThreshold: minimal signal level to be exceeded to start transmission if voice detection is enabled. 0.01 is the default and recommended value.
  5. Miscelleanous:
    • DebugInfo: toggle Photon Voice debug logs in Unity console at info level.
    • DebugLostPercent: lost frames simulation ratio.

The "Audio Source" Prefab

Photon Voice for PUN expects each "audio source" object to be represented by a prefab.
The minimal required prefab should contain two script components attached to the same GameObject:

  • PhotonView
  • PhotonVoiceRecorder
Photon Voice's AudioSource should be used exclusively for voice chat by Photon Voice. If you want to have other sounds per player, use a separate AudioSource attached to a separate GameObject.

After adding the PhotonVoiceRecorder script, you will notice that an AudioClip component has been added and also a PhotonVoiceSpeaker script. Both are essential to reproducing received remote audio from other clients joined to the same room.

The prefab should be instantiated only at runtime and after joining a room using PUN. Scene object instances are not supported. So you should not have any PhotonVoiceRecorder instances in the scene.

The audio source prefab is used for two different purposes:

  1. Record and transmit "local" sound:
    This is handled by PhotonVoiceRecorder. Check the IsTransmitting property of the same component to know if the recorded audio is being sent or not.
  2. Reproduce and play received "remote" sound:
    This is managed by PhotonVoiceSpeaker. Use its IsPlaying property to see if a remote received audio is being played.

This audio source prefab can be used in two different ways:

  1. Voice Chat:
    If no audio clip is assigned to PhotonVoiceRecorder and if a microphone device is detected, audio will be recorded and transmitted to all other joined players. In case multiple recording devices are available, the one to be used need to be set to PhotonVoiceRecorder.MicrophoneDevice property.
  2. 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 PhotonVoiceRecorder.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 PhotonVoiceRecorder.Loop is set to true.

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

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

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 PhotonVoiceRecorder.Transmit 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).

Audio 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 "Audio Groups" which makes use of Photon's "Interest Groups" feature. An "Audio 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, all voice clients are subscribed to the group "0": each player can hear everyone else and talk to everyone else. If you want to replace this default behaviour, change the "Global Audio Group" using the property with the same name PhotonVoiceNetwork.Client.GlobalAudioGroup. Only players registered to that group will hear the audio you transmit.

On the other hand, you can select more than one group you want to listen to. To update the list of groups you're registered to, you can use the following method:

PhotonVoiceNetwork.Client.ChangeAudioGroups(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.

Example Use Case 1: Private Conversations

You can add private voice chat in few steps:

  • If n is the number of players create n * (n - 1) audio group numbers and bind each one to a couple of players. Example: Player 1 and Player 2 can subscribe to group "12" or "21".
  • A player should subscribe to all audio groups shared with another player at once or subscribe on demand for a "phone call like" feature.
  • A player can talk to exactly one player by setting the GlobalAudioGroup to the corresponding shared "binary audio group" number.

Example Use Case 2: Team Chat

If you are implementing teams in your game, you can add "team chat" easily as follows:

  • Assign a group number per team.
  • A player should subscribe to the audio group of the team he/she belongs to.
  • Players of the same team can talk to each other by setting the GlobalAudioGroup to the team's audio group number.

Known Issues

Android 6.0 Permissions

Usually when building for Android platform, most permissions will be added by automatically by Unity to the manifest file. The two permissions required by Photon Voice are:

  • android.permission.INTERNET: automatically added via Unity's Player Settings.
  • android.permission.RECORD_AUDIO: automatically added when Unity's microphone API is used.

However, with Android Marshmallow there seems to be a problem due to the newly introduced permissions model. The generated APK will be missing android.permission.RECORD_AUDIO permission and the application will not be able to record your voice. To avoid such issue please update to the latest Unity version when targeting Android SDK level 23.

 To Document Top