voice

Voice

The Voice module carries real-time audio between players on top of a connected Realtime client. Create a local voice to transmit captured audio, receive remote voices from the frame queue, and mix or mute remote players locally.

Note

Voice runs alongside Realtime. Connect and service the Realtime client, and also call photon_voice_service every step.

Lifecycle

Initialise and service the Voice client:

• photon_voice_init
• photon_voice_shutdown
• photon_voice_service
• photon_voice_is_initialized

Channel & player membership

Notify the voice system about room, channel and player events:

• photon_voice_notify_joined_room
• photon_voice_on_join_channel
• photon_voice_on_leave_channel
• photon_voice_on_join_all_channels
• photon_voice_on_leave_all_channels
• photon_voice_on_player_join
• photon_voice_on_player_leave

Local voice

Create and drive an outgoing voice stream:

• photon_voice_create_local_voice
• photon_voice_remove_local_voice
• photon_voice_push_frame_buffer
• photon_voice_local_voice_set_transmit
• photon_voice_local_voice_get_transmit

Remote voice

Read incoming audio frames and inspect remote streams:

• photon_voice_get_frame_queue_count
• photon_voice_clear_frame_queue
• photon_voice_peek_next_frame_size
• photon_voice_peek_next_frame_player_id
• photon_voice_peek_next_frame_voice_id
• photon_voice_receive_frame_buffer
• photon_voice_get_remote_voice_count
• photon_voice_get_remote_voice_player_id
• photon_voice_get_remote_voice_id
• photon_voice_get_remote_voice_codec
• photon_voice_get_remote_voice_sample_rate
• photon_voice_get_remote_voice_channels
• photon_voice_get_remote_voice_is_speaking

Remote player mixing

Mute and set the volume of remote players locally:

• photon_voice_set_remote_player_muted
• photon_voice_get_remote_player_muted
• photon_voice_set_remote_player_volume
• photon_voice_get_remote_player_volume

Statistics & tuning

Inspect voice statistics and tune behaviour:

• photon_voice_get_frames_sent
• photon_voice_get_frames_received
• photon_voice_get_frames_lost
• photon_voice_get_round_trip_time
• photon_voice_get_round_trip_time_variance
• photon_voice_get_debug_lost_percent
• photon_voice_set_debug_lost_percent
• photon_voice_get_speaking_threshold_ms
• photon_voice_set_speaking_threshold_ms

Callbacks

Register and remove the Voice event callbacks:

• photon_voice_set_callback_remote_voice_added
• photon_voice_set_callback_remote_voice_removed
• photon_voice_set_callback_speaking_changed
• photon_voice_set_callback_debug
• photon_voice_remove_callback_remote_voice_added
• photon_voice_remove_callback_remote_voice_removed
• photon_voice_remove_callback_speaking_changed
• photon_voice_remove_callback_debug

Constants

The Voice module defines the following constants:

• PhotonVoiceCodec

---

Back To Top

photon_voice_init

Initialises the Voice client. Voice runs on top of a connected Realtime client, so connect Realtime first.

Syntax:

photon_voice_init()

Returns:

Boolean

Whether initialisation succeeded.

---

Back To Top

photon_voice_shutdown

Shuts the Voice client down and releases its resources.

Syntax:

photon_voice_shutdown()

Returns:

Boolean

Whether the client was shut down.

---

Back To Top

photon_voice_service

Dispatches queued voice traffic. This must be called every step while using voice.

Syntax:

photon_voice_service()

Returns:

Boolean

Whether the client was serviced.

---

Back To Top

photon_voice_is_initialized

Returns whether the Voice client has been initialised.

Syntax:

photon_voice_is_initialized()

Returns:

Boolean

Whether the client is initialised.

---

Back To Top

photon_voice_notify_joined_room

Notifies the voice system that the Realtime client has joined a room, so voice transport can start.

Syntax:

photon_voice_notify_joined_room()

Returns:

Boolean

Whether the notification was handled.

---

Back To Top

photon_voice_on_join_channel

Notifies the voice system that the local client joined the given voice channel.

Syntax:

photon_voice_on_join_channel(channel_id)

Argument	Type	Description
channel_id	Real	The channel ID.

Returns:

Boolean

Whether the notification was handled.

---

Back To Top

photon_voice_on_leave_channel

Notifies the voice system that the local client left the given voice channel.

Syntax:

photon_voice_on_leave_channel(channel_id)

Argument	Type	Description
channel_id	Real	The channel ID.

Returns:

Boolean

Whether the notification was handled.

---

Back To Top

photon_voice_on_join_all_channels

Notifies the voice system that the local client joined all voice channels.

Syntax:

