Take control over your live stream video by running it yourself. Streaming + chat out of the box.
HTML activitypubbroadcastingchatdecentralizedfederationfediversegolanghacktoberfesthlslivelivestreamowncastrtmpself-hostedstreaming-videovideo
chore(doc): add FEDERATION.md
Gabe Kangas082b6822f174
diff --git a/FEDERATION.md b/FEDERATION.mdnew file mode 100644index 0000000000..925f909806--- /dev/null+++ b/FEDERATION.md@@ -0,0 +1,142 @@+# 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).++## Supported Federation Protocols and Standards++- [ActivityPub](https://www.w3.org/TR/activitypub/) (Server-to-Server)+- [WebFinger](https://webfinger.net/)+- [HTTP Signatures](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures)+- [NodeInfo](https://nodeinfo.diaspora.software/)++## Supported FEPs++- [FEP-67ff: FEDERATION.md](https://codeberg.org/fediverse/fep/src/branch/main/fep/67ff/fep-67ff.md)+- [FEP-f1d5: NodeInfo in Fediverse Software](https://codeberg.org/fediverse/fep/src/branch/main/fep/f1d5/fep-f1d5.md)++## Actor++Owncast servers present as a single `Service` actor (not `Person`). Each Owncast instance has one actor representing the live stream.++The actor profile includes:+- `icon`: Server logo/avatar+- `image`: Profile banner image+- `summary`: Server description (HTML)+- `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+- `discoverable`: Always `true`++Owncast actors do not follow other actors. The `following` collection endpoint returns 404.++## Activities++### Activities Owncast Sends++| Activity | When | Notes |+|----------|------|-------|+| `Create(Note)` | Stream goes live | Contains stream title, thumbnail, hashtags |+| `Create(Note)` | Admin posts to fediverse | Manual posts from admin interface |+| `Update(Service)` | Profile changes | Sent when server name, description, or logo changes |+| `Accept(Follow)` | Follow request received | Automatic unless in private mode |++### Activities Owncast Accepts++| Activity | Response |+|----------|----------|+| `Follow` | Adds follower; sends `Accept` (or queues for approval in private mode) |+| `Undo(Follow)` | Removes follower |+| `Like` | Acknowledged; optionally displayed in chat |+| `Announce` | Acknowledged; optionally displayed in chat |+| `Update(Person)` | Updates cached follower information |++Owncast does **not** accept `Create` activities. It is a broadcast-only service and does not display posts from other servers.++## Notes++Posts from Owncast are `Note` objects with:++- `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++### Go-Live Announcements++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++### Hashtags++Hashtags use `toot:Hashtag` type and link to `https://directory.owncast.online/tags/{tag}` for discovery across Owncast instances.++## Addressing++Public posts are addressed to:+```json+{+ "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.++## HTTP Signatures++**Outbound**: All POST requests are signed using RSA-SHA256. Signed headers: `(request-target)`, `host`, `date`, `digest`.++**Inbound**: All POST requests to the inbox must have a valid signature. Unsigned requests are rejected.++**GET requests** to actor, outbox, and followers endpoints do not require signatures.++## WebFinger++Actor discovery via `/.well-known/webfinger?resource=acct:{username}@{domain}`++Response links include:+- `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.++## NodeInfo++Available at `/.well-known/nodeinfo` with NodeInfo 2.0 at `/nodeinfo/2.0`.++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 accept incoming posts (`Create` from remote actors is ignored)+- Engagement (`Like`, `Announce`) can be displayed in the live chat if enabled+- The `sensitive` flag indicates NSFW content for the entire stream++## Additional Resources++- [Owncast Documentation](https://owncast.online/docs/)+- [ActivityPub Specification](https://www.w3.org/TR/activitypub/)+- [Fediverse Enhancement Proposals](https://codeberg.org/fediverse/fep)