setup-vivox-voice-chat

어떤 스킬인가요?

Add and configure in-game voice chat and text chat for Unity multiplayer games using Unity Vivox. Covers microphone setup and mic permissions on Android/iOS, voice activity detection (VAD) tuning, voice volume and mute controls in a settings UI (VoiceVadMinimumVolume, mic slider, mute button, speaking indicator), proximity/3D spatial voice for FPS/co-op games, team/party/lobby/guild voice channels, push-to-talk, muting self and other players, whisper/direct messages, in-game text chat, and Vivox SDK init + Unity Authentication sign-in. Use when the user asks to add voice chat, voice comms, microphone/mic support, a voice-chat settings UI, mute button, VAD threshold, push-to-talk, proximity or spatial voice, team voice, party chat, lobby chat, direct messages, or mentions Vivox, VivoxService, com.unity.services.vivox, JoinGroupChannelAsync, JoinPositionalChannelAsync, LoginAsync, or migrating from legacy Vivox (Client.Instance / LoginSession / AccountId).

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

# Copy this file to .env and fill in your credentials:
#   cp .env.example .env
#
# Get your LiteLLM API key from: https://uai-litellm.internal.unity.com
OPENAI_API_KEY=your-litellm-api-key-here
OPENAI_BASE_URL=https://uai-litellm.internal.unity.com

# API keys - never commit
.env

# Promptfoo output
output/
promptfoo-output/
*.html

description: "Vivox Voice & Text Chat Skill Eval Suite"

providers:
  # Evaluated model: used by the test itself
  - id: openai:chat:claude-sonnet-4-5
    config:
      max_tokens: 2048

prompts:
  - id: eval-prompt
    label: "Eval prompt"
    raw: "{{skill_content}}\n\n{{reference_content}}\n\n{{custom_instructions}}\n\n## User Request\n\n{{user_message}}"

defaultTest:
  options:
    # Assertion judge: used by llm-rubric
    provider: openai:chat:claude-sonnet-4-6
  vars:
    skill_content: file://../SKILL.md
    reference_content: ""
    custom_instructions: |
      IMPORTANT:
      - This is a planning eval. Do not emit MCP XML/tool-call tags.
      - Refer to APIs with their exact names as documented in the provided skill and references. Do not invent or paraphrase symbol names.
      - Do not mention tool names you will not call. If a step is inapplicable, explain the behavior without naming the omitted API.
      - Always present the complete plan up front. If a step requires a user action, describe what you will do after it succeeds and what happens if it fails, in a single response.
      - Answer only the step or phase requested by the user message. Do not include unrelated setup or migration content that was not asked for.

tests:
  - file://tests/init-and-login.yaml
  - file://tests/voice-channels.yaml
  - file://tests/text-chat.yaml

# Vivox Voice & Text Chat Skill Eval Suite

