Oculus Go Development

On 6/23/20 Oculus announced plans to sunset Oculus Go. Information about dates and alternatives can be found in the Oculus Go introduction.

Oculus Quest Development

All Oculus Quest developers MUST PASS the concept review prior to gaining publishing access to the Quest Store and additional resources. Submit a concept document for review as early in your Quest application development cycle as possible. For additional information and context, please see Submitting Your App to the Oculus Quest Store.

Voice Chat (VoIP) using Platform Solutions

Note: You are viewing the Unity version of this topic. To view this topic for native development, see Voice Chat (VoIP) using Platform Solutions (Native). To view this topic for Unreal development, see Voice Chat (VoIP) using Platform Solutions (Unreal).

Use the Platform VoIP service to add voice chat to your app.

The VoIP service transmits PCM (pulse-code modulation) data between users that the Platform SDK decodes to audio.

VoIP is peer-to-peer so your app will be limited by bandwidth in most cases. In general, the VoIP service becomes unstable if you have 12 or more connections. You should have 8 or less 8 connections on Rift and 4 or less on mobile apps. You may be able to support more if you use push to talk or some proximity-type muting.

Note

VoIP data may be routed through relay servers located inside Facebook's infrastructure when connecting to client devices that are behind network address translation (NAT), if a connection cannot be established from their detected external address. The VoIP data passing through a relay server is not inspected any more than is necessary to forward to the recipient; nor is it retained.

Data Use Checkup

Note that this feature accesses user data and may require you to complete the Data Use Checkup form prior to submitting your app to the Oculus Store. For more information, see Complete a Data Use Checkup.

Integrating VoIP

To integrate Application VoIP in your Native application, follow the steps below. The methods can be called from your client app. Detail about each function can be found in the Platform SDK Reference Content.

Send a VoIP connection request

Use the following method to initiate a VoIP connection request with a specified user.

  • Platform.Voip.Start()

Accept a VoIP connection request

Use the following method to accept a VoIP connection request.

  • Platform.Voip.Accept()

Retrieve the maximum size of the buffer

To retrieve the size of the internal ringbuffer used by the VoIP system in elements, use the following method. This size is the maximum number of elements that can ever be returned by ovr_Voip_GetPCM or ovr_Voip_GetPCMFloat.

  • Platform.Voip.GetOutputBufferMaxSize()

Retrieve PCM data from a user (16 bit fixed point)

The following method retrieves all available samples of voice data from a specified user and copy them into the outputBuffer. The VoIP system will generate data at roughly the rate of 480 samples per 10ms. This function should be called every frame with 50ms (2400 elements) of buffer size to account for frame rate variations. The data format is 16 bit fixed point 48khz mono.

  • Platform.Voip.GetPCM()

Retrieve PCM data from a user (32 bit floating point)

Retrieve all available samples of voice data from a specified user and copy them into the outputBuffer. The VoIP system will generate data at roughly the rate of 480 samples per 10ms. This function should be called every frame with 50ms (2400 elements) of buffer size to account for frame rate variations. The data format is 32 bit floating point 48khz mono.

We do not recommend using floating point unless necessary. This operation requires additional resources when compared to the integer based process.

  • Platform.Voip.GetPCMFloat()

Retrieve the number of PCM data files available

Use the following method to retrieve the current number of audio samples available to read from a specified user. This function is inherently racy, it’s possible that data can be added between a call to this function and a subsequent call to ovr_Voip_GetPCM or ovr_Voip_GetPCMFloat.

  • Platform.Voip.GetPCMSize()

Retrieve PCM data with a timestamp from a user (16 bit fixed point)

Like ovr_Voip_GetPCM, this function copies available audio samples from a specified user into a buffer. Along with the audio samples, this function also stores the timestamp of the first sample in the output parameter timestamp. This timestamp can be used for synchronization, see ovr_Voip_GetSyncTimestamp for more details. The data format is 16 bit fixed point 48khz mono.

This function may return data early, even if there’s more data available, to keep the batch of audio samples returned with a single timestamp small. For example, if 30ms worth of audio is in the buffer, this function may return 480 samples (10ms) each time it’s called. Therefore, it’s recommended to call this as long as there’s data in the buffer (i.e. the function returns a non-zero result).

  • Platform.Voip.GetPCMWithTimestamp()

Retrieve PCM Data with a timestamp from a user (32-bit floating point)