photon_voice_on_join_all_channels()

Returns:

Boolean

Whether the notification was handled.

---

Back To Top

photon_voice_on_leave_all_channels

Notifies the voice system that the local client left all voice channels.

Syntax:

photon_voice_on_leave_all_channels()

Returns:

Boolean

Whether the notification was handled.

---

Back To Top

photon_voice_on_player_join

Notifies the voice system that a player joined the given voice channel.

Syntax:

photon_voice_on_player_join(channel_id, player_id)

Argument	Type	Description
channel_id	Real	The channel ID.
player_id	Real	The player ID that joined.

Returns:

Boolean

Whether the notification was handled.

---

Back To Top

photon_voice_on_player_leave

Notifies the voice system that a player left the given voice channel.

Syntax:

photon_voice_on_player_leave(channel_id, player_id)

Argument	Type	Description
channel_id	Real	The channel ID.
player_id	Real	The player ID that left.

Returns:

Boolean

Whether the notification was handled.

---

Back To Top

photon_voice_create_local_voice

Creates a local outgoing voice stream on the given channel and returns its voice ID. Feed it audio frames with photon_voice_push_frame_buffer.

Syntax:

photon_voice_create_local_voice(channel_id, codec, sample_rate, channels, bitrate, frames_per_packet)

Argument	Type	Description
channel_id	Real	The channel to transmit on.
codec	PhotonVoiceCodec	The codec to encode with.
sample_rate	Real	The audio sample rate in Hz.
channels	Real	The number of audio channels.
bitrate	Real	The target bitrate.
frames_per_packet	Real	How many frames to bundle per network packet.

Returns:

Real

The new local voice ID, or a negative value on failure.

---

Back To Top

photon_voice_remove_local_voice

Removes a local voice stream created with photon_voice_create_local_voice.

Syntax:

photon_voice_remove_local_voice(voice_id)

Argument	Type	Description
voice_id	Real	The local voice ID to remove.

Returns:

Boolean

Whether the voice was removed.

---

Back To Top

photon_voice_push_frame_buffer

Pushes a buffer of audio samples into a local voice stream for encoding and transmission.

Syntax:

photon_voice_push_frame_buffer(voice_id, data, bytes)

Argument	Type	Description
voice_id	Real	The local voice ID.
data	Buffer	The buffer holding the audio samples.
bytes	Real	The number of bytes to read from the buffer.

Returns:

Boolean

Whether the frame was pushed.

---

Back To Top

photon_voice_get_frame_queue_count

Returns the number of received audio frames waiting to be read from the queue.

Syntax:

photon_voice_get_frame_queue_count()

Returns:

Real

The number of queued frames.

---

Back To Top

photon_voice_clear_frame_queue

Clears all received audio frames from the queue without reading them.

Syntax:

photon_voice_clear_frame_queue()

Returns:

Boolean

Whether the queue was cleared.

---

Back To Top

photon_voice_peek_next_frame_size

Returns the size in bytes of the next queued audio frame without removing it.

Syntax:

photon_voice_peek_next_frame_size()

Returns:

Real

The size of the next frame in bytes.

---

Back To Top

photon_voice_peek_next_frame_player_id

Returns the player ID of the next queued audio frame without removing it.

Syntax:

photon_voice_peek_next_frame_player_id()

Returns:

Real

The player ID of the next frame.

---

Back To Top

photon_voice_peek_next_frame_voice_id

Returns the voice ID of the next queued audio frame without removing it.

Syntax:

photon_voice_peek_next_frame_voice_id()

Returns:

Real

The voice ID of the next frame.

---

Back To Top

photon_voice_receive_frame_buffer

Removes the next received audio frame from the queue and writes its decoded samples into the given buffer.

Syntax:

photon_voice_receive_frame_buffer(out_data, max_bytes, offset)

Argument	Type	Description
out_data	Buffer	The buffer to write the samples into.
max_bytes	Real	The maximum number of bytes to write.
offset	Real	The offset within the buffer to start writing at.

Returns:

PhotonRealtimeEventBufferReceived

A struct describing the received frame.

---

Back To Top

photon_voice_get_remote_voice_count

Returns the number of remote voice streams currently being received.

Syntax:

photon_voice_get_remote_voice_count()

Returns:

Real

The number of remote voices.

---

Back To Top

photon_voice_get_remote_voice_player_id

Returns the player ID of a remote voice stream by index.

Syntax:

photon_voice_get_remote_voice_player_id(index)

Argument	Type	Description
index	Real	The zero-based remote-voice index.

Returns:

Real

The player ID.

---

Back To Top

photon_voice_get_remote_voice_id

Returns the voice ID of a remote voice stream by index.

Syntax:

