Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.streampixel.io/llms.txt

Use this file to discover all available pages before exploring further.

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:
  1. webRtcAutoConnect — Auto-connect initiated (only if AutoConnect: true)
  2. webRtcConnecting — WebRTC peer connection is being established
  3. webRtcSdp — SDP offer/answer exchanged between browser and UE
  4. webRtcConnected — Peer connection established, media channels open
  5. streamLoading — Video data arriving from UE
  6. playStream — Video is about to start playback
  7. 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.