Use Audio Taps in C# scripts#

This section contains information on how to add Audio Taps through scripts rather than through the Editor UI.

Capture Source and Channel Audio Taps#

You can add the Capture Source and Channel Audio Taps to a scene through a C# script. The following is an example of how to add an echo effect to Vivox Channel Audio Tap audio through a script:

private GameObject _channelAudioGameObject;

public void AddChannelAudioEffect()
{
    // Create the GameObject
    _channelAudioGameObject = new GameObject("ChannelAudioGameObject");
    // Add the Tap to it
    _channelAudioGameObject.AddComponent<VivoxChannelAudioTap>();
    // Also add an echo filter, for example
    _channelAudioGameObject.AddComponent<AudioEchoFilter>();
}

Create an empty GameObject, then add the VivoxChannelAudioTap and the Unity-provided AudioEchoFilter for all the audio to have an echo applied. You can switch the Audio Tap used in the example for the VivoxCaptureSourceTap without any changes for different use cases.

Participant Tap scripts#

Participant Taps can easily be created in a script through the VivoxParticipant’s class CreateVivoxParticipantTap method. By subscribing to the VivoxService.Instance.ParticipantAddedToChannel message, you will get a callback whenever a participant joins a channel. You can then call the CreateVivoxParticipantTap on the provided VivoxParticipant object which will create a GameObject for the new participant containing the Vivox Participant Tap ready to get the audio for the specific participant.

The following example shows how to subscribe to the ParticipantAddedToChannel and add an echo effect for each new channel participant.

using Unity.Services.Vivox;
using UnityEngine;

public class ParticipantHandler : MonoBehaviour
{
    void Start()
    {
        VivoxService.Instance.ParticipantAddedToChannel += AddParticipantEffect;
    }

    void AddParticipantEffect(VivoxParticipant participant)
    {
        var gameObject = participant.CreateVivoxParticipantTap("MyNewGameObject");
        gameObject.AddComponent<AudioEchoFilter>();
    }
}

Note that the example script above does not delete created objects. It is possible to add logic to only create Taps for a specific channel member if needed.

The lifetime of the Vivox Participant Taps GameObjects created by using the CreateVivoxParticipantTap method are tied to the VivoxParticipant lifetime. This means that the GameObject will automatically be destroyed when the participant leaves the channel or when the local player logs out. It is also possible to explicitly destroy the Participant Tap for any Vivox Participant by calling VivoxParticipant.DestroyVivoxParticipantTap.

Monitoring Audio Tap status#

The Audio Taps have an exposed parameter TapId to monitor the status of your created Audio Taps. After creating a Tap, the TapId should have a value greater or equal to zero, meaning that there were no errors. The following is an example of creating a Tap and making sure the TapId has an expected value:

private GameObject _channelAudioGameObject;

public void AddChannelAudioEffect()
{
    // Create the GameObject
    _channelAudioGameObject = new GameObject("ChannelAudioGameObject");
    // Add the Tap to it
    var tap = _channelAudioGameObject.AddComponent<VivoxChannelAudioTap>();
    if (tap.TapId < 0)
    {
        Destroy(_channelAudioGameObject); // Destroy the GameObject, since the status is not valid
        Debug.LogError($"Failed to create VivoxChannelAudioTap");
        return;
    } else {
        Debug.Log("There was no error creating VivoxChannelAudioTap");
    }
}

If the TapId is less than zero, its value can help troubleshoot the error. These are the possible values and their error reasons:

• -1 : The tap is currently unregistered. This can happen when the tap is instantiated, but not yet registered to Vivox. For example, because it is waiting for the Channel to be acquired automatically.
• -1010 : The tap is not registered.
• -1011 : The tap tried to register with an invalid Participant Name.
• -1012 : The tap tried to register with an invalid Channel Name.
• -1050 : Only applicable to Vivox Participant Taps. The Participant URI was not found from the supplied Participant Name.
• -1051 : The tap tried to register to Vivox, but the VivoxService was not initialized. Make sure to initialize the VivoxService before initializing Audio Taps.
• -1052 : The tap tried to register to Vivox with an invalid Channel Name. Make sure to properly set the Channel Name.