Skip to content

Take control over your live stream video by running it yourself. Streaming + chat out of the box.

docs: rewrite FEDERATION.md as an external FEP-67ff interoperability document

Gabe Kangas4f6d881fc8a2
diff --git a/FEDERATION.md b/FEDERATION.md
index 20e3494d0f..272059e630 100644
--- a/FEDERATION.md
+++ b/FEDERATION.md
@@ -1,8 +1,10 @@
# Federation
-This document describes how Owncast federates with other ActivityPub servers, following [FEP-67ff](https://codeberg.org/fediverse/fep/src/branch/main/fep/67ff/fep-67ff.md).
+This document describes how Owncast federates with other ActivityPub servers, following [FEP-67ff](https://codeberg.org/fediverse/fep/src/branch/main/fep/67ff/fep-67ff.md). It is intended to help operators and developers of other Fediverse software interoperate with Owncast.
-## Supported Federation Protocols and Standards
+Owncast is a self-hosted live streaming server. Each instance federates as a single actor representing its live stream, broadcasting go-live announcements and posts to its followers. It does not present a social timeline and does not follow individual fediverse accounts. Servers can, however, list one another's live streams through the [featured-streams](#owncast-live-stream-status) protocol.
+
+## Supported federation protocols and standards
- [ActivityPub](https://www.w3.org/TR/activitypub/) (Server-to-Server)
- [WebFinger](https://webfinger.net/)
@@ -15,157 +17,150 @@ This document describes how Owncast federates with other ActivityPub servers, fo
- [FEP-f1d5: NodeInfo in Fediverse Software](https://codeberg.org/fediverse/fep/src/branch/main/fep/f1d5/fep-f1d5.md)
- [FEP-044f: Consent-respecting quote posts](https://codeberg.org/fediverse/fep/src/branch/main/fep/044f/fep-044f.md)
-## Actor
+## ActivityPub in Owncast
+
+### Actor
-Owncast servers present as a single `Service` actor (not `Person`). Each Owncast instance has one actor representing the live stream.
+Each Owncast instance presents as a single `Service` actor (not `Person`) representing the live stream. The actor profile includes:
-The actor profile includes:
- `icon`: Server logo/avatar
-- `image`: Profile banner image
-- `summary`: Server description (HTML)
+- `image`: Profile banner image (currently the same asset as `icon`)
+- `summary`: Server description, emitted verbatim as configured
- `attachment`: Array of `PropertyValue` objects containing social links and metadata
- `tag`: Hashtags describing the server content
-- `manuallyApprovesFollowers`: `true` if the server operates in private mode
+- `manuallyApprovesFollowers`: `true` when the server operates in private mode
- `discoverable`: Always `true`
-Owncast actors do not follow other actors. The `following` collection endpoint returns 404.
+Owncast does not expose a `following` collection; that endpoint returns `404`. It does not follow individual fediverse accounts, but it does follow other servers as part of the [featured-streams](#owncast-live-stream-status) directory protocol described below.
-## Activities
+### Activities
-| Activity | Object | Send | Receive | Notes |
-|----------|--------|:----:|:-------:|-------|
-| `Create` | `Note` | Yes | Yes | Sent on go-live and manual fediverse posts. Qualifying inbound notes produce plugin mention or reply events only. |
-| `Update` | `Service` | Yes | No | Sent when server profile changes. |
-| `Update` | `Person` | No | Yes | Updates cached follower profile information. |
-| `Follow` | - | No | Yes | Queued for approval if private mode is enabled. |
-| `Accept` | `Follow` | Yes | No | Sent automatically unless in private mode. |
-| `Undo` | `Follow` | No | Yes | Removes the follower. |
-| `Like` | `Note` | No | Yes | Optionally displayed in live chat. |
-| `Announce` | `Note` | No | Yes | Optionally displayed in live chat. |
-| `QuoteRequest` | `Note` | No | Yes | A remote user asking to quote one of our posts (FEP-044f). |
-| `Accept` | `QuoteRequest` | Yes | No | Sent when the quoted post exists and quoting is allowed. Carries the `QuoteAuthorization` stamp IRI in `result`. |
-| `Reject` | `QuoteRequest` | Yes | No | Sent for unknown posts, while in private mode, or when quoting is disabled. |
+| Activity | Object | Send | Receive | Notes |
+| -------------- | -------------- | :--: | :-----: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Create` | `Note` | Yes | Yes | Sent on go-live and manual fediverse posts. Qualifying inbound notes produce plugin mention or reply events only. |
+| `Update` | `Service` | Yes | No | Sent when the server profile changes. |
+| `Update` | `Person` | No | Yes | Updates cached follower profile information. |
+| `Follow` | - | Yes | Yes | Received from followers (queued for approval in private mode; directory follows always require approval). Sent to other servers to feature their stream (featured-streams). |
+| `Accept` | `Follow` | Yes | Yes | Sent to accept an inbound follow. Received when a server accepts our featured-streams follow. |
+| `Reject` | `Follow` | Yes | Yes | Sent to reject or remove a follower. Received when a server rejects our featured-streams follow. |
+| `Undo` | `Follow` | Yes | Yes | Received to remove a follower. Sent to stop featuring a server. |
+| `Like` | `Note` | No | Yes | Optionally displayed in live chat. |
+| `Announce` | `Note` | No | Yes | Optionally displayed in live chat. |
+| `Offer` | - | Yes | Yes | Featured-streams live signal (see below). |
+| `Leave` | - | Yes | Yes | Featured-streams offline signal (see below). |
+| `QuoteRequest` | `Note` | No | Yes | A remote user asking to quote one of our posts (FEP-044f). |
+| `Accept` | `QuoteRequest` | Yes | No | Sent when the quoted post exists and quoting is allowed. Carries the `QuoteAuthorization` stamp IRI in `result`. |
+| `Reject` | `QuoteRequest` | Yes | No | Sent for unknown posts, while in private mode, or when quoting is disabled. |
-Owncast is a broadcast-only service. It does not follow other actors. Inbound posts are not displayed as a social timeline or federated onward.
+Owncast does not display inbound `Create(Note)` activities as a social timeline and does not federate them onward. Qualifying mentions and replies are delivered only to server plugins.
-## Notes
+### Owncast live stream status
-Posts from Owncast are `Note` objects with:
+Owncast servers can list one another's live streams in a lightweight directory built on standard ActivityPub activities plus a small JSON-LD extension in the `https://owncast.online/ns#` namespace. A directory follows the servers it features; each featured server then signals its live and offline transitions to its directory followers.
-- `content`: HTML-formatted text with linked hashtags
-- `attachment`: `Image` object with stream thumbnail (for go-live posts)
-- `tag`: Array containing `Hashtag` and `Mention` objects
-- `sensitive`: `true` if the stream is marked NSFW
-- `interactionPolicy`: Declares that anyone may quote the post (`canQuote` with `automaticApproval` set to the public collection), attached to public posts unless the operator disables quoting
+Using this mechanism, a standalone, custom, directory can display a list of currently live streams, their status, and their metadata. The protocol is open, so third-party ActivityPub implementations can act as directories that list Owncast streams.
-### Go-Live Announcements
+**Following (listing a stream).** A directory sends a `Follow` whose `actor` is the directory and whose `object` is the target server's actor, carrying the extension property `https://owncast.online/ns#directory: true`. This marker distinguishes a directory listing from an ordinary personal Fediverse follow. A directory follow always requires operator approval, even on otherwise public instances. The target replies with `Accept(Follow)` once approved, or `Reject(Follow)`; it may later send `Reject(Follow)` to drop the listing, and the directory may send `Undo(Follow)` to stop featuring.
-When a stream starts, Owncast sends a `Create(Note)` containing:
-- The configured go-live message (or default announcement)
-- A thumbnail image of the stream
-- Hashtags configured for the server
-- A link to watch the stream
+**Live and offline signals.** Once the follow is accepted, the Owncast server delivers stream-status activities to its directory followers only (never personal account followers): `Offer` when the stream goes live (at go-live and periodically on a timer) and `Leave` when it goes offline. Both use the sending server's base URL (`scheme://host`) as the activity `object` and attach stream metadata as JSON-LD extension properties:
-### Hashtags
+| Property (in `https://owncast.online/ns#`) | Meaning |
+| ------------------------------------------ | ----------------------------------------------- |
+| `streamStatus` | `live` or `offline` |
+| `streamTitle` | Current stream title |
+| `streamDescription` | Stream or server description |
+| `serverName` | Server display name |
+| `logoUrl` | Server logo URL |
+| `thumbnailUrl` | Live preview thumbnail URL (present while live) |
+| `streamTags` | Array of stream tags |
-Hashtags use `toot:Hashtag` type and link to `https://directory.owncast.online/tags/{tag}` for discovery across Owncast instances.
+Received metadata is length- and count-clamped before storage.
-## Quote Posts
+**Interoperating with other software.** This protocol is open, but the two directions differ today. Owncast accepts a directory `Follow` (carrying the `ns#directory` marker) from any actor and will deliver `Offer`/`Leave` to it, so a third-party ActivityPub implementation can act as a directory that features Owncast streams. The reverse is currently Owncast-only: before following a server in order to feature it, Owncast validates that the server's NodeInfo reports `software.name == "owncast"` and `metadata.federation.featuredStreams >= 1`, so it will not feature a non-Owncast server.
-Owncast implements the quoted-server side of [FEP-044f](https://codeberg.org/fediverse/fep/src/branch/main/fep/044f/fep-044f.md): remote users can quote Owncast posts with the consent flow used by Mastodon 4.5+ and GoToSocial.
+### Notes
-- Public posts carry an `interactionPolicy` advertising that quoting is automatically approved for anyone.
-- An inbound `QuoteRequest` for a post this server authored is answered with an `Accept` whose `result` is the IRI of a stored `QuoteAuthorization` stamp. The stamp is dereferenceable at that IRI so third-party servers can verify the quote was approved.
-- A `QuoteRequest` for an unknown object, any request while private mode is enabled, or any request while the operator has disabled quoting receives a `Reject`.
-- Quoting can be turned off by the operator in the admin under the Social configuration ("Allow quotes"). It is enabled by default.
-- Owncast does not author quote posts and does not revoke previously issued stamps.
-
-## Plugin Integration
+Posts from Owncast are `Note` objects with:
-Inbound Fediverse activities can produce internal plugin events. These subscriptions are not external HTTP webhooks. A plugin must declare the `fediverse.inbound` permission to subscribe to `fediverse.follow`, `fediverse.like`, `fediverse.repost`, `fediverse.mention`, `fediverse.reply`, `fediverse.quote`, or `fediverse.activity`.
+- `content`: HTML-formatted text with linked hashtags
+- `attachment`: `Image` object with the stream preview, included on go-live posts when one is available
+- `tag`: Array containing `Hashtag` and `Mention` objects
+- `sensitive`: `true` on go-live posts when the stream is marked NSFW
+- `interactionPolicy`: Declares that anyone may quote the post (`canQuote` with `automaticApproval` set to the public collection), attached to public posts unless quoting is disabled or the server is in private mode
-All inbox requests must pass HTTP signature verification and the activity actor must share an origin with the verified signing key owner. After those checks, `fediverse.activity` receives the raw JSON object in addition to any specialized event the activity produces.
+When a stream starts, Owncast sends a `Create(Note)` go-live announcement containing the configured go-live message (defaulting to `I've gone live!`), the server's configured hashtags, a link to watch the stream, and the current stream preview image when one is available. If the operator clears the go-live message, no announcement is sent.
-Inbound `Create(Note)` activities have narrower requirements for mention and reply events. The `Create` must contain exactly one actor and exactly one `Note`. The note must have an IRI and exactly one `attributedTo` value that matches the activity actor. The resolved actor must also match the activity actor.
+Hashtags use the `Hashtag` type (Mastodon/`toot` vocabulary) and link to `https://owncast.directory/tags/{tag}` for discovery across Owncast instances.
-- A note whose first `inReplyTo` IRI identifies a locally authored post produces `fediverse.reply`.
-- Any other qualifying note produces `fediverse.mention` only when the `Create` or `Note` addresses the local actor in `to` or `cc`.
+### Quote posts
-These inbound notes are delivered to plugins. Owncast does not add them to a social timeline or federate them onward.
+Owncast implements the quoted-server side of [FEP-044f](https://codeberg.org/fediverse/fep/src/branch/main/fep/044f/fep-044f.md): remote users can quote Owncast posts with a consent flow.
-An accepted `QuoteRequest` produces `fediverse.quote` after Owncast signs and queues the acceptance. Its payload contains the remote actor and the target, which is the locally authored quoted post. Rejected quote requests do not produce this event.
+- Public posts carry an `interactionPolicy` advertising that quoting is automatically approved for anyone.
+- An inbound `QuoteRequest` for a post this server authored is answered with an `Accept` whose `result` is the IRI of a stored `QuoteAuthorization` stamp. The stamp is dereferenceable at that IRI so third-party servers can verify the quote was approved.
+- A `QuoteRequest` for an unknown object, any request while private mode is enabled, or any request while quoting is disabled receives a `Reject`.
+- Quoting is enabled by default and can be turned off by the operator.
+- Owncast does not author quote posts and does not revoke previously issued stamps.
-## Addressing
+### Addressing
Public posts are addressed to:
+
```json
{
- "to": ["https://www.w3.org/ns/activitystreams#Public"],
- "cc": ["{actor}/followers"]
+ "to": ["https://www.w3.org/ns/activitystreams#Public"],
+ "cc": ["{actor}/followers"]
}
```
-Owncast supports sending direct messages to specific actors (used for replying to engagement). These include the recipient in `cc` with a corresponding `Mention` tag for Mastodon compatibility.
+Owncast can send direct messages to specific actors (used for replying to engagement). These address the recipient in `to` with a corresponding `Mention` tag for Mastodon compatibility.
+
+### HTTP Signatures
-## HTTP Signatures
+- **Outbound**: All `POST` requests are signed using RSA-SHA256. Signed headers are `(request-target)`, `host`, `date`, and `digest`. A fresh signature is generated for every delivery attempt.
+- **Inbound**: Activities are accepted over HTTP (`202 Accepted`) and verified asynchronously. Only activities carrying a valid HTTP signature are processed; unsigned or invalidly signed activities are discarded without being acted on.
+- **GET requests** to the actor, outbox, and followers endpoints do not require signatures.
-**Outbound**: All POST requests are signed using RSA-SHA256. Signed headers: `(request-target)`, `host`, `date`, `digest`.
+### Private mode
-**Inbound**: All POST requests to the inbox must have a valid signature. Unsigned requests are rejected.
+Owncast can operate in private mode, where:
-**GET requests** to actor, outbox, and followers endpoints do not require signatures.
+- `manuallyApprovesFollowers` is `true` on the actor
+- Follow requests are queued for operator approval
+- `Accept` is only sent after manual approval
-## Outbound Delivery
+### Blocking
-Outbound activities are stored in SQLite before the enqueue operation returns. The queue stores the unsigned payload and creates a fresh HTTP signature for every attempt.
+Owncast supports blocking at both the domain and individual actor level. Inbound activities from a blocked domain or a disabled actor are discarded without being processed, and a rejected or blocked follower is removed from future outbound delivery.
-Network errors, timeouts, `401`, `408`, `425`, `429`, and server errors except `501` are retried up to 16 times with exponential backoff and jitter. `Retry-After` is honored when it requests a longer delay. Other client errors and `501` are recorded as permanent failures.
+### Interoperability notes
-Featured-stream status updates are coalesced per destination. Only the newest pending live or offline state is retained. Follow approvals and pending outbound follows are committed in the same transaction as their delivery record.
+- Owncast uses the `Service` actor type, not `Person`.
+- Owncast does not follow individual fediverse accounts and exposes no `following` collection, but servers follow one another to build the [featured-streams](#owncast-live-stream-status) directory.
+- Inbound `Create(Note)` activities are not shown as timeline posts or federated onward. Qualifying mentions and replies are delivered only to plugins.
+- Engagement (`Like`, `Announce`) can be displayed in the live chat if enabled.
+- The `sensitive` flag indicates NSFW content for the entire stream.
## WebFinger
-Actor discovery via `/.well-known/webfinger?resource=acct:{username}@{domain}`
+Actor discovery is available via `/.well-known/webfinger?resource=acct:{username}@{domain}`.
Response links include:
-- `self` (application/activity+json): Actor document
+
+- `self` (`application/activity+json`): Actor document
- `http://webfinger.net/rel/profile-page`: Web profile
- `http://webfinger.net/rel/avatar`: Profile image
-- `alternate` (application/x-mpegURL): HLS stream URL
-
-The HLS stream link allows clients to discover the live stream URL directly from WebFinger.
+- `alternate` (`application/x-mpegURL`): HLS stream URL, allowing clients to discover the live stream directly from WebFinger
## NodeInfo
-Available at `/.well-known/nodeinfo` with NodeInfo 2.0 at `/nodeinfo/2.0`.
+NodeInfo discovery is available at `/.well-known/nodeinfo`, with NodeInfo 2.0 served at `/nodeinfo/2.0`. Additional related endpoints:
-Additional endpoints:
- `/.well-known/x-nodeinfo2`: Extended format
- `/api/v1/instance`: Mastodon-compatible instance information
- `/.well-known/host-meta`: WebFinger discovery
-## Private Mode
-
-Owncast can operate in private mode where:
-- `manuallyApprovesFollowers` is `true` on the actor
-- Follow requests are queued for admin approval
-- `Accept` is only sent after manual approval
-
-## Blocking
-
-Owncast supports blocking at the domain and individual actor level. Blocked entities:
-- Cannot deliver to the inbox (requests rejected)
-- Do not receive activities from the server
-
-## Interoperability Notes
-
-- Owncast uses `Service` actor type, not `Person`
-- There is no `following` collection (Owncast does not follow accounts)
-- Owncast does not display inbound `Create(Note)` activities as social timeline posts or federate them onward. Qualifying mentions and replies are delivered only to plugins
-- Engagement (`Like`, `Announce`) can be displayed in the live chat if enabled
-- The `sensitive` flag indicates NSFW content for the entire stream
-
-## Additional Resources
+## Additional documentation
- [Owncast Documentation](https://owncast.online/docs/)
- [ActivityPub Specification](https://www.w3.org/TR/activitypub/)