Stream states

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%
`reconnecting`	Attempting to restore the stream after a temporary network interruption.
`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)
    }
});

Stream metadata

In addition to state updates, the iframe sends a one-time stream-metadata message at the start of every session. This message contains the identifiers that uniquely describe the running stream — the same sessionId and streamerId you can see for that session in your StreamPixel Analytics dashboard.

Message format

{
  "type": "stream-metadata",
  "sessionId": "abc123-session-uuid",
  "streamerId": "xyz789-streamer-uuid"
}

Fields:

type: Always stream-metadata.
sessionId: A unique identifier for the current streaming session. Each new session (page load / reconnect to a fresh streamer) generates a new value.
streamerId: The identifier of the underlying streamer (compute instance) serving this session.

Why this is useful

Because these are the exact same IDs surfaced in the StreamPixel Analytics dashboard, capturing them on your frontend lets you link a stream session to your own user. For example, when a logged-in user starts a stream you can store a mapping of { yourUserId → sessionId, streamerId } in your own database. Later, when you look at session analytics in the StreamPixel dashboard, you can correlate any session back to the user who watched it — useful for support, billing, per-user usage reporting, or feeding StreamPixel session data into your own analytics pipeline.

How to intercept stream metadata

window.addEventListener('message', (event) => {
    if (event.origin !== 'https://share.streampixel.io') return;

    if (event.data.type === 'stream-metadata') {
        const { sessionId, streamerId } = event.data;
        console.log('Session started:', sessionId, streamerId);

        // Example: associate this session with the currently signed-in user
        // saveSessionForUser(currentUser.id, { sessionId, streamerId });
    }
});

The stream-metadata message is sent once, immediately after the iframe finishes loading and a session is assigned. Make sure your message listener is attached before the iframe loads so you don’t miss it.

Iframe integration

Overview

Stream state messages

How to intercept stream state messages

Stream metadata

Message format

Why this is useful

How to intercept stream metadata

Next steps

Stream control commands

Sample code for HTML and React

​Overview

​Stream state messages

​How to intercept stream state messages

​Stream metadata

​Message format

​Why this is useful

​How to intercept stream metadata

​Next steps

Stream control commands

Sample code for HTML and React

Overview

Stream state messages

How to intercept stream state messages

Stream metadata

Message format

Why this is useful

How to intercept stream metadata

Next steps