Using the Voice Interface

The following calls use Voice RTC APIs that you can use for your implementation. For Voice Web APIs, see our Web API Overview and Voice Web API documentation.

To use the Voice interface, you should:

1. Review and determine the integration method you want to use with your game.
2. Investigate the Voice sample (C and C#) and learn how to use the Voice interface with your product.
3. Integrate the Voice interface into your applications:
   1. Configure your client policies
   2. Integrate the Voice interface based on your chosen integration method.
4. Review the best practices, voice metrics, and usage limitations for the Voice interface.

When using Voice with Lobbies, the Lobbies interface automatically take care of:

• Requesting and refreshing room tokens
• Joining and leaving the voice room as the user enters or leaves the lobby

When using Voice with a Trusted Server, you need to:

• Request tokens on behalf of users on their server
• Have the game client make calls to refresh tokens
• Have the game client make calls to join and leave the voice room

When using a custom implementation for a trusted server, you are responsible for managing room access and requesting tokens for players to allow them to join that room on a media server. You can do this with EOS_RTCAdmin_QueryJoinRoomToken, which requires the Voice:createRoomToken policy action enabled in the Developer Portal.

EOS_RTCAdminQueryJoinRoomToken is an asynchronous operation and upon completion (see EOS_RTCAdmin_QueryJoinRoomTokenCompleteCallbackInfo), provides you with the media server URL and a QueryId to retrieve the tokens.

From inside the callback, you can use EOS_RTCAdmin_CopyUserTokenByIndex and EOS_RTCAdmin_CopyUserTokenByUserId to retrieve the tokens.

Once you no longer need a EOS_RTCAdmin_UserToken, you can use EOS_RTCAdmin_UserToken_Release to release its resources.

Tokens expire, so the client will need to request a new token.

You must use EOS_RTC_AddNotifyDisconnected to detect token expiration and to ask for another token. The error notification provided at disconnect is EOS_EResult::InvalidAuth.

Once your client has the token and media server URL to join a room, you can call EOS_RTC_JoinRoom to join the room and EOS_RTC_LeaveRoom to leave it.

The SDK assumes default output and input audio devices if you do not explicitly specify the devices to use.

By default, audio is enabled when joining a room. You can use EOS_RTCAudio_UpdateSending to enter a room muted. This sets your state before actually joining the room. However, you first need to register a notification for the room.

For example:

• Call EOS_RTCAudio_AddNotifyParticipantStatusChanged to satisfy required SDK internal needs.
• Call EOS_RTCAudio_UpdateSending and set the AudioStatus field to EOS_RTCAS_Disabled to be muted upon entry.
• Call EOS_RTC_JoinRoom to join the room.

To detect when a player joins or leaves a room, use EOS_RTC_AddNotifyParticipantStatusChanged or EOS_RTC_RemoveNotifyParticipantStatusChanged, respectively.

Setting this notification before your players join a room, gives your players a notification for every member in the room. This allows your players to know who is already in the room even if they joined after them.

Your players also get a notification when they join the room, but not when they leave. Use EOS_RTC_AddNotifyDisconnected and EOS_RTC_RemoveNotifyDisconnected to notify your players when they leave/disconnect from a room (for example, if they are kicked).

EOS_RTC_AddNotifyDisconnected is also used to detect token expiration and required.

If not explicitly changed, the SDK uses the operating system’s default input and output audio devices. However, you can request the list of available input devices (microphones) and output devices (speakers) to select alternatives.

For input devices, you can use EOS_RTCAudio_GetAudioInputDevicesCount to know how many input devices are available and call EOS_RTCAudio_GetAudioInputDeviceByIndex to iterate through the list. As a response, EOS_RTCAudio_AudioInputDeviceInfo provides a DeviceId that uniquely identifies the device. You can then pass this DeviceId to EOS_RTCAudio_SetAudioInputSettings to select the device to use.

Similarly, for output devices, you use EOS_RTCAudio_GetAudioOutputDevicesCount to know how many output devices are available and call EOS_RTC_GetAudioOutputDeviceByIndex to iterate through the list. As a response, EOS_RTCAudio_AudioOutputDeviceInfo provides a DeviceId to uniquely identify the device. You can then pass this DeviceId to EOS_RTCAudio_SetAudioOutputSettings to select the device to use.

Available input and output audio devices may change during a session. For example, your user may plug in or remove a new headset while your product is running. You can use EOS_RTCAudio_AddNotifyAudioDevicesChanged to notify you whenever available devices change.

If you no longer wish to be notified of audio device changes, you can use EOS_RTCAudio_RemoveNotifyAudioDevicesChanged.

You can change the input and output volumes with the same functions used for Audio Device Selection with the Volume field in EOS_RTCAudio_SetAudioOutputSettingsOptions and EOS_RTCAudio_SetAudioInputSettingsOptions.

This volume field can be set within a range of 0 to 100:

• For output volume, 0 means silence, 50 means unmodified, and 100 means 2x gain.
• For input volume, the only value that produces an effect is 0 (silence). Any value other than 0 causes no change to the volume.

You can mute someone in relation to yourself or even yourself.

To mute yourself, use EOS_RTCAudio_UpdateSending.

To mute other people, you can use EOS_RTCAudio_UpdateReceiving. You can mute a single participant by filling in the ParticipantId field, or you can leave it empty to mute the entire room.

This kind of mute only affects your own session. When you use EOS_RTCAudio_UpdateReceiving to mute someone else, you will stop receiving audio from that player, but you are not muting that player for other players in that room.

To completely block communication with another participant in a room (no sending or receiving), you can use EOS_RTC_BlockParticipant. This is different from EOS_RTCAudio_UpdateSending. The former blocks communication both ways (fully ignores/blocks someone), while the latter mutes YOU in the room.

Use remote mute to mute that player for everyone (currently only supported with the trusted server integration).

When using a trusted server integration, you can enable the Voice:mute policy action and call EOS_RTCAdmin_SetParticipantHardMute with the RoomId, ProductUserId, and mute status. This toggles the audibility of a player in a room for everyone, regardless of their local mute status.

When using a trusted server integration, you can enable the Voice:kick policy action and remove individual players from a room using EOS_RTCAdmin_Kick. This also invalidates the user's previously issued room token, preventing them from rejoining the room with that same token.

When using the Lobbies interface integration, the lobby owner can call EOS_Lobby_KickMember to kick a member from the lobby and the voice room.

To visually indicate when an individual player is currently speaking or not, you can use EOS_RTCAudio_AddNotifyParticipantUpdated and EOS_RTCAudio_RemoveNotifyParticipantUpdated. The callback for this notification contains the participant, the state of that participant’s audio stream (unsupported, enabled, disabled, and so on), and if the participant is currently speaking or not.

You can specify your own audio source by instructing the SDK to not capture audio on its own.

First, you need to set the bManualAudioInputEnabled field to true when calling EOS_RTC_JoinRoom.

Next, you can inject your own audio with EOS_RTCAudio_SendAudio. This requires you to set up a EOS_RTCAudio_AudioBuffer struct with the audio data to send, which must have a duration of 10 milliseconds.

The SDK makes a copy of the buffer.

You can implement voice effects by intercepting both the outgoing and incoming audio.

To intercept outgoing audio, you can use EOS_RTCAudio_AddNotifyAudioBeforeSend.

To intercept incoming audio, you use EOS_RTCAudio_AddNotifyAudioBeforeRender, which allows you to either get a full mix of all the participants in the room or individual streams per participant for uses such as spatial audio. You can pick what behavior you want by setting the bUnmixedAudio field of the EOS_RTCAudio_AddNotifyAudioBeforeRenderOptions struct.

Although Voice itself does not currently offer Speech-To-Text, you can grab the audio buffer and send it to a transcription service of your choice.

Use EOS_RTCAudio_AddNotifyAudioBeforeRender to receive audio buffers before they are rendered on the audio device. You can then choose to either convert the mixed audio channels of all speakers or of individual ones, using the bUnmixedAudio flag in EOS_RTCAudio_AddNotifyAudioBeforeRenderOptions.

EOS_RTCAudio_AudioBeforeRenderCallbackInfo contains the RoomId, ProductUserId, and EOS_RTCAudio_AudioBuffer for each speaker.

The audio buffer itself contains the interleaved 16-Bit samples and defines the number of channels, sample rate and sample count it contains. This buffer can then be submitted to speech-to-text services in order to receive and display the matching text representation.