Skip to main content
Beginner Intermediate For anyone who has a stream on a page and wants to know what happens behind it. After this page you can name each part, say what a session is, and explain every step between 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 with EngineLoadError and no stream starts.
  • Two version numbers exist. SDK_VERSION is the package you installed. stream.engineVersion is 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 with create(), 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 from stream.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 a position. The queue event fires when the position changes.
  • position is a whole number. It is 0 when the server did not say.
  • The viewer leaves the queue when your app answers: the state goes back to connecting, then streaming.
  • Your page only has to show it. With @streampixel/ui the 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.
ended is final. A stream that has ended cannot be restarted, and all its listeners are removed after the ended event. To start again, call stream.destroy() and then Streampixel.create() again.
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.