The internal reference for how Owncast's federation actually works: architecture, pipelines, wire formats, security decisions, storage, configuration and testing. The protocol-level summary lives in FEDERATION.md in the repo (FEP-67ff format) and the user-facing doc is on owncast.online under Social features. This doc is for people working on the code.
Owncast uses sqlc to turn hand-written SQL into type-safe Go. You write the SQL, sqlc generates the Go. Two pieces work together:
Our web routing and API are defined by the OpenAPI specification. It defines the available web routes, API endpoints, handlers, requests, responses, and error objects. That gives us one source of truth for documentation, types, and routing.
Status (June 2026): Most of this plan has shipped. Services now live as standalone packages under services/ (chat, dispatcher, notifications, stream, transcoder, rtmp, storage, webhooks, activitypub, geoip, and more). The data layer is split into repositories under persistence/ (config, chat, user, auth, webhook, federated servers). The event bus landed as services/dispatcher, and dependencies are passed in explicitly through Deps structs rather than global getters (see pluginhost/pluginhost.go for a worked example). The notes below are kept as the original design record.
Most people never need to do this. When you change the web app and merge it into the develop branch, the bundling happens automatically. And if you are developing the web app locally, you are better off running npm run dev.
Owncast records viewer playback health through Common Media Client Data (CMCD), defined by CTA-5004. Players that expose CMCD contribute their own measurements. Players that do not are observed from completed HLS segment transfers when the observation is trustworthy.
This document gets you up and running for Owncast development. If you want more on contributing in non-technical ways too, read the Contributor Guide.
Common terms you will run into around Owncast.
A quick tour of the moving parts, so you know where your change belongs. You do not need to understand all of this to contribute, but a map helps. For where each piece lives in the source, see Where the Code Lives.
This is how we build components for the Owncast web UI. Use it when changing existing components or adding new ones. A shared pattern keeps the project readable and maintainable.
How Owncast runs plugins and how the plugin system is wired into the server.
Owncast is a do-ocracy run by a small group of volunteers. New changes are always welcome, and a little process up front keeps things smooth for everyone.
Owncast accepts one RTMP broadcaster, turns it into HLS playlists and MPEG-TS segments with ffmpeg, stores those files, and serves them from /hls/.
Please provide improvements and be patient with this document as we work through all the different use cases when it comes to localizing strings in the web UI.
Owncast is spread across a few repositories. Knowing which one holds what saves a lot of searching.
Owncast now supports custom plugins.