# Stream Control Commands

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

Streampixel allows you to control and interact with the stream dynamically by sending predefined commands to the iframe using the `postMessage` API. These commands let you manage actions like muting, unmuting, disconnecting, adjusting the stream resolution and sending pixel streaming messages to the Unreal Engine application.

***

### **How PostMessage Works**

The `postMessage` API enables communication between your frontend application and the Streampixel iframe. By sending specific commands to the iframe, you can control various aspects of the stream programmatically.

***

## **Detailed Command Descriptions**

Here’s a breakdown of the commands and what they do:

**1. Set Stream Resolution**

* **Description**: Sends the desired resolution for the stream. The actual changes will depend on the **Re**
* **Behavior**:
  * Sending a resolution higher than the **Max Stream Quality** will have no effect.
  * The resolution must be one of the supported values; unsupported resolutions will be ignored.
* **Parameters**:
  * `value`: The desired resolution as a string (e.g., `720p (1280x720)`).
* **Supported Resolutions**:
  * `360p (640x360)`
  * `480p (854x480)`
  * `720p (1280x720)`
  * `1080p (1920x1080)`
  * `1440p (2560x1440)`
  * `4K (3840x2160)`
* **Message Example**:

  ```javascript
  { message: {value: '720p (1280x720)',type:"setResolution" }}
  ```

{% hint style="warning" %}

* If the requested resolution exceeds the **Max Stream Quality** set in your project settings, the resolution will not change.
* Ensure the resolution matches one of the supported values to avoid issues.
  {% endhint %}

***

**2. Mute Stream Audio**

* **Description**: Mutes the audio for the stream.
* **Behavior**:
  * The video continues to play, but the audio is turned off for the user.
  * It won't change the mute/unmute UI within iframe.
* **Message Example**:

  ```javascript
  { message: 'muteAudio' }
  ```

***

**3. Unmute Stream Audio**

* **Description**: Unmutes the audio for the stream.
* **Behavior**:
  * Restores audio playback for the stream.
  * It won't change the mute/unmute UI within iframe.
* **Message Example**:

  ```javascript
  { message: 'unMuteAudio' }
  ```

{% hint style="info" %}
Auto unmute may not work out of the box due to browser policies, such as those outlined by [Google's autoplay policies](https://developer.chrome.com/blog/autoplay). Additional configuration may be required to enable this functionality.
{% endhint %}

***

**4. Terminate Session**

* **Description**: Ends the current session for the stream.
* **Behavior**:
  * Stops the stream and disconnects the WebRTC connection to the server.
* **Message Example**:

  ```javascript
  { message : 'terminateSession' }
  ```

***

**5. Send Heartbeat**

* **Description**: Prevents the Unreal Engine application from timing out due to inactivity.
* **Behavior**:
  * Keeps the session alive by sending periodic heartbeat messages to the server.
  * Recommended for applications where inactivity timeout isn't required.
* **Message Example**:

  ```javascript
  { message: 'heartbeat' }
  ```

***

**6. Custom Messages to Unreal Engine App**

* **Description**: Sends custom messages or data directly to the Unreal Engine application running in the stream.
* **Behavior**:
  * Allows you to trigger specific logic or interactions in your Unreal Engine app.
  * You can send custom fields without the `message` key if required.
* **Message Example**

```javascript
{ customField: 'customValue' } 
```

***

**7. Connect to Chat**

* **Description**: Starts the built-in voice and/or text chat system for the user.
* **Behavior**:
  * Users are connected to the chat and assigned a name, avatar, and optionally a room based on the variables you send
  * If `roomId` is not provided, all users in the same project session are placed into a default shared room.
* **Message Example**

```javascript
{
  "message": {
    "type": "comms",
    "value": {
      "name": "Alice",
      "pfpUrl": "https://example.com/avatar.jpg",
      "roomId": "room-123"
    }
  }
}
```

{% hint style="warning" %}
Make sure that `Communication Startup Behavior` is set to `Start when triggered by App` in the communication tab present on the project details page. For more info check [built-in-voice-and-text-chat](https://docs.streampixel.io/resources/readme/built-in-voice-and-text-chat "mention")
{% endhint %}

***

#### 8. Disconnect from Chat

* **Description:** Terminates the active communication session for the user.
* **Behavior:**
  * Immediately stops both voice and text chat.
  * Removes the user from the communication room and UI.
* **Message Example**

```json
{
  "message": {
    "type": "comms",
    "value": "disconnect"
  }
}
```

{% hint style="warning" %}
Make sure that `Communication Startup Behavior` is set to `Start when triggered by App` in the communication tab present on the project details page. For more info check [built-in-voice-and-text-chat](https://docs.streampixel.io/resources/readme/built-in-voice-and-text-chat "mention")
{% endhint %}

9. **Toggle Browser Cursor Visibility via Iframe**

* **Description:**\
  Allows the parent webpage to programmatically toggle the visibility of the browser‑based mouse cursor inside the embedded Pixel Streaming iframe.
* **Behavior:**
  * Sends a command from the parent page to the iframe to hide or show the cursor.
  * Enables seamless switching between immersive gameplay (hidden cursor) and UI interaction (visible cursor).
* Message Example

Turn on Mouse Visibility

```javascript
{"message": {"type": "togglehoveringmouse", "value": true}}
```

Turn off Mouse Visibility

```javascript
{"message": {"type": "togglehoveringmouse", "value": false}}
```

10. **Screenshot Message**

* **Description:**\
  Allows the application to trigger a screenshot of the stream (without any frontend UI) and automatically download it to the user’s device.
* **Behavior:**
  * Sends a command from the parent page to the iframe to capure screenshot.
  * The frontend captures the current video frame and saves it as an image file locally.
* Message Example

```javascript
{message : 'requestScreenshot'}
```

***

## **How to Send Commands**

Use the `postMessage` API to send these commands to the iframe.

**Basic Example**

```javascript
// Reference the iframe
const streamIframe = document.getElementById('streamIframe');

// Example Commands
streamIframe.contentWindow.postMessage({ message: { value: '720p (1280x720)', type: 'setResolution' } }, '*'); // Set resolution
streamIframe.contentWindow.postMessage({ message: 'muteAudio' }, '*'); // Mute the stream
streamIframe.contentWindow.postMessage({ message: 'unMuteAudio' }, '*'); // Unmute the stream
streamIframe.contentWindow.postMessage({ message: 'terminateSession' }, '*'); // Terminate the session
streamIframe.contentWindow.postMessage({ message: 'heartbeat' }, '*'); // Send a heartbeat
streamIframe.contentWindow.postMessage({ customField: 'customValue' }, '*'); // Send custom data
```