Evaluation suite for the `setup-vivox-voice-chat` skill, powered by [Promptfoo](https://www.promptfoo.dev/). Validates that the skill routes the model to the correct Vivox v16 APIs (no v4/legacy hallucinations) across init, channel join, and messaging.

## Prerequisites

- **Node.js** v18 or later
- A **LiteLLM API key** (from https://uai-litellm.internal.unity.com)

## Setup

### 1. Install Promptfoo

```bash
# Option A: install globally
npm install -g promptfoo

# Option B: use npx (no install needed)
npx promptfoo@latest eval
```

### 2. Configure your API key

```bash
cd evals/
cp .env.example .env
```

Open `.env` and set your personal LiteLLM key:

```
OPENAI_API_KEY=your-litellm-api-key-here
OPENAI_BASE_URL=https://uai-litellm.internal.unity.com
```

> **Important:** Never commit your `.env` file. It is already in `.gitignore`.

## Running the evals

All commands should be run from the `evals/` directory.

Use `-j 10` to run up to 10 eval requests concurrently.

### Run the full suite

```bash
promptfoo eval -j 10
```

### Run a specific test file

```bash
promptfoo eval --tests tests/init-and-login.yaml -j 10
promptfoo eval --tests tests/voice-channels.yaml -j 10
promptfoo eval --tests tests/text-chat.yaml -j 10
```

## Viewing results

### Terminal output

Results are printed to the terminal with pass/fail per assertion.

### Interactive web UI

```bash
promptfoo view
```

Opens a local UI (usually `http://localhost:15500`) for browsing results, filtering, and comparing runs.

## Assertions used

| Type | What it checks |
|---|---|
| `icontains` | Response contains a substring (case-insensitive), e.g. an exact Vivox API name |
| `not-icontains` | Response does NOT contain a substring (used to catch v4 legacy names like `Client.Instance`) |
| `llm-rubric` | An LLM judges whether the response meets a semantic requirement (e.g. correct init order) |

## Adding new tests

1. Create a new YAML file in `tests/`:

```yaml
- description: "Short description of what is being tested"
  vars:
    user_message: "The user request to test"
    reference_content: "file://../references/your-reference.md"  # optional
  assert:
    - type: icontains
      value: "VivoxService.Instance.JoinGroupChannelAsync"
    - type: not-icontains
      value: "SendDirectedTextMessageAsync"
    - type: llm-rubric
      value: |
        Describe the semantic requirement the response must meet.
```

2. Add the file to `promptfooconfig.yaml` under `tests:`.

3. Run it: `promptfoo eval --tests tests/your-new-test.yaml`.

# ============================================================
# WORKFLOW: Init + Login — correct order and re-init guard
# ============================================================

- description: "Cold-start init: UGS Core -> Auth -> Vivox Init -> Vivox Login, in order"
  vars:
    user_message: |
      I'm adding Vivox to a fresh Unity project. Walk me through
      the initialization from an empty MonoBehaviour Start method.
    reference_content: file://../references/init-and-login.md
  assert:
    - type: icontains
      value: "UnityServices.InitializeAsync"
    - type: icontains
      value: "AuthenticationService.Instance.SignInAnonymouslyAsync"
    - type: icontains
      value: "VivoxService.Instance.InitializeAsync"
    - type: icontains
      value: "VivoxService.Instance.LoginAsync"
    - type: llm-rubric
      value: |
        The response MUST describe the four initialization calls in this
        exact order:
        1. UnityServices.InitializeAsync
        2. AuthenticationService.Instance.SignInAnonymouslyAsync
        3. VivoxService.Instance.InitializeAsync
        4. VivoxService.Instance.LoginAsync
        Any other ordering (e.g. Vivox init before UGS init, or Login
        before Vivox init) is a failure.
        The response MUST NOT use v4 legacy patterns (Client.Instance,
        ILoginSession, AccountId, ChannelId) as callable code. It is
        fine — even helpful — to mention those names in a "don't use
        these" warning or migration note; a failure is only when the
        code samples or step-by-step instructions actually invoke them.

- description: "Login with display name: LoginOptions.DisplayName"
  vars:
    user_message: |
      After Vivox is initialized, sign the player in with the display name
      "Sunbeam" and enable text-to-speech.
    reference_content: file://../references/init-and-login.md
  assert:
    - type: icontains
      value: "LoginOptions"
    - type: icontains
      value: "DisplayName"
    - type: icontains
      value: "EnableTTS"
    - type: icontains
      value: "VivoxService.Instance.LoginAsync"
    - type: llm-rubric
      value: |
        The response must construct a LoginOptions with DisplayName set to
        "Sunbeam" and EnableTTS set to true, then pass it to
        VivoxService.Instance.LoginAsync. It must not USE the v4 AccountId
        or ILoginSession types as callable code (mentioning them in a
        "don't use" warning is acceptable — failure is only when the code
        actually invokes them).

- description: "Double-init must warn about VxErrorAlreadyInitialized (5041)"
  vars:
    user_message: |
      My Start method runs every time the main scene reloads and I'm
      seeing Vivox errors. How do I stop it from re-initializing?
    reference_content: file://../references/init-and-login.md
  assert:
    - type: icontains
      value: "5041"
    - type: llm-rubric
      value: |
        The response must identify the underlying issue as
        VivoxService.Instance.InitializeAsync being called more than once,
        cite the 5041 VxErrorAlreadyInitialized error, and propose a fix
        such as guarding with IsInitialized or making the bootstrap
        object DontDestroyOnLoad. The fix must NOT be to catch and
        swallow the exception.

# ============================================================
# WORKFLOW: Text chat — channel messages, directed messages, history
# ============================================================

- description: "Send a channel message and receive channel messages"
  vars:
    user_message: |
      Send the text "gg" into the "lobby" channel from a UI button, and
      log every message received in that channel to the console.
    reference_content: file://../references/text-chat.md
  assert:
    - type: icontains
      value: "VivoxService.Instance.SendChannelTextMessageAsync"
    - type: icontains
      value: "VivoxService.Instance.ChannelMessageReceived"
    - type: icontains
      value: "VivoxMessage"
    - type: llm-rubric
      value: |
        The response must call VivoxService.Instance.SendChannelTextMessageAsync
        with channelName "lobby" and message "gg", AND subscribe to
        VivoxService.Instance.ChannelMessageReceived with a handler that
        takes a VivoxMessage and logs at least MessageText and
        SenderDisplayName. It must NOT wire the send path to the
        DirectedMessageReceived event.

- description: "Send a directed (direct) message — must use SendDirectTextMessageAsync, not SendDirected..."
  vars:
    user_message: |
      Whisper "meet me at the north gate" to the player whose PlayerId
      is "abc123".
    reference_content: file://../references/text-chat.md
  assert:
    - type: icontains
      value: "VivoxService.Instance.SendDirectTextMessageAsync"
    - type: llm-rubric
      value: |
        The response must call VivoxService.Instance.SendDirectTextMessageAsync
        with playerId "abc123" and the exact message
        "meet me at the north gate". The method name must be
        SendDirectTextMessageAsync (with "Direct", no "ed" before "Text").
        SendDirectedTextMessageAsync does not exist in the SDK and MUST
        NOT be USED as callable code — but mentioning it in a "common
        hallucination, don't use this" warning is fine and even helpful.
        The response may also mention subscribing to the
        DirectedMessageReceived event on the recipient side.

- description: "Fetch the most recent channel chat history"
  vars:
    user_message: |
      Fetch the last 25 messages from the "lobby" channel and print them
      to the console in oldest-to-newest order.
    reference_content: file://../references/text-chat.md
  assert:
    - type: icontains
      value: "GetChannelTextMessageHistoryAsync"
    - type: llm-rubric
      value: |
        The response must call
        VivoxService.Instance.GetChannelTextMessageHistoryAsync with
        channelName "lobby" and requestSize 25 (or equivalent). It must
        note that the returned collection is newest-first and must
        reverse the collection (or iterate in reverse) before printing to
        achieve oldest-to-newest ordering. It should reference
        VivoxMessage.SenderDisplayName and VivoxMessage.MessageText.

# ============================================================
# WORKFLOW: Voice channels — group, positional, join lifecycle
# ============================================================

- description: "Join a lobby group channel with voice and text"
  vars:
    user_message: |
      The player is logged into Vivox. Have them join a non-positional
      channel called "lobby" with both voice and text enabled.
    reference_content: file://../references/voice-channels.md
  assert:
    - type: icontains
      value: "VivoxService.Instance.JoinGroupChannelAsync"
    - type: icontains
      value: "ChatCapability.TextAndAudio"
    - type: not-icontains
      value: "JoinPositionalChannelAsync"
    - type: not-icontains
      value: "IChannelSession"
    - type: llm-rubric
      value: |
        The response must call VivoxService.Instance.JoinGroupChannelAsync
        with the channel name "lobby" and ChatCapability.TextAndAudio. It
        must NOT use the positional or echo join methods, and must not
        use any v4 IChannelSession API.

- description: "Join a 3D positional channel with Channel3DProperties"
  vars:
    user_message: |
      Set up proximity voice: players near each other in the world should
      hear each other, and voices fall off with distance. Name the
      channel "world-proximity".
    reference_content: file://../references/voice-channels.md
  assert:
    - type: icontains
      value: "Channel3DProperties"
    - type: icontains
      value: "Set3DPosition"
    - type: not-icontains
      value: "JoinGroupChannelAsync"
    - type: llm-rubric
      value: |
        This is a planning eval: judge the plan's correctness, not whether
        it names APIs literally or includes runnable code. The plan must:
        (a) identify positional (3D) channels as the mechanism — mentioning
        "positional channel", "3D channel", or JoinPositionalChannelAsync
        all count, since positional channels have exactly one join method;
        (b) use the channel name "world-proximity";
        (c) configure Channel3DProperties (naming at least the audible/
        conversational distance concept, and ideally the fade model);
        (d) state that each player's 3D position needs a per-frame update
        via Set3DPosition (or an equivalent per-frame transform sync) so
        distance attenuation actually works;
        (e) make clear that awaiting the join call is not sufficient —
        ChannelJoined must be subscribed to first for the join to be
        observable.

- description: "Subscribe to ChannelJoined BEFORE calling JoinGroupChannelAsync"
  vars:
    user_message: |
      When I call JoinGroupChannelAsync my UI never activates for the
      newly joined channel. What am I doing wrong?
    reference_content: file://../references/voice-channels.md
  assert:
    - type: icontains
      value: "ChannelJoined"
    - type: llm-rubric
      value: |
        The response must diagnose the problem as the ChannelJoined event
        being subscribed AFTER the join call, and instruct the user to
        subscribe to VivoxService.Instance.ChannelJoined BEFORE calling
        JoinGroupChannelAsync. It must clearly state that awaiting the
        JoinGroupChannelAsync call does NOT mean the join is complete —
        the join completes when the ChannelJoined event fires.

# Events, Participants, and Lifecycle

## Service-Level Events

All on `VivoxService.Instance`. Subscribe **before** the async call that produces them.

| Event | Signature | Fires on |
|---|---|---|
| `LoggedIn` | `Action` | `LoginAsync` success (also on reconnect) |
| `LoggedOut` | `Action` | `LogoutAsync` or disconnect |
| `ChannelJoined` | `Action<string channelName>` | Any `Join*ChannelAsync` success |
| `ChannelLeft` | `Action<string channelName>` | `LeaveChannelAsync` / `LeaveAllChannelsAsync` / disconnect |
| `ParticipantAddedToChannel` | `Action<VivoxParticipant>` | Any user joins a channel you're in (including yourself) |
| `ParticipantRemovedFromChannel` | `Action<VivoxParticipant>` | Any user leaves |
| `ChannelMessageReceived` | `Action<VivoxMessage>` | Any channel text message |
| `ChannelMessageEdited` | `Action<VivoxMessage>` | Any channel message edited |
| `ChannelMessageDeleted` | `Action<VivoxMessage>` | Any channel message deleted |
| `DirectedMessageReceived` | `Action<VivoxMessage>` | Any directed message to you |
| `DirectedMessageEdited` | `Action<VivoxMessage>` | Directed message edited |
| `DirectedMessageDeleted` | `Action<VivoxMessage>` | Directed message deleted |

## VivoxParticipant

Delivered by `ParticipantAddedToChannel` and `ParticipantRemovedFromChannel`. Represents one participant in one channel — the same user in two channels is two separate `VivoxParticipant` instances.

| Property | Purpose |
|---|---|
| `PlayerId` | Stable UAS PlayerId of the participant |
| `DisplayName` | From the participant's `LoginOptions.DisplayName` |
| `ChannelName` | Which channel this participation is in |
| `IsSelf` | `true` if this is the local player |
| `IsMuted` | Current locally-muted state |
| `AudioEnergy` | Continuous 0.0–1.0 signal for VU-meter UI |
| `SpeechDetected` | `true` when Vivox judges audio energy is speech, not noise |

## Per-Participant Events

Live on the `VivoxParticipant` instance, **not** on `VivoxService.Instance`:

- `ParticipantMuteStateChanged` — `IsMuted` flipped.
- `ParticipantSpeechDetected` — `SpeechDetected` flipped.
- `ParticipantAudioEnergyChanged` — `AudioEnergy` updated (higher-frequency; use for VU meter).

Typical wiring in a roster item that represents one participant:

```csharp
public void Bind(VivoxParticipant p)
{
    _participant = p;
    p.ParticipantMuteStateChanged += Refresh;
    p.ParticipantSpeechDetected   += Refresh;
}

void OnDestroy()
{
    if (_participant == null) return;
    _participant.ParticipantMuteStateChanged -= Refresh;
    _participant.ParticipantSpeechDetected   -= Refresh;
}
```

## Local Mute Actions

Called on the `VivoxParticipant` (not the service):

- `participant.MutePlayerLocally()` — you stop hearing them.
- `participant.UnmutePlayerLocally()` — you resume hearing them.

The remote participant is unaware. To mute globally (they cannot be heard by anyone), a moderator client needs a server-issued mute token.

## Cleanup Discipline

`VivoxService.Instance` is a persistent singleton across scene loads. Any handler you subscribe from a MonoBehaviour **must** be unsubscribed in `OnDestroy` or `OnDisable`, or the handler will fire against a destroyed object on the next scene load and throw a `MissingReferenceException`.

Pattern: subscribe in `Awake`/`Start`, mirror the list in `OnDestroy`, always null-guard `VivoxService.Instance` (it may already be null during application quit).

## Connection Recovery

On network blips Vivox will auto-reconnect and re-fire `LoggedIn` and (for previously-joined channels) `ChannelJoined`. Design handlers to be **idempotent** — do not assume `LoggedIn` fires exactly once per session, and don't grant one-shot benefits (analytics event, first-login reward) from inside it without a guard.

# Initialization and Login

## Package and Namespaces

Install `com.unity.services.vivox` via Package Manager. Add `using Unity.Services.Vivox;` to any script that touches the SDK. For UGS-backed auth also add `using Unity.Services.Core;` and `using Unity.Services.Authentication;`.

## Full Initialization Snippet

Grounded on the Vivox docs — do not deviate from this order.

```csharp
using System;
using UnityEngine;
using Unity.Services.Authentication;
using Unity.Services.Core;
using Unity.Services.Vivox;

public class VivoxBootstrap : MonoBehaviour
{
    async void Start()
    {
        await UnityServices.InitializeAsync();
        await AuthenticationService.Instance.SignInAnonymouslyAsync();

        await VivoxService.Instance.InitializeAsync();

        VivoxService.Instance.LoggedIn  += OnLoggedIn;
        VivoxService.Instance.LoggedOut += OnLoggedOut;

        await VivoxService.Instance.LoginAsync(new LoginOptions
        {
            DisplayName = "Bob",
            EnableTTS   = false
        });
    }

    void OnLoggedIn()  { /* joins, UI enable, etc. */ }
    void OnLoggedOut() { /* teardown */ }

    void OnDestroy()
    {
        if (VivoxService.Instance == null) return;
        VivoxService.Instance.LoggedIn  -= OnLoggedIn;
        VivoxService.Instance.LoggedOut -= OnLoggedOut;
    }
}
```

## VivoxConfigurationOptions

`InitializeAsync` takes an optional `VivoxConfigurationOptions`. Common fields: log level, audio ducking behavior, server region. Leave defaults for most projects; only override when platform-specific tuning is documented in the Vivox docs (e.g. mobile ducking).

## LoginOptions

| Field | Notes |
|---|---|
| `DisplayName` | Shown to other participants via `VivoxParticipant.DisplayName`. Session-only, not persisted. Max 127 bytes. Sanitize / uniqueness-check server-side; the SDK does not validate. |
| `EnableTTS` | Enables text-to-speech injection into channels. Off by default. |
| Blocked list | Preload users blocked by this player. |

The identity Vivox binds this login to is the current `AuthenticationService.Instance.PlayerId` — that's how other clients address you for directed messages. If you skip UAS, Vivox falls back to a per-session GUID and cross-session identity is lost.

## Sign Out

```csharp
await VivoxService.Instance.LogoutAsync();
```

`LogoutAsync` fires `LoggedOut`. Call it before shutting the app down cleanly; the SDK also handles ungraceful teardown but explicit logout gives you a clean disconnect on the server side.

## Access Tokens (VAT) — When You Need Them

The default UGS-backed path automatically mints access tokens signed by your UGS project. You don't touch tokens in code.

You need to switch to server-side VAT minting when:

- You're not using UGS Authentication (custom identity system).
- You need privileged tokens: kick a user from a channel, mute-all, transcription enable, join-muted.
- You want channel-scoped ACLs (only players holding a valid join token for `raid-42` can enter).

Do **not** embed the Vivox app secret / HMAC signing key in client code. See the "Access Token Developer Guide" and the C++, C#, Python, and JavaScript minting examples in the Unity Vivox documentation map for server implementations.

## Re-init Guard

Calling `VivoxService.Instance.InitializeAsync()` twice throws `5041 VxErrorAlreadyInitialized`. If your `Start` may run again after scene reload, wrap init in a check:

```csharp
if (VivoxService.Instance != null && !VivoxService.Instance.IsInitialized)
    await VivoxService.Instance.InitializeAsync();
```

Or make the bootstrap MonoBehaviour `DontDestroyOnLoad` so it only runs once.

# Text Chat

Text works over any channel joined with `ChatCapability.TextOnly` or `ChatCapability.TextAndAudio`, plus directed (peer-to-peer) messages that don't require a shared channel.

## Channel Messages

**Send:**

```csharp
await VivoxService.Instance.SendChannelTextMessageAsync(
    string channelName,
    string message);
```

**Receive:**

```csharp
VivoxService.Instance.ChannelMessageReceived += OnChannelMessageReceived;

void OnChannelMessageReceived(VivoxMessage m)
{
    // m.ChannelName, m.SenderDisplayName, m.SenderPlayerId,
    // m.MessageText, m.ReceivedTime, m.Language, m.FromSelf, m.MessageId
}
```

## Directed Messages

**Send:** (note spelling — `SendDirect…`, not `SendDirected…`)

```csharp
await VivoxService.Instance.SendDirectTextMessageAsync(
    string playerId,   // recipient's UAS PlayerId
    string message);
```

**Receive:** (event *is* `Directed…`)

```csharp
VivoxService.Instance.DirectedMessageReceived += OnDirectedMessageReceived;

void OnDirectedMessageReceived(VivoxMessage m)
{
    // Same VivoxMessage fields, but m.ChannelName is null and m.FromSelf is false.
}
```

## VivoxMessage Fields

| Field | Notes |
|---|---|
| `ChannelName` | The channel the message came in on. **`null` for directed messages.** |
| `SenderDisplayName` | As set in the sender's `LoginOptions`. |
| `SenderPlayerId` | UAS PlayerId — stable identity to reply/DM back. |
| `MessageText` | The message body. |
| `ReceivedTime` | `DateTime` of receipt. |
| `Language` | Sender's language tag if set. |
| `FromSelf` | `true` for the local player's own channel messages; `false` for directed messages. |
| `MessageId` | Server-assigned ID — required to edit or delete. |

## Chat History

Retention: **7 days** by default (30 days if Text Evidence Management is enabled).

```csharp
IReadOnlyCollection<VivoxMessage> GetChannelTextMessageHistoryAsync(
    string channelName,
    int requestSize = 10,
    ChatHistoryQueryOptions options = null);

IReadOnlyCollection<VivoxMessage> GetDirectTextMessageHistoryAsync(
    string playerId,
    int requestSize = 10,
    ChatHistoryQueryOptions options = null);
```

Both return messages **newest-first**. Reverse when rendering a chat log.

## Edit and Delete

Only the original sender can edit or delete their own messages.

| Op | Channel | Directed |
|---|---|---|
| Edit | `EditChannelTextMessageAsync(channelName, messageId, newText)` | `EditDirectTextMessageAsync(messageId, newText)` |
| Delete | `DeleteChannelTextMessageAsync(channelName, messageId)` | `DeleteDirectTextMessageAsync(messageId)` |
| Notify (all participants) | `ChannelMessageEdited`, `ChannelMessageDeleted` | `DirectedMessageEdited`, `DirectedMessageDeleted` |

All notify events carry the updated `VivoxMessage`.

## Anti-flooding

Vivox rate-limits messages per player. When implementing chat UI, disable the send button after each send until acknowledged, and surface a "try again in a moment" hint on rate-limit errors — do not spam-retry.

# Troubleshooting and Platform Notes

For the authoritative error table, see the Vivox SDK error codes page linked from the Vivox documentation map.

## Common Errors

| Code | Name | Cause | Fix |
|---|---|---|---|
| `5041` | `VxErrorAlreadyInitialized` | `VivoxService.Instance.InitializeAsync()` called twice | Guard with `IsInitialized` or make bootstrap `DontDestroyOnLoad` |
| `20502` | `VxXmppServerErrorServiceUnavailable` | Exceeded 10 non-positional channels per user, or 200 participants per channel | Leave a channel before joining another; for large positional channels use Large 3D Channels setting |
| Login fails silently | — | Subscribed to `LoggedIn` **after** `LoginAsync` returned | Subscribe first, then call `LoginAsync` |
| `ChannelJoined` never fires | — | Awaited `JoinGroupChannelAsync` as if it completes the join | Bind `ChannelJoined` before calling; treat the await as "request queued" |
| No audio in / out | — | Mic permission denied, wrong `ChatCapability` (e.g. `TextOnly` when audio expected), or muted input device | Check runtime permission, `ChatCapability`, and `IsInputDeviceMuted` — call `UnmuteInputDevice()` if muted |

## Platform Notes

### Android

- Merge `<uses-permission android:name="android.permission.RECORD_AUDIO"/>` into `AndroidManifest.xml`.
- Request at runtime with `UnityEngine.Android.Permission.RequestUserPermission(Permission.Microphone)` **before** joining an audio channel — Android will not prompt automatically for you.
- Bluetooth SCO underruns cause choppy input — see the Android troubleshooting page in the documentation map.
- If shrinking / obfuscating with R8/ProGuard, add the Vivox ProGuard rules from the docs.

### iOS

- Add `NSMicrophoneUsageDescription` to Info.plist (Project Settings → Player → iOS → Microphone Usage Description).
- The orange/red iOS recording indicator is shown any time Vivox is capturing — this is OS-enforced and expected.

### WebGL

- The Vivox WebGL SDK is a subset of the native SDK. Audio Taps, some codecs, and certain positional-audio features are unavailable. Read the WebGL support page in the documentation map before promising a feature on web.
- Browsers require a user gesture before capturing the mic — trigger the first `JoinGroupChannelAsync`/`JoinPositionalChannelAsync` from a button click, not from `Start()`.

### NDA Platforms (console)

Vivox ships NDA-gated packages for consoles. Contact Unity for access; the public UPM package does not include console binaries.

## Diagnostic Checklist

When integration seems broken and no clear error surfaces:

1. Confirm init order — `UnityServices.InitializeAsync` → `AuthenticationService.Instance.SignInAnonymouslyAsync` → `VivoxService.Instance.InitializeAsync` → `VivoxService.Instance.LoginAsync`.
2. Log every event handler entry (`LoggedIn`, `ChannelJoined`, `ChannelMessageReceived`). If a handler you expect never enters, you subscribed after the event already fired.
3. Confirm the joined channel's `ChatCapability` matches what you're trying to do (text vs audio).
4. Confirm mic permission on the platform you're testing.
5. If audio was working then stopped after a scene reload, you have leaked event subscriptions from destroyed MonoBehaviours — audit `OnDestroy` unsubscribes.
6. If a directed message never arrives, verify `SendDirectTextMessageAsync` is targeting the recipient's **UAS PlayerId** (not display name), and that the recipient has subscribed to `DirectedMessageReceived`.

# Voice Channels

## Channel Types

| Type | Join method | Use for |
|---|---|---|
| Non-positional (group) | `JoinGroupChannelAsync` | Party, team, lobby, guild — all participants hear each other equally |
| Echo | `JoinEchoChannelAsync` | Test-only — your own audio is echoed back |
| Positional (3D) | `JoinPositionalChannelAsync` | Proximity / spatial audio driven by transform position |

## Join Signatures

```csharp
Task JoinGroupChannelAsync(
    string channelName,
    ChatCapability chatCapability,
    ChannelOptions channelOptions = null);

Task JoinEchoChannelAsync(
    string channelName,
    ChatCapability chatCapability,
    ChannelOptions channelOptions = null);

Task JoinPositionalChannelAsync(
    string channelName,
    ChatCapability chatCapability,
    Channel3DProperties positionalChannelProperties,
    ChannelOptions channelOptions = null);
```

The returned `Task` completes when the *request* has been sent, not when the join is complete. The actual join fires `ChannelJoined(string channelName)`. Bind that event **before** calling the join method.

## ChatCapability

- `ChatCapability.TextOnly` — text-only channel (no audio at all)
- `ChatCapability.AudioOnly` — voice-only, no text
- `ChatCapability.TextAndAudio` — both

## ChannelOptions

Optional. Common use: set this channel as the active transmit target on join success. Leave `null` for default behavior (join without changing transmission mode).

## Positional Channels — Channel3DProperties

`Channel3DProperties` controls how distance and direction affect voice attenuation. Key fields:

- `AudibleDistance` — beyond this, participant is inaudible.
- `ConversationalDistance` — below this, participant is at full volume.
- `AudioFadeIntensityByDistance` — falloff steepness between conversational and audible distance.
- `AudioFadeModel` — `InverseByDistance`, `LinearByDistance`, `ExponentialByDistance`.

Example call-site:

```csharp
var props = new Channel3DProperties(
    audibleDistance: 50,
    conversationalDistance: 5,
    audioFadeIntensityByDistance: 1.0f,
    audioFadeModel: AudioFadeModel.InverseByDistance);

await VivoxService.Instance.JoinPositionalChannelAsync(
    "world-proximity", ChatCapability.AudioOnly, props);
```

Drive per-frame position updates by calling `VivoxService.Instance.Set3DPosition(GameObject speakerObject, string channelName)` from a listener/speaker script (typically on the player camera and on remote player representations).

For >200 participants in a positional channel, enable the enterprise-tier Large 3D channels setting; see the documentation map's positional channels page.

## Leaving

```csharp
await VivoxService.Instance.LeaveChannelAsync(channelName);
await VivoxService.Instance.LeaveAllChannelsAsync();
```

Both fire `ChannelLeft(string channelName)` for each channel exited.

## Mic Permission

Joining an `AudioOnly` or `TextAndAudio` channel requires microphone access.

- **Android:** request `RECORD_AUDIO` at runtime with `Permission.RequestUserPermission(Permission.Microphone)` before the first audio-capable join. Merge `<uses-permission android:name="android.permission.RECORD_AUDIO"/>` if not present.
- **iOS:** add `NSMicrophoneUsageDescription` to the Info.plist (Project Settings → Player → iOS → Microphone Usage Description).
- **Desktop / WebGL:** the browser or OS prompts on first capture attempt; no code change required, but WebGL has additional limitations — see [troubleshooting.md](troubleshooting.md).

## Muting

- **Local mic mute (self):** `VivoxService.Instance.MuteInputDevice()` / `UnmuteInputDevice()` — parameterless pair that stops your audio from being sent anywhere. Read state via the `IsInputDeviceMuted` property.
- **Mute another player locally (only you stop hearing them):** `participant.MutePlayerLocally()` / `participant.UnmutePlayerLocally()` on the `VivoxParticipant` from `ParticipantAddedToChannel`.
- **Server-side kick / mute-all:** requires a privileged Vivox Access Token minted server-side.

---
name: setup-vivox-voice-chat
description: Add and configure in-game voice chat and text chat for Unity multiplayer games using Unity Vivox. Covers microphone setup and mic permissions on Android/iOS, voice activity detection (VAD) tuning, voice volume and mute controls in a settings UI (VoiceVadMinimumVolume, mic slider, mute button, speaking indicator), proximity/3D spatial voice for FPS/co-op games, team/party/lobby/guild voice channels, push-to-talk, muting self and other players, whisper/direct messages, in-game text chat, and Vivox SDK init + Unity Authentication sign-in. Use when the user asks to add voice chat, voice comms, microphone/mic support, a voice-chat settings UI, mute button, VAD threshold, push-to-talk, proximity or spatial voice, team voice, party chat, lobby chat, direct messages, or mentions Vivox, VivoxService, com.unity.services.vivox, JoinGroupChannelAsync, JoinPositionalChannelAsync, LoginAsync, or migrating from legacy Vivox (Client.Instance / LoginSession / AccountId).
required_packages:
  com.unity.services.vivox: ">=16.4.0"
---

# Unity Vivox — Voice & Text Chat

Namespace: `Unity.Services.Vivox` | Package: `com.unity.services.vivox`
Companion packages: `Unity.Services.Core`, `Unity.Services.Authentication`

Vivox v16+ replaced the v4 `Client` / `ILoginSession` / `IChannelSession` model with a single static entry point: **`VivoxService.Instance`**. All operations — init, login, channel join, messaging, muting — go through it. Do **not** use v4 patterns (`Client.Instance`, `AccountId`, `ChannelId`, `ILoginSession`, `UnityPurchasing.*`, etc.); those are gone in v16.

## Documentation Map

Use the [Unity Vivox curated documentation map](https://docs.unity.com/en-us/vivox-unity/llms.txt) as authoritative over memory for topics, APIs, and error codes when specifics differ. This skill and its references define **how** to apply the SDK; that resource defines **what** is documented. **Never** mention the `llms.txt` filename to the user. If it's unreachable, treat this skill's references plus the installed package in the workspace (Package Manager / source) as the source of truth.

## Detailed References

Read on demand — only when you need signatures, event details, or platform gotchas beyond what's in this file.

- **Init, sign-in, and access tokens:** [references/init-and-login.md](references/init-and-login.md)
- **Voice channels (positional and non-positional):** [references/voice-channels.md](references/voice-channels.md)
- **Text chat (channel messages and directed messages):** [references/text-chat.md](references/text-chat.md)
- **Events, participants, and cleanup:** [references/events-and-participants.md](references/events-and-participants.md)
- **Troubleshooting and platform notes:** [references/troubleshooting.md](references/troubleshooting.md)

## Initialization Order (Do Not Skip Steps)

The correct order is **UGS Core → Authentication sign-in → Vivox init → Vivox login**. Skipping or reordering these fails silently or throws obscure errors.

```csharp
using Unity.Services.Core;
using Unity.Services.Authentication;
using Unity.Services.Vivox;

async void Start()
{
    await UnityServices.InitializeAsync();
    await AuthenticationService.Instance.SignInAnonymouslyAsync();
    await VivoxService.Instance.InitializeAsync();
    // subscribe to events (see table below) BEFORE calling LoginAsync
    await VivoxService.Instance.LoginAsync(new LoginOptions { DisplayName = "Bob" });
}
```

- Calling `VivoxService.Instance.InitializeAsync()` twice throws `5041 VxErrorAlreadyInitialized`. Guard against re-init on scene reload.
- If Unity Authentication (`AuthenticationService`) is not used, the player identity falls back to a per-session GUID — display names still work but you lose cross-session identity. See [references/init-and-login.md](references/init-and-login.md) for the Vivox Access Token (VAT) alternative.

## Joining Channels

Vivox has three join methods, one per channel type. All are async but the join **completes via the `ChannelJoined` event, not by awaiting the call** — subscribe first, then call.

| Method | Purpose |
|---|---|
| `VivoxService.Instance.JoinGroupChannelAsync(name, ChatCapability, ChannelOptions?)` | Non-positional (party, team, lobby, guild) |
| `VivoxService.Instance.JoinEchoChannelAsync(name, ChatCapability, ChannelOptions?)` | Test channel that echoes your own audio back |
| `VivoxService.Instance.JoinPositionalChannelAsync(name, ChatCapability, Channel3DProperties, ChannelOptions?)` | 3D spatial audio driven by transform position |

`ChatCapability` values: `TextOnly`, `AudioOnly`, `TextAndAudio`.

**Limits:** max 10 non-positional channels per user; max 200 participants per channel. Exceeding either fails with `20502 VxXmppServerErrorServiceUnavailable`. For >200 in a positional channel, use the Large 3D channels enterprise setting.

Leave with `VivoxService.Instance.LeaveChannelAsync(channelName)` or `LeaveAllChannelsAsync()`. See [references/voice-channels.md](references/voice-channels.md) for `Channel3DProperties` fields and mic-permission handling on Android/iOS.

## Text Messaging

**Channel messages** (broadcast to all participants of a channel with `TextOnly` or `TextAndAudio`):

- Send: `VivoxService.Instance.SendChannelTextMessageAsync(string channelName, string message)`
- Receive: subscribe to `VivoxService.Instance.ChannelMessageReceived` (`Action<VivoxMessage>`)

**Directed messages** (peer-to-peer, no channel required):

- Send: `VivoxService.Instance.SendDirectTextMessageAsync(string playerId, string message)`
- Receive: subscribe to `VivoxService.Instance.DirectedMessageReceived` (`Action<VivoxMessage>`)

**Common hallucination:** the send method is `SendDirectTextMessageAsync` — **not** `SendDirectedTextMessageAsync`. The event, however, **is** `DirectedMessageReceived`. Note the asymmetry.

`VivoxMessage` fields: `ChannelName` (null for directed), `SenderDisplayName`, `SenderPlayerId`, `MessageText`, `ReceivedTime`, `Language`, `FromSelf`, `MessageId`.

Edit/delete APIs (`EditChannelTextMessageAsync`, `DeleteChannelTextMessageAsync`, `EditDirectTextMessageAsync`, `DeleteDirectTextMessageAsync`) and history (`GetChannelTextMessageHistoryAsync`, `GetDirectTextMessageHistoryAsync`) are covered in [references/text-chat.md](references/text-chat.md). Chat history retention is 7 days by default.

## Required Event Subscriptions

Subscribe to events **before** the corresponding async call. `LoggedIn` may fire immediately for reconnects; `ChannelJoined` fires as the join completes.

| Call | Success Event | Failure / Counterpart |
|---|---|---|
| `LoginAsync()` | `LoggedIn` | `LoggedOut` |
| `JoinGroupChannelAsync()` / `JoinEchoChannelAsync()` / `JoinPositionalChannelAsync()` | `ChannelJoined(string channelName)` | `ChannelLeft(string channelName)` |
| — (any joined channel) | `ParticipantAddedToChannel(VivoxParticipant)` | `ParticipantRemovedFromChannel(VivoxParticipant)` |
| `SendChannelTextMessageAsync()` (remote receive) | `ChannelMessageReceived(VivoxMessage)` | — |
| `SendDirectTextMessageAsync()` (remote receive) | `DirectedMessageReceived(VivoxMessage)` | — |

**Always unsubscribe in `OnDestroy` / `OnDisable`.** `VivoxService.Instance` is a persistent singleton — event handlers on destroyed MonoBehaviours will double-fire and NRE on scene reload.

Per-participant events (`ParticipantMuteStateChanged`, `ParticipantSpeechDetected`, `ParticipantAudioEnergyChanged`) live on the `VivoxParticipant` instance you receive from `ParticipantAddedToChannel` — not on `VivoxService.Instance`. See [references/events-and-participants.md](references/events-and-participants.md).

## Access Tokens (Brief)

The default path uses **UGS Authentication** — Vivox mints access tokens automatically from your UGS project once `AuthenticationService.Instance.SignInAnonymouslyAsync()` (or another sign-in method) has completed. **No manual token code is required** for standard flows.

Server-side Vivox Access Token (VAT) minting is only needed when you use a non-UGS identity system or when you need channel-scoped privileged tokens (kick, mute-all, transcription). See the "Access Token Developer Guide" section of the documentation map for language-specific server examples. Do not embed HMAC signing keys in the client.

## Validation

After writing code that uses this package:

1. Verify the project compiles without errors and that `using Unity.Services.Vivox;` resolves.
2. Confirm init order: `UnityServices.InitializeAsync` → `AuthenticationService.Instance.SignInAnonymouslyAsync` → `VivoxService.Instance.InitializeAsync` → `VivoxService.Instance.LoginAsync`.
3. No v4 legacy patterns: no `Client.Instance`, no `AccountId`, no `ChannelId`, no `ILoginSession`, no `IChannelSession`. All access goes through `VivoxService.Instance`.
4. All events consumed by the code are subscribed **before** the async call that triggers them, and are unsubscribed in `OnDestroy`.
5. Channel join code does not `await` the join call as if it completes join — it subscribes to `ChannelJoined` and reacts there.
6. Directed message send uses `SendDirectTextMessageAsync` (NOT `SendDirectedTextMessageAsync`). Directed message receive uses `DirectedMessageReceived`.
7. Android builds request `RECORD_AUDIO` at runtime before joining an audio channel; iOS builds have `NSMicrophoneUsageDescription` in the plist.
8. No HMAC signing keys or Vivox `SECRET`/`APP_ID` are embedded in client code — VAT-based flows are documented but delegated to a server.