Stream States

Learn how to intercept real-time stream state messages sent by Streampixel to your frontend. This guide provides a simple example to help you handle these messages and customize your UI.

Overview

Streampixel enables you to monitor the progress of the stream state process by sending real-time structured messages to your frontend. These messages contain detailed information about the current state of the stream, allowing you to design and implement custom loading UIs tailored to your needs.

Stream State Messages

The messages are sent as structured objects with the following format:

{
  "type": "stream-state",
  "value": "state_value"
}

Fields:

• type: Identifies the type of the message. For stream state updates, this will always be stream-state.

• value: Represents the current state of the stream. Possible values are:

Value	Description
authenticating	Request is sent to the backend to authenticate access to the stream. Progress: 10%
connecting	Establishing a connection with the signaling server and finding an available compute resource. Progress: 20%
finalising	Loading WebRTC components. Progress: 80%
loadingComplete	The stream is ready to be played. Progress: 100%
disconnected	Disconnected due to inactivity, project crash, or another reason.
restricted	Access is restricted due to project inactivity, domain blacklisting, or user permissions.
afkWarning	System detected inactivity. The stream will automatically close if no activity is detected within 10 seconds.
afkAbort	This status occurs when a user successfully interacts with the stream during an AFK warning period, effectively cancelling the automatic closure of the stream. It confirms that the user is still active, preventing the session from ending prematurely.
queue-1	Indicates the user is currently queued for access to the stream due to full capacity. The number following "queue-" shows the user's position in the queue, which dynamically changes as the queue progresses.
showPassword	This message is sent from the iframe when the stream is password protected and a password input field needs to be shown. It indicates that the host page should remove or reposition any loading overlays that might block the password textbox, allowing the user to see and interact with it.
hidePassword	This message is sent once the user has entered a valid password and it has been authenticated. It signals the host page to hide the password UI and optionally restore any loading overlays or transition to the next step in the user flow.

How to Intercept Stream State Messages

You can use the window.addEventListener method to listen for message events sent by the Streampixel iframe. Here's an example:

window.addEventListener('message', (event) => {
    if (event.origin === 'https://share.streampixel.io' && event.data.type === 'stream-state') {
        console.log('Stream State:', event.data.value); // Logs the current stream state
        // Add your custom logic here to handle the stream state (e.g., update UI)
    }
});