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
Why the state stays reconnecting until video plays
Why the state stays reconnecting until video plays
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.
Which ticket does a fresh session use?
Which ticket does a fresh session use?
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
Forcing the relay
Forcing the relay
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
deadlineMsfor a countdown. It is the time, in epoch milliseconds, at which the reconnect window ends. - Expect
sessionto fire again. After a fresh session,currentSessionIdandcurrentStreamerIdare 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
launchParamsagain. Its earlier state is lost. - Listeners survive. Listeners added with
stream.on()andstream.addEventListener()stay attached through every repair. Epic’s object itself is replaced on a rebuild: readstream.pixelStreamingeach time you use it. - After
ended, create again. No repair happens afterended.
reconnect-banner.ts
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.