Like ovr_Voip_GetPCMFloat, this function copies available audio samples from a specified user into a buffer. Along with the audio samples, this function also stores the timestamp of the first sample in the output parameter timestamp. This timestamp can be used for synchronization, see ovr_Voip_GetSyncTimestamp for more details. The data format is 32 bit floating point 48khz mono.

This function may return data early, even if there’s more data available, in order to keep the batch of audio samples with a single timestamp small. For example, if there’s 30ms worth of audio in the buffer, this function may return 480 samples (10ms) each time it’s called. Therefore, it’s recommended to call this as long as there’s data in the buffer (i.e. the function returns a non-zero result).

We do not recommend using floating point unless necessary. This operation requires additional resources when compared to the integer based process.

  • Platform.Voip.GetPCMWithTimestampFloat()

Retrieve the sync timestamp for the sender

Timestamps associated with audio frames are implicitly transmitted to remote peers; on the receiving side, they can be obtained by using ovr_Voip_GetPCMWithTimestamp. ovr_Voip_GetSyncTimestamp is used to fetch those timestamps on the sending side. An application can insert the value returned by this function into each data packet and compare it to the value returned by GetPCMWithTimestamp on the receiving side to determine the ordering of two events (sampling audio and composing a data packet).

Note: The timestamp is generated by an unspecified clock and won’t represent wall-clock time. Use ovr_Voip_GetSyncTimestampDifference to determine the difference between two timestamps in microseconds. This function assumes that a voice connection to the user already exists; it returns 0 if that isn’t the case.

  • Platform.Voip.GetSyncTimestamp()

Returns a timestamp used for synchronizing audio samples sent to the user with an external data stream.

Retrieve the difference (in µs) between two timestamps

Use this method to retrieve the calculated difference between two sync timestamps, in microseconds. returned by ovr_Voip_GetSyncTimestamp, ovr_Voip_GetPCMWithTimestamp, or ovr_Voip_GetPCMWithTimestampFloat.

  • Platform.Voip.GetSyncTimestampDifference()

The return value will be negative if lhs is smaller than rhs, zero if both timestamps are the same, and positive otherwise. The absolute value of the result is the time in microseconds between the two sync timestamps.

Retrieve the mute state of the microphone

This method checks if the microphone has been muted.

  • Platform.Voip.GetSystem VoIPMicrophoneMuted()

Retrieve the VoIP system status

The following method retrieves the status of System VoIP. System VoIP is the service used by Oculus Parties. See the Parties page for information about potential System VoIP conflicts.

  • Platform.Voip.GetSystem VoIPStatus()

Set the microphone filter callback

Set a callback that will be called every time audio data is captured by the microphone.

  • Platform.Voip.SetMicrophoneFilterCallback()

The callback function must match this format:

void filterCallback(int16_t pcmData[], size_t pcmDataLength, int frequency, int numChannels);

Note: If you are using Unity’s IL2CPP scripting backend, you need to add the MonoPInvokeCallback attribute to the callback method, like the following example:

[MonoPInvokeCallback(typeof(CAPI.FilterCallback))]
void filterCallback(int16_t pcmData[], size_t pcmDataLength, int frequency, int numChannels);

The pcmData param is used for both input and output. pcmDataLength is the size of pcmData in elements. numChannels will be 1 or 2. If numChannels is 2, then the channel data will be interleaved in pcmData. frequency is the input data sample rate in hertz.

Mute/unmute the microphone

This function is used to enable or disable the local microphone. When muted, the microphone will not transmit any audio. VoIP connections are unaffected by this state. New connections can be established or closed whether the microphone is muted or not. This can be used to implement push-to-talk, or a local mute button. The default state is unmuted.

  • Platform.Voip.SetMicrophoneMuted()

Set the VoIP output sample rate

Set the output sample rate. Audio data will be resampled as it is placed into the internal ring buffer.

  • Platform.Voip.SetOutputSampleRate()

End the VoIP connection

Use the following method it end a VoIP session with a specified user. Note that a muting functionality should be used to temporarily stop sending audio; restarting a VoIP session after tearing it down may be an expensive operation.

  • Platform.Voip.Stop()

Setting VoIP Options – DTX and Bit Rate

You can optionally configure your app to use discontinuous transmission (DTX) and set the bit rate for VoIP connections.

DTX allows for temporary microphone muting when there’s no voice input. This improves efficiency because a person is usually talking less than half the time in a typical two-way conversation. This can conserve battery life and free up the channel. By default, DTX is disabled.

