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

# Stream methods and properties

> Reference for the Streampixel Web SDK: Streampixel.create(), Streampixel.preload(), and every method and property of the stream object, with Epic's Pixel Streaming names next to the SDK's own.

All levels For anyone who needs to look up a call: `Streampixel.create()`, `Streampixel.preload()`, and every method and property of the stream object that `create()` returns.

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

const stream = await Streampixel.create({ appId: 'YOUR_PROJECT_ID', container });
// `stream` is the object this page describes
```

## All members at a glance

| Group | Members |
| - | - |
| [Static](#streampixel-static) | `Streampixel.create()`, `Streampixel.preload()` |
| [Events](#events) | `on()`, `off()`, `onUnknown()` |
| [Talking to your Unreal app](#talking-to-your-unreal-app) | `send()` / `emitUIInteraction()`, `consoleCommand()` / `emitConsoleCommand()`, `addResponseEventListener()`, `removeResponseEventListener()`, `sendTextboxEntry()` |
| [Audio and playback](#audio-and-playback) | `play()`, `muted`, `setMuted()`, `toggleAudio()` |
| [Resolution and input](#resolution-and-input) | `setResolution()`, `allowedResolutions`, `setHoverMouse()`, `toggleXR()`, `keepAlive()` |
| [Microphone and camera](#microphone-and-camera) | `setMicrophone()`, `setCamera()` |
| [Screenshots and diagnostics](#screenshots-and-diagnostics) | `captureScreenshot()`, `getDiagnostics()` |
| [Identity and configuration](#identity-and-configuration) | `state`, `projectId`, `streamerId`, `currentStreamerId`, `currentSessionId`, `streamConfig`, `voiceToken`, `engineVersion`, `engineSource` |
| [Password, moving and ending](#password-moving-and-ending) | `submitPassword()`, `attach()`, `disconnect()`, `destroy()` |
| [Pixel Streaming object and events](#pixel-streaming-object-and-events) | `pixelStreaming`, `addEventListener()`, `removeEventListener()` |

## `Streampixel` (static)

**Streampixel.create(options)** `Promise\<Streampixel\>`

Starts a stream. It downloads and verifies the engine, looks the project up, asks the platform for a session ticket, and resolves with the stream object. Connecting starts one moment later, so listeners you attach right after `await` see every state and event.

**parameters**

**options** `StreampixelOptions` *required*

See [Options](https://docs.streampixel.io/resources/web-sdk-v2/options.md). Only `appId` is needed.

**rejects with**

**AuthError** `Error`

The platform refused, could not be reached, or answered something unusable. `kind` says which. Also thrown outside a browser with WebRTC (`kind: 'network'`).

**EngineLoadError** `Error`

The engine could not be loaded. `reason` says why.

**TypeError** `Error`

An option is wrong. The message names it. See [What `create()` checks](https://docs.streampixel.io/resources/web-sdk-v2/options#what-create-checks).

**AbortError** `DOMException`

You aborted the `signal` option. Nothing started.

Every error kind and reason is listed on [Errors and disconnects](https://docs.streampixel.io/resources/web-sdk-v2/errors-and-disconnects.md).

**Streampixel.preload(engine?)** `Promise\<\{ source, version \}\>`

Optional warm-up. It downloads and verifies the engine without starting a session, for example before the viewer presses Start. A later `create()` with the same values does not download it again.

**parameters**

**engine.channel** `'stable' | 'beta'` (default: 'stable')

The same as the [`engine.channel`](https://docs.streampixel.io/resources/web-sdk-v2/options#engine) option.

**engine.version** `string`

The same as the [`engine.version`](https://docs.streampixel.io/resources/web-sdk-v2/options#engine) option.

**engine.appId** `string`

The project ID you will pass to `create()`.

**resolves with**

**source** `'cdn'`

How the engine was loaded. Always `'cdn'` in the published package.

**version** `string`

The engine's version, for example `'2.0.0-beta.2'`.

Rejects with `EngineLoadError` when the engine cannot be loaded.

```ts theme={"dark"}
const { source, version } = await Streampixel.preload({ appId: 'YOUR_PROJECT_ID' });
console.log(source, version); // 'cdn' and the engine version
```

## Events

The stream object emits typed events. Every event and its payload is listed on [Events and states](https://docs.streampixel.io/resources/web-sdk-v2/events-and-states.md).

**on(event, fn)** `() =\> void`

Subscribes `fn` to an event. Returns the function that unsubscribes. In TypeScript, an event name that does not exist does not compile.

The event names are `state`, `session`, `progress`, `queue`, `stats`, `videoEncoderAvgQP`, `stalled`, `relayFallback`, `autoplayBlocked`, `afkWarning`, `osk`, `oskHide`, `ueMessage`, `openUrl`, `fileProgress`, `file`, `screenshot` and `ended`.

**off(event, fn)** `void`

Unsubscribes `fn`, by reference.

**onUnknown(event, fn)** `() =\> void`

Subscribes to an event by any name. Use it for an event added by an engine that is newer than your installed package, and so not in its types yet. Returns the function that unsubscribes.

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

> [!NOTE]
>
> A listener that throws is logged to the console and does not affect the stream or other listeners. All listeners are removed when the session ends, after `ended` has fired.

## Talking to your Unreal app

The stream object has two sets of names for messages: the SDK's own, and the names of Epic's Pixel Streaming library. They are the same calls. Use whichever you know.

| The SDK's name | Epic's name | What it does |
| - | - | - |
| `stream.send(payload)` | `stream.emitUIInteraction(payload)` | Sends an object or a string to the app. |
| `stream.consoleCommand(cmd)` | `stream.emitConsoleCommand(cmd)` | Sends a console command to the app. |
| `stream.on('ueMessage', fn)` | `stream.addResponseEventListener(name, fn)` | Receives messages from the app. |
| the function `on()` returned, or `stream.off('ueMessage', fn)` | `stream.removeResponseEventListener(name)` | Stops receiving. |

How to use them, with examples on the Unreal side, is on [Talk to your Unreal app](https://docs.streampixel.io/resources/web-sdk-v2/messaging.md). That page also explains why the SDK has names of its own.

```ts theme={"dark"}
// These two lines do the same thing.
stream.send({ action: 'teleport', to: 'lobby' });
stream.emitUIInteraction({ action: 'teleport', to: 'lobby' });
```

**send(payload) / emitUIInteraction(payload)** `boolean`

Sends a message to the app. The Unreal side receives it as a Pixel Streaming UI interaction. See [JSON messaging](https://docs.streampixel.io/resources/json-message-communication/overview.md).

Returns `true` when the message was handed to the stream. Returns `false` when it was **not sent**: before the video is up, while reconnecting, and after the end. Nothing is queued: send it again once the state is `streaming`.

**parameters**

**payload** `object | string` *required*

The message.

**consoleCommand(cmd) / emitConsoleCommand(cmd)** `boolean`

Sends a console command to the app. Returns `false` when it was not sent: in the same cases as `send()`, and when the app does not allow console commands. The app must be launched with `-AllowPixelStreamingCommands`.

**parameters**

**cmd** `string` *required*

The command, for example `'stat fps'`.

**addResponseEventListener(name, fn)** `void`

Receives every message from the app, the same messages as `on('ueMessage', fn)`. `fn` always gets the message as a string. An `on('ueMessage')` listener gets it as the app sent it, which is usually a JSON string.

**parameters**

**name** `string` *required*

A name for this listener, for example `'handle_responses'`. A second listener with the same name replaces the first.

**fn** `(response: string) =\> void` *required*

Called with each message.

**removeResponseEventListener(name)** `void`

Removes the listener that was added under `name`.

**sendTextboxEntry(text)** `void`

Answers an `osk` event with the text the viewer typed. The `osk` event fires when the app asks for the on-screen keyboard, for example on a phone.

> [accordion] Send as soon as the stream is ready
>
> Nothing is queued, so a message sent too early is lost. This helper sends at once when it can, and otherwise waits for the state `streaming`:
>
> ```ts theme={"dark"}
> function sendWhenStreaming(payload: object) {
>   if (stream.send(payload)) return;
>   const off = stream.on('state', (s) => {
>     if (s.kind === 'streaming' && stream.send(payload)) off();
>   });
> }
> ```

### Messages the SDK acts on

Some messages from your app trigger built-in behaviour, the same as on the share page. They still reach your listeners.

| Message from the app | What the SDK does |
| - | - |
| `{ "message": { "type": "heartbeat" } }` | Cancels a running idle countdown. Send it during cutscenes or other passive content. |
| `{ "type": "togglehoveringmouse", "value": true }` | Switches hover mouse on or off. |
| `requestScreenshot` (bare, or as `{ "message": "requestScreenshot" }`) | Captures the frame: the `screenshot` event fires, or the frame is downloaded when nobody listens. |
| A plain `https://` link | The `openUrl` event fires, or a desktop browser opens the link when nobody listens. |

