# Owncast - Free and Open Source Livestreaming

> Free and Open Source Livestreaming

This file contains all documentation content in a single document following the llmstxt.org standard.

## Show Custom Action Buttons On Your Page

You can build additional interfaces that are hosted with any add-ons, extensions, or 3rd party sites. Each action is a single URL or custom HTML that will be loaded and displayed when a user presses a button on the Owncast page.

:::new[Plugin action buttons require Owncast v0.3.0]
Plugins can also contribute action buttons alongside the ones you register by hand. See the [plugin manifest](/docs/plugins/manifest) documentation.
:::

## Examples

Some examples of this functionality might be things like:

1. A leader board for some chat-based game you built or an external game you're playing on stream.
1. Lists of actions that perform fun animations on your stream overlays when selected.
1. Integrations with your polling chat bot that shows recent polls and the results.
1. Tip Jar to accept donations.
1. A schedule that is fancier or more interactive than what you can represent in Markdown.

## Limitations

1. URLs embedded via external actions must be hosted on a server that supports SSL and has a `https` protocol. Unsecured URLs are not supported.
1. These URLs must support existing inside an iframe. This means [X-FRAME-OPTIONS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options) and the [CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) cannot be blocking. If you are blocked then you're limited to loading this URL in a new tab and that's not a great experience.
1. While you can experiment with using URLs that you don't personally control, it's often likely that many of them will not work due to limitations placed on the remote server. An example of this is just throwing in a PayPal or Google URL.

## How to register actions

1. Visit the admin, and under "Integrations" go to the "External Actions" page.
1. Add an action.
1. Set the URL or custom HTML of this action. URLs should be a HTTPS destination and follow the best practices listed.
1. Give it a name that will be displayed on the button that launches this action, an optional description that will show in the modal that presents the action, a URL to an optional icon for the button, and optionally a color that will be used for the button.
1. If you really want to register a URL you don't control, but it doesn't work with the default functionality, you can tell it to "Open Externally" and it will open a new tab in your browser. This is not optimal, but it's an option.

## Query parameters passed to URL actions

When a viewer opens a URL action, Owncast appends query parameters to your URL:

- `instance` is always appended and holds the URL of the Owncast page the viewer is on. Useful if you host one action for multiple servers.
- `username` and `userId` are appended only when the viewer has a chat user. `username` is the display name, which is not unique. `userId` is a stable identifier for that chat user.

These parameters are conveniences, not authenticated identity. Anyone can open your URL with any values, so never grant access or make privileged API calls based on them. Use them to pre-fill forms and label sessions.

## The iframe sandbox

A URL action loads inside a modal in an iframe with `sandbox="allow-same-origin allow-scripts allow-popups allow-forms"`. Your page can run scripts, submit forms, and open popups, but it cannot navigate the top-level Owncast page or trigger downloads.

There is no postMessage bridge. An embedded action cannot close or resize the modal, and it has no way to call back into Owncast. Treat the action as a self-contained page.

## Best practices

1. This action's UI should perform little to no navigation. It shouldn't be treated as a way to show just any page.
1. Design your UI to live in a small window that doesn't require much, if any, scrolling, and is responsive to mobile and small displays.
1. Make sure your URL's server allows loading your content from your Owncast server via [X-FRAME-OPTIONS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options) and the [CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy).
1. The [query parameters](#query-parameters-passed-to-url-actions) Owncast appends tell you which server and which chat user opened the action. Use them to pre-fill forms, and remember they can be faked, so never treat them as proof of identity.
1. For HTML actions that include custom styling via `<style>` tags, you should make sure to have selectors that are as specific as possible, not colliding with any other elements in the page.
1. For HTML actions that directly embed a `<form>` element, it makes sense to set `target="_blank"` to open the submit page in a new tab. That way your viewers won't have to stop the stream when submitting the form.

---

## ActivityPub & The Fediverse Protocol


This page documents the [ActivityPub](https://www.w3.org/TR/activitypub/) implementation inside Owncast at the protocol level: which activities a server **sends**, which it **receives**, how it identifies itself, and how it signs and verifies requests. It is aimed at developers who want to build a Fediverse application that interoperates with Owncast, whether that means following an Owncast server from another platform, consuming its live notifications, or building tooling that understands Owncast's custom extensions.

If you are an Owncast operator and just want to turn federation on, see [The Fediverse](/docs/social/the-fediverse) and [Enabling social features](/docs/social#enabling-social-features) instead. This page assumes familiarity with ActivityPub, ActivityStreams 2.0, JSON-LD, and HTTP Signatures.

## Mental model

An Owncast server federates as a **single actor** of type `Service`. There is one account per server (default username `live`), and it represents the stream itself rather than a person. Compared to a general-purpose social server, the model is intentionally narrow:

- The actor **sends** posts to its followers (most importantly, a "going live" notification) and a periodic stream "ping".
- The actor **receives** follows, likes, boosts (announces), replies and mentions, quote requests, and a handful of server-to-server activities. Inbound posts are only surfaced to the operator and plugins: they are never added to a timeline and never re-federated.
- There is exactly one user, no open registration, and the `following` collection is always empty.

All federation endpoints return `405 Method Not Allowed` when federation is disabled, so check that first if a server appears unreachable.

## Discovery

A remote application locates and describes an Owncast actor through the standard well-known discovery mechanisms.

### WebFinger

```
GET /.well-known/webfinger?resource=acct:{username}@{host}
```

The `resource` must be an `acct:` URI whose host matches the server's configured host (otherwise the request is rejected with `501`/`400`). The response is served as `application/jrd+json`:

```json
{
  "subject": "acct:live@owncast.example.com",
  "aliases": ["https://owncast.example.com/federation/user/live"],
  "links": [
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://owncast.example.com/federation/user/live"
    },
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://owncast.example.com/federation/user/live"
    },
    {
      "rel": "http://webfinger.net/rel/avatar",
      "type": "image/png",
      "href": "https://owncast.example.com/logo/external"
    },
    {
      "rel": "alternate",
      "type": "application/x-mpegURL",
      "href": "https://owncast.example.com/hls/stream.m3u8"
    }
  ]
}
```

The `self` link is the canonical actor IRI. Note the Owncast-specific `alternate` link of type `application/x-mpegURL`: it points directly at the HLS playlist for the stream, which lets clients discover the live video without scraping the web UI.

### host-meta

```
GET /.well-known/host-meta
```

Returns an XRD document pointing back at the WebFinger endpoint, for clients that bootstrap from host-meta:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0">
  <Link rel="lrdd" type="application/json"
        template="https://owncast.example.com/.well-known/webfinger?resource={uri}"/>
</XRD>
```

### NodeInfo

Owncast exposes server-level metadata through [NodeInfo](https://nodeinfo.diaspora.software/) so that Fediverse crawlers, directories, and statistics sites can describe the instance.

**NodeInfo discovery** — `GET /.well-known/nodeinfo`:

```json
{
  "links": [
    {
      "rel": "http://nodeinfo.diaspora.software/ns/schema/2.0",
      "href": "https://owncast.example.com/nodeinfo/2.0"
    }
  ]
}
```

**NodeInfo 2.0** — `GET /nodeinfo/2.0`:

```json
{
  "version": "2.0",
  "software": {
    "name": "owncast",
    "version": "0.2.x"
  },
  "protocols": ["activitypub"],
  "services": {
    "inbound": [],
    "outbound": []
  },
  "usage": {
    "users": {
      "total": 1,
      "activeMonth": 1,
      "activeHalfyear": 1
    },
    "localPosts": 42
  },
  "openRegistrations": false,
  "metadata": {
    "chat_enabled": true,
    "federation": {
      "username": "live",
      "featured_streams": 1
    }
  }
}
```

Most of this is standard NodeInfo, with a few Owncast-specific signals worth calling out:

- **`software.name`** is always `owncast`. This is the most reliable way to detect that you are talking to an Owncast server.
- **`usage.users.total`** is always `1` and **`openRegistrations`** is always `false` — an Owncast instance is a single-actor server, not a multi-user community.
- **`usage.localPosts`** is the count of activities the server has sent (go-live notifications and other public messages), which is a useful proxy for how active the stream is.
- **`metadata.chat_enabled`** reflects whether Owncast's built-in chat is enabled.
- **`metadata.federation`** is the Owncast-specific block:
  - **`username`** is the actor's preferred username (default `live`). Combined with the host, this gives you the `acct:` handle without a separate WebFinger round-trip.
  - **`featured_streams`** indicates participation in the featured-streams / mini-directory flow (see [Stream pings](#offer--stream-ping-outbound) below). A value of `1` means the server advertises its live status to followers via periodic `Offer` activities.

**x-nodeinfo2** — `GET /.well-known/x-nodeinfo2` provides the same information in the alternate [x-nodeinfo2](https://github.com/jaywink/xnodeinfo2) shape used by some directories, including an `organization` block (`name`, `contact`) and an `activeWeek` user figure. Here `services.inbound`/`services.outbound` are both `["activitypub"]`.

**Mastodon instance API** — `GET /api/v1/instance` returns a Mastodon-compatible instance description (`uri`, `title`, `short_description`, `description`, `version`, `thumbnail`, `stats`, and registration flags) so Mastodon-aware tooling can render a familiar instance card. `stats.user_count` is `1`, `stats.status_count` is the local post count, and registrations/approval/invites are all disabled.

## The actor

```
GET /federation/user/{username}
Accept: application/activity+json
```

Requesting the actor IRI with an ActivityStreams `Accept` header returns the actor document. Owncast represents itself as an ActivityStreams **`Service`** (not a `Person`). The shape is:

```json
{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/security/v1"
  ],
  "type": "Service",
  "id": "https://owncast.example.com/federation/user/live",
  "preferredUsername": "live",
  "name": "My Owncast Server",
  "summary": "Server description / bio",
  "url": "https://owncast.example.com/federation/user/live",
  "published": "2023-01-01T00:00:00Z",
  "manuallyApprovesFollowers": false,
  "discoverable": true,
  "inbox": "https://owncast.example.com/federation/user/live/inbox",
  "outbox": "https://owncast.example.com/federation/user/live/outbox",
  "followers": "https://owncast.example.com/federation/user/live/followers",
  "icon": {
    "type": "Image",
    "mediaType": "image/png",
    "url": "https://owncast.example.com/logo/external?uc=..."
  },
  "image": {
    "type": "Image",
    "url": "https://owncast.example.com/logo/external?uc=..."
  },
  "tag": [
    {
      "type": "Hashtag",
      "name": "#owncast",
      "href": "https://owncast.directory/tags/owncast"
    }
  ],
  "attachment": [
    {
      "type": "PropertyValue",
      "name": "Website",
      "value": "..."
    }
  ],
  "publicKey": {
    "id": "https://owncast.example.com/federation/user/live#main-key",
    "owner": "https://owncast.example.com/federation/user/live",
    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
  }
}
```

Key points for an interoperating implementation:

- **Actor IRI layout** is `{server}/federation/user/{username}`, and the collections hang off it: `{actor}/inbox`, `{actor}/outbox`, `{actor}/followers`.
- **`following`** is requested at `{actor}/following` but always returns `404` — Owncast never exposes a following list.
- **`manuallyApprovesFollowers`** reflects whether the server is in _private_ federation mode. When `true`, follows are not auto-accepted.
- **`discoverable`** is always `true` (using the `toot:` namespace semantics).
- The **public key** lives at `{actor}#main-key`, is an RSA-2048 key in PEM (PKIX) form, and is what you use to verify the server's HTTP signatures.

## HTTP Signatures

Owncast both signs its outbound requests and verifies inbound ones using the "Signature" HTTP header scheme ([draft-cavage HTTP signatures](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures), as used across the Fediverse).

### Verifying requests Owncast sends to you

When Owncast POSTs an activity to your inbox it includes:

- A `Signature` header with `keyId="{actor}#main-key"`, `algorithm="rsa-sha256"`, and the signed `headers` list.
- The signed headers cover `(request-target)`, `host`, `date`, and `digest`.
- A `Digest` header containing the SHA-256 digest of the request body.
- `Content-Type: application/activity+json` and a `User-Agent` of the form `{version}; https://owncast.online`.

To verify: fetch the actor at `keyId`, read `publicKey.publicKeyPem`, and verify both the signature and the body digest.

### Signing requests you send to Owncast

Owncast verifies the signature on every activity delivered to its inbox:

1. It parses `keyId` and `algorithm` from your `Signature` header. The `keyId` **must** be an `https://` URL.
2. It resolves your actor and fetches your public key.
3. It checks that your key's owning domain is **not** on the instance's blocked-domains list and that the actor itself is not blocked.
4. It verifies the signature, trying the stated algorithm and then falling back to `rsa-sha256` and `rsa-sha512`.
5. It verifies the `Digest` header against the request body.
6. If your request carries a parseable `Date` header, it must be close to the server's clock: a date more than 1 hour in the past or more than 1 hour in the future is rejected. This bounds replay of captured, validly-signed requests. A missing or unparseable `Date` skips the check.

In practice this means: sign `(request-target) host date digest` with an RSA key, publish that key in your actor's `publicKey` field, include a SHA-256 `Digest`, and serve your actor over HTTPS.

## Activities Owncast sends (outbound)

All outbound activities originate from the server actor and are delivered to follower inboxes (preferring `sharedInbox` where a follower advertises one). Public activities are addressed to `https://www.w3.org/ns/activitystreams#Public` in `to` with the followers collection in `cc`; in private mode they are addressed only to the followers collection.

| Activity | Object           | When                                                               | Sent to              |
| -------- | ---------------- | ------------------------------------------------------------------ | -------------------- |
| `Create` | `Note`           | The stream goes live (the "go live" message); other public posts   | Followers (+ Public) |
| `Update` | `Service`        | The server profile (name, avatar, summary, etc.) changes           | Followers            |
| `Follow` | actor IRI        | An operator follows another Owncast server (featured-streams flow) | The target server    |
| `Offer`  | server URL       | Periodically while live, as a stream "ping"                        | Directory followers  |
| `Accept` | inbound `Follow` | In response to a received `Follow`                                 | The follower         |
| `Reject` | inbound `Follow` | When the operator removes a directory that was listing this server | That directory       |
| `Leave`  | server URL       | The stream ends (the offline counterpart to `Offer`)                | Directory followers  |
| `Undo`   | `Follow`         | An operator unfeatures an Owncast server they previously followed   | The target server    |
| `Accept` / `Reject` | inbound `QuoteRequest` | In response to a received [`QuoteRequest`](#quote-requests-fep-044f) | The requester |

### Create / Note — going live

The most important activity. When the stream goes live, Owncast sends a `Create` wrapping a `Note`. The `Note` contains HTML `content` (the configurable go-live message, stream title, hashtag links, and a link back to the server), `Hashtag` tags, and — when available — an `Image` attachment with the stream preview (`preview.gif` or `thumbnail.jpg`). If the server is marked NSFW, the note carries `sensitive: true`. Hashtags link to `https://owncast.directory/tags/{tag}`, and an `#owncast` hashtag is always appended.

This is the activity most consumers care about: subscribe by following the actor, then watch the inbox for `Create`/`Note` activities to know when a stream starts.

### Offer / stream ping (outbound)

This is an Owncast extension that supports the **featured-streams / mini-directory** feature. While live, the server periodically sends an `Offer` activity whose `object` is the server URL, carrying [Owncast custom metadata](#owncast-custom-namespace) (stream status, title, description, server name, logo, tags). It lets a receiving directory keep its list of live streams fresh without polling. The matching offline signal is the [`Leave`](#server-to-server-activities) activity, sent when the stream ends. Owncast sends `Offer` and `Leave` only to followers that identified themselves as a directory (see [the custom namespace](#owncast-custom-namespace)), never to ordinary fan followers.

### Update, Follow, Accept

- **`Update`** of the `Service` actor is sent to followers when the server's profile metadata changes, so remote caches refresh.
- **`Follow`** is sent when an operator follows another Owncast server. The server then expects an `Accept` (or `Reject`) back.
- **`Accept`** is sent automatically in response to an inbound `Follow` when the server is in public (auto-approve) mode.

## Activities Owncast receives (inbound)

Deliver these by POSTing a signed activity to the actor's `inbox`. The inbox returns `202 Accepted` immediately and processes the activity asynchronously, so a `202` only means the activity was queued, not that it was acted on. Owncast signature-verifies and dispatches each one from that queue.

| Activity                      | Handling                                                                                                                                                                                                                                                                                                |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Follow`                      | Stores the follower; auto-approves and returns `Accept` in public mode (held for approval in private mode). A follow carrying the `ns#directory` marker is always held for manual approval regardless of mode, and does not emit the follow event. Otherwise emits a `FediverseEngagementFollow` event. |
| `Undo` → `Follow`             | Removes the follower.                                                                                                                                                                                                                                                                                   |
| `Like`                        | Records an engagement against a local object. Emits `FediverseEngagementLike`.                                                                                                                                                                                                                          |
| `Announce`                    | Boost/repost of a local object. Records an engagement and emits `FediverseEngagementRepost`.                                                                                                                                                                                                            |
| `Accept` → `Follow`           | Marks a remote Owncast server we followed as having accepted (featured-streams flow).                                                                                                                                                                                                                   |
| `Reject` → `Follow`           | Marks our follow of a remote server as rejected.                                                                                                                                                                                                                                                        |
| `Offer`                       | A stream ping from another Owncast server. If it carries `streamStatus: "live"` Owncast marks that server online in its federated-servers table and stores the streamed metadata.                                                                                                                       |
| `Leave`                       | The offline counterpart to `Offer`: marks the remote Owncast server's stream offline.                                                                                                                                                                                                                   |
| `Update` → `Person`           | Updates stored metadata (display name, inbox, shared inbox, avatar) for an existing follower. Updates with any other object type are ignored.                                                                                                                                            |
| `Create` → `Note`             | Accepted when the object is a single `Note` attributed to the signing actor and the note is either a reply to a post this server published or addressed to the actor (a mention). Raised as an event for the operator and plugins, not added to any timeline. See [inbound posts](#inbound-posts-create). |
| `QuoteRequest`                | A [FEP-044f](https://codeberg.org/fediverse/fep/src/branch/main/fep/044f/fep-044f.md) request to quote one of the server's posts. Accepted only for locally authored posts while federation is public and quotes are enabled. Answered with `Accept` or `Reject`. See [quote requests](#quote-requests-fep-044f). |

Two important guards:

- **Engagement age limit.** `Like` and `Announce` activities are only recorded if the referenced object is no more than **36 hours** old. Older engagements are ignored. This keeps engagement notifications tied to recent streams.
- **Blocking & SSRF.** Inbound activities from blocked domains/actors are rejected during signature verification. Outbound deliveries refuse non-HTTPS and internal/loopback inbox URLs.

### Inbound posts (Create)

:::new[Inbound fediverse posts require Owncast v0.3.0]
Earlier releases rejected every inbound `Create`. Owncast 0.3.0 accepts the narrow cases described here.
:::

Owncast accepts a `Create` whose object is exactly one `Note` attributed to the same actor that sent it. It keeps two kinds of notes: replies to a post the server itself published, and notes that address the actor directly (mentions). Everything else is ignored. An accepted post is raised as a reply or mention event for the operator's integrations and plugins. It is not added to a timeline, is not shown to viewers, and is never re-federated, so there is still no public conversation surface on an Owncast server.

### Quote requests (FEP-044f)

:::new[Quote requests require Owncast v0.3.0]
`QuoteRequest` handling is new in Owncast 0.3.0.
:::

A remote user asking permission to quote one of the server's posts sends a [FEP-044f](https://codeberg.org/fediverse/fep/src/branch/main/fep/044f/fep-044f.md) `QuoteRequest` whose `object` is the post being quoted and whose `instrument` is the quote post itself. Owncast accepts the request only when the quoted object is a post this server authored, federation is in public mode, and the operator has quoting enabled. On accept it stores a `QuoteAuthorization` stamp as a dereferenceable object and replies with an `Accept` whose `result` is the stamp's IRI, so any server can fetch the stamp to verify the quote was approved. Every other case gets a `Reject`, which clears the pending quote on the remote end.

### Server-to-server activities

`Offer`, `Leave`, `Accept`, and `Reject` together form the Owncast-to-Owncast "featured streams" protocol. If you are building a directory or aggregator that wants to participate, the pattern is:

1. Send a `Follow` that sets the `ns#directory` marker (see [the custom namespace](#owncast-custom-namespace)) to the Owncast server's actor. The operator approves it by hand, then expect an `Accept`.
2. Receive periodic `Offer` activities (with Owncast metadata) while the server is live.
3. Receive a `Leave` when the stream ends.

You can equally consume only the standard `Create`/`Note` go-live posts if you do not need real-time liveness pings.

## Owncast custom namespace

Owncast adds a small set of custom JSON-LD properties under the namespace **`https://owncast.online/ns#`**. The stream-metadata properties appear as extra top-level fields on `Offer` (and related server-to-server) activities and let a receiver populate a directory entry from a single activity. The `ns#directory` marker appears on a `Follow` and identifies the sender as a directory. All are optional and safe to ignore if you only care about standard ActivityPub.

| Property                                      | Type             | Meaning                                                                 |
| --------------------------------------------- | ---------------- | ----------------------------------------------------------------------- |
| `https://owncast.online/ns#streamStatus`      | string           | `"live"` or `"offline"`. Always present on server-to-server activities. |
| `https://owncast.online/ns#streamTitle`       | string           | Current stream title, when set.                                         |
| `https://owncast.online/ns#streamDescription` | string           | Server summary / description.                                           |
| `https://owncast.online/ns#serverName`        | string           | Human-readable server name.                                             |
| `https://owncast.online/ns#logoUrl`           | string           | Absolute URL to the server logo.                                        |
| `https://owncast.online/ns#thumbnailUrl`      | string           | Absolute URL to the current stream thumbnail.                           |
| `https://owncast.online/ns#streamTags`        | array of strings | Server metadata tags.                                                   |
| `https://owncast.online/ns#directory`         | boolean          | Set to `true` on a `Follow` to identify the sender as a directory.      |

A directory identifies itself by setting `ns#directory` to `true` on the `Follow` it sends. That marker, and only that marker, makes Owncast treat the follow as a directory listing: it holds the follow for the operator to approve, and once approved, delivers the `Offer` and `Leave` stream pings to that follower. The stream-metadata fields above are descriptive only and do not, on their own, identify a directory.

## Building a directory of Owncast streams

The server-to-server activities that power Owncast's own [featured streams](/docs/social/featured-streams) feature are open for you to consume. If you want to run a directory or aggregator that tracks which Owncast servers are live, you follow each server the way any Fediverse actor would and then react to the liveness signals it sends.

For a complete, runnable example reference, see the [owncast-directory-example](https://github.com/owncast/owncast-directory-example) repository. It is a small Python application that implements everything in this section: a published actor, the `ns#directory` follow, the `Offer`/`Leave`/`Reject` handling, and a web page that lists the live servers. Treat it as a starting point rather than a production service.

You need a published actor and signed requests, the same as any follower (see [HTTP Signatures](#http-signatures)). From there:

1. Send a signed `Follow` that sets `https://owncast.online/ns#directory` to `true` (see [the custom namespace](#owncast-custom-namespace)) to each server's actor. That marker identifies you as a directory, which is what makes the server deliver its stream pings to you, and it makes being listed opt-in: an Owncast server always holds a directory follow for its operator to approve by hand, no matter how the server's federation privacy is configured. You will not receive any status until the operator approves, so expect entries to stay pending until each one opts in. A `Follow` without the marker is treated as an ordinary fan follow: it may be auto-accepted, but it will never receive the `Offer`/`Leave` pings.
2. While a server is live it posts an `Offer` to your inbox roughly every 5 minutes, carrying the [Owncast custom metadata](#owncast-custom-namespace): stream status, title, description, server name, logo, thumbnail, and tags. Create or refresh that server's directory entry from those fields.
3. When the stream ends cleanly the server posts a `Leave`. Mark the entry offline.
4. If the server's operator removes your directory from their side, the server posts a `Reject` of your original `Follow`. Drop the entry: you are no longer authorized to list that server, and it will stop sending you pings.

There is no built-in flow for an Owncast server to request a spot in your directory, so assembling the list is your side's job. A simple way to let operators opt in is to put a submission form on your directory where an operator enters their server URL. You and your directory decide which submissions to list and which to turn away. When you accept one, follow that server the same way as above. The operator approves the follow, which a submitter will be expecting to do, and the follow, accept, and ping flow lists their stream.

Treat the pings as a heartbeat. If a server stops sending `Offer` activities without a `Leave`, because it crashed, lost connectivity, or was firewalled, nothing actively tells you it went down. Expire any entry you have not heard from in a couple of ping intervals. Owncast's own directory marks a peer offline after two missed pings, about 11 minutes, and runs that staleness check once a minute.

A few things worth getting right:

- The metadata fields come from the remote server, so treat them as untrusted input. Clamp lengths and confirm that any URL is `http` or `https` before you render it. The value you can trust is the server URL you chose to follow, not the display name the server sends.
- The thumbnail and logo URLs are stable, so the browser will cache them. Append a changing cache-busting query when you refresh an entry if you want the preview to stay current.
- You do not have to use the pings at all. If you only need to know that a server went live, rather than keep a running view of who is live right now, follow the actor and watch for the standard `Create`/`Note` go-live posts like any other Fediverse consumer.

To have your service recognized as a directory, set `https://owncast.online/ns#directory` to `true` on the `Follow` you send. A server that sees it holds the follow for its operator and, once approved, sends you its stream pings.

## Endpoint reference

All paths are relative to the server's base URL. Every endpoint returns `405` when federation is disabled.

| Path                                    | Method | Purpose                                      |
| --------------------------------------- | ------ | -------------------------------------------- |
| `/.well-known/webfinger`                | GET    | Resolve `acct:` → actor IRI                  |
| `/.well-known/host-meta`                | GET    | XRD pointer to WebFinger                     |
| `/.well-known/nodeinfo`                 | GET    | NodeInfo discovery document                  |
| `/nodeinfo/2.0`                         | GET    | NodeInfo 2.0 server metadata                 |
| `/.well-known/x-nodeinfo2`              | GET    | x-nodeinfo2 server metadata                  |
| `/api/v1/instance`                      | GET    | Mastodon-compatible instance description     |
| `/federation/user/{username}`           | GET    | The `Service` actor document                 |
| `/federation/user/{username}/inbox`     | POST   | Deliver activities to the server             |
| `/federation/user/{username}/outbox`    | GET    | Collection of activities the server has sent |
| `/federation/user/{username}/followers` | GET    | Paginated followers collection               |
| `/federation/user/{username}/following` | GET    | Always `404` (no following list)             |
| `/federation/{object-id}`               | GET    | Fetch a single stored ActivityPub object     |

## Building a compatible application — checklist

To follow and consume an Owncast stream from your own application:

1. **Resolve** the handle with WebFinger (`acct:live@host`) to get the actor IRI, then fetch the actor with `Accept: application/activity+json`.
2. **Publish your own actor** with a `publicKey`, served over HTTPS, with a reachable `inbox`.
3. **Send a signed `Follow`** to the actor's inbox. Sign `(request-target) host date digest` with RSA and include a SHA-256 `Digest`.
4. **Handle the `Accept`** that Owncast posts back to your inbox (public mode) — or wait for manual approval (private mode).
5. **Listen for go-live posts**: `Create`/`Note` activities arriving in your inbox tell you the stream started; the `alternate`/`application/x-mpegURL` WebFinger link gives you the HLS URL to play.
6. **Optionally** act as a directory: set `https://owncast.online/ns#directory` to `true` on your `Follow`, have the operator approve it, then consume the `Offer`/`Leave` pings and the `https://owncast.online/ns#*` metadata for real-time liveness and richer directory entries.
7. **Verify** the signature on everything Owncast sends you against the actor's `#main-key`.

Owncast accepts replies and mentions only as notifications for the operator and plugins: they are never threaded, displayed, or re-federated, and the server exposes no `following` list. Design your integration around following + notifications + likes/boosts rather than two-way conversation.

---

## Owncast Web APIs

The web APIs are how code running outside Owncast talks to your server over HTTP. They come in two halves:

- [**Webhooks**](/docs/api/webhooks) notify your application when something happens on the stream, like a chat message arriving or the stream going live. Owncast sends an HTTP `POST` to an endpoint you host.
- [**APIs**](/docs/api/requests) let your application send actions back into Owncast, such as posting a chat message or updating the stream title. Requests are authenticated with an access token.

To receive webhooks, create an endpoint on any web server, in any language, that accepts an HTTP `POST`. Each event payload carries a `type` field naming the event and an `eventData` object with its details.

## Example

<iframe width="560" height="315" src="https://www.youtube.com/embed/eWE7HGJQI_4?start=547" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

## API reference

Browse every endpoint in the [released API](/api/release) or the [in-development API](/api/development).

## Development environment

Host your code anywhere and write it in any language. It needs to be reachable by your Owncast server to receive webhooks, and able to reach your server to call the APIs. While developing locally, a tunneling tool like [ngrok](https://ngrok.com/) or [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) gives your machine a temporary public URL so Owncast can deliver webhooks to it. When you are ready, move the code to any server or hosting platform you like.

## Run your code inside Owncast instead

If you would rather your code run inside the server than call it over HTTP, [plugins](/docs/plugins) are the other way to build. See [ways to extend Owncast](/docs/extend) for how the two approaches compare.

---

## Send requests to the Owncast API

We currently support the following actions you can make via requests from your code.

| Event                    |                                                                            Endpoint                                                                            |                      Scope |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------: | -------------------------: |
| System chat message      |                     /api/integrations/chat/system                      | `CAN_SEND_SYSTEM_MESSAGES` |
| Standard chat message    |                       /api/integrations/chat/send                       |        `CAN_SEND_MESSAGES` |
| Chat action              |                      /api/integrations/chat/action                      | `CAN_SEND_SYSTEM_MESSAGES` |
| Remove chat message      |       /api/integrations/chat/messagevisibility       |         `HAS_ADMIN_ACCESS` |
| Get chat history         |                             /api/integrations/chat                             |         `HAS_ADMIN_ACCESS` |
| Get connected clients    |                          /api/integrations/clients                          |         `HAS_ADMIN_ACCESS` |
| Set stream title         |                     /api/integrations/streamtitle                      |         `HAS_ADMIN_ACCESS` |
| system message to client | /api/integrations/chat/system/client/`{clientId}` | `CAN_SEND_SYSTEM_MESSAGES` |
| Get server status        |                            /api/integrations/status                            |         `HAS_ADMIN_ACCESS` |
| Get a chat user's details |            /api/integrations/moderation/chat/user/`{userId}`            |         `HAS_ADMIN_ACCESS` |

Visit the API documentation for each endpoint to learn more about what values are expected or will be returned.

Your Owncast server will only accept actions from requests with a valid Access Token. Follow the below steps to create an access token.

1. visit `/admin/access-tokens` on your owncast server.
1. Click `Create Access Token`.
1. Select the scope of permissions you want to give this token.
1. Save this access token.

### Your code

Send an authenticated `POST` with your access token in the `Authorization` header and a JSON body. For example, to send a system chat message:

```js
const res = await fetch("https://your.owncast.server/api/integrations/chat/system", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer " + YOUR_ACCESS_TOKEN,
  },
  body: JSON.stringify({ body: "this is a system chat message" }),
});

const result = await res.json();
// { "success": true, "message": "sent" }
```

### Test sending chat messages

Change the following `curl` command to point to your server URL and use your auth token with "system message" access. It will send a system message to your chat.

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOURAUTHTOKEN" \
  -d '{"body": "I am a system message!"}' \
  https://your.owncast.server/api/integrations/chat/system
```

A successful request returns `200` with a JSON body:

```json
{ "success": true, "message": "sent" }
```

## Scopes

Each access token is granted one or more scopes that control what it can do. The endpoints above list the scope each one requires.

| Scope                      | Grants                                                                                                   |
| -------------------------- | -------------------------------------------------------------------------------------------------------- |
| `CAN_SEND_MESSAGES`        | Send standard chat messages as the token's own user.                                                     |
| `CAN_SEND_SYSTEM_MESSAGES` | Send chat messages as the system, and send chat actions.                                                 |
| `HAS_ADMIN_ACCESS`         | Administrative actions: read chat history, list connected clients, set the stream title, change message visibility, get the server status, and look up a chat user. |

## Responses and errors

| Status | Meaning                                                                                          |
| ------ | ------------------------------------------------------------------------------------------------ |
| `200`  | The request succeeded. For the mutation (`POST`) endpoints the JSON body is the `success: true` envelope with a short `message`. The `GET` endpoints return the domain object instead: the server status, an array of chat messages, an array of connected clients, or a user's details. |
| `400`  | The request body was malformed. The JSON body has `success: false` and a `message`.              |
| `401`  | The access token is missing, invalid, or lacks the scope the endpoint requires. The body is plain text. |
| `500`  | The server hit an error handling the request.                                                    |

Owncast does not return a separate `403` for an insufficient scope. A token without the required scope is rejected with `401`, the same as a missing or invalid token.

---

## Webhooks

Owncast supports HTTP Webhooks to notify third-party applications (such as chatbots) about events on the stream. In other words: Webhooks will send events to your code when things happen on your Owncast server.

The following is a list of events you can get notified about.

| Event Type                                    | webhook triggers when ...                                                                    |
| :-------------------------------------------- | :------------------------------------------------------------------------------------------- |
| [CHAT](#chat)                                 | user sends a chat message                                                                    |
| [NAME_CHANGE](#name_change)                   | user changes their username                                                                  |
| [USER_JOINED](#user_joined)                   | user joins the chat                                                                          |
| [USER_PARTED](#user_parted)                   | a user's last active chat connection disconnects                                             |
| [STREAM_STARTED](#stream_started)             | an incoming RTMP stream is detected                                                          |
| [STREAM_STOPPED](#stream_stopped)             | an incoming RTMP stream disconnects (e.g. OBS stops)                                         |
| [STREAM_TITLE_UPDATED](#stream_title_updated) | the title of the stream is updated                                                           |
| [VISIBILITY-UPDATE](#visibility-update)       | a previously sent chat message becomes visible/invisible (set by an Administrator/Moderator) |
| [FEDIVERSE_ENGAGEMENT_FOLLOW](#fediverse_engagement_follow) | a Fediverse user follows your server                                             |

### How to accept webhooks

1. Visit `/admin/webhooks` on your owncast server.
1. Click `Create Webhook`.
1. Put in the full public URL to an endpoint that can receive this webhook.
1. Keep or replace the pre-filled webhook secret. Owncast uses it to sign every delivery, and you'll use it to verify them. You can reveal or copy it later from the webhook list.
1. Select the events you want to be notified of.
1. Save this new webhook.

### Your code

1. In any language, on any kind of web server, create an endpoint that accepts a HTTP `POST` request. This is where Owncast will be sending events.
1. Each event payload will have a `type` property that states which event type it is, and an `eventData` object that includes specific properties of that event.

### Verifying webhook requests

:::new[Signed webhooks require Owncast v0.3.0]
Owncast 0.3.0 signs every webhook delivery. Earlier releases send unsigned requests with no signature header.
:::

Every webhook has a secret, created with the webhook in the admin. Each delivery includes an `owncast-signature` header:

```text
owncast-signature: t=1718400000.s=5f8a1c...
```

`t` is the Unix timestamp when the request was signed. `s` is a hex-encoded HMAC-SHA256 signature.

To verify a delivery:

1. Parse `t` and `s` from the header.
2. Reject the request if `t` differs from the current time by more than 300 seconds. This blocks replayed deliveries.
3. Compute `HMAC-SHA256(secret, "<t>." + body)`, where `body` is the exact raw request body. Don't re-serialize the JSON, since any formatting difference changes the signature.
4. Hex-encode the result and compare it to `s` using a constant-time comparison.

A Node.js example:

```js
const crypto = require("crypto");

function verifyWebhook(signatureHeader, rawBody, secret) {
  const parts = {};
  for (const part of signatureHeader.split(".")) {
    const [key, value] = part.trim().split("=");
    if (key === "t" || key === "s") parts[key] = value;
  }
  if (!parts.t || !parts.s) return false;

  // Reject replays outside a 5 minute window.
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");

  if (parts.s.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(parts.s), Buffer.from(expected));
}
```

Verification is optional. If you skip it, treat your endpoint as something anyone on the internet could call.

### High level webhooks

Webhooks utilize the `HTTP POST` method to push data to an endpoint. The request body of the webhook is plain `JSON`.
Thus the ContentType header for the request is `application/json`. Each webhook body follows a simple JSON structure.

```json
{
  "type": "",
  "eventData": {}
}
```

where

- **type** gives information about what kind of event it is (one of the types from the table above).
- **eventData** gives more information on the event. The structure of `eventData` is different for each `type`.

Every `eventData` also includes a `status` object describing the current stream state and a `serverURL` string identifying the server that sent the event. The one exception is `FEDIVERSE_ENGAGEMENT_FOLLOW`, which carries `serverURL` but no `status`.

Examples of what `eventData` to expect for each event type are below.

## Webhook Examples

#### CHAT

```json
{
  "type": "CHAT",
  "eventData": {
    "status": {
      "lastConnectTime": "2021-08-12T07:45:03.986220954Z",
      "lastDisconnectTime": null,
      "versionNumber": "0.2.5",
      "streamTitle": "",
      "viewerCount": 3,
      "overallMaxViewerCount": 7,
      "sessionMaxViewerCount": 4,
      "online": true
    },
    "serverURL": "https://stream.example.com",
    "user": {
      "id": "qSRQpeM7R",
      "displayName": "lazyDaisy",
      "displayColor": 182,
      "createdAt": "2021-08-12T07:51:37.470812684Z",
      "previousNames": ["lazyDaisy"],
      "nameChangedAt": "2022-09-19T12:33:59.42313245+02:00",
      "isBot": false,
      "authenticated": false
    },
    "timestamp": "2021-08-12T07:53:12.061982913Z",
    "body": "\u003cp\u003ehello world \u003cimg class=\"emoji\" alt=\":beerparrot:\" title=\":beerparrot:\" src=\"/img/emoji/beerparrot.gif\"\u003e\u003c/p\u003e",
    "rawBody": "hello world :beerparrot:",
    "id": "j-rXteG7R",
    "clientId": 2,
    "visible": true
  }
}
```

- `body` is the message rendered to sanitized HTML. Markdown is converted and emoji shortcodes are replaced with `` tags.
- `rawBody` is the original message text exactly as the user typed it.

Note: the field `user` in the chat was introduced with `v0.0.8`. Before `v0.0.8` a simple string field with the name `author` was used.

#### NAME_CHANGE

```json
{
  "type": "NAME_CHANGE",
  "eventData": {
    "status": {
      "lastConnectTime": "2021-08-12T07:45:03.986220954Z",
      "lastDisconnectTime": null,
      "versionNumber": "0.2.5",
      "streamTitle": "",
      "viewerCount": 3,
      "overallMaxViewerCount": 7,
      "sessionMaxViewerCount": 4,
      "online": true
    },
    "serverURL": "https://stream.example.com",
    "id": "GsxeK6MIg",
    "timestamp": "2022-09-19T12:33:59.423278816+02:00",
    "user": {
      "id": "qSRQpeM7R",
      "displayName": "NotSoLazyDaisy",
      "displayColor": 182,
      "createdAt": "2021-08-12T07:51:37.470812684Z",
      "previousNames": ["lazyDaisy"],
      "nameChangedAt": "2022-09-19T12:33:59.423278816+02:00",
      "isBot": false,
      "authenticated": false
    },
    "newName": "NotSoLazyDaisy"
  }
}
```

#### USER_JOINED

```json
{
  "type": "USER_JOINED",
  "eventData": {
    "status": {
      "lastConnectTime": "2021-08-12T07:45:03.986220954Z",
      "lastDisconnectTime": null,
      "versionNumber": "0.2.5",
      "streamTitle": "",
      "viewerCount": 3,
      "overallMaxViewerCount": 7,
      "sessionMaxViewerCount": 4,
      "online": true
    },
    "serverURL": "https://stream.example.com",
    "id": "wAgcTeM7g",
    "timestamp": "2021-08-12T08:19:28.921355401Z",
    "user": {
      "id": "yFgco6M7R",
      "displayName": "laughing-cray",
      "displayColor": 257,
      "createdAt": "2021-08-12T08:19:28.759651178Z",
      "previousNames": ["laughing-cray"],
      "nameChangedAt": "0001-01-01T00:00:00Z",
      "isBot": false,
      "authenticated": false
    }
  }
}
```

#### USER_PARTED

`USER_PARTED` is sent 10 seconds after a user's last active chat connection disconnects. If the user reconnects during that time, the event is canceled. Disabling visible join and part messages only hides the message in chat. The webhook is still sent.

```json
{
  "type": "USER_PARTED",
  "eventData": {
    "status": {
      "lastConnectTime": "2021-08-12T07:45:03.986220954Z",
      "lastDisconnectTime": null,
      "versionNumber": "0.2.5",
      "streamTitle": "",
      "viewerCount": 3,
      "overallMaxViewerCount": 7,
      "sessionMaxViewerCount": 4,
      "online": true
    },
    "serverURL": "https://stream.example.com",
    "id": "Ws4gTeM7R",
    "timestamp": "2021-08-12T08:20:01.061982913Z",
    "user": {
      "id": "yFgco6M7R",
      "displayName": "laughing-cray",
      "displayColor": 257,
      "createdAt": "2021-08-12T08:19:28.759651178Z",
      "previousNames": ["laughing-cray"],
      "nameChangedAt": "0001-01-01T00:00:00Z",
      "isBot": false,
      "authenticated": false
    }
  }
}
```

#### STREAM_STARTED

```json
{
  "type": "STREAM_STARTED",
  "eventData": {
    "id": "WtokptnVR",
    "name": "Owncast",
    "serverURL": "https://stream.example.com",
    "status": {
      "lastConnectTime": "2022-09-19T12:30:26.97907142+02:00",
      "lastDisconnectTime": null,
      "versionNumber": "0.2.5",
      "streamTitle": "",
      "viewerCount": 0,
      "overallMaxViewerCount": 7,
      "sessionMaxViewerCount": 0,
      "online": true
    },
    "streamTitle": "",
    "summary": "Welcome to your new Owncast server! This description can be changed in the admin. Visit https://owncast.online/docs/configuration/ to learn more.",
    "timestamp": "2022-09-19T12:30:26.97907142+02:00"
  }
}
```

#### STREAM_STOPPED

```json
{
  "type": "STREAM_STOPPED",
  "eventData": {
    "id": "YP-aptn4g",
    "name": "Owncast",
    "serverURL": "https://stream.example.com",
    "status": {
      "lastConnectTime": "2022-09-19T12:30:26.97907142+02:00",
      "lastDisconnectTime": "2022-09-19T12:40:21.205872269+02:00",
      "versionNumber": "0.2.5",
      "streamTitle": "",
      "viewerCount": 0,
      "overallMaxViewerCount": 7,
      "sessionMaxViewerCount": 2,
      "online": false
    },
    "streamTitle": "",
    "summary": "Welcome to your new Owncast server! This description can be changed in the admin. Visit https://owncast.online/docs/configuration/ to learn more.",
    "timestamp": "2022-09-19T12:40:21.205872269+02:00"
  }
}
```

#### STREAM_TITLE_UPDATED

```json
{
  "type": "STREAM_TITLE_UPDATED",
  "eventData": {
    "id": "DmeikEf4Rz",
    "name": "New Owncast Server",
    "serverURL": "https://stream.example.com",
    "status": {
      "lastConnectTime": null,
      "lastDisconnectTime": "2024-10-24T22:35:05Z",
      "versionNumber": "0.1.3",
      "streamTitle": "Test stream title change",
      "viewerCount": 0,
      "overallMaxViewerCount": 7,
      "sessionMaxViewerCount": 2,
      "online": false
    },
    "streamTitle": "Test stream title change",
    "summary": "This is a new live video streaming server powered by Owncast.",
    "timestamp": "2023-03-27T21:50:10.121391094-07:00"
  }
}
```

#### VISIBILITY-UPDATE

```json
{
  "type": "VISIBILITY-UPDATE",
  "eventData": {
    "status": {
      "lastConnectTime": "2022-09-19T12:30:26.97907142+02:00",
      "lastDisconnectTime": null,
      "versionNumber": "0.2.5",
      "streamTitle": "",
      "viewerCount": 3,
      "overallMaxViewerCount": 7,
      "sessionMaxViewerCount": 4,
      "online": true
    },
    "serverURL": "https://stream.example.com",
    "id": "zqGupt7VR",
    "timestamp": "2022-09-19T12:44:28.225779601+02:00",
    "user": null,
    "visible": false,
    "ids": ["-Zzltt74g", "rvd2ppn4g"]
  }
}
```

- `ids` is a list of IDs of messages that had their visibility changed.
- `visible` is the new visibility of those messages.
- `user` is always `null` for this event.

#### FEDIVERSE_ENGAGEMENT_FOLLOW

:::new[Webhook server URLs require Owncast v0.3.0]
Owncast 0.3.0 adds the `serverURL` field to this event. Earlier releases send only `id`, `timestamp`, `name`, `username`, and `image`.
:::

```json
{
  "type": "FEDIVERSE_ENGAGEMENT_FOLLOW",
  "eventData": {
    "id": "AqilY4hDR",
    "timestamp": "2026-04-13T19:17:12.528099886Z",
    "name": "Test Follower",
    "username": "testfollower@fake-mastodon.example.com",
    "image": "https://fake-mastodon.example.com/avatars/testfollower.png",
    "serverURL": "https://stream.example.com"
  }
}
```

- `eventData.id` is an Owncast-generated webhook event ID. It is not the Fediverse actor ID or follow request ID.
- `eventData.name` is the display name of the follower.
- `eventData.username` is the full `user@domain` handle.
- `eventData.image` is the URL to the follower's avatar.
- Unlike the other events, `eventData` does not include a `status` object.

### clientId vs. user.id

When a user is connected from multiple devices (or multiple browsers) at the same time with the same username, Owncast differentiates between their sessions with a `clientId`. Users can have multiple clientIds - a single clientId represents a single connection to Owncast.

`clientId` is a number, whereas `user.id` can container uppercase, lowercase and numeric characters.

### Test webhooks on a local development environment

1. Start Owncast locally (e.g. via docker).
1. Visit `localhost:8080/admin`, authenticate with Username: `admin` and the default streaming key: `abc123`.
1. Navigate to the "Integration" menu-block on the left side, click "Webhooks", then "Create Webhook".
1. Set the Webhook Address to point to your application/integration (something like: `http://localhost:8100/webhooks/incoming`).
1. Select the types of events that you want to receive.
1. Press "OK" to save the webhook.
1. Start your integration/application listening on the previously configured address.
   1. Optionally, start an interception proxy (e.g. Burp) if you want to inspect the HTTP messages beforehand.
1. Trigger events yourself (e.g. write a message to the chat, connect/disconnect your streaming software to Owncast).

### Test webhooks before writing any code

If you want to test how webhooks work before you write any code, create a test endpoint at [RequestCatcher](https://requestcatcher.com/), and add the URL it gives you as a webhook in your admin and see the requests come through.

### Test webhooks from a production instance of Owncast

If you already have an Owncast instance running in production, listening to the world wide web, you might want to make use [ngrok](https://ngrok.com/) to tunnel HTTP requests to your local development environment.

---

## Back Up Your Stream Data and Configuration

Owncast automatically backs up its database once an hour to `data/backup/owncastdb.bak` inside your Owncast directory. You can point the backup somewhere else by starting Owncast with `--backupdir <path>`. Add this file to your normal system backups to keep your configuration, users, and chat history safe.

## What the automatic backup covers

The automatic backup contains only the database: your configuration, users, chat history, and access tokens. Other data lives as plain files under the `data/` directory and is not included, such as custom emoji, files in `data/public`, GeoIP data, and installed plugins and their data.

To fully protect an instance, or to move it to another machine, back up the entire `data/` directory instead. Copying `data/` to a new install carries everything over.

## Restore

Restoring a database backup file brings the database back to the time the backup was created. This is useful if you want to undo a bad change or recover from database corruption.

:::warning
Restoring replaces your current database with the contents of the backup. Anything that changed since the backup was taken is lost. If you might need the current data, copy it somewhere safe before you restore.
:::

1. Stop Owncast from running.
1. From your Owncast directory, run `./owncast --restoreDatabase <backupfile>`.
1. Restart Owncast as you normally would. It will be using the restored data.

---

## ffmpeg

Most people broadcast to Owncast with software like [OBS](/docs/broadcasting/obs). If you would rather stream straight from the command line, ffmpeg can capture a camera or capture card and push it to your server over RTMP. This is an advanced path and assumes you are comfortable on the command line.

The example below is for **Linux**, capturing the `/dev/video2` camera and the `hw:1,0` ALSA audio device:

```bash
ffmpeg -f alsa -ac 2 -i hw:1,0 -thread_queue_size 64 \
  -f v4l2 -framerate 60 -video_size 1280x720 -input_format yuyv422 -i /dev/video2 \
  -c:v libx264 -preset veryfast -b:v 1984k -maxrate 1984k -bufsize 3968k \
  -vf "format=yuv420p" -g 120 -c:a aac -b:a 128k -ar 44100 \
  -f flv rtmp://<ip-of-your-server>/live/<your-streaming-key>
```

What the main options do:

- `-i /dev/video2` and `-i hw:1,0`: the video and audio inputs. These are the parts you change for your hardware and platform (see below).
- `-c:v libx264 -preset veryfast`: encode video with x264. `veryfast` trades some compression efficiency for lower CPU use. Slower presets look better at the same bitrate but use more CPU.
- `-b:v 1984k -maxrate 1984k -bufsize 3968k`: aim for a video bitrate of about 1984 kbps and cap it there. See [choosing video quality](/docs/video) to pick a bitrate for your content and upload speed.
- `-g 120`: emit a keyframe every 120 frames. `-g` counts frames, not seconds, so at 60 fps this is a keyframe every 2 seconds, which is what Owncast needs to segment the stream cleanly. Set `-g` to twice your framerate.
- `-c:a aac -b:a 128k -ar 44100`: AAC audio at 128 kbps and 44.1 kHz.
- `-f flv rtmp://.../live/<your-streaming-key>`: send the result to your Owncast server. Keep the `/live/` path and use your stream key.

## Inputs on other platforms

Only the input flags change between operating systems. The encoding and output options above stay the same.

**macOS** uses `avfoundation`. List your devices, then pick them by index in `video:audio` order:

```bash
ffmpeg -f avfoundation -list_devices true -i ""
ffmpeg -f avfoundation -framerate 30 -i "0:0" ...
```

**Windows** uses `dshow`. List your devices, then pick them by name:

```bash
ffmpeg -list_devices true -f dshow -i dummy
ffmpeg -f dshow -i video="Your Camera":audio="Your Microphone" ...
```

For most setups a dedicated broadcasting application is easier than maintaining an ffmpeg command. See the [broadcasting software](/docs/broadcasting) overview for the common options.

---

## Compatible hardware

The following hardware with native live streaming support has been reported to work by the community. This list is not independently verified by the Owncast team.

- [GoPro Hero 8](https://gopro.com/)
- [Mevo](https://mevo.com/)
- [ATEM Mini Pro](https://www.blackmagicdesign.com/products/atemmini)
- [TriCaster Mini](https://www.vizrt.com/tricaster/mini/) \*you have to send the Stream Key as an unencrypted parameter called "Stream ID"
- [Kiloview E1](https://www.kiloview.com/en/encoder/h264-wired/)
- [Blackmagic Web Presenter HD](https://www.blackmagicdesign.com/products/blackmagicwebpresenter)

When a device asks for separate fields, use these values:

| Field | Value |
| ----- | ----- |
| Server URL | `rtmp://yourserver:1935/live` |
| Stream Key | A stream key from the admin, under Configuration > Server Setup in the Stream Keys tab |

If you have tested other hardware with Owncast we'd love to hear about it!

---

## Set Up Broadcasting Software

## Compatibility

In general Owncast is compatible with any software that uses `RTMP` to broadcast to a remote server. `RTMP` is what all the major live streaming services use, so if you're currently using one of those it's likely that you can point your existing software at your Owncast instance instead.

However, we haven't tested with everything. So if you're using something specific [we'd love to hear what software you're using and the results](https://github.com/owncast/owncast/issues/new). If you're finding yourself running into issues, we'd love to help troubleshoot.

## Pointing your software to Owncast

Owncast accepts incoming streams over RTMP on TCP port 1935 by default. The port is configurable in the admin under Configuration > Server Setup (see [Server Setup](/docs/configuration/server-setup)). Your stream key is only accepted on the `/live/` path, so the full endpoint is `rtmp://yourserver:1935/live/<your-stream-key>`.

Most broadcasting software will have a way to specify a "custom" location as a RTMP endpoint. In this case you would specify `rtmp://yourserver:1935/live` as the RTMP destination, specifying your stream key where it asks for it. The default stream key is `abc123` but you should change this immediately after setting up Owncast.

If your software doesn't have a place to specify a stream key you can simply append it to your RTMP location, for example: `rtmp://yourserver:1935/live/abc123`.

## How you configure your broadcasting software matters

You will want to configure your broadcasting software to match the highest quality you can offer your viewers. **That means if your Owncast server can only handle 720p@2500k you should not configure your broadcasting software to send 1080p@6000k**. The more conversion work you ask Owncast to do the more resources it will use on your server, making it even harder to offer the best qualities to your viewers.

Every server, environment, network speed and processing capacity is different. Just because you _want_ to offer a certain quality doesn't mean your server can support it.

If you find yourself trying to squeeze better performance out of Owncast then try setting your broadcasting software to a lower quality as well as lowering the output quality in the admin under Configuration > Video.

## Broadcasting Settings

The following are some suggested settings for a high quality stream you can set in your broadcasting software. But you should keep in mind the highest quality you'll be offering your viewers, as stated above. Continue to read more about the values.

### Video resolution and quality

| Resolution | Framerate | Bitrate |
| ---------- | --------- | ------- |
| 1920x1080  | 60fps     | 5000k   |
| 1920x1080  | 30fps     | 4500k   |
| 1280x720   | 60fps     | 4000k   |
| 1280x720   | 30fps     | 3000k   |

### Resolution and Frame rate

Resolution refers to the size of a video on a screen, and frame rate refers to how many frames per second are displayed. Full HD resolution is typically 1080p, 60 frames per second (fps). Streaming at a higher resolution like 1080p requires a higher bitrate, and a higher frame rate takes more encoding power. If you have the bandwidth and encoding power both on your broadcasting computer and your Owncast server to stream at 1080p, 60 fps, great! If not, try one of the other settings above to optimize your video quality and stability.

### Bitrate

The bitrate is the amount of data you send to your Owncast server when you stream. A higher bitrate takes up more of your available internet bandwidth. Increasing your bitrate can improve your video quality, but only up to a certain point.

### Video and audio codecs

Use H.264 video and AAC audio for the best compatibility. Owncast's ingest layer also recognizes H.265 video and MP3 and Speex audio, but transcoding and playback compatibility are only assured for H.264 and AAC.

### Keyframe Interval

Set your broadcasting software to send a keyframe every 2 seconds and do not leave it at `auto`. Keyframe settings use different units in different tools. The OBS keyframe interval is in seconds, so use `2`. The ffmpeg `-g` option counts frames, so use twice your framerate.

### Audio settings

Set your broadcasting software to send Owncast `AAC` audio.

### Audio bitrate and quality

When streaming also make sure to match your audio quality to what you're streaming. If you're a music focused stream then maybe go higher. If you're just talking, then maybe you can afford to go lower.

Owncast passes audio through untouched by default, so it goes out exactly how it's sent. If audio passthrough is turned off for an output variant, Owncast re-encodes that variant's audio to AAC.

| Quality | Bitrate |
| ------- | ------- |
| Low     | 96kbps  |
| Medium  | 128kbps |
| High    | 192kbps |
| Higher  | 256kbps |
| Highest | 320kbps |

## Dropping frames

Read more about troubleshooting [Dropped frames](/docs/troubleshoot/dropped-frames) being reported in your broadcasting software.

## Errors or disconnections

If your broadcasting software keeps disconnecting from Owncast, or your stream drops partway through, read [Your stream keeps disconnecting](/docs/troubleshoot/stream-disconnect). It covers the common causes: an unstable network, a bitrate higher than your upload can sustain, and ffmpeg problems on the server.

---

## Jitsi

[Jitsi](https://jitsi.org) is both a video conferencing provider and a software suite. It is open source and can be self-hosted. It is also available as a service at [meet.jit.si](https://meet.jit.si).

Jitsi sends its RTMP stream from the internet, so TCP port 1935 on your Owncast server must be publicly reachable. Have your stream key ready.

1. Visit your Jitsi meeting page.
2. Click on the three dots in the lower right.
3. Select "Start live stream"

![Image](/docs/img/jitsi-1.png)

4. In the "Start a live screen" modal put your full Owncast RTMP in the "Live stream key" field. This would be in the format of rtmp://your-owncast-server/live/yourkey.

![Image](/docs/img/jitsi-2.png)

5. Note that the error "Live stream key may be incorrect" will display. This is expected and can be ignored.

---

## OBS/Streamlabs Desktop

OBS is a popular piece of free software that will get you streaming from your own computer right away.

Before configuring OBS, make sure your Owncast server is installed and running.

1. Install [OBS](https://obsproject.com/) or [Streamlabs Desktop](https://streamlabs.com/) and get it working with your local setup.
2. Open OBS Settings and go to "Stream".
3. Select "Custom..." as the service.
4. Enter the URL of your Owncast server in the format of `rtmp://myserver.net:1935/live`.
5. Enter a "Stream Key" that matches a stream key defined in the Owncast admin under Configuration > Server Setup, in the Stream Keys tab. The default stream key happens to be the same value as the default admin password, `abc123`, but the two are independent settings and both should be changed.
6. Press "Start Streaming" (OBS) or "Go Live" (Streamlabs Desktop).

---

## Restream.io

You must be a paid user of [Restream](http://restream.io) to point to your Owncast instance as a destination "channel".

Restream sends its RTMP stream from the internet, so TCP port 1935 on your Owncast server must be publicly reachable. Have your stream key ready.

1. Login and go to the "Add Channel" screen.
![Add Channel Screen](/docs/img/restream1.png)

1. Select "Custom RTMP"
![Select Custom RTMP](/docs/img/restream2.png)

1. Add your server information in the format of `rtmp://myserver/live` for the RTMP URL and your Stream Key.
![Server Information](/docs/img/restream3.png)

---

## Zoom

[Zoom](https://zoom.us/) offers to stream your meeting to a livestreaming service like Owncast. Please mind that some changes might need to be done by your Zoom administrator.

Zoom sends its RTMP stream from the internet, so TCP port 1935 on your Owncast server must be publicly reachable. Have your stream key ready.

1. Set up Owncast and configure it by your choosing.
2. Allow live streaming for the user account. In [zoom.us/profile/setting](https://zoom.us/profile/setting), scroll down to "Allow live streaming meetings" and activate _Custom Live Streaming Service_:
  ![Image](/docs/img/zoom-activate-for-account.png)
3. Schedule a meeting using the website and save it. Zoom will redirect you to a "Manage meeting" page which has a Live Streaming section at the very bottom. Click on the "configure live stream settings" link:
  ![Image](/docs/img/zoom-manage-meeting.png)
4. Fill in your Owncast server information. The "live streaming page URL" should be the Owncast Frontend, since Zoom will link to it from the meeting.
  ![Image](/docs/img/zoom-server-settings.png)
5. Once the meeting is started, click on "More" in the menu bar and then "Livestream to Custom service". Zoom will open a browser window and then redirect you to the Owncast frontend (or whichever URL you specified).

The instructions for Webinars and Personal Meeting Rooms are similar, [see Zoom's support page](https://support.zoom.us/hc/en-us/articles/115001777826-Live-Streaming-Meetings-or-Webinars-Using-a-Custom-Service) for more information.

---

## Content Delivery Networks (CDNs)

## What is a CDN?

A CDN, or Content Delivery Network, is a service used to geographically distribute your content to end users. It helps to improve performance by reducing the time it takes to load content.

A CDN works by distributing the content across multiple servers strategically placed in various geographic locations. This distribution ensures that content is delivered from a server that is physically closer to the user, reducing the distance data needs to travel. It also helps to alleviate the load on the origin (your Owncast server) by offloading the delivery of content to the CDN servers.

CDNs employ caching to store content. When a user requests content that is already cached in the CDN server, it can be delivered quickly without needing to retrieve it from the origin server. This caching mechanism improves the overall speed and responsiveness of your content.

In addition to caching, CDNs may also provide other optimization features such as data compression and security measures like DDoS protection. These additional features contribute to further improving the performance, scalability, and availability of websites and web applications.

## How is this helpful with your Owncast stream?

By putting a CDN in front of your Owncast instance it can be useful for viewers of your stream who may be geographically distant from your actual server, making it slower to stream your video, potentially causing buffering or other issues.

Additionally, your entire Owncast web page will load faster for all visitors, as the CDN will cache and serve the static assets (like CSS, JavaScript, images, etc) that make up your Owncast instance.

## What is the difference between a storage provider and a CDN?

CDNs are designed to improve delivery performance and reduce latency by caching and distributing content from servers located closer to users. Storage providers focus on providing scalable and reliable storage infrastructure for storing data. While there may be some overlap in functionalities, their primary objectives and features differentiate them from each other.

While CDNs and storage providers are two different services, some object storage providers may offer built in CDNs that can be enabled.

## How can you use a CDN with Owncast?

While it's impossible to go into detail for every CDN provider and configuration, here are the high level steps you'll need to take to put a CDN in front of your Owncast instance.

### Without a storage provider

1. Your actual Owncast server, known to a CDN as the "origin", will need a publicly available hostname that is different than the one you use to access your Owncast instance. For example, if you want your viewers to access your Owncast instance at `https://owncast.example.com` you'll need to create a new hostname like `owncast-origin.example.com` and point it to your Owncast server.
1. In your CDN configuration you'll need to tell it to use `owncast-origin.example.com` as the origin for your Owncast instance.
1. You'll need to update your DNS configuration to point your Owncast hostname to your CDN. For example, if you access your Owncast instance at `https://owncast.example.com` you'll need to update your DNS configuration to point `owncast.example.com` to your CDN instead of your actual server.
1. Visit your Owncast admin and go to Configuration > Server Setup. On the Server Config tab, under Advanced Settings, set the "Websocket host override" to the origin URL you created in step 1. For example, `https://owncast-origin.example.com`. The field takes a regular `http://` or `https://` URL and the web player converts it to a websocket connection. If you don't perform this step your chat will no longer be accessible for CDN providers who do not support passing through websockets. See the [server setup documentation](/docs/configuration/server-setup) for more about these settings.

### With an external storage provider

1. In this configuration your storage provider is the origin server, not your Owncast server.
1. Get the endpoint hostname for your storage bucket from your provider.
1. In your CDN configuration you'll need to tell it to use the storage provider hostname as the origin server.
1. In the Owncast admin go to Configuration > Server Setup. On the Server Config tab, under Advanced Settings, set the "Serving Endpoint" to the full URL of your CDN deployment. For example, `https://cdn.example.com`. See the [server setup documentation](/docs/configuration/server-setup) for more about these settings.

## Things to consider

- Your Owncast server (the origin server) must still be on a network fast enough for the CDN to access your content and distribute it to your viewers. Simply adding a CDN won't automatically make your Owncast's network faster, though it may reduce the network load of your server via caching.
- In some cases using a CDN in front of your Owncast server makes it more difficult for Owncast to have an accurate count of how many viewers you have. This is a tradeoff you'll need to consider. Generally if you have a low number of viewers it will report a higher number of viewers than you actually have (due to multiple CDN servers fetching your content), and if you have a large number of users it will report a lower number of viewers than you actually have (due to multiple viewers watching the same cached content).
- The more viewers you have, the more useful a CDN will be. If you have a small number of viewers it's likely every request will be hitting your origin server anyway, so a CDN won't be as useful, and even potentially detrimental to viewers in some cases since it requires an additional network hop. Refer to your CDN statistics to see how many requests are being served from the CDN cache (hits) vs your origin server (misses).

---

## Enable Chat authentication

By default there is no requirement to authenticate when using Owncast chat. However, some prefer
to authenticate themselves to verify their identity to others, and to continue using the same chat
identity across multiple devices and browsers. This is especially helpful for those with [moderator](/docs/chat/)
privileges.

Server operators can also turn on _Require Authentication_ in the admin under `Configuration` \> `Chat`.
When it is on, anyone who has not authenticated, other than moderators, is rejected when they try to send
a chat message.

You can access the authentication options via the chat dropdown menu in the upper right of the page.

<Tabs queryString="authentication-method">
  <TabItem value="FediAuth" label="FediAuth" default>
## Fediverse Authentication (FediAuth)

Using your Fediverse account you can be sent a one time use six digit code to verify your identity and authenticate
yourself with Owncast chat. Fediverse support must be enabled on the Owncast server for this feature to be available.

The code arrives as a direct message to your account. If you do not receive this message make sure you can accept
direct messages.

The code is valid for 10 minutes. After that you will need to request a new one.
  </TabItem>

  <TabItem value="IndieAuth" label="IndieAuth">
    ## IndieAuth

IndieAuth is an open standard decentralized authentication protocol that enables services to verify the identity of a user represented by a URL. This means anybody that has an existing URL that supports IndieAuth can use it to authenticate with Owncast chat.

Visit [IndieAuth.net](https://indieauth.net/) to learn more.

### Owncast is an IndieAuth server

If you run an Owncast server you can use it as your IndieAuth provider by entering the URL of your server. Authenticating this way verifies you as the admin of that Owncast server.
  </TabItem>
</Tabs>

---

## Upload Custom emoji

Your stream's chat can be customized with your own custom emoji. You can add as many as you'd like and they'll be available to use in chat.

## In the Admin

By visiting the chat custom emoji page in the admin located at `/admin/chat/emojis` you can add and remove images that are available to chat participants.

## Manual management

You can manage your custom emoji images in the `data/emoji` directory on your filesystem. Here's what you can do:

* Add multiple static and/or animated emoji image files at once
* Delete an entire set of emojis
* Rename all emoji files
* Back up your custom emojis by copying them to another folder

## Bundled emoji images

The images bundled with Owncast out of the box are freely licensed by different authors. See the [directory of emoji](https://github.com/owncast/owncast/tree/develop/static/img/emoji) for the respective licenses associated to each collection.

---

## Chat

### Text Formatting

The web chat supports some basic formatting using [Markdown](https://www.markdownguide.org/basic-syntax/):

Italic: `*your text*`

Bold: `**your text**`

Inline code: <code>\`your text\`</code>

When you send a message, Owncast renders the formatting inline:

### Your Name and Color

Open the dropdown in the upper right of the page and choose _Change name_ to set your chat display name. The same dialog lets you pick one of eight display colors used for your name and messages.

### Hiding and Popping Out Chat

The same dropdown has an option to hide or show chat, and pressing the `c` key toggles it too. You can also pop chat out into its own window and put it back later.

### Badges

Some senders have a badge next to their name: a moderator badge, an authenticated badge for people who have [verified their identity](chat-authentication.mdx), and a bot badge for messages sent by bots and integrations.

---

## Chat moderation

Using either the Owncast admin, or inline moderation controls within your chat, you can remove individual messages or entire users.

## Chat Moderators

Moderators have no access to the admin, and exist to help you keep your chat in order.

In your admin, visit `Users` to find the user you want to grant Moderator privileges.
Bring up their details and you can add them as a moderator.

By default there are no moderators, so at the very least you might want to make yourself one.

Moderators will be notified when they become one, and have a moderator icon next to their name in chat
that everyone can see.

## How to moderate

Once you become a moderator you can hover over a chat message and open a menu where you can remove a single message,
or ban the user from the chat completely.

Using the "More info" action you can get a short overview of the user such as when they first joined. This information
is useful when trolls are trying to impersonate somebody.

## Removing chat messages using the Admin

Visit `Chat` \> `Messages` in your admin to perform chat message moderation tasks.

### Single message

You can toggle the visibility of a single message in your chat by clicking the visibility toggle button (that looks like an eyeball) on the far right of each message.

![The Messages tab of the admin, with the eyeball visibility toggle on the right of a chat message](/docs/img/chat-moderation-hide-message.png)

### Bulk changing of visibility

![The Messages tab with several messages selected by checkbox and the show and hide buttons above the list](/docs/img/chat-moderation-bulk-hide-messages.png)

Alternately, you can select, via checkboxes, the messages you want to change all at once, and then press the _"show"_ or _"hide"_ buttons.

## Banning users from your chat using the Admin

Visit `Users` in your admin to perform user moderation tasks.

Banning a user will immediately disconnect them from chat and hide the chat interface from their browser. It will also remove all previous messages sent by this user from the chat feed.

You can un-ban a previously banned user, but note that it will not restore these removed messages. You may restore them manually if needed.

![The Users tab of the admin, showing a user row with the option to ban the user](/docs/img/user-moderation-ban-user.png)

Alternatively, you can click on the user display name and bring up the user info modal and ban them from there.

![The user info modal opened from a display name, with a button to ban the user](/docs/img/user-moderation-ban-user-modal.png)

### Banning vs deleting

Banning is reversible, since you can un-ban the user later. The same menu also offers _Delete user_, which is permanent. It removes the user and all of their data, including their messages, and cannot be undone.

## IP Address Blocking

When banning a user Owncast will automatically block their known IP address. While this can deter most trolls,
like anything else, it is possible to evade.

- Owncast uses the IP address as provided in the `x-forwarded-for` header if it's provided, meaning it may be possible
  for somebody to override this value with a fake address. If you're concerned about this, make sure your reverse proxy
  is configured to explicitly set the correct header value.
- VPNs are a thing. By using a VPN it's trivial to evade the IP address ban.

This is all to say: This feature will help keep abuse down, but in no way does it guarantee that it will keep the
worst of the worst away. Moderation is still the responsibility of each individual stream.

A list of blocked IPs can be viewed in the Admin Chat Users interface and can be un-banned via the same interface.

## Chat settings

Visit `Configuration` \> `Chat` in your admin to change how chat behaves:

- **Chat**: turn chat on or off entirely.
- **Join Messages**: announce in chat when a viewer joins.
- **Welcome Message**: a system chat message sent to viewers when they first connect. Leave it blank to disable.
- **Forbidden usernames**: a list of words that are not allowed in chat usernames.
- **Default usernames**: an optional list of usernames that new visitors get assigned. With fewer than 10 entries, random names are generated instead.
- **Established users only**: block messages from accounts younger than 15 minutes. Moderators are exempt.
- **Chat language filter**: reject messages that contain offensive language, using an internal word list.
- **Require Authentication**: only [authenticated users](/docs/chat/chat-authentication) and moderators may send messages.

## Rate limiter

Chat has a built-in rate limiter to prevent spam. It allows roughly one message every two thirds of a second. A user who floods faster than that is blocked from sending messages for 10 seconds and is told so. Moderators are never rate limited. You can turn the limiter off with the _Spam Protection_ toggle in the chat settings.

---

## Hardware Accelerated Encoding & Codecs

## Requirements

**All four of these things need to be true to support hardware accelerated encoding with Owncast.**

1. You are **not** running on a VPS provided to you by a hosting provider, as shared virtual servers do not allow for direct access to hardware.
1. You have compatible hardware and have direct access to it.
1. You installed and configured any drivers and libraries needed to take advantage of your hardware.
1. You have a copy of `ffmpeg` that is specifically built to utilize these drivers and libraries. Version 4.1.5 or newer is suggested.

## Things to keep in mind

1. Most people won't be able to take advantage of this unless you're running your own hardware.
1. Just because a specific hardware accelerated codec shows in the Owncast admin **does not mean your machine is configured to support it**. Owncast builds that list by running `ffmpeg -encoders` and keeping the H.264 encoders it knows how to use. An entry appearing means your copy of ffmpeg advertises that encoder, not that the drivers and hardware behind it are proven to work.
1. Very little of what is required to get your hardware working has anything to do with Owncast. Any questions you have about your particular hardware should be directed to your hardware manufacturer or whoever provides the drivers and libraries to utilize it. There's likely a lot of information already online, so please do your research.

## Compatible hardware

### Intel Graphics

If you have Intel integrated graphics you may be able to use it using [VA-API](#va-api) or [Quicksync](#intel-quicksync).

### NVIDIA GPUs

NVIDIA GPUs ship with an on-chip hardware encoder unit often referred to as NVENC. Separate from the CUDA cores, NVENC run encoding workloads without slowing the execution of graphics or CUDA workloads running at the same time.

Most modern NVIDIA GPUs ship with NVENC. Check the [NVIDIA GPU Support Matrix](https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new#Encoder) to confirm your GPU appears in the "encoder" list.

### AMD GPUs

[VA-API](#va-api) is supported on AMD and ATI GPUs by the [libva-mesa-driver](https://wiki.archlinux.org/title/Hardware_video_acceleration).

## Compatible codecs/libraries

### Intel QuickSync

"Intel Quick Sync Video" is the marketing name for the hardware video decoding and encoding features on Intel processors with integrated graphics. Processors with an Intel iGPU can be used to do hardware video encoding as long as you have `libva` installed and the processors iGPU supports the video codec and resolution you want to use.

Follow the instructions on Intel's site on [how to get QuickSync setup on Linux](https://www.intel.com/content/www/us/en/architecture-and-technology/quick-sync-video/quick-sync-video-installation.html).

Links:

- [Setting up QuickSync on Ubuntu](https://wiki.ubuntu.com/IntelQuickSyncVideo)
- [Intel Graphics at Linux Reviews](https://linuxreviews.org/Intel_graphics)

### VA-API

VA-API (video acceleration API) is a layer to support hardware accelerated encoding on linux. You need the `libva` library installed for it to work. VA-API is not compatible with ARM chipsets.

ffmpeg 5 and newer are supported with VA-API.

Links:

- [VA-API at Linux Reviews](https://linuxreviews.org/VAAPI)
- [Intel Media Driver for VA-API](https://github.com/intel/media-driver/)

### NVIDIA Encoder (nvenc)

Follow the instructions on the [NVIDIA ffmpeg transcoding guide](https://developer.nvidia.com/blog/nvidia-ffmpeg-transcoding-guide/) to install all the required drivers and libraries. This requires installing a driver from the [NVIDIA website](https://www.nvidia.com/en-us/drivers/), Downloading and install the [CUDA toolkit](https://developer.nvidia.com/cuda-toolkit), [downloading nv-codec-headers](https://github.com/FFmpeg/nv-codec-headers), and building ffmpeg. Scroll to the section entitled _Hardware accelerated transcoding with FFmpeg_ at the [NVIDIA transcoding guide](https://developer.nvidia.com/blog/nvidia-ffmpeg-transcoding-guide/) for more information.

You may be able to find a pre-built version of ffmpeg that has `nvenc` support, however that's outside the scope of this document. You still need NVIDIA drivers regardless.

Links:

- [Tal.org instructions on building ffmpeg with nvenc](https://www.tal.org/tutorials/ffmpeg_nvidia_encode)
- [Shell script that claims to automate the process on Ubuntu](https://gist.github.com/ransagy/3f6f1a9e5ede6212425f3b36b136216e)

### OpenMAX (omx)

OpenMAX (`h264_omx`) is a hardware encoding interface most commonly used on older Raspberry Pi boards. It shows in the admin as "OpenMax (omx) for Raspberry Pi". Your copy of ffmpeg must be built with OpenMAX support, which many distribution builds no longer include.

### Apple VideoToolbox

VideoToolbox (`h264_videotoolbox`) is Apple's hardware video encoding framework. If you run Owncast on macOS, ffmpeg builds from Homebrew and most other sources include it, and it uses the media engine built into Apple hardware.

## ffmpeg

Once your system is configured to use the correct drivers and libraries required you'll need to make sure your copy of `ffmpeg` supports it.

Owncast suggests `ffmpeg` version 4.1.5 or newer. This is a suggestion, not a hard requirement. Owncast does not refuse to run with an older version, but you may experience issues with video.

```
$ ffmpeg -version
ffmpeg version 6.1.1 Copyright (c) 2000-2024 the FFmpeg developers
```

Verify the encoder you expect to use is enabled in your version of ffmpeg. This mirrors what Owncast itself does to populate the codec dropdown in the admin.

```
$ ffmpeg -hide_banner -encoders | grep 264
 V....D libx264              libx264 H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10 (codec: h264)
 V....D h264_v4l2m2m         V4L2 mem2mem H.264 encoder wrapper (codec: h264)
 V....D h264_vaapi           H.264/AVC (VAAPI) (codec: h264)
```

If the encoder you hope to use is not in this list then you may need to build your own copy of ffmpeg that supports it.

---

## Customizing colors and appearance

You can customize your Owncast page's colors and appearance from **Configuration → General → Appearance** in the admin. Start with the section color pickers, which need no code. For finer control you can write your own CSS in the editor, and the Owncast CSS helper below generates a starting point you can paste in.

If you want to go further with custom CSS it helps to be comfortable with CSS selectors and the CSS variable syntax, but you do not need either to get started.

## CSS Selectors

| Selector                | Description                                        |
| ----------------------- | -------------------------------------------------- |
| `header`                | The page header element                            |
| `footer`                | The page footer element                            |
| `#global-header-text`   | The text in the header                             |
| `#offline-banner`       | The banner that appears when the stream is offline |
| `#custom-page-content`  | The custom content of the page                     |
| `#notify-button`        | Button to display the notify modal                 |
| `#follow-button`        | Button to display the follow modal                 |
| `#followers-collection` | The collection of followers                        |
| `#modal-container`      | The container for the modals                       |
| `#chat-container`       | The container for the chat                         |
| `.chat-message_user`    | A user-sent chat message                           |
| `.chat-message_system`  | A system-sent chat message                         |
| `.chat-message_social`  | A social message from the Fediverse                |
| `.followers-follower`   | A single Follower in the followers collection      |

## CSS Variables

You can override the values assigned to CSS variables manually by setting them in the CSS editor in the admin.
You can find a list of [variable names](https://ui.owncast.online/?path=/docs/owncast-styles-colors-palette--docs) you can override.

For example, if you'd like to make all action items (links, buttons) red, button borders green, and change the body font to a `serif` font, you can set the following CSS variables as follows:

```css
:root {
  --theme-color-action: red;
  --theme-color-components-primary-button-border: green;
  --theme-text-body-font-family: serif;
}
```

### Additional selectors and variables

While, using CSS, you can target any element on the page, if there are specific elements you find yourself having difficulty customizing, please open an issue on the Owncast GitHub repository so we can consider adding additional selectors or CSS variables to make customization easier.
We will also likely add more customization options directly within Owncast's appearance page over time for common use cases. If you find yourself wanting to customize something specific, contributions are welcome!

## Appearance and theme plugins

:::new[Theme plugins require Owncast v0.3.0]
Theme plugins require Owncast 0.3.0 or later.
:::

Plugins can style the viewer page too. A theme plugin is the supported way to install and share a packaged look. Your settings on this page and a plugin's styles combine into the final result.

Your choices win. The colors you pick here and the CSS you write in the editor are applied on top of any plugin's styles, so where both touch the same color, yours takes effect. A theme plugin acts as a baseline: it changes the colors you have not set yourself, and any color you set explicitly overrides it.

When a plugin is styling your page, this page tells you:

- A notice at the top names the plugin or plugins currently applying styles.
- Each color a plugin also sets is flagged with an `also set by <plugin>` note next to its picker.

Two levers control the outcome:

- To let a theme plugin fully control the look, clear your own colors with **Reset to Defaults**. With nothing set here, the plugin's theme shows through completely.
- To stop a plugin's styling entirely, disable it on the **Plugins** page in the admin.

## Owncast CSS helper

To assist in customizing your Owncast colors via CSS variables and customizing specific elements, use the CSS helper below. This is meant to give you a head start in writing your own CSS, not a complete solution.
Select colors using the color pickers, edit the CSS directly as needed, then copy and paste the result into your Owncast admin under Configuration → General → Appearance.

:::tip
You can copy and paste your custom CSS and share it with other Owncast users as themes!
:::

<ColorThemeBuilder />

---

## Add custom JavaScript

If you have some JavaScript you need to run when your Owncast web page loads, you can add it in the admin under **Configuration** > **General** > **Custom Scripting**.

Some examples of reasons you might need this:

- Adding privacy-respecting analytics.
- Initializing a payment processor you have embedded on your page.
- Use JavaScript to manipulate the interface.

:::new[Plugin scripts require Owncast v0.3.0]
Starting in Owncast 0.3.0, the `/customjavascript` endpoint serves your code followed by the scripts of every enabled plugin, so your code and plugin scripts share the same page context.
:::

:::warning

Double check your JavaScript. Any incorrect syntax or errors that you insert into the page may create errors and stop the page from loading or functionality from working.
:::

---

## Configuration

For most people Owncast will be completely usable out of the box without additional configuration. Simply following the [Quickstart](/quickstart) will have you streaming in minutes.

Configuration is done in the admin. Open it at `/admin` on your server and sign in with your admin password. The **Configuration** menu contains:

- **General**: your server name, logo, tags and page content. See [customizing your website](/docs/configuration/website).
- **Server Setup**: admin password, stream keys, ports and S3 storage. See [server setup](/docs/configuration/server-setup).
- **Video**: quality variants, latency and codec settings. See [video quality](/docs/video).
- **Chat**: enable or disable chat and set moderation rules. See [chat moderation](/docs/chat/moderation).
- **Social**: Fediverse participation and social links. See [social features](/docs/social).
- **Notifications**: let your audience know when you go live. See [notifications](/docs/configuration/notifications).

A few related settings live elsewhere in the admin. [Webhooks](/docs/api/webhooks), [Access Tokens](/docs/api/requests) and [External Actions](/docs/api/actions) are under **Integrations**. Custom [emoji](/docs/chat/emoji) are under **Chat > Emojis**.

You can also [extend Owncast's functionality](/docs/extend) with plugins or by building your own bots, overlays, tools and integrations on the APIs.

---

## Live stream notifications

Some streams benefit from announcing to their audience when they go live.

This is not an endorsement of any particular service, but it may help some streamers integrate into their existing communities.

If you'd like to expand on this and send automated notifications to other destinations, create a custom [webhook](/docs/api/webhooks).

You'll find these channels under **Configuration → Notifications** in the admin.

Before you can enable any of them you must set your **Server URL** under **Configuration → General**. Until you do, every notification channel on this page is disabled and the admin shows a warning with a field to set it.

Go-live notifications are not instant. Owncast waits 2 minutes after your stream starts before sending them, which avoids notifying people about accidental or very short streams. And if a notification already went out in the previous 10 minutes, for example because your stream briefly dropped and reconnected, a new one is not sent.

<Tabs>
  <TabItem value="browser-push-notifications" label="Browser notifications" default>

        Using browser push notifications your viewers can choose to be notified each time you go live.

        To offer this, turn on **Enable browser notifications** and set the required **Go Live Text**, the message sent when you go live, up to 200 characters.

        Browser push notifications are not supported for local servers. Your instance must be reachable at a public HTTPS address.

        Not all browsers support this feature, and browsers that do may handle it differently. Brave, for example, requires you to choose the duration the notifications are valid. They will likely want to select "Forever" to keep the notification active.

        ### Enabling browser notifications on iOS

        You can request to be notified when a stream goes live on iOS by following these steps:

        1.  Open Safari and navigate to your Owncast instance.
        2.  Tap the share button in Safari.
        3.  Scroll down and tap "Add to Home Screen".
        4.  Tap "Add".
        5.  Give the link a name and tap the new icon on your home screen.
        6.  Press the "Notify" button and enable notifications.
        7.  Tap "Allow" when prompted.

  </TabItem>
  <TabItem value="browser-extension" label="Browser extension">
    Another suggested way to receive browser notifications from any number of
    streams is by using the [Owncast Browser Extension by
    craftamap](https://github.com/craftamap/owncast-browser-extension). It's
    available for
    [Chrome](https://chrome.google.com/webstore/detail/owncast-extension/djgneammmklaajinkihpibdpaflehgio)
    and
    [Firefox](https://addons.mozilla.org/en-US/firefox/addon/owncast-extension/).
  </TabItem>

<TabItem value="fediverse" label="Fediverse">
  The Fediverse social features have built in support to notify your followers
  when you go live. [Visit the documentation](/docs/social/) for more
  information.
</TabItem>

  <TabItem value="discord" label="Discord">
        You can notify a Discord channel when your stream goes live.

    - Visit Edit Channel / Integrations on your Discord channel and create a webhook. The [Discord documentation](https://support.discord.com/hc/en-us/articles/228383668) has complete instructions.
    - In the Owncast admin, turn on **Enable Discord**.
    - Paste the webhook into the **Webhook URL** field.
    - Set the **Go Live Text**, the message posted when you go live, up to 300 characters.
    </TabItem>

<TabItem value="custom" label="Custom">
  You can create your own custom notifications using
  [webhooks](/docs/api/webhooks). This allows you to send notifications to any
  service by writing your own integration.
</TabItem>

</Tabs>

---

## Plugins

Plugins let you add new behavior to your Owncast server without writing code yourself. They're small add-ons that run inside Owncast and can react to chat, viewers, stream events, and the fediverse. A plugin is delivered as a single `.ocpkg` file you upload from the admin.

:::new[Plugins require Owncast v0.3.0]
Plugins are brand-new functionality, introduced in Owncast v0.3.0, and there are few plugins available today. If you hit a bug or have a suggestion, please [open an issue](https://github.com/owncast/plugin-sdk/issues) or [chat live with the community](/chat?tab=community). If you have an idea for a plugin you'd like to see, share it with the [community](/chat?tab=community). You are encouraged to build your own plugins to share chat bots, stream overlays, custom integrations, themes and more. The [plugin SDK](/docs/plugins) has everything you need to get started.
:::

## What can a plugin do?

A plugin can:

- Add a **chat bot** that replies to commands, posts reminders, or removes spam.
- Add a **stream overlay** you can drop into OBS as a browser source (live chat overlays, viewer counters, alerts, and so on).
- **Connect Owncast to other services** like Discord, the fediverse, or your own webhooks, so going live or a new follower triggers something elsewhere.
- Add **custom UI buttons** that link to your store, donation page, schedule, or anything else.

The plugin author decides what their plugin does. You decide whether to install it.

## How a plugin asks for permission

Before a plugin can do anything sensitive, it has to declare it. When you install a plugin, the admin shows you a **Permissions** list, in plain language, of every capability the plugin will use: things like "Post chat messages as the plugin's own bot identity" or "Make outbound HTTP requests to other services". You review that list and decide whether to enable the plugin.

![The permission prompt Owncast shows when you install a plugin](/docs/img/plugins-permissions.png)

If the plugin is later updated and asks for **more** access than before, Owncast pauses the plugin and shows a "needs re-approval" badge. The plugin won't run again until you review the new permissions and approve them. Your existing approvals never expand silently.

## Installing a plugin

Open **Plugins** in the admin sidebar. There are two ways to add one.

**Browse the catalog.** The **Browse** tab lists plugins published to the public directory. Each card shows what the plugin does, who built it, and the permissions it asks for. Click **Install** on any of them and Owncast downloads it for you.

![The plugin catalog in the Owncast admin Browse tab](/docs/img/plugins-browse.png)

**Upload your own.** On the **Installed** tab, click **Upload plugin** and pick an `.ocpkg` file. Use this for a plugin you built yourself or got from somewhere other than the catalog. Every plugin has a unique identifier, so an upload that collides with a plugin you already have installed is rejected. Uninstall the old copy first if you are replacing it by hand.

Either way, Owncast shows you the plugin's permission list and asks whether to enable it. Toggle **Enabled** to load it. The plugin survives restarts, so you do not need to enable it again after a reboot.

## Disabling and removing

- **Disable** keeps the plugin installed but stops it from running. Toggle **Enabled** back on to load it again.
- **Uninstall** removes the plugin entirely. From the **Plugins** page click the trash icon on its row and confirm. The plugin's file is removed from the server and it stops doing anything immediately.

## Chat commands and `!help`

Many plugins add chat commands. These are short messages that start with a prefix, usually `!`, that tell a plugin to do something. The Timer Bot example below adds `!remind`, `!countdown`, and a few others. A viewer types the command and the plugin responds in chat.

You do not have to memorize what each plugin offers. Owncast has a built-in `!help` command. Anyone in chat can type `!help` (or `!commands`) and Owncast replies with a single message listing every command from supported plugins, grouped by plugin, each with a short description.

![Chat showing the !help command listing and the Timer Bot plugin in use](/docs/img/plugins-chat-help.png)

A few things worth knowing about `!help`:

- **Automatically generated.** Install a plugin that adds commands and they appear in `!help` right away. Disable it and they disappear.
- **Plugins advertise their own commands.** A plugin declares its commands and their descriptions, so there is nothing for you to configure. The descriptions you see in `!help` come straight from the plugin.
- **Moderator commands stay hidden.** Commands a plugin marks as moderator-only only show up in `!help` for your moderators.

## Hardware and resource usage

Plugins are standalone tiny programs that run inside Owncast. If you enable plugins they will take up some additional CPU and memory for the runtimes and plugin themselves. Generally the first plugin will see the most RAM usage jump, and then small increases from there. If you notice your server slowing down after enabling a plugin, try disabling it to see if performance improves.

## Where do plugins come from?

Plugins are built and shared by their authors.

When you install a third-party plugin, the **Permissions** list is your trust boundary. If a plugin asks for more access than you'd expect for what it claims to do, that's worth a second look before you enable it.

## Want to build one?

The full developer documentation lives at our [plugin development docs](/docs/plugins).

---

## Configuration via Runtime Flags

Configuration is generally done through the Owncast administration site located on your server under `/admin`, however, there are a number of runtime flags you can set when starting Owncast to modify its behavior.

Most admins never need these. Use the admin UI for normal configuration. The flags here are mainly for recovery, such as resetting a lost admin password, or for scripted and automated startups.

You can run Owncast with `--help` to see a full list of available runtime flags.

## Flag reference

| Flag                           | Value             | Purpose                                                                                       | Persistence                                     |
| ------------------------------ | ----------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `--adminpassword`              | password          | Set a new admin password. The usual way to recover access if you lost yours.                  | Saved to the database                           |
| `--backupdir`                  | directory path    | Directory where [database backups](/docs/backups) are written.                                | This run only                                   |
| `--database`                   | file path         | Use a database file other than the default `data/owncast.db`.                                 | This run only                                   |
| `--enableDebugFeatures`        | none              | Enable additional debugging options.                                                          | This run only                                   |
| `--enableVerboseLogging`       | none              | Enable additional logging.                                                                    | This run only                                   |
| `--followervalidationinterval` | seconds           | How often Fediverse followers are re-validated.                                               | This run only                                   |
| `--logdir`                     | directory path    | Directory where logs are written.                                                             | This run only                                   |
| `--restoreDatabase`            | backup file path  | Restore a database backup, then exit. Restart Owncast afterwards.                             | One-time action                                 |
| `--rtmpport`                   | port number       | Set the listen port for the RTMP server. Default is `1935`.                                   | Saved to the database                           |
| `--streamkey`                  | key               | Set a temporary stream key. While it's in effect the Stream Keys admin tab is hidden.         | This session only                               |
| `--webserverip`                | IP address        | Force the web server to listen on a specific IP address.                                      | Saved to the database                           |
| `--webserverport`              | port number       | Force the web server to listen on a specific port. Default is `8080`.                         | Saved to the database                           |

Flags marked "saved to the database" change your stored server configuration. The new value keeps applying on later starts even after you drop the flag. The others only affect the run they're passed to.

## Examples

Reset a lost admin password:

```bash
owncast --adminpassword mynewpassword
```

Set a temporary stream key for this session:

```bash
owncast --streamkey mystreamkey
```

Run on custom ports. You can also change ports in the admin, which requires a restart to take effect:

```bash
owncast --webserverport 9090 --rtmpport 2945
```

Restore a database backup:

```bash
owncast --restoreDatabase /path/to/owncastdb.bak
```

---

## Server Setup

The **Configuration → Server Setup** page in the admin holds the core settings of your server. It's split into three tabs: **Server Config**, **Stream Keys**, and **S3 Object Storage**.

## Server Config

### Admin Password

The password you use to log into the admin dashboard. Save it somewhere safe. A valid password must have:

- 8 to 192 characters
- at least one lowercase and one uppercase letter
- at least one digit
- at least one special character: `!@#$%^&*`
- no dash (`-`) anywhere

If you lose it, you can reset it at startup with the `--adminpassword` [runtime flag](/docs/configuration/runtime-flags/).

### FFmpeg Path

The absolute file path of the FFmpeg application on your server.

### Owncast port

The port the Owncast web server listens on. Default is `8080`. Changing it requires a restart.

### RTMP port

The port that accepts inbound broadcasts. Default is `1935`. Changing it requires a restart.

### RTMP address

The address or interface that accepts inbound broadcasts. Default is `0.0.0.0`, which listens on all interfaces. Changing it requires a restart.

### Advanced Settings

#### Websocket host override

If you have a CDN in front of your entire Owncast instance, set the direct URL of your origin server here so the chat websocket connects to it instead of the CDN. Enter it as an `http` or `https` URL. The web player converts it to `ws` or `wss` automatically. Most people never need to set this.

#### Serving Endpoint

An optional full URL that video content should be accessed from instead of the default. Used with [CDNs](/docs/cdns/) and specific storage providers. Generally not required.

## Stream Keys

Stream keys are the credentials your [broadcasting software](/docs/broadcasting/) uses to send video to your server. You can keep any number of keys, each with a comment so you remember what it's for. When you add a key, Owncast pre-fills an auto-generated 30 character value you can use as is.

If you set your own key it must have:

- 8 to 192 characters
- at least one lowercase and one uppercase letter
- at least one digit
- no dash (`-`) anywhere

Unlike the admin password, a special character is not required because some broadcasting software strips special characters from stream keys.

If you started Owncast with the `--streamkey` [runtime flag](/docs/configuration/runtime-flags/), a temporary key is used for that session and this tab is hidden.

For a step by step walkthrough of changing your key, see [change your streaming key](/docs/troubleshoot/change-streamkey/).

## S3 Object Storage

Offload video delivery to any S3 compatible storage provider instead of serving it from your own server. See the [object storage documentation](/docs/storage/) for setup instructions and provider examples.

---

## Run Owncast as a Background Service

You can run Owncast under [systemd](https://systemd.io/) so it starts automatically when your machine boots and restarts on its own if it crashes. This page is for Linux servers running systemd. If you run Owncast in a container, use Docker's `restart: unless-stopped` policy instead (see [Run Owncast in a container](/docs/getting-started/install/container)). On macOS the equivalent is a `launchd` agent.

## Create the service file

Create a file at `/etc/systemd/system/owncast.service` with the following. Change `WorkingDirectory`, `ExecStart`, `User`, and `Group` to match where Owncast is installed and the account it should run as.

```ini
[Unit]
Description=Owncast
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/owncast
ExecStart=/opt/owncast/owncast
User=owncast
Group=owncast
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

`WorkingDirectory` is the folder that holds the `owncast` binary and its `data/` directory. `ExecStart` is the full path to the binary. Do not run Owncast as `root`. Create a dedicated user (for example `sudo useradd --system --home-dir /opt/owncast owncast`) and point `User`/`Group` at it.

## Enable and start it

Reload systemd so it picks up the new file, then enable and start the service in one step:

```sh
sudo systemctl daemon-reload
sudo systemctl enable --now owncast
```

`enable --now` both starts Owncast immediately and sets it to start on every boot.

## Confirm it's running

```sh
systemctl status owncast
```

You should see `active (running)`. To follow the logs live:

```sh
journalctl -u owncast -f
```

Once it's running, load your server in a browser on port `8080` to confirm it's serving.

## Hardening (optional)

The project ships a [sample service file](https://github.com/owncast/owncast/blob/develop/contrib/owncast-sample.service) that adds systemd sandboxing options:

```ini
ReadWritePaths=/opt/owncast
NoNewPrivileges=true
SecureBits=noroot
ProtectSystem=strict
ProtectHome=read-only
```

`ProtectSystem=strict` makes most of the filesystem read-only, so `ReadWritePaths` must point at your Owncast directory or the server cannot write its `data/`. Add these to the `[Service]` section if you want them.

:::tip

The [contrib directory](https://github.com/owncast/owncast/tree/develop/contrib) holds more user-supplied examples (including notes for Windows). Those files are community-contributed and not officially supported, but they are a good starting point for setups this page doesn't cover.

:::

---

## Customize Your Owncast Site

## Overview

Owncast includes a web interface for your video with built-in chat that is available once you start the server. It shows online/offline states, viewer counts, stream duration, your instance's description, images, links and more. You can just start using it without making any changes, but you'll likely want to update the content displayed on your page by visiting your server admin page.

Additionally, the web interface was specifically built to be customizable by anybody comfortable tweaking colors and styles. No development environment is needed, just open the admin and start tweaking.

If you want to embed Owncast in your existing website, check out our [documentation on embedding Owncast](/docs/embed/).

Below are some items you'll likely want to customize to update the content that displays on your page. You'll find all of them on the **General** settings page in the admin.

### Name and About

By setting your name, About text and logo you can quickly update the contents of the website to reflect your stream. The **Name** field accepts up to 255 characters. The **About** field is a short blurb, up to 500 characters, about you, your server, or what your stream is about.

### Server URL

The full public URL of your server, for example `https://owncast.mysite.com`. You must set it before you can enable the [Owncast Directory](/docs/directory/) listing or any of the [live stream notifications](/docs/configuration/notifications/).

### Offline Message

An optional message, up to 2500 characters, shown to visitors when you're not streaming. Markdown is supported.

### Logo

Upload your logo as a PNG, JPEG or GIF up to 2 MB. A square image of at least 256x256 works best. SVGs are discouraged as they can't be displayed on all social media platforms.

### Favicon

Upload a custom favicon in PNG or ICO format, up to 200 KB. It appears in browser tabs and bookmarks.

### Tags

By setting tags you're showing potential viewers what categories of content you typically stream.

### External social links

You can add links to your profiles on other sites by adding them in the admin.

### Web page content

The body of your page content can be customized in your admin. Use standard [Markdown syntax](https://www.markdownguide.org/basic-syntax/) to add links, images, and more.

### Hide viewer count

Turn this on to hide the viewer count on your web page.

### Disable search engine indexing

Turn this on to ask search engines not to index your site.

### Enable directory

Request a listing in the [Owncast Directory](https://owncast.directory), an external service run by the Owncast project that helps people find streams. Requires the Server URL to be set. Read more about [the directory](/docs/directory/).

### NSFW

If you stream explicit or adult content, turn this on so unexpected eyes won't accidentally see it in the directory. Like the directory toggle, it requires the Server URL to be set.

---

## Host public assets

By creating a `data/public` directory and putting your own files there you can serve any assets that you wish to make publicly available for any reason.

Owncast 0.3.0 writes plugin-hosted files under `data/public/plugins/`, so do not place your own files there.

Afterward, you will be able to access these assets via the `/public` path on your Owncast web server. For example:

`https://stream.example.com/public/image.png`

`https://stream.example.com/public/style.css`

Some examples of reasons you might want to take advantage of this:

- Making a CSS font available so you can reference it in your custom CSS.
- You have images you wish to use in your page content.
- Some arbitrary files that you want people to download have no other place to be hosted.

---

## List Your Stream in the Owncast Directory

To help people discover streams by people using Owncast we have an optional Owncast directory located at https://owncast.directory you can add yourself to.

1. Visit the **"General"** settings in the admin.
1. Set the public URL to your Owncast instance that you want people to be linked to.
1. Set the **"About"** with a brief description of your stream.
1. Set the **tags** associated with the content you stream.
1. Mark if your content is _Not Safe For Work_ (nsfw).
1. Turn on the **"Enable directory"** toggle at the bottom of the page. It stays disabled until you have set your Server URL.

## If your server is not showing up in the directory

1. It's opt-in, so make sure you follow the [configuration directions](/docs/directory) to enable the directory for your server.
1. Your server registers by pinging the directory every 4 minutes, and only while you are live. Expect to show up a few minutes into the first stream after enabling this feature.
1. You may want to run your server with `owncast --enableVerboseLogging` to see what errors show up.
1. If you used to be listed, but no longer show up, reset your registration in the admin under **Server Setup** > **Advanced Settings** > **Reset Directory**. The section appears once the directory is enabled.
1. If you recently changed the URL of your server, reset your registration the same way.
1. If there's some issue that's causing you not to be listed [please file a GitHub issue](https://github.com/owncast/owncast/issues) so we can help troubleshoot or reset your registration with the directory.

## Browse the Owncast Directory

If your application has what is often called "IPTV" or M3U support, you can browse the directory directly by adding `https://owncast.directory/api/iptv` to the application. Not all apps support this.

Additionally, there are some native applications that allow you to browse the Owncast directory and watch streams directly from within the application. Read more about [watching streams](/docs/watching-streams/).

## Build your own directory

The Owncast directory is not the only one possible. Every Owncast server broadcasts its live status over ActivityPub, so you can run your own directory or aggregator that tracks which servers are streaming. See [building a directory of Owncast streams](/docs/api/activitypub#building-a-directory-of-owncast-streams) for the protocol, and the [owncast-directory-example](https://github.com/owncast/owncast-directory-example) repository for a small runnable reference.

---

## Embed Owncast Into Your Website

## Embedding video

Owncast supports embedding your video stream directly into any other web site or source without having to setup a player.

The video-only URL to your stream content lives at: `http://owncast.example.com/embed/video`.

Here's some example HTML you can use.

```html
<iframe
  src="https://owncast.example.com/embed/video"
  title="Owncast"
  height="350px"
  width="550px"
  referrerpolicy="origin"
  allowfullscreen
>
</iframe>
```

It will look something like:

<iframe
  src="https://watch.owncast.online/embed/video"
  title="Owncast"
  height="350px"
  width="550px"
  referrerpolicy="origin"
  allowfullscreen
></iframe>

### Autoplay

Whether an embedded video starts playing on its own follows your server's [autoplay setting](/docs/video/#autoplay). You can override it for a single embed by appending `?autoplay=` to the URL with one of `off`, `always`, or `sound-only`. An unrecognized value falls back to the server setting.

Most browsers block autoplay inside an iframe on another site unless the embedding page grants permission with the `allow` attribute:

```html
<iframe
  src="https://owncast.example.com/embed/video?autoplay=always"
  title="Owncast"
  height="350px"
  width="550px"
  referrerpolicy="origin"
  allow="autoplay"
  allowfullscreen
>
</iframe>
```

### Muting

If you would like the player to be muted once it starts playing, append `?initiallyMuted=true` to the URL. Viewers can still unmute manually. Combine parameters with `&`, for example `?autoplay=always&initiallyMuted=true`.

One interaction to know about: `sound-only` never starts silently, so combining it with `initiallyMuted=true` means the player will not autoplay at all.

### Hiding the follow button

If your server has social features enabled, the embedded player offers a follow button. Hide it for a single embed by appending `?supportsSocialFollow=false` to the URL. Any other value keeps the button.

## Customizing the Embedded Stream Styling

You can easily customize the styling of the embedded Owncast stream to match your website's design by applying CSS styles. Here's how you can do it:

1. **Create a CSS File:** First, create a CSS file (e.g., `stream-styles.css`) where you'll define your custom styles.

2. **Link the CSS File:** In the `<head>` section of your HTML document where you embed the Owncast stream, add a `<link>` tag to include your CSS file. Make sure to add this line before the closing `</head>` tag:

   ```html
   <link rel="stylesheet" href="path/to/stream-styles.css" />
   ```

   Replace "path/to/stream-styles.css" with the actual path to your CSS file.

3. **Apply Styles:** Customize the styles in your stream-styles.css file according to your preferences. You can target the `<iframe>` element using CSS selectors, as shown in the example below:

   ```css
   /* Style the embedded stream's iframe box */
   iframe[title="Owncast"] {
     border: none; /* Remove the iframe border */
     box-shadow: 0px 0px 10px rgba(0, 0, 0, 0.3); /* Add a subtle shadow for depth */
     border-radius: 10px; /* Rounded corners for a modern look */
     overflow: hidden;
     margin: 0 auto; /* Center the iframe horizontally */
   }
   ```

4. **Customize to Your Needs:** Adjust the values above to match your website's design and layout.

The embedded stream is a separate page loaded from your Owncast server, so your site's CSS can only style the `<iframe>` box itself, not the content inside it. To change the colors, fonts, and layout inside the player, use the [appearance settings](/docs/configuration/appearance) on your Owncast server instead.

Following these steps, you can seamlessly integrate your Owncast stream into your website while maintaining control over its visual appearance.

### Using the HLS feed

As long as the player supports it, it is recommended to open the homepage of your Owncast instance directly.
The player will automatically find the correct playlist and will start playing.
This will guarantee forward compatibility if the way how Owncast publishes HLS is ever changed.

However, if you need the HLS feed (i.e. for sharing your stream to a 3rd party player), you can access the HLS feed directly via this URL: `http://your.host/hls/stream.m3u8`.

## Embedding chat

Owncast supports embedding your chat directly into any other website or source.

There are two types of embed chats: A read-only chat which only shows the messages and a standalone chat which has the same functionality as the one within the main Owncast web interface.

### Embedding standalone chat

The standalone chat URL lives at: `http://owncast.example.com/embed/chat/readwrite`. It is the full chat: viewers get a name and can send messages, subject to the same chat rules as your main page.

```html
<iframe
  src="https://owncast.example.com/embed/chat/readwrite"
  title="Owncast chat"
  height="500px"
  width="350px"
></iframe>
```

It will look something like:

[Owncast Embed](https://watch.owncast.online/embed/chat/readwrite)

### Embedding read-only chat

The read-only chat URL lives at: `http://owncast.example.com/embed/chat/readonly`. It shows messages only, with no input for sending them.

```html
<iframe
  src="https://owncast.example.com/embed/chat/readonly"
  title="Owncast chat"
  height="500px"
  width="350px"
></iframe>
```

One common use of read-only chat is adding the chat messages to your broadcasting software, such as a web layer in OBS.

#### Using OBS

1. Click the `+` or right mouse click to add a new source. Choose `Browser` from the list.
1. For a new source, you will need to add the name. Type in "_Chat_".
1. In the Browser Source settings, you will need to change the URL to your Owncast instance's `/embed/chat/readonly` url.
1. You can use the _Custom CSS_ to tweak how the browser shows your video. The following example will add some space around the box, give it a semi-transparent dark background and increase the overall font size to a base unit of 24px. You may change any of these settings to fit your presentation layout. Note that the overall message text color is white.

   ```css
   html {
     margin: 0px;
     padding: 20px;
     background-color: rgba(0, 0, 0, 0);
     font-size: 24px;
   }

   #chat-container {
     background-color: rgba(0, 0, 0, 0.5);
   }
   ```

1. Click ‘OK’ to save your chat settings and re-position the new chat source in your scene.

## SSL Requirements

Embedded Owncast content that is not served via HTTPS within a page that is using SSL/TLS gets [blocked by browsers](https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content/How_to_fix_website_with_mixed_content). [Learn how you can use a SSL Proxy](/docs/sslproxies/nginx) to fulfil this browser requirement and secure your Owncast site.

---

## Ways to extend Owncast

There are two ways to build on top of Owncast, and the right one depends on where your code runs.

:::new[Plugins require Owncast v0.3.0]
Update your version of Owncast for plugin support.
:::

[**Plugins**](/docs/plugins) run inside the Owncast server. The server loads them at runtime, sandboxes them, and hands them events as they happen: chat messages, stream start and stop, fediverse activity, and HTTP requests. A plugin can add its own admin UI and serve endpoints without you hosting anything separately. Reach for a plugin when the behavior belongs with the server, such as a chat bot, a moderation rule, or a custom admin panel.

[**Web APIs and webhooks**](/docs/api) connect Owncast to code you run somewhere else. [Webhooks](/docs/api/webhooks) push events out to your application when something happens on the stream. The web APIs let your application send actions back in, like posting a chat message, authenticated with an access token. Reach for these when you already run a service, when you are wiring Owncast into a third-party tool, or when the integration should live outside the server.

Both can run at the same time, reacting to the same events. Owncast also speaks ActivityPub, so your server federates with the fediverse without any extra code.

---

## Configure Your Stream Key and First Stream

Any piece of software you're already using for live streaming is likely compatible with Owncast. Visit our [broadcasting software](/docs/broadcasting) page to see some specific pieces of software and how they're configured.

<IncludeMarkdown>
  <AdminLogin />
</IncludeMarkdown>

## Stream Key

To begin streaming you need two things: your Owncast server's RTMP URL (`rtmp://yourserver/live`) and a stream key. The stream key and the admin password both default to `abc123`, but they are separate settings. The stream key lets your broadcasting software publish video. The admin password logs you into the admin dashboard. Change both as soon as you can.

The admin password and stream keys are managed independently, so you can add as many stream keys as you like. Most people only need one, but multiple keys are useful in some setups, such as giving a co-host their own key you can revoke later.

You manage stream keys in the admin under **Configuration > Server Setup**, which has **Server Config** and **Stream Keys** tabs. New keys are auto-generated for you, and each key in the list can be revealed and copied. See the [server setup guide](/docs/configuration/server-setup) for the full page.

If you start Owncast with the `--streamkey` flag, the **Stream Keys** tab is hidden and the value from the command line is used for that session.

## What to configure next

Some common items many people update after installing Owncast are:

- Your site name, logo, description and external links that are displayed on the [web site](/docs/configuration/website).
- Your **stream key**, which your broadcasting software uses to publish video, and your **admin password**, which you use to log into the admin dashboard.
- Enable your stream to show up in the [Owncast Directory](/docs/directory).

Read more about [what you can configure and how](/docs/configuration).

---

## Use a container image

:::new[Plugin support requires an Owncast v0.3.0 build]
Owncast 0.3.0 features such as [plugins](/docs/plugins) are only in the nightly image, `ghcr.io/owncast/owncast:nightly`. The stable image is `owncast/owncast:latest` on Docker Hub.
:::

1. Pull the `latest` version [from Dockerhub](https://hub.docker.com/r/owncast/owncast/tags): `docker pull owncast/owncast:latest`.
1. Run the following to start the service. Binding the `data` directory keeps your database and backups on the host, so you can move them to another server later.

```bash
docker run --restart unless-stopped -v "$(pwd)/data:/app/data" -p 8080:8080 -p 1935:1935 owncast/owncast:latest
```

Alternatively, you can create a `docker-compose.yml` file with the following contents:

```yaml
services:
  owncast:
    image: owncast/owncast:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
      - "1935:1935"
    volumes:
      - ./data:/app/data
```

and run `docker compose up -d` to start the service.

To upgrade to a newer release later, pull the latest image and recreate the container: run `docker pull owncast/owncast:latest`, then `docker compose up -d` (or stop the container and re-run your `docker run` command).

## Login to the admin and set up your stream

<IncludeMarkdown>
  <AdminLogin />
</IncludeMarkdown>

---

## Installation

There are several ways to install Owncast. The quick installer below is the easiest and works on most Linux and macOS servers. You can also install [manually](#manual-installation) from a release download, run the [container image](/docs/getting-started/install/container), or use a [one-click install at a hosting provider](/docs/getting-started/install/providers).

<IncludeMarkdown>
  <Installer />
</IncludeMarkdown>

---

<IncludeMarkdown>
  ## Manual Installation
  <Manual />
</IncludeMarkdown>

---

## Owncast Quick Installer

By using the installer you can get up and running in about a minute. However, if you would prefer to [download a release manually](/docs/getting-started/install/manual), use a [one-click install](/docs/getting-started/install/providers) at a supported hosting provider, or other methods visit the [Installation page](/docs/getting-started/install/) to find the installation method that best matches your needs.

### Installer

Paste the following into your shell and the installer will download the most recent version of Owncast for your platform.
It will also download a copy of ffmpeg if you don't currently have one installed.

```bash
curl -s https://owncast.online/install.sh | bash
```

**Note**: It is not suggested you run this as root, as you're downloading and running a script off the internet. It's also recommended you inspect the contents of any remote script before executing it.

---

### See an example of getting running in under a minute.

<VideoPlayer
  src="/install-preview.mp4"
  webm="/install-preview.webm"
  poster="/install-preview.jpg"
  title="Getting Owncast running in under a minute"
  autoPlay={false}
  muted={false}
  controls={false}
  maxWidth="none"
/>

### That's it!

While the above installer will be enough for most people to get up and running quickly, you may want to learn about server configuration, broadcasting, and optional next steps such as [SSL proxies](/docs/sslproxies/nginx) and running Owncast as a [system service](/docs/configuration/systemservice).

## Login to the admin and set up your stream

<IncludeMarkdown>
  <AdminLogin />
</IncludeMarkdown>

---

## Manual Install

1. Owncast needs [ffmpeg](https://ffmpeg.org/) installed on your server. The automated installer downloads it for you, but a manual install does not, so install ffmpeg first if you do not already have it.
1. Make a directory to run the service from, and download the release that matches your server from the [releases page](https://github.com/owncast/owncast/releases) into that directory. Run `uname -m` to find your architecture, then pick the matching archive:

   | `uname -m` output | OS    | Archive                             |
   | ----------------- | ----- | ----------------------------------- |
   | `x86_64`          | Linux | `owncast-<version>-linux-64bit.zip` |
   | `aarch64`         | Linux | `owncast-<version>-linux-arm64.zip` |
   | `armv7l`          | Linux | `owncast-<version>-linux-arm7.zip`  |
   | `i686`            | Linux | `owncast-<version>-linux-32bit.zip` |
   | `x86_64`          | macOS | `owncast-<version>-macOS-64bit.zip` |
   | `arm64`           | macOS | `owncast-<version>-macOS-arm64.zip` |

   Raspberry Pi boards are covered by the `arm64` and `arm7` builds. There is no ARMv6 build, so the original Raspberry Pi and the first Pi Zero are not supported.
1. Unzip the release.
1. Make sure the two ports Owncast uses are reachable from outside your server: `8080` for the web interface and `1935` for RTMP ingest. Open them in your firewall or cloud provider's security rules if needed.
1. Run `./owncast` to start the service. This runs Owncast in the foreground. To keep it running in the background and start it on boot, [run it as a system service](/docs/configuration/systemservice).
1. Visit the admin at `/admin` to configure your server. Log in with the username `admin` and your admin password (`abc123` by default).

<IncludeMarkdown>
  <AdminLogin />
</IncludeMarkdown>

---

## Pre-installed Owncast with hosting providers

Some service providers offer 1-click-install options for Owncast where you can get up and running without manually installing the software yourself.

## Follow your hosting provider's instructions

Follow the instructions from your chosen hosting provider to get started, as each will have their own specific process. The Owncast project will generally not be able to support issues specific to your hosting provider, so please reach out to their support if you have any issues.

## What you need

1. A domain name and access to your DNS settings. This is required for supporting [SSL](/docs/sslproxies).
1. An account with a hosting provider that supports automatic Owncast installs.

### Some known providers

- [DigitalOcean](https://marketplace.digitalocean.com/apps/owncast?refcode=492f098407b2)
- [Elestio](https://elest.io/open-source/owncast). They are fully managed, meaning they handle updates, backups, etc.
- [Hetzner](https://docs.hetzner.com/cloud/apps/list/owncast/)
- [Hostinger](https://www.hostinger.com/vps/docker/owncast)
- [Linode/Akamai](https://www.linode.com/marketplace/apps/owncast/owncast/?r=588ad4bf08ce8394e8eb11f0a463fde64637af9d)
- [Reclaim Cloud](https://support.reclaimhosting.com/hc/en-us/articles/11925004212631-Installing-Owncast-on-Reclaim-Cloud)
- [Vultr](https://www.vultr.com/marketplace/apps/owncast/)

Some of these providers may offer free credits for new accounts, or give credit to Owncast for referrals.

## Setting up DNS

1. Login to your DNS provider.
1. Add an **"A Record"** pointing to the new server your hosting provider created, and the hostname you wish to use for Owncast.
1. Wait approximately 5 minutes, but it may take longer depending on your DNS provider.
1. When `http://your_new_server:8080` in your browser loads then your install is complete.
1. You may need to reboot your new server so the SSL proxy starts, depending on your hosting provider.

<IncludeMarkdown>
  <AdminLogin />
</IncludeMarkdown>

---

## Welcome

<DocsWelcomeBanner />

## Installation

If you're looking to install Owncast for the first time, go through our Quickstart Wizard to get up and running. It will guide you through the installation options available for your use cases. [Quickstart Wizard](/quickstart)

## Your first stream

Once you have Owncast running, you'll want to prepare for your first stream. Check out the [Configure Your Stream Key and First Stream](/docs/getting-started/configure-first-stream) guide to learn how to set up your broadcasting software and start streaming.

## Configuration

Owncast offers a variety of configuration options to customize your streaming experience. Visit the Configuration page to explore the different settings available, including video quality, page customization, social features, and more. [Configuration](/docs/configuration)

## Troubleshooting

Have questions or run into issues? The Troubleshooting Wizard provides solutions to common problems and answers to frequently asked questions. [Troubleshooting Wizard](/troubleshoot)

## Building on top of Owncast

Looking to build bots, overlays, integrations, tools or other custom functionality? Read about the [ways to extend Owncast](/docs/extend) to choose between plugins and the web APIs, or jump straight to the [API Reference](/api/release).

## Want to contribute to this documentation?

Owncast is an open source project and contributions to the documentation are welcome! If you find any errors, have suggestions for improvements, or want to add new content, please do help us make the documentation better for everyone! You can contribute by submitting a pull request on the [Owncast documentation repository](https://github.com/owncast/owncast.github.io). You'll get credited on the page you helped improve.

---

## Reducing Latency

## Overview

It is natural for you to want to have as little latency as possible between when you stream and when your viewers see the stream. However, there are a number of factors that contribute to latency in a streaming system like Owncast.

<IncludeMarkdown>
  <Reducing />
</IncludeMarkdown>

## Latency buffer levels

The **Latency Buffer** setting on the admin's Video configuration page selects one of five levels. Each level trades latency for stability by changing how long each video segment is and how many segments the playlist holds for viewers.

| Level       | Seconds per segment | Segments in playlist | Approximate latency |
| ----------- | ------------------- | -------------------- | ------------------- |
| 0 (lowest)  | 1                   | 25                   | ~5 seconds          |
| 1           | 2                   | 15                   | ~8-9 seconds        |
| 2 (default) | 3                   | 10                   | ~10 seconds         |
| 3           | 4                   | 8                    | ~15 seconds         |
| 4 (highest) | 5                   | 5                    | ~18 seconds         |

Changing the level while you are live does not affect the current stream. The new setting takes effect the next time you begin a stream.

## The Minimize latency player setting

:::new[Minimize latency option requires Owncast v0.3.0]
This option may not be the best for everyone. People should try it for themselves in the player settings.
:::

Viewers can turn on **Minimize latency** in the player's settings menu. It slightly speeds up playback to bring the viewer closer to live. It only acts when there is spare bandwidth and enough buffered video, it backs off immediately when playback conditions degrade, and it disables itself for the rest of the session after repeated buffering. Viewers with an unstable connection can leave it off.

---

## Stream performance

## Overall stream health

<IncludeMarkdown>
  <StreamHealth />
</IncludeMarkdown>

## Hardware

Knowing how your CPU, in particular, is keeping up with the video processing tasks is important when troubleshooting. Owncast gives you a high level overview of key hardware metrics to help with this.

If you see your hardware is being over utilized, you may wish to [troubleshoot](/troubleshoot).

## Prometheus

For people who prefer to use external monitoring solutions, Owncast supports using [Prometheus](https://prometheus.io/) to collect a set of metrics.

You can point your Prometheus config at your Owncast instance with the endpoint of `/api/admin/prometheus`, using basic auth and the admin login data.

For example:

```yaml
- job_name: owncast
  scrape_interval: 1m
  metrics_path: /api/admin/prometheus
  scheme: https
  basic_auth:
    username: admin
    password: my_admin_password
  static_configs:
    - targets: ["my.owncast.server"]
```

### Exported metrics

All series are gauges, and all carry two constant labels: `version` (the Owncast version) and `host` (your configured server URL, or `unknown` if it isn't set).

| Name                                        | Meaning                                                          |
| ------------------------------------------- | ---------------------------------------------------------------- |
| `owncast_instance_active_viewer_count`      | The number of current viewers.                                   |
| `owncast_instance_active_chat_client_count` | The number of connected chat clients.                            |
| `owncast_instance_total_chat_users`         | The total number of chat users on this Owncast instance.         |
| `owncast_instance_current_chat_message_count` | The number of chat messages currently saved before cleanup.    |
| `owncast_instance_playback_error_count`     | Errors reported by players within the current collection window. |
| `owncast_instance_cpu_usage`                | CPU usage as seen internally by Owncast.                         |

Owncast refreshes these values every 2 minutes, so scraping more frequently than that won't give you more resolution.

---

## Owncast Plugin APIs

The Owncast plugin runtime exposes a single global, `owncast`, with the host functions your plugin can call. Most methods require the matching permission in your manifest. A call without it never reaches Owncast: the host logs the denial and the call does nothing. What your plugin sees depends on the method. Mutating calls that report an outcome raise an error (moderation, `users.register`, `auth.grantSession`, `kv.set`, `videoConfig.write`, `actions.add`, `actions.clear`, and every `sql` method), readers return an empty or zero value, and calls that return nothing become silent no-ops. `fs.write`, `fs.delete`, and `storage.upload` are the exceptions: they report failure in their return value rather than raising. A few methods are **ambient** and need no permission: logging, timers, reading bundled assets, and `owncast.config.get`.

:::new[Plugin APIs require Owncast v0.3.0]
Plugins require Owncast 0.3.0 or later.
:::

Calls are shown for both SDKs, pick your language with the tabs. See [JavaScript](/docs/plugins/sdks/javascript) or [Python](/docs/plugins/sdks/python) for setup. (JavaScript method names are camelCase, Python uses `snake_case`, so `sendAction` becomes `send_action`, and so on.)

## Logging

### `owncast.log.info(message)`, `.warning(message)`, and `.error(message)`

Write an operator-visible entry to Owncast's server log. Owncast records the calling plugin's slug and the matching `info`, `warning`, or `error` severity. It replaces control characters with spaces so each entry stays on one line, then truncates messages longer than 4 KiB.

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

```js
owncast.log.info('sync started');
owncast.log.warning('provider response is incomplete');
owncast.log.error('sync failed');
```

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

```python
owncast.log.info("sync started")
owncast.log.warning("provider response is incomplete")
owncast.log.error("sync failed")
```

</TabItem>
</Tabs>

Ambient: no permission required. See the paired `chat-logger` examples for [JavaScript](https://github.com/owncast/plugin-sdk/tree/main/examples/js/chat-logger) and [Python](https://github.com/owncast/plugin-sdk/tree/main/examples/python/chat-logger).

## Chat

Building a chat bot, moderation tool, or filter? Start with [Chat plugins](/docs/plugins/chat).

### `owncast.chat.send(text)`

Post a chat message. Sent as your plugin's bot identity (display name from `bot.displayName` or `name` in your manifest).

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

```js
owncast.chat.send('hello chat');
```

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

```python
owncast.chat.send("hello chat")
```

</TabItem>
</Tabs>

Requires `chat.send`.

### `owncast.chat.sendAction(text)`

Post an action-style ("/me") message.

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

```js
owncast.chat.sendAction('is now live');
```

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

```python
owncast.chat.send_action("is now live")
```

</TabItem>
</Tabs>

Requires `chat.send`.

### `owncast.chat.system(body)`

Post a server-announcement message. No bot identity attached. The body renders inline as HTML, so use this for short, server-attributed notices like "the stream is starting in 5 minutes". Treat the body as untrusted-HTML output: don't interpolate user input into it without escaping.

Requires `chat.send`.

### `owncast.chat.sendTo(clientId, text)`

Send a private message to a single connected client.

Requires `chat.send`.

### `owncast.chat.replyTo(msg, text)` {/* #chat-replyto */}

Whisper a reply back to whoever sent a chat message. Pass the chat message from `onChatMessage`/`filterChatMessage` (or a bare client ID). Returns `false` if the sender's connection is unknown (no client ID), so you can fall back to a public `send`. Sugar over `sendTo(clientId, text)`.

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

```js
onChatMessage(msg) {
  if (!owncast.chat.replyTo(msg, "got it")) {
    owncast.chat.send("got it");
  }
}
```

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

```python
@plugin.on_chat_message
def handle(msg):
    if not owncast.chat.reply_to(msg, "got it"):
        owncast.chat.send("got it")
```

</TabItem>
</Tabs>

Requires `chat.send`.

### `owncast.chat.history(limit?)`

Return the most recent chat messages, each with `id`, `user`, `body`, and `timestamp`. `limit` defaults to 50.

Requires `chat.history`.

### `owncast.chat.clients()`

Return the list of currently-connected chat clients, each with `id`, `userId?`, `displayName?`, `connectedAt?`, `userAgent?`, `ipAddress?`, and `messageCount`. `id` is the per-connection client ID used by `chat.kick`.

Requires `chat.history`.

### `owncast.chat.deleteMessage(messageId)`

Hide a chat message from viewers.

Requires `chat.moderate`.

### `owncast.chat.kick(clientId)`

Disconnect a chat client.

Requires `chat.moderate`.

### Chat identity

Every plugin has exactly one chat identity, the bot Owncast provisions when your plugin is installed. The display name is your manifest's `bot.displayName` if set, otherwise its `name`, with `IsBot: true`. Both `send` and `sendAction` post as this identity, through Owncast's normal chat pipeline (filters, rate limits, moderation). Plugins cannot post under arbitrary names or impersonate real users.

The bot user is keyed on the plugin's `slug` so the identity survives manifest edits to `name` or `bot.displayName`. If you need multiple chat personas, ship multiple plugins.

## Users

### `owncast.users.list()` and `owncast.users.get(id)`

Read the chat user list or a single user record.

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

```js
const users = owncast.users.list();
const alice = owncast.users.get('u-alice');
```

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

```python
users = owncast.users.list()
alice = owncast.users.get("u-alice")
```

</TabItem>
</Tabs>

Requires `users.read`.

### `owncast.users.setEnabled(id, enabled, reason?)`

Enable or disable a chat user.

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

```js
owncast.users.setEnabled('u-spammer', false, 'spam');
```

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

```python
owncast.users.set_enabled("u-spammer", False, "spam")
```

</TabItem>
</Tabs>

Requires `users.moderate`.

### `owncast.users.banIP(ip)`

Ban an IP from joining chat.

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

```js
owncast.users.banIP('203.0.113.42');
```

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

```python
owncast.users.ban_ip("203.0.113.42")
```

</TabItem>
</Tabs>

Requires `users.moderate`.

### `owncast.users.register({ authId, displayName?, scopes?, profileUrl?, handle?, public? })` {/* #users-register */}

Find or create an authenticated Owncast user for an external identity and return `{ userId }`. Pass the provider's stable `authId` without adding your plugin slug. The host stores the slug separately as the identity provider, so plugins cannot collide with or spoof each other's users. `displayName` seeds a new user's name and is optional: omit it, or pass `null`, and Owncast generates a display name the same way it does for anonymous viewers. Non-empty `scopes` such as `["MODERATOR"]` are applied on each call.

The optional `profileUrl`, `handle`, and `public` fields describe a verified external identity. `profileUrl` must be empty or an absolute HTTP(S) URL. `handle` is the provider's verified label, such as a GitHub login or fediverse handle. Set `public` to `true` only after the viewer opts into public display. It defaults to `false`. These profile fields are captured when the identity is first registered. Later calls with the same `authId` return the existing user but do not change the stored profile fields.

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

```js
const { userId } = owncast.users.register({
  authId: 'github:583231',
  displayName: 'octocat',
  profileUrl: 'https://github.com/octocat',
  handle: 'octocat',
  public: false, // Set true only after the viewer opts in.
});
```

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

```python
result = owncast.users.register(
    "github:583231",
    display_name="octocat",
    profile_url="https://github.com/octocat",
    handle="octocat",
    public=False,  # Set true only after the viewer opts in.
)
user_id = result.user_id
```

</TabItem>
</Tabs>

Requires `users.register`.

## Authentication

These power a [viewer-authentication gate](/docs/plugins/auth). `grantSession` and `endSession` only work inside an `onHttpRequest` handler, because the host attaches the session cookie to the in-flight HTTP response.

### `owncast.auth.grantSession({ userId, ttl? })` {/* #auth-grant-session */}

Issue a signed session for an already-registered user (the `userId` from `owncast.users.register`). The host mints, signs, and attaches the session cookie to the current response; your plugin never sees the token, so it can't forge or leak it. `ttl` is an optional lifetime in seconds (`0`/omitted uses the host default of 24 hours).

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

```js
const { userId } = owncast.users.register({ authId: 'shared', displayName: 'Guest' });
owncast.auth.grantSession({ userId });
return { status: 302, headers: { Location: returnTo } };
```

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

```python
result = owncast.users.register("shared", display_name="Guest")
owncast.auth.grant_session(result.user_id)
return {"status": 302, "headers": {"Location": return_to}}
```

</TabItem>
</Tabs>

Requires `auth.gate`.

### `owncast.auth.endSession()` {/* #auth-end-session */}

Clear the current viewer's session cookie on this response to sign them out. Your plugin still controls the redirect (and may bounce on to the provider's own logout).

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

```js
owncast.auth.endSession();
return { status: 302, headers: { Location: '/' } };
```

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

```python
owncast.auth.end_session()
return {"status": 302, "headers": {"Location": "/"}}
```

</TabItem>
</Tabs>

Requires `auth.gate`.

## Storage

### `owncast.kv.get(key)` and `owncast.kv.set(key, value)`

Per-plugin key/value store, namespaced by your plugin's `slug`. Values are strings.

For richer types, use the JSON helpers (`getJSON` / `setJSON`, `get_json` / `set_json` in Python) instead of parsing and serializing yourself. The JSON getter returns the fallback when the key is unset or holds invalid JSON. Plugins cannot read each other's keys.

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

```js
owncast.kv.set('count', '1');
const n = Number(owncast.kv.get('count') ?? '0');

owncast.kv.setJSON('prefs', { theme: 'dark' });
const prefs = owncast.kv.getJSON('prefs', {});
```

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

```python
owncast.kv.set("count", "1")
n = int(owncast.kv.get("count") or "0")

owncast.kv.set_json("prefs", {"theme": "dark"})
prefs = owncast.kv.get_json("prefs", {})
```

</TabItem>
</Tabs>

Requires `storage.kv`.

### `owncast.storage.upload(name, data)`

Upload a file to Owncast's public file area. JavaScript accepts a `Uint8Array` or string. Python accepts `bytes` or `str`. Raw bytes are preserved, while strings are encoded as UTF-8. JavaScript returns `{ url }` or `null`. Python returns a dict accessed as `result["url"]`, or `None`.

Requires `storage.upload`.

### `owncast.fs.*`

A private, sandboxed filesystem at `data/plugin-storage/<your-slug>/files/`. Unlike `owncast.storage.upload`, these files stay server-side: they're never served over HTTP. Paths are relative to your sandbox root. The host confines every path to your own directory (a plugin cannot read another plugin's files, and `../` or absolute paths collapse back inside the sandbox). Parent directories are created as needed on write.

| JavaScript             | Python                 | Returns                                               |
| ---------------------- | ---------------------- | ----------------------------------------------------- |
| `fs.read(path)`        | `fs.read(path)`        | `Uint8Array` / `bytes`, or `null` / `None` if missing |
| `fs.readText(path)`    | `fs.read_text(path)`   | UTF-8 `string` / `str`, or `null` / `None` if missing |
| `fs.write(path, data)` | `fs.write(path, data)` | `{ error? }`                                          |
| `fs.list(dir)`         | `fs.list(dir)`         | entry names (a missing directory is empty)            |
| `fs.delete(path)`      | `fs.delete(path)`      | `{ error? }` for a file or empty directory            |
| `fs.exists(path)`      | `fs.exists(path)`      | boolean                                               |

`fs.read` preserves the original bytes. `fs.readText` and `fs.read_text` decode UTF-8. Python replaces malformed byte sequences when decoding. `fs.write` preserves a JavaScript `Uint8Array` or Python `bytes`, and UTF-8 encodes strings. `fs.write` and `fs.delete` return `{}` on success. If the host rejects the operation, they return `{ error }` with the reason.

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

```js
owncast.fs.write('notes/log.txt', 'hello');
const text = owncast.fs.readText('notes/log.txt');

const data = new Uint8Array([0xff, 0x00, 0x80]);
owncast.fs.write('cache/data.bin', data);
const stored = owncast.fs.read('cache/data.bin');
if (stored) owncast.storage.upload('data.bin', stored);
```

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

```python
owncast.fs.write("notes/log.txt", "hello")
text = owncast.fs.read_text("notes/log.txt")

data = bytes((0xFF, 0x00, 0x80))
owncast.fs.write("cache/data.bin", data)
stored = owncast.fs.read("cache/data.bin")
if stored is not None:
    owncast.storage.upload("data.bin", stored)
```

</TabItem>
</Tabs>

Requires `storage.fs`.

### `owncast.sql.*`

One private SQLite database per plugin, at `data/plugin-storage/<your-slug>/db/plugin.db`, separate from Owncast's own database and from the [`storage.fs`](/docs/plugins/permissions#storagefs) sandbox. The sandbox is rooted at `files/`, so `db/` is not a path `owncast.fs.*` refuses but one it cannot express, and the filesystem quota walk covers `files/` only, so the two quotas stay independent. Reach for this over [`storage.kv`](/docs/plugins/permissions#storagekv) when you need to sort, filter, or aggregate rather than just remember a value.

| Method                       | Returns                                              |
| ---------------------------- | ---------------------------------------------------- |
| `sql.exec(sql, params?)`     | `{ rowsAffected, lastInsertId }`                     |
| `sql.query(sql, params?)`    | rows as objects keyed by column name                 |
| `sql.queryRow(sql, params?)` | the first row object, or `null` when nothing matched |

In Python `queryRow` is `query_row`, rows come back as dicts, and `query_row` returns `None` when nothing matched. An error throws in JavaScript and raises `RuntimeError` in Python. Parameters are `null`/`None`, booleans, numbers, or strings. Anything else is refused.

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

```js
owncast.sql.exec(`CREATE TABLE IF NOT EXISTS chatters (
  user_id  TEXT PRIMARY KEY,
  messages INTEGER NOT NULL DEFAULT 0
)`);

owncast.sql.exec(
  `INSERT INTO chatters (user_id, messages) VALUES (?, 1)
   ON CONFLICT (user_id) DO UPDATE SET messages = messages + 1`,
  [msg.user.id],
);

const top = owncast.sql.query(
  'SELECT user_id, messages FROM chatters ORDER BY messages DESC LIMIT ?',
  [5],
);
const mine = owncast.sql.queryRow('SELECT messages FROM chatters WHERE user_id = ?', [msg.user.id]);
```

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

```python
owncast.sql.exec("""
    CREATE TABLE IF NOT EXISTS chatters (
      user_id  TEXT PRIMARY KEY,
      messages INTEGER NOT NULL DEFAULT 0
    )
""")

owncast.sql.exec(
    """
    INSERT INTO chatters (user_id, messages) VALUES (?, 1)
    ON CONFLICT (user_id) DO UPDATE SET messages = messages + 1
    """,
    [msg.user.id],
)

top = owncast.sql.query(
    "SELECT user_id, messages FROM chatters ORDER BY messages DESC LIMIT ?",
    [5],
)
mine = owncast.sql.query_row("SELECT messages FROM chatters WHERE user_id = ?", [msg.user.id])
```

</TabItem>
</Tabs>

Each `exec` call runs as one host-owned transaction. A multi-statement batch commits whole or leaves the database untouched, so a schema migration can't half-apply. A plugin cannot leave a transaction open across calls, so there's nothing to clean up either.

`query` never hands back a silently short result. A query that overruns the row cap or the result budget is an **error** telling you to add a `LIMIT`, so write the bound you actually want when a table grows with your audience. `queryRow` reads a single row, which keeps it cheap on a table `query` is too big for.

| Limit                 | Value                         |
| --------------------- | ----------------------------- |
| Encoded request       | 64 KiB total JSON             |
| Bound parameters      | 64 per call                   |
| Returned column value | 1 MiB                         |
| Encoded query result  | 1 MiB                         |
| Rows returned         | 10000                         |
| Call duration         | 2 seconds                     |
| Database size         | 128 MiB                       |

Ordinary SQL is unaffected: DDL, DML, indexes, views, triggers, `ORDER BY`, recursive CTEs, subqueries, `UNION`, and the json1 functions all work. Refused in every host: `ATTACH`, `DETACH`, every `PRAGMA` (reads included), temporary-schema DDL both as keywords (`CREATE TEMP TABLE` / `INDEX` / `TRIGGER` / `VIEW`) and schema-qualified (`CREATE TABLE temp.x`), `load_extension()`, `VACUUM` and `VACUUM INTO`, and transaction controls (`BEGIN`, `COMMIT`, `END`, `ROLLBACK`, `SAVEPOINT`, and `RELEASE`). `exec` already owns the transaction around the whole batch.

::::caution[JavaScript loses precision above 2^53]
Parameters and results cross the host boundary as JSON. Python can bind and read exact 64-bit SQLite integers. JavaScript loses unsafe integers before `JSON.stringify` on writes and during `JSON.parse` on reads. Store values above `Number.MAX_SAFE_INTEGER` (2^53 - 1) as TEXT when a JavaScript plugin needs them to remain exact.
::::

Requires `storage.sql`. For a worked example, the `chat-leaderboard` plugin covers schema creation in one atomic `exec`, an `ON CONFLICT` upsert, a bounded ranked `query`, and a single-row read, in both [JavaScript](https://github.com/owncast/plugin-sdk/tree/main/examples/js/chat-leaderboard) and [Python](https://github.com/owncast/plugin-sdk/tree/main/examples/python/chat-leaderboard). It contrasts with `message-counter`, which keeps the same counts in [`storage.kv`](/docs/plugins/permissions#storagekv) and cannot rank.

## Config

### `owncast.config.get(key, fallback?)`

Read one of your plugin's [manifest-declared `config`](/docs/plugins/configuration) settings. Returns the admin-set value when present, otherwise the declared default, already parsed to its declared type. For an unknown key (or one with no value) it returns `fallback`.

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

```js
const cooldownMs = owncast.config.get('cooldownMs', 2000);
```

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

```python
cooldown_ms = owncast.config.get("cooldownMs", 2000)
```

</TabItem>
</Tabs>

Ambient: no permission required. Prefer this over building a bespoke settings page and key/value plumbing for simple knobs. (The config key is whatever you named it in the manifest, and it isn't translated per language.)

## Network

### `owncast.http.fetch(url, opts?)`

Synchronous outbound HTTP request. `opts` carries `method`, `headers`, and `body`. The result is `{ status, headers, body }`. Only hosts listed in your manifest's `network.allowedHosts` are reachable. Everything else returns an error.

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

```js
const res = owncast.http.fetch('https://api.example.com/status');
if (res.status === 200) {
  const data = JSON.parse(res.body);
}
```

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

```python

res = owncast.http.fetch("https://api.example.com/status")
if res.status == 200:
    data = json.loads(res.body)
```

</TabItem>
</Tabs>

Requires `network.fetch` and a matching entry in `network.allowedHosts`. Use this for outbound HTTP rather than your language's own HTTP client (in Python, don't use `requests`: it won't compile into a plugin).

See [Manifest reference: network](/docs/plugins/manifest#network-outbound-http-allowlist) for allowlist syntax.

## Plugin-to-plugin events

### `owncast.events.emit(eventType, payload)`

Emit to a custom hook owned by another plugin. `eventType` is the fully
qualified `<recipient-slug>.<hook>` target. The host dispatches that exact name
and does not add the emitter's slug. The receiving plugin declares only its
local hook name. See the
[handlers reference](/docs/plugins/events#plugin-to-plugin-events).

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

```js
owncast.events.emit('announcer.announcement.broadcast', { text: 'We are live' });
```

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

```python
owncast.events.emit("announcer.announcement.broadcast", {"text": "We are live"})
```

</TabItem>
</Tabs>

Requires `events.emit`.

## Stream and server state

### `owncast.stream.current()`

The current live stream state: `{ online, title?, summary?, viewers, startedAt?, latencyLevel? }`.

Requires `server.read`.

### `owncast.stream.broadcaster()`

Inbound encode telemetry for the current connection: `{ remoteAddr?, codecs?, resolution?, framerate?, bitrates? }`. Read-only, and zero-valued when no broadcast is connected. For changing video output, see the [video configuration](#video-and-transcoding-configuration) group below.

Requires `server.read`.

### `owncast.server.info()`

Static server info: `{ name?, url?, summary?, welcomeMessage?, version? }`.

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

```js
const name = owncast.server.info().name;
```

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

```python
name = owncast.server.info().name
```

</TabItem>
</Tabs>

Requires `server.read`.

### `owncast.server.socials()`

The streamer's configured social links, each `{ platform, url, icon? }`.

Requires `server.read`.

### `owncast.server.emotes()`

The server's custom chat emotes: the same set the public `/api/emoji` endpoint serves, each `{ name, url }`. Useful for rendering or filtering `:code:` emotes server-side.

Requires `server.read`.

### `owncast.server.federation()`

Whether fediverse federation is enabled and under what handle: `{ enabled, username?, isPrivate? }`. `username` is omitted when unset, and `isPrivate` is present only when true.

Requires `server.read`.

### `owncast.server.tags()`

The streamer's configured tags, as a list of strings.

Requires `server.read`.

## Video and transcoding configuration

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

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>

```js
const cfg = owncast.videoConfig.read();
```

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

```python
cfg = owncast.video_config.read()
```

</TabItem>
</Tabs>

Requires `videoconfig.read`.

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

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, autoplay: "sound-only" });
```

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

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

</TabItem>
</Tabs>

Requires `videoconfig.write`. This is high-trust. Admins should grant sparingly.

## Notifications

### `owncast.notifications.discord(text)`

Send a Discord notification through the streamer's configured webhook.

Requires `notifications.send`.

### `owncast.notifications.browserPush({ title, body, url? })`

Push to subscribed browsers.

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

```js
owncast.notifications.browserPush({ title: 'Live now', body: 'Come say hi', url: '/' });
```

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

```python
owncast.notifications.browser_push({"title": "Live now", "body": "Come say hi", "url": "/"})
```

</TabItem>
</Tabs>

Requires `notifications.send`.

### `owncast.notifications.fediverse({ type, body, image?, link? })`

Send a fediverse-formatted notification (renders as a post to followers).

Requires `notifications.send`.

## Fediverse

### `owncast.fediverse.post(text)`

Make a public post to the fediverse from the Owncast account.

Returns `{ url }` on success (currently with an empty `url`: Owncast publishes the note but does not yet return its URL), or `null` when the host rejects the call.

Requires `fediverse.post`. High-trust: a fediverse post goes out under the streamer's own handle and can't be silently revoked. Admins should grant sparingly.

## Action buttons (runtime)

### `owncast.actions.add(button | buttons[])`

Append one or more action buttons to your plugin's manifest set without a reload. Each button takes the same fields as a `manifest.actions` entry (`title`, plus `url`/`openExternally` or inline `html`). The host validates each entry with the same rules as `manifest.actions` and persists the result so additions survive a reload. A rejected entry throws an error naming the entry and the rule it broke, and the whole batch is rejected, so nothing is added when any entry is invalid.

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

```js
owncast.actions.add({ title: 'Donate', url: '/plugins/my-plugin/donate', openExternally: true });
```

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

```python
owncast.actions.add({"title": "Donate", "url": "/plugins/my-plugin/donate", "openExternally": True})
```

</TabItem>
</Tabs>

Requires `ui.modify`.

### `owncast.actions.clear()`

Drop every runtime-added action button. Manifest-declared actions remain.

Requires `ui.modify`.

Full coverage in [UI: Action buttons](/docs/plugins/ui#action-buttons).

## Realtime push (Server-Sent Events)

### `owncast.sse.send(channel, event, data)`

Push a Server-Sent-Event to every browser connected to your plugin's `/_sse/<channel>` endpoint.

- `channel`: which stream to push to. Use `""` for the default channel.
- `event`: the event name the browser listens for. Use `""` for the default `message` event.
- `data`: payload. Strings are sent as-is. Anything else is JSON-encoded for you.

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

```js
owncast.sse.send('alerts', 'donation', { from: 'alice', amount: 5 });
```

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

```python
owncast.sse.send("alerts", "donation", {"from": "alice", "amount": 5})
```

</TabItem>
</Tabs>

Fire-and-forget. The call returns immediately and never blocks. Slow clients drop frames rather than stalling your plugin.

Requires `http.sse`.

Full coverage in [Serving HTTP: Realtime updates](/docs/plugins/http#realtime-updates-server-sent-events).

## Timers

Schedule deferred and repeating work. Timers are **ambient**, no permission required, and are cleared automatically when your plugin is disabled. (Python: `set_timeout`, `set_interval`, `clear`.)

### `owncast.timer.setTimeout(fn, ms)`

Run `fn` once after `ms` milliseconds. Returns an id.

### `owncast.timer.setInterval(fn, ms)`

Run `fn` repeatedly every `ms` milliseconds. Returns an id.

### `owncast.timer.clear(id)`

Cancel a pending timeout or interval by the id either call returned.

## Bundled assets

Read files you shipped in your plugin's `assets/` directory. **Ambient**: no permission required. (Python: `read`, `read_text`.)

### `owncast.assets.read(path)` and `owncast.assets.readText(path)`

Read a file bundled under `assets/`, relative to that directory. `read` returns the original bytes as a JavaScript `Uint8Array` or Python `bytes`. `readText` and Python's `read_text` decode the bytes as UTF-8. Python replaces malformed byte sequences when decoding. Missing files return `null` in JavaScript or `None` in Python.

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

```js
const image = owncast.assets.read('badge.png');
const template = owncast.assets.readText('template.html');
```

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

```python
image = owncast.assets.read("badge.png")
template = owncast.assets.read_text("template.html")
```

</TabItem>
</Tabs>

## Complete API reference

Method names below are the JavaScript (camelCase) form. The Python equivalents are `snake_case` (`sendAction` → `send_action`, `banIP` → `ban_ip`, `videoConfig` → `video_config`, and so on).

| API                                                                          | Permission           |
| ---------------------------------------------------------------------------- | -------------------- |
| `owncast.log.info` / `.warning` / `.error`                                   | none (ambient)       |
| `owncast.chat.send`                                                          | `chat.send`          |
| `owncast.chat.sendAction`                                                    | `chat.send`          |
| `owncast.chat.sendTo`                                                        | `chat.send`          |
| `owncast.chat.system`                                                        | `chat.send`          |
| `owncast.chat.replyTo`                                                       | `chat.send`          |
| `owncast.chat.history`                                                       | `chat.history`       |
| `owncast.chat.clients`                                                       | `chat.history`       |
| `owncast.chat.deleteMessage`                                                 | `chat.moderate`      |
| `owncast.chat.kick`                                                          | `chat.moderate`      |
| `owncast.users.list` / `.get`                                                | `users.read`         |
| `owncast.users.setEnabled` / `.banIP`                                        | `users.moderate`     |
| `owncast.users.register`                                                     | `users.register`     |
| `owncast.auth.grantSession` / `.endSession`                                  | `auth.gate`          |
| `owncast.kv.get` / `.set` / `.getJSON` / `.setJSON`                          | `storage.kv`         |
| `owncast.storage.upload`                                                     | `storage.upload`     |
| `owncast.fs.read` / `.readText` / `.write` / `.list` / `.delete` / `.exists` | `storage.fs`         |
| `owncast.sql.exec` / `.query` / `.queryRow`                                  | `storage.sql`        |
| `owncast.http.fetch`                                                         | `network.fetch`      |
| `owncast.events.emit`                                                        | `events.emit`        |
| `owncast.stream.current`                                                     | `server.read`        |
| `owncast.stream.broadcaster`                                                 | `server.read`        |
| `owncast.server.info` / `.socials` / `.emotes` / `.federation` / `.tags`     | `server.read`        |
| `owncast.videoConfig.read`                                                   | `videoconfig.read`   |
| `owncast.videoConfig.write`                                                  | `videoconfig.write`  |
| `owncast.notifications.discord` / `.browserPush` / `.fediverse`              | `notifications.send` |
| `owncast.fediverse.post`                                                     | `fediverse.post`     |
| `owncast.actions.add` / `.clear`                                             | `ui.modify`          |
| `owncast.timer.setTimeout` / `.setInterval` / `.clear`                       | none (ambient)       |
| `owncast.assets.read` / `.readText`                                          | none (ambient)       |
| `owncast.config.get`                                                         | none (ambient)       |
| `owncast.sse.send`                                                           | `http.sse`           |

---

## Authentication

An **authentication gate** plugin makes viewers sign in before reaching the
resources selected by the server operator. The plugin supplies the login
method, such as OAuth, a magic link, SAML, or a shared password. Owncast
enforces the selected access mode.

- **Your plugin is the identity provider.** It renders the login screen, talks to the external provider, and decides who is allowed in.
- **The Owncast host is the gatekeeper and session authority.** It owns the session cookie, enforces the selected access mode, and never puts your plugin in the per-request hot path.

:::info[Requires auth.gate]
Everything on this page needs the [`auth.gate`](/docs/plugins/permissions#authgate) permission, plus [`users.register`](/docs/plugins/permissions#usersregister) to create the authenticated user and [`http.serve`](/docs/plugins/permissions#httpserve) to render the login flow.
:::

## What gets gated

When an `auth.gate` plugin is enabled, the viewer page, chat, embeds,
`/api/config`, and the rest of the public web surface require login. A short
list of routes stays public in every mode, including Owncast's admin pages
(they keep their own admin authentication, so an operator can always disable a
broken gate), the instance logo, and the ActivityPub federation endpoints. See
[what bypasses the gate](#what-bypasses-the-gate) for the full list.

The operator selects one cumulative access mode on the plugin's
**Authentication** tab:

| Access mode | Effect |
| --- | --- |
| Website only (default) | The web interface requires sign-in. `/hls/*`, `/api/status`, and Owncast Directory listing stay public. |
| Website, video players, and other resources | Also gates Owncast-hosted `/hls/*`. Players such as VLC cannot complete the browser login. `/api/status` and directory listing stay public. |
| Website, video players, and server status requests | Gates the web interface, Owncast-hosted `/hls/*`, and `/api/status`. Owncast Directory listing is disabled. |

The modes are cumulative. There is no status-only mode that hides
`/api/status` while leaving HLS public. The default protects the website
without breaking existing players or uptime monitors.

Selecting either stream-protection mode blocks native players. VLC, QuickTime,
mobile apps, and restreamers cannot complete a browser login or carry the
session cookie. An `Authorization` header or query token does not bypass the
gate.

A viewer with a valid session is always let through, regardless of the
selected mode.

:::warning[Distributing your video with External storage (Object storage/CDN) caveat]
When distributing your video stream directly from your server, stream protection is airtight: every byte flows through Owncast. With Object Storage or CDN, playlists are rewritten to absolute remote URLs and segments are fetched directly from the bucket, so the gate never sees those requests. Gating still stops an anonymous visitor from _discovering_ the segment list, but a _leaked or shared_ segment URL stays fetchable. **Stream protection + local distribution is airtight. Stream protection + Object Storage is good friction, not airtight.**
:::

## How it works

Once the gate is armed, every non-exempt request is checked. Under stream protection that includes each HLS segment, which a live viewer pulls every few seconds. Calling into your plugin's embedded engine on every one of those would melt the server, so the plugin is kept out of the hot path:

| When                                             | Cost                                                                   | What happens                                                         |
| ------------------------------------------------ | ---------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Every non-exempt request**                     | Verify cookie signature + expiry                                       | valid passes. Missing or invalid gets a redirect to login, or a `401` for anything that is not a `GET` or `HEAD` |
| **`/` page loads only**                          | Optional engine call: [`onAuthCheck`](/docs/plugins/events#auth-check) | re-validate against your provider, returns `ok` / `refresh` / `deny` |

Your plugin only runs the **login flow** (infrequent, about once per viewer session) and the optional per-page-load `onAuthCheck`. The Owncast host mints and checks a **signed session cookie** so the per-request check is signature-and-expiry only: no database lookup, no plugin call.

The cookie is a signed envelope carrying an Owncast access token plus a session expiry. The host mints a fresh access token for the user each time it grants a session. The Owncast host owns the cookie end to end: it reserves the cookie name (`owncast_session`), signs it with a host-held secret, and attaches it to the response. Your plugin never sees or sets the token, so it can't forge or leak one. (This is also how chat picks up the viewer's identity automatically. See [Chat identity](#chat-identity) below.)

## Building a gate plugin

A gate plugin is an [HTTP-serving plugin](/docs/plugins/http) with a login flow. The control loop, by convention, is rooted at your plugin's own namespace `/plugins/<your-slug>/`:

```mermaid
flowchart TD
    Visit([Visitor requests a page]) --> Cookie{"Valid sessioncookie?"}
    Cookie -->|"missing or invalid"| Login["Owncast host redirects to your login screen/plugins/&lt;slug&gt;/?return_to=…"]
    Login --> Flow["Your plugin runs the login flow(a password form, or an OAuth round-tripto the provider and back to your callback)"]
    Flow --> Register["owncast.users.register → userId"]
    Register --> Grant["owncast.auth.grantSessionOwncast host mints and attaches the signed cookie"]
    Grant --> Redirect([Redirect to return_to])
    Redirect --> Cookie
    Cookie -->|"valid"| Check["onAuthCheck(/ page loads only)"]
    Check --> Render([Render the page])
```

Three pieces do the work:

1. **Register the user.** Turn the external identity into a real Owncast user with [`owncast.users.register`](/docs/plugins/apis#users-register). Pass a stable, provider-scoped `authId` (e.g. `"github:583231"`). The host namespaces it by your slug so plugins can't collide or spoof each other.
2. **Grant the session.** Call [`owncast.auth.grantSession`](/docs/plugins/apis#auth-grant-session) with that `userId`. The Owncast host mints the signed cookie and attaches it to the in-flight response. This only works inside an `onHttpRequest` handler.
3. **Redirect home.** The Owncast host appends a `return_to` query parameter when it bounces an unauthenticated visitor to your login screen, and **sanitizes it to a same-origin path** (so it can't be turned into an open redirect). Send the viewer there after a successful login.

To sign a viewer out, call [`owncast.auth.endSession()`](/docs/plugins/apis#auth-end-session) and redirect. Your plugin still controls where to (it may bounce on to the provider's own logout).

### Revocation with `onAuthCheck`

Sessions are stateless, so there's no per-request "is this user still allowed" list. That would put the plugin back on the hot path. Instead, define the optional [`onAuthCheck`](/docs/plugins/events#auth-check) handler. It fires on each `/` page load with the resolved viewer identity, and returns `ok`, `refresh` (re-issue the cookie, optionally with a new TTL for sliding expiry), or `deny` (end the session and bounce to login). A provider-backed plugin re-checks membership here (org still valid? account not deleted?).

Because the check runs only on `/`, a viewer you revoke keeps any open tab working until they reload or the cookie expires. The session **TTL is the hard backstop** for revocation, so keep it short if fast revocation matters.

## Worked example: a shared-password gate

The `basic-auth` example plugin is the simplest possible gate: one shared password, one shared "Guest" identity, no external provider. It ships in both [`examples/js/basic-auth`](https://github.com/owncast/plugin-sdk/tree/main/examples/js/basic-auth) and [`examples/python/basic-auth`](https://github.com/owncast/plugin-sdk/tree/main/examples/python/basic-auth).

Its manifest declares the permissions and a single config field for the password:

```json
{
  "name": "Basic Auth",
  "slug": "basic-auth",
  "version": "0.1.0",
  "permissions": ["auth.gate", "users.register", "http.serve", "storage.kv"],
  "config": {
    "password": {
      "type": "string",
      "default": "letmein",
      "description": "Shared password viewers must enter to watch"
    }
  }
}
```

The handler renders a password form at `/`, checks the submitted password against the configured value, and on success registers the shared identity, grants a session, and redirects back. `onAuthCheck` reads an admin-flippable `revoked` flag to kick everyone on their next page load. (The `page()` helper that builds the HTML form is omitted below for brevity. See the example source.)

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

```js
const { definePlugin, owncast, authCheck } = require('@owncast/plugin-sdk');

module.exports = definePlugin({
  onHttpRequest(req) {
    const query = req.query || {};
    const returnTo = query.return_to || '/';

    if (req.method === 'GET' && req.path === '/') {
      return {
        status: 200,
        headers: { 'content-type': 'text/html' },
        body: page(returnTo),
      };
    }

    if (req.path === '/login') {
      const expected = owncast.config.get('password', 'letmein');
      if ((query.password || '') !== expected) {
        return {
          status: 200,
          headers: { 'content-type': 'text/html' },
          body: page(returnTo, 'Incorrect password.'),
        };
      }
      // Everyone who knows the password shares one authenticated identity.
      const { userId } = owncast.users.register({
        authId: 'shared',
        displayName: 'Guest',
      });
      owncast.auth.grantSession({ userId });
      return { status: 302, headers: { Location: returnTo } };
    }

    if (req.path === '/logout') {
      owncast.auth.endSession();
      return { status: 302, headers: { Location: '/' } };
    }

    // Admin-only revocation toggle. req.authenticated is true for admins only.
    if (req.path === '/revoke' || req.path === '/unrevoke') {
      if (!req.authenticated) return { status: 403, body: 'admin only' };
      owncast.kv.set('revoked', req.path === '/revoke' ? '1' : '');
      return {
        status: 200,
        body: req.path === '/revoke' ? 'revoked' : 'unrevoked',
      };
    }

    return { status: 404, body: 'not found' };
  },

  // Re-validate on each page load. While revoked, end every session.
  onAuthCheck() {
    if (owncast.kv.get('revoked') === '1') return authCheck.deny('access has been revoked');
    return authCheck.ok();
  },
});
```

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

```python
from owncast_plugin import plugin, owncast, auth_check

@plugin.get("/")
def login_form(req):
    return_to = (req.raw.get("query") or {}).get("return_to") or "/"
    return {"status": 200, "headers": {"content-type": "text/html"}, "body": page(return_to)}

@plugin.get("/login")
def login(req):
    query = req.raw.get("query") or {}
    return_to = query.get("return_to") or "/"
    expected = owncast.config.get("password", "letmein")
    if (query.get("password") or "") != expected:
        return {"status": 200, "headers": {"content-type": "text/html"},
                "body": page(return_to, "Incorrect password.")}
    # Everyone who knows the password shares one authenticated identity.
    result = owncast.users.register("shared", display_name="Guest")
    owncast.auth.grant_session(result.user_id)
    return {"status": 302, "headers": {"Location": return_to}}

@plugin.get("/logout")
def logout(req):
    owncast.auth.end_session()
    return {"status": 302, "headers": {"Location": "/"}}

@plugin.get("/revoke")
def revoke(req):
    if not req.authenticated:  # true for admin requests only
        return {"status": 403, "body": "admin only"}
    owncast.kv.set("revoked", "1")
    return {"status": 200, "body": "revoked"}

@plugin.on_auth_check
def check(_req):
    # Re-validate on each page load. While revoked, end every session.
    if owncast.kv.get("revoked") == "1":
        return auth_check.deny("access has been revoked")
    return auth_check.ok()
```

</TabItem>
</Tabs>

For a real OAuth flow (CSRF `state` in [`storage.kv`](/docs/plugins/permissions#storagekv), a code exchange over [`network.fetch`](/docs/plugins/permissions#networkfetch), org-membership enforcement, and a callback URL built from [`owncast.server.info()`](/docs/plugins/apis#stream-and-server-state)), see the `github-auth` example in the SDK.

## Enabling the gate

Declaring `auth.gate` does nothing on its own. The gate is armed by **enabling the plugin** through the normal enable/disable lifecycle in the admin. Disable it and the gate drops instantly.

- **Only one `auth.gate` plugin can be enabled at a time.** Owncast refuses to enable a second one while one is already live ("disable the other first").
- **Configure before you enable.** A plugin can be installed and configured while disabled, then enabled to go live. Use the auto-generated [config form](/docs/plugins/configuration) for credentials like an OAuth client ID and secret.

### Fail closed

The gate's posture is decoupled from your plugin's health. If the gate is armed but the plugin is unavailable (crashed, failed to load, errored, or auto-disabled after repeated failures), Owncast **denies all viewer traffic** and serves a static "authentication temporarily unavailable" page. It never falls open. The admin is always reachable (admin routes use Owncast's existing Basic Auth and bypass the gate) so you can fix the config or disable the plugin. Already-valid sessions survive an outage, because checking a cookie needs no plugin call.

A gate that is enabled but not running is still a gate. No access-policy setting can turn a failing-closed gate into an open one.

### What bypasses the gate

The gate covers the otherwise-public surface. Routes that enforce their own
credentials bypass it. The selected access mode also leaves some resources
public.

Always exempt:

- The active gate plugin's own namespace `/plugins/<your-slug>/*` and its static assets, so the login screen remains reachable.
- `/admin/*` and `/api/admin/*`, which use admin authentication.
- External API routes under `/api/integrations/`, which validate their own Bearer tokens.
- Static viewer assets needed to render the page. HTML entry points are still gated.
- `/api/yp`, which the Owncast Directory fetches anonymously. The most restrictive mode disables directory listing and makes this endpoint return `404`.
- `/logo` and `/logo/external`, the instance logo, which the viewer shell and federation metadata both reference.
- `/federation/*`, the ActivityPub protocol surface. Those handlers enforce Owncast's own federation and privacy settings.

Mode-dependent:

- `/hls/*` stays public only in **Website only** mode.
- `/api/status` stays public in **Website only** and **Website, video players, and other resources** modes.

Everything else is gated, including embeds and `/api/config`.

## Session details

- **Stateless signed cookie** named `owncast_session`, `HttpOnly`, `Secure` (on HTTPS requests), `SameSite=Lax`, `Path=/`. Lax rather than Strict because the provider callback is a cross-site top-level redirect. The host owns the name: a plugin that tries to set it in its own response has that header stripped.
- **TTL is set by your plugin** when it calls `grantSession({ ttl })`, defaulting to 24 hours and capped at 30 days. A sliding refresh is available through `onAuthCheck`'s `refresh` verdict. Because the TTL is the revocation backstop, it's a real security knob.
- **The signing secret is the Owncast host's responsibility.** It's auto-generated on first use and persisted in config. Rotating it invalidates every session (a panic button). Plugin authors never touch it, and it's separate from any OAuth _client_ secret, which is your plugin's config concern.

## Chat identity {/* #chat-identity */}

A gate login produces an authenticated chat identity automatically. Because `users.register` creates or links a real Owncast user (marked authenticated, with the display name you passed, or a generated one if you passed none) and the session cookie carries an access token for that user, chat reads the identity straight from the cookie: when `/ws` (or a chat REST call) arrives with no `?accessToken=` query parameter, it falls back to the access token in the gate cookie. No token is ever shuttled into the browser's `localStorage`. The viewer signs in once and shows up in chat under that name.

## Related

- [Permissions](/docs/plugins/permissions): `auth.gate`, `users.register`
- [Owncast APIs](/docs/plugins/apis#authentication): `users.register`, `auth.grantSession`, `auth.endSession`
- [Events](/docs/plugins/events#auth-check): the `onAuthCheck` handler
- [Serving HTTP](/docs/plugins/http): the request model the login flow is built on

---

## Chat plugins

If you want to build a plugin that talks in chat, reacts to viewers, or moderates messages, this is the page to start with. Code samples are shown in both supported languages. Set up your toolchain on the [JavaScript](/docs/plugins/sdks/javascript) or [Python](/docs/plugins/sdks/python) SDK page first.

Owncast exposes chat functionality in three layers:

1. **Chat event handlers** so your plugin can react when people talk, join, leave, or rename themselves.
2. **Chat and user APIs** so your plugin can post messages, inspect chat state, and moderate users.
3. **Chat filters** so your plugin can rewrite or drop messages *before* viewers see them.

## What you can build

* Chat bots that reply to commands or keywords.
* Welcome bots that greet people when they join.
* Reminder bots that post messages when the stream starts.
* Countdown and timer bots powered by `owncast.timer` or the tick handler.
* Moderation helpers that hide messages, disconnect clients, or disable abusive users.
* Filters that rewrite, translate, or drop messages before they are broadcast.

A reply bot is just one handler:

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

```js
const { definePlugin, owncast } = require("@owncast/plugin-sdk");

module.exports = definePlugin({
  onChatMessage(msg) {
    const name = msg.user?.displayName ?? "someone";
    owncast.chat.send(`${name} said: ${msg.body}`);
  },
});
```

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

```python
from owncast_plugin import plugin, owncast

@plugin.on_chat_message
def echo(msg):
    name = msg.user.display_name if msg.user else "someone"
    owncast.chat.send(f"{name} said: {msg.body}")
```

</TabItem>
</Tabs>

## Reacting to chat

Define `onChatMessage` (`@plugin.on_chat_message` in Python) to see each message after filters run, just before it broadcasts to viewers:

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

```js
module.exports = definePlugin({
  onChatMessage(msg) {
    owncast.chat.send(`echo: ${msg.body}`);
  },
});
```

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

```python
@plugin.on_chat_message
def echo(msg):
    owncast.chat.send(f"echo: {msg.body}")
```

</TabItem>
</Tabs>

The fields you reach for most are `msg.body` (the raw text), `msg.user` (the sender identity, with `user.id` for per-user state and `user.scopes` for moderator checks), and `msg.timestamp` (deterministic, so prefer it over the clock when comparing elapsed time or asserting in tests). Don't key state or permissions off display names.

For the full message payload and every other event a chat plugin can subscribe to (user join and part, rename, moderation, and more), see the [Events reference](/docs/plugins/events).

## Sending chat messages

### `owncast.chat.send`

Post a chat message. Sent as your plugin's bot identity. Takes plain text, not markup: the chat UI HTML-escapes it on display, so characters like `<`, `&`, and `"` render as text rather than HTML.

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

```js
owncast.chat.send("hello chat");
owncast.chat.sendAction("waves");        // /me-style action message
owncast.chat.system("Stream starting in 5 minutes");
```

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

```python
owncast.chat.send("hello chat")
owncast.chat.send_action("waves")        # /me-style action message
owncast.chat.system("Stream starting in 5 minutes")
```

</TabItem>
</Tabs>

Requires `chat.send`.

### `owncast.chat.sendAction`

Post an action-style (`/me`) message: `sendAction` in JavaScript, `send_action` in Python. Like `send`, takes plain text and is HTML-escaped by the chat UI on display.

Requires `chat.send`.

### `owncast.chat.system`

Post a server-announcement message. No bot identity is attached. The body renders inline as HTML. Use this for short, server-attributed notices like "Stream starting in 5 minutes". Treat the body as untrusted HTML output: don't interpolate viewer-controlled input without escaping it.

Requires `chat.send`.

### Chat identity

Every plugin has exactly one chat identity: the bot Owncast provisions when your plugin is installed. Its display name is your manifest's `bot.displayName` if set, otherwise `name`.

Both `send` and `sendAction` post as this identity through Owncast's normal chat pipeline, including filters, rate limits, and moderation. Plugins cannot post under arbitrary names or impersonate real users.

The bot user is keyed on the plugin's `slug`, so the identity survives manifest edits to `name` or `bot.displayName`. If you need multiple chat personas, ship multiple plugins.

## Reading chat state

### `owncast.chat.history`

Return the most recent chat messages (an optional limit defaults to 50). Each entry has the shape `{ id, user?, clientId?, body, timestamp }`.

Requires `chat.history`.

### `owncast.chat.clients`

Return the list of currently connected chat clients: `{ id, userId?, displayName?, connectedAt?, userAgent?, ipAddress?, messageCount? }`. The `id` is the per-connection client ID used by `owncast.chat.kick`.

Requires `chat.history`.

### `owncast.server.emotes`

Read the server's custom chat emotes (`{ name, url }`) when your bot wants to reference or mirror the emote catalog.

Requires `server.read`.

### `owncast.users.list` and `owncast.users.get`

Read the chat user list or a single user record by id.

Requires `users.read`.

## Moderation APIs

These are `deleteMessage` / `kick` / `sendTo` / `replyTo` in JavaScript and `delete_message` / `kick` / `send_to` / `reply_to` in Python.

### `owncast.chat.deleteMessage`

Hide a chat message from viewers, by message id.

Requires `chat.moderate`.

### `owncast.chat.kick`

Disconnect a chat client, by client id.

Requires `chat.moderate`.

### `owncast.chat.sendTo`

Send a private message to a single connected client, by client id.

Requires `chat.send`.

### `owncast.chat.replyTo`

Whisper a reply back to whoever sent a chat message. You can pass either the full message object from the chat-message / filter handler, or a bare client id if that's all you have. It returns a falsy value when the sender connection is no longer known, which gives you a clean fallback to a public message.

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

```js
module.exports = definePlugin({
  onChatMessage(msg) {
    if (!owncast.chat.replyTo(msg, "psst: got your message")) {
      owncast.chat.send("got your message"); // sender already disconnected
    }
  },
});
```

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

```python
@plugin.on_chat_message
def whisper(msg):
    if not owncast.chat.reply_to(msg, "psst: got your message"):
        owncast.chat.send("got your message")  # sender already disconnected
```

</TabItem>
</Tabs>

Requires `chat.send`.

## Commands

For chat commands, declare a command table with aliases, cooldowns, moderator gating, and automatic `!help` listings. See [Chat commands](/docs/plugins/commands).

## Moderating users

### `owncast.users.setEnabled`

Enable or disable a chat user, by id, with an optional reason: `setEnabled` in JavaScript, `set_enabled` in Python.

Requires `users.moderate`.

### `owncast.users.banIP`

Ban an IP from joining chat: `banIP` in JavaScript, `ban_ip` in Python.

Requires `users.moderate`.

## Chat filters

Filters see chat messages before they're broadcast, with the ability to rewrite or drop them. Filters run lowest-priority first. A `drop` ends the chain and the message never reaches later filters or notifications. A `modify` passes the new payload to the next filter.

### `filterChatMessage`

Receives the same `ChatMessage` shape as the chat-message handler and returns one of three results, built with the `filter` helper:

* **pass**: let the message through unchanged.
* **modify**: replace it with a new payload.
* **drop**: drop it (with a reason). The chain stops here.

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

```js
const { definePlugin, filter } = require("@owncast/plugin-sdk");

module.exports = definePlugin({
  filterChatMessage(msg) {
    if (msg.body.includes("spam")) return filter.drop("spam keyword");
    if (msg.body.includes("damn")) {
      return filter.modify({ ...msg, body: msg.body.replace("damn", "****") });
    }
    return filter.pass();
  },
});
```

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

```python
from owncast_plugin import plugin, filter

@plugin.filter_chat_message
def clean(msg):
    if "spam" in msg.body:
        return filter.drop("spam keyword")
    if "damn" in msg.body:
        return filter.modify({**msg.raw, "body": msg.body.replace("damn", "****")})
    return filter.pass_()  # trailing underscore: pass is a keyword
```

</TabItem>
</Tabs>

Requires the `chat.filter` permission. The host rejects the load if a plugin defines the filter handler without declaring that permission.

### Filter priority (optional)

Lower numbers run earlier. Default `100`. Set it with `filterPriority` (JavaScript) on the plugin definition, or by calling `plugin.set_filter_priority(priority)` (Python).

Use this when your plugin's behavior depends on whether other filters have already run. For example, a profanity filter should usually run before a translator.

### Filter safety

* Errors are treated as a pass. A throwing filter never blocks chat.
* Filters are time-capped at 50 ms. A slow filter is cancelled and treated as pass.
* After 5 consecutive failures (errors or timeouts) the plugin is auto-disabled for the rest of the session. A successful filter call resets the counter.

## Host-enforced limits that matter for chat plugins

A few host limits are worth designing around:

* filter runtime: **50 ms** per message
* event-handler runtime (chat-message, user-joined, etc.): **500 ms** per call
* hard per-call ceiling: **10 s**
* filter output size: **1 MiB**
* pending timers: **64** at once
* timer delay range: **100 ms to 24 h**

That means chat bots and filters should stay lightweight, avoid slow network round-trips in the hot path, and keep rewritten payloads small.

## Permissions you'll commonly need

* `chat.send`: post chat messages and private replies.
* `chat.history`: read recent chat messages and connected clients.
* `chat.moderate`: hide messages and disconnect clients.
* `chat.filter`: rewrite or drop messages before broadcast.
* `users.read`: inspect user records.
* `users.moderate`: disable chat users or ban IPs.

See [Permissions](/docs/plugins/permissions) for the complete security model.

## Example chat plugins

The plugin SDK ships small chat-focused examples that map closely to the patterns on this page (each has both a JavaScript and a Python version):

* `echo-bot`: the smallest possible reply bot using the chat-message handler + `owncast.chat.send`.
* `chat-logger`: logs every chat message without replying.
* `stream-tracker`: combines chat commands, chat-user lifecycle handlers, and action announcements.
* `profanity-filter`: rewrites messages without dropping them.
* `slow-mode`: drops messages using `msg.timestamp` for rate limiting.
* `engagement-bot`: moderates by deleting a message.
* `timer-bot`: reminder/countdown bots driven from chat, using timers and the tick handler.

Browse them at [examples/js](https://github.com/owncast/plugin-sdk/tree/main/examples/js) · [examples/python](https://github.com/owncast/plugin-sdk/tree/main/examples/python).

## Where this fits with the other plugin docs

* [Choosing an SDK](/docs/plugins) and the [JavaScript](/docs/plugins/sdks/javascript) / [Python](/docs/plugins/sdks/python) pages cover the language-specific setup, CLI, and syntax.
* [Chat commands](/docs/plugins/commands) covers command tables, the automatic `!help`, and mixing commands with your own chat handlers.
* [Event handlers](/docs/plugins/events) is the full handler reference for *all* plugin events.
* [Owncast APIs](/docs/plugins/apis) is the full API reference for *all* `owncast.*` methods.
* [Manifest reference](/docs/plugins/manifest) covers permissions, bot identity fields, and every manifest property.
* [Contributing UI](/docs/plugins/ui) covers viewer-side UI, overlays, buttons, scripts, and styles if your chat plugin also ships frontend pieces.

If you're starting from scratch, read [Quickstart](/docs/plugins/quickstart) first and then come back here.

---

## Chat plugin commands

Declare a command table for commands such as `!uptime` or `!so`. Command tables
support aliases, moderator gates, per-user cooldowns, parsed arguments, and
automatic `!help` listings. See [chat basics](/docs/plugins/chat) for the chat
message payload, sending messages, and filters.

## Register a command table

A command table provides:

- a configurable command prefix, with `!` as the default
- per-command `description`, `usage`, and `aliases`
- per-user cooldowns
- moderator-only gating based on the sender's scopes
- argument parsing
- an automatic `!help` listing

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

```js
const { definePlugin } = require('@owncast/plugin-sdk');

module.exports = definePlugin({
  commandPrefix: '!', // optional
  commands: {
    uptime: {
      description: "How long we've been live",
      run: ctx => ctx.reply("we've been live a while!"),
    },
    so: {
      description: 'Shout out a viewer',
      usage: '!so <name>',
      aliases: ['shoutout'],
      cooldownMs: 10_000,
      run: ctx => ctx.reply(`go follow ${ctx.args[0] || 'someone cool'}`),
    },
    clear: {
      description: 'Clear the chat',
      modOnly: true,
      run: ctx => ctx.replyPrivately('done'),
    },
  },
});
```

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

```python
from owncast_plugin import plugin

plugin.commands({
    "uptime": {
        "description": "How long we've been live",
        "run": lambda ctx: ctx.reply("we've been live a while!"),
    },
    "so": {
        "description": "Shout out a viewer",
        "usage": "!so <name>",
        "aliases": ["shoutout"],
        "cooldown_ms": 10_000,
        "run": lambda ctx: ctx.reply(
            f"go follow {ctx.args[0] if ctx.args else 'someone cool'}"
        ),
    },
    "clear": {
        "description": "Clear the chat",
        "mod_only": True,
        "run": lambda ctx: ctx.reply_privately("done"),
    },
}, prefix="!")
```

</TabItem>
</Tabs>

JavaScript handlers receive `msg`, `user`, `command`, `invokedAs`, `args`,
`argString`, `reply`, and `replyPrivately`. Python uses `invoked_as`,
`arg_string`, and `reply_privately`.

Duplicate command names are allowed, so every matching plugin runs.
Unknown commands, moderator-gated invocations, and cooldown-limited invocations
are silent. Declaring or receiving a command requires no permission. Actions
inside the handler still require their usual permissions, such as `chat.send`.

## `!help` is automatic but not reserved

Owncast posts a system message listing command descriptions from every enabled
plugin. Moderator-only commands stay hidden from non-moderators. This built-in
response needs no plugin permission.

`!help` and its `!commands` alias remain ordinary chat messages. Plugins may
also declare or respond to them. The built-in response does not block additional
plugin responses.

## Using ordinary chat handlers and filters

A command table is optional. A plugin may inspect `msg.body` in an
`onChatMessage` handler for a single fixed command. Hand-rolled commands do not
appear in the built-in help listing.

Command messages remain ordinary chat messages, so a plugin may use both a
command table and an ordinary chat handler. Chat filters run before command
matching. A message dropped by a filter does not execute any declared command.

## Example plugins

- **mod-commands** ([JavaScript](https://github.com/owncast/plugin-sdk/tree/main/examples/js/mod-commands), [Python](https://github.com/owncast/plugin-sdk/tree/main/examples/python/mod-commands)): a custom `?` prefix with aliases, cooldowns, and moderator gating.
- **stream-tracker** ([JavaScript](https://github.com/owncast/plugin-sdk/tree/main/examples/js/stream-tracker), [Python](https://github.com/owncast/plugin-sdk/tree/main/examples/python/stream-tracker)): a command table with `!uptime` and `!who`, plus stream and chat-user activity tracking.
- **stream-ops** ([JavaScript](https://github.com/owncast/plugin-sdk/tree/main/examples/js/stream-ops), [Python](https://github.com/owncast/plugin-sdk/tree/main/examples/python/stream-ops)): a command table that reports broadcast and video telemetry.
- **timer-bot** ([JavaScript](https://github.com/owncast/plugin-sdk/tree/main/examples/js/timer-bot), [Python](https://github.com/owncast/plugin-sdk/tree/main/examples/python/timer-bot)): a command table for reminders and countdowns (`!remind`, `!every`, `!countdown`).
- **ip-bot** ([JavaScript](https://github.com/owncast/plugin-sdk/tree/main/examples/js/ip-bot), [Python](https://github.com/owncast/plugin-sdk/tree/main/examples/python/ip-bot)): a single `!ip` command answered with the server's public IP.
- **relay** ([JavaScript](https://github.com/owncast/plugin-sdk/tree/main/examples/js/relay), [Python](https://github.com/owncast/plugin-sdk/tree/main/examples/python/relay)): re-emits `/announce <text>` as a broadcast announcement.

## Where to go next

- [Chat plugins](/docs/plugins/chat) for the chat message payload, sending messages, and filters.
- [Handlers reference](/docs/plugins/events) for the chat events your plugin can subscribe to.
- [APIs reference](/docs/plugins/apis) for every `owncast.*` method and the permission it needs.

---

## Configuration via Plugins

Owncast gives plugins two ways to let an admin change settings. Declare a `config` block in the manifest and Owncast renders a typed form for you, with no admin HTML and no save or load code to write. Or register an `admin` page and serve your own HTML.

Use the manifest `config` block for flat, typed knobs: strings, numbers, and switches. Reach for a [custom admin page](/docs/plugins/ui#admin-pages) only when you need a UI the auto-form can't express, like a grouped layout, a live preview, or an action button that calls your own API. The two can coexist. A plugin can have both the auto-form Settings tab and one or more custom admin pages.

## Declare settings in the manifest

Each entry under `config` has a `type`, a `default`, and a `description`:

```json
{
  "config": {
    "greeting": { "type": "string", "default": "welcome!", "description": "First-join message" },
    "cooldownMs": { "type": "number", "default": 2000, "description": "Per-user command cooldown" },
    "modOnly": { "type": "boolean", "default": false, "description": "Restrict to moderators" }
  }
}
```

| Field         | Notes                                                                                                                          |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `type`        | One of `string`, `number`, or `boolean`. Any other value is accepted but gets a plain text input and no type checking on save. |
| `default`     | The value `config.get` returns until an admin saves an override. Its JSON type should match `type`.                            |
| `description` | The label shown next to the field in the admin form. Falls back to the key name when empty.                                    |

Key names cannot start with `__`. That prefix is reserved for per-instance state the host injects, and a plugin that declares a key like `__internal` fails to load.

## What the admin sees

A plugin that declares a `config` block gets a **Settings** tab on its detail page under Admin → Plugins. Owncast builds the form from the schema:

- `string` renders a text input, `number` a numeric input, and `boolean` a switch.
- The `description` is the field label.
- The `default` shows until an admin saves an override.
- A key whose name looks like a credential renders as a masked password input. The match is case-insensitive and fires when the name contains `secret`, `password`, `token`, `apikey`, or `api_key`, or is the standalone word `key`. So `apiKey`, `clientSecret`, `accessToken`, and `webhook_secret` mask. Names like `accessKey` or `keyValue` do not, because `key` only matches as a whole word. Name a secret field `apiKey`, `api_key`, or anything ending in `Secret` or `Token` if you want it masked.

A plugin with no `config` block shows no Settings tab.

## Read values at runtime

`owncast.config.get(key, fallback?)` returns the admin's override when one is set, otherwise the declared default, already parsed to the declared type.

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

```js
const cooldownMs = owncast.config.get('cooldownMs', 2000);
const modOnly = owncast.config.get('modOnly', false);
```

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

```python
cooldown_ms = owncast.config.get("cooldownMs", 2000)
mod_only = owncast.config.get("modOnly", False)
```

</TabItem>
</Tabs>

`config.get` is ambient, so it needs no permission. A `number` field comes back as a number and a `boolean` as a bool, so you don't parse strings yourself. For an unknown key, or a declared key that has neither a default nor a saved override, it returns `fallback` (`undefined` in JavaScript and `None` in Python when you pass none). Pass a fallback you can run with.

The full signature lives in the [APIs reference](/docs/plugins/apis#config).

## Validation and storage

When an admin saves the form, Owncast checks each value against the schema before storing it:

- A key not declared in the manifest is rejected with `400 unknown config key`.
- A `string` field must receive a string, a `number` a number, and a `boolean` a bool. A type mismatch is rejected. Any other declared `type` is stored as-is.
- The request body is capped at 1 MB.

Overrides persist in the plugin's own key/value store under the reserved key `owncast.config`, namespaced by the plugin's `slug`. Other plugins can't read them, and they survive restarts and reinstalls. Changing the `slug` after release starts a fresh store, so saved overrides revert to their defaults, the same rule that applies to the rest of your [KV data](/docs/plugins/apis#storage).

---

## Plugin Events

Plugins react to things happening in Owncast by defining a handler for each event they care about. Only define the handlers you want: a missing handler means no subscription, and the SDK derives the manifest's subscription list from which handlers are present, so there's nothing else to keep in sync.

Code below is shown for both SDKs. Pick your language with the tabs, and your choice follows you across the docs. New to this? See the [JavaScript](/docs/plugins/sdks/javascript) or [Python](/docs/plugins/sdks/python) setup pages first.

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

```js
const { definePlugin, owncast, filter } = require('@owncast/plugin-sdk');

module.exports = definePlugin({
  onChatMessage(msg) {
    /* react to a chat message */
  },
  onStreamStarted(info) {
    /* react to the stream going live */
  },
});
```

Handlers are methods on the object you pass to `definePlugin`, named in camelCase (`onChatMessage`, `onStreamStarted`, …). Payload fields are camelCase too (`msg.user.displayName`, `msg.clientId`).

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

```python
from owncast_plugin import plugin, owncast, filter

@plugin.on_chat_message
def handle_chat(msg):
    # react to a chat message
    ...

@plugin.on_stream_started
def handle_live(info):
    # react to the stream going live
    ...
```

Handlers are decorated functions (`@plugin.on_chat_message`, `@plugin.on_stream_started`, …). Payload fields are snake_case (`msg.user.display_name`, `msg.client_id`). Use `msg.raw` for the underlying dict.

</TabItem>
</Tabs>

Payloads are shown as their wire shape. Each SDK exposes the fields idiomatically: the JavaScript SDK as-is, the Python SDK as snake_case attributes over the same JSON (with the raw dict available too).

## Chat events

Building a chat-focused plugin? [Chat plugins](/docs/plugins/chat) is a friendlier starting point.

### Chat message: `chat.message.received`

Fires once per chat message after filters have run and the message is being broadcast to viewers.

```ts
interface ChatMessage {
  id: string;
  user?: User; // full sender identity (see User below); absent for the rare message with no account
  clientId?: number; // originating connection; pass to the chat send-to / reply-to APIs for private replies
  body: string; // raw text, not HTML-rendered markup
  timestamp: string; // RFC3339Nano / ISO-8601, e.g. "2026-05-28T14:00:00.123456789Z"
}
```

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

```js
module.exports = definePlugin({
  onChatMessage(msg) {
    if (msg.user?.scopes?.includes('MODERATOR')) {
      owncast.chat.send(`hi mod ${msg.user.displayName}`);
    }
  },
});
```

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

```python
@plugin.on_chat_message
def greet_mods(msg):
    if msg.user and "MODERATOR" in (msg.user.scopes or []):
        owncast.chat.send(f"hi mod {msg.user.display_name}")
```

</TabItem>
</Tabs>

`user` carries the **full sender identity**, so key per-user state on the stable `user.id` and gate moderator-only behavior on `user.scopes` (e.g. `"MODERATOR"`) rather than matching the display name. To reply privately to the sender, use the chat reply-to API (see [Owncast APIs](/docs/plugins/apis#chat-replyto)).

`timestamp` is the host's wall-clock time for the message. The sandbox clock works, but `timestamp` is deterministic and the right choice when comparing elapsed time across events or asserting in tests.

No permission required to subscribe.

> **Older hosts** delivered `user` as a plain display-name string rather than the identity object. If you support hosts that predate the identity payload, read it defensively. See your SDK page for the idiom.

### Chat user joined / parted: `chat.user.joined`, `chat.user.parted`

Fires when a chat user connects or disconnects.

```ts
interface User {
  id: string;
  displayName: string;
  displayColor: number; // index into the instance's user-color palette, not a literal color
  previousNames?: string[];
  createdAt?: string; // ISO-8601
  disabledAt?: string; // ISO-8601 if banned, omitted otherwise
  isBot?: boolean;
  isAuthenticated?: boolean;
  scopes?: string[];
}
```

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

```js
module.exports = definePlugin({
  onChatUserJoined(user) {
    owncast.chat.send(`welcome ${user.displayName}`);
  },
  onChatUserParted(user) {
    /* … */
  },
});
```

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

```python
@plugin.on_chat_user_joined
def welcome(user):
    owncast.chat.send(f"welcome {user.display_name}")

@plugin.on_chat_user_parted
def farewell(user):
    ...
```

</TabItem>
</Tabs>

No permission required.

### Chat user renamed: `chat.user.renamed`

Fires when a chat user changes their display name.

```ts
interface { user: User; previousName: string }
```

No permission required.

### Message moderated: `chat.message.moderated`

Fires when a moderator hides or unhides a chat message.

```ts
interface { messageId: string; visible: boolean; moderator?: User }
```

No permission required.

## Stream lifecycle

### Stream started: `stream.started`

Fires when a broadcast begins.

```ts
interface { startedAt?: string; title?: string; summary?: string }
```

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

```js
module.exports = definePlugin({
  onStreamStarted(info) {
    owncast.chat.send(`live now: ${info.title}`);
  },
  onStreamStopped(info) {
    /* … */
  },
  onStreamTitleChanged(change) {
    /* change.to */
  },
});
```

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

```python
@plugin.on_stream_started
def announce(info):
    owncast.chat.send(f"live now: {info.title}")

@plugin.on_stream_stopped
def wrap_up(info):
    ...

@plugin.on_stream_title_changed
def retitle(change):
    ...  # change.to
```

</TabItem>
</Tabs>

No permission required.

### Stream stopped: `stream.stopped`

Fires when a broadcast ends.

```ts
interface { stoppedAt?: string }
```

No permission required.

### Stream title changed: `stream.title.changed`

Fires when the streamer updates the title mid-stream.

```ts
interface { from: string; to: string }
```

`from` is currently always empty: Owncast's title-changed event carries only the new title.

No permission required.

## Fediverse events

Owncast exposes internal plugin event subscriptions for inbound Fediverse activity. These are plugin events, not external HTTP webhooks. Every subscription in this section requires the `fediverse.inbound` permission.

| Event                | JavaScript handler   | Python handler                 | Payload                     |
| -------------------- | -------------------- | ------------------------------ | --------------------------- |
| `fediverse.follow`   | `onFediverseFollow`  | `@plugin.on_fediverse_follow`  | `{ actor }`                 |
| `fediverse.like`     | `onFediverseLike`    | `@plugin.on_fediverse_like`    | `{ actor, target }`         |
| `fediverse.repost`   | `onFediverseRepost`  | `@plugin.on_fediverse_repost`  | `{ actor, target }`         |
| `fediverse.quote`    | `onFediverseQuote`   | `@plugin.on_fediverse_quote`   | `FediverseQuote`            |
| `fediverse.mention`  | `onFediverseMention` | `@plugin.on_fediverse_mention` | `FediverseInboundPost`      |
| `fediverse.reply`    | `onFediverseReply`   | `@plugin.on_fediverse_reply`   | `FediverseInboundPost`      |
| `fediverse.activity` | `onFediverse`        | `@plugin.on_fediverse`         | Raw ActivityPub JSON object |

### Follow, like, repost, and quote

```ts
interface FediverseActor {
  name: string;
  handle: string;
  url?: string;
  image?: string;
}

interface FediverseEngagement {
  actor: FediverseActor;
  target?: { url: string };
}

interface FediverseQuote extends FediverseEngagement {
  target: { url: string }; // locally authored post being quoted
  content?: string; // rendered HTML from the source instance
  contentText?: string; // plain-text version
  url: string; // remote quote post permalink
  postedAt?: string; // ISO-8601
  inReplyTo?: string;
  attachments?: { url: string; mediaType: string; alt?: string }[];
  language?: string;
}
```

A follow contains only `actor`. Likes and reposts also contain `target`.

A quote contains `target` for the locally authored post and `url` for the remote quote post. Content metadata is included when the requesting server embeds its quote `Note` in the `QuoteRequest`. Some servers send only the quote post IRI, so `content`, `contentText`, `postedAt`, `inReplyTo`, `attachments`, and `language` are optional.

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

```js
module.exports = definePlugin({
  onFediverseFollow(event) {
    owncast.chat.send(`new follower: ${event.actor.handle}`);
  },
  onFediverseQuote(event) {
    console.log(`${event.actor.handle}: ${event.contentText ?? 'quoted your post'}`);
    console.log(`quote: ${event.url}`);
  },
});
```

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

```python
@plugin.on_fediverse_follow
def thank(event):
    owncast.chat.send(f"new follower: {event.actor.handle}")

@plugin.on_fediverse_quote
def record_quote(event):
    print(f"{event.actor.handle}: {event.content_text or 'quoted your post'}")
    print(f"quote: {event.url}")
```

</TabItem>
</Tabs>

`actor.handle` is the fully qualified address, such as `@alice@fediverse.example`. The follow examples also call `owncast.chat.send`, which separately requires `chat.send`:

```json
{ "permissions": ["fediverse.inbound", "chat.send"] }
```

### Mention and reply

Both receive a `FediverseInboundPost`:

```ts
interface FediverseInboundPost {
  actor: FediverseActor;
  content: string; // rendered HTML from the source instance
  contentText: string; // plain-text version, usually what you want
  url: string; // permalink on the source instance
  postedAt: string; // ISO-8601
  inReplyTo?: string; // parent post URL, set when this is a reply
  attachments?: { url: string; mediaType: string; alt?: string }[];
  language?: string;
}
```

These specialized hooks accept a verified `Create` activity containing exactly one `Note`. The note must be attributed to the activity actor. A mention must address the local Owncast actor. A reply must reference a post stored by the local Owncast instance.

Use `contentText` for analysis or to echo into chat. Use `content` only when you need the original formatting, and sanitize it before rendering.

### Raw inbound activity

`fediverse.activity` receives the verified inbound ActivityPub activity as its raw JSON object. Owncast sends it after the HTTP signature passes verification and the activity actor's origin matches the signing key owner's origin.

The catch-all runs in addition to a specialized handler. For example, an accepted quote can invoke both `onFediverseQuote` and `onFediverse`.

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

```js
module.exports = definePlugin({
  onFediverse(activity) {
    if (typeof activity.type === 'string') {
      console.log(`inbound activity: ${activity.type}`);
    }
  },
});
```

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

```python
@plugin.on_fediverse
def record_activity(activity):
    if isinstance(activity.type, str):
        print(f"inbound activity: {activity.type}")
```

</TabItem>
</Tabs>

Signature and actor-origin verification establish where the activity came from. They do not make its fields safe. Treat the raw object as untrusted plugin input. Check field types and required values, sanitize content before rendering it, and validate URLs before fetching them.

## Filter chain

Filters see chat messages before they're broadcast, with the ability to rewrite or drop them. They run sequentially in priority order (lowest first), and any one filter can short-circuit the chain: a `drop` ends it, while a `modify` passes the new payload to the next filter.

### Chat message filter: `chat.message.received` (filter)

A filter handler receives the same `ChatMessage` shape as the chat-message event and returns one of three results:

- **pass**: let the message through unchanged.
- **modify**: replace the message with a new payload, which flows to the next filter.
- **drop**: block the message with a reason. The chain stops here.

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

```js
module.exports = definePlugin({
  filterChatMessage(msg) {
    if (msg.body.includes('spam')) return filter.drop('spam');
    if (msg.body.includes('damn'))
      return filter.modify({ ...msg, body: msg.body.replace('damn', '****') });
    return filter.pass();
  },
});
```

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

```python
@plugin.filter_chat_message
def clean(msg):
    if "spam" in msg.body:
        return filter.drop("spam")
    if "damn" in msg.body:
        return filter.modify({**msg.raw, "body": msg.body.replace("damn", "****")})
    return filter.pass_()
```

</TabItem>
</Tabs>

Requires the `chat.filter` permission. Reading or rewriting every chat message is a meaningful side-effect, so the admin has to see the permission to grant it. The host rejects the load if a plugin defines the filter handler without declaring the permission.

### Filter priority (optional)

Each filter can declare a priority. Lower numbers run earlier (default `100`). Use this when your plugin's behavior depends on whether other filters have already run (for example, a profanity filter should usually run before a translator). See your SDK page for where to set it.

### Filter safety

- Errors are treated as a pass. A throwing filter never blocks chat. The chain continues with the original message.
- Filters are time-capped at 50 ms. A slow filter is cancelled and treated as pass.
- After 5 consecutive failures (errors or timeouts) the plugin is auto-disabled for the rest of the session, with a one-time log line. A successful filter call resets the counter, so transient flakiness doesn't accumulate. Restart the host to re-enable.

### Command tables

Declare a **command table** for aliases, cooldowns, moderator gating, parsed arguments, and automatic `!help` listings. Gating uses the sender identity (`user.scopes`, `user.id`), not a display-name guess.

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

```js
module.exports = definePlugin({
  commands: {
    uptime: { description: "How long we've been live", run: ctx => ctx.reply('a while!') },
  },
});
```

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

```python
plugin.commands({
    "uptime": {"description": "How long we've been live",
               "run": lambda ctx: ctx.reply("a while!")},
})
```

</TabItem>
</Tabs>

See [Chat commands](/docs/plugins/commands) for the full command-table reference (aliases, cooldowns, mod-only gating, `!help`).

## HTTP handler

### HTTP request

Fires for every request to `/plugins/<your-slug>/*` that didn't match a static file in `public/`. Returns a response object.

```ts
interface IncomingHttpRequest {
  method: string;
  path: string; // relative to /plugins/<your-slug>/
  query: Record<string, string>;
  headers: Record<string, string>;
  body: string;
  remoteAddr: string;
  authenticated: boolean; // came from any authenticated Owncast session, admin or viewer
  user?: { id: string; displayName: string; scopes: string[] }; // user-token requests only
}

interface OutgoingHttpResponse {
  status?: number; // default 200
  headers?: Record<string, string>;
  body?: string;
}
```

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

```js
module.exports = definePlugin({
  onHttpRequest(req) {
    if (req.path === '/status') return { status: 200, body: '{"ok":true}' };
    return { status: 404 };
  },
});
```

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

```python
@plugin.get("/status")
def status(req):
    return {"status": 200, "body": '{"ok":true}'}
```

</TabItem>
</Tabs>

Endpoints are public by default. Gate admin features on `req.authenticated`. Paths matching a key in `admin.pages` are auth-gated by the host before your handler runs, so for those routes you don't need to check.

Requires the `http.serve` permission. The JavaScript SDK exposes a single `onHttpRequest` catch-all. The Python SDK adds declarative per-path/per-method routes (`@plugin.get`, `@plugin.route`, …). See [Serving HTTP](/docs/plugins/http) for the full request model.

## Authentication

### Auth check hook {/* #auth-check */}

Only fires for the enabled [`auth.gate`](/docs/plugins/auth) plugin, and only on a viewer's `/` page load, never on the hot path (video segments, the API, chat). By the time it runs, the host has already verified the viewer's session cookie and resolved their identity. Your handler decides whether that session should continue. It's optional: omit it and a valid cookie is enough until it expires.

Return one of three verdicts via the `authCheck` helper:

- **ok**: keep the session as-is.
- **refresh**: keep it and re-issue the cookie, optionally with a new `ttl` in seconds (sliding expiry).
- **deny**: end the session and bounce the viewer back to the login screen. This is how you revoke access (a user deleted or banned upstream).

```ts
interface AuthCheckRequest {
  user: {
    id: string;
    displayName: string;
    scopes?: string[];
    isAuthenticated?: boolean;
  };
}

type AuthCheckResult =
  { action: 'ok' } | { action: 'refresh'; ttl?: number } | { action: 'deny'; reason?: string };
```

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

```js
const { definePlugin, owncast, authCheck } = require('@owncast/plugin-sdk');

module.exports = definePlugin({
  onAuthCheck(req) {
    if (owncast.kv.get(`banned:${req.user.id}`)) {
      return authCheck.deny('access revoked');
    }
    return authCheck.ok();
  },
});
```

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

```python
from owncast_plugin import plugin, owncast, auth_check

@plugin.on_auth_check
def check(req):
    if owncast.kv.get(f"banned:{req.user.id}"):
        return auth_check.deny("access revoked")
    return auth_check.ok()
```

</TabItem>
</Tabs>

Requires `auth.gate`, and it fails closed: if the handler errors or times out, the host treats that page load as a deny. Because the check runs only on `/`, a viewer whose access you revoke keeps any open tab working until they reload or the cookie expires. The session `ttl` is the hard backstop.

## Content handlers

These two handlers let a plugin generate tab or extra-page HTML at request time. Use them when content should be personalised per viewer or depend on live stream data. They're the dynamic counterpart to shipping a static HTML file via a tab value's `content` member or `manifest.extraPageContent.content`.

Both handlers receive a `ContentRequest`:

```ts
interface ContentRequest {
  slug: string; // manifest.tabs object key or manifest.extraPageContent.slug
  user?: User; // viewer's chat identity: present when authenticated, absent for anonymous viewers
}
```

Return the full HTML string for the content block. If you don't recognise the slug, return an empty string.

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

```js
module.exports = definePlugin({
  onTabContent(ctx) {
    if (ctx.slug === 'stats') {
      return `Live stats for ${ctx.user?.displayName ?? 'viewer'}`;
    }
    return '';
  },
  onPageContent(ctx) {
    return ctx.slug === 'banner' ? 'Welcome!' : '';
  },
});
```

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

```python
@plugin.on_tab_content("stats")
def stats(ctx):
    name = ctx.user.display_name if ctx.user else "viewer"
    return f"Live stats for {name}"

@plugin.on_page_content("banner")
def banner(ctx):
    return "Welcome!"
```

</TabItem>
</Tabs>

### Tab content

Called when a value in the `manifest.tabs` object has no static `content` file. The host passes that value's object key as `slug`, so a single plugin can serve multiple tabs. No permission required to subscribe. Whatever Owncast APIs you call from inside the handler require their usual permissions.

### Page content

Called when `manifest.extraPageContent` has no static `content` file. The host passes the slug from the manifest so the handler knows which content slot is being requested. Same permission rules as tab content.

See [Contributing UI](/docs/plugins/ui) for the manifest side.

## SSE connection events {/* #sse-events */}

When a browser opens or closes one of your plugin's `/plugins/<name>/_sse/<channel>` streams, Owncast fires `sse.connect` and `sse.disconnect`. Use them to track who is connected, for example to keep a live count for an overlay. See [Realtime updates](/docs/plugins/http#realtime-updates-server-sent-events) for the push side that sends data to those browsers.

### Connect / disconnect: `sse.connect`, `sse.disconnect`

```ts
interface SSEConnectionEvent {
  channel: string; // which _sse/<channel> stream the browser opened
  connectionId: number; // unique per connection for the life of the host process
  user?: User; // present only when the connection carried a chat identity
}
```

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

```js
module.exports = definePlugin({
  onSseConnect(e) {
    /* e.connectionId, e.channel */
  },
  onSseDisconnect(e) {
    /* same connectionId as the matching connect */
  },
});
```

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

```python
@plugin.on_sse_connect
def joined(e):
    ...  # e.connection_id, e.channel

@plugin.on_sse_disconnect
def left(e):
    ...
```

</TabItem>
</Tabs>

`connectionId` is stable for the life of a connection, so you can pair a disconnect with its matching connect and count the same viewer across several tabs. Both handlers require the `http.sse` permission.

## Tick

Owncast dispatches a `tick` event about once a second to any plugin that defines a tick handler. Use it for periodic work such as flushing counters or refreshing cached data. Defining the handler is what opts you in, so plugins that leave it out pay nothing.

### Periodic tick: `tick`

```ts
interface TickEvent {
  now: number; // host wall-clock time in unix milliseconds when the tick fired
}
```

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

```js
module.exports = definePlugin({
  onTick(e) {
    /* e.now */
  },
});
```

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

```python
@plugin.on_tick
def each_second(e):
    ...  # e.now
```

</TabItem>
</Tabs>

For one-off or custom-interval scheduling, use timers (`owncast.timer.setTimeout` and `setInterval`) instead of the tick. No permission required.

## Plugin-to-plugin events

Custom events are directed hooks for plugin-to-plugin composition. A plugin declares a local hook name, and the host registers it as `<plugin-slug>.<hook>`. The slug comes from the receiving plugin's manifest, so another plugin cannot claim the same fully qualified hook. Declaring a hook requires no permission. Emitting to one requires `events.emit`.

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

```js
// In the plugin whose slug is "announcer":
module.exports = definePlugin({
  on: {
    'announcement.broadcast'(payload) {
      /* react */
    },
  },
});

// Another plugin targets announcer's fully qualified hook:
owncast.events.emit('announcer.announcement.broadcast', { text: 'We are live' });
```

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

```python
# In the plugin whose slug is "announcer":
@plugin.on("announcement.broadcast")
def announce(payload):
    ...

# Another plugin targets announcer's fully qualified hook:
owncast.events.emit(
    "announcer.announcement.broadcast",
    {"text": "We are live"},
)
```

</TabItem>
</Tabs>

The receiving handler uses only its local hook name. Emitters use the full
`<recipient-slug>.<hook>` target. Built-in event names remain canonical and
cannot be claimed as custom hooks.

See [Owncast APIs](/docs/plugins/apis#plugin-to-plugin-events) for the emit API.

## Complete handler reference

Each row is a runtime event. The handler name follows your SDK's convention: camelCase methods (`onChatMessage`) in JavaScript, `@plugin.*` decorators (`@plugin.on_chat_message`) in Python.

| Event                    | Payload                            | Permission                                         |
| ------------------------ | ---------------------------------- | -------------------------------------------------- |
| `chat.message.received`  | `ChatMessage`                      | none                                               |
| `chat.user.joined`       | `User`                             | none                                               |
| `chat.user.parted`       | `User`                             | none                                               |
| `chat.user.renamed`      | `{ user, previousName }`           | none                                               |
| `chat.message.moderated` | `{ messageId, visible, moderator}` | none                                               |
| `stream.started`         | `{ startedAt, title, summary }`    | none                                               |
| `stream.stopped`         | `{ stoppedAt }`                    | none                                               |
| `stream.title.changed`   | `{ from, to }`                     | none                                               |
| `fediverse.follow`       | `{ actor }`                        | `fediverse.inbound`                                |
| `fediverse.like`         | `{ actor, target }`                | `fediverse.inbound`                                |
| `fediverse.repost`       | `{ actor, target }`                | `fediverse.inbound`                                |
| `fediverse.quote`        | `FediverseQuote`                   | `fediverse.inbound`                                |
| `fediverse.mention`      | `FediverseInboundPost`             | `fediverse.inbound`                                |
| `fediverse.reply`        | `FediverseInboundPost`             | `fediverse.inbound`                                |
| `fediverse.activity`     | Raw ActivityPub JSON object        | `fediverse.inbound`                                |
| chat message filter      | `ChatMessage`                      | `chat.filter`                                      |
| HTTP request             | `IncomingHttpRequest`              | `http.serve`                                       |
| auth check               | `AuthCheckRequest`                 | `auth.gate`                                        |
| `sse.connect`            | `SSEConnectionEvent`               | `http.sse`                                         |
| `sse.disconnect`         | `SSEConnectionEvent`               | `http.sse`                                         |
| `tick`                   | `{ now }`                          | none                                               |
| tab content              | `ContentRequest`                   | none. Whatever APIs the handler calls              |
| page content             | `ContentRequest`                   | none. Whatever APIs the handler calls              |
| custom hooks             | (per-hook)                         | none to declare, `events.emit` to target one       |

Subscribing to ungated built-in events and declaring custom hooks requires no permission. Gated hooks require the permission listed in the table. Calling Owncast APIs from inside a handler requires the API's permission too. See [Owncast APIs](/docs/plugins/apis) for the catalog of methods and what each one grants.

---

## Serving HTTP via Plugins

Plugins can serve their own URLs. Once you declare `http.serve` in your manifest, the URL space at `/plugins/<your-slug>/` is yours: static files from your `public/` directory go out verbatim, and anything else falls through to your request handler.

Code is shown for both SDKs. See [JavaScript](/docs/plugins/sdks/javascript) or [Python](/docs/plugins/sdks/python) for install and setup.

## Routing

Once `http.serve` is declared, the host routes every request under `/plugins/<your-slug>/` to your plugin:

1. Static files. Anything in your `public/` directory is served verbatim.
2. Dynamic handler. Anything else falls through to your plugin's request handler.

```mermaid
flowchart LR
    Req([Request to/plugins/my-plugin/X]) --> Admin{Path matches amanifest.admin.pages key?}
    Admin -->|yes, not authenticated| Auth401([401 Unauthorized])
    Admin -->|yes, authenticated| Static
    Admin -->|no| Static
    Static{Does public/Xexist?} -->|yes| Serve([Serve the file])
    Static -->|no| Handler[Call your request handler]
    Handler --> Resp([Plugin returns a response])
```

A request's path is relative to your plugin's namespace: a request to `/plugins/my-plugin/api/messages` reaches your handler as `/api/messages` (the query string is excluded). The handler reads query parameters and the request body from the request, and returns a response with a status, optional headers, and an optional body.

There are two routing styles. In **JavaScript** you write a single `onHttpRequest(req)` handler and branch on `req.method` / `req.path`. In **Python** you declare per-method routes with decorators. A request whose path matches a route but not its method gets an automatic **405**, and an unmatched path falls through to the bare catch-all, else **404**.

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

```js
const { definePlugin } = require('@owncast/plugin-sdk');

module.exports = definePlugin({
  onHttpRequest(req) {
    // req: { method, path, headers, query, body, user? }
    if (req.method === 'GET' && req.path === '/api/messages') {
      return {
        status: 200,
        headers: { 'Content-Type': 'application/json' },
        body: '[]',
      };
    }
    if (req.method === 'POST' && req.path === '/api/messages') {
      const data = JSON.parse(req.body || '{}');
      return { status: 201 };
    }
    return { status: 404 };
  },
});
```

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

```python
from owncast_plugin import plugin

@plugin.get("/api/messages")
def list_messages(req):
    return {"status": 200, "headers": {"Content-Type": "application/json"}, "body": "[]"}

@plugin.post("/api/messages")
def add_message(req):
    body = req.body          # raw request body
    return {"status": 201}

@plugin.on_http_request      # bare: catch-all fallback (any method, any path)
def fallback(req):
    return {"status": 404}
```

Routes are exact and plugin-relative. Read query params from `req.query`. A handler returns a `dict` (`{status, body, headers}`), a `str` (→ 200), or `None` (→ 204). `@plugin.route(path, methods=[...])` covers multiple methods on one path.

</TabItem>
</Tabs>

The `manifest.admin.pages` key match at the top is covered in [UI: Admin pages](/docs/plugins/ui#admin-pages). From the perspective of HTTP serving, it is a 401-before-your-handler-runs filter applied to paths matching one of the object's keys.

## Static files

The `public/` directory holds files served at `/plugins/<your-slug>/<path>`. A separate `assets/` directory holds files the host reads internally for manifest fields that inline content (`styles`, `scripts`, `extraPageContent`). Those are not reachable through the plugin's URL space.

```text
my-plugin/
└── public/
    ├── index.html        → /plugins/my-plugin/index.html (and /plugins/my-plugin/)
    ├── style.css         → /plugins/my-plugin/style.css
    └── img/
        └── logo.png      → /plugins/my-plugin/img/logo.png
```

A request to `/plugins/my-plugin/` (no trailing path) serves `public/index.html` automatically.

## Request and response limits

- Request bodies are capped at 1 MB.
- Response bodies are capped at 10 MB.
- Path traversal (`..`) in URLs is blocked at the host level. You'll never see it in your handler's path.
- Response headers are filtered through an allowlist. You can set `Content-Type`, `Content-Encoding`, `Content-Language`, `Cache-Control`, `Set-Cookie`, `Location`, `ETag`, `Last-Modified`, `Vary`, `Link`, and CORS (`Access-Control-*`) headers. Owncast-owned headers (`Server`, `Content-Security-Policy`, `Strict-Transport-Security`, `X-Frame-Options`) are blocked.
- Cookies you set apply to your plugin's URL space by default (`/plugins/<your-slug>/`). If you want a cookie to be sent on requests outside that path, set `Path=...` explicitly. Otherwise the browser scopes it to your namespace and won't leak it into other plugins or into Owncast's own paths.
- Each request is time-capped at 5 seconds before the host returns a `504` and discards your response.

## Public vs. authenticated

Endpoints are public by default. To make something admin-only, either check whether the request is authenticated inside your handler and return `401` when it isn't, or add its path glob as a key in `manifest.admin.pages` and let the host gate it for you (see [UI: Admin pages](/docs/plugins/ui#admin-pages)).

For requests made by a chat user with a valid user-token, the request carries the user's identity (`id`, display name, and `scopes`). Useful for per-user dashboards or moderator-only tools:

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

```js
module.exports = definePlugin({
  onHttpRequest(req) {
    if (!req.user) return { status: 401 }; // not signed in
    if (!req.user.scopes?.includes('MODERATOR')) return { status: 403 };
    return { status: 200, body: `hello ${req.user.displayName}` };
  },
});
```

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

```python
@plugin.get("/my-data")
def my_data(req):
    if not req.user:                                  # not signed in
        return {"status": 401}
    if "MODERATOR" not in (req.user.scopes or []):
        return {"status": 403}
    return {"status": 200, "body": f"hello {req.user.display_name}"}
```

</TabItem>
</Tabs>

For paths matching a key in `manifest.admin.pages`, the host returns `401` before your handler runs, so you don't have to check at all.

## Realtime updates (Server-Sent Events)

For pushing live updates to a browser (an overlay that reacts to chat, a dashboard that ticks viewer counts, an alert widget) declare `http.sse` and use `owncast.sse.send`.

You do not open or hold the connection yourself. Your request handler can't stream: each call is a single buffered request/response. The host owns the long-lived connection and exposes a ready-made endpoint at `/plugins/<your-slug>/_sse/<channel>`. Your plugin pushes. The host fans each message out to every connected browser.

```mermaid
sequenceDiagram
    participant Browser
    participant Host as Owncast host/plugins/my-plugin/_sse/overlay
    participant Plugin as Your plugin

    Browser->>Host: new EventSource('/plugins/my-plugin/_sse/overlay')
    Host-->>Browser: connection opens, kept alive

    Note over Plugin: A chat message arrives
    Plugin->>Host: owncast.sse.send('overlay', 'chat', payload)
    Host-->>Browser: event: chatdata: { ... }

    Note over Plugin: Another event
    Plugin->>Host: owncast.sse.send('overlay', 'chat', payload)
    Host-->>Browser: event: chatdata: { ... }
```

### Plugin side

Push from any handler, for example, from your chat handler, by calling `owncast.sse.send(channel, event, data)`:

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

```js
const { definePlugin, owncast } = require('@owncast/plugin-sdk');

module.exports = definePlugin({
  onChatMessage(msg) {
    owncast.sse.send('overlay', 'chat', {
      from: msg.user?.displayName,
      body: msg.body,
    });
  },
});
```

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

```python
from owncast_plugin import plugin, owncast

@plugin.on_chat_message
def push(msg):
    owncast.sse.send("overlay", "chat", {
        "from": msg.user.display_name if msg.user else None,
        "body": msg.body,
    })
```

</TabItem>
</Tabs>

- `channel`: which stream to push to. Browsers subscribe per channel, so you can run several independent streams (`"overlay"`, `"admin-stats"`) from one plugin. Use `""` for a single default channel.
- `event`: the event name the browser listens for (`addEventListener("chat", ...)`). Pass `""` for the browser's default `message` event.
- `data`: the payload. Strings are sent as-is. Anything else is JSON-encoded for you.

Sends are fire-and-forget. The call returns immediately and never blocks, even if no one is connected or a client is slow. Slow clients drop frames rather than stall your plugin. There are also SSE-connection lifecycle events (a viewer's stream opening and closing) you can subscribe to: see the [handlers reference](/docs/plugins/events#sse-events).

### Browser side

Standard `EventSource` API on the viewer page. No library. This runs in the browser, so it's always JavaScript whatever language your plugin is written in:

```html
<!-- public/index.html, served at /plugins/my-plugin/ -->
<script>
  const events = new EventSource('/plugins/my-plugin/_sse/overlay');
  events.addEventListener('chat', e => {
    const { from, body } = JSON.parse(e.data);
    document.getElementById('feed').textContent = `${from}: ${body}`;
  });
</script>
```

### Notes

- Up to 64 simultaneous connections per plugin. Over that the endpoint returns `503`. `EventSource` reconnects automatically.
- If the channel matches a key in `admin.pages`, it's auth-gated like any admin route. Handy for an admin-only stats stream.
- The endpoint is host-owned. Your request handler never sees `/_sse/...` requests, and you can't serve your own route there.

## Putting it together: a complete overlay plugin

The manifest declares the two permissions the overlay needs:

```json
{
  "api": "1",
  "name": "Chat Overlay",
  "slug": "overlay",
  "version": "0.1.0",
  "permissions": ["http.serve", "http.sse"]
}
```

The plugin subscribes to chat messages and pushes each one to the `overlay` SSE channel:

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

```js
// src/plugin.js
const { definePlugin, owncast } = require('@owncast/plugin-sdk');

module.exports = definePlugin({
  onChatMessage(msg) {
    owncast.sse.send('overlay', 'chat', {
      from: msg.user?.displayName,
      body: msg.body,
    });
  },
});
```

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

```python
# src/plugin.py
from owncast_plugin import plugin, owncast

@plugin.on_chat_message
def push(msg):
    owncast.sse.send("overlay", "chat", {
        "from": msg.user.display_name if msg.user else None,
        "body": msg.body,
    })
```

</TabItem>
</Tabs>

The viewer page is the same `EventSource` snippet shown above, pointed at the relative `./_sse/overlay` endpoint:

```html
<!-- public/index.html -->
<!doctype html>
<body>
  
  <script>
    const events = new EventSource('./_sse/overlay');
    events.addEventListener('chat', e => {
      const { from, body } = JSON.parse(e.data);
      document.getElementById('feed').textContent = `${from}: ${body}`;
    });
  </script>
</body>
```

Build, package, install. Open `/plugins/overlay/` in OBS as a browser source.

---

## Extend Owncast with plugins

Owncast can be extended with **plugins**: small programs that the server loads at runtime to react to chat messages, stream events, fediverse activity, and HTTP requests. They run inside a sandbox, so a plugin can crash without taking the server down, and the host enforces a clear permission model so an admin always knows what a plugin can touch.

:::new[Plugins require Owncast v0.3.0]
Plugins are brand-new functionality, introduced in Owncast 0.3.0, and the API is still evolving. If you hit a bug or have a suggestion, please [open an issue](https://github.com/owncast/plugin-sdk/issues) or [chat live with the community](/chat?tab=community).
:::

You can write a plugin with the JavaScript SDK, the Python SDK, or as a native WebAssembly module. The two SDKs are the recommended paths for most plugins. Native WebAssembly is an advanced option for compiled languages and direct access to the plugin wire protocol.

## What you can build

- Chat bots that reply to keywords or commands, post reminders, run polls, or moderate spam.
- Filters that rewrite or drop chat messages before they reach viewers.
- Overlays rendered on top of your stream, talking to your plugin's HTTP endpoints.
- Integrations that bridge Owncast to Discord, the fediverse, browser push, or any HTTPS service.
- Admin tools that add a tab to the Owncast admin UI for plugin-specific settings.
- Action buttons that appear under your stream, launching widgets, donation pages, or anything else you serve.

Every example plugin in the SDK is a complete starting point you can copy.

## Choose an authoring path

All three paths produce the same `.ocpkg` format and use the same manifest, permissions, events, and Owncast APIs.

- **[JavaScript](/docs/plugins/sdks/javascript)** with [`@owncast/plugin-sdk`](https://www.npmjs.com/package/@owncast/plugin-sdk). Scaffold with `npx create-owncast-plugin`, write `definePlugin({ ... })`, and build with `npm run package`.
- **[Python](/docs/plugins/sdks/python)** with [`owncast-plugin-py`](https://pypi.org/project/owncast-plugin-py/). Scaffold with `uvx owncast-plugin-py new`, write decorated functions, and build with `owncast-plugin-py package`.
- **[Native WebAssembly](/docs/plugins/sdks/native-wasm)** with Rust, TinyGo, AssemblyScript, Zig, or another compiled language. Implement the wire protocol directly and package the compiled module as `plugin.wasm`.

The same echo bot in each SDK:

```js
// JavaScript
const { definePlugin, owncast } = require('@owncast/plugin-sdk');

module.exports = definePlugin({
  onChatMessage(msg) {
    owncast.chat.send(`echo: ${msg.body}`);
  },
});
```

```python
# Python
from owncast_plugin import plugin, owncast

@plugin.on_chat_message
def echo(msg):
    owncast.chat.send(f"echo: {msg.body}")
```

## How it fits together

A plugin is a single `.ocpkg` file containing your plugin's manifest, the compiled code, and any static assets. An admin drops the file into Owncast's `data/plugins/` directory and enables it from the **Plugins** page in the admin.

```mermaid
flowchart LR
    subgraph Dev[Development]
        direction TB
        Source["your plugin sourceplugin.manifest.jsonpublic/assets/"]
        Build["build and package"]
        Pkg["my-plugin.ocpkg"]
        Source --> Build --> Pkg
    end

    subgraph Server[Owncast server]
        direction TB
        Dir["Plugin installeddata/plugins/my-plugin.ocpkg"]
        Admin["Admin enablesin Plugins UI"]
        Running["Plugin runninginside Owncast"]
        Dir --> Admin --> Running
    end

    Pkg -->|admin uploads from Plugins page| Dir
```

Once enabled, the plugin runs inside the Owncast process. Handlers you defined fire when matching events happen. APIs you call (sending chat, reading config, fetching URLs) go through the host, which checks the permissions you declared in your manifest.

Each enabled plugin uses more server memory. JavaScript and Python share one runtime per language, so the first plugin in either language has a larger one-time cost. A native WebAssembly plugin loads its own compiled module instead of a shared language runtime.

## What a plugin can do

1. Subscribe to events. Chat messages, stream start and stop, fediverse follows, new chat user joins. Define a handler method and the SDK derives the subscription.
2. Filter chat. See every chat message before it's broadcast, modify it, or drop it.
3. Call Owncast APIs. `owncast.chat.send(text)`, `owncast.kv.get(key)`, `owncast.http.fetch(url)`, and dozens more, most gated by a declared permission.
4. Serve HTTP. Every plugin can own the URL space at `/plugins/<your-slug>/...` for both static assets and dynamic handlers.
5. Add UI. Declare admin pages, action buttons, plugin stylesheets, plugin scripts, or an extra-content HTML block in your manifest and Owncast inlines them into its own chrome.
6. Gate access. A plugin can be the site's authentication provider. Make viewers sign in (OAuth, a password, anything over HTTP) before they can reach the page, the video, chat, or the API.

## What a plugin can't do

By design:

- No direct access to the host filesystem, network, or processes. The sandbox enforces this. Plugins do what the host APIs expose, and only with declared permissions.
- No identity impersonation. Each plugin gets one chat identity (the bot Owncast provisions on install), and outbound fediverse posts come from the streamer's own account.
- No cross-plugin reads. Each plugin's key-value store is namespaced.
- No indefinite chat blocking. Filter calls are time-capped at 50 ms, and a plugin that throws repeatedly is auto-disabled.

This is why an admin can install a third-party plugin without auditing every line of code. The trust boundary is the manifest's permission list.

## Where to go next

- [Quickstart](/docs/plugins/quickstart). Scaffold a new plugin, build it, install it.
- [JavaScript](/docs/plugins/sdks/javascript), [Python](/docs/plugins/sdks/python), and [Native WebAssembly](/docs/plugins/sdks/native-wasm). Choose a language and build path.
- [Manifest reference](/docs/plugins/manifest). Every field your `plugin.manifest.json` can contain.
- [Chat plugins](/docs/plugins/chat). Build bots, moderation tools, and chat filters.
- [Events](/docs/plugins/events). Every event your plugin can subscribe to, with payload shapes.
- [Owncast APIs](/docs/plugins/apis). Every `owncast.*` method, what it does, and the permission it needs.
- [Permissions](/docs/plugins/permissions). The full list and how the security model works.
- [Serving HTTP](/docs/plugins/http). Serve URLs from your plugin and push realtime events to browsers.
- [Contributing UI](/docs/plugins/ui). Register admin pages and contribute action buttons under the stream.
- [Testing](/docs/plugins/testing). Scenario tests that drive your plugin through the real runtime.
- [Packaging & publishing](/docs/plugins/packaging). Bundle the `.ocpkg`, install it, and list it in the directory.

## Source

- SDK source: [github.com/owncast/plugin-sdk](https://github.com/owncast/plugin-sdk)
- Example plugins: [JavaScript](https://github.com/owncast/plugin-sdk/tree/main/examples/js) · [Python](https://github.com/owncast/plugin-sdk/tree/main/examples/python)

---

## Plugin Manifest reference

Every plugin has a `plugin.manifest.json` file at its root. This is the source of truth for the plugin's identity, the permissions it needs, the network destinations it's allowed to call, the admin pages it contributes, and the action buttons it adds to the viewer UI.

:::new[Plugin manifests require Owncast v0.3.0]
Plugins require Owncast 0.3.0 or later.
:::

The manifest is what an admin reviews before installing the plugin. The host parses it at load time and enforces every declaration. Nothing in the compiled plugin can grant a capability the manifest didn't ask for.

:::info[Available in every SDK]
The manifest is plain JSON that describes the plugin to the host, independent of the language you wrote the code in. For the language-specific details, see the **[JavaScript](/docs/plugins/sdks/javascript)** or **[Python](/docs/plugins/sdks/python)** SDK reference.
:::

## Minimum manifest

```json
{
  "api": "1",
  "name": "My Plugin",
  "version": "0.1.0",
  "description": "Short description for admins",
  "permissions": []
}
```

`api`, `name`, and `version` are required. Everything else is optional and only needed when you use the corresponding feature.

## Top-level fields

| Field              | Type     | Required | Description                                                                                                                                                 |
| ------------------ | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api`              | string   | yes      | Manifest schema version. Currently `"1"`.                                                                                                                   |
| `name`             | string   | yes      | Human-readable display name shown in admin lists and registry cards. Example: `"Awesome Echo Bot"`.                                                         |
| `slug`             | string   | no       | Canonical identifier (URL prefix, config namespace, filename). Auto-derived from `name` if omitted. See below.                                              |
| `version`          | string   | yes      | Your plugin's version. SemVer recommended. Informational metadata for admins and the registry: the host doesn't gate loading on it.                         |
| `description`      | string   | no       | One-sentence summary the admin sees in the plugin list and during install.                                                                                  |
| `category`         | string   | no       | Registry browse category. See [`category`](#category-registry-browse-category).                                                                             |
| `permissions`      | string[] | no       | List of capabilities your plugin needs. See [Permissions](/docs/plugins/permissions).                                                                       |
| `config`           | object   | no       | Admin-configurable settings your plugin reads at runtime. See [Configuration](/docs/plugins/configuration).                                                 |
| `bot`              | object   | no       | Chat-bot configuration. See [`bot`](#bot-chat-bot-identity).                                                                                                |
| `network`          | object   | no       | Outbound-HTTP allowlist, required when `network.fetch` is granted. See below.                                                                               |
| `actions`          | object[] | no       | Action buttons to add to the viewer UI. See [UI: Action buttons](/docs/plugins/ui#action-buttons).                                                          |
| `admin`            | object   | no       | Admin pages to add to the Owncast admin UI. See [UI: Admin pages](/docs/plugins/ui#admin-pages).                                                            |
| `styles`           | string[] | no       | CSS files inlined into the viewer page. See [`styles`](#styles-css-injection).                                                                              |
| `scripts`          | string[] | no       | JavaScript files inlined into the viewer page. See [`scripts`](#scripts-javascript-injection).                                                              |
| `extraPageContent` | object   | no       | An object declaring a slug and an optional HTML file prepended to the viewer's extra-content block. See [`extraPageContent`](#extrapagecontent-html-block). |
| `tabs`             | object   | no       | Viewer-page tabs keyed by stable slug. See [`tabs`](#tabs-viewer-page-tabs).                                                                                |

### `name` and `slug`

`name` is the human-readable display name. It can contain any characters, including spaces and punctuation, and is what admins see in the plugin list, what shows up on registry browse cards, and the default chat-bot identity.

`slug` is the canonical identifier. It controls:

- The plugin's URL prefix: `/plugins/<slug>/...`
- The config (key-value store) namespace
- The filename of the built artifact (`<slug>.ocpkg`)
- The primary key in the plugin registry

Slugs are lowercase letters, digits, and hyphens, starting with a letter, up to 64 characters. The SDK derives one from `name` automatically when `slug` is omitted: spaces and punctuation collapse into single hyphens, letters lowercase. `"Awesome Echo Bot"` becomes `awesome-echo-bot`. Pin `slug` explicitly when the auto-derivation isn't what you want, or when your display name uses characters outside ASCII (`"Café Helper"` would otherwise yield `caf-helper`).

Avoid changing the slug after release: the rename will look like a different plugin to admins, with a fresh config store. Changing `name` (display only) is safe. It doesn't change identity.

### `category`: registry browse category

An optional label that places your plugin in a browse category on the registry and in the admin UI. The canonical values are `chat-bots`, `chat-filters`, `moderation`, `authentication`, `themes`, `overlays`, `notifications`, `integrations`, `video`, `analytics`, `games`, `admin-utilities`, `examples`, and `other`.

The SDK's packaging CLI warns when `category` isn't one of these, but nothing rejects it: the host and registry tolerate unknown categories, they just won't match any browse filter.

### `bot`: chat-bot identity

Plugins that post to chat (using `owncast.chat.send`) appear under a chat-bot user. By default the bot shows up under the plugin's display `name`. Override that with `bot.displayName`:

```json
{
  "name": "Stream Sidekick",
  "bot": {
    "displayName": "Sidekick"
  }
}
```

In chat, the bot posts as "Sidekick" instead of "Stream Sidekick". The first time the plugin loads, Owncast provisions a persistent chat user keyed on the plugin's `slug` (so the bot identity survives reinstalls and display-name changes).

`bot.displayName` is only relevant for plugins that have the `chat.send` permission. It's ignored otherwise.

### `config`: admin-configurable settings

Declare typed settings here and Owncast renders an editable form for them in the admin, which your plugin reads at runtime with `owncast.config.get`. Each entry has a `type` (`string`, `number`, or `boolean`), a `default`, and a `description`:

```json
{
  "config": {
    "greeting": { "type": "string", "default": "welcome!", "description": "First-join message" },
    "cooldownMs": { "type": "number", "default": 2000, "description": "Per-user command cooldown" },
    "modOnly": { "type": "boolean", "default": false, "description": "Restrict to moderators" }
  }
}
```

Config keys starting with `__` are reserved: the host uses that prefix to inject per-instance state into the plugin runtime, and a manifest declaring one is rejected at load.

Full coverage, including how the form renders, credential masking, validation, and where overrides are stored, in [Configuration](/docs/plugins/configuration).

## `permissions`

Each entry unlocks a slice of host APIs. The host rejects calls to a method whose permission you didn't declare.

```json
{
  "permissions": ["chat.send", "storage.kv", "network.fetch"]
}
```

See [the permissions reference](/docs/plugins/permissions) for the full list of identifiers and what each one grants.

## `network`: outbound HTTP allowlist

`network.fetch` is gated by an explicit allowlist of hostnames. If you declare `network.fetch` in `permissions`, you also need a `network.allowedHosts` field listing the hosts you'll call:

```json
{
  "permissions": ["network.fetch"],
  "network": {
    "allowedHosts": ["api.discord.com", "*.weather.com"]
  }
}
```

Entries are hostname globs. Bare names like `api.discord.com` match exactly. `*` is a wildcard segment, so `*.weather.com` matches `api.weather.com` and `data.weather.com` but not `weather.com` itself or `evil.com`.

The wildcard `"*"` matches any host, but you must write it explicitly:

```json
{
  "network": { "allowedHosts": ["*"] }
}
```

This is intentional. Admins reviewing the manifest see the scope they're granting. Most plugins should list the specific hosts they call instead.

The host rejects the load if `network.fetch` is granted without an `allowedHosts` entry.

## `actions`: action buttons

Action buttons are clickable entries Owncast surfaces under the stream. While your plugin is enabled, the host merges its entries into the list Owncast already shows.

```json
{
  "permissions": ["ui.modify", "http.serve"],
  "actions": [
    {
      "title": "Chat Overlay",
      "description": "Open the live chat overlay",
      "url": "/",
      "icon": "/star.png",
      "color": "#3b82f6"
    },
    {
      "title": "Issue tracker",
      "url": "https://github.com/example/my-plugin/issues",
      "openExternally": true
    },
    {
      "title": "About this stream",
      "html": "Live every weekday at 8pm UTC."
    }
  ]
}
```

Each entry:

| Field            | Type    | Notes                                                                           |
| ---------------- | ------- | ------------------------------------------------------------------------------- |
| `title`          | string  | Required. The button label.                                                     |
| `url`            | string  | Either an absolute `https://...` URL or a path. Mutually exclusive with `html`. |
| `html`           | string  | Raw HTML rendered in an inline modal. Mutually exclusive with `url`.            |
| `icon`           | string  | Optional image URL shown on the button. Same path rules as `url`.               |
| `color`          | string  | Optional hex color for the button background.                                   |
| `description`    | string  | Optional. Shown in the modal that opens for URL-based actions.                  |
| `openExternally` | boolean | If `true`, the URL opens in a new tab instead of an inline modal.               |

Rules the host enforces at load time:

- `ui.modify` permission is required. Without it, the manifest is rejected.
- Exactly one of `url` or `html` per entry.
- Relative URLs (and icons) starting with `/` auto-prefix to your plugin's namespace. `"/"` becomes `/plugins/my-plugin/`. `"/star.png"` becomes `/plugins/my-plugin/star.png`. Saves you from hard-coding your plugin name.
- URLs (and icons) that resolve into your namespace require `http.serve`, since you're the one serving them.
- URLs (and icons) pointing at another plugin's namespace are rejected. Catches typos and prevents one plugin from advertising another's UI.

Full coverage in [UI: Action buttons](/docs/plugins/ui#action-buttons).

## `admin`: admin pages

Plugins can register pages that appear in the Owncast admin UI under **Plugins**. The `pages` object is keyed by plugin-relative path glob:

```json
{
  "permissions": ["http.serve"],
  "admin": {
    "pages": {
      "/admin": { "title": "Settings", "icon": "gear" }
    }
  }
}
```

Each entry has:

| Part       | Type   | Notes                                                                                |
| ---------- | ------ | ------------------------------------------------------------------------------------ |
| object key | string | Required path glob under the plugin's namespace, such as `"/admin"` or `"/admin/*"`. |
| `title`    | string | Required. The tab label shown in the admin UI.                                       |
| `icon`     | string | Optional. A short semantic name (`gear`, `wrench`, `user`, and so on).               |

The host derives each page path from its object key. A key of `"/admin"` maps to `/plugins/<your-slug>/admin`. Requests matching any key are auth-gated by the host, so unauthenticated requests get a `401` before your plugin code runs.

JSON object order is not significant. Owncast displays admin pages in lexicographic path order. `pages` must be an object. Do not add a `path` member to a page value. The host rejects arrays and page values containing the legacy `path` member.

Full coverage in [UI: Admin pages](/docs/plugins/ui#admin-pages).

## `styles`: CSS injection

A list of CSS files the plugin contributes to the viewer page. Each file's contents are inlined into the same `<style>` block Owncast already uses for the admin's custom CSS, so plugins can theme the page without each contribution needing its own `<link>` tag.

```json
{
  "permissions": ["ui.modify"],
  "styles": ["theme.css", "overrides.css"]
}
```

Path rules match action-button URLs:

- Bare paths like `"theme.css"` auto-prefix to your plugin's namespace.
- Single-slash paths like `"/theme.css"` get the same treatment.
- Fully qualified `/plugins/<your-slug>/...` paths pass through.
- Paths in another plugin's namespace are rejected.
- `http://` and `https://` URLs are rejected. Bundle external assets (fonts, images) and reference them with `@font-face` or `url(...)` from inside your CSS, so an admin reviewing the manifest sees every file that will land in their page.
- Each entry must end in `.css`.

Requires `ui.modify` only (the plugin paints inside Owncast's chrome). `http.serve` is not needed: each file's bytes are read from `assets/` and inlined into `customStyles` on `/api/config`, not served at a URL. The host emits a `/* plugin: <your-slug> ... */` comment in front of each contribution so a reader can attribute a rule back to whichever plugin shipped it.

For CSS that depends on plugin state, an `onPageStyles` handler returns it at request time, with no manifest field. Its output appends to `customStyles` after these static files.

Full coverage in [UI: Viewer stylesheets](/docs/plugins/ui#viewer-stylesheets).

## `scripts`: JavaScript injection

A list of JavaScript files the plugin contributes to the viewer page. Each file's contents are appended to the same response the admin's custom JavaScript already comes from (`/customjavascript`), so plugins can extend the page without each contribution needing its own `<script>` tag.

```json
{
  "permissions": ["ui.modify"],
  "scripts": ["client.js"]
}
```

Path rules and required permissions match `styles`, applied to `.js` files (only `ui.modify` is needed, and the host reads from `assets/` and inlines into `/customjavascript`). Wrap your script in an IIFE so top-level declarations don't collide with the admin's JavaScript or other plugins. The host emits a `// plugin: <your-slug> ...` comment in front of each contribution and wraps every contribution in a try/catch so one plugin's runtime error can't break the others.

For JavaScript that depends on plugin state, an `onPageScripts` handler returns it at request time, with no manifest field. Its output appends to `/customjavascript` after these static files.

Full coverage in [UI: Viewer scripts](/docs/plugins/ui#viewer-scripts).

## `extraPageContent`: HTML block

An object that contributes an HTML block to the viewer's extra-content area, prepended above the admin's prose on `/api/config`.

```json
{
  "permissions": ["ui.modify"],
  "extraPageContent": { "slug": "banner", "content": "content.html" }
}
```

| Field     | Type   | Notes                                                                                                                                                                   |
| --------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `slug`    | string | Required only when `content` is omitted (the host passes it to `onPageContent`). Optional otherwise. Lowercase letters, digits, and hyphens, starting with a letter.    |
| `content` | string | Optional. Relative path to a static HTML file in `assets/`. When present, that file's bytes are inlined directly. When omitted, the host calls `onPageContent` instead. |

**Static** (with `content`): the host reads the file at request time and inlines the bytes. Same path rules as `styles` and `scripts`, applied to a single `.html` entry. Plugin HTML bypasses the markdown processor so tags and attributes pass through as written.

**Dynamic** (without `content`): implement `onPageContent({ slug, user? })` in your plugin to return HTML at request time. Use this when the content should vary per viewer or draw on live data (for example, personalised greetings or current stream stats). `user` is the viewer's chat identity, present when authenticated.

Requires `ui.modify`. `http.serve` is not required because the HTML is inlined into the config response, not served as a URL. Each contribution is wrapped with an `<!-- plugin: <your-slug> ... -->` comment so a reader can attribute the markup back.

Full coverage in [UI: Extra page content](/docs/plugins/ui#extra-page-content).

## `tabs`: viewer-page tabs

The `tabs` object contributes tabs to the viewer page's tab row next to the built-in **About** and **Followers** tabs. Each object key is the tab's stable slug. Every value requires `title`, and `content` is optional.

```json
{
  "permissions": ["ui.modify"],
  "tabs": {
    "music": { "title": "Music", "content": "music.html" },
    "schedule": { "title": "Schedule", "content": "schedule.html" }
  }
}
```

Each entry has:

| Part       | Notes                                                                                                                                                                                                                                                |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| object key | Required stable slug. Lowercase letters, digits, and hyphens, starting with a letter. The host passes this key to `onTabContent` when `content` is omitted.                                                                                          |
| `title`    | Required. The label shown on the tab. Must be unique within the plugin's tabs.                                                                                                                                                                       |
| `content`  | Optional. Relative path to an HTML file under `assets/`. Same path rules as `extraPageContent` (auto-prefix to your namespace, cross-plugin paths and `http(s)://` URLs rejected, must end in `.html`). When omitted, the host calls `onTabContent`. |

Within each plugin, Owncast displays tabs in lexicographic slug order. JSON object order is not significant. Ordering between tabs from different plugins is unspecified. `tabs` must be an object. Do not add a `slug` member to a tab value. The host rejects arrays and tab values containing the legacy `slug` member.

Requires `ui.modify`. `http.serve` is not required: each static tab's HTML is read from `assets/` and inlined into the `pluginTabs[]` array on `/api/config`. For a dynamic tab, the host passes the object key to `onTabContent` as `slug` and inlines the returned HTML.

Full coverage in [UI: Viewer-page tabs](/docs/plugins/ui#viewer-page-tabs).

## Manifest-to-runtime contract

When your plugin loads, the host parses the manifest and asks the runtime to register itself. It compares the two and rejects the load when:

- the slugs don't match (`slug` is the canonical identity on both sides)
- the runtime uses a permission that wasn't declared in the manifest

`version` is intentionally not compared. It's informational metadata the host gates nothing on, and the SDK bakes it into the registration from the same manifest at build time anyway.

You don't write the registration yourself: the SDK generates it from the handlers you define (see your [SDK reference](/docs/plugins) for how handlers are declared in your language). Knowing this contract exists is useful when debugging. A "permission requested at runtime not declared in manifest" error means you added a handler that needs a permission you forgot to list.

## Complete example

A non-trivial manifest exercising most features:

```json
{
  "api": "1",
  "name": "Stream Sidekick",
  "slug": "stream-sidekick",
  "version": "0.2.0",
  "description": "Posts to Discord on stream start, shows an overlay, and adds a Donate button.",
  "permissions": [
    "chat.send",
    "chat.filter",
    "storage.kv",
    "http.serve",
    "http.sse",
    "network.fetch",
    "notifications.send",
    "ui.modify"
  ],
  "bot": {
    "displayName": "Sidekick"
  },
  "network": {
    "allowedHosts": ["api.discord.com", "*.example.com"]
  },
  "actions": [
    {
      "title": "Donate",
      "url": "https://example.com/donate",
      "openExternally": true
    }
  ],
  "admin": {
    "pages": {
      "/admin": { "title": "Sidekick settings", "icon": "gear" }
    }
  },
  "styles": ["sidekick.css"],
  "scripts": ["sidekick.js"],
  "extraPageContent": { "slug": "intro", "content": "intro.html" },
  "tabs": {
    "schedule": { "title": "Schedule", "content": "schedule.html" }
  }
}
```

---

## Packaging & publishing plugins

A plugin's distribution format is the `.ocpkg` file: a single bundle containing your `plugin.manifest.json`, your plugin code, your `public/` and `assets/` directories, and optionally an icon and an instructions document. That one file is everything a server admin needs to install your plugin.

## Building the package

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

```sh
npm run package
```

`npm run package` only rebuilds when the bundle is missing. After changing source, run `npm run build` first so the package doesn't ship stale code.

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

```sh
owncast-plugin-py package my-plugin
```

</TabItem>
<TabItem value="wasm" label="Native WebAssembly">

Use your language toolchain to compile the module, then package it as a ZIP with
the canonical `plugin.wasm` filename. The
[Native WebAssembly guide](/docs/plugins/sdks/native-wasm) includes build
commands for Rust, TinyGo, and AssemblyScript.

</TabItem>
</Tabs>

The resulting `<your-slug>.ocpkg` contains the manifest and runnable code. It can also include the plugin's `public/` and `assets/` directories.

The JavaScript and Python packagers run the built plugin through `owncast-plugin-test --load-only` before writing the archive. This uses the same install-time load path as a real server, covering `register()`, manifest and runtime agreement, and permission-gated subscriptions. Native WebAssembly authors run `owncast-plugin-test` directly before packaging. See [Native WebAssembly: Test before installing](/docs/plugins/sdks/native-wasm#test-before-installing).

The file is self-contained. Share it however you like:

- Attach it to a GitHub release
- Host it on your own server
- Hand it to an admin over chat or email

## Plugin icon

Drop an `icon.png` at the root of your project (alongside `plugin.manifest.json`) and the packager bundles it into the `.ocpkg` automatically. The admin UI fetches it from `/api/plugins/<your-slug>/icon` and renders it in the plugin list and in the sidebar entry for any plugin that ships an admin page.

```text
my-plugin/
├── plugin.manifest.json
├── icon.png              bundled automatically
├── src/
├── public/
└── assets/
```

Notes:

- No permission required. The host serves the icon directly. You don't need `http.serve`.
- The icon is separate from action button icons, which live in `public/` (web-served) and are referenced by the `icon` field of an `actions[]` entry. See [UI: Action buttons](/docs/plugins/ui#action-buttons).

## Instructions

Drop an `INSTRUCTIONS.md` at the root of your project (alongside `plugin.manifest.json`) and the packager bundles it into the `.ocpkg` automatically. The admin UI fetches it from `/api/admin/plugins/<your-slug>/instructions` and renders it as markdown in an **Instructions** tab on the plugin's detail page.

```text
my-plugin/
├── plugin.manifest.json
├── INSTRUCTIONS.md          bundled automatically
├── src/
├── public/
└── assets/
```

Use this for setup steps, configuration notes, what permissions are requested and why, and anything else an admin needs to know after installing. Plugins without one show no Instructions tab. The filename is fixed (`INSTRUCTIONS.md`). No `http.serve` permission required.

The file is admin-facing, so write it for the streamer who installed your plugin and is opening the admin UI to figure out how to use it. README-style developer-facing notes belong in your repo's README instead.

## What's inside a `.ocpkg`

- `plugin.manifest.json`
- One code entry: `plugin.js`, `plugin.py`, or `plugin.wasm`
- `icon.png` if you provided one
- `INSTRUCTIONS.md` if you provided one
- The contents of your `public/` directory if you have one (web-served at `/plugins/<slug>/`)
- The contents of your `assets/` directory if you have one (host-read for manifest fields that inline content)

The code filename selects the runtime. A native module must be named `plugin.wasm` inside the archive, regardless of the plugin slug.

Build inputs such as `node_modules`, `package.json`, `pyproject.toml`, `Cargo.toml`, and uncompiled source do not belong in the package. They produce the code entry that the server runs.

## Loose native WebAssembly files

During development, a native module can be installed without creating an `.ocpkg`. Copy the module and manifest into `data/plugins/` with the same basename:

```text
data/plugins/
├── my-plugin.wasm
└── my-plugin.manifest.json
```

Owncast scans for the `.wasm` file and reads the matching `.manifest.json`. The packaged `.ocpkg` format is still recommended for distribution because it keeps the code, manifest, and optional assets together.

## Installing on a server

In the Owncast admin, open **Plugins** in the sidebar and click **Upload plugin**. Pick your `.ocpkg` and the server installs it in place. The new plugin appears in the list immediately.

If the admin UI isn't an option (automation, no browser access, scripted deploys) you can also drop the `.ocpkg` directly into the server's `data/plugins/` directory:

```sh
scp my-plugin.ocpkg user@your-owncast-server:/path/to/owncast/data/plugins/
```

The server scans this directory periodically. The plugin appears in the admin's **Plugins** page within a couple of seconds.

In either case, finish the install in the admin:

1. Click your plugin in the list to open its detail view.
2. Review the **Permissions** tab. These are exactly what your manifest declared.
3. Toggle **Enabled** to load the plugin. The first enable also captures the approved permission set.

## Updating an installed plugin

To ship an update, replace the package file in `data/plugins/` directly, or install the new version from the admin's **Browse** tab if you publish to the plugin catalog. The manifest's `slug` is the identity key: the new contents replace the existing entry with the same slug, whatever the file was called. To force an immediate reload of an enabled plugin, click **Reload** on its row.

Uploading from the admin's **Plugins** page only installs a _new_ plugin. An upload whose `slug` already belongs to an installed plugin is rejected ("uninstall it before uploading another plugin with the same slug"), so uninstall the old one first if the admin upload is your only update path.

Two files in `data/plugins/` that declare the same `slug` are also a conflict. Owncast keeps the first one it finds, ignores the other, and logs which package was skipped.

### What happens when permissions change

- You removed permissions. Silent. The plugin reloads with the smaller set.
- You added permissions. The old approved version keeps running (it holds only the approved permissions) and the new package waits as pending, with a "needs re-approval" badge in the plugin list. The admin reviews the new permissions in the **Permissions** tab (new entries are tagged) and clicks **Approve** to accept the expanded set and load the update.

A plugin's effective capabilities never grow without explicit admin consent, even across updates.

### Bumping the version

Bump `version` in `plugin.manifest.json` whenever you cut a release. It's what admins see in the plugin list and what the registry uses to tell releases apart. The host doesn't gate loading on it: update identity is the `slug`, and the load-time check compares slug and permissions, not version.

Versioning is for humans. Semver is recommended but not enforced.

## Disabling and uninstalling

- Disable keeps the plugin installed but stops loading it. The admin's choice is persisted across restarts. Toggle **Enabled** back on to load it again.
- Uninstall removes the plugin entirely. From the admin's **Plugins** page click the trash icon on the plugin's row and confirm. (You can also remove the `.ocpkg` from `data/plugins/` directly, and the next scan picks up the deletion.)

## Distribution checklist

Before you publish a plugin:

- The manifest declares only what you use. Drop unused permissions. The narrower your ask, the easier the admin's trust decision.
- `description` is filled in. Admins see it in the plugin list and during install. One sentence covering what the plugin does.
- `version` reflects what you're shipping. Semver is conventional.
- The README in your repo explains what it does, what permissions it asks for and why, and what to configure (env vars, admin-page settings, and so on).
- Tests pass. Your SDK's test command should be green.
- The icon is included if you have one.
- An `INSTRUCTIONS.md` ships with anything an admin needs to know after install: setup steps, configuration notes, why each permission is requested. Plugins with non-obvious behavior or required configuration should ship one. Trivial plugins (a hello-world chat handler) don't need it.

## Publishing to the plugin catalog

Listing your plugin in the public plugin catalog is optional, but this is how you offer it to all Owncast users. A `.ocpkg` is self-contained, so you can always hand it to an admin directly if they want it, but the catalog is the way to go. The catalog just makes your plugin discoverable and gives admins one-click install and updates.

A few manifest fields shape your listing, so fill them in first: `name` (the display name), `version` (bump it for every update), `slug` (your permanent identifier, see [Manifest](/docs/plugins/manifest#name-and-slug)), `description` (the one-line summary on your card), `permissions` (keep them minimal, admins review them), and an optional `icon.png`.

### Sign in

The catalog uses passwordless, magic-link sign-in. Go to [the catalog login](https://owncast.directory/plugins/login), enter your email, and click the link in your inbox. Your email is your author identity, tied to the plugins you own. On your account page you can set an optional display name that appears as the author on your listings.

### Submit

Go to [the catalog submission page](https://owncast.directory/plugins/submit) and upload your `.ocpkg`. The public catalog reads your manifest, validates the package, and publishes the version. Submission is done through the website, with no command-line publish step today. The form also takes a few optional extras: a preview image (a screenshot, PNG or JPEG up to 5 MB), a homepage link, browse tags, and a summary that overrides the manifest description.

### Ownership and updates

- The first submitter owns the slug. When you publish a slug for the first time, it is bound to your account and nobody else can publish under it. A submission for a slug owned by another author is rejected.
- Each version is published once. To ship an update, bump `version` in your manifest, re-package, and submit again.
- Manage your plugins at [on the catalog](https://owncast.directory/plugins/account), where you can see everything you have published and remove a listing.

### What operators see

In the Owncast admin's catalog Browse view your plugin shows its name, author, description, icon, latest version, and preview image if you uploaded one. When an admin installs it, Owncast shows the permissions your manifest requests, renders your `INSTRUCTIONS.md`, and lists any chat commands you register. That metadata is what an operator uses to decide whether to trust and enable your plugin, so write it with that reader in mind.

## Where to go next

- [Manifest reference](/docs/plugins/manifest) for the full list of manifest fields.
- [Permissions](/docs/plugins/permissions) for the trust model and the full permission list.
- Example plugins: [JavaScript](https://github.com/owncast/plugin-sdk/tree/main/examples/js) · [Python](https://github.com/owncast/plugin-sdk/tree/main/examples/python).

---

## Plugin Permissions

Every Owncast plugin runs in a sandbox with no implicit access to anything outside the plugin itself. To do useful work (read chat, post to the fediverse, fetch a URL, write to a key-value store) your plugin asks the host through `owncast.*` methods. Almost every one of those methods is gated by a permission you declare in your manifest. The exceptions are a handful of **ambient** methods that reach nothing sensitive and need no permission: `owncast.log.*`, `owncast.timer.*`, reading your own bundled assets, and `owncast.config.get`.

:::new[Plugin permissions require Owncast v0.3.0]
Plugins require Owncast 0.3.0 or later.
:::

When an admin installs a plugin, the **Permissions** tab on the plugin's detail page lists exactly what the plugin asked for, in plain language. That's the trust boundary: an admin can install a third-party plugin without auditing every line of code, because the manifest is the upper bound on what the plugin can do.

:::info[Available in every SDK]
The permission identifiers and the trust model below are the same regardless of which SDK you use. `owncast.*` methods are referenced here by their canonical names. For the exact spelling in your language, see the **[JavaScript](/docs/plugins/sdks/javascript)** or **[Python](/docs/plugins/sdks/python)** SDK reference.
:::

## How it works

1. You declare permissions in `plugin.manifest.json`:

   ```json
   { "permissions": ["chat.send", "storage.kv"] }
   ```

2. The admin reviews them when enabling. Owncast's plugin detail page lists each permission with a human-readable description.

3. The host enforces them at runtime. Calling `owncast.chat.send(...)` without `chat.send` in your manifest never reaches Owncast: the host logs the denial and the call does nothing. Mutating calls that report an outcome raise an error (moderation, `users.register`, `auth.grantSession`, `kv.set`, `videoConfig.write`, `actions.add`, `actions.clear`, and every `sql` method), readers return an empty or zero value, and calls that return nothing become silent no-ops. `fs.write`, `fs.delete`, and `storage.upload` report failure in their return value instead of raising.

4. The host catches drift. Your built plugin declares the permissions it uses at runtime. The host compares that against the manifest and refuses to load the plugin if the runtime asks for more than the manifest grants. You can't sneak in extra access by swapping out the plugin file after the fact.

### Re-approval when permissions expand

If you ship an update that asks for more permissions than the admin previously approved, the old approved version keeps running (it holds only the approved permissions) and the new package waits as pending. The plugin list shows a "needs re-approval" badge. The admin reviews the new permissions in the **Permissions** tab and clicks **Approve** to accept the expanded set and load the update. Shrinking permissions is silent.

```mermaid
flowchart TB
    Update([Admin drops a new .ocpkg]) --> Scan[Owncast scans the manifest]
    Scan --> Diff{Manifest permissionsvs approved set}
    Diff -->|same or subset| Load[Reload with the update]
    Diff -->|new permissions added| Pending[Old approved version keeps runningnew package waits as pending]
    Pending --> Review[Admin reviews new permissionsin the Permissions tab]
    Review --> Click[Admin clicks Approve]
    Click --> Snapshot[Capture new permission setas approved baseline]
    Snapshot --> Load
```

An installed plugin's effective capabilities never grow without the admin saying yes again.

## Permission reference

### `chat.send`

Grants:

- `owncast.chat.send(text)`: post as the plugin's bot identity
- `owncast.chat.sendAction(text)`: post a "/me" message
- `owncast.chat.sendTo(clientId, text)`: private message a connected client
- `owncast.chat.replyTo(msg, text)`: whisper a reply back to whoever sent a chat message (sugar over `sendTo`)
- `owncast.chat.system(body)`: post a system message with no user identity, rendered as a server announcement (the body is HTML)

Messages go through Owncast's normal chat pipeline (filters, rate limits, persistence, moderation). Plugins cannot send under arbitrary names or impersonate real users.

### `chat.history`

Grants:

- `owncast.chat.history(limit?)`: read recent chat messages
- `owncast.chat.clients()`: list connected chat clients

Read-only.

### `chat.moderate`

Grants:

- `owncast.chat.deleteMessage(messageId)`: hide a message from viewers
- `owncast.chat.kick(clientId)`: disconnect a chat client

### `chat.filter`

Grants the ability to define `filterChatMessage(msg)`: see every chat message before it's broadcast, with the ability to rewrite or drop it.

Filtering happens inline on every chat message, so the admin needs to see this called out explicitly. The host rejects the load if a plugin defines `filterChatMessage` without declaring this permission.

### `users.read`

Grants:

- `owncast.users.list()`: read the chat user list
- `owncast.users.get(id)`: read a single user record

### `users.moderate`

Grants:

- `owncast.users.setEnabled(id, enabled, reason?)`: enable or disable a user
- `owncast.users.banIP(ip)`: ban an IP from joining chat

### `users.register`

Grants `owncast.users.register({ authId, displayName?, scopes?, profileUrl?, handle?, public? })`: find or create an authenticated Owncast user for an external identity and return its `userId`. The `authId` is a stable, provider-scoped identifier such as `"github:583231"`. Pass it raw, without prefixing your slug. The host records the slug separately and scopes every lookup to that pair, so two plugins cannot collide with or spoof each other's users.

The optional `profileUrl`, `handle`, and `public` fields attach a verified external identity. The profile URL must be empty or an absolute HTTP(S) URL. Set `public` to `true` only after the viewer opts into public display. These profile fields are captured on the first registration.

This is how a plugin turns a third-party login (OAuth, Discord, a shared password) into a real Owncast user with an authenticated chat identity. On its own it neither gates the site nor issues a session: pair it with `auth.gate` to build a login gate, or use it alone to mint verified chat identities.

### `auth.gate`

Grants the viewer-authentication gate:

- `owncast.auth.grantSession({ userId, ttl? })`: issue a signed session for an already-registered user (see `users.register`)
- `owncast.auth.endSession()`: clear the current viewer's session (sign-out)
- the optional `onAuthCheck` handler: re-validate a viewer's session on each page load

A plugin holding `auth.gate` is an **identity provider**. While it is enabled, viewers must authenticate through it before they can reach the page, chat, or the API. The operator selects one cumulative access mode on the plugin's **Authentication** tab to decide whether Owncast-hosted video and stream status also require a session. Only one `auth.gate` plugin can be enabled at a time, and the gate fails closed: if the plugin is unavailable, viewers are kept out rather than let in. See **[Authentication](/docs/plugins/auth)** for the full model.

### `storage.kv`

Grants `owncast.kv.get(key)`, `owncast.kv.set(key, value)`, and the JSON helpers `owncast.kv.getJSON(key, fallback?)` and `owncast.kv.setJSON(key, value)`: a per-plugin namespaced key/value store. Plugins cannot read each other's keys.

State persists across reloads and host restarts.

### `storage.upload`

Grants `owncast.storage.upload(name, data)`: upload a file to Owncast's public file area and get back a URL. Useful for badges, dynamically-generated images, fediverse post attachments.

### `storage.fs`

Grants `owncast.fs.*`: a private, sandboxed filesystem at `data/plugin-storage/<your-slug>/files/` that your plugin can read, write, list, and delete within. Useful for caches, generated data files, append-style logs, or anything you need to persist as real files rather than key/value strings.

Unlike `storage.upload`, these files stay **server-side**: they're never served over HTTP. Every path is confined to your plugin's own directory: a plugin cannot read another plugin's files or escape its sandbox (`../` and absolute paths are collapsed back inside).

### `storage.sql`

Grants `owncast.sql.*`: one private SQLite database per plugin, at `data/plugin-storage/<your-slug>/db/plugin.db`. `owncast.sql.exec(sql, params?)` runs statements, `owncast.sql.query(sql, params?)` returns matching rows, and `owncast.sql.queryRow(sql, params?)` reads a single row. Reach for this instead of `storage.kv` when you need to sort, filter, or aggregate rather than just remember a value. See [`owncast.sql.*`](/docs/plugins/apis#owncastsql) for the methods in both languages, the per-call limits, and the SQL the host refuses.

The database is private to your plugin and separate from Owncast's own database. The `storage.fs` sandbox is rooted at `files/`, so `db/` is not a path `owncast.fs.*` refuses but one it **cannot express**, and the filesystem quota walk covers `files/` only, so the two quotas stay independent: the database has its own 128 MiB cap, and files written through `storage.fs` count against a separate 256 MiB quota.

Plugin databases are **not** included in Owncast's database backups, so treat the contents as rebuildable or export what matters yourself. SQL data is retained when a plugin is uninstalled, the same as its config and its `storage.fs` files, so a reinstall finds its tables where it left them. An admin who wants the space back deletes `data/plugin-storage/<your-slug>/`.

### `network.fetch`

Grants `owncast.http.fetch(url, opts?)`: synchronous outbound HTTP.

Requires a companion `network.allowedHosts` list in the manifest. The host rejects the load if `network.fetch` is granted without an allowlist. Each call is checked against the allowlist. Hosts that don't match return an error before any bytes leave the server.

```json
{
  "permissions": ["network.fetch"],
  "network": { "allowedHosts": ["api.discord.com", "*.weather.com"] }
}
```

The wildcard `"*"` is permitted but must be written explicitly so admins reviewing the manifest see the scope. The admin UI surfaces the full `allowedHosts` list on the **Permissions** tab next to the `network.fetch` row, so a server operator reviewing a plugin sees exactly which hosts it can reach without unpacking the `.ocpkg`.

### `events.emit`

Grants `owncast.events.emit(eventType, payload)`. Pass the receiving plugin's
fully qualified `<recipient-slug>.<hook>` name. The host does not rewrite the
emitted name. Declaring and receiving a plugin-owned custom hook does not
require a permission.

### `http.serve`

Grants the host's HTTP router permission to send requests at `/plugins/<your-slug>/*` to your plugin. This covers both static files in your `public/` directory and dynamic requests routed to your `onHttpRequest` handler.

Without this permission, the entire `/plugins/<your-slug>/` URL space returns `404`.

### `http.sse`

Grants `owncast.sse.send(channel, event, data)` and exposes a host-owned endpoint at `/plugins/<your-slug>/_sse/<channel>` that browsers connect to with `EventSource`. Independent of `http.serve`. A plugin may push events without serving any other routes.

### `server.read`

Grants the read-only stream and server state APIs:

- `owncast.stream.current()`: live stream state
- `owncast.stream.broadcaster()`: inbound encode telemetry
- `owncast.server.info()`: server name, version, summary
- `owncast.server.socials()`: configured social links
- `owncast.server.emotes()`: custom chat emotes configured on this server
- `owncast.server.federation()`: fediverse settings
- `owncast.server.tags()`: configured tags

### `videoconfig.read`

Grants `owncast.videoConfig.read()`: read the output and transcoding configuration (codecs, latency level, stream variants).

### `videoconfig.write`

Grants `owncast.videoConfig.write(partial)`: modify the video output configuration.

High-trust. Changes apply on the next stream start. The host does not restart an active broadcast. Admins should grant sparingly.

### `notifications.send`

Grants the broadcaster-notification APIs:

- `owncast.notifications.discord(text)`: through the streamer's configured Discord webhook
- `owncast.notifications.browserPush({ title, body, url? })`: to subscribed browsers
- `owncast.notifications.fediverse({ type, body, image?, link? })`: fediverse-formatted notification

### `fediverse.inbound`

Grants subscription to all seven inbound Fediverse plugin events:

- `fediverse.follow`
- `fediverse.like`
- `fediverse.repost`
- `fediverse.quote`
- `fediverse.mention`
- `fediverse.reply`
- `fediverse.activity`

The `fediverse.activity` catch-all receives the verified activity's raw JSON object. It runs in addition to any matching specialized event. This permission only covers receiving activity. Posting from the Owncast account requires the separate `fediverse.post` permission.

### `fediverse.post`

Grants `owncast.fediverse.post(text)`: make a public post to the fediverse from the Owncast account.

High-trust: posts go out under the streamer's own fediverse handle and can't be silently revoked. Admins should grant sparingly.

### `ui.modify`

Grants the ability to place UI inside Owncast's own chrome:

- Declaring `manifest.actions` (action buttons under the stream).
- Calling `owncast.actions.add(...)` / `.clear()` at runtime.
- Declaring `manifest.styles` (CSS inlined into the viewer page).
- Declaring `manifest.scripts` (JavaScript inlined into the viewer page).
- Declaring `manifest.extraPageContent` (an HTML block prepended to the viewer's extra-content area).
- Declaring `manifest.tabs` (additional tabs in the viewer page's tab row).
- Implementing an `onPageStyles` or `onPageScripts` handler (CSS or JavaScript returned at request time, with no manifest field).

Without this permission, manifests that declare any of those fields are rejected at load. The `onPageStyles` and `onPageScripts` handlers have no manifest field, so they aren't rejected at load. The host just doesn't call them unless the plugin holds `ui.modify`. Each of these reaches into the viewer page rather than staying inside the plugin's own URL space, so the admin needs to see the permission to understand the plugin paints into the host UI.

None of the four viewer-injection fields require `http.serve`, and neither do the two handlers. The host reads each file from the plugin's `assets/` directory (not from a URL), or calls the handler, and inlines the result into the existing config / custom-JS responses, so `ui.modify` alone is enough.

## Summary table

| Permission           | Grants                                                                                                                         |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `chat.send`          | `owncast.chat.send`, `.sendAction`, `.sendTo`, `.replyTo`, `.system`                                                           |
| `chat.history`       | `owncast.chat.history`, `.clients`                                                                                             |
| `chat.moderate`      | `owncast.chat.deleteMessage`, `.kick`                                                                                          |
| `chat.filter`        | Subscribe to `filterChatMessage` (read, modify, or drop every chat message).                                                   |
| `users.read`         | `owncast.users.list`, `.get`                                                                                                   |
| `users.moderate`     | `owncast.users.setEnabled`, `.banIP`                                                                                           |
| `users.register`     | `owncast.users.register`: find-or-create an authenticated user for an external identity                                        |
| `auth.gate`          | `owncast.auth.grantSession`, `.endSession`, and the `onAuthCheck` handler: be the site's auth gate                             |
| `storage.kv`         | Per-plugin namespaced key/value store                                                                                          |
| `storage.upload`     | Upload files to Owncast's public file area                                                                                     |
| `storage.fs`         | Private, sandboxed server-side filesystem at `data/plugin-storage/<your-slug>/files/`                                          |
| `storage.sql`        | Private per-plugin SQLite database at `data/plugin-storage/<your-slug>/db/plugin.db`                                           |
| `network.fetch`      | Outbound HTTP. Also requires `network.allowedHosts`                                                                            |
| `events.emit`        | Emit custom events for other plugins                                                                                           |
| `http.serve`         | Serve HTTP at `/plugins/<your-slug>/*`                                                                                         |
| `http.sse`           | Push realtime events via `owncast.sse.send` and the `/_sse/` endpoint                                                          |
| `server.read`        | Read stream state, server config, encode telemetry                                                                             |
| `videoconfig.read`   | Read the output/transcoding config                                                                                             |
| `videoconfig.write`  | Modify the video output config (applies on the next stream start)                                                              |
| `notifications.send` | Send Discord, browser-push, or fediverse notifications                                                                         |
| `fediverse.inbound`  | Subscribe to all seven inbound events: `fediverse.follow`, `.like`, `.repost`, `.quote`, `.mention`, `.reply`, and `.activity` |
| `fediverse.post`     | Public-post to the fediverse (rate-limited)                                                                                    |
| `ui.modify`          | Add action buttons or tabs to Owncast's viewer chrome. Inline plugin CSS, JavaScript, or HTML into the viewer page             |

## Principle of least privilege

Declare only what you actually use. The narrower your manifest, the easier the admin's trust decision. If you find yourself listing every permission, step back and see if your plugin should really be two plugins.

If you stop using a permission during development, drop it from the manifest. Shrinking is silent. There's no friction in removing unused entries.

---

## Plugin quickstart

The quickest way to build a plugin is with the JavaScript or Python SDK. Pick a tab below and follow it through installation. To use Rust, TinyGo, AssemblyScript, Zig, or another compiled language instead, see [Native WebAssembly](/docs/plugins/sdks/native-wasm).

## Prerequisites

- An Owncast server you can administer, version 0.3.0 or newer.

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

- Node.js 18 or newer (`node --version` to check) for the `@owncast/plugin-sdk` toolchain.

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

- Python 3.8 or newer, and [`uv`](https://docs.astral.sh/uv/) or `pip` to install the `owncast-plugin-py` toolchain.

</TabItem>
</Tabs>

## 1. Create a new plugin

A plugin's identifier is its **slug**: lowercase letters, digits, and hyphens, starting with a letter. It's used as the directory name, the output filename, and the URL prefix.

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

Scaffold a project with `create-owncast-plugin`, passing the slug:

```sh
npx create-owncast-plugin@latest my-plugin
cd my-plugin
npm install
```

You now have:

```text
my-plugin/
├── package.json
├── plugin.manifest.json     display name, slug, version, permissions
├── README.md                how to build, test, package, and install it
├── INSTRUCTIONS.md          optional, rendered as a tab in the admin
├── AGENTS.md                notes for AI coding agents
├── .agents/                 a bundled skill for AI coding agents
├── src/
│   └── plugin.js            your code, with a sample handler
└── __tests__/
    └── plugin.test.js       a sample scenario test
```

`npm install` also creates `node_modules/`. None of these are created for you, but you can add an `icon.png` (shown in the admin plugin list), a `public/` directory (static files served at `/plugins/my-plugin/`), and an `assets/` directory (files the host inlines for manifest fields).

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

Scaffold a project with `new`, passing the slug. `uvx` runs the scaffolder straight from PyPI without installing anything:

```sh
uvx owncast-plugin-py new my-plugin
cd my-plugin
uv tool install owncast-plugin-py      # or:  pip install owncast-plugin-py — for build/test/serve/package
```

You now have:

```text
my-plugin/
├── plugin.manifest.json     display name, slug, version, permissions
├── README.md                how to build, test, package, and install it
├── INSTRUCTIONS.md          optional, rendered as a tab in the admin
├── AGENTS.md                notes for AI coding agents
├── .agents/                 a bundled skill for AI coding agents
├── src/
│   └── plugin.py            your code, with a sample handler
└── __tests__/
    └── plugin.test.json     a sample scenario test
```

</TabItem>
</Tabs>

The manifest has both a human-readable display name (`"name": "My Plugin"`) and a slug (`"slug": "my-plugin"`). The display name is what admins see in lists. The slug is the canonical identifier. See the [manifest reference](/docs/plugins/manifest#name-and-slug) for the rules.

## 2. Write some code

A handler reacts to an event. The SDK derives the manifest's subscription list from which handlers you define, so there's nothing else to keep in sync. Here's an echo bot:

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

Open `src/plugin.js`:

```js
const { definePlugin, owncast } = require('@owncast/plugin-sdk');

module.exports = definePlugin({
  onChatMessage(msg) {
    owncast.chat.send(`echo: ${msg.body}`);
  },
});
```

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

Create `src/plugin.py`:

```python
from owncast_plugin import plugin, owncast

@plugin.on_chat_message
def echo(msg):
    owncast.chat.send(f"echo: {msg.body}")
```

</TabItem>
</Tabs>

See the [handlers reference](/docs/plugins/events) for everything you can hook into, and the [APIs reference](/docs/plugins/apis) for every `owncast.*` method.

## 3. Build the plugin

This produces `my-plugin.ocpkg` in your project root: a single file containing your manifest, the compiled plugin, and the contents of `public/` and `assets/`. The `.ocpkg` is the distribution format: that one file is everything an admin needs.

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

```sh
npm run package
```

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

```sh
owncast-plugin-py package
```

</TabItem>
</Tabs>

## 4. Run the tests

Each scenario fires events through the real plugin runtime with mocked side effects, so a passing test means the same behavior in production. See the [testing guide](/docs/plugins/testing) for the full data model.

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

```sh
npm test
```

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

```sh
owncast-plugin-py test
```

</TabItem>
</Tabs>

## 5. (Optional) iterate against a local dev server

Serves the plugin at `http://localhost:8080/plugins/my-plugin/` for curling endpoints, opening static pages in a browser, or triggering event handlers through the `/_dev/` helper endpoints (for example `POST /_dev/chat`). Restart the dev server when you change your code.

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

```sh
npm run serve
```

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

```sh
owncast-plugin-py serve
```

</TabItem>
</Tabs>

## 6. Install on your server

In the Owncast admin, open **Plugins** in the sidebar and click **Upload plugin**. Pick the `my-plugin.ocpkg` file your build produced. The plugin appears in the list immediately. Toggle **Enabled** to load it.

Alternatively, copy `my-plugin.ocpkg` to your server's `data/plugins/` directory and the next scan tick will pick it up:

```sh
scp my-plugin.ocpkg user@your-owncast-server:/path/to/owncast/data/plugins/
```

If the plugin declares permissions, the admin reviews them in the **Permissions** tab on the plugin's detail page before enabling. The first enable captures the approved permission set. If you later ship an update that asks for more access, the already-approved version keeps running with its existing permissions while the update waits as pending until the admin re-approves.

## What to read next

- [Choosing an SDK](/docs/plugins) and its [JavaScript](/docs/plugins/sdks/javascript) / [Python](/docs/plugins/sdks/python) pages for the full language-specific reference.
- [Manifest reference](/docs/plugins/manifest) for the full schema for `plugin.manifest.json`.
- [Handlers reference](/docs/plugins/events) for every event you can subscribe to.
- [Owncast APIs](/docs/plugins/apis) for every method you can call from plugin code.

## When things go wrong

- The plugin doesn't appear in the admin list. Make sure the `.ocpkg` is in `data/plugins/`, not just `plugins/`, and the filename ends in `.ocpkg`. The admin **Plugins** page has a Refresh button if you don't want to wait for the next scan tick.
- The plugin appears but won't enable. Check the admin's plugin detail view. The **Status** column shows `error` if the manifest is invalid or the plugin failed to instantiate. Hover for the message, or run your tests locally to catch the same problem before shipping.
- The plugin enables but does nothing. Make sure you're using the right handler name (`onChatMessage` / `on_chat_message`, not `onMessage`) and that the matching permission is in your manifest. A call without its permission never reaches Owncast: the denial is logged on the server and the call returns an empty or zero value, so watch the Owncast logs.
- The plugin is auto-disabled. A filter that throws or hangs five times in a row gets disabled for the rest of the session. Fix the bug, rebuild, redeploy, and re-enable.

---

## JavaScript SDK

The JavaScript SDK, [`@owncast/plugin-sdk`](https://www.npmjs.com/package/@owncast/plugin-sdk), is the most common way to write an Owncast plugin. You write JavaScript or TypeScript, and the CLI bundles it into a single installable plugin that runs sandboxed inside the Owncast server. If you're choosing an authoring path, see the [plugins overview](/docs/plugins#choose-an-authoring-path).

:::new[JavaScript plugins require Owncast v0.3.0]
The plugin SDKs are brand-new in Owncast 0.3.0 and the API is still evolving. If you hit a bug or have a suggestion, please [open an issue](https://github.com/owncast/plugin-sdk/issues) or [chat live with the community](/chat?tab=community).
:::

This page is the JavaScript-specific layer: scaffolding, `definePlugin`, the CLI, and TypeScript. Handlers, APIs, permissions, and the manifest work the same in both SDKs and have their own reference pages.

## How it maps to the reference docs

The shared reference names APIs in their canonical form, which is the JavaScript form: so you can read it as-is. Quick orientation:

| In the reference                                    | In JavaScript                                                      |
| --------------------------------------------------- | ------------------------------------------------------------------ |
| Define a handler                                    | a method on `definePlugin({ ... })`                                |
| Handler for an event (e.g. `chat.message.received`) | `onChatMessage(msg)`: camelCase, `on` + the event                  |
| Call a host API (e.g. `owncast.chat.sendAction`)    | identical: `owncast.chat.sendAction(text)`                         |
| Payload fields                                      | camelCase: `msg.user.displayName`, `msg.clientId`                  |
| Filter result                                       | `filter.pass()` / `filter.modify(payload)` / `filter.drop(reason)` |
| Declare a plugin-owned custom hook                 | `on: { "my.event"(payload) { … } }`. Owned as `<your-slug>.my.event` |
| Build / test your plugin                            | `npm run package` / `npm test`                                     |

## Prerequisites

- An Owncast server you can administer, version 0.3.0 or newer.
- Node.js 18 or newer (`node --version` to check).

## Scaffold a new plugin

You don't install the SDK by hand. Scaffold a project with `create-owncast-plugin` and the generated `package.json` already lists `@owncast/plugin-sdk` as a dependency:

```sh
npx create-owncast-plugin@latest my-plugin
cd my-plugin
npm install     # fetches the test and serve helpers
```

Pass the slug you want as the argument. The scaffold uses it for the directory name, the output filename, and the URL prefix. Slugs are lowercase letters, digits, and hyphens, starting with a letter.

You now have:

```text
my-plugin/
├── package.json
├── plugin.manifest.json     display name, slug, version, permissions
├── README.md                how to build, test, package, and install it
├── INSTRUCTIONS.md          optional, rendered as a tab in the admin
├── AGENTS.md                notes for AI coding agents
├── .agents/                 a bundled skill for AI coding agents
├── src/
│   └── plugin.js            your code, with a sample handler
└── __tests__/
    └── plugin.test.js       a sample scenario test
```

`npm install` also creates `node_modules/`. None of these are created for you, but you can add an `icon.png` (shown in the admin plugin list), a `public/` directory (static files served at `/plugins/my-plugin/`), and an `assets/` directory (files the host inlines for manifest fields).

`npm install` runs a postinstall step that fetches the prebuilt test and serve host binaries (the scenario runner and the dev server). Building and packaging a plugin need no download. This postinstall is the only network step, and everything after is local.

## Write a plugin

A plugin is the object you pass to `definePlugin`. Define a method for each event you want to react to: the SDK derives the manifest's subscription list from which methods are present, so there's no separate list to keep in sync.

```js
const { definePlugin, owncast, filter } = require('@owncast/plugin-sdk');

module.exports = definePlugin({
  onChatMessage(msg) {
    owncast.chat.send(`echo: ${msg.body}`);
  },

  filterChatMessage(msg) {
    return msg.body.includes('spam') ? filter.drop('spam') : filter.pass();
  },
});
```

The package exports four things you'll use:

- **`definePlugin(handlers)`**: registers your handlers and returns the plugin object to export.
- **`owncast`**: the host API namespace (`owncast.chat.send(...)`, `owncast.kv.get(...)`, and the rest). Method names are **camelCase**. Each call is gated by the matching permission you declare in your manifest. See the [APIs reference](/docs/plugins/apis).
- **`filter`**: the constructor for filter results: `filter.pass()`, `filter.modify(payload)`, `filter.drop(reason)`. Used only from `filterChatMessage`.
- **`authCheck`**: verdict helpers for the `onAuthCheck` handler of an `auth.gate` plugin: `authCheck.ok()`, `authCheck.refresh({ ttl? })`, `authCheck.deny(reason?)`.

Handler names are camelCase and map to the runtime events listed in the [handlers reference](/docs/plugins/events): `onChatMessage`, `filterChatMessage`, `onChatUserJoined`, `onStreamStarted`, `onTick`, `onFediverseFollow`, `onHttpRequest`, and so on. Payload fields are camelCase too (`msg.user.displayName`, `msg.clientId`).

Beyond top-level methods, custom-event handlers are passed as a nested object keyed by event type: `on: { "my.event"(payload) {} }`. Dynamic viewer pages use plain functions. `onTabContent(ctx)` receives the requested `manifest.tabs` object key as `ctx.slug`. `onPageContent(ctx)` receives `manifest.extraPageContent.slug`. Two more take no key: `onPageStyles()` and `onPageScripts()` return CSS and JavaScript injected into the viewer page at request time, gated on `ui.modify`. Rather than hand-rolling prefix parsing in `onChatMessage`, you can declare a `commands` table that the host's built-in `!help` picks up automatically. Both are shown for JavaScript on the subject pages: [Handlers](/docs/plugins/events), [Commands](/docs/plugins/commands), and [UI](/docs/plugins/ui).

## TypeScript

The package ships `index.d.ts`, so you get autocomplete and type-checking on every event payload and host API with no extra setup. Name your entry `src/plugin.ts` and the CLI compiles it the same way:

```ts

export default definePlugin({
  onChatMessage(msg: ChatMessage) {
    owncast.chat.send(`echo: ${msg.body}`);
  },
});
```

The build detects `src/plugin.ts`, `src/plugin.js`, `plugin.ts`, or `plugin.js` in that order. Types are declarations only: there's no separate compile step or `tsconfig` required.

## The CLI

The SDK installs an `owncast-plugin` CLI, exposed through the `package.json` scripts the scaffold writes:

| Command                  | Script            | What it does                                                          |
| ------------------------ | ----------------- | --------------------------------------------------------------------- |
| `owncast-plugin build`   | `npm run build`   | Bundles `src/plugin.{js,ts}` into an intermediate build artifact      |
| `owncast-plugin test`    | `npm test`        | Builds, then runs the `__tests__/` scenarios through the real runtime |
| `owncast-plugin serve`   | `npm run serve`   | Local dev server at `http://localhost:8080/plugins/<slug>/`           |
| `owncast-plugin package` | `npm run package` | Builds and bundles everything into `<slug>.ocpkg`: the file you ship  |

```sh
npm run package   # produces my-plugin.ocpkg
npm test          # runs your scenarios
npm run serve     # iterate against a local dev server
```

`npm run package` only rebuilds when the bundle is missing. After changing source, run `npm run build` first so the package doesn't ship stale code.

The `.ocpkg` is the single distribution artifact: it contains your manifest, the bundled code, your `public/` and `assets/` directories, and an optional `icon.png` and `INSTRUCTIONS.md`. See [Packaging & distribution](/docs/plugins/packaging) for what goes inside and how to install it.

In JavaScript, `npm test` runs `__tests__/*.test.js` files calling `runScenarios` (build the array with loops, helpers, and fixtures), or static `__tests__/*.test.json` files. The full scenario data model and the local dev server (`npm run serve`) are on the [Testing](/docs/plugins/testing) page.

## Constraints to know

The CLI bundles your code into a single file that runs inside the server's sandbox, not in Node. That sandbox shapes how you write a plugin:

- **Use `owncast.http.fetch` for outbound HTTP**, not the global `fetch`, `axios`, or a package that wraps Node's `http`. Network access goes through the host API and is gated on the `network.fetch` permission. See the [APIs reference](/docs/plugins/apis).
- **Not every npm package works.** Pure-JavaScript packages bundle in fine. Anything that needs the Node.js runtime does not. See [Third-party libraries](#third-party-libraries).

## Third-party libraries

:::caution[Read this before you add a dependency]
npm packages work only if they're **pure JavaScript**. A plugin runs in a sandbox, not Node, so a package that touches `fs`, `net`, `http`/`https`, `path`, `crypto`, `process`, or `child_process` bundles cleanly and then throws when that code runs.
:::

A package can also hit a Node built-in on a path you never exercise, so test the parts you use. For outbound HTTP, use [`owncast.http.fetch`](/docs/plugins/apis), not an HTTP-client package.

The [`page-content-demo`](https://github.com/owncast/plugin-sdk/tree/main/examples/js/page-content-demo) example uses the `mustache` package this way.

## What's in the package

- `index.js`: the runtime with `definePlugin`, command handlers, the `owncast.*` host wrappers, and filter helpers.
- `index.d.ts`: TypeScript declarations for every event payload and host API.
- `testing.js`: the `runScenarios` / `runScenarioFiles` test API.
- `bin/owncast-plugin`: the CLI (`build`, `test`, `serve`, `package`).
- `scripts/postinstall.js`: fetches the prebuilt test and serve host binaries on install, used by `npm test` and `npm run serve`.

## Where to go next

- [Handlers reference](/docs/plugins/events): every event you can subscribe to and its payload shape.
- [APIs reference](/docs/plugins/apis): every `owncast.*` method and the permission it needs.
- [Testing](/docs/plugins/testing): the full scenario data model.
- [Packaging & distribution](/docs/plugins/packaging): building the `.ocpkg` and installing it.
- [Example plugins](https://github.com/owncast/plugin-sdk/tree/main/examples/js): one per feature, each a complete starting point you can copy.
- [SDK source](https://github.com/owncast/plugin-sdk): the `@owncast/plugin-sdk` package and toolchain.

---

## Native WebAssembly

A native WebAssembly plugin is a self-contained module that implements the Owncast plugin wire protocol directly. It does not use the JavaScript or Python SDK and it does not run on their shared language engines.

Use this path when you need a compiled language, want to reuse an existing library, or need direct control over the WebAssembly interface. For most plugins, the [JavaScript SDK](/docs/plugins/sdks/javascript) or [Python SDK](/docs/plugins/sdks/python) requires less code and tooling.

## Choose a language and Extism PDK

Any language that can produce an Extism-compatible WebAssembly module can be used.

| Language | Extism PDK | Build target |
| --- | --- | --- |
| Rust | [`extism-pdk`](https://github.com/extism/rust-pdk) | `wasm32-unknown-unknown` |
| TinyGo | [`go-pdk`](https://github.com/extism/go-pdk) | `wasip1` with `-buildmode=c-shared` |
| AssemblyScript | [`@extism/as-pdk`](https://www.npmjs.com/package/@extism/as-pdk) | WebAssembly through `asc` |
| Zig and others | [Extism PDKs](https://extism.org/docs/concepts/pdk) | Depends on the language |

The examples below implement the smallest valid Owncast plugin. Each exports `register`, reads the packaged manifest that Owncast injected, and returns it unchanged. They intentionally register no events or commands.

<Tabs groupId="native-wasm-language">
<TabItem value="rust" label="Rust" default>

Add `extism-pdk` to a library crate that builds as `cdylib`:

```toml title="Cargo.toml"
[package]
name = "my-plugin"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
extism-pdk = "1"
```

```rust title="src/lib.rs"
use extism_pdk::*;

#[plugin_fn]
pub fn register() -> FnResult<String> {
    Ok(config::get("manifest")?
        .ok_or_else(|| Error::msg("Owncast did not inject the plugin manifest"))?)
}
```

Build it:

```sh
rustup target add wasm32-unknown-unknown
cargo build --release --target wasm32-unknown-unknown
cp target/wasm32-unknown-unknown/release/my_plugin.wasm my-plugin.wasm
```

</TabItem>
<TabItem value="tinygo" label="TinyGo">

Create a module and add the Extism Go PDK:

```sh
go mod init example.com/my-plugin
go get github.com/extism/go-pdk@v1.1.3
```

```go title="main.go"
package main

//go:wasmexport register
func register() int32 {
	manifest, ok := pdk.GetConfig("manifest")
	if !ok {
		pdk.SetErrorString("Owncast did not inject the plugin manifest")
		return 1
	}
	pdk.OutputString(manifest)
	return 0
}

func main() {}
```

Build it with TinyGo 0.34.0 or newer:

```sh
tinygo build -o my-plugin.wasm -target wasip1 -buildmode=c-shared main.go
```

The `c-shared` build mode creates a reactor module, so Owncast can call `register` without running the module as a command.

</TabItem>
<TabItem value="assemblyscript" label="AssemblyScript">

Install AssemblyScript and its Extism PDK:

```sh
npm init -y
npm install @extism/as-pdk@1.0.0
npm install --save-dev assemblyscript@0.27.31
mkdir -p assembly
```

```ts title="assembly/index.ts"

export function myAbort(
  _message: string | null,
  _fileName: string | null,
  _lineNumber: u32,
  _columnNumber: u32,
): void {}

export function register(): i32 {
  const manifest = Config.get('manifest');
  if (manifest === null) {
    return 1;
  }
  Host.outputString(manifest);
  return 0;
}
```

Build it:

```sh
npx asc assembly/index.ts \
  --outFile my-plugin.wasm \
  --use abort=assembly/index/myAbort
```

The custom `myAbort` export keeps the module from importing AssemblyScript's default abort handler, which the Owncast host does not provide.

</TabItem>
</Tabs>

## Implement the Owncast wire protocol

Every native plugin must export `register`. Export the other entry points your plugin uses, such as `on_event`, `on_filter`, or `on_http_request`. Declare Owncast host functions as imports from the `extism:host/user` module. Your language's Extism PDK handles memory shared with those imports.

The [Owncast wire protocol](https://github.com/owncast/plugin-sdk/blob/main/docs/WIRE_PROTOCOL.md) is the source of truth for:

- Plugin exports and their input and output shapes.
- Owncast host imports and their required permissions.
- Event envelopes, filter results, and HTTP request responses.
- Timeouts and size limits.

Native modules use the same manifest, events, host functions, and permission checks as JavaScript and Python plugins. They only replace the language SDK layer.

## Read the packaged manifest

Owncast sets reserved Extism config values before calling the plugin:

| Key | Native WebAssembly value |
| --- | --- |
| `manifest` | The manifest Owncast loaded, unchanged. |
| `__slug` | The canonical slug resolved by Owncast. Use this when the plugin needs its identity. |
| `script` | Not set. The WebAssembly module is already the plugin code. |

Read `manifest` in `register` and return that JSON. Do not compile a second copy of the manifest into the module. The packaged manifest is what the administrator reviewed and what Owncast loaded, so returning it prevents two copies from drifting apart.

A language SDK derives subscriptions and commands from registered handlers. A native module has no SDK to do that work, so declare any `subscriptions` and `commands` entries it needs in `plugin.manifest.json`. Returning the injected manifest from `register` reports those declarations to Owncast.

Owncast registers each custom hook in `subscriptions.notify` as
`<recipient-slug>.<hook>` using the module's manifest slug. Emitters target that
fully qualified name. The module's `on_event` export receives the local `<hook>`.

A minimal manifest shared by all three examples is:

```json title="plugin.manifest.json"
{
  "api": "1",
  "name": "My Plugin",
  "slug": "my-plugin",
  "version": "0.1.0"
}
```

## Package the module

For loose installation and local testing, place the compiled module beside its project manifest:

```text
my-plugin.wasm
plugin.manifest.json
```

For a loose installation in Owncast's `data/plugins/` directory, rename the manifest so both files have the same basename:

```text
my-plugin.wasm
my-plugin.manifest.json
```

For an installable `.ocpkg`, create a ZIP archive with canonical names:

```text
my-plugin.ocpkg
├── plugin.manifest.json
├── plugin.wasm
├── icon.png               optional
├── INSTRUCTIONS.md        optional
├── public/                optional, web-served files
└── assets/                optional, host-read files
```

The module inside the archive must be named `plugin.wasm`, regardless of the plugin slug. Owncast uses that filename to select the native WebAssembly runtime.

See [Packaging and publishing](/docs/plugins/packaging) for installation, updates, icons, instructions, and the public plugin directory.

## Test before installing

Clone the plugin SDK repository and build `owncast-plugin-test` once:

```sh
git clone https://github.com/owncast/plugin-sdk.git
cd plugin-sdk
./tools/bootstrap.sh
```

Run it against the directory containing `<slug>.wasm`, `plugin.manifest.json`, and any scenarios:

```sh
./tools/owncast-plugin-test path/to/my-plugin
```

Use `--load-only` when the plugin has no scenario files:

```sh
./tools/owncast-plugin-test --load-only path/to/my-plugin
```

The load check calls `register`, compares the returned identity and permissions with the manifest, validates permission-carrying subscriptions, and instantiates the same host-function surface with test implementations. Fix any load failure before creating the `.ocpkg`.

---

## Python SDK

The Python SDK, `owncast-plugin-py`, lets you author Owncast plugins in **Python**. You write ordinary Python with decorators. A build step turns it into a single installable plugin that runs sandboxed inside the Owncast server: the same `.ocpkg` format and full feature set as the [JavaScript SDK](/docs/plugins/sdks/javascript), so a Python plugin is a first-class peer of a JS one.

:::new[Python plugins require Owncast v0.3.0]
The plugin SDKs are brand-new in Owncast 0.3.0 and the API is still evolving. If you hit a bug or have a suggestion, please [open an issue](https://github.com/owncast/plugin-sdk/issues) or [chat live with the community](/chat?tab=community).
:::

This page is the Python-specific layer: install, the `@plugin` decorators, the `owncast-plugin-py` CLI, and testing. Handlers, APIs, permissions, and the manifest work the same in both SDKs and have their own reference pages.

## How it maps to the reference docs

The shared reference names handlers and APIs in their canonical (camelCase) form. To read it as Python, apply one rule: **decorators, host methods, and payload attribute access are `snake_case`.** Raw wire dictionaries (`msg.raw`) and scenario JSON keep their camelCase wire names. Quick orientation:

| In the reference                                    | In Python                                                                                               |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Define a handler                                    | a `@plugin.*` decorated function                                                                        |
| Handler for an event (e.g. `chat.message.received`) | `@plugin.on_chat_message`                                                                               |
| Call a host API (e.g. `owncast.chat.sendAction`)    | `owncast.chat.send_action(text)`: snake_case                                                            |
| Payload fields (e.g. `msg.user.displayName`)        | `msg.user.display_name`, `msg.client_id`. `msg.raw` for the raw dict                                    |
| Filter result (`filter.pass()`)                     | `filter.pass_()` (trailing `_`: `pass` is a keyword). Also `filter.modify(...)` / `filter.drop(reason)` |
| Declare a plugin-owned custom hook                 | `@plugin.on("my.event")`. Owned as `<your-slug>.my.event`                                           |
| Build / test your plugin                            | `owncast-plugin-py package` / `owncast-plugin-py test`                                                  |

## Prerequisites

- An Owncast server you can administer, version 0.3.0 or newer.
- Python 3.8 or newer.

## Install

Scaffold a project with `new`, passing the slug. `uvx` runs the scaffolder straight from PyPI without installing anything:

```sh
uvx owncast-plugin-py new my-plugin
cd my-plugin
```

Install the SDK to get the `owncast-plugin-py` CLI on your PATH for the build, test, serve, and package steps:

```sh
uv tool install owncast-plugin-py      # or:  pip install owncast-plugin-py
```

You get a ready-to-build directory:

```text
my-plugin/
├── plugin.manifest.json     name, slug, version, permissions
├── README.md                how to build, test, package, and install it
├── INSTRUCTIONS.md          optional, rendered as a tab in the admin
├── AGENTS.md                notes for AI coding agents
├── .agents/                 a bundled skill for AI coding agents
├── src/plugin.py            your code, with a sample handler
└── __tests__/*.test.json    a sample scenario test
```

## Write a plugin

Import `plugin`, `owncast`, and `filter`, and register handlers with decorators. Each decorator subscribes to one event. The SDK derives the manifest's subscription list from which handlers you define.

```python
from owncast_plugin import plugin, owncast, filter

@plugin.on_chat_message
def greet(msg):
    name = msg.user.display_name if msg.user else "someone"
    owncast.chat.send(f"{name} said: {msg.body}")

@plugin.filter_chat_message
def block_spam(msg):
    return filter.drop("spam") if "spam" in msg.body else filter.pass_()
```

The module exports five things:

- **`plugin`**: the decorator registry. `@plugin.on_chat_message`, `@plugin.filter_chat_message`, `@plugin.on_stream_started`, `@plugin.on_tick`, `@plugin.on_fediverse_follow`, and the rest mirror the runtime events in the [handlers reference](/docs/plugins/events). Two take a key: `@plugin.on("custom.event")` declares a local custom hook that the host owns as `<your-slug>.custom.event`, while `@plugin.on_tab_content("slug")` and `@plugin.on_page_content("slug")` provide dynamic viewer-page HTML. For tab content, the decorator argument matches a `manifest.tabs` object key. For extra page content, it matches `manifest.extraPageContent.slug`. Two take no key: `@plugin.on_page_styles` and `@plugin.on_page_scripts` return CSS and JavaScript injected into the viewer page at request time, gated on `ui.modify`.
- **`owncast`**: the host API namespace. Method names are **`snake_case`** (`owncast.chat.send_action`, `owncast.kv.get_json`). Each call is gated by the matching permission you declare in your manifest. See the [APIs reference](/docs/plugins/apis).
- **`filter`**, filter results returned from a `filter_chat_message` handler: `filter.pass_()` (trailing underscore, `pass` is a Python keyword), `filter.modify(...)`, `filter.drop(reason)`.
- **`auth_check`**: verdict helpers for the `@plugin.on_auth_check` handler of an `auth.gate` plugin: `auth_check.ok()`, `auth_check.refresh(ttl=...)`, `auth_check.deny(reason)`.
- **`CommandContext`**: what a declared command's `run()` receives: `.msg`, `.user`, `.command`, `.invoked_as`, `.args`, and `.arg_string`, plus `reply(text)` and `reply_privately(text)` helpers. Import it for type hints.

Payloads are attribute objects with `snake_case` accessors over the wire JSON (`msg.body`, `msg.user.display_name`, `msg.client_id`). Use `msg.raw` for the underlying dict. Host calls that return JSON objects come back as the same attribute objects (`owncast.server.info().name`). Lists come back as Python lists.

Two more Python idioms worth knowing, both documented in full (with Python examples) on the subject pages:

- **HTTP routing**: plugins with `http.serve` declare routes with decorators: `@plugin.get/post/put/delete/patch(path)`, `@plugin.route(path, methods=[...])`, `@plugin.on_http_request(path)`, and a bare `@plugin.on_http_request` catch-all. A handler returns a `dict` (`{status, body, headers}`), a `str` (→ 200), or `None` (→ 204). See [Serving HTTP](/docs/plugins/http).
- **Chat commands**: `plugin.commands({...})` declares commands with aliases, moderator gating, and per-user cooldowns. The built-in `!help` lists them automatically. See [Chat commands](/docs/plugins/commands).

## The CLI

Installing the SDK gives you `owncast-plugin-py`. Building and packaging bundle your source and need no compiler. The `test`, `serve`, and `package` commands fetch the prebuilt host binaries on first use (`package` runs its install-time load check through the test binary):

| Command                           | What it does                                                        |
| --------------------------------- | ------------------------------------------------------------------- |
| `owncast-plugin-py new my-plugin` | Scaffold a new plugin project in `./my-plugin`                      |
| `owncast-plugin-py build`         | Build `src/plugin.py` (without packaging)                           |
| `owncast-plugin-py test`          | Build, then run the `__tests__/` scenarios                          |
| `owncast-plugin-py serve`         | Local dev server (`-p/--port` to change the port, defaults to 8080) |
| `owncast-plugin-py package`       | Build + bundle → `<slug>.ocpkg`: the file you ship                  |

```sh
owncast-plugin-py package    # produces my-plugin.ocpkg
owncast-plugin-py test
owncast-plugin-py serve      # POST /_dev/chat to drive event handlers
```

All four run against the current directory. The positional project argument defaults to `.`, so inside the project you pass nothing. From elsewhere, pass the project directory: `owncast-plugin-py package my-plugin`. The `.ocpkg` is the single distribution artifact. See [Packaging & distribution](/docs/plugins/packaging) for what goes inside and how to install it.

## Constraints to know

A few things about how Python plugins are built shape how you write them. You import `owncast_plugin` normally for editor support and unit tests. The build takes care of the rest.

- **Pure-Python only, and no `pip`.** There is no `pip install` step: you add third-party code by copying its (pure-Python) source into your project. Dependencies with C extensions (numpy, pandas, and the like) won't load. See [Third-party libraries](#third-party-libraries). For outbound HTTP use `owncast.http.fetch`, not `requests`.
- **Don't shadow standard-library names.** A top-level `def json(...)` (or any other stdlib name) shadows the real module and can break the build, and a module file named after a stdlib module (`src/json.py`) is ignored in favor of the real one. Name them `json_response` and the like.
- **The entry can't use relative imports.** In `src/plugin.py`, import your own modules absolutely (`from helpers import ...`), not `from . import helpers`. A relative import there fails the build, though relative imports inside a package's own modules are fine.
- **`snake_case` in the code you write**, in contrast to the JS SDK's camelCase: `send_action`, `get_json`, `msg.user.display_name`, `filter.pass_()`. Raw wire dictionaries (`msg.raw`) and scenario JSON stay camelCase.

## Third-party libraries

There is no `pip install` and no `requirements.txt`. A third-party library works only if it is **pure Python and you copy its source into `src/`**, where it becomes one of your own modules.

:::caution[pip install does nothing]
Installing a package into a virtualenv has no effect on what ships, and `import requests` fails at runtime. To use a library, copy its `.py` source into `src/` (a single module or a package directory) and import it.
:::

- **C extensions never work.** numpy, pandas, lxml, Pydantic v2, and anything else with compiled code won't load.
- **You own the whole tree.** If a library you copy in imports other third-party packages, copy those too, or choose a smaller one.
- **Use `owncast.http.fetch` for outbound HTTP**, not `requests`.

The standard library is available, as long as the module is pure Python (`json`, `re`, `datetime`, `base64`, and the like).

For example, the [`page-content-demo`](https://github.com/owncast/plugin-sdk/tree/main/examples/python/page-content-demo) example needs Mustache templating. Rather than copy in a templating package, it ships a small Mustache-subset renderer of its own.

## Testing

Tests are `__tests__/*.test.json` scenario files run with `owncast-plugin-py test`. The format is **identical to the JS SDK's**, so a Python port of a plugin can reuse the JS version's test scenarios verbatim. Each scenario dispatches events / HTTP requests and asserts on observed side effects (`chatSends`, kv writes, HTTP responses, …).

```json
[
  {
    "name": "echoes the message",
    "events": [
      {
        "event": "chat.message.received",
        "payload": { "user": { "id": "u1", "displayName": "alice" }, "body": "hi" }
      }
    ],
    "expect": { "chatSends": ["alice said: hi"] }
  }
]
```

The full scenario data model (step types, `given` state, `expect` assertions) is on the [Testing](/docs/plugins/testing) page. Note the scenario JSON uses the **wire** field names (camelCase: `displayName`, `clientId`), since it describes host events, not your Python code.

## Status

The runtime, the `owncast-plugin-py` CLI (scaffold, build, test, serve, package), the full host API, HTTP routing, and `.ocpkg` packaging all work today. All of the JS example plugins have Python counterparts under [`examples/python/`](https://github.com/owncast/plugin-sdk/tree/main/examples/python).

## Where to go next

- [Handlers reference](/docs/plugins/events): every event you can subscribe to (read names as `snake_case`).
- [APIs reference](/docs/plugins/apis): every `owncast.*` method and the permission it needs.
- [Testing](/docs/plugins/testing): the full scenario data model.
- [Packaging & distribution](/docs/plugins/packaging): building the `.ocpkg` and installing it.
- [Python example plugins](https://github.com/owncast/plugin-sdk/tree/main/examples/python): one per feature, each a complete starting point you can copy.
- [SDK source](https://github.com/owncast/plugin-sdk): the `owncast-plugin-py` package and toolchain.

---

## Testing plugins

Owncast plugins ship with a scenario-based testing framework that drives your built plugin through the real Owncast plugin runtime, with the side effects (chat sends, HTTP fetches, config writes) captured for assertions. A passing test means the same behavior in production.

:::new[Plugin testing requires Owncast v0.3.0]
Plugins require Owncast 0.3.0 or later.
:::

Scenarios are plain data, so the scenario model on this page is identical whatever language you write in. Test files live under `__tests__/`. How you write and run them differs slightly by SDK.

## Writing and running tests

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

Write `__tests__/*.test.js` files that call `runScenarios([...])`:

```js
const { runScenarios } = require('@owncast/plugin-sdk/testing');

runScenarios([
  {
    name: 'echoes the message',
    events: [
      {
        event: 'chat.message.received',
        payload: { user: { id: 'u1', displayName: 'alice' }, body: 'hi' },
      },
    ],
    expect: { chatSends: ['alice said: hi'] },
  },
]);
```

Run them with `npm test`. Because it's a script, you can build the scenario array with loops, fixtures, and computed payloads. Split scenarios across several `__tests__/*.test.js` files and run them all in one pass with `runScenarioFiles()`. Static `__tests__/*.test.json` files work too.

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

Write `__tests__/*.test.json` files containing an array of scenarios (the format shown throughout this page):

```json
[
  {
    "name": "echoes the message",
    "events": [
      {
        "event": "chat.message.received",
        "payload": { "user": { "id": "u1", "displayName": "alice" }, "body": "hi" }
      }
    ],
    "expect": { "chatSends": ["alice said: hi"] }
  }
]
```

Run them with `owncast-plugin-py test` (the directory argument defaults to the current one). Python uses the JSON format: there's no script-based runner.

</TabItem>
</Tabs>

Running the tests builds your plugin, then runs every scenario file under `__tests__/`. The scenario data model is the same whichever SDK you use.

:::note[Wire field names stay camelCase]
A scenario describes **host events**, not your plugin code, so payload fields use the wire names (`displayName`, `clientId`) regardless of the language you wrote the plugin in.
:::

## Anatomy of a scenario

```json
{
  "name": "human-readable description",
  "given": {},
  "events": [],
  "expect": {}
}
```

- `name`: what the scenario tests. Shown in pass/fail output.
- `given`: optional. Seed initial state your plugin reads from (chat history, kv values, server info, canned HTTP responses).
- `events`: the steps to run, in order. Each step is one notification dispatch, filter chain invocation, or HTTP request.
- `expect`: final-state assertions (after every step runs). What chat messages were posted, what HTTP requests went out, what was written to kv, and so on.

## Step types

### `event`: fire-and-forget notification

Dispatches a notification to the matching event handler. For a custom hook, use
the fully qualified `<recipient-slug>.<hook>` target. The host strips the slug
before invoking the plugin's local handler.

```json
{
  "event": "chat.message.received",
  "payload": {
    "user": { "id": "u1", "displayName": "alice" },
    "clientId": 1,
    "body": "hi",
    "timestamp": "2026-01-01T00:00:00Z"
  }
}
```

Common event types include `chat.message.received`, `chat.user.joined`, `stream.started`, and `stream.stopped`. Fediverse scenarios can dispatch `fediverse.follow`, `fediverse.like`, `fediverse.repost`, `fediverse.quote`, `fediverse.mention`, `fediverse.reply`, or the raw `fediverse.activity` catch-all. The full list mirrors the [handlers reference](/docs/plugins/events).

### `filter`: chain invocation with inline assertion

Sends a chat message into your chat-message filter and checks the result. The `expect` here is per-step, asserting on the `FilterResult`:

```json
{
  "filter": "chat.message.received",
  "payload": { "user": { "id": "u-alice", "displayName": "alice" }, "body": "hello damn world" },
  "expect": { "action": "modify", "payload": { "body": "hello **** world" } }
}
```

Or to assert a drop:

```json
{
  "filter": "chat.message.received",
  "payload": { "user": { "id": "u-alice", "displayName": "alice" }, "body": "buy crypto" },
  "expect": { "action": "drop", "reason": "spam keyword" }
}
```

`action` is one of `"pass"`, `"modify"`, `"drop"`.

### `http`: send an HTTP request through your plugin

```json
{
  "http": {
    "method": "GET",
    "path": "/api/status",
    "expect": { "status": 200, "body": "{\"ok\":true}" }
  }
}
```

Headers and body are optional:

```json
{
  "http": {
    "method": "POST",
    "path": "/admin/api/save",
    "headers": { "content-type": "application/json" },
    "body": "{\"value\":42}",
    "authenticated": true,
    "expect": { "status": 200 }
  }
}
```

### `authCheck`: re-validate a gate session

For [`auth.gate`](/docs/plugins/auth) plugins, drives the [`onAuthCheck`](/docs/plugins/events#auth-check) handler directly with a resolved viewer identity and asserts the verdict:

```json
{
  "authCheck": {
    "user": { "id": "u1", "displayName": "Alice" },
    "expect": { "action": "deny", "reason": "access revoked" }
  }
}
```

`action` is `"ok"`, `"refresh"`, or `"deny"`. `reason` is optional and matched exactly when set.

### Content steps

`tabContent`, `pageContent`, `pageStyles`, and `pageScripts` call the matching content handler directly and assert on the returned markup, CSS, or JavaScript:

```json
{ "tabContent": { "slug": "schedule", "expect": { "bodyContains": "Friday" } } }
```

`tabContent` and `pageContent` take a `slug` and an optional `user`. In production, Owncast passes a `manifest.tabs` object key to `onTabContent` and `manifest.extraPageContent.slug` to `onPageContent`. Scenario steps call these handlers directly, so the slug can be arbitrary when testing fallback behavior for an unknown slug. All four steps accept `expect.body` (exact) or `expect.bodyContains`.

## Final-state assertions

The scenario's top-level `expect` checks what happened across the whole run:

| Assertion           | What it checks                                                                                                                                                                                                                         |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chatSends`         | List of `owncast.chat.send` strings (exact match, in order)                                                                                                                                                                            |
| `chatActions`       | List of `owncast.chat.sendAction` strings                                                                                                                                                                                              |
| `chatSystems`       | List of `owncast.chat.system` strings                                                                                                                                                                                                  |
| `logs`              | Ordered list of `{ plugin, level, message }` entries from `owncast.log`. `plugin` is the manifest slug and `level` is `info`, `warning`, or `error`                                                                                    |
| `chatTo`            | List of `{ clientId, text }` from `owncast.chat.sendTo` / `replyTo`                                                                                                                                                                    |
| `sseSends`          | Ordered list of `{ channel, event?, data? }` from `owncast.sse.send` (omit `event`/`data` to match only on channel)                                                                                                                    |
| `deletedMessages`   | Message IDs hidden via `owncast.chat.deleteMessage`                                                                                                                                                                                    |
| `kickedClients`     | Client IDs disconnected via `owncast.chat.kick`                                                                                                                                                                                        |
| `discordPosts`      | List of Discord notification strings                                                                                                                                                                                                   |
| `browserPushes`     | List of `{ title, body, url }` browser-push payloads                                                                                                                                                                                   |
| `fediversePosts`    | List of `{ type, body?, image?, link? }` payloads sent via `owncast.notifications.fediverse`                                                                                                                                           |
| `fediverseOutbox`   | List of `owncast.fediverse.post` strings (exact match, in order)                                                                                                                                                                       |
| `userRegistrations` | List of `{ authId, displayName?, scopes?, profileUrl?, handle?, public? }` from `owncast.users.register`, in order. `authId` is always checked. Other fields are checked when present                                                  |
| `sessionGrants`     | List of `{ userId, ttl? }` from `owncast.auth.grantSession` (`ttl` is checked only when non-zero)                                                                                                                                      |
| `sessionClears`     | Number of `owncast.auth.endSession` calls                                                                                                                                                                                              |
| `userModerations`   | List of `{ userId, enabled, reason }` from `owncast.users.setEnabled`                                                                                                                                                                  |
| `bannedIPs`         | List of IPs banned via `owncast.users.banIP`                                                                                                                                                                                           |
| `uploads`           | List of `{ name, body?, bodyBase64? }` from `owncast.storage.upload`. `name` is always checked. Non-empty `body` values compare text. Present `bodyBase64` values compare exact decoded bytes                                          |
| `videoConfigWrites` | List of partial configs applied via `owncast.videoConfig.write()`                                                                                                                                                                      |
| `emits`             | List of `{ eventType, payload }` for `owncast.events.emit` calls. `eventType` is the exact fully qualified target passed by the plugin |
| `commands`          | List of `{ name, prefix?, description?, usage?, aliases?, modOnly, caseSensitive, cooldownMs }` chat-command registrations, matched by `name` in any order (`prefix`, `description`, `usage`, and `aliases` are checked only when set) |
| `kv`                | Partial map of plugin-config state after the scenario                                                                                                                                                                                  |
| `httpRequests`      | List of `{ url, method?, body? }` outbound `owncast.http.fetch` calls. `url` is an exact match, an omitted `method` matches any, an omitted `body` skips the check                                                                     |

Use the camelCase wire names in `userRegistrations` for both JavaScript and Python scenarios. `displayName`, `profileUrl`, and `handle` are compared whenever supplied, including when set to `""`. `scopes` is compared whenever supplied. `[]` expects no scopes and matches either an omitted or empty actual list. Non-empty arrays match exactly. `public` is compared whenever supplied, so `false` asserts that the plugin kept the identity private. Omit any of these fields to skip its check.

```json
{
  "expect": {
    "userRegistrations": [
      {
        "authId": "github:583231",
        "displayName": "octocat",
        "profileUrl": "https://github.com/octocat",
        "handle": "octocat",
        "public": false
      }
    ]
  }
}
```

Use `body` for text uploads. It is checked only when its value is non-empty, so omitting it or setting it to `""` skips the body check. Use `bodyBase64` for exact byte comparisons. It is checked whenever supplied and accepts standard base64 with or without padding. An empty `bodyBase64` value (`""`) decodes to zero bytes and asserts an empty upload. If both fields contain checked values, both comparisons run.

```json
{
  "expect": {
    "uploads": [{ "name": "invalid-utf8.bin", "bodyBase64": "/wCA" }]
  }
}
```

`chatSends` (and the other chat assertions) capture posts from **any** step: including chat your plugin sends from inside an HTTP-request handler, not just from event handlers.

`owncast.fs.*` (the `storage.fs` sandbox) has no dedicated assertion: the runtime backs it with a real in-memory sandbox during tests, so test it the way you'd use it: drive your plugin's own endpoints (or handlers) and assert on what they return. For example, `POST` a file through your upload endpoint, then `GET` your list endpoint and assert the response includes it. The [`file-manager`](https://github.com/owncast/plugin-sdk/tree/main/examples) example does exactly this.

[`owncast.sql.*`](/docs/plugins/apis#owncastsql) works the same way. The test runner and the dev server give each plugin a real in-memory SQLite database, so there's no SQL assertion and no `given.sql`: every scenario starts with an empty database and your plugin creates its own schema on first use. Drive the handlers or commands that write, then assert on what the ones that read send back. The same statements are refused there as on a real server and the same per-call limits apply, so a scenario that passes runs the same SQL in production. The `chat-leaderboard` example ([JavaScript](https://github.com/owncast/plugin-sdk/tree/main/examples/js/chat-leaderboard), [Python](https://github.com/owncast/plugin-sdk/tree/main/examples/python/chat-leaderboard)) is tested exactly this way: chat events count messages, then `!top` and `!rank` report the standings.

Example exercising several:

```json
{
  "name": "bumps the counter and targets an achievement hook",
  "events": [
    {
      "event": "chat.message.received",
      "payload": { "user": { "id": "u-alice", "displayName": "alice" }, "body": "hi" }
    },
    {
      "event": "chat.message.received",
      "payload": { "user": { "id": "u-alice", "displayName": "alice" }, "body": "hi again" }
    }
  ],
  "expect": {
    "chatSends": ["alice: 1 message", "alice: 2 messages"],
    "kv": { "count:u-alice": "2" },
    "emits": [{ "eventType": "achievements.milestone.reached", "payload": { "user": "alice", "count": 2 } }]
  }
}
```

## Seeding state with `given`

Each `given.*` field controls what a specific host read returns. Combine these to put your plugin in any state you want.

| Field                 | Controls                                                                                                                 |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `given.kv`            | Pre-populate your plugin's key/value store (`owncast.kv`)                                                                |
| `given.config`        | Admin-set overrides for manifest-declared config keys (`owncast.config.get`). Unseeded keys return the manifest defaults |
| `given.stream`        | What `owncast.stream.current()` returns                                                                                  |
| `given.broadcaster`   | What `owncast.stream.broadcaster()` returns                                                                              |
| `given.server`        | What `owncast.server.info()` returns                                                                                     |
| `given.socials`       | What `owncast.server.socials()` returns                                                                                  |
| `given.federation`    | What `owncast.server.federation()` returns                                                                               |
| `given.tags`          | What `owncast.server.tags()` returns                                                                                     |
| `given.videoConfig`   | What `owncast.videoConfig.read()` returns                                                                                |
| `given.chatHistory`   | What `owncast.chat.history()` returns                                                                                    |
| `given.chatClients`   | What `owncast.chat.clients()` returns                                                                                    |
| `given.users`         | What `owncast.users.list()` / `.get(id)` returns                                                                         |
| `given.httpResponses` | Canned responses for outbound `owncast.http.fetch` calls                                                                 |

Example:

```json
{
  "name": "answers !uptime when the stream is live",
  "given": {
    "stream": { "online": true, "startedAt": "2026-05-28T14:00:00Z", "viewers": 12 }
  },
  "events": [
    {
      "event": "chat.message.received",
      "payload": {
        "user": { "id": "u-alice", "displayName": "alice" },
        "body": "!uptime",
        "timestamp": "2026-05-28T14:01:30Z"
      }
    }
  ],
  "expect": {
    "chatSends": ["uptime: 90s, 12 viewer(s)"]
  }
}
```

### Canned HTTP responses

For plugins that call `owncast.http.fetch`, `given.httpResponses` is an array of canned responses. Each fixture is a flat object: `url` (a glob, e.g. `https://api.foo.com/*`), optional `method`, `status`, optional `headers`, and `body`.

```json
{
  "given": {
    "httpResponses": [
      {
        "url": "https://api.ipify.org?format=json",
        "status": 200,
        "body": "{\"ip\":\"203.0.113.42\"}"
      }
    ]
  }
}
```

A fixture matches by `url` glob (and `method`, if set). The first matching fixture wins and serves any number of calls. Fixtures aren't consumed, so a sequence where the same URL must answer differently across calls (a 401 followed by a 200 after a token refresh, say) can't be modeled. Unit-test that branch outside the runner. If your plugin makes a call that no fixture matches, the framework fails the scenario so you know to add a case.

## Auth in HTTP scenarios

By default, HTTP steps are treated as unauthenticated. To exercise admin endpoints, set `authenticated: true`:

```json
{
  "http": {
    "method": "GET",
    "path": "/admin/api/settings",
    "authenticated": true,
    "expect": { "status": 200 }
  }
}
```

For chat-user-token endpoints, set `user`:

```json
{
  "http": {
    "method": "GET",
    "path": "/my-data",
    "user": { "id": "u1", "displayName": "alice", "scopes": ["MODERATOR"] },
    "expect": { "status": 200 }
  }
}
```

Without either flag, requests to manifest-declared admin paths return `401` before your plugin code runs. Useful for asserting the auth gate works:

```json
{
  "http": {
    "method": "GET",
    "path": "/admin/index.html",
    "expect": { "status": 401 }
  }
}
```

## Speed and isolation

- Each scenario gets a fresh plugin instance and a clean in-memory config. State doesn't leak from one scenario to the next.
- Tests are fast. A typical test file with rebuild finishes in a few seconds. Run them on every save.
- No real Owncast required. The runtime is bundled with the SDK, so you don't need a server to test.

## Local dev server

For interactive iteration, run a local dev server that loads your plugin and serves it at `http://localhost:8080/plugins/<your-slug>/`: curl your endpoints, open static pages in a browser, or drive your event and filter handlers.

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

```sh
npm run serve
# override the port:
PORT=8765 npm run serve
```

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

```sh
owncast-plugin-py serve my-plugin
# override the port:
owncast-plugin-py serve my-plugin -p 8765
```

</TabItem>
</Tabs>

Beyond static files and your HTTP routes, it exposes dev-only endpoints to drive the handlers a plain HTTP server can't reach. Host reads (server info, video config, and so on) return sample dev data.

- `POST /_dev/chat` with `{"user":"alice","body":"hi"}`: runs your chat-message filter chain, then fires `chat.message.received`. The JSON response shows what your filter did.
- `GET /_dev/chat`: the chat log so far, including anything your plugin posted.
- `POST /_dev/event` with `{"type":"stream.started","payload":{}}`: dispatch an arbitrary event to your handlers.

Restart the dev server when you change your code. Use scenario tests for repeatable assertions. The dev server is for interactive iteration. Many authors run both: dev server in one terminal, test watcher in another.

---

## Contributing web UI with Plugins

Plugins can add their own UI to Owncast in two places: tabs inside the admin (for streamer-facing settings) and action buttons under the stream (for viewer-facing actions). Both are declared in your manifest and managed by the host. You ship the content, Owncast slots it into the right chrome.

Manifest declarations on this page are plain JSON, identical whatever language you write in. Dynamic-content handlers and runtime calls are shown for both SDKs. See [JavaScript](/docs/plugins/sdks/javascript) or [Python](/docs/plugins/sdks/python) for install and setup.

## Admin pages

:::tip[Just need a settings form?]
For flat, typed settings (strings, numbers, switches), declare a manifest `config` block and let Owncast render the form for you. See [Configuration](/docs/plugins/configuration). Build a custom admin page when you need a UI the auto-form can't express.
:::

Plugins can register pages that appear inside the Owncast admin UI under **Plugins**. Declare them as an object keyed by plugin-relative path glob:

```json
{
  "permissions": ["http.serve"],
  "admin": {
    "pages": {
      "/admin": { "title": "Settings", "icon": "gear" }
    }
  }
}
```

Each entry has:

| Part       | Notes                                                                                                                                                                       |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| object key | Required path glob under `/plugins/<your-slug>/`. Examples: `"/admin"`, `"/admin/*"`, `"/admin/api/*"`.                                                                     |
| `title`    | Required tab label inside the plugin's admin view.                                                                                                                          |
| `icon`     | Optional short semantic name. Supported: `gear`, `wrench`, `user`, `users`, `lock`, `info`, `apps`, `docs`, `bell` (aliases like `settings` and `notifications` also work). |

The host derives the page path from the object key. Do not add a `path` member to the value. The host rejects arrays and page values containing the legacy `path` member.

### How they're rendered

Owncast's admin renders each declared page as a tab inside `/admin/plugins/configure?id=<your-slug>`. The tab body is an `<iframe>` pointed at the path from the object key under `/plugins/<your-slug>/`. Each plugin gets a bookmarkable URL and a sidebar entry under **Plugins** in the admin navigation.

The host auto-injects the baseline stylesheet into HTML responses on admin paths, so plain `<input>` and `<button>` controls look native to Owncast's admin without you needing to ship CSS. See [Styling plugin UI](#styling-plugin-ui) for what you get for free and the helper classes available. Plugins that prefer their own styling can layer on top.

### Sandbox

The page runs in a sandboxed `<iframe>`. Your scripts run, forms submit, and same-origin `fetch` to your own `/plugins/<your-slug>/` endpoints works. Pages may also **open popups**, **trigger file downloads** (e.g. a blob or data-URL `` you click from script), and use **`confirm()` / `alert()` / `prompt()`** dialogs. The sandbox is the only constraint you'll usually notice. If a browser feature seems silently blocked, the iframe sandbox is the first thing to check.

### Auth gating

Requests to manifest-declared admin paths are auth-gated by the host. Unauthenticated requests get a `401` before your plugin code runs. You don't have to check the request's authentication for these paths.

Static files and dynamic endpoints under matched paths are both auth-gated. The same gating applies to your `public/admin/index.html` and to `POST /admin/api/save-settings`.

Use multiple globs when you have both a UI page and a JSON API:

```json
{
  "admin": {
    "pages": {
      "/admin": { "title": "Settings" },
      "/admin/*": { "title": "Settings" }
    }
  }
}
```

The admin UI deduplicates tabs by the resolved iframe URL, not by title. `/admin` and `/admin/*` both resolve to `/admin/`, so this pair produces one visible tab that gates the whole subtree. A pair like `/admin` and `/admin/api/*` resolves to two different URLs and produces two tabs. JSON object order is not significant. Owncast processes and displays pages in lexicographic path order.

### Author flow

1. Put admin HTML, CSS, and JS in `public/admin/index.html` (and friends).
2. Expose admin APIs via your request handler at `/admin/api/...` (see [Serving HTTP](/docs/plugins/http)).
3. Declare the relevant path keys in `manifest.admin.pages`.
4. Visit `/admin/plugins/configure?id=<your-slug>` in the admin UI. Owncast uses your existing admin login to gate the page. No extra prompt.

## Action buttons

Owncast surfaces a row of action buttons in its viewer UI. Clickable entries that either open a URL (in a modal or new tab) or render raw HTML. Plugins can contribute their own.

### Manifest-declared buttons

```json
{
  "permissions": ["ui.modify", "http.serve"],
  "actions": [
    {
      "title": "Chat Overlay",
      "description": "Open the live chat overlay",
      "url": "/",
      "icon": "/star.png",
      "color": "#3b82f6"
    },
    {
      "title": "Issue tracker",
      "url": "https://github.com/example/my-plugin/issues",
      "openExternally": true
    },
    {
      "title": "About this stream",
      "html": "Live every weekday at 8pm UTC."
    }
  ]
}
```

While your plugin is enabled, the host merges its action entries into the list Owncast already shows under the stream. When disabled, they disappear.

### Field reference

| Field            | Notes                                                                           |
| ---------------- | ------------------------------------------------------------------------------- |
| `title`          | Required. The button label.                                                     |
| `url`            | Either an absolute `https://...` URL or a path. Mutually exclusive with `html`. |
| `html`           | Raw HTML rendered in an inline modal. Mutually exclusive with `url`.            |
| `icon`           | Optional image URL shown on the button. Same path rules as `url`.               |
| `color`          | Optional hex color for the button background.                                   |
| `description`    | Optional. Shown in the modal that opens for URL-based actions.                  |
| `openExternally` | If `true`, the URL opens in a new tab instead of an inline modal.               |

### Path rules

Two simple rules cover everything:

- Relative paths auto-prefix to your plugin's namespace. `"/"` becomes `/plugins/my-plugin/`. `"/star.png"` becomes `/plugins/my-plugin/star.png`. This saves you from hard-coding your plugin name. Applies to both `url` and `icon`.
- Absolute `https://...` URLs pass through unchanged. Use these for external links and CDN-hosted icons.

The host enforces:

- `ui.modify` permission is required. Manifests with `actions` but no `ui.modify` are rejected at load.
- Exactly one of `url` or `html` per entry.
- URLs and icons that resolve into your namespace require `http.serve`. You're the one serving them.
- URLs and icons pointing at another plugin's namespace are rejected. Catches typos and prevents one plugin from advertising another's UI.

### Runtime additions

A plugin can append more action buttons at runtime, without a reload, by calling `owncast.actions.add(...)` with a single action or an array of them. Each runtime entry goes through the same validation as `manifest.actions`, and is persisted in the plugin's config, so additions survive a reload. `owncast.actions.clear()` drops every runtime addition. Manifest-declared actions remain.

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

```js
const { definePlugin, owncast } = require('@owncast/plugin-sdk');

module.exports = definePlugin({
  onStreamStarted() {
    owncast.actions.add({
      title: 'Donate',
      url: 'https://example.com/donate',
      openExternally: true,
    });
    // or add several at once: owncast.actions.add([ { ... }, { ... } ])
  },
});
```

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

```python
from owncast_plugin import plugin, owncast

@plugin.on_stream_started
def add_button(info):
    owncast.actions.add({
        "title": "Donate",
        "url": "https://example.com/donate",
        "openExternally": True,
    })
    # or add several at once: owncast.actions.add([ { ... }, { ... } ])
```

</TabItem>
</Tabs>

A common pattern is an admin page that lets the streamer add custom buttons (label + URL) on top of the plugin's defaults. The `action-buttons` example in the SDK ships a working version of this.

## Styling plugin UI

Owncast injects a baseline stylesheet into every plugin surface that renders in an iframe: your **admin pages** and your **viewer-page tabs**. It's built from Owncast's own design tokens, so plain semantic HTML adopts the native look with no CSS of your own.

- Headings, paragraphs, and links pick up the theme fonts and colors.
- `<input>`, `<textarea>`, `<select>`, and `<button>` render like the native controls. A `<button>` gets the primary style. Add `class="secondary"` for the outline variant.
- ``, `<fieldset>`, and `<code>` / `<pre>` get sensible native styling.

Your content sits **flush on the page**. The iframe background is transparent so the host's panel shows through, the same way the built-in About and Followers tabs render. You don't get, and shouldn't add, an opaque page background or a wrapping box around everything. That flush rendering is what makes a plugin tab read as part of Owncast rather than an embedded frame.

:::info[Where it applies]
The baseline styles the iframe-rendered surfaces: [admin pages](#admin-pages) and [viewer-page tabs](#viewer-page-tabs). Content you inject straight into the viewer page (`extraPageContent`, `scripts`) renders in the real page DOM and inherits Owncast's actual styles instead.
:::

### Helper classes

For native building blocks beyond plain elements, the baseline ships a few opt-in classes. They reference the same theme tokens as the rest of Owncast, so they restyle automatically when an admin customizes the theme.

| Class              | What it does                                                                                                                                                                                    |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `card`             | A native card surface, the same look as the followers and featured-streams cards. A plain `<section>` / `<article>` stays flush, so opt in with `class="card"` when you want the boxed surface. |
| `card interactive` | Add `interactive` to a clickable card for the native hover lift.                                                                                                                                |
| `card-grid`        | A responsive grid that fills as many ~260px columns as fit and collapses to one column on a narrow frame. Drop `card` children straight in.                                                     |
| `tag`              | A pill tag or badge, matching the tags on the native stream cards.                                                                                                                              |
| `stack`            | A vertical flex column with a consistent gap.                                                                                                                                                   |
| `row`              | A horizontal flex row that wraps, with a consistent gap.                                                                                                                                        |
| `muted`            | De-emphasized text, for captions and secondary detail.                                                                                                                                          |

```html

  <article class="card interactive">
    Album A
    Artist A
    
      jazz
      2024
    
  </article>
  <article class="card interactive">
    Album B
    Artist B
  </article>

```

Everything here is opt-in. A tab that ships nothing but semantic HTML already looks native. Reach for the helpers when you want cards, grids, or tags without hand-copying Owncast's values, and layer your own CSS on top (see [Viewer stylesheets](#viewer-stylesheets)) whenever you need something the baseline doesn't cover.

## Viewer stylesheets

Plugins can theme the viewer page by bundling CSS files and listing them in `manifest.styles`. The host inlines each file's contents into a single plugin styles block on the page, so plugins extend the page's CSS without each contribution needing its own `<link>` tag.

```json
{
  "permissions": ["ui.modify"],
  "styles": ["theme.css", "overrides.css"]
}
```

Requires `ui.modify` only (the plugin paints inside Owncast's chrome). `http.serve` isn't needed: the host reads each file from your plugin's `assets/` directory and inlines the bytes into the page's plugin styles block on `/api/config`, not at a URL.

### Path rules

- Bare paths like `"theme.css"` auto-prefix to your plugin's namespace.
- `"/theme.css"` resolves the same way.
- Fully qualified `/plugins/<your-slug>/...` paths pass through.
- Paths in another plugin's namespace are rejected.
- `http://` and `https://` URLs are rejected. Bundle external assets and reference them with `@font-face` or `url(...)` from inside your CSS instead, so an admin reviewing the manifest sees every file that will load.
- Each entry must end in `.css`.

### How contributions are rendered

The host reads each file at request time and concatenates the bytes in front of an `/* plugin: <your-slug> ... */` comment, so devtools "view source" attributes a rule back to the plugin that shipped it. Disabling the plugin drops its contribution on the next page load.

The CSS body runs against the live viewer DOM, so your selectors target whatever the page renders. Scoping every rule under a single root id is a defensive habit worth keeping. Without it your rules can match elements the host page renders and produce surprising regressions.

### Where plugin styles sit in the cascade

The viewer page builds its appearance from four layers, applied in this order. Later layers win.

1. Owncast's built-in defaults.
2. Plugin styles: your `manifest.styles` files first, then your `onPageStyles` output.
3. The admin's appearance variables, the colors set with the pickers under **General Settings → Appearance**.
4. The admin's custom CSS, the editor on that same page.

Your styles are layer 2, so the admin's explicit choices in layers 3 and 4 override yours on any property you both set. Treat a theme as a baseline rather than the final word:

- A token you set that the admin left at its default shows your value.
- A token you set that the admin also set shows the admin's value.

Both partial and full themes are fine. A plugin that only recolors links leaves every other color untouched. A plugin that sets the whole palette still yields to any individual color the admin picked. The admin stays in control of their own instance, and the Appearance page tells them a plugin is involved: it shows a notice naming your plugin and flags each color you set with an `also set by <plugin>` note. For that flagging to work, declare your colors as `--theme-color-*` custom properties in a `:root { ... }` block, the same form the admin's pickers write.

One escape hatch breaks the ordering: a plugin rule marked `!important` beats the admin's normal declarations regardless of layer. Avoid it in theme CSS if you want the admin to keep the final say over their colors.

### Caveat: relative URLs in CSS

`url(...)` references inside a plugin's CSS resolve against the viewer page, not against the plugin's namespace. If you want to reference a bundled image, use the absolute path `/plugins/<your-slug>/logo.png` instead of `./logo.png`. Same goes for `@font-face` sources. The plugin's static URL space stays served, so direct references work even though no `<link>` points at the file.

### Dynamic stylesheets: `onPageStyles`

When the CSS depends on plugin state, a theme the admin picked or a value in the KV store, return it from an `onPageStyles` handler instead of (or alongside) a static file. There is no manifest field for it. The host calls the handler once per `/api/config` for any plugin that holds `ui.modify` and exports it, then appends what it returns to your plugin styles block after the static `manifest.styles` files. Within your plugin's own styles the later rule wins, so returning only the active override from `onPageStyles` is enough. The whole block still sits below the admin's appearance settings (see [where plugin styles sit in the cascade](#where-plugin-styles-sit-in-the-cascade)).

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

```js
const ACCENTS = { ocean: '#2386e2', forest: '#42bea6' };

module.exports = definePlugin({
  onPageStyles() {
    const accent = ACCENTS[owncast.kv.get('theme')];
    if (!accent) return;
    return `:root { --theme-color-action: ${accent}; }`;
  },
});
```

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

```python
ACCENTS = {"ocean": "#2386e2", "forest": "#42bea6"}

@plugin.on_page_styles
def page_styles():
    accent = ACCENTS.get(owncast.kv.get("theme"))
    if not accent:
        return
    return f":root {{ --theme-color-action: {accent}; }}"
```

</TabItem>
</Tabs>

Requires `ui.modify`. The examples above also read the KV store, which separately requires `storage.kv`. Return nothing (a bare `return`, the same as returning `""`) when there is nothing to contribute on a given request. The call takes no per-viewer argument, so the `/api/config` response stays cacheable. The `theme-hub` example in the SDK uses this to apply an admin-selected theme to the whole viewer UI.

## Viewer scripts

Plugins can extend the viewer page's runtime by bundling JavaScript files and listing them in `manifest.scripts`. Each file's contents are appended to the `/customjavascript` response Owncast already serves for the admin's custom JS, so plugins extend the page's behavior without each contribution needing its own `<script>` tag.

```json
{
  "permissions": ["ui.modify"],
  "scripts": ["client.js"]
}
```

Same permission and path rules as `styles`, applied to `.js` files (only `ui.modify` is needed, and the host reads from `assets/` and inlines into `/customjavascript`). Each contribution is prefixed with a `// plugin: <your-slug> ...` comment.

These are **viewer-page** scripts that run in the browser, always JavaScript, regardless of which language you wrote the server-side plugin in.

### Execution context

The viewer page loads `/customjavascript` as a single `<script async>` tag. Every plugin's JS runs in the same global window as the admin's custom JS and the rest of Owncast's chrome. Three implications:

- Top-level `var` and `function` declarations land on `window`. Wrap your script in an IIFE (`(function(){ ... })()`) so private state stays private and you don't collide with the admin's JS or other plugins.
- The host wraps each plugin's contribution in its own try/catch, so a runtime error throws to the browser console (prefixed `owncast plugin <your-slug> script error:`) without stopping the other plugins' scripts. A syntax error is not isolated: it breaks parsing of the one concatenated script tag before any try/catch runs, so ship valid JavaScript.
- Relative `fetch('./data.json')` resolves against the viewer page's URL, not against your plugin. Use absolute paths like `/plugins/<your-slug>/data.json` for files you ship in `public/`.

### Dynamic scripts: `onPageScripts`

The script counterpart to `onPageStyles`. Return JavaScript computed at request time from an `onPageScripts` handler, with no manifest field. The host calls it once per `/api/config` for any plugin holding `ui.modify` that exports it, and appends the result to `/customjavascript` after the static `manifest.scripts` files, wrapped in the same per-plugin try/catch.

This is for any request-time JavaScript, not only theming. Use it to run viewer-side code computed per request, for example surfacing a value the admin set in the plugin's KV store. The example below shows that value to viewers:

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

```js
module.exports = definePlugin({
  // Run request-time JavaScript on the viewer page.
  onPageScripts() {
    const notice = owncast.kv.get('notice');
    if (!notice) return;
    return `alert(${JSON.stringify(notice)});`;
  },
});
```

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

```python

@plugin.on_page_scripts
def page_scripts():
    notice = owncast.kv.get("notice")
    if not notice:
        return
    return f"alert({json.dumps(notice)});"
```

</TabItem>
</Tabs>

The output runs in the shared viewer `window`, so the IIFE and absolute-path advice above still applies. Escape any untrusted strings you embed: `JSON.stringify` in JavaScript and `json.dumps` in Python both produce a safely-quoted literal, which is why the examples wrap the notice in one before passing it to `alert`. Like the styles examples, reading the KV store requires `storage.kv` on top of `ui.modify`. Return nothing (a bare `return`, the same as returning `""`) to contribute nothing.

### When to use it

`scripts` is the right tool for plugins that need to react to viewer-side state, mount their own UI on top of the page, or talk to a backend the plugin runs at `/plugins/<your-slug>/`. For chat-driven bots, message filters, and any logic that should run server-side, the regular plugin handlers are a better fit. They run inside the host sandbox, can speak to Owncast APIs the viewer page can't reach, and don't trust user-controlled DOM.

## Extra page content

Plugins can prepend HTML to the viewer page's extra-content block. Declare `manifest.extraPageContent` as an object with a required `slug` and an optional `content` path:

```json
{
  "permissions": ["ui.modify"],
  "extraPageContent": { "slug": "banner", "content": "content.html" }
}
```

| Field     | Notes                                                                                                                                                                             |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `slug`    | Required. A stable identifier passed to the page-content handler when the host asks for rendered HTML. Lowercase letters, digits, and hyphens, starting with a letter.            |
| `content` | Optional. Relative path to a static HTML file in `assets/`. When present, that file's bytes are inlined directly. When omitted, the host calls your page-content handler instead. |

### Static vs dynamic

Use `content` when the HTML is the same for every viewer: announcement strips, sponsor banners, blocks of prose. Leave `content` out and implement a **page-content handler** when the content should change per viewer or draw on live data. The host calls the handler with the requested `slug` and the viewer's identity, and your handler returns the HTML string to render:

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

```js
module.exports = definePlugin({
  onPageContent(ctx) {
    if (ctx.slug === 'banner') {
      const who = ctx.user ? `, ${ctx.user.displayName}` : '';
      return `Welcome${who}!`;
    }
    return '';
  },
});
```

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

```python
@plugin.on_page_content("banner")
def banner(ctx):
    name = ctx.user.display_name if ctx.user else None
    who = f", {name}" if name else ""
    return f'Welcome{who}!'
```

</TabItem>
</Tabs>

See [Handlers: page content](/docs/plugins/events#page-content) for the payload shape. The viewer identity is present when the viewer is authenticated and absent for anonymous viewers.

Requires `ui.modify`. `http.serve` is not required: the HTML is inlined into the `/api/config` response, not served as a URL.

The bytes land at the top of the extra-content block, above any prose the admin has configured. Each contribution is wrapped with an `<!-- plugin: <your-slug> ... -->` comment for attribution. Multiple plugins' contributions stack in the order the host loaded them.

### Path rules

Same as `styles` and `scripts`, applied to a single `.html` entry. One file per plugin. If you want several distinct blocks, link or `<iframe>` them from the one file you ship.

### Markdown vs HTML

The admin's extra page content goes through Owncast's markdown processor before rendering. Plugin HTML does not: the host runs the markdown processor on the admin's content first, then prepends your raw bytes. Tags, attributes, and inline scripts pass through as written.

This means plugin HTML can use any element the viewer page accepts. It also means a malformed tag can break the surrounding chrome, so escape any untrusted strings you embed (user names, fetched text, anything not in your control).

### Pairing with `scripts`

`extraPageContent` shines when paired with `scripts`: ship the markup as HTML where it's reviewable at a glance, and wire interactions from your JavaScript by querying the elements you declared. The host loads the HTML before the script runs, so a script targeting `document.getElementById(...)` on a plugin-contributed element works without timing tricks.

```json
{
  "permissions": ["ui.modify", "http.serve"],
  "extraPageContent": { "slug": "panel", "content": "panel.html" },
  "scripts": ["panel.js"]
}
```

A pattern that often reads cleaner than building the same DOM imperatively from a `scripts`-only plugin:

- `panel.html` declares structure, classes, and IDs you can reason about as plain HTML.
- `panel.css` (declared in `styles`) themes it.
- `panel.js` attaches event listeners, fetches data, mutates state.

When to reach for HTML-plus-JS instead of pure JavaScript: anything with non-trivial layout, ARIA attributes, or third-party widgets that expect to bootstrap from existing DOM. Pure `scripts` still makes sense for plugins that build their UI only on certain conditions (after a fetch, after a user action) where rendering nothing on initial paint is the right behavior.

### When `extraPageContent` is enough on its own

Standalone, `extraPageContent` is the simplest path for announcement strips, sponsor banners, and any block that doesn't need to react to events: it ships markup directly, doesn't require a script, and survives a JavaScript-disabled viewer.

## Viewer-page tabs

Plugins can add tabs to the viewer page's tab row next to the built-in **About** and **Followers** tabs by declaring `manifest.tabs` as an object. Each object key is the tab's stable slug. Every value requires a `title`, and `content` is optional.

```json
{
  "permissions": ["ui.modify"],
  "tabs": {
    "music": { "title": "Music", "content": "music.html" },
    "stream-info": { "title": "Stream Info" }
  }
}
```

| Part       | Notes                                                                                                                                                                           |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| object key | Required stable slug passed to the tab-content handler. Lowercase letters, digits, and hyphens, starting with a letter.                                                         |
| `title`    | Required. The label shown on the tab. Must be unique within the plugin's tabs.                                                                                                  |
| `content`  | Optional. Relative path to a static HTML file in `assets/`. When present, that file's bytes are inlined directly. When omitted, the host calls the tab-content handler instead. |

The host derives the tab slug from the object key. Do not add a `slug` member to the value. The host rejects arrays and tab values containing the legacy `slug` member.

Requires `ui.modify`. `http.serve` is not required: each static tab's HTML is read from `assets/` and inlined into the tab body. For a dynamic tab, the host passes the object key to the tab-content handler as `slug` and inlines the returned HTML.

### How tabs are rendered

The host emits a `pluginTabs[]` array on `/api/config`. The viewer page maps each entry to a tab whose body is the inlined HTML, rendered in a sandboxed iframe with the baseline stylesheet injected, so plain HTML looks native with no CSS of your own.

See [Styling plugin UI](#styling-plugin-ui) for the baseline and the helper classes. Tabs from each
plugin are appended after the built-ins in lexicographic slug order. Ordering between tabs from
different plugins is unspecified. JSON object order is not significant. The React key combines the
tab slug and title, so changing either value remounts that tab.

### The tab object key

The object key is a stable name you control. The host passes it to your tab-content handler as `slug`, so one handler can serve multiple tabs without guessing which one was requested. It also appears in host logs and future API calls, so pick something clear, like `"music"` or `"stream-info"`. You can change `title` freely unless your code depends on it. Changing the key is a breaking change if code depends on the existing slug.

### Dynamic tab content

When a tab value has no `content` file, the host calls your **tab-content handler** to produce it. Implement it when content should change per viewer or pull live data. The host resolves every dynamic tab while building the viewer's `/api/config` payload, once per config request rather than on tab click, so keep the handler fast. It passes the tab's object key as `slug` with the viewer's identity, and expects the HTML string for the tab body:

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

```js
module.exports = definePlugin({
  onTabContent(ctx) {
    // ctx = { slug, user? }
    if (ctx.slug === 'stream-info') {
      return 'Stream infoLive every weekday at 8pm UTC.';
    }
    return '';
  },
});
```

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

```python
@plugin.on_tab_content("stream-info")
def stream_info(ctx):
    return "Stream infoLive every weekday at 8pm UTC."
```

</TabItem>
</Tabs>

See [Handlers: tab content](/docs/plugins/events#tab-content) for the payload shape. The viewer identity is present when authenticated and absent for anonymous viewers.

### Path rules

Same as `extraPageContent`, applied per entry:

- Bare paths like `"music.html"` auto-prefix to your plugin's namespace.
- Fully qualified `/plugins/<your-slug>/...` paths pass through.
- Paths in another plugin's namespace are rejected.
- `http(s)://` URLs are rejected.
- Each entry must end in `.html`.

### Tab title

The `title` field shows up verbatim in the tab bar. Keep it short: long titles get truncated by the tab UI. There's no schema constraint on length, but anything past ~16 characters won't fit cleanly on mobile.

### When to use tabs vs `extraPageContent`

- `extraPageContent`: one block of HTML that sits above the tab row. Good for announcement strips, sponsor banners, anything that should always be visible.
- `tabs`: dedicated panels the viewer clicks into. Good for content that doesn't need to compete with chat for attention: music lists, event schedules, link pages, sponsor sections you want viewers to find but not necessarily see first.

---

## What You Need to Run Owncast

It is impossible to give a single answer about what the requirements are for you to run Owncast, or what it will cost. It is your server, and it is completely up to you how you choose to configure it, and in what environments you choose to run it. Every environment has different performance, prices and features.

---

## Base knowledge

It is very helpful for you to understand the basics included in video streaming.

- **CPU**: Used to transcode the video to multiple qualities so viewers can watch it on different speed networks.
- **Network bandwidth**: Used to distribute the video to your viewers.

### Viewer count does not impact CPU use

Knowing this, you see that **CPU usage is the same regardless of how many viewers you have**. 0 or 100, the CPU is still performing the work. Think of it like creating a zip file. If you have a 100MB file, and you zip it, and it becomes 70MB, you can send that 70MB file to as many people as you want without zipping that file again for each person. But you still need to send the file to each person seperately, requiring network bandwidth for each time you send it. However, if you want to send some people a 70MB version and others a 50MB version, you'll need to create two seperate files. That 50MB version will take longer and use more CPU to create, because of the additional work it takes to compress the file more. This is the same with video. The more work required to encode your video, the more CPU that's required. Generally, the more you need to reduce the size and bitrate of your video, the more CPU that will be used. But offering low bitrate/lower quality versions of your stream is important to enable more viewers to watch it from across the world, on any kind of network.

### Your upload bandwidth as a streamer

Before your server can distribute video to viewers, you need to send your stream to the server. This requires **upload bandwidth** from wherever you're broadcasting. If you're streaming at 5000kbps, you need an upload speed that can reliably sustain that rate.

**Rule of thumb**: Your upload speed should be at least **1.5x your streaming bitrate** to account for fluctuations and overhead. For a 5000kbps stream, aim for at least 7.5 Mbps upload.

| Streaming Bitrate | Minimum Upload Speed |
| ----------------- | -------------------- |
| 2500 kbps         | 4 Mbps               |
| 4000 kbps         | 6 Mbps               |
| 5000 kbps         | 7.5 Mbps             |
| 6000 kbps         | 9 Mbps               |
| 8000 kbps         | 12 Mbps              |

**Important considerations:**

- **Home internet is often asymmetric**: Most residential connections have much faster download than upload speeds. A "100 Mbps" plan might only have 10-20 Mbps upload. Check your actual upload speed at [speedtest.net](https://www.speedtest.net/) or similar.
- **Shared connections**: If others on your network are using bandwidth while you stream, your available upload decreases.
- **Use a wired connection**: WiFi adds latency and instability. A wired ethernet connection to your router is strongly recommended for streaming.
- **This is separate from server bandwidth**: Your upload gets the stream to the server. The server then needs its own bandwidth to distribute to viewers.

## Example Scenario

Now that you understand the basics, let's use an example to illustrate how your configuration can impact your server's resources, and most importantly, your viewers' experience. It's a little simplistic and the actual numbers can vary in real life, but it could help answer the question of "approximately how much bandwidth and CPU will Owncast use?"

You've configured your broadcasting source (such as OBS) to stream to your Owncast instance at **5000kbps**. You have **25 viewers**. **5** of them are on slow or mobile networks, **17** of them have fast, stable internet, and **3** of them have fast internet most of the time but the speed fluctuates. All 25 viewers watched an entire stream that lasts two hours. You have a hosting provider that gives you 4TB of bandwidth per month.

### Offer a high and low quality option

You decide to offer both a high and low quality option, and you set the high quality option to 5000kbps and the low quality option to 1500kbps.

**How much bandwidth is used on your server for this stream?**

| Bitrate                                   | Duration     | Viewers | Total                      |
| ----------------------------------------- | ------------ | ------- | -------------------------- |
| 0.000625 Gigabytes per second (5000kbps)  | 7200 seconds | 20      | 90 Gigabytes               |
| 0.0001875 Gigabytes per second (1500kbps) | 7200 seconds | 5       | 6.75 Gigabytes             |
|                                           |              |         | **Total**: 96.75 Gigabytes |

**What peak network speed does your server need?**

Your server must be able to sustain the combined outbound bitrate to all viewers at the same time. In this scenario: (20 viewers × 5000kbps) + (5 viewers × 1500kbps) = **107.5 Mbps**. Your hosting plan needs to support at least this much outbound throughput.

**How much CPU?**

| Quality  | CPU Usage                                    |
| -------- | -------------------------------------------- |
| 5000kbps | Light (minimal transcoding, matches input)   |
| 1500kbps | Moderate (active encoding to reduce bitrate) |

**How is the viewer experience?**

| Quality  | Viewers | Experience |
| -------- | ------- | ---------- |
| 5000kbps | 20      | Good       |
| 1500kbps | 5       | Good       |

**Result**: You've provided both a high and low quality option for your viewers so those with a slow network have an option, and those with a fast network that might periodically slow down can dip down into the low quality when needed. Additionally, in this case you saved nearly 16G of bandwidth traffic due to offering a lower quality. You're using more CPU for a much better experience. You would be able to stream 42 times in a month before you hit your bandwidth limit.

### Offer a single high quality option using the least amount of CPU

You've decided you want to use as little CPU on your Owncast server as possible so you enable "Video Passthrough" mode as the only output available. This means the exact video you're sending from your local broadcasting software is what is sent to your viewers.

**How much bandwidth is used on your server for this stream?**

| Bitrate                                  | Duration     | Viewers | Total           |
| ---------------------------------------- | ------------ | ------- | --------------- |
| 0.000625 Gigabytes per second (5000kbps) | 7200 seconds | 25      | 112.5 Gigabytes |

**What peak network speed does your server need?**

All 25 viewers are receiving the same 5000kbps stream: 25 × 5000kbps = **125 Mbps** of sustained outbound throughput.

**How much CPU?**

| Quality  | CPU Usage                |
| -------- | ------------------------ |
| 5000kbps | Minimal (no transcoding) |

**How is the viewer experience?**

| Quality  | Viewers | Experience  |
| -------- | ------- | ----------- |
| 5000kbps | 17      | Good        |
| 5000kbps | 3       | Bad         |
| 5000kbps | 5       | Unwatchable |

**Result**: You're not using much CPU, but only **68%** of your viewers are having a good experience. The other **32%** are having a bad experience with frequent buffering, and **20%** of them cannot watch your stream at all. You would be able to stream 36 times in a month before you hit your bandwidth limit.

### Use a S3 compatible storage provider for bandwidth

If you have concerns about your hosting plan, bandwidth allocation or viewership growth you can use a S3 storage provider instead of your server for bandwidth responsibilities. In this example you again decide to offer both a high and low quality option, and you set the high quality option to 5000kbps and the low quality option to 1500kbps. The CPU used is the same as the above example for the high+low quality option. Learn more about [S3 compatible storage](/docs/storage).

**How much bandwidth is used on your server for this stream?**

| Bitrate                                   | Duration     | Total                     |
| ----------------------------------------- | ------------ | ------------------------- |
| 0.000625 Gigabytes per second (5000kbps)  | 7200 seconds | 4.5 Gigabytes             |
| 0.0001875 Gigabytes per second (1500kbps) | 7200 seconds | 1.35 Gigabytes            |
|                                           |              | **Total**: 5.85 Gigabytes |

**How much outbound bandwidth is used on your S3 provider for this stream?**

| Bitrate                                   | Duration     | Viewers | Total                      |
| ----------------------------------------- | ------------ | ------- | -------------------------- |
| 0.000625 Gigabytes per second (5000kbps)  | 7200 seconds | 20      | 90 Gigabytes               |
| 0.0001875 Gigabytes per second (1500kbps) | 7200 seconds | 5       | 6.75 Gigabytes             |
|                                           |              |         | **Total**: 96.75 Gigabytes |

**What peak network speed does your server need?**

Since viewers are served from S3, your server doesn't send video to viewers at all. It only needs enough outbound bandwidth to upload one copy of each quality stream to S3: 5000kbps + 1500kbps = 6500kbps = **6.5 Mbps**. This stays the same whether you have 0 viewers or 1,000. Your S3 provider handles the viewer-facing throughput, which in this scenario peaks at **107.5 Mbps**, but that is their infrastructure, not yours.

**Result**: You've provided both a high and low quality option for your viewers so those with a slow network have an option, and those with a fast network that might periodically slow down can dip down into the low quality when needed. However, these video qualities are not being served from your Owncast server, but instead an external S3 compatible storage provider. This allows for increasing your viewership and adding additional video qualities without concern of you exhausting your server's bandwidth allocation. You would be able to stream 24/7 without worry using this configuration, however you'd be using the same amount of your server bandwidth if you had zero viewers or 100 viewers. Your CPU usage would be the same as if you were serving the video directly from your server.

## Quick Reference

### How much bandwidth will Owncast use?

**Formula**: `(bitrate in kbps × duration in seconds × viewers) ÷ 8,000,000 = GB`

**Quick estimates for a 2-hour stream:**

| Bitrate  | 10 viewers | 25 viewers | 50 viewers |
| -------- | ---------- | ---------- | ---------- |
| 2000kbps | 18 GB      | 45 GB      | 90 GB      |
| 4000kbps | 36 GB      | 90 GB      | 180 GB     |
| 6000kbps | 54 GB      | 135 GB     | 270 GB     |

Offering multiple quality options reduces total bandwidth because viewers on slower connections use the lower bitrate stream. Using [S3-compatible storage](/docs/storage) offloads bandwidth from your server entirely.

### What peak network speed does my server need?

**Formula**: `bitrate in kbps × viewers ÷ 1,000 = Mbps`

**Quick estimates:**

| Bitrate  | 10 viewers | 25 viewers | 50 viewers |
| -------- | ---------- | ---------- | ---------- |
| 2000kbps | 20 Mbps    | 50 Mbps    | 100 Mbps   |
| 4000kbps | 40 Mbps    | 100 Mbps   | 200 Mbps   |
| 6000kbps | 60 Mbps    | 150 Mbps   | 300 Mbps   |

This is the sustained outbound throughput your server needs during a stream. If you offer multiple quality options, calculate each quality separately and add them together. Most VPS providers offer 1 Gbps ports, which supports roughly 200 viewers at 5000kbps. If your viewers exceed your server's network capacity, they will experience buffering. Using [S3-compatible storage](/docs/storage) eliminates this limit from your server.

### How much CPU will Owncast use?

These are rough examples from measured tests, not guarantees. Actual CPU use varies by codec, bitrate, resolution and encoder preset.

| Configuration                        | CPU Usage |
| ------------------------------------ | --------- |
| Single passthrough quality           | Minimal   |
| Single transcoded quality            | Light     |
| Two qualities (high + low)           | Moderate  |
| Three qualities or heavy compression | Heavy     |

As a rough rule of thumb from measured examples, a single CPU core can often handle one transcoded output quality at 30fps, but this varies with codec, bitrate, resolution and encoder preset. Passthrough mode (no transcoding) uses very little CPU regardless of bitrate. All CPUs are different in performance across hardware and hosting providers, so no guarantee can ever be made. You will need to experiment to find out what works best for your needs.

### Does CPU usage increase with more viewers?

No. For video encoding, CPU usage stays constant whether you have 1 viewer or 1,000. The video is encoded once and distributed to all viewers. Only server bandwidth increases with viewer count. CPU usage can grow slightly with more viewers due to chat activity and other overhead, but this is minimal compared to video encoding.

### How does frame rate affect CPU usage?

Higher frame rates require more CPU. Reducing frame rate is an effective way to lower CPU usage. These multipliers are rough measured examples and will vary by codec, bitrate, resolution and encoder preset:

| Frame Rate | Relative CPU |
| ---------- | ------------ |
| 60 fps     | 2x baseline  |
| 30 fps     | 1x baseline  |
| 24 fps     | 0.8x         |

Consider using lower frame rates (24fps) for lower quality outputs to save CPU while maintaining smooth playback for viewers on slow connections.

### How much disk space will Owncast use?

Live video needs very little disk space. Owncast writes HLS video segments to disk temporarily and cleans them up as the stream progresses, so you don't need to plan for video storage.

The `data/` directory does persist and grow over time. It holds the Owncast database and its hourly backups, custom emoji, public files, viewer metrics, GeoIP data and, starting with Owncast 0.3.0, installed plugins and their data. Give it room to grow and include it in your [backups](/docs/backups).

### Should I just offer the highest quality to keep things simple?

Offering only high bitrate video excludes viewers on mobile networks and slower connections. A 5000kbps stream requires a stable 5+ Mbps connection to watch without buffering. Many viewers don't have that, especially on mobile.

**Recommendation**: Offering a second, lower quality option (1000-2000kbps) alongside your high quality one (4000-6000kbps) helps viewers on slow or mobile connections. That said, Owncast ships with a single variant by default, and the [video documentation](/docs/video) recommends starting with one variant and testing before adding more. Add a low quality option once your setup works and your CPU has headroom.

## Resources Calculator

Use this interactive calculator to estimate your bandwidth and CPU requirements based on your specific streaming configuration:

<ResourcesCalculator />

## Learn more

Visit the detailed [video documentation](/docs/video) to learn more about how Owncast handles video.

---

## Support Increased Viewer Capacity

## Disclaimer

Owncast works great out of the box as a personal streaming service. The ease of install and all-in-one architecture allows for people to get up and running quickly. The downside of this is it requires a bit more thought around large deployments, as you can't just run more copies of Owncast for scale.

If you are not familiar with the topics below, or you don't feel comfortable with the following steps it's unlikely you should be taking on the additional responsibility of a larger deployment of any service. **Basic system administration experience and understanding of the architecture is generally expected when trying to squeeze additional performance out of anything**, and this might not be for you. Don't feel bad. **Owncast will still work great for you out of the box**, but you might want to acquire some professional help if you need something more than that.

## Video

### Object Storage

<IncludeMarkdown>
  <OwncastObjectStorage />
  <UseStorage />
</IncludeMarkdown>

### Content Delivery Networks (CDNs)

<IncludeMarkdown>
  <OwncastWithCDN />
  <UseCDN />
  <OwncastObjectStorageCDN />
</IncludeMarkdown>

## Chat

When scaling chat you're limited by what your single server will be able to handle as far as open connections. For most people the standard configuration is likely going to suffice. Users have run chat with thousands of concurrent connections, but that is anecdotal experience rather than a tested or guaranteed limit, and results depend on your server's resources.

Owncast will automatically increase the amount of concurrent sockets that your operating system will allow. However, if you still get the `too many open files` error it's because your `ulimit` value is lower than the number of open resources Owncast is trying to to use. You will want to have a more powerful server (cpu, ram) when raising the max limit and handle more chat connections.

You can increase concurrent connections by using the `ulimit` command or editing your system files. [Here is an overview of the different limits and how to change them](https://www.learnitguide.net/2015/07/how-to-increase-ulimit-values-in-linux.html). It's beyond the scope of this documentation to go into detail of what numbers you should use and where to put them.

---

## Default Login Information

The admin interface can be found by navigating to `/admin` on your Owncast server (e.g., `https://owncast.example.com/admin`).

[Configuring your broadcasting software](/docs/broadcasting) to stream to your Owncast server requires you to use the `/live` endpoint along with providing the stream key. (e.g., `rtmp://owncast.example.com/live` with stream key `abc123`). If your software does not allow specifying the stream key separately, you may need to append it to the URL as `rtmp://owncast.example.com/live/abc123`.

## Default credentials

| Default        | Value  |
| -------------- | ------ |
| Admin username | admin  |
| Admin password | abc123 |
| Stream key     | abc123 |

These are the default credentials for logging into the Owncast admin interface and streaming to your Owncast server. It is highly recommended that you change these values immediately after your first login to ensure the security of your server.

## Next steps

1. Point your broadcasting software at your new server using `rtmp://yourserver/live` with your stream key. If your software doesn't have a way to specify a stream key use the url `rtmp://yourserver/live/streamkey` and use your stream key instead.
1. Access your server in your web browser by visiting `http://yourserver:8080`.
1. You can visit the Admin dashboard at `http://yourserver:8080/admin` where you can check visitor and server stats, change your stream key, personalize the content displayed on your page, and more. To log in, use the username `admin` and your admin password (`abc123` by default).

**Note:** Your stream key and admin password both default to `abc123`, but they are separate settings. The stream key is only used by your broadcasting software to publish video. It is not your admin password.

---

## Owncast Basic

```mermaid
flowchart LR
    subgraph Broadcasting
        OBS[OBS / Broadcasting Software]
    end

    subgraph Owncast[Owncast Server]
        direction TB
        RTMP[RTMP Ingest]
        Encoder[Video Encoder]
        WebServer[Web Server]
        RTMP --> Encoder --> WebServer
    end

    subgraph Viewers[Video Clients]
        direction TB
        Browser[Web Browsers]
        Phone[Mobile Phones]
        TV[Smart TVs]
        VLC[VLC / Media Players]
    end

    OBS -->|RTMP Stream| RTMP
    WebServer -->|HLS Video| Browser
    WebServer -->|HLS Video| Phone
    WebServer -->|HLS Video| TV
    WebServer -->|HLS Video| VLC
```

---

## Owncast Cdn

```mermaid
flowchart LR
    subgraph Broadcasting
        OBS[OBS / Broadcasting Software]
    end

    subgraph Owncast[Owncast Server]
        direction TB
        RTMP[RTMP Ingest]
        Encoder[Video Encoder]
        WebServer[Web Server]
        RTMP --> Encoder --> WebServer
    end

    subgraph CDN[CDN Network]
        direction TB
        Edge1[Edge NodeNorth America]
        Edge2[Edge NodeEurope]
        Edge3[Edge NodeAsia]
    end

    subgraph Viewers[Video Clients]
        direction TB
        US[US Viewer]
        EU[EU Viewer]
        AS[Asia Viewer]
    end

    OBS -->|RTMP Stream| RTMP
    WebServer -->|Origin| Edge1
    WebServer -->|Origin| Edge2
    WebServer -->|Origin| Edge3
    Edge1 -->|HLS Video| US
    Edge2 -->|HLS Video| EU
    Edge3 -->|HLS Video| AS
```

---

## Owncast Object Storage Cdn

```mermaid
flowchart LR
    subgraph Broadcasting
        OBS[OBS / Broadcasting Software]
    end

    subgraph Owncast[Owncast Server]
        direction TB
        RTMP[RTMP Ingest]
        Encoder[Video Encoder]
        WebServer[Web Server]
        RTMP --> Encoder
    end

    subgraph Storage[Object Storage]
        S3[Storage Provider]
    end

    subgraph CDN[CDN Network]
        direction TB
        Edge1[Edge NodeNorth America]
        Edge2[Edge NodeEurope]
        Edge3[Edge NodeAsia]
    end

    subgraph Viewers[Video Clients]
        direction TB
        US[US Viewer]
        EU[EU Viewer]
        AS[Asia Viewer]
    end

    OBS -->|RTMP Stream| RTMP
    Encoder -->|Upload HLS Segments| S3
    S3 -->|Origin| Edge1
    S3 -->|Origin| Edge2
    S3 -->|Origin| Edge3
    Edge1 -->|HLS Video| US
    Edge2 -->|HLS Video| EU
    Edge3 -->|HLS Video| AS
```

---

## Owncast Object Storage

```mermaid
flowchart LR
    subgraph Broadcasting
        OBS[OBS / Broadcasting Software]
    end

    subgraph Owncast[Owncast Server]
        direction TB
        RTMP[RTMP Ingest]
        Encoder[Video Encoder]
        WebServer[Web Server]
        RTMP --> Encoder
    end

    subgraph Storage[Object Storage]
        S3[Storage Provider]
    end

    subgraph Viewers[Video Clients]
        direction TB
        Browser[Web Browsers]
        Phone[Mobile Phones]
        TV[Smart TVs]
    end

    OBS -->|RTMP Stream| RTMP
    Encoder -->|Upload HLS Segments| S3
    S3 -->|HLS Video| Browser
    S3 -->|HLS Video| Phone
    S3 -->|HLS Video| TV
```

---

## Owncast With Qualities

```mermaid
flowchart LR
    subgraph Broadcasting
        OBS[OBS / Broadcasting Software]
    end

    subgraph Owncast[Owncast Server]
        direction TB
        RTMP[RTMP Ingest]
        Encoder[Video Encoder]
        High[High Quality1080p @ 5000kbps]
        Medium[Medium Quality720p @ 2500kbps]
        Low[Low Quality480p @ 1000kbps]
        WebServer[Web Server]
        RTMP --> Encoder
        Encoder --> High
        Encoder --> Medium
        Encoder --> Low
        High --> WebServer
        Medium --> WebServer
        Low --> WebServer
    end

    subgraph Viewers
        Desktop[DesktopFast Connection]
        Tablet[TabletWiFi]
        Mobile[MobileCellular]
    end

    OBS -->|RTMP Stream| RTMP
    WebServer -->|HLS| Desktop
    WebServer -->|HLS| Tablet
    WebServer -->|HLS| Mobile
```

---

## Featured Streams

Featured streams let your server show a small directory of other Owncast streams. Visitors get a **Featured** tab on your main page listing the servers you feature, with each one's live or offline status. It gives people somewhere to go when you are not streaming and a way to find related streams.

Featuring is opt-in on both sides. You choose which servers to feature, and the other operator chooses whether to let you feature them. Two servers can feature each other, but each side approves the other independently.

:::new[Featured streams require Owncast v0.3.0]
Featured streams is a brand-new feature in Owncast 0.3.0. If you hit a bug or have a suggestion, please [open an issue](https://github.com/owncast/owncast/issues) or [chat live with the community](/chat?tab=community).
:::

## Before you start

Featured streams runs over the same federation that powers Owncast's [social features](./index.mdx), so:

- [Social features must be enabled](./index.mdx#enabling-social-features) on both your server and the one you want to feature.
- The other server must also be Owncast, on a recent enough version to support featured streams.
- It must be reachable over HTTPS on the standard port (443). A server published on a non-standard port cannot be featured.

## Feature another stream

1. In the admin sidebar, open **Featured Streams**.
2. Click **Feature Live Stream**.
3. Enter the address of the server you want to feature, for example `https://otherserver.example.com`.
4. Save.

The server appears in your list right away with a **Pending approval** status, and it is not shown to your visitors yet. Featuring a server sends it a request, and that server's operator has to approve it before the entry goes live. This is what stops anyone from listing a server as featured without its consent.

## Approve a request to feature you

When another server features you, a request shows up under **Featured Streams** in the admin. The **Featured Streams** item in the sidebar carries a badge with the number of requests waiting on you, so you notice them without going to look. Approve a request and that server may list you in its directory. Until you approve, the other server shows your entry as pending and keeps it hidden from its visitors.

Approving a request is separate from your regular followers. A server that features you does not appear in your Followers list or count.

You can see every directory currently featuring you, and remove any of them, under the **Featuring you** tab of the Followers admin. Removing one stops sending it your stream status, so your entry drops off that directory.

## What your visitors see

Once a server you feature has approved the request, it shows up on the **Featured** tab of your main page:

- Live servers show a thumbnail of the current stream along with its title, and sort to the top.
- Offline servers show the server's logo.
- Every card shows the server name and its address and links out to that server so a visitor can go watch.

The tab refreshes about once a minute on its own, so a featured server going live or offline shows up without anyone reloading the page.

A server's status follows what is actually happening on it:

- It shows as live within about a minute of the stream starting.
- It returns to offline as soon as that stream ends.
- If a featured server disappears without ending its stream cleanly, because it crashed or lost connectivity, its entry falls back to offline after about ten minutes.

## Stop featuring a stream

In **Featured Streams**, click **Unfeature** next to the server you no longer want to list. It is removed from your directory and your visitors stop seeing it.

## Build your own directory

Featured streams is built on Owncast's ActivityPub support. If you would rather build your own directory or aggregator that tracks live Owncast servers instead of using the built-in Featured tab, see [Building a directory of Owncast streams](/docs/api/activitypub#building-a-directory-of-owncast-streams) in the ActivityPub protocol reference.

For a complete, runnable example, see the [owncast-directory-example](https://github.com/owncast/owncast-directory-example) repository. It is a small reference application that follows Owncast servers, tracks which ones are live, takes operator submissions, and serves a web page listing them. It is purely a proof of concept and not intended for production use, but it shows how to use the ActivityPub API to build a directory of Owncast streams.

---

## Owncast Social Features

Owncast allows people to follow, engage with, and share your stream with others on what is known as [**The Fediverse**](the-fediverse.mdx), a decentralized network of services.

## What it supports

1. People can follow your server.
1. Your followers show up in the "Followers" tab on your stream's page. You can hide this tab if you prefer.
1. You can send out posts to your followers via the admin.
1. Your followers will automatically get notified when you go live.
1. Your followers can share that you've gone live with their circle of followers.
1. Actions such as following, liking or sharing get exposed within your stream's chat.

## Why use Owncast's social features?

### Own Your Audience

Unlike traditional streaming platforms, there's no risk of algorithm changes hiding your content, sudden platform policy shifts, or losing access to your community. Your followers are yours.

### Reach Beyond Your Site

Your stream becomes discoverable across the entire Fediverse network. Millions of users on Mastodon, Pixelfed, and other federated platforms. When your followers share that you're live, it spreads organically across their networks without algorithms gatekeeping your reach.

### No Extra Accounts Needed

Your audience doesn't need to create yet another account on yet another platform. If they're already using any Fediverse service like Mastodon or Pleroma, they can follow your Owncast server with their existing account.

### Direct Communication

Send updates directly to your followers about upcoming streams, special events, or important announcements. No competing with millions of other creators in an algorithmic feed, your followers see your posts chronologically where they already are.

### Community Building

Engagement from the Fediverse (follows, likes, shares) appears directly in your stream's chat, creating excitement and social proof. Your followers and shares are featured in front of everyone, making them feel valued as part of your community and encouraging others to share and follow as well.

### FediAuth

Enabling FediAuth allows your viewers to authenticate using their Fediverse accounts when participating in chat. This helps maintain a consistent chat presence across sessions, browsers, and devices. This is especially useful for moderators.

## How do people follow your Owncast server?

Any person on the Fediverse using a service that is compatible with following Owncast, such as [Pleroma](https://pleroma.social/) or [Mastodon](https://joinmastodon.org/) can follow your server.

[Learn more about The Fediverse](./the-fediverse.mdx).

## How it works

The Fediverse is an ensemble of decentralized and interconnected servers that are used for social networking, microblogging and more. While each server is independently hosted, they communicate with each other.

Each Owncast instance operates as a completely standalone server with a single user that can take part in the Fediverse, exchanging posts and notifications with any participating user who is interested in them.

Any user on the Fediverse that is on a compatible server can follow any Owncast server that has this feature enabled.

## Enabling social features

Social features are disabled by default. To enable them on your Owncast server visit the _Configuration -> Social_ page.

### Requirements

You must be hosting your Owncast server behind SSL, with a _https_ URL. Set up a [HTTP Proxy](/docs/sslproxies/nginx) if needed.

### Configuration

Visit the _Configuration -> Social_ page to configure.

1. You can set the username that you're seen as.
1. You can set the "Now Live" message that is sent out each time you go live. Go-live posts are only sent when this message is set, so leave it blank to disable them.
1. You can toggle "Private mode".
1. You can mark your server as potentially NSFW so previews of your stream are flagged as sensitive.
1. You can toggle "Show engagement" to control whether follows, likes and shares appear in your chat feed.
1. You can toggle "Allow quotes" to control whether people can quote your posts.
1. You can toggle "Hide followers" to remove the public Followers tab from your stream page. Social features stay enabled.
1. You can list blocked domains to stop specific servers from interacting with yours.

:::warning
Once you set your server name and your username that's how people will see you. If you change either of those two settings you'll show up as a different user and your existing followers may no longer be following you. It is not suggested you change these after you set them.
:::

### Private mode

Enabling _Private Mode_ will require those who wish to follow your server to be approved by you first. Approving followers can be done via the _Followers_ section in the admin.

Private Mode will also make it so any posts you send out are only visible to your followers, not others, as they cannot be shared.

### Managing followers

The _Followers_ section of the admin lists your current, pending, and blocked followers. With Private Mode on, new follow requests wait there until you approve or reject them. For existing followers you can choose between _Remove_, which lets them follow you again later, and _Block_, which prevents them from following you again.

### Quote posts

:::new[Quote posts require Owncast v0.3.0]
Quote post support was added in Owncast 0.3.0.
:::

People on Mastodon, GoToSocial and other platforms that support quote posts can quote your posts in their own, adding their commentary while showing your original post to their followers. Owncast approves these quotes automatically using the consent flow the Fediverse uses, so quotes of your posts show up correctly everywhere.

If you would rather not allow this, turn off _Allow quotes_ on the _Configuration -> Social_ page. New posts will no longer offer quoting and any quote requests will be declined. Posts are also not quotable while _Private Mode_ is enabled, since they are only visible to your followers.

## Composing messages to your followers

By clicking the _Compose_ button in the admin header you can create a post to send to your followers. This could be used to tell people when you plan on streaming, or to remind people that you're still live. Posts are limited to 500 characters and support simple Markdown formatting. Hashtags are turned into links to their tag pages.

## Engagement

If somebody **follows** you, **likes** a post you send out, or **shares** any of your posts while a stream is live it will display that these actions took place within the chat feed. This can be disabled under the social settings.

Fediverse follow events are also available to third-party integrations through [webhooks](/docs/api/webhooks#fediverse_engagement_follow).

---

## The Fediverse

<center>
  <TheFediverse
    width="200"
    height="200"
    alt="Fediverse logo"
    title="The Fediverse logo"
  />
</center>

## What is The Fediverse?

**The fediverse** is a network of independently operated social platforms that communicate using shared, open protocols, most commonly **ActivityPub**. Instead of a single, centralized service, the fediverse is made up of many servers (often called _instances_) run by different organizations or individuals.

Each instance hosts its own users and content, but can exchange posts, follows and likes with other instances across the network. From a user’s perspective, this means people on Mastodon (for example) can follow an Owncast server, get notified when the stream goes live, and share that stream with their followers, all while using their existing Mastodon account.

Key characteristics:

- **Decentralized**: No single owner or point of control, as each instance is autonomous.
- **Federated**: Instances interoperate by exchanging activities (posts, follows, etc.) over open protocols.
- **Interoperable**: Different applications (e.g., Mastodon, Pleroma, PeerTube, Owncast) can interact with each other.
- **User choice**: Users can choose an instance that matches their values or run their own, without losing the ability to connect with the wider network.

<iframe
  title="Introducing the Fediverse: a New Era of Social Media"
  width="560"
  height="315"
  src="https://videos.elenarossini.com/videos/embed/64VuNCccZNrP4u9MfgbhkN"
  frameborder="0"
  allowfullscreen=""
  sandbox="allow-same-origin allow-scripts allow-popups allow-forms"
></iframe>

## The Future

A decentralized network of different services built on standards is the future of social networking. Learn more about all the different services that make up The Fediverse and see how, much like Owncast can empower you to operate your own live streams, there are other opportunities to leave the centralized corporate social networking services in the past.

### Discover services and sites that make up The Fediverse

- [Join The Fediverse](https://jointhefediverse.net) is an overview of The Fediverse and how it works.
- [What is The Fediverse?](https://joinfediverse.wiki/What_is_the_Fediverse%3F) on Fediverse.wiki.
- [Fediverse](https://en.wikipedia.org/wiki/Fediverse) on Wikipedia.
- [Fediverse.party](https://fediverse.party/)
- [Fediverse.observer](https://fediverse.observer/)

---

## Apache

If you're already using Apache as a web server you can [configure it as a reverse proxy](https://httpd.apache.org/docs/2.4/howto/reverse_proxy.html) in front of your Owncast server to enable SSL.
The following configuration example requires Apache >= 2.4.47.

Ensure required Apache modules are enabled using the `a2enmod` command.

```bash
$ sudo a2enmod proxy proxy_http ssl headers
```

```apacheconf
<VirtualHost *:80>
        ServerName live.example.com
        ServerAdmin admin@example.com

        Redirect permanent / https://live.example.com

</VirtualHost>

# live-le-ssl.conf

<IfModule mod_ssl.c>
<VirtualHost *:443>
        ServerName live.example.com
        ServerAdmin admin@example.com

        ProxyRequests       Off
        ProxyPreserveHost   On
        AllowEncodedSlashes NoDecode

        ProxyPass        / http://localhost:8080/ upgrade=websocket
        ProxyPassReverse / http://localhost:8080/

        RequestHeader    set X-Forwarded-Proto "https"
        RequestHeader    set X-Forwarded-Port "443"

        SSLCertificateFile /path/to/fullchain.pem
        SSLCertificateKeyFile /path/to/privkey.pem
        Include /etc/letsencrypt/options-ssl-apache.conf

</VirtualHost>
</IfModule>
```

---

## Caddy

[Caddy](https://caddyserver.com/) is the fastest way to setup a SSL reverse proxy with a free certificate from [Let's Encrypt](https://letsencrypt.org/).

While we will try to walk you through some installation steps **it is highly suggested you follow Caddy's [Install options](https://caddyserver.com/docs/install) and [Reverse Proxy Quickstart](https://caddyserver.com/docs/quick-starts/reverse-proxy) for more documentation, examples and detailed information**. Caddy is a well documented quality piece of software that you should get familiar with if you need to run a SSL reverse proxy.

## 1. Make sure you don't have other web servers running.

If you are running other pieces of web server software such as Apache or NGINX using port 80 or 443 then you won't be able to continue with this Caddy install. Either remove the other pieces of software or read up on how to make them live in harmony.

## 2. Install Caddy

Depending on your system there may be different options on installing. Using APT is suggested if it's supported on your machine.

<Tabs>
  <TabItem value="apt" label="Using APT (recommended)" default>
      Installing this package automatically starts and runs Caddy for you as a systemd service so it will automatically run Caddy each time you start your machine.

```bash
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy
```

[Read the Caddy install steps for using apt](https://caddyserver.com/docs/install#debian-ubuntu-raspbian) for more details.

  </TabItem>

  <TabItem value="manually" label="Download manually">
    1. [Visit the releases page](https://github.com/caddyserver/caddy/releases) and expand the "assets" section.
  1. Find the version for your platform and operating system.
  1. Unarchive the file: `tar -xvzf caddy_<version>_linux_amd64.tar.gz`
  1. You're likely to want to setup Caddy as a system service to automatically start in the background.  [Learn how to do this](https://caddyserver.com/docs/install#linux-service).
[Read the Caddy download page for more details.](https://caddyserver.com/docs/install#static-binaries)
  </TabItem>
</Tabs>

## 3. Run Caddy as a reverse proxy

<Tabs>
  <TabItem value="single-command-line" label="Single command line" default>

It offers automatic configuration of HTTPS with a single command.

```bash
caddy reverse-proxy --from owncast.mydomain.com --to 127.0.0.1:8080
```

Replace `owncast.mydomain.com` with the public hostname of your Owncast server like `watch.owncast.online` for example.

[Read the Caddy reverse proxy documentation for more details.](https://caddyserver.com/docs/quick-starts/reverse-proxy)

  </TabItem>

  <TabItem value="caddyfile" label="Caddyfile">
  The [Caddyfile](https://caddyserver.com/docs/caddyfile) is Caddy's config file.

Add to your Caddyfile:

```nginx
owncast.example.com {
  encode gzip
  reverse_proxy 127.0.0.1:8080
  tls webmaster@mydomain.com
}
```

Replace `owncast.example.com` with the public hostname of your Owncast server like `watch.owncast.online` for example.

  </TabItem>

</Tabs>

If you specify `owncast.example.com` without a protocol or a port, it will attempt to use the default `http` and `https` ports (80 and 443). Since these are [_privileged ports_](https://www.w3.org/Daemon/User/Installation/PrivilegedPorts.html#:~:text=Priviliged%20ports,has%20put%20up%20for%20you.), you will need to run caddy with `sudo` or as `root`.

## 4. Run Owncast normally

Continue to run Owncast on port 8080.

## 5. Access Owncast through the proxy

You should now be able to access your Owncast server by visiting https://owncast.example.com instead of http://owncast.example.com:8080.

Replace `owncast.example.com` with the public hostname of your Owncast server like `watch.owncast.online` for example.

---

## HAProxy

HAProxy is a well known, performant reverse proxy. Modern HAProxy (2.x and newer) forwards Owncast's WebSocket chat transparently as long as you set a long `timeout tunnel`, so you do not need a separate WebSocket backend.

The `haproxy.cfg` below terminates TLS on ports 80 and 443 and forwards to Owncast on port 8080. It expects your certificate chain and private key combined into a single PEM file at `/etc/haproxy/certs/owncast.pem`. With Let's Encrypt you can build that file with `cat fullchain.pem privkey.pem > /etc/haproxy/certs/owncast.pem`. Change the certificate path and the `127.0.0.1:8080` backend address to match your setup.

`haproxy.cfg`

```
global
  log /dev/log local0
  chroot /var/lib/haproxy
  user haproxy
  group haproxy
  daemon
  maxconn 16384

  # SSL defaults, see https://ssl-config.mozilla.org/#server=haproxy&config=intermediate
  ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384
  ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
  ssl-default-bind-options ssl-min-ver TLSv1.2 no-tls-tickets

defaults
  log global
  mode http
  option httplog
  option forwardfor
  timeout connect 5s
  timeout client 50s
  timeout server 50s
  # Keep long-lived WebSocket (chat) connections open
  timeout tunnel 1h

frontend tls
  bind :80
  bind :443 ssl crt /etc/haproxy/certs/owncast.pem
  # Send all plain HTTP to HTTPS
  http-request redirect scheme https code 301 unless { ssl_fc }
  default_backend owncast

backend owncast
  http-request set-header X-Forwarded-Port %[dst_port]
  http-request add-header X-Forwarded-Proto https if { ssl_fc }
  server server1 127.0.0.1:8080 check
```

---

## SSL & HTTP Proxies

If you’re setting up Owncast and confused by terms like reverse proxy, SSL, or HTTPS, perhaps this can help. This page explains what they are, why Owncast can need them, and how everything fits together.

## What a reverse proxy is

A reverse proxy is a small server that sits in front of Owncast. It:

- Listens on the public internet (ports 80 and 443)
- Handles HTTPS / SSL
- Forwards traffic to Owncast (by default on port 8080)
- Owns the certificate
- Encrypts traffic
- Decrypts it before sending it to Owncast
  Owncast never sees HTTPS — it sees plain internal traffic.

Think of it like a **front desk**:

- The public talks to the front desk.
- The front desk hands things to Owncast.

Owncast relies on standard, battle-tested tools (like Caddy, Nginx, Traefik) to do it correctly. Many who already self-host, or own their own infrastructure will have a reverse proxy setup already that they can add Owncast to.

## Why you want to support SSL

1. If you want to embed your Owncast video or chat into a page that is using SSL your Owncast server will also need to be secured.
1. Browsers will label your site as ["Not Secure"](https://support.apple.com/en-us/HT208672) without using SSL.
1. It looks more professional and your site will come off more trustworthy.
1. Securing web traffic on the public internet is the right thing to do.

### When you might not need it

1. If you're just testing and experimenting with Owncast.
1. You're running the service internally and you don't have any plans for a public audience.

## Common misunderstanding (and why it breaks things)

- ❌ “I enabled HTTPS in Owncast”
- ❌ “I forwarded port 443 to Owncast”
- ❌ “I don’t need a reverse proxy”
- ❌ "I forwarded RTMP port 1935 to the web proxy"

These usually cause:

- OBS connection failures
- Admin UI works but video doesn’t
- Embeds not working
- Mixed content warnings in browsers
- You can still load Owncast on port 8080 but not over https port 443
- Your stream not being available in mobile apps

## A correct setup (simplified)

1. DNS points your domain to your server
2. Reverse proxy listens on ports 80 / 443 (not RTMP 1935)
3. Reverse proxy gets an SSL certificate
4. Reverse proxy forwards traffic to Owncast
5. Owncast runs on :8080 (the port is configurable in Server Setup)
6. Owncast itself is kept off the public internet: bind it to loopback with `--webserverip 127.0.0.1` or firewall port 8080. By default Owncast listens on every interface, so without this step visitors can bypass your proxy and reach it directly over plain HTTP.
7. OBS sends RTMP to Owncast on port 1935, not through the proxy

The proxy must forward every path to Owncast, including the websocket upgrade at `/ws` that chat uses. All of the example configurations in this section do this.

## If something isn’t working, the most helpful questions to ask are:

- “Where does HTTPS terminate?”
- “Which service is listening on port 443?”
- “Is OBS talking to Owncast or the proxy?”
  Answering those almost always reveals the issue.

## Popular options

You can use any method you like to add SSL support but there are some popular options we've seen work well with people. If you have any specific questions or would like to make suggestions on configurations or other setups [let us know](/contact).

## Inherit display name from reverse proxy

Owncast usually assigns a random display name when new users are joining the chat. Upstream reverse proxies can influence this behavior by setting a `X-Forwarded-User` HTTP header when passing along the web traffic. This header will be used instead of a random name to derive a user's display name. A user will still be able to change it's own display name to any desired value.

## Suggested

If you have no requirement to use other options else it is suggested you install [Caddy](/docs/sslproxies/caddy) as it can be installed quickly and easily.

---

## lighttpd

[lighttpd](https://www.lighttpd.net/) is a light HTTP server which can be configured as a suitable reverse proxy via the [mod_proxy](https://redmine.lighttpd.net/projects/lighttpd/wiki/Mod_proxy) module.

## SSL

An implementation of [SSL support](https://redmine.lighttpd.net/projects/lighttpd/wiki/Docs_SSL) via the mod_openssl module using OpenSSL may appear as follows:

```
$SERVER["socket"] == "[::]:443" {
  ssl.engine = "enable"
  ssl.cipher-list = "HIGH"
  $HTTP["host"] == "owncast.yourdomain.com" {
    ssl.pemfile = "/etc/letsencrypt/live/yourdomain.com/fullchain.pem"
    ssl.privkey = "/etc/letsencrypt/live/yourdomain.com/privkey.pem"
    ssl.dh-file = "/etc/letsencrypt/ssl-dhparams.pem"
  }
}
```

## Reverse Proxy

Proxying of incoming websocket connections is integrated with the module.

An example configuration for lighttpd might appear as follows:

```
$HTTP["host"] == "owncast.yourdomain.com" {
  # Forward all requests to Owncast:
  proxy.server = ( "" => ( ( "host" => "127.0.0.1", "port" => 8080 ) ) )

  proxy.forwarded = ( "host" => 1,
                      "proto" => 1,
                      "for" => 1,
                      "remote_user" => 1 )

  # Required for websocket (chat) forwarding:
  proxy.header = ( "upgrade" => "enable" )
}
```

---

## NGINX

NGINX is a popular web server used as a reverse proxy with free Let's Encrypt certificates. Visit the [official documentation](https://www.nginx.com/blog/using-free-ssltls-certificates-from-lets-encrypt-with-nginx/) for detailed instructions.

## Websockets

People often look over the need to tell NGINX to proxy websockets correctly, leading to chat being disabled. Please read the quick [documentation by nginx around websocket support](https://nginx.org/en/docs/http/websocket.html) to make sure you're doing it properly.

Essentially, you'll need to edit `/etc/nginx/nginx.conf` to add the following map block to the http section

```nginx
http {
  ...
  map $http_upgrade $connection_upgrade {
      default upgrade;
      ''      close;
  }
  ...
}
```

You'll end up with a configuration that looks somewhat like the following when you're done setting up NGINX. The below should be added to `/etc/nginx/sites-available/my.site.com.conf` and enabled with `ln /etc/nginx/sites-available/my.site.com.conf /etc/nginx/sites-enabled/my.site.com.conf` and tested with `sudo nginx -t`, then restarted `sudo service nginx restart`

```nginx
server {
    server_name owncast.yourdomain.com;
    listen 443 ssl;
    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header  Authorization $http_authorization;
        proxy_pass_header Authorization;
        proxy_pass http://127.0.0.1:8080;
    }
}
```

---

## Use Object Storage to Save Bandwidth

Instead of serving video directly from your personal server you can use a S3 compatible storage provider to offload the bandwidth and storage requirements elsewhere. This is not for permanent storage of recordings or archival purposes, just for live streams.

To learn more about how your bandwidth may be affected by your video configuration and how using object storage could help for some use cases, visit the [resources and requirements](/docs/resources-requirements/) page.

If your storage provider is S3 compatible it will likely work with Owncast. Read the documentation for your provider to learn how to setup an object storage bucket, enable CORS, make the files public, and get the necessary credentials to provide to your Owncast configuration.

## Configuration

1. Visit your Owncast server setup page in the admin and view the Object Storage settings.
1. Enable it.
1. Visit your storage provider and create a new bucket.
1. Enter the bucket name, access key, secret key, endpoint, and region that your object storage provider's interface gave you into the Owncast settings. All of these fields are required, and Owncast will reject the configuration if any are missing, so double check them. If your provider doesn't use regions, enter the placeholder value its documentation suggests. Contact your storage provider's support if you're not sure what these are.
1. Make sure your bucket is publicly accessible, and anybody can read files from it. Some storage providers may set your bucket as private by default, so you may need to change this setting.
1. If your storage provider requires you to setup any kind of [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) policy in order for your files to be accessed, make sure you do that. Visit your object storage provider's documentation to learn how to configure your CORS policy, as it's different for every provider. It's generally a good idea to allow all origins, but you can restrict it to your Owncast server if you have a specific need to do that, and you don't anticipate using your stream in other web pages. If your stream is not working and your browser console error log shows errors about `CORS` or `Access-Control-Allow-Origin`, this is likely the problem. This is often very common, so make sure your bucket is setup correctly.

## Retention

Owncast keeps only the recent playback window in your bucket. As new video segments upload, it deletes objects older than the playlist depth plus a cleanup buffer of about 20 segments. The bucket never holds more than the last few minutes of your stream, so don't treat it as a recording archive.

### Optional settings

Most people won't need to touch these settings, but they're available if you need them.

- **ACL**: If you are required to specify a specific access control option when uploading files, you can specify it here. Refer to your object storage provider's documentation.
- **Path Prefix**: If you want to store your files in a subdirectory within your bucket, you can specify that here. For example, if you want to store your files in a folder called `mystream`, you would enter `mystream` here. This is only useful if you're using a single bucket for multiple purposes, or have multiple Owncast servers pointing to the same bucket.
- **Path-style configuration**: Some storage providers, such as Oracle Cloud Objects, require the "path-style" configuration option to be enabled. Refer to your storage provider documentation to learn if this is required.

---

## Video quality and performance

Stream quality is a chain that runs from the software you broadcast with to the way viewers pull video. Each page here covers one link in that chain.

Your [broadcasting software](/docs/broadcasting) sets the resolution, framerate, and bitrate that Owncast receives. The [video quality settings](/docs/video) then control the output qualities Owncast produces and the hardware cost of producing them, since more qualities and higher bitrates mean more CPU.

[Object storage](/docs/storage) moves the bandwidth of serving video off your own server onto an S3 compatible provider, which starts to matter as your audience grows. [Reducing latency](/docs/latency) is the tradeoff between how close to live your stream runs and how smoothly it plays. [Stream performance](/docs/metrics) shows from the admin whether the result is holding up.

---

## Choose the Right Video Quality Settings

This document aims to outline what is being done to your content and the different knobs you can tweak to get the best output for your instance.

To see how your specific stream is performing, visit the [Stream Health](/docs/metrics) page in the admin.

## Overview

1. Configure your broadcasting software to send a stream to Owncast that is reasonably close to what you expect to send to your viewers. [How you configure your broadcasting software matters](/docs/video/#how-you-configure-your-broadcasting-software-matters). Don't tell OBS to send to Owncast at 7000k at 60fps if you only expect to support bitrates of 4000k and 2000k at 30fps.
1. Start with a single [output configuration](/docs/video/#things-you-can-configure) with average settings. Test it. See how your hardware handles it. If you want to, and are able to, then add another and test that. Repeat until you arrive at the configuration you want to offer your viewers and that your hardware can handle.
1. If your hardware can't handle your current configuration then reduce the number of output variants to only a single one, [reduce the quality of video you're sending to Owncast](/docs/video/#how-you-configure-your-broadcasting-software-matters), reduce your [framerate](/docs/video/#framerate), and reduce the [CPU usage](/docs/video/#cpu-usage)

## Your stream can be played outside of your web site.

Because Owncast uses the HLS standard, almost any video player can play your stream. You can also build your own app that plays it. Commonly used video player such as Quicktime, VLC, and mpv can play your stream simply by using its base URL as `https://owncast.mydomain.com`. Alternatively, you can also access your stream directly on your server by putting the path of `/hls/stream.m3u8` into your player. For example: `https://owncast.mydomain.com/hls/stream.m3u8`.

## How does an Owncast video stream work?

<IncludeMarkdown>
  <OwncastBasic />
</IncludeMarkdown>

Owncast takes your source stream and converts it to short, individual video segments. A list of these segments is supplied to your viewer's player and will read and play all the segments in order. This is using a specification called [HLS](https://developer.apple.com/documentation/http-live-streaming) or HTTP Live Streaming. You can optionally generate multiple different qualities of video to allow lower bandwidth options. This is called [Adaptive bitrate streaming](https://en.wikipedia.org/wiki/Adaptive_bitrate_streaming).

In this case Owncast works as the Media encoder, Stream segmenter, and distribution web server. However [Owncast supports video being distributed via 3rd party storage as well](/docs/storage), so in that case the video segments would be distributed from there, instead.

#### Things to keep in mind.

1. The more work you need done to convert the video from one size, quality or format to another the more it will slow everything else down.
1. The slower things go the slower the stream is provided to the user.
1. If stream is provided to the user too slowly they'll start seeing buffering and errors.

Here's what knobs can be tweaked when trying to determine the quality or qualities you want to provide your user while balancing the amount of server resources you're consuming.

## Things you can configure

### Bitrate

The bitrate is the amount of data you send when you stream. A higher bitrate takes up more available internet bandwidth and create larger sized segments of video, making it take longer for viewers to download. Increasing your bitrate can improve your video quality, but only up to a certain point. You can select bitrates between 400 and 13,000 kbps, in 100 kbps steps.

### Resolution

Resolution refers to the size of a video on a screen. Like bitrates you can provide multiple different sizes for different cases, but asking to resize a video amounts to additional work that needs to be performed.

It's recommended if you have to change the size to only change the width **or** the height, and it'll keep the correct aspect ratio for you. If you change both the width and the height you may be changing the aspect ratio of the video you may end up with a squished picture if you don't set it correctly.

### Framerate

Framerate is the number of frames per second in the video. Owncast defaults to 24fps, but other common framerates are 30 or 60. You can select any framerate between 24 and 120. Increasing the framerate will use more CPU on your server, and more bandwidth for your users as more frames of video have to be processed and made available to your viewers any given second.

### CPU Usage

The more CPU you use the better the output image will be, or the smaller of a file the output will be for the same quality. However, you will need to balance the amount of CPU you have available with the amount you can use to process video. There are five CPU usage levels to pick from, ranging from lowest to highest.

### Latency Buffer

You have some control over the live latency between the broadcaster and the viewer. While it's completely understandable to want to have as little latency as possible you may need to increase the latency buffer if you're experiencing issues. In general the lower the latency the less buffer is available for any possible slow transfers, network blips or errors.

### Autoplay

By default viewers press play to start watching. If you would rather the stream start on its own when someone opens your page, change the **Autoplay** setting on the same Video configuration page. It has no performance impact, and it applies to your Owncast page and to [embedded players](/docs/embed#autoplay).

- **Never**: the player waits for the viewer to press play. This is the default.
- **Always**: the stream starts the moment the page opens. It plays with sound where the browser allows it and starts muted everywhere else. While the stream plays muted, the player shows a large unmute button over the video so turning on sound is one click.
- **Only if sound is available**: the stream starts on its own only when the viewer's browser allows sound to play too. It never starts silently. If the browser blocks sound, the viewer presses play as usual.

Every major browser restricts autoplay with sound, based on its own rules, its settings, and often the viewer's history with your site. In practice **Always** usually starts muted for first-time visitors, and **Only if sound is available** usually does not autoplay for them at all.

The player also never autoplays, regardless of this setting, for viewers who have data saver enabled or whose system asks for reduced motion (the `prefers-reduced-motion` accessibility preference).

<IncludeMarkdown>
  <OwncastWithQualities />
</IncludeMarkdown>

### Video Passthrough

:::warning[This is an advanced setting that most people should not use.]
Owncast has an optional setting to turn off re-encoding of your inbound stream, potentially saving substantial hardware utilization and supporting a higher quality stream with less resources. However, because your video will not be re-encoded it’s possible that certain video from certain sources may **end up not being playable at all**. This is the risk of enabling this.
:::

When passthrough is enabled for a stream output, Owncast copies your inbound video untouched instead of re-encoding it. All the other settings for that output, such as bitrate, resolution, framerate and CPU usage level, are ignored. Because no encoding work happens, passthrough saves nearly all the CPU that output would otherwise use.

The tradeoff is that viewers receive exactly what your broadcasting software sends. If your source uses settings some players or browsers can't handle, the stream can be **unplayable** for those viewers, and Owncast can't correct it. Long keyframe intervals in your source also increase latency, because Owncast can't optimally segment video it isn't re-encoding. This is why the admin asks you to confirm you understand the risks before enabling it. Test playback on the devices you care about before relying on passthrough.

## Audio

What you're sending from your broadcasting software is generally reasonable and additional conversion isn't required, even for low-bandwidth viewers. Owncast will not change the audio stream and instead just pass it along to the end users to save additional work being performed.

<ResourcesCalculator />

## How you configure your broadcasting software matters.

You will want to configure your broadcasting software to match the highest quality you can offer your viewers. **That means if your Owncast server can only handle 720p@2500k you should not configure your broadcasting software to send 1080p@6000k**. The more conversion work you ask Owncast to do the more resources it will use on your server, making it even harder to offer the best qualities to your viewers.

If you find yourself trying to squeeze better performance out of Owncast then try setting your broadcasting software to a lower quality as well as lowering the quality in your Owncast instance.

Read more about [configuring your broadcasting software](/docs/broadcasting/obs).

## Hardware accelerated video encoding

If you are running on physical hardware you may be able to increase the performance of your Owncast instance by using your hardware along with a compatible codec, taking the heavy load off of your CPU. There is no guarantee all hardware configurations, drivers or operating systems will work and it may take some effort on your part to install all of the additional software required to get it working. Read more about what is supported, and how, at our [hardware accelerated encoding with additional codecs](/docs/codecs) document.

## Resource and requirement examples

Visit the [resources and requirements](/docs/resources-requirements/) page to see some examples of what you can expect from your server hardware and network connection and how it may affect your viewers.

---

## Show Where Your Viewers Are From

Owncast can display high-level geographic information about your current viewers if you enable it in your instance.

Your server can optionally use the [MaxMind GeoLite2 Database](https://dev.maxmind.com/geoip/geolocate-an-ip/databases/). If you provide your own free copy of the database it will be used. Perform the following in order to add this feature.

1. [Create a free account](https://www.maxmind.com/en/geolite2/signup) with MaxMind.
1. Wait for an email and follow the link to your account.
1. Under `Database Products and Subscriptions` click `Download Databases`.
1. Download `GeoLite2 City (GeoIP2 Binary .mmdb)`.
1. Unzip the file and place the `GeoLite2-City.mmdb` file into the `data` directory of your Owncast server. Create this directory if needed.
1. Restart your Owncast service.

Once enabled, the **Viewers** page in the admin at `/admin/viewer-info` shows a **Location** column with the region and country for each current viewer, resolved from the GeoIP data. Viewers without a resolvable country, or connecting through an anonymous proxy, do not get a location.

---

## Amazon Fire TV

<DeviceLayout>

<DeviceOptionsGrid>

  <DeviceOptionCard
    id="vlc-fire-tv"
    title="VLC for Fire TV"
    badge="Recommended"
    difficulty="easy"
    screenshot="/images/devices/google-tv/vlc-android-tv.jpg"
    screenshotAlt="VLC for Android TV playback interface"
    summary="Use VLC to play Owncast streams directly on your Fire TV device."
  >
    
      Reliable media player with excellent stream support.
      Direct URL input for any Owncast server.
      Free and widely available.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Install VLC for Amazon Fire TV from the Amazon App Store.
      2. Select **Streams** from the **Browsing** row.
      3. Enter the stream URL. The direct HLS form is the most reliable, for example `https://watch.owncast.online/hls/stream.m3u8`.
      4. Select the send arrow next to the field to start playback.

    </details>

    <StoreButton
      url="https://www.amazon.com/VLC-Mobile-Team-for-Fire/dp/B00U65KQMQ"
      type="amazon"
    />

  </DeviceOptionCard>

</DeviceOptionsGrid>

</DeviceLayout>

---

## Android phones and tablets

<DeviceLayout>

<DeviceOptionsGrid>
  <DeviceOptionCard
    id="owncasts-android"
    title="Owncasts for Android"
    badge="Recommended"
    difficulty="easy"
    screenshot="/apps/owncasts/android/owncasts-android-home.png"
    screenshotAlt="Owncasts for Android directory screen"
    summary="Use the native Owncasts app to browse the directory, save favorite servers, and watch streams."
  >
    
      Built for Android phones and tablets.
      Directory browsing and favorite servers built in.
      Includes playback and chat.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Open the [Owncasts for Android](/apps/owncasts/android/) page.
      2. Choose Google Play, Obtainium, or a direct APK download.
      3. Launch Owncasts and browse the directory or add your own Owncast server.
      4. Select a stream to start watching.

    </details>

    <AndroidInstallButton />

  </DeviceOptionCard>

  <DeviceOptionCard
    id="vlc-android"
    title="VLC for Android"
    badge="Recommended"
    difficulty="easy"
    screenshot="/images/devices/android/vlc-android.webp"
    screenshotAlt="VLC for Android app interface"
  >
    
      Free and open source.
      Supports network streams and adaptive streaming.
      Works on Android phones, tablets, and Android TV devices.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Install VLC from Google Play.
      2. Open the **More** tab and select **Streams**.
      3. Enter your stream URL. The direct HLS form is the most reliable, for example `https://watch.owncast.online/hls/stream.m3u8`.
      4. Tap the send arrow next to the field to start playback.

    </details>

    <StoreButton
      url="https://play.google.com/store/apps/details?id=org.videolan.vlc"
      type="android"
    />

  </DeviceOptionCard>

  <DeviceOptionCard
    id="mpv-android"
    title="mpv-android"
    difficulty="medium"
    screenshot="/images/devices/android/mpv-android.webp"
    screenshotAlt="mpv-android playback interface"
    summary="Use mpv-android when you want a lightweight player for a direct Owncast stream URL."
  >
    
      Open source player based on libmpv.
      Supports network playback, including HLS streams.
      Offers detailed playback and subtitle controls.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Install mpv-android from Google Play.
      2. On the main screen, tap **Open URL**.
      3. Enter your stream URL, for example `https://watch.owncast.online/hls/stream.m3u8`.
      4. Tap **OK**.

    </details>

    <StoreButton
      url="https://play.google.com/store/apps/details?id=is.xyz.mpv"
      type="android"
    />

  </DeviceOptionCard>

  <DeviceOptionCard
    id="android-web-player"
    title="Android web browser"
    difficulty="easy"
    summary="The built-in browser can use Owncast's web player without installing another app."
  >
    
      Open your Owncast server URL in Chrome or another modern Android browser.
      Uses the same web player as desktop viewers.
      Supports chat, stream metadata, and authentication when the server enables them.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Open Chrome or another modern browser on your Android device.
      2. Navigate to your Owncast server URL, such as `https://watch.owncast.online`.
      3. Tap the play button.

    </details>

  </DeviceOptionCard>

</DeviceOptionsGrid>

</DeviceLayout>

---

## Apple TV

<Head>
  <meta name="apple-itunes-app" content="app-id=6451178968" />
</Head>

<DeviceLayout>

<DeviceOptionsGrid>

  <DeviceOptionCard
    id="owncasts-tvos"
    title="Owncasts for tvOS"
    badge="Recommended"
    difficulty="easy"
    screenshot="/images/devices/apple-tv/owncasts-tvos-home.png"
    screenshotAlt="Owncasts app directory screen"
    summary="Use the native Owncasts for tvOS app to browse the Owncast directory or connect directly to your own server."
  >
    
      Best experience if you primarily watch Owncast streams.
      Simple interface with directory browsing built in.
      No casting or mirroring required.
    

    <StoreButton
      url="https://apps.apple.com/us/app/owncasts/id6451178968"
      type="tvos"
    />

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Open the **App Store** on your Apple TV.
      2. Search for **Owncasts** and install the app.
      3. Launch Owncasts for tvOS.
      4. Browse the directory or add your Owncast server URL in settings.
      5. Select a stream and start watching.

    </details>

  </DeviceOptionCard>

  <DeviceOptionCard
    id="vlc-tvos"
    title="VLC for tvOS"
    difficulty="medium"
    screenshot="/images/devices/apple-tv/vlc-playback.jpg"
    screenshotAlt="VLC playback screen"
    summary="Use VLC to open your Owncast URL directly as a network stream."
  >
    
      Good if you already use VLC on other devices.
      Works with the main Owncast page URL or direct HLS URL.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Install **VLC** from the tvOS App Store.
      2. Open VLC and navigate to **Network Stream**.
      3. Type your Owncast URL into the **Enter URL to play** field. The direct HLS form is the most reliable, for example `https://watch.yourserver.tld/hls/stream.m3u8`.
      4. Submit the field to start playback. VLC keeps recent stream URLs on this screen so you can pick the stream again later.

    </details>

    <StoreButton
      url="https://apps.apple.com/app/vlc-for-mobile/id650377962"
      type="tvos"
    />

  </DeviceOptionCard>

  <DeviceOptionCard
    id="airplay-ios"
    title="AirPlay from iPhone or iPad"
    difficulty="easy"
    screenshot="/images/devices/iphone-ipad/airplay-tv.png"
    screenshotAlt="AirPlay device selection screen"
    summary="Play the Owncast stream on your iPhone/iPad and AirPlay to your Apple TV."
  >
    
      Great if you primarily watch on your phone but want to send it to TV occasionally.
      No extra tvOS apps required.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Open the Owncast stream in a browser on iOS or iPadOS. Alternatively open using the Owncasts iOS app.
      2. Start playback.
      3. Open **Control Center** and tap the AirPlay icon.
      4. Select your Apple TV.

    </details>

  </DeviceOptionCard>

  <DeviceOptionCard
    id="airplay-mac"
    title="AirPlay from Mac"
    difficulty="medium"
    summary="Play the Owncast stream on your Mac and mirror or AirPlay the video to Apple TV."
  >
    
      Good if you want to use your laptop to stream to your AppleTV.
      Works from Safari or screen sharing from macOS.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Open the Owncast stream in Safari on your Mac.
      2. Start playback.
      3. Use the **Screen Mirroring / AirPlay** icon in the menu bar, or in the video player if available.
      4. Select your Apple TV.

    </details>

  </DeviceOptionCard>

  <DeviceOptionCard
    id="iplaytv-tvos"
    title="iPlayTV for tvOS"
    difficulty="medium"
    screenshot="/images/devices/apple-tv/iplaytv-interface.png"
    screenshotAlt="iPlayTV for tvOS IPTV interface"
    summary="Use iPlayTV to browse the Owncast directory via IPTV playlist on your Apple TV."
  >
    
      Browse the entire Owncast directory directly on your TV.
      IPTV playlist support for directory integration.
      Reload the playlist to pick up the streams that are live now.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Install **iPlayTV** from the tvOS App Store.
      2. Open iPlayTV and choose **Add Playlist**.
      3. Choose the remote M3U link option and enter the directory playlist URL: `https://owncast.directory/api/iptv`
      4. Give the playlist a name and save it.
      5. Open the playlist and browse the available Owncast streams.

    </details>

    <StoreButton
      url="https://apps.apple.com/app/iplaytv-iptv-m3u-player/id1072226801"
      type="tvos"
    />

  </DeviceOptionCard>

</DeviceOptionsGrid>

</DeviceLayout>

---

## Chromecast

<DeviceLayout>

<DeviceOptionsGrid>

  <DeviceOptionCard
    id="chrome-cast"
    title="Chrome Browser Casting"
    badge="Recommended"
    difficulty="easy"
    screenshot="/images/devices/chromecast/chrome-cast.png"
    screenshotAlt="Owncast web interface in a browser"
    summary="Cast your Owncast stream directly from Chrome browser to your Chromecast device."
  >
    
      Works with any Owncast stream in Chrome browser.
      Simple casting process with just a few clicks.
      No additional apps required on the Chromecast.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. On your computer, open **Chrome**.
      2. Visit the Owncast server you want to watch.
      3. At the top right, select **More**, then **Cast, save, and share**, then **Cast**.
      4. Choose the Chromecast device where you want to watch the content.
      5. If you're already using the Chromecast, your content will replace what's on your TV.

    </details>

    For more details, visit the [official Chromecast documentation](https://support.google.com/chromecast/answer/3228332).

  </DeviceOptionCard>

</DeviceOptionsGrid>

</DeviceLayout>

---

## Google TV

<DeviceLayout>

<DeviceOptionsGrid>

  <DeviceOptionCard
    id="vlc-google-tv"
    title="VLC for Android TV"
    badge="Recommended"
    difficulty="easy"
    screenshot="/images/devices/google-tv/vlc-android-tv.jpg"
    screenshotAlt="VLC for Android TV playback interface"
    summary="Use VLC from the Google Play Store to play Owncast streams on your Google TV."
  >
    
      Full-featured media player optimized for TV interface.
      Easy stream URL input.
      Free and regularly updated.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Install VLC from the Google Play store.
      2. Select **Streams** from the **Browsing** row.
      3. Enter the stream URL. The direct HLS form is the most reliable, for example `https://watch.owncast.online/hls/stream.m3u8`.
      4. Select the send arrow next to the field to start playback.

    </details>

    <StoreButton
      url="https://play.google.com/store/apps/details?id=org.videolan.vlc"
      type="android"
    />

  </DeviceOptionCard>

</DeviceOptionsGrid>

</DeviceLayout>

---

## Watching on TVs and Devices

There are numerous ways to watch Owncast live streams on many different devices. This section provides detailed guides for each supported platform and device type.

:::note
Most applications listed here are not provided by, endorsed by, or supported by Owncast. You should make your own choices about what applications you install. Products listed are suggestions that have been tested and found to work with Owncast. Those built and provided by Owncast should be seen as side projects to assist viewers.
:::

:::new[Authentication gates require Owncast v0.3.0]
If the server runs an authentication gate plugin, direct HLS URLs and third-party apps may be redirected to authenticate before playback. These instructions assume a public instance.
:::

## Quick Access Methods

### Any Existing Video Player or Hardware

Owncast supports video streaming standards, so you can use any video player that supports HLS (HTTP Live Streaming) to watch streams. This means many existing video playing applications, pieces of hardware, and smart TVs can play Owncast streams already.

Install or open any video playback application for your platform and use the URL `https://your-owncast-server.com/hls/stream.m3u8` to access the stream directly. This includes simply putting that URL into the Safari web browser on an iPhone, or sending `https://your-owncast-server.com` as a link in an iMessage to a friend, they'll be able to play the stream back directly in the message.

### Browsing the Directory

If your application has what is often called "IPTV" or M3U support, you can browse the directory directly by adding `https://owncast.directory/api/iptv` to the application. Not all apps support this.

## Device-Specific Guides

### Streaming Boxes and Devices

- **[Apple TV](/docs/watching-streams/apple-tv)** - Owncasts for tvOS, VLC, or AirPlay
- **[Roku](/docs/watching-streams/roku)** - Owncasts for Roku or AirPlay
- **[Amazon Fire TV](/docs/watching-streams/amazon-fire-tv)** - VLC for Fire TV
- **[Google TV](/docs/watching-streams/google-tv)** - VLC for Android TV
- **[Chromecast](/docs/watching-streams/chromecast)** - Cast from the Chrome browser

### Smart TVs

- **[LG TVs (WebOS)](/docs/watching-streams/lg-webos)** - An IPTV playlist app or the built-in browser
- **[Samsung TVs](/docs/watching-streams/samsung-tv)** - The Internet app, mirroring, or an external device

### Mobile, Desktop, and Media Centers
- **[Android phones and tablets](/docs/watching-streams/android)** - VLC, mpv-android, or the built-in web player

- **[iPhone & iPad](/docs/watching-streams/iphone-ipad)** - Owncasts for iOS, Safari, or VLC
- **[Kodi](/docs/watching-streams/kodi)** - Owncast plugin or direct URL playback
- **[Web Browsers](/docs/watching-streams/web)** - The built-in Owncast web player

## Recommended Setup

For the best experience, we recommend:

1. **Dedicated streaming device** (Apple TV, Fire TV, Roku) and a streaming app rather than built-in smart TV apps
2. **VLC** as a universal solution for most platforms
3. **Native Owncast apps** when available for your platform
4. **Casting/AirPlay** from mobile devices when direct apps aren't available

## Need Help?

If you're having trouble with any of these methods join our community chat for assistance.

---

## iPhone & iPad

<Head>
  <meta name="apple-itunes-app" content="app-id=6451178968" />
</Head>

<DeviceLayout>

<DeviceOptionsGrid>

  <DeviceOptionCard
    id="owncasts-ios"
    title="Owncasts for iOS"
    badge="Recommended"
    difficulty="easy"
    screenshot="/images/devices/iphone-ipad/owncasts-ios-directory.png"
    screenshotAlt="Owncasts for iOS directory screen"
    summary="Use the native Owncasts app to browse the directory or connect directly to your own server."
  >
    
      Best experience for watching Owncast streams on mobile.
      Directory browsing built in.
      Picture-in-picture support for multitasking.
      AirPlay integration for casting to TV.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Install **Owncasts for iOS** from the App Store.
      2. Launch the application and browse the directory or add your own Owncast server in settings.
      3. Select a stream to start watching.
      4. Use the AirPlay button to cast to compatible devices like Apple TV or AirPlay-enabled TVs.

    </details>

    <StoreButton
      url="https://apps.apple.com/us/app/owncasts/id6451178968"
      type="ios"
    />

  </DeviceOptionCard>

  <DeviceOptionCard
    id="safari-browser"
    title="Safari Browser"
    difficulty="easy"
    screenshot="/images/devices/iphone-ipad/safari-browser.png"
    screenshotAlt="Owncast mobile web interface"
    summary="Watch Owncast streams directly in Safari with full-screen and AirPlay support."
  >
    
      No app installation required.
      Works with any Owncast server.
      Built-in AirPlay controls in video player.
      Picture-in-picture support on supported devices.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Open **Safari** on your iPhone or iPad.
      2. Navigate to your Owncast server URL (e.g., `https://watch.owncast.online`).
      3. Tap the play button to start the stream.
      4. Use the AirPlay button in the video controls to cast to other devices.
      5. Tap the full-screen button for immersive viewing.

    </details>

  </DeviceOptionCard>

  <DeviceOptionCard
    id="vlc-ios"
    title="VLC for iOS"
    difficulty="medium"
    screenshot="/images/devices/iphone-ipad/vlc-network.png"
    screenshotAlt="VLC for iOS playback interface"
    summary="Use VLC to play Owncast streams with advanced playback controls and options."
  >
    
      Advanced media player with extensive format support.
      Network stream support for direct URL input.
      Offline playback capabilities.
      Built-in AirPlay support.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Install **VLC for iOS** from the App Store.
      2. Open VLC and select the **Browse** tab.
      3. Select **Open Network Stream**.
      4. Enter your Owncast URL. The direct HLS form is the most reliable, for example `https://watch.owncast.online/hls/stream.m3u8`.
      5. Tap the **Open** arrow to start playback.
      6. Use AirPlay button to cast to other devices if desired.

    </details>

    <StoreButton
      url="https://apps.apple.com/app/vlc-for-mobile/id650377962"
      type="ios"
    />

  </DeviceOptionCard>

  <DeviceOptionCard
    id="airplay-casting"
    title="AirPlay to TV"
    difficulty="easy"
    screenshot="/images/devices/iphone-ipad/airplay-tv.png"
    screenshotAlt="AirPlay device selection screen"
    summary="Stream from your iPhone or iPad to Apple TV, AirPlay-compatible TVs, or other AirPlay receivers."
  >
    
      Works from both the Owncasts app and Safari.
      High-quality video streaming to large screens.
      Control playback from your mobile device.
      Continue using your phone while streaming.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Start playing an Owncast stream on your iPhone or iPad (using either the Owncasts app or Safari).
      2. Look for the **AirPlay** button in the video controls or app interface.
      3. Tap the AirPlay button and select your target device (Apple TV, smart TV, etc.).
      4. The stream will begin playing on the selected device.
      5. Use your iPhone/iPad as a remote control.

    </details>

    For more details, visit [Apple's AirPlay documentation](https://support.apple.com/en-us/HT204289).

  </DeviceOptionCard>

  <DeviceOptionCard
    id="control-center-airplay"
    title="Control Center AirPlay"
    difficulty="easy"
    screenshot="/images/devices/iphone-ipad/control-center-airplay.png"
    screenshotAlt="iOS Control Center with AirPlay button"
    summary="Use Control Center to quickly AirPlay any Owncast stream to compatible devices."
  >
    
      System-wide AirPlay access from Control Center.
      Works with any app or browser playing Owncast streams.
      Quick device switching.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Start playing an Owncast stream in any app or Safari.
      2. Open **Control Center** (swipe down from top-right on newer iPhones, swipe up from bottom on older models).
      3. Tap the **AirPlay** icon (rectangle with triangle).
      4. Select your AirPlay-compatible device from the list.
      5. The audio and video will stream to the selected device.

    </details>

  </DeviceOptionCard>

</DeviceOptionsGrid>

</DeviceLayout>

---

## Kodi

<DeviceLayout>

<DeviceOptionsGrid>

  <DeviceOptionCard
    id="owncast-plugin"
    title="Owncast Kodi Plugin"
    badge="Recommended"
    difficulty="medium"
    screenshot="/images/devices/kodi/plugin-interface.png"
    screenshotAlt="Owncast Kodi plugin directory interface"
    summary="Install the official Owncast plugin to browse the directory directly within Kodi."
  >
    
      Browse the entire Owncast directory from within Kodi.
      Dedicated plugin built specifically for Owncast.
      Integrates seamlessly with Kodi's interface.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Visit the [Owncast Kodi Plugin](https://github.com/rAcHekLoS/plugin.video.owncast) GitHub repository by rAcHekLoS.
      2. Follow the plugin's installation instructions on GitHub.
      3. Launch the plugin from Kodi's Add-ons section.
      4. Browse available Owncast streams from the directory.
      5. Select a stream to start watching.

    </details>

    
      
        View on GitHub
      
    

  </DeviceOptionCard>

  <DeviceOptionCard
    id="direct-url-kodi"
    title="Direct URL Playback"
    difficulty="medium"
    summary="Play a single Owncast stream by pointing Kodi at a small .strm file that holds the stream URL."
  >
    
      Works with any Kodi installation.
      Direct access to specific Owncast servers.
      No additional plugins required.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Create a plain text file named `owncast.strm` containing only your stream's HLS URL, for example `https://watch.owncast.online/hls/stream.m3u8`.
      2. Put the file in a folder Kodi can reach, either on the same machine or on a network share.
      3. In Kodi, go to **Videos** > **Files** and select **Add videos...**.
      4. Choose **Browse**, select the folder holding `owncast.strm`, and select **OK**. For a network share, use **Add network location...** first to set the protocol, server, and shared folder.
      5. Open the source, select `owncast.strm`, and choose **Play**.

      Kodi's **Add network location...** dialog asks for a protocol, server, and shared folder, so it cannot take a full stream URL on its own. The `.strm` file is what makes the stream playable.

    </details>

  </DeviceOptionCard>

</DeviceOptionsGrid>

</DeviceLayout>

---

## LG Smart TVs (WebOS)

<DeviceLayout>

<DeviceOptionsGrid>

  <DeviceOptionCard
    id="iptv-webos"
    title="IPTV Playlist App"
    badge="Recommended"
    difficulty="medium"
    summary="Install an IPTV player from the LG Content Store and point it at the Owncast directory playlist."
  >
    
      Browse the entire Owncast directory directly on your TV.
      webOS has no native M3U playlist support, so this needs a third-party player.
      Reload the playlist to pick up the streams that are live now.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Install an IPTV or M3U player from the LG Content Store. Availability varies by region and by TV model.
      2. Add a playlist using this URL: `https://owncast.directory/api/iptv`. Make sure it starts with `https`.
      3. Double check you typed it in correctly, then save the playlist.
      4. Reload or reopen the playlist to refresh the list of live streams.
      5. Choose the live stream you want to watch.

      **Note:** Players differ in how a playlist is added. Some take the URL on the TV, and others want you to upload the playlist through their own website keyed to your TV. Follow whichever method your chosen app documents.

    </details>

  </DeviceOptionCard>

  <DeviceOptionCard
    id="direct-url-webos"
    title="Direct URL Input"
    difficulty="hard"
    screenshot="/images/devices/lg-webos/direct-url.png"
    screenshotAlt="LG webOS browser address bar"
    summary="Use the webOS Web browser app to open an Owncast stream directly on the TV."
  >
    
      webOS includes a Web browser app on the Home menu.
      Requires manual URL entry.
      LG notes that browser functions are more limited than on a computer or phone.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Open **Web browser** from **Home** on your LG webOS TV.
      2. Enter your Owncast server URL in the address bar.
      3. Try to play the stream directly in the browser.

      **Note:** TV browsers are limited compared with a phone or computer, so web video playback may not work reliably.

    </details>

  </DeviceOptionCard>

</DeviceOptionsGrid>

</DeviceLayout>

---

## Roku

<DeviceLayout>

<DeviceOptionsGrid>

  <DeviceOptionCard
    id="owncasts-roku"
    title="Owncasts for Roku"
    badge="Recommended"
    difficulty="easy"
    screenshot="/images/devices/roku/owncasts-roku-home.jpg"
    screenshotAlt="Owncasts for Roku home screen"
    summary="Use the official Owncasts app to browse the Owncast directory directly on your Roku."
  >
    
      Browse the Owncast directory directly on your Roku.
      Official app built for the Roku platform.
      Simple interface designed for TV remotes.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Install the Owncasts for Roku from the Roku Channel Store.
      2. Launch the application.
      3. Browse for the stream you wish to watch.
      4. Select a stream to start watching.

    </details>

    <StoreButton
      url="https://channelstore.roku.com/details/2179326b6b85869a1a3a18d48ca76de6/owncasts"
      type="roku"
    />

  </DeviceOptionCard>

  <DeviceOptionCard
    id="roku-airplay"
    title="AirPlay to Roku"
    difficulty="medium"
    screenshot="/images/devices/roku/airplay-setup.jpg"
    screenshotAlt="AirPlay setup screen on Roku"
    summary="Stream from your iPhone or Mac to your AirPlay-compatible Roku device."
  >
    
      Works with newer Roku devices that support AirPlay.
      Stream from iPhone, iPad, or Mac.
      No additional Roku apps required.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Open the Owncast stream you want to watch on your iPhone or Mac computer.
      2. Play the Owncast stream.
      3. Press the **AirPlay** button.
      4. Select your Roku device.

    </details>

    For more details, visit [Apple's AirPlay documentation](https://support.apple.com/en-us/HT204289).

  </DeviceOptionCard>

</DeviceOptionsGrid>

</DeviceLayout>

---

## Samsung Smart TVs

<DeviceLayout>

<DeviceOptionsGrid>

  <DeviceOptionCard
    id="browser-samsung"
    title="Built-in Internet Browser"
    difficulty="hard"
    summary="Try Samsung's preinstalled Internet app to open an Owncast stream directly on the TV."
  >
    
      Samsung ships a preinstalled browser app called Internet.
      Browser capability and video support vary by model and firmware.
      No guarantees of compatibility.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Press **Home**, move left in Smart Hub, select **Media**, then open the **Internet** app.
      2. Navigate to your Owncast server URL.
      3. Try to play the stream directly in the browser.

      **Note:** TV browsers are limited compared with a phone or computer, so web video playback may not work reliably.

    </details>

  </DeviceOptionCard>

  <DeviceOptionCard
    id="casting-samsung"
    title="Screen Mirroring/Casting"
    difficulty="medium"
    screenshot="/images/devices/samsung-tv/screen-mirroring.png"
    screenshotAlt="AirPlay device selection screen"
    summary="Use screen mirroring from your phone or computer to display Owncast streams."
  >
    
      Works with Samsung's Smart View app or built-in screen mirroring.
      Requires a compatible smartphone or computer.
      May introduce some latency.
    

    <details>
      <summary>Show step-by-step instructions</summary>

      1. Ensure your Samsung TV and device are on the same Wi-Fi network.
      2. On your phone or computer, open the Owncast stream.
      3. Use screen mirroring features:
         - **Android**: Use Smart View or Screen Mirroring
         - **iOS**: Use AirPlay (if supported by TV)
         - **Windows**: Use Project/Cast to Device
      4. Select your Samsung TV from the list of available devices.

    </details>

  </DeviceOptionCard>

  <DeviceOptionCard
    id="external-device-samsung"
    title="External Streaming Device"
    badge="Recommended"
    difficulty="easy"
    screenshot="/images/devices/roku/owncasts-roku-home.jpg"
    screenshotAlt="Owncasts for Roku home screen"
    summary="Connect a dedicated streaming device to your Samsung TV for better Owncast compatibility."
  >
    
      Much more reliable than built-in Samsung TV apps.
      Wide variety of compatible apps and options.
      Better long-term support and updates.
    

    Consider connecting one of these devices to your Samsung TV:
    - Apple TV
    - Roku
    - Amazon Fire TV Stick
    - Google Chromecast
    - NVIDIA Shield TV

    Then follow the instructions for your chosen streaming device.

  </DeviceOptionCard>

</DeviceOptionsGrid>

</DeviceLayout>

---

## Web Browsers

## Web Player

The Owncast web video player has a handful of keyboard shortcuts you can use.

| Action             | Shortcut   |
| ------------------ | ---------- |
| Play/Pause         | _Spacebar_ |
| Volume up          | _0_        |
| Volume down        | _9_        |
| Mute               | _m_        |
| Toggle full screen | _f_        |
| Toggle chat        | _c_        |

Shortcuts do not fire while you are typing in chat or another text field.