Setting the bit rate controls the network usage when transmitting on VoIP connections. The higher the bit rate, the better the audio quality, but more network resources are used. A lower bit rate will conserve network resources. By default, the bit rate is 32,000 bits per second.

Once these options have been configured, they apply only to new connections. Existing connections must be closed and reconnected for the new settings to be applied.

To configure these options in a Native application, follow these steps:

  1. Create an options handle with ovr_VoipOptions_Create.
  2. Configure the desired options using the handle with ovr_VoipOptions_SetCreateNewConnectionUseDtx and ovr_VoipOptions_SetBitrateForNewConnections.
  3. Enable the newly configured options with ovr_Voip_SetNewConnectionOptions.
  4. Destroy the handle with ovr_VoipOptions_Destroy.

These functions are described below. Additional details about all functions can be found in the Platform SDK Reference Content.

An example flow of calls in a Native application would look like this:

ovrVoipOptionsHandle options = ovr_VoipOptions_Create();
ovr_VoipOptions_SetCreateNewConnectionUseDtx(options, ovrVoipDtxState_Enabled);
ovr_VoipOptions_SetBitrateForNewConnections(options, ovrVoipBitrate_B64000);
ovr_Voip_SetNewConnectionOptions(options);
ovr_VoipOptions_Destroy(options);

Create a handle to set VoIP options:

Creates a handle used to set options.

  • var voipOptions = new VoipOptions()

Set DTX usage

The following method is used to enable or disable DTX. Passing the options handle and a value of ovrVoipDtxState_Enabled enables DTX on all new VoIP connections. It does not apply to existing connections, which must be closed and then reconnected for DTX to be enabled. Passing the options handle and a value of ovrVoipDtxState_Disabled similarly disables DTX on all new connections.

  • voipOptions.SetCreateNewConnectionUseDtx()

In Unity, this is set to ovrVoipDtxState.Enabled or ovrVoipDtxState.Disabled.

By default, apps will have DTX disabled.

Set the bit rate for new connections

Used to set the bit rate on all new VoIP connections. The higher the bit rate, the better the audio quality, at the expense of network usage. It does not apply to existing connections, which must be closed and then reconnected for the new bit rate to take effect.

  • voipOptions.SetBitrateForNewConnections()

To change the bit rate, pass the options handle and one of the following values:

+ ovrVoipBitrate_B16000
+ ovrVoipBitrate_B24000
+ ovrVoipBitrate_B32000  (default)
+ ovrVoipBitrate_B64000
+ ovrVoipBitrate_B96000
+ ovrVoipBitrate_B128000

In Unity, these values are in the format of VoipBitrate.B32000.

Enable the newly configured options

Enables the options set on all new connections.

  • Platform.Voip.SetNewConnectionOptions()

In addition, there are several functions related to these options.

Check if a connection is using DTX

Checks if a connection is using DTX. If a connection exists and both sides have DTX enabled, this returns ovrVoipDtxState_Enabled (Unity: ovrVoipDtxState.Enabled). If a connection exists and only one or neither side has it enabled, this returns ovrVoipDtxState_Disabled (Unity: ovrVoipDtxState.Disabled). If there’s no existing connection, this returns ovrVoipDtxState_Unknown (Unity: ovrVoipDtxState.Unknown).

  • Platform.Voip.GetIsConnectionUsingDtx()

Check the bit rate for users

These functions return an ovrVoipBitrate value specifying the VoIP bit rate of the remote and local users respectively. The bit rates do not have to be the same. For example, if the remote bit rate is very high and the local bit rate is very low, the local user will hear high quality audio but send low quality audio. If there is no existing connection, this returns ovrVoipBitrate.Unknown).

For a local remote user:

  • Platform.Voip.GetRemoteBitrate()

For a remote user:

  • Platform.Voip.GetLocalBitrate()

Implementation Overview

This section will walk you through the basic process of implementing VoIP in your Unity app. Before integrating VoIP, please review the Parties page for information about potential conflicts with users who launch your app while participating in a party. Neglecting to do so will result in a poor user experience.

