> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streampixel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice, text and video chat

> Add a Streampixel project's built-in voice, text and video chat to your own page with @streampixel/web-sdk/voice: join a room, show people and messages, and handle microphone and camera.

Advanced For developers who want the people on a stream to talk, type or see each other. After this page you can join the project's chat room from your own page and build your own chat interface on its events.

Chat is a separate entry point of the same package: `@streampixel/web-sdk/voice`. A page that does not import it downloads no chat code. The SDK draws no chat interface: it gives you methods and events, and you draw the people, the messages and the buttons.

> [!NOTE]
>
> **npm only.** The script-tag build does not include chat.

## Before you start

* Turn chat on for the project in the dashboard: [Built-in voice and text chat](https://docs.streampixel.io/resources/quick-start-guide/built-in-voice-and-text-chat.md). While it is off, `stream.voiceToken` is `undefined` and `VoiceChat.for()` rejects.
* You need a running stream: chat is created from a `stream` object. See [Quick start](https://docs.streampixel.io/resources/web-sdk-v2/quick-start.md).
* If your site sends a Content-Security-Policy, allow the chat server. See [Content-Security-Policy](#content-security-policy).

## Add chat to your page

**1. Install the package**

Chat is in the package you already have. There is nothing extra to install.

```bash npm theme={"dark"}
npm install @streampixel/web-sdk
```

```bash yarn theme={"dark"}
yarn add @streampixel/web-sdk
```

```bash pnpm theme={"dark"}
pnpm add @streampixel/web-sdk
```

**2. Create the chat for a stream**

`VoiceChat.for()` loads the chat code and prepares the chat. It does not connect yet.

```ts highlight={6-8} theme={"dark"}
import { Streampixel } from '@streampixel/web-sdk';
import { VoiceChat } from '@streampixel/web-sdk/voice';

const stream = await Streampixel.create({ appId: 'YOUR_PROJECT_ID', container });

// stream.voiceToken is undefined when the project has chat off
if (!stream.voiceToken) throw new Error('Chat is off for this project');
const chat = await VoiceChat.for(stream, { userName: 'Alex' });
```

**3. Listen, then join**

Attach your listeners first, so you see the first list of people. Then call `join()`.

```ts theme={"dark"}
chat.on('message', ({ from, text }) => addLine(from, text));
chat.on('roster', ({ localParticipant, remoteParticipants }) => renderPeople(localParticipant, remoteParticipants));

await chat.join();
```

> [!TIP]
>
> `roster` fires with yourself as `localParticipant`. Open the page in a second browser: each page sees the other in `remoteParticipants`.

**4. Turn the microphone on from a button**

The microphone starts off. Turn it on when the viewer asks for it. The browser shows its permission prompt the first time.

```ts theme={"dark"}
micButton.addEventListener('click', async () => {
  const on = await chat.toggleMic(true); // false when permission was refused
  micButton.textContent = on ? 'Mute' : 'Unmute';
});
```

Everyone on the same project who joins is in the same room. Pass `roomId` for a separate room inside the project's room.

When the stream ends, the chat leaves the room by itself.

> [accordion] A complete example
>
> A page with a list of people, a message list, a text field and a microphone button. It leaves out styling and the error handling around `Streampixel.create()`.
>
> ```ts chat.ts expandable theme={"dark"}
> import { Streampixel } from '@streampixel/web-sdk';
> import { VoiceChat, type VoiceRoster } from '@streampixel/web-sdk/voice';
>
> const container = document.getElementById('stream')!;
> const people = document.getElementById('people')!;       // <ul>
> const messages = document.getElementById('messages')!;   // <ul>
> const input = document.getElementById('message') as HTMLInputElement;
> const micButton = document.getElementById('mic') as HTMLButtonElement;
>
> const stream = await Streampixel.create({ appId: 'YOUR_PROJECT_ID', container });
>
> if (stream.voiceToken) {
>   const chat = await VoiceChat.for(stream, { userName: 'Alex' });
>   let micOn = false;
>
>   const addLine = (text: string) => {
>     const li = document.createElement('li');
>     li.textContent = text; // textContent, never innerHTML: the text comes from other people
>     messages.append(li);
>   };
>
>   const renderPeople = ({ localParticipant, remoteParticipants }: VoiceRoster) => {
>     people.replaceChildren();
>     for (const p of [localParticipant, ...remoteParticipants]) {
>       if (!p) continue; // localParticipant is null after leaving
>       const li = document.createElement('li');
>       li.textContent = `${p.id}${p.micMuted ? ' (muted)' : ''}${p.speaking ? ' (speaking)' : ''}`;
>       people.append(li);
>     }
>   };
>
>   chat.on('roster', renderPeople);
>   chat.on('message', ({ from, text }) => addLine(`${from}: ${text}`));
>   chat.on('deviceError', ({ message }) => addLine(message)); // for example "Microphone permission denied."
>
>   await chat.join();
>
>   micButton.addEventListener('click', async () => {
>     const changed = await chat.toggleMic(!micOn);
>     if (changed) micOn = !micOn;
>     micButton.textContent = micOn ? 'Mute' : 'Unmute';
>   });
>
>   input.addEventListener('keydown', (e) => {
>     if (e.key === 'Enter' && input.value.trim()) {
>       chat.sendMessage(input.value); // comes back as a `message` event with from: 'You'
>       input.value = '';
>     } else {
>       chat.sendTyping();
>     }
>   });
> }
> ```

## `VoiceChat.for(stream, options)`

Returns a `Promise` of the chat object. It rejects when the project has chat off, and with an `EngineLoadError` when the chat code cannot be loaded.

**stream** `Streampixel` *required*

The stream this chat belongs to. The chat uses the stream's project and its chat token.

**options** `object` *required*

**properties**

**userName** `string` *required*

The name shown to the others.

**avatar** `string`

An avatar URL shown to the others.

**voice** `boolean` (default: false)

Open the microphone on join. Off by default, as on the share page: the viewer turns it on.

**roomId** `string`

A room inside the project's room. Without it, everyone on the project is in one room.

**platformHost** `string` (default: [https://platform.streampixel.io](https://platform.streampixel.io))

The platform's address, for dedicated and on-premises deployments. Must be `https`. **It is not taken from the stream**: if you set `advanced.platformHost` on the stream, pass the same host here.

**livekitUrl** `string` (default: Streampixel's chat server)

The chat server's address, for deployments with their own chat server.

## Methods

| Call | Returns | What it does |
| - | - | - |
| `join()` | `Promise<void>` | Connects to the room. Rejects when the platform refuses the chat token or the chat server cannot be reached. |
| `leave()` | `Promise<void>` | Leaves the room. `roster` fires once more, with `localParticipant: null` and no remote participants. |
| `toggleMic(enable)` | `Promise<boolean>` | Turns the microphone on or off. Resolves to whether the change took effect: `false` when permission was refused, and before `join()`. |
| `toggleCamera(enable)` | `Promise<boolean>` | The same for the camera. |
| `sendMessage(text)` | `void` | Sends a text message. Empty text is ignored. Your own message also comes back as a `message` event with `from: 'You'`. |
| `sendTyping()` | `void` | Tells the others that this viewer is typing. It is a best-effort signal: decide in your own page how long to show it. |
| `setRemoteAudio(enabled, id?)` | `void` | Stops or resumes hearing one participant (by `id`), or everyone when you pass no `id`. For this viewer only. |
| `on(event, fn)` | unsubscribe function | Subscribes to an event. Any number of listeners per event. |

## Events

**message** `\{ from, text, avatar? \}`

A chat message arrived, or you sent one. `from` is the sender's `id`, or `'You'` for your own message.

**roster** `\{ localParticipant, remoteParticipants \}`

Someone joined or left, started or stopped speaking, or changed microphone or camera. Redraw your list of people from it.

**a participant**

**id** `string`

The participant's ID in the room.

**avatar** `string`

The avatar URL the participant passed, when there is one.

**speaking** `boolean`

Whether the participant is speaking now.

**micMuted** `boolean`

Whether the participant's microphone is off.

**videoTrack** `object | null`

The participant's camera track, or `null` when the camera is off. Hide the tile then, rather than show black.

**typing** `\{ from, avatar? \}`

Someone is typing.

**deviceError** `\{ name, kind?, message \}`

The microphone or camera could not be opened. `message` is a short sentence: permission denied, no device found, or the device is in use by another app. `name` is the browser's error name.

`localParticipant` is `null` when you are not in the room.

> [accordion] Showing a participant's camera
>
> `videoTrack` is the track object of the chat library (LiveKit). The SDK types it as `unknown`, so cast it. This is a pattern: test it in your page.
>
> ```ts theme={"dark"}
> type CameraTrack = { attach(): HTMLMediaElement; detach(): HTMLMediaElement[] };
>
> function showCamera(tile: HTMLElement, videoTrack: unknown) {
>   tile.replaceChildren();
>   tile.hidden = !videoTrack;          // camera off: hide the tile
>   if (videoTrack) tile.append((videoTrack as CameraTrack).attach());
> }
> ```

> [accordion] Sound from the other participants
>
> Remote audio plays by itself: you do not attach audio elements. Browsers block sound until the viewer interacts with the page, so the SDK starts the audio on the viewer's first click, tap or key press.

> [accordion] What the SDK sets for you
>
> | Setting | Value |
> | - | - |
> | Camera capture on a phone | 320 × 240 at 15 frames per second, at most 250 kbps |
> | Camera capture on other devices | 640 × 480 at 24 frames per second, at most 600 kbps |
> | Reconnecting to the chat server | Handled by the chat connection itself. Your page does not rejoin after a network blip. |
>
> The capture sizes are small on purpose, so that sending a camera does not take bandwidth from the stream.

## Chat the app asks for

Some apps put the viewer into chat themselves, by sending a `comms` message. The SDK does not join by itself: listen for the message and join.

> [!TIP]
>
> **Coming from Epic's Pixel Streaming library?** Its method names work on the stream object too: `emitUIInteraction()`, `emitConsoleCommand()` and `addResponseEventListener()`. They are the same calls as `send()`, `consoleCommand()` and `on('ueMessage')`. Use whichever you know. See [Talk to your Unreal app](https://docs.streampixel.io/resources/web-sdk-v2/messaging.md).

The app sends `{ "message": { "type": "comms", "value": { "roomId": "...", "name": "..." } } }` to join a room, and `"value": "disconnect"` to leave.

```ts ueMessage event theme={"dark"}
import { VoiceChat } from '@streampixel/web-sdk/voice';

let chat: Awaited<ReturnType<typeof VoiceChat.for>> | null = null;

stream.on('ueMessage', async (m) => {
  const msg = typeof m === 'string' && m.trim().startsWith('{') ? JSON.parse(m) : m;
  if (msg?.message?.type !== 'comms') return;
  const value = msg.message.value;
  if (value === 'disconnect') {
    await chat?.leave();
    chat = null;
  } else if (!chat) {
    chat = await VoiceChat.for(stream, { userName: value.name, roomId: value.roomId });
    await chat.join();
  }
});
```

```ts addResponseEventListener theme={"dark"}
import { VoiceChat } from '@streampixel/web-sdk/voice';

let chat: Awaited<ReturnType<typeof VoiceChat.for>> | null = null;

// The listener receives every message from the app, as a string.
stream.addResponseEventListener('comms', async (raw) => {
  const msg = raw.trim().startsWith('{') ? JSON.parse(raw) : null;
  if (msg?.message?.type !== 'comms') return;
  const value = msg.message.value;
  if (value === 'disconnect') {
    await chat?.leave();
    chat = null;
  } else if (!chat) {
    chat = await VoiceChat.for(stream, { userName: value.name, roomId: value.roomId });
    await chat.join();
  }
});
```

## Chat in a shared session

Chat works the same for the host and the viewers of a [shared session](https://docs.streampixel.io/resources/web-sdk-v2/shared-sessions.md). Each page creates its own chat from its own stream.

## Content-Security-Policy

Chat connects to the chat server on LiveKit Cloud. If your site sends a Content-Security-Policy, add this to `connect-src`:

```text theme={"dark"}
connect-src wss://*.livekit.cloud https://*.livekit.cloud;
```

The chat code itself is downloaded from the same two hosts as the stream engine, with the same checks, so `script-src` needs nothing extra. The full list is in [Installation](https://docs.streampixel.io/resources/web-sdk-v2/installation.md#content-security-policy).

## Troubleshooting

> [accordion] VoiceChat.for() rejects: the project has chat disabled
>
> The project's chat is off, so the ticket carried no chat token. Turn chat on in the dashboard, then start a new stream. Check `stream.voiceToken` before you call `VoiceChat.for()`.

> [accordion] VoiceChat.for() rejects with EngineLoadError
>
> The chat code could not be downloaded or verified. It is loaded like the stream engine, in the same version as the stream's engine. See the reasons in [Errors and disconnects](https://docs.streampixel.io/resources/web-sdk-v2/errors-and-disconnects.md#engineloaderror).

> [accordion] join() rejects
>
> The platform refused the chat token, or the chat server could not be reached. Check your Content-Security-Policy first. On a dedicated or on-premises deployment, pass `platformHost` to `VoiceChat.for()`: it is not taken from the stream.

> [accordion] toggleMic(true) resolves to false
>
> The browser did not give the microphone: the viewer refused the prompt, there is no device, or another app is using it. The `deviceError` event says which. `toggleMic()` also resolves to `false` before `join()`.

> [accordion] I hear nobody until I click
>
> Browsers block sound until the viewer interacts with the page. The SDK starts the audio on the first click, tap or key press.

> [accordion] I use the script-tag build
>
> Chat is not in the script-tag build. Install the package with npm and use a bundler.

## Next steps

> [card] [Shared sessions](https://docs.streampixel.io/resources/web-sdk-v2/shared-sessions.md)
>
> One app for many people: the natural place for chat.

> [card] [Talk to your Unreal app](https://docs.streampixel.io/resources/web-sdk-v2/messaging.md)
>
> Messages between your page and the app, such as `comms`.

> [card] [The engine and updates](https://docs.streampixel.io/resources/web-sdk-v2/engine-and-updates.md)
>
> One level up: how the stream engine and the chat code are loaded and verified.

> [card] [Stream API](https://docs.streampixel.io/resources/web-sdk-v2/stream-api.md)
>
> Reference: `voiceToken` and everything else on the stream object.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.