# WebRTC

A distribution can be configured with a WebRTC source to enable sub-second, real-time delivery alongside the standard HESP and HLS output protocols. When WebRTC is enabled, the platform connects the distribution to an [OptiView Real-time Streaming](https://docs-preview.optiview.dolby.com/pr-863/millicast/getting-started.md) source, allowing viewers to receive the stream over WebRTC for the lowest possible latency.

> **Distribution-level security does not apply to WebRTC**
>
> When viewers play back via the WebRTC source, traffic is served directly by OptiView Real-time Streaming and bypasses the distribution. As a result, distribution-level [token-based security](https://docs-preview.optiview.dolby.com/pr-863/theolive/distribution/security/token-based-security.md), [geo-blocking](https://docs-preview.optiview.dolby.com/pr-863/theolive/distribution/security/geo-blocking.md), [IP blocking](https://docs-preview.optiview.dolby.com/pr-863/theolive/distribution/security/ip-blocking.md), and [referrer blocking](https://docs-preview.optiview.dolby.com/pr-863/theolive/distribution/security/referrer-blocking.md) are **not enforced** for WebRTC playback. Read the [Secure viewing](#secure-viewing) section to learn how to access a protected stream.

## How it works

WebRTC delivery is configured per distribution using the `webRtc` field. The field links the distribution to an OptiView Real-time Streaming source by specifying the source name, account ID, and API URL of the real-time stream.

When a viewer connects to a distribution that has WebRTC configured, the player selects between the WebRTC source and the regular HESP/HLS output based on priority. The `priority` field must be `0` or higher, where a lower value means higher precedence — the same direction as [engine priority](https://docs-preview.optiview.dolby.com/pr-863/theolive/architecture.md#engine). When the WebRTC priority is lower than the engine's priority, the player prefers the WebRTC source, with HESP/HLS acting as a fallback.

### Configuration fields

| Field           | Type     | Required | Description                                                                                |
| --------------- | -------- | -------- | ------------------------------------------------------------------------------------------ |
| `priority`      | `number` | Yes      | Priority of the WebRTC source. Must be `0` or higher; lower values mean higher precedence. |
| `src.name`      | `string` | Yes      | The OptiView Real-time Streaming stream name.                                              |
| `src.accountId` | `string` | Yes      | The OptiView Real-time Streaming account ID.                                               |
| `src.apiUrl`    | `string` | Yes      | The OptiView Real-time Streaming Director API URL (for example, the subscribe endpoint).   |

To remove the WebRTC configuration from a distribution, set the `webRtc` field to `null` when updating.

## Secure viewing

In order to properly protect the viewing experience, you will want to use a single protection token for both the WebRTC and the HLS feeds. This JWT token will be based on the [subscribe tokens](https://docs-preview.optiview.dolby.com/pr-863/millicast/subscribe-tokens.md) of the OptiView Real-time Streaming platform. Here are the steps to achieve this.

* Create a parent [subscribe token](https://docs-preview.optiview.dolby.com/pr-863/millicast/subscribe-tokens.md) that you will be using for generating self-signed tokens.

* In your channel distribution settings, go to the *JWT security* section and add a new JWT security key. Provide a name that will help you remembering what OptiView Real-time Streaming subscribe token it comes from (e.g. `Subscribe Token 1071141886`). Copy the token value for the key (e.g. `7f4a7f358e163d298a95b96b95e18cf677e43252d6c2387d64a26aa5ae5bcacc`).

* When a viewer is trying to access the feed, generate a [self-sign subscribe token](https://docs-preview.optiview.dolby.com/pr-863/millicast/subscribe-tokens.md#self-signing-subscribe-tokens) and provide it to the player before connecting to the feed.

  Web SDK example

  ```javascript
  player.theoLive.authToken = SUBSCRIBE_TOKEN;
  ```

## When to use WebRTC

* **Sub-second latency** — WebRTC delivers end-to-end latency under 500 ms, making it ideal for interactive use cases such as auctions, betting, or live Q\&A.
* **Hybrid delivery** — combine WebRTC for the lowest latency with HESP/HLS as a fallback for broad device compatibility. The player automatically selects the best available protocol.

## API example

You can configure WebRTC via the API using the `webRtc` field when [creating](https://docs-preview.optiview.dolby.com/pr-863/theolive/api/create-channel-distribution.md) or [updating](https://docs-preview.optiview.dolby.com/pr-863/theolive/api/update-distribution.md) a distribution.

### Add WebRTC to a distribution

`POST https://api.theo.live/v2/channels/{channelId}/distributions`

```json
{
  "name": "my-distribution",
  "webRtc": {
    "priority": 0,
    "src": {
      "name": "my-realtime-stream",
      "accountId": "your-realtime-account-id",
      "apiUrl": "https://director.millicast.com/api/director/subscribe"
    }
  }
}
```

In this example, the WebRTC source is configured with `priority: 0`, the highest possible WebRTC priority. When the engine priority is higher than `0`, the player prefers the WebRTC source and falls back to the engine output (HESP/HLS) otherwise.

### Remove WebRTC from a distribution

`PATCH https://api.theo.live/v2/distributions/{distributionId}`

```json
{
  "webRtc": null
}
```

## Notes

* WebRTC is configured per distribution, not per engine. Different distributions on the same channel can have different WebRTC configurations — or none at all.
* Distribution-level security and geo-blocking do **not** apply to WebRTC playback — they only affect HESP and HLS delivery. See the warning above for details.
* [Distribution overrides](https://docs-preview.optiview.dolby.com/pr-863/theolive/distribution/distribution-override.md) work as expected with WebRTC.