The general process of implementing VoIP is:

  1. Send the connection request. The user initiating the connection request calls Voip.Start with the user id’s of the other user. Information about how to retrieve a user id’s can be found or the Users, Friends, and Relationships.
  2. Establish a callback as a notification handler to accept incoming connection requests by calling Voip.Accept from the user receiving the request. For example, to accept all incoming connections, you could use the following: Voip.SetVoipConnectRequestCallback((Message<NetworkingPeer> msg) => { Voip.Accept(msg.Data.ID); });
  3. Listen for the state change. Both users will be listening for the callback that the connection has been established. Once this is received the users can begin exchanging data. An example of a state change listener is: Voip.SetVoipStateChangeCallback((Message<NetworkingPeer> msg) => { Debug.LogFormat("peer {0} is in state {1}", msg.Data.ID, msg.Data.State); });
  4. Accept the connection request by calling Voip.Accept to open the connection.
  5. Add the playback component. The audio playback component handles buffering and playback of voice data from a remote peer. You should add this component to a game object that represents a connected user, such as their avatar. For each connected user, you’ll need to set the senderID field of each VoipAudioSourceHiLevel object you create. This lets the system know which user’s voice data corresponds to each playback component. For example: var audioSource = gameObject.AddComponent <VoipAudioSourceHiLevel>(); audioSource.senderID = remotePeer.ID;
  6. You can access the Unity AudioSource object from the VoipAudioSourceHiLevel object to modify playback options. For instance to spatialize the audio playback:Var voipAudio = RemoteAvatar.GetComponent<VoipAudioSourceHiLevel>(); voipAudio.audioSource.spatialize = true;

  7. To end a VoIP connection call:

Oculus.Platform.Voip.Stop(userID);
Voip.Stop(remotePeer.ID)

  1. (Optional) At any time either user may mute their microphone by calling Platform.Voip.SetMicrophoneMuted. Calling the same function will unmute the microphone. Call Platform.Voip.GetSystem VoIPMicrophoneMuted to check the mute state of the microphone.

Example Implementation

The VrVoiceChat Unity app provided in the Platform SDK download demonstrates use of the VoIP service. Please see the Sample Apps page for more information about the apps that are available.

using UnityEngine;
using System.Collections;

using Oculus.Platform;
using Oculus.Platform.Models;

// Helper class to manage the Voice-over-IP connection to the
// remote user
public class VoipManager
{
    // the ID of the remote user I expect to talk to
    private ulong m_remoteID;

    // the last reported state of the VOIP connection
    private PeerConnectionState m_state = PeerConnectionState.Unknown;

    // the GameObject where the remote VOIP will project from
    private readonly GameObject m_remoteHead;

    public VoipManager(GameObject remoteHead)
    {
        m_remoteHead = remoteHead;

        Voip.SetVoipConnectRequestCallback(VoipConnectRequestCallback);
        Voip.SetVoipStateChangeCallback(VoipStateChangedCallback);
    }

    public void ConnectTo(ulong userID)
    {
        m_remoteID = userID;
        var audioSource = m_remoteHead.AddComponent<VoipAudioSourceHiLevel>();
        audioSource.senderID = userID;

        // ID comparison is used to decide who initiates and who gets the Callback
        if (PlatformManager.MyID < m_remoteID)
        {
            Voip.Start(userID);
        }
    }


    public void Disconnect()
    {
        if (m_remoteID != 0)
        {
            Voip.Stop(m_remoteID);
            Object.Destroy(m_remoteHead.GetComponent<VoipAudioSourceHiLevel>(), 0);
            m_remoteID = 0;
            m_state = PeerConnectionState.Unknown;
        }
    }

    public bool Connected
    {
        get
        {
            return m_state == PeerConnectionState.Connected;
        }
    }

    void VoipConnectRequestCallback(Message<NetworkingPeer> msg)
    {
        Debug.LogFormat("Voip request from {0}, authorized is {1}", msg.Data.ID, m_remoteID);

        if (msg.Data.ID == m_remoteID)
        {
            Voip.Accept(msg.Data.ID);
        }
    }

    void VoipStateChangedCallback(Message<NetworkingPeer> msg)
    {
        Debug.LogFormat("Voip state to {0} changed to {1}", msg.Data.ID, msg.Data.State);

        if (msg.Data.ID == m_remoteID)
        {
            m_state = msg.Data.State;

            if (m_state == PeerConnectionState.Timeout &&
                // ID comparison is used to decide who initiates and who gets the Callback
                PlatformManager.MyID < m_remoteID)
            {
                // keep trying until hangup!
                Voip.Start(m_remoteID);
            }
        }

        PlatformManager.SetBackgroundColorForState();
    }
}