> ## 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.

# Events and states

> The state machine of a Streampixel Web SDK stream: every state and its fields, every event and its payload, StreamStats, and what your page sees during reconnection and recovery.

Advanced For developers who ship a page to production. After this page you can show the right thing for every state a stream can be in, and react to every event it emits.

A stream tells your page what it is doing in two ways:

* **One state at a time.** `stream.state` holds it, and the `state` event fires on every change.
* **Events** for everything else: loading progress, statistics, prompts for the viewer, messages from your application.

## Subscribing

```ts title="Listeners" theme={"dark"}
const off = stream.on('stats', (s) => console.log(s.fps, s.bitrateKbps));
off();                                            // unsubscribe

// @ts-expect-error  'stat' is not an event: a typo does not compile
stream.on('stat', () => {});

// An event added by an engine newer than your installed package (not in its types yet):
stream.onUnknown('someFutureEvent', (payload) => console.log(payload));
```

**stream.on(event, listener)** `() =\> void`

Subscribes. Accepts only the event names on this page. Returns the function that unsubscribes.

**stream.off(event, listener)** `void`

Unsubscribes, by the same function reference.

**stream.onUnknown(event, listener)** `() =\> void`

Subscribes to any name. Use it for an event that a newer engine added and your installed package does not know yet.

Four rules apply to every listener:

1. **Attach listeners straight after `await Streampixel.create(...)`.** The first events fire one moment later. If your code awaits something else first, read `stream.state`, `stream.currentSessionId` and `stream.currentStreamerId` instead.
2. **Any number of listeners can share one event.**
3. **A listener that throws is logged.** It does not stop the stream or the other listeners.
4. **All listeners are removed when the session ends**, after `ended` has fired.

```ts title="Render the state that is already there" highlight={3} theme={"dark"}
const render = (s: StreamState) => setStatus(s.kind);
stream.on('state', render);
render(stream.state); // on a password project create() resolves already in 'awaitingPassword'
```

## States

`stream.state` is an object. Switch on its `kind`.

The usual path is short: `idle`, `connecting`, `streaming`, `ended`. Everything else is a detour that the SDK handles by itself. Your page only has to show it.

### What to show in each state

```ts title="status-text.ts" theme={"dark"}
import type { StreamState } from '@streampixel/web-sdk';

export function statusText(s: StreamState): string {
  switch (s.kind) {
    case 'idle':
    case 'connecting':       return 'Connecting…';
    case 'awaitingPassword': return 'Enter the password';
    case 'queued':           return `In queue: ${s.position}`;
    case 'streaming':        return '';
    case 'awaitingPlay':     return 'Click to start';
    case 'recovering':       return 'Restarting the stream…';
    case 'reconnecting':     return s.waitingForHost ? 'Waiting for the host…' : 'Reconnecting…';
    case 'ended':            return s.message;
    default:                 return ''; // a newer engine may add a kind
  }
}
```

> [!WARNING]
>
> Keep the `default` branch. A newer engine may add a kind, and the engine updates without a new install.

### Every state

**idle** `\{ kind: 'idle' \}`

`create()` has resolved. Connecting starts in a moment. Show your loading screen.

**awaitingPassword** `\{ kind: 'awaitingPassword'; wrong?; locked?; hard?; retryAfterSec? \}`

