npm package: @managexr/react-streaming
Description: A React library for streaming from XR devices on ManageXR
Author: Henry Thiemann
Latest version: 1.3.0

# ManageXR React Streaming SDK

This package allows organizations managing XR devices with ManageXR to embed the ManageXR web console's streaming functionality in their own React apps. Devices must be actively enrolled with ManageXR in order to stream.

## Usage

### Step 1: Generate an SDK token for the device(s) you want to stream

See our [API Docs](https://docs.managexr.com/api-reference/introduction) for instructions on authenticating API requests.

The API key used in the request must have access to every device specified. The returned token will authenticate the SDK to stream only those devices. To stream additional devices, request a new token.

Request:

```bash
curl --request POST \
  --url https://managexrapi.com/v1/devices/generate-streaming-sdk-token \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '{ "deviceIds": ["device_id_1", "device_id_2"] }'
```

Response:

```json
{ "token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }
```

### Step 2: Render an instance of `useDeviceStream` for each device

The connection process will start as soon as the hook is rendered. To end the stream, simply stop rendering the component that contains the hook.

```tsx
import { useDeviceStream } from '@managexr/react-streaming'

const StreamingComponent = ({ deviceId, token }) => {
   const { videoRef } = useDeviceStream(deviceId, token)

   return (
      <div>
         <video ref={videoRef} />
      </div>
   )
}
```

## API

### `useDeviceStream(deviceId: string, token: string, options?: DeviceStreamOptions) => DeviceStream`

| Argument   | Description                                                                                                                           |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `deviceId` | The id (serial) of the device to stream from. This device must be registered with ManageXR and have the ManageXR Admin App installed. |
| `token`    | An authentication token returned by the `generate-streaming-sdk-token` endpoint. The token must include the provided `deviceId`.      |
| `options`  | See [`DeviceStreamOptions`](#devicestreamoptions)                                                                                     |

**Returns [`DeviceStream`](#devicestream)**

### `DeviceStreamOptions`

| Option                        | Default | Description                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `endOtherStreamAutomatically` | `false` | When `true`, if the requested device is already streaming to another computer, that stream will be ended automatically. The `error_already_streaming` status will not be emitted.                                                                                                                                                                                                   |
| `enableReconnection`          | `false` | When `true`, the SDK automatically handles WebRTC connection failures by waiting for the device to re-establish the connection via ICE restart. Without this option, any connection failure immediately transitions to `error_connection`. When enabled, the SDK enters a `reconnecting` state and waits for the device to send a new offer within the reconnection timeout window. |
| `reconnectionTimeoutMs`       | `30000` | How long (in milliseconds) to wait for the device to reconnect before falling back to `error_connection`. Set to `0` to wait indefinitely. Only applies when `enableReconnection` is `true`.                                                                                                                                                                                        |

### `DeviceStream`

| Property         | Description                                                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `videoRef`       | Set this as the `ref` of the `<video>` element that should display the stream.                                           |
| `status`         | The current status of the stream. See [`DeviceStreamStatus`](#devicestreamstatus) for info about each status.            |
| `reloadVideo`    | To change which `<video>` element is displaying the stream, call this after setting `ref={videoRef}` on the new element. |
| `retryStream`    | Call this to restart the stream if it encounters an error status other than `error_already_streaming`.                   |
| `endOtherStream` | Call this when the `error_already_streaming` status is encountered to end any active streams for the current device.     |

### `DeviceStreamStatus`

| Status                          | Description                                                                                                                                                                            |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending_online`                | Device is currently offline. The connection process will start once the device is online.                                                                                              |
| `pending_permission`            | The in-headset user has been prompted to allow ManageXR to capture the screen. The connection process will continue once permission is granted.                                        |
| `pending_connection`            | Screen capture permission has been granted and the connection process is underway.                                                                                                     |
| `connected`                     | The stream is connected. If `videoRef` has been set correctly, the stream is now visible.                                                                                              |
| `reconnecting`                  | The stream has disconnected due to a network issue and is attempting to reconnect automatically.                                                                                       |
| `error_request_failed`          | The device did not acknowledge the request to start a stream.                                                                                                                          |
| `error_permission_dismissed`    | The in-headset user dismissed the prompt to allow screen capture.                                                                                                                      |
| `error_permission_denied`       | The in-headset user denied screen capture permission.                                                                                                                                  |
| `error_failed_to_start`         | Screen capture permission was granted, but the stream failed to start.                                                                                                                 |
| `error_terminated_on_device`    | The stream session was ended on the device side (e.g. network error or app restart).                                                                                                   |
| `error_user_ended_on_device`    | The in-headset user explicitly ended the stream (e.g. via an "End Cast" button on the device).                                                                                         |
| `error_connection`              | The stream was successfully connected but a network issue caused it to end early. When `enableReconnection` is `true`, this status is only set after the reconnection timeout expires. |
| `error_already_streaming`       | Another computer is already streaming this device. A device can't stream to more than one computer at a time.                                                                          |
| `error_oem_permission_required` | The device manufacturer suppressed the stream.                                                                                                                                         |