Connection lifecycle

This page describes the events that fire as a stream connects, how to use them for loading screens, and how to manage connection state manually.

Event sequence

When a stream connects successfully, events fire in this order:

webRtcAutoConnect — Auto-connect initiated (only if AutoConnect: true)
webRtcConnecting — WebRTC peer connection is being established
webRtcSdp — SDP offer/answer exchanged between browser and UE
webRtcConnected — Peer connection established, media channels open
streamLoading — Video data arriving from UE
playStream — Video is about to start playback
videoInitialized — Video element is ready (via appStream.onVideoInitialized)

Listening for events

videoInitialized is handled via a callback (appStream.onVideoInitialized), not through addEventListener like the other events. This is because it fires from the application wrapper, not from the pixelStreaming instance.

pixelStreaming.addEventListener('webRtcConnecting', () => {
  console.log('Establishing connection...');
});

pixelStreaming.addEventListener('webRtcConnected', () => {
  console.log('Connected!');
});

pixelStreaming.addEventListener('playStream', () => {
  console.log('Stream is playing');
});

// videoInitialized is handled via callback, not addEventListener
appStream.onVideoInitialized = () => {
  document.getElementById('container').appendChild(appStream.rootElement);
};

Building a loading screen

Map each event to a progress percentage for a smooth loading experience:

const PROGRESS_MAP = {
  webRtcAutoConnect: 15,
  webRtcConnecting: 30,
  webRtcSdp: 50,
  webRtcConnected: 70,
  streamLoading: 80,
  playStream: 90,
};

Object.entries(PROGRESS_MAP).forEach(([event, progress]) => {
  pixelStreaming.addEventListener(event, () => {
    updateProgressBar(progress);
  });
});

appStream.onVideoInitialized = () => {
  updateProgressBar(100);
  hideLoadingScreen();
  document.getElementById('container').appendChild(appStream.rootElement);
};

Failure events

`webRtcFailed`

Fires when the WebRTC connection fails to establish.

pixelStreaming.addEventListener('webRtcFailed', () => {
  showError('Connection failed. Please try again.');
});

`webRtcDisconnected`

Fires when an established connection drops.

pixelStreaming.addEventListener('webRtcDisconnected', () => {
  showError('Connection lost.');
});

When automatic reconnection is active, webRtcDisconnected may fire during the reconnection process. Check reconnectStream state to differentiate between a temporary disconnect (reconnecting) and a permanent one. See Reconnection.

Manual connection control

Use AutoConnect: true for the simplest setup — the stream connects immediately on initialization. Use AutoConnect: false (the default) when you want to show a “Play” button or loading screen before connecting, giving you full control over when the connection starts.

If AutoConnect is false, connect manually:

const { pixelStreaming } = await StreamPixelApplication({
  appId: 'your-project-id',
  AutoConnect: false,
});

// Connect when the user clicks a button
document.getElementById('play-btn').addEventListener('click', () => {
  pixelStreaming.connect();
});

// Disconnect
pixelStreaming.disconnect();

// Reconnect after disconnect
pixelStreaming.reconnect();

Mobile background handling

On iOS and Android, the SDK automatically disconnects the stream if the browser tab is hidden (user switches apps) for more than 60 seconds. This prevents idle resource consumption on mobile devices. When the user returns within 60 seconds, the stream continues normally.

Next steps

Reconnection

Handle WebSocket drops with the automatic reconnection state machine.

Return values

Reference for pixelStreaming, appStream, and the other returned objects.

Getting started

Core concepts

Features

UI customization

API reference

Guides

Event sequence

Listening for events

Building a loading screen

Failure events

`webRtcFailed`

`webRtcDisconnected`

Manual connection control

Mobile background handling

Next steps

Reconnection

Return values

​Event sequence

​Listening for events

​Building a loading screen

​Failure events

​webRtcFailed

​webRtcDisconnected

​Manual connection control

​Mobile background handling

​Next steps

Reconnection

Return values

Event sequence

Listening for events

Building a loading screen

Failure events

`webRtcFailed`

`webRtcDisconnected`

Manual connection control

Mobile background handling

Next steps