Skip to main content
Expert For developers who want the exact mechanism behind every recovery. After this page you can say, for each failure, what the SDK does, after how many seconds, and which state, event and end code your page gets. The SDK repairs a broken stream by itself. Your page only shows the state. This page lists every failure the SDK watches for, one table each. All numbers are the engine’s own constants, for engine 2.0.0-beta.2.

Three terms

Signalling and the video connection fail independently. Most of this page follows from that.

Four kinds of repair

When no repair works, the session ends. ended is final: your page calls create() again.

All timers at a glance

Signalling drops

After signalling reopens, the app sets up a new video connection for the new socket, and the old video stops as soon as the app drops the old one. If the SDK reported streaming when signalling reopened, a failed renegotiation would leave your page showing streaming over a frozen picture. So streaming is reported when the new video plays, and the old video connection is closed only then: its last frame stays on screen until the new one takes over.

The browser goes offline, or comes back

The video connection is kept on purpose. Browsers sometimes report “offline” while video still flows: a Wi-Fi switch, a VPN. Closing the video connection then would make the app see the viewer leave and end the session.

Signalling does not open

The video connection dies

This check only runs while the state is streaming or awaitingPlay. Before the first frame, the connect limit below decides.

Connected, and no video frames

The fresh session is given once per stream object. The count is not reset when the new session plays.

The video never starts

The two codes exist so that the end points to the right place: 4101 to the network between the viewer and the stream, 4102 to the app.

A network that blocks the stream

A stream that connects over local addresses only, on the same local network, is never judged blocked. Point the viewer’s IT team to Network requirements.

Relay fallback

@streampixel/ui shows this notice for you, when the project’s setting is on. See Ready-made screens.
The SDK forces the relay only when advanced.iceTransportPolicy is 'relay', or when the project’s “force TURN” setting is on. Otherwise the browser chooses the best path that works, and uses the relay when no direct path does.When the relay is forced and the platform handed out no relay, the session ends with code 4010, endKind: 'server'.

The app stops, or never starts

These are decided by the platform, or by the SDK when the platform stays silent. None of them is retried for a normal session: a stopped app cannot be reconnected to.

Shared sessions and Test locally

Three cases recover differently from a normal session. The final closes end every kind of session: 1008, 4401, and the platform’s reasons project inactive, no worker available, application not found, application error, maximum runtime reached, no streamer connected and relay unavailable. See Shared sessions and Test locally.

Ends that are not failures

What this means for your page

  • Show the state, do not repair. Do not build your own reconnect on top. Do not call reconnect() on Epic’s object (stream.pixelStreaming): the SDK owns reconnection.
  • Use deadlineMs for a countdown. It is the time, in epoch milliseconds, at which the reconnect window ends.
  • Expect session to fire again. After a fresh session, currentSessionId and currentStreamerId are new. If you store them, update them.
  • Expect your app to restart once. After a fresh session, the app starts from the beginning and receives launchParams again. Its earlier state is lost.
  • Listeners survive. Listeners added with stream.on() and stream.addEventListener() stay attached through every repair. Epic’s object itself is replaced on a rebuild: read stream.pixelStreaming each time you use it.
  • After ended, create again. No repair happens after ended.
reconnect-banner.ts
More patterns for banners and status screens are in the cookbook.

Next steps

Diagnostics

Read stats and getDiagnostics(), and find out why one session went wrong.

The engine and updates

How the code that does all this reaches the page.

Events and states

Reference: the states and events named on this page, with their fields.

Errors and disconnects

Reference: every end code and the sentence shown to the viewer.