Skip to main content
Advanced For developers who ship a page to production. After this page you can show the right thing for every state a stream can be in, and react to every event it emits. A stream tells your page what it is doing in two ways:
  • One state at a time. stream.state holds it, and the state event fires on every change.
  • Events for everything else: loading progress, statistics, prompts for the viewer, messages from your application.

Subscribing

Listeners
() => void
Subscribes. Accepts only the event names on this page. Returns the function that unsubscribes.
void
Unsubscribes, by the same function reference.
() => void
Subscribes to any name. Use it for an event that a newer engine added and your installed package does not know yet.
Four rules apply to every listener:
  1. Attach listeners straight after await Streampixel.create(...). The first events fire one moment later. If your code awaits something else first, read stream.state, stream.currentSessionId and stream.currentStreamerId instead.
  2. Any number of listeners can share one event.
  3. A listener that throws is logged. It does not stop the stream or the other listeners.
  4. All listeners are removed when the session ends, after ended has fired.
Render the state that is already there

States

stream.state is an object. Switch on its kind. The usual path is short: idle, connecting, streaming, ended. Everything else is a detour that the SDK handles by itself. Your page only has to show it.

What to show in each state

status-text.ts
Keep the default branch. A newer engine may add a kind, and the engine updates without a new install.

Every state

{ kind: 'idle' }
create() has resolved. Connecting starts in a moment. Show your loading screen.
{ kind: 'awaitingPassword'; wrong?; locked?; hard?; retryAfterSec? }
A password project is waiting for stream.submitPassword(). Nothing has started: no ticket, no GPU. See Access.
{ kind: 'connecting' }
Three things happen in this state: opens, the application starts, and the video connection is set up. The progress event tells the steps apart.The stream is also connecting after it leaves the queue, while a connection is rebuilt, and while a fresh session starts. In a Test locally session it stays connecting, with no time limit, until your Unreal connects.
{ kind: 'queued'; position: number }
Waiting for a free GPU. When the application answers, the state goes back to connecting.
{ kind: 'streaming' }
The video is playing. Hide your loading screen. Messages and console commands can be sent now.
{ kind: 'awaitingPlay'; reason: string }
The stream is up, and the browser refused to start playback without a click or tap. Show a “Click to start” control that calls stream.play(). A press anywhere on the container also starts it. See Controls and input.
{ kind: 'recovering'; attempt: number }
No video arrived. The stalled event says why. The SDK is starting one fresh session. A viewer of a shared session, and a Test locally session, rejoin the same session instead.
{ kind: 'reconnecting'; attempt: number; deadlineMs: number; waitingForHost? }
The connection dropped and the SDK is restoring it, on the same session.
{ kind: 'ended'; code: number; reason: string; endKind; message: string }
Final. The fields are the same as the payload of the ended event. There is no way back from this state: to start again, destroy the stream and create a new one. See How a session ends.
The StreamState type also declares resolving, starting and stalled. They are marked deprecated and are never emitted. They are in the type so that a switch written against an earlier 2.0 alpha still compiles. stalled is an event; the state it leads to is recovering.

Reconnection and recovery

The SDK restores a broken stream by itself. Your page does nothing except show the state. There are two kinds of repair, and the difference matters to your application. What your page sees for each thing that can go wrong: Tries inside the window wait about 1, 2, 4, 8 and then 15 seconds, each varied by 20 % up or down. When the browser reports that it is back online, the remaining wait is skipped.
A normal session reconnects only after a drop. Any other close from the platform ends the session with the platform’s code. Shared sessions do not start a fresh session after a stall: see Shared sessions.
For the mechanism behind each row and every timing, read Reliability. For a banner with a countdown, see the cookbook.

Events

A normal start fires events in this order:

Lifecycle

StreamState
Fires on every state change. The payload is the new state: see Every state.
{ sessionId: string; streamerId: string }
A platform session starts. These are the ids shown in your Streampixel analytics, so storing them links a session to your own user.Fires once per session, again with new ids when the SDK recovers into a fresh session, and not on a reconnect that keeps the session. The same values are on stream.currentSessionId and stream.currentStreamerId. The event carries no ticket and no password.
{ code: number; reason: string; endKind: EndKind; message: string }
The session is over. This is the last event: all listeners are removed after it.
stream.destroy() and stream.disconnect() on a live stream also fire ended, with code 1000 and endKind: 'user'. If your page restarts on ended, check endKind, or unsubscribe before you destroy.

