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

# Options reference

> Every option of Streampixel.create() in the Streampixel Web SDK: its type, its default, what it does, what the dashboard limits, and what create() checks.

All levels For anyone who needs to look up an option of `Streampixel.create()`: every option is here, with its type, its default and what it does.

```ts highlight={2-3} theme={"dark"}
const stream = await Streampixel.create({
  appId: 'YOUR_PROJECT_ID',
  container: document.getElementById('stream')!,
  // everything else is optional
});
```

> [!TIP]
>
> Anything you leave out comes from the project's settings in the dashboard. Set an option only when this page must differ from the dashboard.

## All options at a glance

| Option | What it sets | Section |
| - | - | - |
| `appId`, `container`, `signal`, `telemetry` | Which project, where the video goes, cancelling, reporting | [Basics](#basics) |
| `auth`, `rememberPassword` | How the viewer gets in | [`auth`](#auth) |
| `shared` | One app for a host and viewers | [`shared`](#shared) |
| `dev` | Stream from Unreal on your own machine | [`dev`](#dev-test-locally) |
| `codec`, `resolution`, `bitrate` | The video | [Video](#video) |
| `input`, `media` | Mouse, keyboard, touch, gamepad, microphone, camera | [Input and media](#input-and-media) |
| `launchParams`, `afk` | Values for your app, idle time | [Session](#session) |
| `engine` | Which engine build runs the stream | [`engine`](#engine) |
| `advanced` | Relay, ids, hosts, engine switches | [`advanced`](#advanced) |

In TypeScript the whole object is the type `StreampixelOptions`:

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

const options: StreampixelOptions = { appId: 'YOUR_PROJECT_ID' };
```

## Basics

**appId** `string` *required*

The project ID from the dashboard. You can leave it out only on a page served from the project's own verified [custom domain](https://docs.streampixel.io/resources/dashboard/custom-domains.md): the SDK then finds the project by the page's hostname.

**container** `HTMLElement`

The element the video goes into. It must be an element, not a selector string, and it needs a width. The SDK adds one element of its own to it and puts the `<video>` inside. See [Quick start](https://docs.streampixel.io/resources/web-sdk-v2/quick-start.md) for the sizing rules.

Leave it out to start without a video on the page, and call [`stream.attach(element)`](https://docs.streampixel.io/resources/web-sdk-v2/stream-api#password-moving-and-ending) later.

**signal** `AbortSignal`

Cancels the stream. Aborting before `create()` resolves rejects it with an `AbortError` and leaves nothing running. Aborting later destroys the stream.

Pass the signal of an `AbortController` in a React effect and abort it in the cleanup. Without it, a fast unmount or the double effect of React StrictMode leaves a session streaming in the background.

**telemetry** `'standard' | 'minimal'` (default: 'standard')

What the SDK reports to Streampixel's own telemetry service.

* `'standard'`: the session's lifecycle, WebRTC diagnostics, and a statistics row about once a minute.
* `'minimal'`: the session's lifecycle only.

There is no "off" value, and there are no third-party trackers. See [Diagnostics](https://docs.streampixel.io/resources/web-sdk-v2/diagnostics.md).

> [!NOTE]
>
> The `loading` option of early pre-release builds was removed. Passing it logs a console warning and draws nothing. Use [`@streampixel/ui`](https://docs.streampixel.io/resources/web-sdk-v2/ui-overlays) for the loading screen.

## `auth`

How the viewer gets in. With the default, the SDK follows the project's access setting in the dashboard. Each mode is explained on [Access](https://docs.streampixel.io/resources/web-sdk-v2/access.md).

**auth** `AuthOption` (default: \{ mode: 'auto' })

One object. `mode` chooses the path; the other fields belong to one mode each.

**fields of auth**

**auth.mode** `'auto' | 'password' | 'sso' | 'ticket'` *required*

Which path to use. See the table below.

**auth.password** `string`

With `mode: 'password'`: what the viewer typed into your own form. Required in that mode. Never write a password in your code: page code is public.

**auth.redirect** `'auto' | 'manual'` (default: 'auto')

With `mode: 'sso'`. `'auto'`: the SDK sends the browser to the sign-in page. `'manual'`: `create()` rejects with an `AuthError` of kind `sso-required` that carries `ssoStartUrl`, and your code navigates.

**auth.ticket** `object | string | function`

With `mode: 'ticket'` (not available yet). The whole response of your server's ticket request, as an object or as its JSON text, or a function that asks your server and returns it. The ticket string alone is refused.

A function receives `{ reason, sfu }`. `reason` is `'start'` or `'recovery'`. `sfu` is set for a shared session: forward it in your server's ticket request. The SDK calls the function when the stream is created, and again when it opens a fresh session by itself.

| Value | What `create()` does |
| - | - |
| `{ mode: 'auto' }` | The default. A public project starts. A password project resolves in the state `awaitingPassword` and waits for `stream.submitPassword()`. A single sign-on project sends the browser to the sign-in page. A "Your app only" project (not available yet) rejects with `AuthError` kind `server-ticket-required`. |
| `{ mode: 'password', password }` | Uses the password the viewer typed into your own form. A wrong one does not throw: the stream lands in `awaitingPassword` with `wrong: true`, so the same form can retry with `submitPassword()`. |
| `{ mode: 'sso' }` | On a single sign-on project, the same as `'auto'`. |
| `{ mode: 'sso', redirect: 'manual' }` | The SDK does not navigate. `create()` rejects with `AuthError` kind `sso-required` and `ssoStartUrl`. |
| `{ mode: 'ticket', ticket }` | "Your app only" (not available yet): your server requested the ticket. See [Your app only](https://docs.streampixel.io/resources/web-sdk-v2/access.md#your-app-only). |

**rememberPassword** `boolean` (default: true)

Password projects with `auth` `'auto'`. After a correct password, the SDK keeps it for this browser tab only (`sessionStorage`, per project) and tries it silently on the next `create()`, so a reload does not ask again. `false` turns this off.

Errors that `create()` rejects with are listed on [Errors and disconnects](https://docs.streampixel.io/resources/web-sdk-v2/errors-and-disconnects.md).

## `shared`

**shared** `SharedMode`

A shared session: one app, one host who controls it, and viewers who watch. Leave it out for a private session (the default). See [Shared sessions](https://docs.streampixel.io/resources/web-sdk-v2/shared-sessions.md).

**fields of shared**

**shared.role** `'host' | 'viewer'` *required*

`'host'`: this page owns the session and the input. Give `stream.streamerId` to the viewers. `'viewer'`: this page watches the host's stream and cannot control it.

**shared.hostStreamerId** `string`

Required for a viewer: the host's `stream.streamerId`, unchanged.

```ts theme={"dark"}
// Host
const host = await Streampixel.create({ appId, container, shared: { role: 'host' } });

// Viewer, with the id the host page read from host.streamerId
const viewer = await Streampixel.create({ appId, container, shared: { role: 'viewer', hostStreamerId } });
```

## `dev`: test locally

**dev** `object`

Streams from Unreal on your own machine instead of an uploaded build. For development only: viewers of a released app use the normal options.

**fields of dev**

**dev.sessionId** `string` *required*

The id of a Test locally session from the dashboard: `dev-` followed by six characters (digits and the letters a to f), for example `dev-1a2b3c`.

```ts highlight={4} theme={"dark"}
const stream = await Streampixel.create({
  appId: 'YOUR_PROJECT_ID',
  container,
  dev: { sessionId: 'dev-1a2b3c' }, // from the dashboard's Test Locally tab
});
```

* `appId` is required with `dev`.
* `dev` cannot be combined with `shared` or with `auth: { mode: 'ticket' }`. Both are refused with a `TypeError`.
* An unknown or expired session rejects with `AuthError` kind `dev-session-not-found` or `dev-session-expired`.

How to start a session, how to connect Unreal, and what is different in a dev session are on [Test locally](https://docs.streampixel.io/resources/web-sdk-v2/test-locally.md).

## Video

**codec** `object`

The video codec. Both fields default to the project's [codec settings](https://docs.streampixel.io/resources/quick-start-guide/codec-settings.md).

**fields of codec**

**codec.primary** `'AV1' | 'H264' | 'VP9' | 'VP8'` (default: dashboard)

The preferred codec. The SDK orders the codecs the browser can decode, so a browser without the primary uses the fallback, then its own default. AV1 is used only when the app was built with Unreal Engine above 5.3.

**codec.fallback** `'H264' | 'VP8'` (default: dashboard)

The codec used when the primary is not available.

**resolution** `object`

The size of the stream. All fields default to the project's [resolution settings](https://docs.streampixel.io/resources/quick-start-guide/resolution-settings.md). None of them can go above the project's maximum stream quality: see [Dashboard limits](#dashboard-limits).

**fields of resolution**

**resolution.start** `Resolution` (default: dashboard, else 1080p)

The size the stream starts at.

**resolution.mobileStart** `Resolution` (default: dashboard)

The starting size on phones. Without it, phones use `resolution.start` when you set that, else the dashboard's start resolution for phones.

**resolution.tabletStart** `Resolution` (default: dashboard)

The starting size on tablets. Without it, tablets use `resolution.start` when you set that, else the dashboard's start resolution for tablets.

**resolution.max** `Resolution` (default: dashboard)

The upper limit for `stream.setResolution()`. Without it, the limit is the project's maximum stream quality, or the start resolution when the project has no maximum.

**resolution.mode** `'fixed' | 'dynamic' | 'crop'` (default: dashboard, else 'fixed')

How the stream is sized and fitted.

* `'fixed'`: the start size (or the size last set with `setResolution()`), letterboxed in the container.
* `'dynamic'`: the stream follows the container's size (CSS size × `devicePixelRatio`), never above the start resolution.
* `'crop'`: sized like `'dynamic'`, and the video fills the container edge to edge. What does not fit is cropped.

> [accordion] The Resolution type
>
> `Resolution` is one of these strings, or an object with two numbers:
>
> ```ts theme={"dark"}
> type Resolution =
>   | '480p (854x480)'
>   | '720p (1280x720)'
>   | '1080p (1920x1080)'
>   | '1440p (2560x1440)'
>   | '4K (3840x2160)'
>   | { width: number; height: number };
> ```
>
> In the object form, both numbers must be at least 64. Odd values are rounded down to even ones. A value that is not usable is ignored, with a console warning.

**bitrate** `object`

Limits for the encoder's bitrate, in **kilobits per second**. `{ min: 1_000, max: 20_000 }` is 1 to 20 Mbps. Not set by default.

**fields of bitrate**

**bitrate.min** `number`

The lowest bitrate, in kilobits per second.

**bitrate.max** `number`

The highest bitrate, in kilobits per second.

> [!WARNING]
>
> Bitrate is in kilobits per second, not bits per second. A value above 200,000 logs a console warning, because it looks like bits per second.

## Input and media

**input** `object`

Which input the app receives from the viewer. Each field defaults to the project's dashboard setting.

**fields of input**

**input.mouse** `boolean` (default: dashboard (on))

Mouse input.

**input.keyboard** `boolean` (default: dashboard (on))

Keyboard input. Keys typed into your page's own inputs are never sent to the app.

**input.touch** `boolean` (default: dashboard (on))

Touch input.

**input.hover** `boolean` (default: dashboard (off))

Hover mouse: the app receives mouse movement without a button pressed. Switch it later with `stream.setHoverMouse()`.

**input.gamepad** `boolean` (default: dashboard (off))

Gamepad input.

**input.xr** `boolean` (default: dashboard (off))

WebXR controller input.

**input.fakeMouseWithTouches** `boolean` (default: dashboard (off))

Sends touches to the app as mouse events.

**media** `object`

Sends the viewer's microphone or camera to the app. Each field defaults to the project's dashboard setting.

**fields of media**

**media.mic** `boolean` (default: dashboard)

Allows the viewer's microphone. The browser asks for permission once the video is up. A prompt the viewer ignores never delays the video. Switch the microphone later with `stream.setMicrophone(on)`.

**media.camera** `boolean` (default: dashboard)

Allows the viewer's camera, the same way. Switch it later with `stream.setCamera(on)`.

> [!NOTE]
>
> A viewer of a shared session is watch-only. Mouse, keyboard, touch, gamepad, microphone and camera are off for a viewer, whatever these options say.

How these behave in a page is on [Controls and input](https://docs.streampixel.io/resources/web-sdk-v2/controls-and-input.md).

## Session

**launchParams** `object`

Values for your Unreal app, for example `{ unit: 'A-12', lang: 'fr' }`. The SDK sends them to the app once per started app, as one UI interaction, shortly after the first frame. They are sent again when the SDK recovers into a fresh session, because that is a new app process. A shared-session viewer does not send them.

See [Talk to your Unreal app](https://docs.streampixel.io/resources/web-sdk-v2/messaging.md).

**afk** `object`

The idle time.

**fields of afk**

**afk.timeoutSec** `number` (default: dashboard, else 600)

Seconds without input before the idle countdown starts. It can be shorter than the project's setting, never longer. Not applied to a shared-session viewer or to a `dev` session: they have no idle timeout.

## `engine`

Which engine build runs the stream. The engine is downloaded from Streampixel's servers when `create()` runs. It is never part of your bundle. See [Engine and updates](https://docs.streampixel.io/resources/web-sdk-v2/engine-and-updates.md).

**engine** `EngineOptions` (default: \{ channel: 'stable' })

**fields of engine**

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

`'beta'` runs the next release early, for testing.

**engine.version** `string`

Pins one exact engine version, for example `'2.0.0-beta.2'`. There are no automatic updates while it is pinned. A value that is not a version is refused with a `TypeError`. A version that does not exist rejects with `EngineLoadError`, reason `no-build`.

```ts theme={"dark"}
await Streampixel.create({ appId, container, engine: { channel: 'beta' } });          // the next release, for testing
await Streampixel.create({ appId, container, engine: { version: '2.0.0-beta.2' } });  // one exact build
```

`stream.engineVersion` tells you which engine is running. If the chosen engine cannot be loaded, `create()` rejects with `EngineLoadError`. There is no engine inside the npm package to fall back to.

## `advanced`

For special cases. Leave these unset unless you know you need one, or support asks you to set one.

**advanced** `object`

**fields of advanced**

**advanced.iceTransportPolicy** `'all' | 'relay'`

`'relay'` forces the stream through the TURN relay (a server that forwards the video when a direct path is not allowed). Unset or `'all'`, the project's "force TURN" setting decides.

**advanced.streamerId** `string` (default: generated)

Your own id for this connection: letters, digits, `_` and `-` only. The SDK connects as `<streamerId>_<projectId>`; an id that already ends in `_<projectId>` is used as given. An id you choose is kept when the SDK recovers into a fresh session.

**advanced.ticketInUrl** `boolean` (default: true)

`false` sends the session ticket as the first signalling message instead of in the signalling address. Only for dedicated or on-premises deployments that require it. Not applied to a `dev` session.

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

The platform's address, for dedicated or on-premises deployments. It must be `https` (`http` is accepted on `localhost` only). Voice chat does not read this option: pass the same host to `VoiceChat.for()`.

**advanced.telemetryHost** `string` (default: [https://telemetry.streampixel.io](https://telemetry.streampixel.io))

The telemetry address, for dedicated or on-premises deployments. It must be `https` (`http` is accepted on `localhost` only).

**advanced.flags** `object`

Switches read by the engine, including ones added after you installed the package. Unknown names are ignored. The flags the current engine reads are listed below.

### Flags the engine reads

All four are on by default. Set one to `false` to turn it off.

**advanced.flags.isTouchDevice** `boolean` (default: true)

`false` stops the `{ type: 'isTouchDevice', value, os, device }` message that the SDK sends to the app on every video start. See [Hide / unhide touch controls](https://docs.streampixel.io/resources/additional-unreal-engine-features/hide-unhide-touch-controls.md).

**advanced.flags.startupCommands** `boolean` (default: true)

`false` stops the SDK from running the project's startup console commands. See [Launch arguments and startup commands](https://docs.streampixel.io/resources/additional-unreal-engine-features/launch-arguments-and-startup-commands.md).

**advanced.flags.backgroundDisconnect** `boolean` (default: true)

`false` stops the SDK from ending the session after 60 seconds in the background on phones and tablets.

**advanced.flags.autoEnterVR** `boolean` (default: true)

`false` stops the SDK from entering VR by itself in a headset browser.

```ts theme={"dark"}
await Streampixel.create({
  appId,
  container,
  advanced: { flags: { startupCommands: false, autoEnterVR: false } },
});
```

## Dashboard limits

For the settings that cost GPU time or bandwidth, the dashboard is the upper limit. Your code can ask for less, never more. A value above the limit is lowered to it, with one warning in the browser console.

| Setting | Your code can |
| - | - |
| Codec, resolution mode, input, microphone and camera | change it. |
| `resolution.start`, `mobileStart`, `tabletStart`, `max`, and `setResolution()` | go lower than the project's maximum stream quality, not higher. A project without a maximum is limited to 4K. |
| `afk.timeoutSec` | make the idle time shorter, not longer. Idle detection cannot be switched off from the SDK: an idle session holds a GPU. |
| `bitrate.min`, `bitrate.max` | set them. The platform does not send a project maximum today. When it does, the same rule applies. |

## What `create()` checks

Mistakes in the options are reported before any network call.

| Mistake | Result |
| - | - |
| No options object | `create()` rejects with `TypeError`. |
| An `appId` that is not a project ID | `TypeError`. The message names the option. |
| A `container` that is not an element (a selector string, for example) | `TypeError` |
| `shared.role` other than `'host'` or `'viewer'`; a viewer without a valid `hostStreamerId` | `TypeError` |
| An `advanced.streamerId` with other characters than letters, digits, `_` and `-` | `TypeError` |
| A `dev.sessionId` that is not a dev session id; `dev` with `shared`; `dev` with `auth: { mode: 'ticket' }`; `dev` without `appId` | `TypeError` |
| An unknown codec | `TypeError` |
| An `auth.mode` other than `'auto'`, `'password'`, `'sso'`, `'ticket'`; `auth.mode: 'password'` without a password | `TypeError` |
| An `advanced.platformHost` or `advanced.telemetryHost` that is not `https` (`http` is accepted on `localhost` only) | `TypeError` |
| An `engine.version` that is not a version | `TypeError` |
| `projectId` instead of `appId` | Accepted as `appId`, with a console warning. |
| An option name the SDK does not know | Ignored, with a console warning. |
| `loading` (removed) | Ignored, with a console warning. |

## Next steps

> [card] [Stream methods and properties](https://docs.streampixel.io/resources/web-sdk-v2/stream-api.md)
>
> Everything on the object that `create()` returns.

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

> [card] [Engine and updates](https://docs.streampixel.io/resources/web-sdk-v2/engine-and-updates.md)
>
> How the engine is loaded, verified and pinned.

> [card] [FAQ](https://docs.streampixel.io/resources/web-sdk-v2/faq.md)
>
> Short answers to common questions.


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