### Messages the SDK sends to your app

A shared-session viewer sends none of these, because one app serves the whole room.

| Message | When |
| - | - |
| `{ type: 'isTouchDevice', value, os, device }` | On every video start, so the app can show or hide touch controls. See [Hide / unhide touch controls](https://docs.streampixel.io/resources/additional-unreal-engine-features/hide-unhide-touch-controls.md). |
| The project's startup commands from the dashboard | As console commands, after the first frame. See [Launch arguments and startup commands](https://docs.streampixel.io/resources/additional-unreal-engine-features/launch-arguments-and-startup-commands.md). |
| `launchParams`, if you set the option | Once per started app, as one UI interaction, shortly after the first frame. |

You can turn the first two off with [`advanced.flags`](https://docs.streampixel.io/resources/web-sdk-v2/options#advanced).

## Audio and playback

**play()** `void`

Starts playback when the browser blocked autoplay (the state is `awaitingPlay`). Call it from a click or tap handler. A press anywhere on the container also starts playback.

**muted** `boolean`

Read-only. Whether the sound is muted. Streams start muted: browsers require a user gesture before sound.

**setMuted(muted)** `boolean`

Mutes or unmutes. Returns the muted state now in effect. Before the video exists it returns `true`.

**parameters**

**muted** `boolean` *required*

`true` to mute, `false` to unmute.

**toggleAudio()** `boolean`

Flips mute. Returns `true` when the sound is now on.

```ts theme={"dark"}
soundButton.onclick = () => {
  const audible = stream.toggleAudio();
  soundButton.textContent = audible ? 'Mute' : 'Unmute';
};
```

## Resolution and input

**setResolution(width, height)** `\{ width, height \} | null`

Asks the app to render at this size. The size is lowered to the maximum (the [`resolution.max`](https://docs.streampixel.io/resources/web-sdk-v2/options#video) option, never above the project's maximum stream quality), keeping the aspect ratio, and rounded to even numbers. It needs no console-command permission on the app.

Returns the size that was sent, or `null` when **nothing was sent**: numbers under 64, no stream up yet, after the end, and always for a shared-session viewer (the size is the host's).

* A size asked for before the stream is up is remembered. It is applied when the stream starts, and after every reconnect.
* In `dynamic` and `crop` modes the size is the new upper limit. The stream is fitted to the container under it.

**parameters**

**width** `number` *required*

Width in pixels, at least 64.

**height** `number` *required*

Height in pixels, at least 64.

**allowedResolutions** `string[]`

Read-only. The project's sizes up to its maximum stream quality, for a picker: `'360p (640x360)'`, `'480p (854x480)'`, `'720p (1280x720)'`, `'1080p (1920x1080)'`, `'1440p (2560x1440)'`, `'4K (3840x2160)'`.

**setHoverMouse(enabled)** `void`

Switches hover mouse on or off. With hover mouse on, the app receives mouse movement without a button pressed.

**toggleXR()** `void`

Enters or leaves the WebXR session in a headset browser. It does nothing in a browser without immersive VR.

**keepAlive()** `void`

Tells the SDK that the viewer is still there. It restarts the idle timer, and cancels the countdown when one is showing.

```ts theme={"dark"}
const sent = stream.setResolution(1920, 1080);
if (sent) console.log(`asked for ${sent.width}x${sent.height}`);
```

Keys typed into your page's own `<input>`, `<textarea>`, `<select>` and editable elements are not sent to the app. How input, sound and resolution behave in a page is on [Controls and input](https://docs.streampixel.io/resources/web-sdk-v2/controls-and-input.md).

## Microphone and camera

**setMicrophone(on)** `Promise\<boolean\>`

Turns the viewer's microphone on or off while the stream is up. Resolves to whether the microphone is now live.

**parameters**

**on** `boolean` *required*

`true` to switch it on, `false` to switch it off.

**setCamera(on)** `Promise\<boolean\>`

The same for the viewer's camera.

* The microphone or camera must be allowed when the stream starts: the [`media`](https://docs.streampixel.io/resources/web-sdk-v2/options#input-and-media) option, or the project's dashboard setting. Without that, the call resolves `false` and nothing is captured.
* The first call may show the browser's permission prompt. Call it from a click or tap.
* A shared-session viewer always gets `false`.

```ts theme={"dark"}
const stream = await Streampixel.create({ appId: 'YOUR_PROJECT_ID', container, media: { mic: true } });

micButton.onclick = async () => {
  const live = await stream.setMicrophone(true); // false switches it off again
  console.log('microphone live:', live);
};
```

## Screenshots and diagnostics

**captureScreenshot()** `string | null`

A PNG data URL of the current frame. `null` before the first frame.

**getDiagnostics()** `Promise\<DiagnosticsSnapshot | null\>`

A snapshot of the video connection, for support requests. `null` when there is no connection. The network addresses in it are not shortened. See [Diagnostics](https://docs.streampixel.io/resources/web-sdk-v2/diagnostics.md).

**main fields of the snapshot**

**verdict** `string`

One sentence that says what the connection looks like, for example a direct connection, a relayed one, or a network that blocks the stream.

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

The browser's own states of the video connection.

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

Which kinds of network path the browser found.

**candidatePairs, connectedPairs, failedPairs** `number`

How many paths were tried, how many work, how many failed.

**connectionType** `string`

The kind of path in use: `'TURN'` for the relay, otherwise the path's type.

**selectedServer** `string`

Address and port of the path in use.

**issues** `string[]`

Problems the SDK recognised, when there are any: `ICE_FAILED`, `ICE_DISCONNECTED`, `PEER_CONNECTION_FAILED`, `NO_TURN`, `NO_CANDIDATES`, `ALL_CANDIDATE_PAIRS_FAILED`, `ICE_CHECKING_TIMEOUT`.

**likelyCause** `string`

Set together with `issues`: `TURN_SERVER_ISSUE`, `NETWORK_FIREWALL_ISSUE`, `SIGNALLING_SERVER_ISSUE` or `UNKNOWN_ISSUE`.

**timeSinceStart** `number`

Milliseconds since the stream object was created.

**statsAvailable** `boolean`

Whether the browser returned statistics for this snapshot.

**localCandidates, remoteCandidates, candidatePairsDetails, turnServerUrls, transport, inboundRtp, selectedTurn** `object`

The raw details behind the fields above.

```ts theme={"dark"}
const snapshot = await stream.getDiagnostics();
if (snapshot) console.log(snapshot.verdict, snapshot.issues ?? []);
```

## Identity and configuration

All of these are read-only.

**state** `StreamState`

The current state. Switch on `state.kind`. See [Events and states](https://docs.streampixel.io/resources/web-sdk-v2/events-and-states.md).

**projectId** `string`

The project ID the platform resolved. It is the same as `appId`, or the project found for the page's custom domain.

**streamerId** `string`

The streamer ID of this connection. The host of a shared session gives it to viewers. It changes when the SDK recovers into a fresh session. In a `dev` session it is the dev session id.

**currentStreamerId** `string`

The same value as `streamerId`, under a second name.

**currentSessionId** `string`

The platform's session ID of the session that is up. It changes when the SDK recovers into a fresh session. The `session` event announces each new pair of ids.

**streamConfig** `StreamServerConfig`

The project's stream settings for this session, branding included, for your own loading screen or overlays. Before a password is accepted it holds the branding only.

**branding fields**

**customLogo** `string`

The project's logo.

**loadingBannerUrl** `string`

The project's loading banner.

**loadingTextOne, loadingTextTwo, loadingTextThree** `string`

The project's three loading texts.

**logoPosition, loadingType, chatTheme** `string`

The dashboard's settings for the logo position, the loading type and the chat theme.

> [accordion] All fields of StreamServerConfig
>
> The field names are the platform's own, letter for letter. A field is absent when the platform did not send it, and a newer platform may send more.
>
> ```ts expandable theme={"dark"}
> interface StreamServerConfig {
>   status: boolean;
>   ready: boolean;
>   region?: string;
>   signallingHost?: string;
>   primaryCodec?: Codec;
>   fallbaCodec?: Codec;
>   unrealVersion?: number | null;   // the Unreal Engine version of the build
>   resolutionMode?: string;
>   maxStreamQuality?: string;       // for example "1080p (1920x1080)"
>   startResolution?: string;
>   startResolutionTab?: string;
>   startResolutionMobile?: string;
>   resolution?: boolean;
>   afktimeout?: number;
>   maxBitrate?: number;             // in Mbps; not sent by the platform today
>   minBitrate?: number;
>   forceTurn?: boolean;
>   showUdpBlockedWarning?: boolean; // the dashboard's "UDP blocked warning" setting
>   touchInput?: boolean;
>   mouseInput?: boolean;
>   gamepadInput?: boolean;
>   hoverMouse?: boolean;
>   xrInput?: boolean;
>   keyBoardInput?: boolean;
>   fakeMouseTouch?: boolean;
>   showMic?: boolean;
>   showCamera?: boolean;
>   voiceChat?: boolean;
>   textChat?: boolean;
>   videoChat?: boolean;
>   startChat?: string;
>   chatPosition?: string;
>   // branding
>   customLogo?: string;
>   logoPosition?: string;
>   loadingType?: string;
>   loadingBannerUrl?: string;
>   loadingTextOne?: string;
>   loadingTextTwo?: string;
>   loadingTextThree?: string;
>   chatTheme?: string;
>   [key: string]: unknown;
> }
> ```

**voiceToken** `string | undefined`

Present only when the project has chat switched on. Used by [voice chat](https://docs.streampixel.io/resources/web-sdk-v2/voice-chat.md).

**engineVersion** `string`

The version of the engine running this stream. It can be newer or older than the package you installed.

**engineSource** `'cdn'`

How the engine was loaded. Always `'cdn'` in the published package.

```ts theme={"dark"}
stream.on('session', ({ sessionId, streamerId }) => {
  // the same values as stream.currentSessionId and stream.currentStreamerId
  console.log(sessionId, streamerId, stream.engineVersion);
});
```

## Password, moving and ending

**submitPassword(password)** `Promise\<void\>`

Answers the `awaitingPassword` state with what the viewer typed. See [Access](https://docs.streampixel.io/resources/web-sdk-v2/access.md).

* A right password: the stream starts.
* A wrong password, or too many attempts: the promise **resolves**, and the state is `awaitingPassword` again with `wrong`, or with `locked` and `retryAfterSec`.
* A network error, or a project that went offline: the promise rejects with `AuthError`. The state stays `awaitingPassword`.
* Called in any other state, or while a check is running: it rejects with `Error`. An empty password rejects with `TypeError`.

**attach(element)** `void`

Moves the video into another element. Use it when you created the stream without a `container`. The element needs a height of its own. In `dynamic` and `crop` modes the stream is then sized to that element.

**disconnect()** `void`

Ends the session on purpose and removes the video. It never reconnects. `ended` fires with code `1000` and `endKind: 'user'`.

**destroy()** `void`

Does what `disconnect()` does if the session is still live, and then drops every listener. It is safe to call more than once. Call it before you create another stream in the same container, and when your component unmounts.

> [!WARNING]
>
> `destroy()` on a live stream fires `ended` (code `1000`, `endKind: 'user'`) before it drops the listeners. If your code restarts the stream on `ended`, check `endKind` first, or unsubscribe before you destroy.

A stream that has ended cannot be started again: there is no `connect()` or `reconnect()`. Destroy it and call `create()` again:

```ts theme={"dark"}
let stream = await Streampixel.create({ appId: 'YOUR_PROJECT_ID', container });

async function startAgain() {
  stream.destroy();
  stream = await Streampixel.create({ appId: 'YOUR_PROJECT_ID', container });
}
```

## Pixel Streaming object and events

For code written against Epic's Pixel Streaming library: Epic's own object, and Epic's events by their original names.

**pixelStreaming** `object | null`

Read-only. Epic's own `PixelStreaming` object for this connection. `null` when there is no connection.

The SDK replaces this object when it rebuilds the connection. Read it each time you use it, and do not keep a reference to it. Do not call its `reconnect()`, `unmuteMicrophone()` or `unmuteCamera()`: the SDK owns reconnection and capture.

**addEventListener(name, fn)** `void`

Subscribes to one of Epic's events by its original name, for example `webRtcConnected`, `playStream`, `afkWarningActivate` or `statsReceived`. The SDK attaches your listener again each time it rebuilds the connection.

**removeEventListener(name, fn)** `void`

Removes a listener added with `addEventListener()`.

```ts theme={"dark"}
stream.addEventListener('playStream', () => console.log('playing'));
```

> [!NOTE]
>
> Through `addEventListener()`, Epic's `webRtcDisconnected` event fires on every signalling drop, including the ones the SDK recovers from by itself. To show a "Disconnected" message, use the `state` and `ended` events instead.

## Tabs in the background

* When the tab is hidden or loses focus, held keys and mouse buttons are released, so nothing stays stuck in the app.
* On phones and tablets, a tab left in the background for **60 seconds** ends the session (`endKind: 'afk'`), so a forgotten phone does not hold a GPU until the idle timeout. Turn this off with [`advanced.flags.backgroundDisconnect: false`](https://docs.streampixel.io/resources/web-sdk-v2/options#advanced).

## Package exports

What `@streampixel/web-sdk` exports besides the stream object:

| Export | What it is |
| - | - |
| `Streampixel` | The object with `create()` and `preload()`. As a TypeScript type, it is the stream object: `let stream: Streampixel`. |
| `AuthError` | The error class for a refused or failed start. Fields: `kind`, `message`, `status`, and where they apply `ssoStartUrl`, `ssoErrorCode`, `retryAfterSec`, `hard`, `branding`. |
| `EngineLoadError` | The error class for an engine that could not be loaded. Field: `reason`. |
| `DisconnectCodes` | The names of the end codes, for example `DisconnectCodes.NETWORK_BLOCKED`. |
| `SDK_VERSION` | The version of the installed package. |
| Types | `StreampixelOptions`, `StreampixelEvents`, `StreamState`, `StreamStats`, `EndedEvent`, `EndKind`, `AfkWarning`, `AuthOption`, `SharedMode`, `EngineOptions`, `Codec`, `Resolution`, `Diagnostics`, `DiagnosticsSnapshot`, `StreamServerConfig`, `TicketResponse`, `AccessDescriptor`. |

The script-tag build puts the same values on `window.StreampixelSDK`: `Streampixel`, `AuthError`, `EngineLoadError`, `DisconnectCodes` and `SDK_VERSION`. Voice chat is a separate entry, `@streampixel/web-sdk/voice`: see [Voice chat](https://docs.streampixel.io/resources/web-sdk-v2/voice-chat.md).

## Next steps

> [card] [Options](https://docs.streampixel.io/resources/web-sdk-v2/options.md)
>
> Every option of `Streampixel.create()`.

> [card] [Events and states](https://docs.streampixel.io/resources/web-sdk-v2/events-and-states.md)
>
> Every state and every event, with its payload.

> [card] [Talk to your Unreal app](https://docs.streampixel.io/resources/web-sdk-v2/messaging.md)
>
> Sending and receiving messages, with examples.

> [card] [Errors and disconnects](https://docs.streampixel.io/resources/web-sdk-v2/errors-and-disconnects.md)
>
> What `create()` rejects with, and every end code.


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