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

# Web SDK FAQ

> Short answers to the questions developers ask about the Streampixel Web SDK: npm or script tag, a black or empty stream, sound, phones, sizing, cleanup, reconnection, pinning the engine, Content-Security-Policy and offline use.

All levels For anyone with a quick question about the Web SDK. Each answer is two or three sentences and links to the page with the detail.

The questions are grouped by where you are: starting, building a page, going to production, or looking under the hood.

## Getting started

Beginner You have a project in the dashboard and want to see it in your own page.

> [accordion] Do I need npm or a build tool?
>
> No. One script tag loads the SDK and defines `window.StreampixelSDK`:
>
> ```html theme={"dark"}
> <script src="https://js.streampixel.io/v2/loader.js"></script>
> ```
>
> The ready-made screens (`@streampixel/ui`) and voice chat are available from npm only. See [Your first stream](https://docs.streampixel.io/resources/web-sdk-v2/first-stream.md) for a page with no build tools, and [Installation](https://docs.streampixel.io/resources/web-sdk-v2/installation.md) for npm.

> [accordion] What do I need before I start?
>
> A project that is switched on and has a build, its project ID (the option is called `appId`), and an element in your page to put the video in. The page must be served over `https` or from `localhost`. See [Your first stream](https://docs.streampixel.io/resources/web-sdk-v2/first-stream.md).

> [accordion] Why is my stream black, or zero pixels tall?
>
> Look at `stream.state.kind` first. `connecting` or `queued` means the stream has not started yet. `awaitingPlay` means the browser blocked autoplay: call `stream.play()` from a click.
>
> If the state is `streaming`, check the container. It must be an element with a width. If it has no height when the stream starts, the SDK gives the video the stream's aspect ratio, but an element you pass to `stream.attach()` needs a height of its own. See [Quick start](https://docs.streampixel.io/resources/web-sdk-v2/quick-start.md).

> [accordion] Why is there no sound?
>
> Every stream starts muted, because browsers require a click or tap before a page may play sound. Call `stream.setMuted(false)` or `stream.toggleAudio()` from a click or tap handler. The control bar of `@streampixel/ui` has a sound button that does this. See [Controls and input](https://docs.streampixel.io/resources/web-sdk-v2/controls-and-input.md).

> [accordion] Does it work on a phone?
>
> Yes. A phone needs a few things a desktop does not: a text field when the app asks for the keyboard (the `osk` event), and a button for links and files the app sends, because a phone refuses to open them outside a tap. `@streampixel/ui` draws these for you.
>
> On phones and tablets, a tab left in the background for 60 seconds ends the session. See [Controls and input](https://docs.streampixel.io/resources/web-sdk-v2/controls-and-input.md).

> [accordion] Why does create() fail on my http\:// page?
>
> The page must be served over `https` or from `localhost`. The SDK checks the signature of the engine it downloads, and browsers offer the tool for that (WebCrypto) only on those addresses. On another address `create()` rejects with `EngineLoadError`, reason `no-webcrypto`. See [Installation](https://docs.streampixel.io/resources/web-sdk-v2/installation.md).

> [accordion] Which browsers can run it?
>
> A browser with WebRTC. Without WebRTC, `create()` rejects with `AuthError` kind `network`. The video codec is agreed with what the browser can decode: a browser without the preferred codec uses the fallback. See [Overview](https://docs.streampixel.io/resources/web-sdk-v2/overview.md).

> [accordion] When do I use the SDK instead of the share link or an iframe?
>
> The share link is Streampixel's own hosted page for a project. The SDK puts the stream inside your own page and gives your code one object with states, events and errors, so you control what the viewer sees around the video. See [Overview](https://docs.streampixel.io/resources/web-sdk-v2/overview.md).

> [accordion] Is the SDK finished?
>
> It is a public beta, version 2.0.0-beta.2. Names and behaviour can still change before the stable 2.0.0 release. The [changelog](https://docs.streampixel.io/resources/web-sdk-v2/changelog.md) lists what changed in each version.

## Building your page

Intermediate You are a web developer building a real page with the SDK.

> [accordion] Do I have to build the loading screen and the other screens myself?
>
> No. The SDK core draws only the video. `mountUI(stream, { container })` from `@streampixel/ui` draws the loading screen, the password form, "Click to start", the idle warning, the text input for phones, a control bar and the end message. You can also switch any of them off and draw your own. See [UI overlays](https://docs.streampixel.io/resources/web-sdk-v2/ui-overlays.md).

> [accordion] How do I size the stream?
>
> Size the container with CSS: give it a width and a height, and the video fills it. How the picture is fitted depends on the resolution mode: `fixed` shows the whole picture with bars, `dynamic` follows the container's size, and `crop` fills the container edge to edge. See [`resolution`](https://docs.streampixel.io/resources/web-sdk-v2/options#video) and [Controls and input](https://docs.streampixel.io/resources/web-sdk-v2/controls-and-input.md).

> [accordion] Why does send() return false?
>
> `false` means the message was not sent: the video is not up yet, the stream is reconnecting, or the session has ended. Nothing is queued. Send the message again once the state is `streaming`. See [Talk to your Unreal app](https://docs.streampixel.io/resources/web-sdk-v2/messaging.md).

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

> [accordion] Why does my console command do nothing?
>
> The app must allow console commands: it must be launched with `-AllowPixelStreamingCommands`. When it does not, `stream.consoleCommand()` returns `false`. See [Launch arguments and startup commands](https://docs.streampixel.io/resources/additional-unreal-engine-features/launch-arguments-and-startup-commands.md).

> [accordion] How do I use it with React or another framework?
>
> Create the stream when the component mounts, pass an `AbortSignal` as the `signal` option, and abort it in the cleanup. Aborting before `create()` resolves starts nothing; aborting afterwards destroys the stream. The same pattern works in any framework with a cleanup step. See [Quick start](https://docs.streampixel.io/resources/web-sdk-v2/quick-start.md).

> [accordion] Does it work with server-side rendering?
>
> Yes. Importing the package touches no browser globals, so it can be imported during server-side rendering. Only `Streampixel.create()` needs a browser: call it in code that runs in the browser. See [Installation](https://docs.streampixel.io/resources/web-sdk-v2/installation.md).

> [accordion] Does it have TypeScript types?
>
> Yes. The package has ESM and CommonJS builds with TypeScript types, and no runtime dependencies. The types are listed under [Package exports](https://docs.streampixel.io/resources/web-sdk-v2/stream-api.md#package-exports).

> [accordion] How do I pass values to my app when it starts?
>
> Set the `launchParams` option, for example `{ unit: 'A-12', lang: 'fr' }`. The SDK sends it to the app once per started app, shortly after the first frame. See [`launchParams`](https://docs.streampixel.io/resources/web-sdk-v2/options#session).

> [accordion] Can I run more than one stream on a page?
>
> Yes, any number. Each one is a session of its own. Call `stream.destroy()` before you start another stream in the same container. See [`destroy()`](https://docs.streampixel.io/resources/web-sdk-v2/stream-api#password-moving-and-ending).

> [accordion] Can I test my page before I upload a build?
>
> Yes. Start a Test locally session in the dashboard, connect Unreal on your own machine to it, and pass the session id as the `dev` option. See [Test locally](https://docs.streampixel.io/resources/web-sdk-v2/test-locally.md).

## Going to production

Advanced Your page works and real viewers are about to use it.

> [accordion] When does a session start, and how do I avoid sessions nobody watches?
>
> `create()` starts the session. On a password project nothing starts, and no GPU is in use, until the password is accepted. `Streampixel.preload()` never starts a session.
>
> A session nobody watches still holds a GPU. Call `create()` when the viewer presses your button, call `stream.destroy()` when they leave, and pass `signal` in React so an unmounted component leaves nothing running. See [Quick start](https://docs.streampixel.io/resources/web-sdk-v2/quick-start.md).

> [accordion] How do I clean up?
>
> Call `stream.destroy()`. It ends the session if it is still live, removes the video and drops every listener, and it is safe to call more than once. If you use `@streampixel/ui`, call `ui.destroy()` first, then `stream.destroy()`. See [`destroy()`](https://docs.streampixel.io/resources/web-sdk-v2/stream-api#password-moving-and-ending).

> [accordion] How do I start again after a session ended?
>
> `ended` is final: a stream that has ended cannot be started again. Call `stream.destroy()`, call `Streampixel.create()` again, and attach your listeners to the new object. See [`destroy()`](https://docs.streampixel.io/resources/web-sdk-v2/stream-api#password-moving-and-ending).

> [accordion] What happens when the viewer's network drops?
>
> The SDK reconnects by itself, and your page only shows the state `reconnecting`. It tries for 180 seconds (10 minutes for a viewer of a shared session). If that fails, the session ends with code `4007`. See [Reconnection and recovery](https://docs.streampixel.io/resources/web-sdk-v2/events-and-states.md#reconnection-and-recovery).

> [accordion] How long can a viewer stay idle?
>
> As long as the project's idle time in the dashboard, or 600 seconds when none is set. The `afk.timeoutSec` option can make it shorter, not longer, and idle detection cannot be switched off. When the viewer is watching without clicking, call `stream.keepAlive()`, or let the app send a heartbeat message. See [`afk`](https://docs.streampixel.io/resources/web-sdk-v2/options#session).

> [accordion] My project has a password or single sign-on. What does my page have to do?
>
> Your page follows the project's access setting in the dashboard. On a password project, `create()` resolves in the state `awaitingPassword`, and `@streampixel/ui` draws the password form. On a single sign-on project, the SDK sends the viewer to the sign-in page and finishes when they come back. "Your app only" is not available yet. See [Access](https://docs.streampixel.io/resources/web-sdk-v2/access.md).

> [accordion] Can my code go above the dashboard's resolution or idle time?
>
> No. 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. See [Dashboard limits](https://docs.streampixel.io/resources/web-sdk-v2/options.md#dashboard-limits).

> [accordion] How do I link a session to my own user?
>
> Listen to the `session` event. It carries `sessionId` and `streamerId`, the same ids your Streampixel analytics show, so storing them next to your user's id links the two. See [Events and states](https://docs.streampixel.io/resources/web-sdk-v2/events-and-states.md).

> [accordion] What do I show the viewer when a session ends?
>
> The `ended` event carries `message`, a sentence in plain language for the viewer. It also carries `code`, `reason` and `endKind` for your logs and for support. See [How a session ends](https://docs.streampixel.io/resources/web-sdk-v2/errors-and-disconnects.md#how-a-session-ends).

> [accordion] What does the SDK report to Streampixel, and can I turn it off?
>
> It reports the session's lifecycle, connection diagnostics and a statistics row about once a minute, to Streampixel's own telemetry service. `telemetry: 'minimal'` reduces that to the lifecycle; there is no "off" value. It never sends passwords, tickets, your `launchParams` or your messages, and it uses no third-party tracker. See [Diagnostics](https://docs.streampixel.io/resources/web-sdk-v2/diagnostics.md).

> [accordion] I have a v1 page. Do I have to rewrite it?
>
> No. `npm install streampixelsdk@next` keeps your v1 code and runs it on the current engine. Either way, your page follows the project's access setting: check it first, so a password or sign-in screen does not surprise your viewers. See [Migrating from v1](https://docs.streampixel.io/resources/web-sdk-v2/migration.md).

## Under the hood

Expert You want to know exactly what the SDK loads, stores and decides.

> [accordion] How do I pin the engine version?
>
> Set `engine: { version: '2.0.0-beta.2' }`. While a version is pinned there are no automatic updates. A version that does not exist rejects with `EngineLoadError`, reason `no-build`. See [`engine`](https://docs.streampixel.io/resources/web-sdk-v2/options#engine).

> [accordion] How do I try the next engine release early?
>
> Set `engine: { channel: 'beta' }`. The default channel is `'stable'`. See [Engine and updates](https://docs.streampixel.io/resources/web-sdk-v2/engine-and-updates.md).

> [accordion] How do I know which engine version is running?
>
> Read `stream.engineVersion`. The engine is downloaded when `create()` runs, so it can be newer or older than the package you installed, whose version is `SDK_VERSION`. See [Engine and updates](https://docs.streampixel.io/resources/web-sdk-v2/engine-and-updates.md).

> [accordion] What must my Content-Security-Policy allow?
>
> The engine script, and the SDK's connections:
>
> ```text theme={"dark"}
> script-src  https://js.streampixel.io https://js-backup.streampixel.io;
> connect-src https://*.streampixel.io wss://*.streampixel.io;
> ```
>
> Voice chat needs two more entries, and a page that enforces Trusted Types must allow the policy `streampixel-sdk`. See [Content-Security-Policy](https://docs.streampixel.io/resources/web-sdk-v2/installation.md#content-security-policy).

> [accordion] Can the SDK work offline, or can I host the engine myself?
>
> No. The engine is not in the npm package. It is always downloaded from two Streampixel hosts that are fixed in the package, and no option changes them. If neither host can deliver a verified engine, `create()` rejects with `EngineLoadError` and no stream starts. See [Engine and updates](https://docs.streampixel.io/resources/web-sdk-v2/engine-and-updates.md).

> [accordion] Can I download the engine before the viewer presses Start?
>
> Yes. `await Streampixel.preload()` downloads and verifies the engine without starting a session. See [`Streampixel.preload()`](https://docs.streampixel.io/resources/web-sdk-v2/stream-api#streampixel-static).

> [accordion] How do I force the stream through the relay?
>
> Set `advanced: { iceTransportPolicy: 'relay' }`, or switch on the project's "force TURN" setting. Without either, the stream uses a direct path when the network allows it, and the relay when it does not. See [`advanced`](https://docs.streampixel.io/resources/web-sdk-v2/options#advanced).

> [accordion] What does the viewer see on a network that blocks the stream?
>
> When the network allows neither a direct path nor the relay, the session ends with code `4100` and `endKind: 'network-blocked'`. When only UDP is blocked, the stream is relayed over TCP or TLS at lower quality, and the `relayFallback` event fires. See [Reliability](https://docs.streampixel.io/resources/web-sdk-v2/reliability.md).

> [accordion] What does the SDK store in the browser?
>
> Three things, and no cookie. In `sessionStorage`, for this tab only: a correct project password (`spx:pw:<projectId>`), and a shared-session host's room id and key (`spx:sfuHost:<projectId>`, `spx:sfuHostKey:<roomId>`). In `localStorage`: the number of the newest engine manifest seen (`spx.sdk.seq`). `rememberPassword: false` turns the first one off.

> [accordion] What do I send to support?
>
> The project ID, the page address, the time of the session, and the `code` and `reason` of the `ended` event. Add `stream.currentSessionId` and the result of `await stream.getDiagnostics()` when you have them. See [Diagnostics](https://docs.streampixel.io/resources/web-sdk-v2/diagnostics.md).

## Next steps

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

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

> [card] [Errors and disconnects](https://docs.streampixel.io/resources/web-sdk-v2/errors-and-disconnects.md)
>
> What each error and end code means.

> [card] [Changelog](https://docs.streampixel.io/resources/web-sdk-v2/changelog.md)
>
> What changed in each version.


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