Getting started
Beginner You have a project in the dashboard and want to see it in your own page.Do I need npm or a build tool?
Do I need npm or a build tool?
window.StreampixelSDK:@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.What do I need before I start?
What do I need before I start?
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.Why is my stream black, or zero pixels tall?
Why is my stream black, or zero pixels tall?
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.Why is there no sound?
Why is there no sound?
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.Does it work on a phone?
Does it work on a phone?
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.Why does create() fail on my http:// page?
Why does create() fail on my http:// page?
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.Which browsers can run it?
Which browsers can run it?
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.Is the SDK finished?
Is the SDK finished?
Building your page
Intermediate You are a web developer building a real page with the SDK.Do I have to build the loading screen and the other screens myself?
Do I have to build the loading screen and the other screens myself?
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.How do I size the stream?
How do I size the stream?
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.Why does send() return false?
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.Can I use the method names of Epic's Pixel Streaming library?
Can I use the method names of Epic's Pixel Streaming library?
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.Why does my console command do nothing?
Why does my console command do nothing?
-AllowPixelStreamingCommands. When it does not, stream.consoleCommand() returns false. See Launch arguments and startup commands.How do I use it with React or another framework?
How do I use it with React or another framework?
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.Does it work with server-side rendering?
Does it work with server-side rendering?
Streampixel.create() needs a browser: call it in code that runs in the browser. See Installation.Does it have TypeScript types?
Does it have TypeScript types?
How do I pass values to my app when it starts?
How do I pass values to my app when it starts?
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.Can I run more than one stream on a page?
Can I run more than one stream on a page?
stream.destroy() before you start another stream in the same container. See destroy().Can I test my page before I upload a build?
Can I test my page before I upload a build?
dev option. See Test locally.Going to production
Advanced Your page works and real viewers are about to use it.When does a session start, and how do I avoid sessions nobody watches?
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.How do I clean up?
How do I clean up?
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().How do I start again after a session ended?
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().What happens when the viewer's network drops?
What happens when the viewer's network drops?
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.How long can a viewer stay idle?
How long can a viewer stay idle?
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.My project has a password or single sign-on. What does my page have to do?
My project has a password or single sign-on. What does my page have to do?
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.Can my code go above the dashboard's resolution or idle time?
Can my code go above the dashboard's resolution or idle time?
How do I link a session to my own user?
How do I link a session to my own user?
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.What do I show the viewer when a session ends?
What do I show the viewer when a session ends?
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.What does the SDK report to Streampixel, and can I turn it off?
What does the SDK report to Streampixel, and can I turn it off?
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.I have a v1 page. Do I have to rewrite it?
I have a v1 page. Do I have to rewrite it?
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.How do I pin the engine version?
How do I pin the engine version?
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.How do I try the next engine release early?
How do I try the next engine release early?
engine: { channel: 'beta' }. The default channel is 'stable'. See Engine and updates.How do I know which engine version is running?
How do I know which engine version is running?
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.What must my Content-Security-Policy allow?
What must my Content-Security-Policy allow?
streampixel-sdk. See Content-Security-Policy.Can the SDK work offline, or can I host the engine myself?
Can the SDK work offline, or can I host the engine myself?
create() rejects with EngineLoadError and no stream starts. See Engine and updates.Can I download the engine before the viewer presses Start?
Can I download the engine before the viewer presses Start?
await Streampixel.preload() downloads and verifies the engine without starting a session. See Streampixel.preload().How do I force the stream through the relay?
How do I force the stream through the relay?
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.What does the viewer see on a network that blocks the stream?
What does the viewer see on a network that blocks the stream?
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.What does the SDK store in the browser?
What does the SDK store in the browser?
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.What do I send to support?
What do I send to support?
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
Streampixel.create().