photon_voice_get_remote_voice_id(index)

Argument	Type	Description
index	Real	The zero-based remote-voice index.

Returns:

Real

The voice ID.

---

Back To Top

photon_voice_get_remote_voice_codec

Returns the codec of a remote voice stream by index.

Syntax:

photon_voice_get_remote_voice_codec(index)

Argument	Type	Description
index	Real	The zero-based remote-voice index.

Returns:

PhotonVoiceCodec

The codec.

---

Back To Top

photon_voice_get_remote_voice_sample_rate

Returns the sample rate of a remote voice stream by index.

Syntax:

photon_voice_get_remote_voice_sample_rate(index)

Argument	Type	Description
index	Real	The zero-based remote-voice index.

Returns:

Real

The sample rate in Hz.

---

Back To Top

photon_voice_get_remote_voice_channels

Returns the channel count of a remote voice stream by index.

Syntax:

photon_voice_get_remote_voice_channels(index)

Argument	Type	Description
index	Real	The zero-based remote-voice index.

Returns:

Real

The number of audio channels.

---

Back To Top

photon_voice_get_remote_voice_is_speaking

Returns whether a remote voice stream is currently speaking, by index.

Syntax:

photon_voice_get_remote_voice_is_speaking(index)

Argument	Type	Description
index	Real	The zero-based remote-voice index.

Returns:

Boolean

Whether the remote voice is speaking.

---

Back To Top

photon_voice_get_frames_sent

Returns the total number of audio frames sent.

Syntax:

photon_voice_get_frames_sent()

Returns:

Real

The number of frames sent.

---

Back To Top

photon_voice_get_frames_received

Returns the total number of audio frames received.

Syntax:

photon_voice_get_frames_received()

Returns:

Real

The number of frames received.

---

Back To Top

photon_voice_get_frames_lost

Returns the total number of audio frames lost.

Syntax:

photon_voice_get_frames_lost()

Returns:

Real

The number of frames lost.

---

Back To Top

photon_voice_get_round_trip_time

Returns the voice transport's round-trip time, in milliseconds.

Syntax:

photon_voice_get_round_trip_time()

Returns:

Real

The round-trip time in milliseconds.

---

Back To Top

photon_voice_get_round_trip_time_variance

Returns the variance of the voice transport's round-trip time, in milliseconds.

Syntax:

photon_voice_get_round_trip_time_variance()

Returns:

Real

The round-trip time variance.

---

Back To Top

photon_voice_set_callback_remote_voice_added

Registers the callback fired when a new remote voice stream is added.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Callback.

Syntax:

photon_voice_set_callback_remote_voice_added(callback)

Argument	Type	Description
callback	Function	The function to call when a remote voice is added.

Returns:

Boolean

Whether the callback was set.

Triggers:

Callback

The callback is invoked with the following arguments:

Key	Type	Description
player_id	Real	The remote player's ID.
voice_id	Real	The remote voice ID.
codec	PhotonVoiceCodec	The codec of the remote voice.
sample_rate	Real	The sample rate of the remote voice.
channels	Real	The channel count of the remote voice.

---

Back To Top

photon_voice_set_callback_remote_voice_removed

Registers the callback fired when a remote voice stream is removed.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Callback.

Syntax:

photon_voice_set_callback_remote_voice_removed(callback)

Argument	Type	Description
callback	Function	The function to call when a remote voice is removed.

Returns:

Boolean

Whether the callback was set.

Triggers:

Callback

The callback is invoked with the following arguments:

Key	Type	Description
player_id	Real	The remote player's ID.
voice_id	Real	The remote voice ID.

---

Back To Top

photon_voice_set_callback_speaking_changed

Registers the callback fired when a remote voice starts or stops speaking.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Callback.

Syntax:

photon_voice_set_callback_speaking_changed(callback)

Argument	Type	Description
callback	Function	The function to call on a speaking-state change.

Returns:

Boolean

Whether the callback was set.

Triggers:

Callback

The callback is invoked with the following arguments:

Key	Type	Description
player_id	Real	The remote player's ID.
voice_id	Real	The remote voice ID.
is_speaking	Boolean	Whether the remote voice is now speaking.

---

Back To Top

photon_voice_set_callback_debug

Registers the callback fired with Voice SDK debug output.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Callback.

Syntax:

photon_voice_set_callback_debug(callback)

Argument	Type	Description
callback	Function	The function to call with debug output.

Returns:

Boolean

Whether the callback was set.

Triggers:

Callback

The callback is invoked with the following arguments:

Key	Type	Description
debug_level	Real	The debug level of the message.
message	String	The debug message.

---

Back To Top

photon_voice_remove_callback_remote_voice_added

