# Stream States

## Overview <a href="#overview" id="overview"></a>

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:

```javascript
{
  "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:

{% code lineNumbers="true" %}

```javascript
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)
    }
});
```

{% endcode %}