Skip to main content
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.
No. One script tag loads the SDK and defines window.StreampixelSDK:
The ready-made screens (@streampixel/ui) and voice chat are available from npm only. See Your first stream for a page with no build tools, and Installation for npm.
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.
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.
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.
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.
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.
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.
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 lists what changed in each version.

Building your page

Intermediate You are a web developer building a real page with the SDK.
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.
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 and Controls and input.
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.
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.
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.
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.
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.
Yes. The package has ESM and CommonJS builds with TypeScript types, and no runtime dependencies. The types are listed under Package exports.
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.
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().
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.

Going to production

Advanced Your page works and real viewers are about to use it.
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.
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().
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().
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.
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.
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.
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.
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.
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.
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.

Under the hood

Expert You want to know exactly what the SDK loads, stores and decides.
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.
Set engine: { channel: 'beta' }. The default channel is 'stable'. See Engine and updates.
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.
The engine script, and the SDK’s connections:
Voice chat needs two more entries, and a page that enforces Trusted Types must allow the policy streampixel-sdk. See Content-Security-Policy.
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.
Yes. await Streampixel.preload() downloads and verifies the engine without starting a session. See Streampixel.preload().
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.
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.
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.
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.

Next steps

Options

Every option of Streampixel.create().

Stream methods and properties

Everything on the stream object.

Errors and disconnects

What each error and end code means.

Changelog

What changed in each version.