Loading

{ stage: 'offer' | 'answer' | 'connected' }
Steps inside connecting, for a loading screen. It fires again each time a connection is built.Streampixel’s share page shows the project’s loading texts one, two and three at these three points. They are in stream.streamConfig as loadingTextOne, loadingTextTwo and loadingTextThree.
{ position: number; message?: string }
The queue position changed. position is a whole number, 0 when the server did not say. message is the server’s own text.
{ reason: string }
The browser refused to start playback without a click or tap. The state is awaitingPlay. Show a control that calls stream.play().

Quality and network

StreamStats
Every second while the video is up. The fields are in StreamStats.
number
The encoder’s , about once a second, on H.264’s scale of 0 to 51 whatever the codec. Lower is a better picture. The same number is avgQp in stats.
Diagnostics
No video. Recovery follows: the state becomes recovering, or the session ends when recovery was already tried.The object carries more detail than the type lists. See Diagnostics.
{ transport: 'tcp' | 'tls'; showWarning: boolean }
UDP is blocked on the viewer’s network, and the stream is relayed over TCP or TLS, at lower quality. showWarning is the project’s Show UDP Blocked Warning setting from the dashboard: show your notice only when it is true.

Prompts for the viewer

{ kind: 'countdown'; secondsRemaining: number; dismiss: () => void } | { kind: 'dismissed' }
The idle countdown started, counted down, or was cancelled.Not raised for a viewer of a shared session, nor in a Test locally session: they have no idle timeout.
{ contents: string }
The application asked for text input: one of its text fields got focus. contents is the text already in that field. Show a text input and answer with stream.sendTextboxEntry(text). See Text input on phones.
no payload
The application asked to hide the keyboard. Close your text input.

From your application

Coming from Epic’s Pixel Streaming library? Its method names work on the stream object too: emitUIInteraction(), emitConsoleCommand() and addResponseEventListener(). They are the same calls as send(), consoleCommand() and on('ueMessage'). Use whichever you know. See Talk to your Unreal app.
unknown
A message from your Unreal application, usually a JSON string. See Talk to your Unreal app.
{ url: string; open: () => void }
The application sent a plain https link for the viewer. open() opens it in a new tab. On phones and tablets, call it from a click or tap.
{ received: number; total: number; name: string }
A file from the application is arriving. received and total count pieces, not bytes.
{ blob: Blob; name: string; mimeType: string }
A file from the application arrived, complete.
{ dataUrl: string }
The application asked for a screenshot with its requestScreenshot message. dataUrl is the current frame as a PNG.

Events with a built-in action

Three events have an action that runs only when your page has no listener for them. Add a listener and the action is yours. With @streampixel/ui mounted and its files or links part on, that package handles those events.

StreamStats

The payload of the stats event. Totals count from the start of the current connection, so they begin again after a rebuilt connection.
number
Frames decoded per second.
number
Network round-trip time in milliseconds, as the browser measures it for the connection in use. 0 until the browser has a first reading. When one sample has no reading, the last one is kept.
number | null
Received video bitrate, in kilobits per second.
string | null
The size of the video as received, for example "1920x1080".
string | null
The video codec in use, for example "H264" or "AV1".
number | null
The latest encoder QP, on the scale of 0 to 51. null before the first sample.
number
Frames decoded, in total.
number
Frames dropped, in total.
number
Video packets lost, in total.
number
Bytes received, video and audio together, in total.
'' | 'udp' | 'tcp' | 'tls'
The transport of the relay in use. Empty on a direct path.
An older engine may not send every field. When you print a value, give it a fallback: s.packetsLost ?? '—'.

Next steps

Errors and disconnects

Every end code, endKind and message.

Cookbook

A loading screen, a queue display and a reconnecting banner built on these states.

Reliability

One level up: the mechanism and timing behind reconnection and recovery.

Stream API reference

play(), keepAlive(), submitPassword() and every other method.