Vivox Unity SDK quickstart guide
Follow this workflow to get started with Vivox voice and text chat.
Read time 5 minutesLast updated 3 months ago
Unity offers the Vivox service as a way for game developers to provide voice and text communications between users through a channel-style workflow without the need to invest in a self-hosted solution.
Unity's Voice and Text chat service for multiplayer communication offers a voice chat and direct message text service with a managed hosted solution.
Plug in to your game and configure your project settings to immediately add communications to your project. Connect an unlimited number of users in 2D and 3D channels. Allow users to control voice volume, perform mute actions, and manage channels. Place users in team chat. Allow users to participate in multiple channels.
Enable the Vivox service in a Unity project
To set up Vivox Voice and Text for a Unity project on the Unity Dashboard, complete the following steps.
- Create an account and project on the Unity Dashboard.
- Go to Development > Products.
- Select Vivox Voice and Text Chat.
- Follow the onboarding steps. During the onboarding process, you are provided with Vivox API credentials to use in your project.
Connect your Unity project to Vivox
To connect your Unity project to Vivox, complete the following steps.
-
Create or open your local Unity project.
-
In the Editor, select Window > Package Manager > Search Unity Registry.
-
Search for Vivox. Select Install.
-
Select Edit > Project Settings > Services and ensure that your project has the correct project ID associated with it.
-
Under Service, select Vivox, and ensure that the correct credentials have been pulled into the project.NoteYou can directly add required packages by editing the manifest.json file or by using the package manager (select Window > Package Manager > + > Add package by name by usingas the name.).
com.unity.services.vivoxFor more information, refer to the Unity documentation on the Project manifest.
Lifecycle actions
Initialize
When using Unity Authentication Services, the Vivox package handles credentials and tokens for you.
using System;using UnityEngine;using Unity.Services.Authentication;using Unity.Services.Core;using Unity.Services.Vivox;async void InitializeAsync(){ await UnityServices.InitializeAsync(); await AuthenticationService.Instance.SignInAnonymouslyAsync(); await VivoxService.Instance.InitializeAsync();}
Sign in
After you initialize the Vivox SDK, the VivoxService can be used to log in.
Note
LoginOptionsVivoxService.Instance.LoginAsync(LoginOptions options = null)using Unity.Services.Vivox;public async void LoginToVivoxAsync(){ LoginOptions options = new LoginOptions(); options.DisplayName = UserDisplayName; options.EnableTTS = true; await VivoxService.Instance.LoginAsync(options);}
Join an echo channel
After logging in, use to join an echo channel and test Vivox locally.
VivoxService.Instance.JoinEchoChannelAsync(string channelName, ChatCapability chatCapability, ChannelOptions channelOptions = null)using Unity.Services.Vivox;public async void JoinEchoChannelAsync(){ string channelToJoin = "Lobby"; await VivoxService.Instance.JoinEchoChannelAsync(channelToJoin, ChatCapability.TextAndAudio);}
Note
Channels are created at the moment the first join request is sent.
After confirming that you can hear your voice in an echo channel, join a positional or group channel to hear other participants.
- Use to join a group channel.
VivoxService.Instance.JoinGroupChannelAsync((string channelName, ChatCapability chatCapability, ChannelOptions channelOptions = null)) - Use to join a positional channel.
VivoxService.Instance.JoinPositionalChannelAsync(string channelName, ChatCapability chatCapability, Channel3DProperties positionalChannelProperties, ChannelOptions channelOptions = null)
Channel3DProperties is a struct that can be used to pass positional channel specific values like conversational distance and the audio fade model.
Optionally, if you need better access control over what channels a user can join you can integrate Vivox Access Tokens (VATs) into your channel join flow.
Note
Channel names must be unique across the channel types.
Leave a voice and text channel
To remove a user from the channel use or . If more then one channel can be left independently, those channel names must be stored somewhere retrievable.
VivoxService.Instance.LeaveChannelAsync(string channelName)VivoxService.Instance.LeaveAllChannelsAsync()using Unity.Services.Vivox;public async void LeaveEchoChannelAsync(){ string channelToLeave = "Lobby"; await VivoxService.Instance.LeaveChannelAsync(channelToLeave);}
For more information, refer to Leave a channel.
Sign out a user
To sign out a user, call the method. After the user is signed out, there is no network traffic to or from the Vivox SDK. This is typically only called when quitting the application, or in the scenario where a user can sign in to different accounts within the app, when signing the user out of the game server.
VivoxService.Instance.LogoutAsync()using Unity.Services.Vivox;public async void LogoutOfVivoxAsync (){ await VivoxService.Instance.LogoutAsync();}
For more information, refer to Sign out of a game.
In-channel actions
Handle participant events
The Vivox SDK posts events whenever a new player is added to or removed from a channel the user is a part of. These events can be subscribed to as:
This event fires with an object of type , which includes important information like the , , and of the participant at the moment they joined the channel. Events exist to alert the game to any changes to the values capable of changing (, , and ). These events are as follows:
VivoxParticipantDisplayNamePlayerIdAudioEnergySpeechDetectedIsMutedAudioEnergyVivoxParticipant.ParticipantMuteStateChangedVivoxParticipant.ParticipantSpeechDetectedVivoxParticipant.ParticipantAudioEnergyChanged
using Unity.Service.Vivox;List<RosterItem> rosterList = new List<RosterItem>();private void BindSessionEvents(bool doBind){ if(doBind) { VivoxService.Instance.ParticipantAddedToChannel += onParticipantAddedToChannel; VivoxService.Instance.ParticipantRemovedFromChannel += onParticipantRemovedFromChannel; } else { VivoxService.Instance.ParticipantAddedToChannel -= onParticipantAddedToChannel; VivoxService.Instance.ParticipantRemovedFromChannel -= onParticipantRemovedFromChannel; }}private void onParticipantAddedToChannel(VivoxParticipant participant){ ///RosterItem is a class intended to store the participant object, and reflect events relating to it into the game's UI. ///It is a sample of one way to use these events, and is detailed just below this snippet. RosterItem newRosterItem = new RosterItem(); newRosterItem.SetupRosterItem(participant); rosterList.Add(newRosterItem);}private void onParticipantRemovedFromChannel(VivoxParticipant participant){ RosterItem rosterItemToRemove = rosterList.FirstOrDefault(p => p.Participant.PlayerId == participant.PlayerId); rosterList.Remove(rosterItemToRemove);}
The following code snippet further details the structure takes:
RosterItemusing Unity.Service.Vivox;using UnityEngine;public class RosterItem : MonoBehaviour{ public VivoxParticipant Participant; public Text PlayerNameText; public Image ChatStateImage; public Sprite MutedImage; public Sprite SpeakingImage; public Sprite NotSpeakingImage; public void SetupRosterItem(VivoxParticipant participant) { Participant = participant; PlayerNameText.text = Participant.DisplayName; UpdateChatStateImage(); Participant.ParticipantMuteStateChanged += UpdateChatStateImage; Participant.ParticipantSpeechDetected += UpdateChatStateImage; } private void UpdateChatStateImage() { /// Update the UI of the game to the state of the participant if (Participant.IsMuted) { ChatStateImage.sprite = MutedImage; ChatStateImage.gameObject.transform.localScale = Vector3.one; } else { if (Participant.SpeechDetected) { ChatStateImage.sprite = SpeakingImage; ChatStateImage.gameObject.transform.localScale = Vector3.one; } else { ChatStateImage.sprite = NotSpeakingImage; } } }}
For more information, refer to Participant events.
Send text messages to a channel
If the game has joined a channel with text enabled, users can send and receive group text messages. To send messages, the game uses the method. After this SDK call is made, other users in that channel receive a event. This event returns a value, which contains the message's sender, text, and the channel it was sent in.
VivoxService.Instance.SendChannelTextMessageAsync(string channelName, string message)ChannelMessageReceivedVivoxMessageusing Unity.Service.Vivox;private async void SendMessageAsync(string channelName, string message){ VivoxService.Instance.SendChannelTextMessageAsync(channelName, message);}private void BindSessionEvents(bool doBind){ VivoxService.Instance.ChannelMessageReceived += onChannelMessageReceived;}private void onChannelMessageReceived(VivoxMessage message){ string messageText = message.MessageText; string senderID = message.SenderPlayerId; string senderDisplayName = message.SenderDisplayName; string messageChannel = message.ChannelName;}
For more information, refer to Send and receive group text messages. For information on sending direct messages, refer to Directed messages
Mute other participants
You can mute other users for a specific user by using a local mute. The function prevents a user from hearing a muted user, but other users in the channel will continue to hear the muted user. can be used to unmute the user. Attach these commands to UI elements tied to the specific participants of the channel as they come in.
VivoxParticipant.MutePlayerLocally()VivoxParticipant.UnmutePlayerLocally()For example, Cynthia, Fernando, and Wang are in a channel. Fernando does not want to hear Wang’s audio. By using a local mute, you can allow Fernando to stop hearing Wang’s audio. However, Cynthia continues to hear Wang, and Wang continues to hear Cynthia and Fernando.
{if (participant.InAudio && setMute){ participant.MutePlayerLocally}else if (participant.InAudio){ participant.UnmutePlayerLocally}else{ //Tell player to try again Debug.Log("Try Again");}}
For more information, refer to Mute other users for a specific user.
Mute yourself
There are two methods for muting a user’s microphone: or . Each method is beneficial for different scenarios.
AudioInputDevicesSetTransmissionMode()Use can also use to prevent a player from being heard in any channels. For example:
Transmission.Noneawait VivoxService.Instance.SetChannelTransmissionModeAsync(Transmission.None, channelName)
For more information, refer to Mute a user's microphone.
Next steps
Once basic chat is working you can expand on Vivox functionality with additional tools:
- Add features to enrich text chat.
- Consider accessibility features such as speech-to-text.
- Review the Developer guide for more topics and features.