Skip to content

Document plugin video configuration fields #239

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gabek wants to merge 2 commits into
base: owncast-docusaurus
Choose a base branch
from
Open

Document plugin video configuration fields #239

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b35c849
docs(plugins): document video config fields
gabek Aug 5, 2026
ad47501
docs(plugins): clarify codec read values
gabek Aug 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 28 additions & 4 deletions docs/plugins/apis.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -666,7 +666,31 @@ Requires `server.read`.

### `owncast.videoConfig.read()`

Read the output and transcoding configuration: `{ latencyLevel, codec, variants }`, where each variant is `{ width, height, framerate, videoBitrate, audioBitrate, isPassthrough }`.
Returns the current `VideoConfig`.

| Field | Type | Values |
| --- | --- | --- |
| `latencyLevel` | number | `0` through `4` |
| `codec` | string | Configured ffmpeg encoder name |
| `autoplay` | string | `off`, `always`, or `sound-only` |
| `variants` | `StreamVariant[]` | Configured output renditions |

`codec` reads can report a legacy value or an encoder added by a newer host. Writes accept `libx264`, `h264_omx`, `h264_vaapi`, `h264_qsv`, `h264_nvenc`, `h264_v4l2m2m`, or `h264_videotoolbox`. Hardware codecs require the matching encoder in the host's ffmpeg build.

Autoplay `off` requires the viewer to press play. `always` starts automatically and may fall back to muted playback. `sound-only` starts automatically only when the browser allows sound.

Each `StreamVariant` has these fields:

| Field | Type | Description |
| --- | --- | --- |
| `width` | number | Scaled output width |
| `height` | number | Scaled output height |
| `framerate` | number | Output frames per second |
| `videoBitrate` | number | Video bitrate in kbps |
| `cpuUsageLevel` | number | Processing usage from `0` (lowest) through `4` (highest) |
| `isPassthrough` | boolean | Pass video through without transcoding |

Audio settings are not exposed to plugins. Owncast preserves the existing audio configuration for each variant a plugin updates.

<Tabs groupId="plugin-lang">
<TabItem value="js" label="JavaScript" default>
Expand All @@ -689,20 +713,20 @@ Requires `videoconfig.read`.

### `owncast.videoConfig.write(partial)`

Update video configuration. Pass a partial object. Only the fields you include are changed. Changes apply on the next stream start: the host does not restart an active broadcast.
Update any of the `VideoConfig` fields above. Pass a partial object. Only the fields you include are changed. Changes apply on the next stream start: the host does not restart an active broadcast.

<Tabs groupId="plugin-lang">
<TabItem value="js" label="JavaScript" default>

```js
owncast.videoConfig.write({ latencyLevel: 2 });
owncast.videoConfig.write({ latencyLevel: 2, autoplay: "sound-only" });
```

</TabItem>
<TabItem value="py" label="Python">

```python
owncast.video_config.write({"latencyLevel": 2})
owncast.video_config.write({"latencyLevel": 2, "autoplay": "sound-only"})
```

</TabItem>
Expand Down