Removes the remote-voice-added callback registered with photon_voice_set_callback_remote_voice_added.

Syntax:

photon_voice_remove_callback_remote_voice_added()

Returns:

Boolean

Whether the callback was removed.

---

Back To Top

photon_voice_remove_callback_remote_voice_removed

Removes the remote-voice-removed callback registered with photon_voice_set_callback_remote_voice_removed.

Syntax:

photon_voice_remove_callback_remote_voice_removed()

Returns:

Boolean

Whether the callback was removed.

---

Back To Top

photon_voice_remove_callback_speaking_changed

Removes the speaking-changed callback registered with photon_voice_set_callback_speaking_changed.

Syntax:

photon_voice_remove_callback_speaking_changed()

Returns:

Boolean

Whether the callback was removed.

---

Back To Top

photon_voice_remove_callback_debug

Removes the debug callback registered with photon_voice_set_callback_debug.

Syntax:

photon_voice_remove_callback_debug()

Returns:

Boolean

Whether the callback was removed.

---

Back To Top

photon_voice_local_voice_set_transmit

Enables or disables transmission for a local voice stream (for example to implement push-to-talk).

Syntax:

photon_voice_local_voice_set_transmit(voice_id, enabled)

Argument	Type	Description
voice_id	Real	The local voice ID.
enabled	Boolean	Whether the stream should transmit.

Returns:

Boolean

Whether the value was set.

---

Back To Top

photon_voice_local_voice_get_transmit

Returns whether a local voice stream is currently transmitting.

Syntax:

photon_voice_local_voice_get_transmit(voice_id)

Argument	Type	Description
voice_id	Real	The local voice ID.

Returns:

Boolean

Whether the stream is transmitting.

---

Back To Top

photon_voice_set_remote_player_muted

Mutes or unmutes a remote player locally.

Syntax:

photon_voice_set_remote_player_muted(player_id, muted)

Argument	Type	Description
player_id	Real	The remote player ID.
muted	Boolean	Whether to mute the player.

Returns:

Boolean

Whether the value was set.

---

Back To Top

photon_voice_get_remote_player_muted

Returns whether a remote player is muted locally.

Syntax:

photon_voice_get_remote_player_muted(player_id)

Argument	Type	Description
player_id	Real	The remote player ID.

Returns:

Boolean

Whether the player is muted.

---

Back To Top

photon_voice_set_remote_player_volume

Sets the local playback volume for a remote player.

Syntax:

photon_voice_set_remote_player_volume(player_id, volume)

Argument	Type	Description
player_id	Real	The remote player ID.
volume	Real	The playback volume.

Returns:

Boolean

Whether the value was set.

---

Back To Top

photon_voice_get_remote_player_volume

Returns the local playback volume for a remote player.

Syntax:

photon_voice_get_remote_player_volume(player_id)

Argument	Type	Description
player_id	Real	The remote player ID.

Returns:

Real

The playback volume.

---

Back To Top

photon_voice_get_debug_lost_percent

Returns the artificial packet-loss percentage used for debugging.

Syntax:

photon_voice_get_debug_lost_percent()

Returns:

Real

The debug packet-loss percentage.

---

Back To Top

photon_voice_set_debug_lost_percent

Sets an artificial packet-loss percentage for debugging voice resilience.

Syntax:

photon_voice_set_debug_lost_percent(percent)

Argument	Type	Description
percent	Real	The packet-loss percentage to simulate.

Returns:

Boolean

Whether the value was set.

---

Back To Top

photon_voice_get_speaking_threshold_ms

Returns the speaking-detection threshold, in milliseconds.

Syntax:

photon_voice_get_speaking_threshold_ms()

Returns:

Real

The speaking threshold in milliseconds.

---

Back To Top

photon_voice_set_speaking_threshold_ms

Sets the speaking-detection threshold: how long audio must be present before a voice is considered "speaking".

Syntax:

photon_voice_set_speaking_threshold_ms(ms)

Argument	Type	Description
ms	Real	The threshold in milliseconds.

Returns:

Boolean

Whether the value was set.

---

Back To Top

PhotonVoiceCodec

The codecs a voice stream can use. Audio uses Opus; the video codecs are listed for completeness.

These constants are referenced by the following functions:

• photon_voice_create_local_voice
• photon_voice_get_remote_voice_codec
• photon_voice_set_callback_remote_voice_added

Member	Description
None	No codec.
AudioOpus	The Opus audio codec.
VideoVp8	The VP8 video codec.
VideoVp9	The VP9 video codec.
VideoAv1	The AV1 video codec.
VideoH264	The H.264 video codec.
VideoH265	The H.265 video codec.

---