A password project is waiting for `stream.submitPassword()`. Nothing has started: no ticket, no GPU. See [Access](https://docs.streampixel.io/resources/web-sdk-v2/access.md#password-projects).

**fields**

**wrong** `boolean`

`true`: the last password was refused.

**locked** `boolean`

`true`: too many wrong attempts. The right password is still accepted, so keep the field usable, unless `hard` is also `true`.

**hard** `boolean`

`true`: every attempt is refused for now. Disable the form.

**retryAfterSec** `number`

How many seconds to wait, when the server said.

**connecting** `\{ kind: 'connecting' \}`

Three things happen in this state: signalling (The WebSocket on which the browser and your application agree on the video connection.) opens, the application starts, and the video connection is set up. The [`progress`](#loading) event tells the steps apart.

The stream is also `connecting` after it leaves the queue, while a connection is rebuilt, and while a fresh session starts. In a [Test locally](https://docs.streampixel.io/resources/web-sdk-v2/test-locally.md) session it stays `connecting`, with no time limit, until your Unreal connects.

**queued** `\{ kind: 'queued'; position: number \}`

Waiting for a free GPU. When the application answers, the state goes back to `connecting`.

**fields**

**position** `number`

The place in the queue: a whole number, `0` when the server did not say. The [`queue`](#loading) event fires as it changes.

**streaming** `\{ kind: 'streaming' \}`

The video is playing. Hide your loading screen. Messages and console commands can be sent now.

**awaitingPlay** `\{ kind: 'awaitingPlay'; reason: string \}`

The stream is up, and the browser refused to start playback without a click or tap. Show a "Click to start" control that calls `stream.play()`. A press anywhere on the container also starts it. See [Controls and input](https://docs.streampixel.io/resources/web-sdk-v2/controls-and-input.md#when-the-browser-blocks-autoplay).

**fields**

**reason** `string`

The browser's reason, usually the name of its error, for example `NotAllowedError`. For your logs.

**recovering** `\{ kind: 'recovering'; attempt: number \}`

No video arrived. The [`stalled`](#quality-and-network) event says why. The SDK is starting one fresh session. A viewer of a shared session, and a Test locally session, rejoin the same session instead.

**fields**

**attempt** `number`

`1` for the one fresh session. `1` to `3` for a shared-session viewer or a Test locally session that rejoins.

**reconnecting** `\{ kind: 'reconnecting'; attempt: number; deadlineMs: number; waitingForHost? \}`

The connection dropped and the SDK is restoring it, on the same session.

**fields**

**attempt** `number`

The number of the current try, from `1`.

**deadlineMs** `number`

The time at which the SDK gives up, in milliseconds since the epoch, like `Date.now()`. Use it for a countdown.

**waitingForHost** `boolean`

`true` for a shared-session viewer waiting for the host's application to come back, and for a Test locally session waiting for your Unreal.

**ended** `\{ kind: 'ended'; code: number; reason: string; endKind; message: string \}`

Final. The fields are the same as the payload of the [`ended`](#lifecycle) event. There is no way back from this state: to start again, destroy the stream and create a new one. See [How a session ends](https://docs.streampixel.io/resources/web-sdk-v2/errors-and-disconnects.md#how-a-session-ends).

> [accordion] Three kinds that are in the type and never happen
>
> The `StreamState` type also declares `resolving`, `starting` and `stalled`. They are marked deprecated and are never emitted. They are in the type so that a `switch` written against an earlier 2.0 alpha still compiles. `stalled` is an event; the state it leads to is `recovering`.

## Reconnection and recovery

The SDK restores a broken stream by itself. Your page does nothing except show the state. There are two kinds of repair, and the difference matters to your application.

| | Reconnect | Fresh session |
| - | - | - |
| State | `reconnecting` | `recovering` |
| When | The connection dropped. | No video arrived. |
| The application process | The same. Its state is kept. | A new one. Its state is lost. |
| The `session` event | Does not fire. | Fires again, with new ids. |
| `launchParams` | Not sent again. | Sent again. |
| How often | As often as needed, inside the reconnect window. | Once per stream. |
| Your listeners | Kept. | Kept. |

What your page sees for each thing that can go wrong:

| What happens | States your page sees | If it cannot be repaired |
| - | - | - |
| Signalling drops, or the browser reports that it is offline | `reconnecting`, then `streaming`. The last picture stays on screen while the video path is still alive. The state stays `reconnecting` **until the new video really plays**. | `ended`, code `4007`, `endKind: 'error'`, when the reconnect window runs out. |
| The video path dies while signalling is still up | `reconnecting`, `connecting`, `streaming`. A shared-session viewer: `recovering`, `connecting`, `streaming`. | As above. |
| No video within 60 seconds of the application's offer | `stalled` event, `recovering`, `connecting`, `streaming`. | `ended`, code `4101` (the video connection never came up) or `4102` (connected, no video), `endKind: 'error'`. |
| Connected, and no video frame for 10 seconds. Not judged while the tab is hidden. | `stalled` event, `recovering`, `connecting`, `streaming`. | `ended`, code `4102`, `endKind: 'error'`, after a second stall. |
| The viewer's network allows neither a direct path nor the relay (A server that forwards the video when a direct path is not allowed.) | None: there is nothing to repair. | `ended`, code `4100`, `endKind: 'network-blocked'`, about 8 seconds after the application's offer. A slow network gets up to 30 seconds. |
| Signalling accepted the viewer and then sent no offer and no queue position for 210 seconds | None. | `ended`, code `4104`, `endKind: 'error'`. Not applied while queued, nor to a shared-session viewer. |

| Who | Reconnect window |
| - | - |
| A normal session, and the host of a shared session | 180 seconds |
| A viewer of a shared session, and a Test locally session | 10 minutes |

Tries inside the window wait about 1, 2, 4, 8 and then 15 seconds, each varied by 20 % up or down. When the browser reports that it is back online, the remaining wait is skipped.

> [!NOTE]
>
> A normal session reconnects only after a drop. Any other close from the platform ends the session with the platform's code. Shared sessions do not start a fresh session after a stall: see [Shared sessions](https://docs.streampixel.io/resources/web-sdk-v2/shared-sessions.md).

> [!TIP]
>
> For the mechanism behind each row and every timing, read [Reliability](https://docs.streampixel.io/resources/web-sdk-v2/reliability.md). For a banner with a countdown, see the [cookbook](https://docs.streampixel.io/resources/web-sdk-v2/cookbook.md#a-reconnecting-banner).

## Events

A normal start fires events in this order:

| Step | Event | Payload |
| - | - | - |
| 1 | `session` | The ids of the session. |
| 2 | `state` | `connecting` |
| 3 | `state` and `queue` | Only when no GPU is free: `queued`, with the position, until the application answers. Then `connecting` again. |
| 4 | `progress` | `offer`: the application answered. |
| 5 | `progress` | `answer`, then `connected`. |
| 6 | `state` | `streaming` |
| 7 | `stats` | Every second from now on. |

### Lifecycle

**state** `StreamState`

Fires on every state change. The payload is the new state: see [Every state](#every-state).

**session** `\{ sessionId: string; streamerId: string \}`

A platform session starts. These are the ids shown in your Streampixel analytics, so storing them links a session to your own user.

Fires once per session, again with new ids when the SDK recovers into a fresh session, and not on a reconnect that keeps the session. The same values are on `stream.currentSessionId` and `stream.currentStreamerId`. The event carries no ticket and no password.

```ts theme={"dark"}
stream.on('session', ({ sessionId, streamerId }) => {
  analytics.track('stream_session', { userId: currentUser.id, sessionId, streamerId });
});
```

**ended** `\{ code: number; reason: string; endKind: EndKind; message: string \}`

The session is over. This is the last event: all listeners are removed after it.

**payload**

**message** `string`

A sentence in plain language for the viewer. Show this.

**code** `number`

The end code. `DisconnectCodes` exports the names. See [Errors and disconnects](https://docs.streampixel.io/resources/web-sdk-v2/errors-and-disconnects.md#how-a-session-ends).

**endKind** `'user' | 'afk' | 'server' | 'error' | 'network-blocked'`

Who ended it: your code, the idle rule, the platform, the SDK giving up, or the viewer's network.

**reason** `string`

The server's own text, or the SDK's description. For logs and support.

> [!NOTE]
>
> `stream.destroy()` and `stream.disconnect()` on a live stream also fire `ended`, with code `1000` and `endKind: 'user'`. If your page restarts on `ended`, check `endKind`, or unsubscribe before you destroy.

### Loading

**progress** `\{ stage: 'offer' | 'answer' | 'connected' \}`

Steps inside `connecting`, for a loading screen. It fires again each time a connection is built.

**stages**

**offer** `stage`

The application answered. A GPU is assigned.

**answer** `stage`

The browser's answer went back to the application.

**connected** `stage`

The video connection is up.

Streampixel's share page shows the project's loading texts one, two and three at these three points. They are in `stream.streamConfig` as `loadingTextOne`, `loadingTextTwo` and `loadingTextThree`.

**queue** `\{ position: number; message?: string \}`

The queue position changed. `position` is a whole number, `0` when the server did not say. `message` is the server's own text.

**autoplayBlocked** `\{ reason: string \}`

The browser refused to start playback without a click or tap. The state is `awaitingPlay`. Show a control that calls `stream.play()`.

### Quality and network

**stats** `StreamStats`

Every second while the video is up. The fields are in [`StreamStats`](#streamstats).

**videoEncoderAvgQP** `number`

The encoder's QP (Quantisation parameter: how strongly the encoder compresses the picture. Lower means a better picture.), about once a second, on H.264's scale of 0 to 51 whatever the codec. Lower is a better picture. The same number is `avgQp` in `stats`.

**stalled** `Diagnostics`

No video. Recovery follows: the state becomes `recovering`, or the session ends when recovery was already tried.

**payload**

**verdict** `string`

A one-line explanation, for your logs.

**iceConnectionState, connectionState, iceGatheringState** `string`

The browser's own states of the video connection.

**srflxCandidatesFound, relayCandidatesFound, hostCandidatesFound** `boolean`

Which kinds of network path the browser found: through the public address, through the relay, on the local network.

**candidatePairs, connectedPairs** `number`

How many paths were tried, and how many connected.

The object carries more detail than the type lists. See [Diagnostics](https://docs.streampixel.io/resources/web-sdk-v2/diagnostics.md).

**relayFallback** `\{ transport: 'tcp' | 'tls'; showWarning: boolean \}`

UDP is blocked on the viewer's network, and the stream is relayed over TCP or TLS, at lower quality. `showWarning` is the project's **Show UDP Blocked Warning** setting from the dashboard: show your notice only when it is `true`.

### Prompts for the viewer

**afkWarning** `\{ kind: 'countdown'; secondsRemaining: number; dismiss: () =\> void \} | \{ kind: 'dismissed' \}`

The idle countdown started, counted down, or was cancelled.

**payload**

**kind** `'countdown' | 'dismissed'`

`countdown`: show or update your warning. `dismissed`: hide it.

**secondsRemaining** `number`

Seconds until the session ends. Only with `countdown`.

**dismiss** `() =\> void`

Call it when the viewer says they are still there. `stream.keepAlive()` does the same. Only with `countdown`.

Not raised for a viewer of a shared session, nor in a Test locally session: they have no idle timeout.

**osk** `\{ contents: string \}`

The application asked for text input: one of its text fields got focus. `contents` is the text already in that field. Show a text input and answer with `stream.sendTextboxEntry(text)`. See [Text input on phones](https://docs.streampixel.io/resources/web-sdk-v2/controls-and-input.md#text-input-on-phones).

**oskHide** `no payload`

The application asked to hide the keyboard. Close your text input.

### From your application

> [!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).

**ueMessage** `unknown`

A message from your Unreal application, usually a JSON string. See [Talk to your Unreal app](https://docs.streampixel.io/resources/web-sdk-v2/messaging.md#receive-messages-from-unreal).

**openUrl** `\{ url: string; open: () =\> void \}`

The application sent a plain `https` link for the viewer. `open()` opens it in a new tab. On phones and tablets, call it from a click or tap.

**fileProgress** `\{ received: number; total: number; name: string \}`

A file from the application is arriving. `received` and `total` count pieces, not bytes.

**file** `\{ blob: Blob; name: string; mimeType: string \}`

A file from the application arrived, complete.

**screenshot** `\{ dataUrl: string \}`

The application asked for a screenshot with its `requestScreenshot` message. `dataUrl` is the current frame as a PNG.

### Events with a built-in action

Three events have an action that runs **only when your page has no listener** for them. Add a listener and the action is yours.

| Event | Without a listener: desktop browsers | Without a listener: phones and tablets |
| - | - | - |
| `openUrl` | The link opens in a new tab. | Nothing. These browsers refuse a tab opened outside a tap: add a listener with a button that calls `open()`. |
| `file` | The file is downloaded. | Nothing. Add a listener with a Save button. |
| `screenshot` | The frame is downloaded as `pixelstream_screenshot.png`. | The same. |

With [`@streampixel/ui`](https://docs.streampixel.io/resources/web-sdk-v2/ui-overlays) mounted and its `files` or `links` part on, that package handles those events.

### `StreamStats`

The payload of the `stats` event. Totals count from the start of the current connection, so they begin again after a rebuilt connection.

**fps** `number`

Frames decoded per second.

**latencyMs** `number`

Network round-trip time in milliseconds, as the browser measures it for the connection in use. `0` until the browser has a first reading. When one sample has no reading, the last one is kept.

**bitrateKbps** `number | null`

Received video bitrate, in kilobits per second.

**resolution** `string | null`

The size of the video as received, for example `"1920x1080"`.

**codec** `string | null`

The video codec in use, for example `"H264"` or `"AV1"`.

**avgQp** `number | null`

The latest encoder QP, on the scale of 0 to 51. `null` before the first sample.

**framesDecoded** `number`

Frames decoded, in total.

**framesDropped** `number`

Frames dropped, in total.

**packetsLost** `number`

Video packets lost, in total.

**bytesReceived** `number`

Bytes received, video and audio together, in total.

**relayTransport** `'' | 'udp' | 'tcp' | 'tls'`

The transport of the relay in use. Empty on a direct path.

> [!TIP]
>
> An older engine may not send every field. When you print a value, give it a fallback: `s.packetsLost ?? '—'`.

## Next steps

> [card] [Errors and disconnects](https://docs.streampixel.io/resources/web-sdk-v2/errors-and-disconnects.md)
>
> Every end code, `endKind` and message.

> [card] [Cookbook](https://docs.streampixel.io/resources/web-sdk-v2/cookbook.md)
>
> A loading screen, a queue display and a reconnecting banner built on these states.

> [card] [Reliability](https://docs.streampixel.io/resources/web-sdk-v2/reliability.md)
>
> One level up: the mechanism and timing behind reconnection and recovery.

> [card] [Stream API reference](https://docs.streampixel.io/resources/web-sdk-v2/stream-api.md)
>
> `play()`, `keepAlive()`, `submitPassword()` and every other method.


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