create() and the first picture.
No code is needed to read this page. If you have not run a stream yet, start with Your first stream.
The parts
Your Unreal app does not run in the browser. It runs on a server with a , and the browser shows a live video of it. The viewer’s mouse, keyboard and touch input travel the other way.
Once the connection is open, video and sound go from your app to the browser, and input and your messages go from the browser to your app. They take a direct path when the network allows one. Otherwise they go through a .
The SDK is a loader and an engine
The SDK comes in two pieces. This is the one design choice that affects how you install and update it.
What this means for you:
- Fixes reach your site without a new install or deploy. Streampixel releases a new engine, and your page downloads it the next time it starts a stream (unless you pinned one engine version).
- The engine is checked before it runs. The list of engine builds is signed, and the loader verifies the signature with keys built into the package. The engine file must match the hash in that signed list.
- There is no copy of the engine in the package. If the engine cannot be downloaded and verified,
create()rejects withEngineLoadErrorand no stream starts. - Two version numbers exist.
SDK_VERSIONis the package you installed.stream.engineVersionis the engine that runs.
The engine and its updates
Channels, pinning a version, how the engine is verified, and what an update can change.
What a session is
A session is one run of your app for one viewer. Your page starts one withcreate(), and it is over when the state is ended.
From create() to the first picture
This is what happens when your page calls Streampixel.create(), with what your code sees at each step:
1
The engine is downloaded and verified
Your code sees nothing yet:
create() has not resolved. If this fails, create() rejects with EngineLoadError.2
The project is looked up
Steps 4 and 5. The platform says whether the project is online and how viewers get in: public, password, or single sign-on. A project that is switched off or has no active build stops here:
create() rejects with AuthError, kind project-offline.3
The ticket is requested
Steps 6 and 7. The answer also carries the project’s stream settings from the dashboard: codec, resolution, input, idle time.A password-protected project pauses before this step.
create() resolves with the stream in the state awaitingPassword, and the ticket is requested when your page calls submitPassword(). Nothing has started until then, and no GPU is in use. See Access.4
create() resolves
Step 8. Your code has the
stream object, in the state idle. Connecting starts one moment later, so listeners that you attach right after await Streampixel.create(...) see everything that follows.5
The SDK connects to signalling
Step 9. The state is
connecting. Streampixel starts your app on a GPU server. If no GPU is free, the state becomes queued (step 10).6
Your app and the browser agree on the connection
Steps 11 to 14. Your app sends an offer, and the browser sends an answer back. The
progress event fires with offer, then answer. The offer also means a GPU is assigned: a queued viewer goes back to connecting.7
The video connection opens
Step 15. The
progress event fires with connected.8
The first picture plays
Step 16. The state is
streaming. If the browser refuses to start the video without a click, the state is awaitingPlay until the viewer clicks: call stream.play() from a button, or let the viewer click the video.Streams start muted, because browsers want a click before they play sound. Your page turns the sound on with
stream.toggleAudio() or stream.setMuted(false), from a click. See Controls and input.The states in short
A stream is always in one state. Your page reads it fromstream.state, and the state event fires on every change. The complete list, with every field, is in Events and states. The usual path:
One more state exists for recovery:
recovering. The state is also connecting again while a connection is rebuilt. Any state can lead to ended.
The queue
A session needs a GPU. When none is free, the viewer waits.- The state is
queued, with aposition. Thequeueevent fires when the position changes. positionis a whole number. It is0when the server did not say.- The viewer leaves the queue when your app answers: the state goes back to
connecting, thenstreaming. - Your page only has to show it. With
@streampixel/uithe loading screen shows the position. For your own display, see the Cookbook.
When the connection drops
A short network problem does not end a session. The SDK handles it by itself, and your page only shows the state.
The exact timings and every case are in Reliability. What your page sees is in Reconnection and recovery.
What ends a session
Every end has a code, a kind (endKind) and a sentence for the viewer (message). Your page gets them in the ended event and in the ended state.
All codes, with the sentence for each: How a session ends.
Glossary
Next steps
Installation
npm or a script tag, TypeScript, frameworks, Content-Security-Policy.
Quick start
A real page with npm and the ready-made screens.
Events and states
Every state and every event, with its fields.
Under the hood: reliability
What the SDK does when things go wrong, with the real timings.