From 87b78c8bef3bb5049628d8d3a52bbc84ab344f60 Mon Sep 17 00:00:00 2001 From: Jeroen Tempels Date: Fri, 3 Apr 2026 11:47:34 +0200 Subject: [PATCH 1/7] Add image overlays page to media engine docs --- theolive/media-engine/image-overlays.mdx | 92 ++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 theolive/media-engine/image-overlays.mdx diff --git a/theolive/media-engine/image-overlays.mdx b/theolive/media-engine/image-overlays.mdx new file mode 100644 index 000000000000..1092bf0c16bf --- /dev/null +++ b/theolive/media-engine/image-overlays.mdx @@ -0,0 +1,92 @@ +--- +sidebar_position: 4 +sidebar_label: Image overlays +sidebar_custom_props: + icon: 🖼️ +description: Add static image overlays like logos or watermarks to your live stream. +--- + +# Image overlays + +Image overlays let you burn static images — such as logos or watermarks — directly into your transcoded stream. Overlays are configured per engine and rendered on top of the video at the specified position and opacity. + +## Configuration + +Each engine supports one or more overlays. An overlay is defined by: + +| Property | Type | Required | Description | +| ---------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------- | +| `url` | `string` | Yes | URL of the overlay image. | +| `position` | `object` | No | Where to place the overlay on the video frame. If omitted, the image is placed at the top-left corner (0, 0). | +| `opacity` | `number` | No | Overlay opacity, from `0` (invisible) to `1` (fully visible). Defaults to `1`. | + +### Position + +The `position` object accepts the following properties, all specified in **pixels**: + +| Property | Type | Description | +| -------- | -------- | ----------------------------------------------------- | +| `top` | `number` | Distance from the top edge of the video frame. | +| `bottom` | `number` | Distance from the bottom edge. Ignored if `top` is set. | +| `left` | `number` | Distance from the left edge of the video frame. | +| `right` | `number` | Distance from the right edge. Ignored if `left` is set. | + +Use a combination of one vertical (`top` or `bottom`) and one horizontal (`left` or `right`) property to anchor the overlay. + +## API example + +Add a logo overlay in the bottom-right corner when [creating](../api/create-channel-engine.api.mdx) or [updating](../api/update-engine.api.mdx) an engine: + +`POST https://api.theo.live/v2/channels/{channelId}/engines` + +```json +{ + "name": "my-engine", + "region": "europe-west", + "quality": { + "abrLadderId": "your-abr-ladder-id" + }, + "overlays": [ + { + "url": "https://example.com/logo.png", + "position": { + "bottom": 20, + "right": 20 + }, + "opacity": 0.8 + } + ] +} +``` + +### Multiple overlays + +You can add multiple overlays to a single engine. For example, a logo in the bottom-right and a "LIVE" badge in the top-left: + +```json +{ + "overlays": [ + { + "url": "https://example.com/logo.png", + "position": { + "bottom": 20, + "right": 20 + } + }, + { + "url": "https://example.com/live-badge.png", + "position": { + "top": 10, + "left": 10 + }, + "opacity": 0.9 + } + ] +} +``` + +## Notes + +- Use **PNG images with transparency** for clean overlays that blend naturally with the video. +- The overlay is burned into the transcoded output, so it will appear on all quality levels and all output protocols. +- To remove overlays, update the engine with an empty `overlays` array. From 1246f04ab9db7ffe2ce0b65e5e05d7cc1789a003 Mon Sep 17 00:00:00 2001 From: Jeroen Tempels Date: Fri, 3 Apr 2026 14:00:25 +0200 Subject: [PATCH 2/7] Refine image overlays page: add ingest resolution note, simplify examples --- theolive/media-engine/image-overlays.mdx | 30 ++---------------------- 1 file changed, 2 insertions(+), 28 deletions(-) diff --git a/theolive/media-engine/image-overlays.mdx b/theolive/media-engine/image-overlays.mdx index 1092bf0c16bf..6a3c386038c9 100644 --- a/theolive/media-engine/image-overlays.mdx +++ b/theolive/media-engine/image-overlays.mdx @@ -31,7 +31,7 @@ The `position` object accepts the following properties, all specified in **pixel | `left` | `number` | Distance from the left edge of the video frame. | | `right` | `number` | Distance from the right edge. Ignored if `left` is set. | -Use a combination of one vertical (`top` or `bottom`) and one horizontal (`left` or `right`) property to anchor the overlay. +Use a combination of one vertical (`top` or `bottom`) and one horizontal (`left` or `right`) property to anchor the overlay. The pixel values are relative to the **ingest resolution** (i.e. the width and height of the incoming source stream). ## API example @@ -59,34 +59,8 @@ Add a logo overlay in the bottom-right corner when [creating](../api/create-chan } ``` -### Multiple overlays - -You can add multiple overlays to a single engine. For example, a logo in the bottom-right and a "LIVE" badge in the top-left: - -```json -{ - "overlays": [ - { - "url": "https://example.com/logo.png", - "position": { - "bottom": 20, - "right": 20 - } - }, - { - "url": "https://example.com/live-badge.png", - "position": { - "top": 10, - "left": 10 - }, - "opacity": 0.9 - } - ] -} -``` - ## Notes - Use **PNG images with transparency** for clean overlays that blend naturally with the video. - The overlay is burned into the transcoded output, so it will appear on all quality levels and all output protocols. -- To remove overlays, update the engine with an empty `overlays` array. +- To remove overlays, update the engine with an empty `overlays` array and restart the engine. From 5016ad9f9aa7f31f3ff8a9cb4cd635ac2f1d4ca3 Mon Sep 17 00:00:00 2001 From: Jeroen Tempels Date: Fri, 3 Apr 2026 14:19:59 +0200 Subject: [PATCH 3/7] Add usage monitoring page with transcoding, viewing minutes and bytes transferred API docs --- theolive/platform/usage.mdx | 104 ++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 theolive/platform/usage.mdx diff --git a/theolive/platform/usage.mdx b/theolive/platform/usage.mdx new file mode 100644 index 000000000000..cf8917d96b36 --- /dev/null +++ b/theolive/platform/usage.mdx @@ -0,0 +1,104 @@ +--- +sidebar_position: 20 +sidebar_label: Usage monitoring +sidebar_custom_props: + icon: 📊 +description: Track viewing minutes, bytes transferred, and transcoding minutes per channel. +--- + +# Usage monitoring + +The usage monitoring page lets you track how your streams are consumed and how much transcoding capacity is used. The [dashboard](https://dashboard.optiview.dolby.com/) shows these metrics visually under **Streaming → Usage monitoring**. You can also query them directly through the API. + +Your usage — and pricing — is made up of two independent components: + +1. **Transcoding** — the time your engines spend actively transcoding video. This is measured in **transcoding minutes**. +2. **Viewing** — the consumption by your viewers. Depending on your contract, this is measured either in **viewing minutes** (time spent watching) or **bytes transferred** (data delivered). + +## Common parameters + +All three endpoints share the same base parameters: + +| Parameter | Type | Required | Description | +| ------------ | -------- | -------- | --------------------------------------------------------------------------- | +| `start` | `string` | Yes | Start date for the analytics period. | +| `end` | `string` | Yes | End date for the analytics period. | +| `resolution` | `string` | Yes | Time granularity: `15min`, `hour`, `day`, or `month`. | +| `utcOffset` | `string` | No | UTC offset in minutes. Adjusts how data points align to time boundaries. | + +## Viewing minutes + +Returns how many minutes viewers spent watching a channel's streams. + +`GET https://api.theo.live/v2/channels/{channelId}/analytics/viewing-minutes` + +| Parameter | Type | Required | Description | +| ----------------- | -------- | -------- | ---------------------------------------------------------------- | +| `groupBy` | `string` | No | `channel`, `distribution`, or `streaming-format`. | +| `distributionIds` | `string` | No | Comma-separated list of distribution IDs to filter by. | +| `streamingFormats` | `string` | No | Comma-separated list of streaming formats to filter by. | + +### Example + +``` +GET /v2/channels/{channelId}/analytics/viewing-minutes?start=2025-01-01&end=2025-01-31&resolution=day&groupBy=distribution +``` + +## Bytes transferred + +Returns the total amount of data delivered to viewers for a channel. + +`GET https://api.theo.live/v2/channels/{channelId}/analytics/bytes-transferred` + +| Parameter | Type | Required | Description | +| ------------------ | -------- | -------- | ---------------------------------------------------------------- | +| `groupBy` | `string` | No | `channel`, `distribution`, or `streaming-format`. | +| `streamingFormats` | `string` | No | Comma-separated list of streaming formats to filter by. | + +### Example + +``` +GET /v2/channels/{channelId}/analytics/bytes-transferred?start=2025-01-01&end=2025-01-31&resolution=day&groupBy=streaming-format +``` + +## Transcoding minutes + +Returns how many minutes of transcoding capacity was used by a channel's engines. + +`GET https://api.theo.live/v2/channels/{channelId}/analytics/transcoding-minutes` + +| Parameter | Type | Required | Description | +| ----------- | -------- | -------- | ---------------------------------------------------------------- | +| `groupBy` | `string` | No | `engine` or `channel`. | +| `engineIds` | `string` | No | Comma-separated list of engine IDs to filter by. | + +### Example + +``` +GET /v2/channels/{channelId}/analytics/transcoding-minutes?start=2025-01-01&end=2025-01-31&resolution=month&groupBy=engine +``` + +## Response format + +All three endpoints return the same response structure: + +```json +{ + "data": [ + { + "timestamp": "2025-01-01T00:00:00.000Z", + "records": [ + { + "id": "channel-id-or-group-id", + "amount": 1234.5 + } + ] + } + ] +} +``` + +- **`timestamp`** — the start of the time bucket, based on the chosen `resolution`. +- **`records`** — one entry per group (e.g. per distribution, per engine). When no `groupBy` is specified, there is a single record per bucket. + - **`id`** — identifier of the grouped entity (channel ID, distribution ID, engine ID, or streaming format name). + - **`amount`** — the metric value for that time bucket. From df050d8645a871c2c0b611879188b1039bf11605 Mon Sep 17 00:00:00 2001 From: Jeroen Tempels Date: Fri, 3 Apr 2026 14:23:43 +0200 Subject: [PATCH 4/7] Change viewer insights icon to light bulb --- theolive/platform/viewer-insights.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/theolive/platform/viewer-insights.mdx b/theolive/platform/viewer-insights.mdx index cfc83d83b3be..4e74c6566dbb 100644 --- a/theolive/platform/viewer-insights.mdx +++ b/theolive/platform/viewer-insights.mdx @@ -2,7 +2,7 @@ sidebar_position: 7 sidebar_label: Viewer insights sidebar_custom_props: - icon: 📊 + icon: 💡 description: Monitor concurrent viewers, latency, locations and platforms in real time. --- From a0f3cbb70cc63889c76c6aa382edffb97c42b8a4 Mon Sep 17 00:00:00 2001 From: Jeroen Tempels Date: Fri, 3 Apr 2026 14:24:26 +0200 Subject: [PATCH 5/7] Fix prettier formatting --- theolive/media-engine/image-overlays.mdx | 18 +++++------ theolive/platform/usage.mdx | 38 ++++++++++++------------ 2 files changed, 28 insertions(+), 28 deletions(-) diff --git a/theolive/media-engine/image-overlays.mdx b/theolive/media-engine/image-overlays.mdx index 6a3c386038c9..aa7a25ba5711 100644 --- a/theolive/media-engine/image-overlays.mdx +++ b/theolive/media-engine/image-overlays.mdx @@ -14,21 +14,21 @@ Image overlays let you burn static images — such as logos or watermarks — di Each engine supports one or more overlays. An overlay is defined by: -| Property | Type | Required | Description | -| ---------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------- | -| `url` | `string` | Yes | URL of the overlay image. | -| `position` | `object` | No | Where to place the overlay on the video frame. If omitted, the image is placed at the top-left corner (0, 0). | -| `opacity` | `number` | No | Overlay opacity, from `0` (invisible) to `1` (fully visible). Defaults to `1`. | +| Property | Type | Required | Description | +| ---------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------- | +| `url` | `string` | Yes | URL of the overlay image. | +| `position` | `object` | No | Where to place the overlay on the video frame. If omitted, the image is placed at the top-left corner (0, 0). | +| `opacity` | `number` | No | Overlay opacity, from `0` (invisible) to `1` (fully visible). Defaults to `1`. | ### Position The `position` object accepts the following properties, all specified in **pixels**: -| Property | Type | Description | -| -------- | -------- | ----------------------------------------------------- | -| `top` | `number` | Distance from the top edge of the video frame. | +| Property | Type | Description | +| -------- | -------- | ------------------------------------------------------- | +| `top` | `number` | Distance from the top edge of the video frame. | | `bottom` | `number` | Distance from the bottom edge. Ignored if `top` is set. | -| `left` | `number` | Distance from the left edge of the video frame. | +| `left` | `number` | Distance from the left edge of the video frame. | | `right` | `number` | Distance from the right edge. Ignored if `left` is set. | Use a combination of one vertical (`top` or `bottom`) and one horizontal (`left` or `right`) property to anchor the overlay. The pixel values are relative to the **ingest resolution** (i.e. the width and height of the incoming source stream). diff --git a/theolive/platform/usage.mdx b/theolive/platform/usage.mdx index cf8917d96b36..1e36ce602b43 100644 --- a/theolive/platform/usage.mdx +++ b/theolive/platform/usage.mdx @@ -19,12 +19,12 @@ Your usage — and pricing — is made up of two independent components: All three endpoints share the same base parameters: -| Parameter | Type | Required | Description | -| ------------ | -------- | -------- | --------------------------------------------------------------------------- | -| `start` | `string` | Yes | Start date for the analytics period. | -| `end` | `string` | Yes | End date for the analytics period. | -| `resolution` | `string` | Yes | Time granularity: `15min`, `hour`, `day`, or `month`. | -| `utcOffset` | `string` | No | UTC offset in minutes. Adjusts how data points align to time boundaries. | +| Parameter | Type | Required | Description | +| ------------ | -------- | -------- | ------------------------------------------------------------------------ | +| `start` | `string` | Yes | Start date for the analytics period. | +| `end` | `string` | Yes | End date for the analytics period. | +| `resolution` | `string` | Yes | Time granularity: `15min`, `hour`, `day`, or `month`. | +| `utcOffset` | `string` | No | UTC offset in minutes. Adjusts how data points align to time boundaries. | ## Viewing minutes @@ -32,11 +32,11 @@ Returns how many minutes viewers spent watching a channel's streams. `GET https://api.theo.live/v2/channels/{channelId}/analytics/viewing-minutes` -| Parameter | Type | Required | Description | -| ----------------- | -------- | -------- | ---------------------------------------------------------------- | -| `groupBy` | `string` | No | `channel`, `distribution`, or `streaming-format`. | -| `distributionIds` | `string` | No | Comma-separated list of distribution IDs to filter by. | -| `streamingFormats` | `string` | No | Comma-separated list of streaming formats to filter by. | +| Parameter | Type | Required | Description | +| ------------------ | -------- | -------- | ------------------------------------------------------- | +| `groupBy` | `string` | No | `channel`, `distribution`, or `streaming-format`. | +| `distributionIds` | `string` | No | Comma-separated list of distribution IDs to filter by. | +| `streamingFormats` | `string` | No | Comma-separated list of streaming formats to filter by. | ### Example @@ -50,10 +50,10 @@ Returns the total amount of data delivered to viewers for a channel. `GET https://api.theo.live/v2/channels/{channelId}/analytics/bytes-transferred` -| Parameter | Type | Required | Description | -| ------------------ | -------- | -------- | ---------------------------------------------------------------- | -| `groupBy` | `string` | No | `channel`, `distribution`, or `streaming-format`. | -| `streamingFormats` | `string` | No | Comma-separated list of streaming formats to filter by. | +| Parameter | Type | Required | Description | +| ------------------ | -------- | -------- | ------------------------------------------------------- | +| `groupBy` | `string` | No | `channel`, `distribution`, or `streaming-format`. | +| `streamingFormats` | `string` | No | Comma-separated list of streaming formats to filter by. | ### Example @@ -67,10 +67,10 @@ Returns how many minutes of transcoding capacity was used by a channel's engines `GET https://api.theo.live/v2/channels/{channelId}/analytics/transcoding-minutes` -| Parameter | Type | Required | Description | -| ----------- | -------- | -------- | ---------------------------------------------------------------- | -| `groupBy` | `string` | No | `engine` or `channel`. | -| `engineIds` | `string` | No | Comma-separated list of engine IDs to filter by. | +| Parameter | Type | Required | Description | +| ----------- | -------- | -------- | ------------------------------------------------ | +| `groupBy` | `string` | No | `engine` or `channel`. | +| `engineIds` | `string` | No | Comma-separated list of engine IDs to filter by. | ### Example From 61b6337eade9ccd30eefb1b0b8e35224ae4de595 Mon Sep 17 00:00:00 2001 From: Jeroen Tempels Date: Fri, 3 Apr 2026 15:48:12 +0200 Subject: [PATCH 6/7] Add THEOlive engine changelog fetched from S3 --- .gitignore | 1 + package.json | 5 +++-- scripts/fetch-theolive-changelog.mjs | 22 ++++++++++++++++++++++ sidebarsTheolive.ts | 1 + 4 files changed, 27 insertions(+), 2 deletions(-) create mode 100644 scripts/fetch-theolive-changelog.mjs diff --git a/.gitignore b/.gitignore index ab474137bea2..a90a143b2321 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ .docusaurus .cache-loader static/theoplayer-license.txt +theolive/changelog.md # Misc .DS_Store diff --git a/package.json b/package.json index eca1017a6ae0..a14a2a83fe73 100644 --- a/package.json +++ b/package.json @@ -5,14 +5,15 @@ "scripts": { "docusaurus": "docusaurus", "start": "docusaurus start", - "prestart": "npm run gen-api-docs", + "prestart": "npm run gen-api-docs && npm run fetch-theolive-changelog", "build": "docusaurus build", - "prebuild": "npm run gen-api-docs", + "prebuild": "npm run gen-api-docs && npm run fetch-theolive-changelog", "swizzle": "docusaurus swizzle", "clear": "docusaurus clear", "serve": "node serve.js", "write-translations": "docusaurus write-translations", "write-heading-ids": "docusaurus write-heading-ids", + "fetch-theolive-changelog": "node scripts/fetch-theolive-changelog.mjs", "gen-api-docs": "docusaurus gen-api-docs all --plugin-id ads-api && docusaurus gen-api-docs all --plugin-id ad-engine-api && docusaurus gen-api-docs all --plugin-id millicast-api && docusaurus gen-api-docs all --plugin-id theolive-api --all-versions", "clean-api-docs": "docusaurus clean-api-docs all --plugin-id ads-api && docusaurus clean-api-docs all --plugin-id ad-engine-api && docusaurus clean-api-docs all --plugin-id millicast-api && docusaurus clean-api-docs all --plugin-id theolive-api --all-versions", "typecheck": "tsc", diff --git a/scripts/fetch-theolive-changelog.mjs b/scripts/fetch-theolive-changelog.mjs new file mode 100644 index 000000000000..db8108deb159 --- /dev/null +++ b/scripts/fetch-theolive-changelog.mjs @@ -0,0 +1,22 @@ +import fs from 'fs'; +import path from 'path'; +import { fileURLToPath } from 'url'; + +const __dirname = path.dirname(fileURLToPath(import.meta.url)); +const url = 'https://engine-changelog.s3.eu-west-3.amazonaws.com/CHANGELOG.md'; +const outputPath = path.join(__dirname, '..', 'theolive', 'changelog.md'); + +try { + const response = await fetch(url); + if (!response.ok) { + throw new Error(`Failed to fetch changelog: ${response.status} ${response.statusText}`); + } + const content = await response.text(); + fs.writeFileSync(outputPath, content); + console.log('Fetched THEOlive engine changelog.'); +} catch (error) { + console.warn(`Warning: Could not fetch THEOlive engine changelog: ${error.message}`); + if (!fs.existsSync(outputPath)) { + fs.writeFileSync(outputPath, '# Changelog\n\nChangelog could not be fetched.\n'); + } +} diff --git a/sidebarsTheolive.ts b/sidebarsTheolive.ts index ce2f7368b273..5026e893467f 100644 --- a/sidebarsTheolive.ts +++ b/sidebarsTheolive.ts @@ -80,6 +80,7 @@ const sidebars: SidebarsConfig = { }, href: '/theolive/next/api/', }, + 'changelog', 'api/migration-from-v1', ], theoLiveApi: [ From 4937d37f15e7e0c7ee9d6ec536e958e92e162469 Mon Sep 17 00:00:00 2001 From: jeroentempels-dolby Date: Fri, 3 Apr 2026 15:59:39 +0200 Subject: [PATCH 7/7] Remove details to prevent docs from getting outdated Co-authored-by: Gilles Moris (Dolby x THEO) <165768935+GillesMoris-Dolby@users.noreply.github.com> --- theolive/platform/usage.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/theolive/platform/usage.mdx b/theolive/platform/usage.mdx index 1e36ce602b43..ae498ee3c12e 100644 --- a/theolive/platform/usage.mdx +++ b/theolive/platform/usage.mdx @@ -8,7 +8,7 @@ description: Track viewing minutes, bytes transferred, and transcoding minutes p # Usage monitoring -The usage monitoring page lets you track how your streams are consumed and how much transcoding capacity is used. The [dashboard](https://dashboard.optiview.dolby.com/) shows these metrics visually under **Streaming → Usage monitoring**. You can also query them directly through the API. +The usage monitoring page lets you track how your streams are consumed and how much transcoding capacity is used. The [dashboard](https://dashboard.optiview.dolby.com/) shows these metrics visually. You can also query them directly through the API. Your usage — and pricing — is made up of two independent components: