obs-multisite
Streaming multisitio para iglesias, mediante almacenamiento que posees.
¿Qué es
dos plugins OBS Studio en un módulo: un encoder en el campus principal que publica el programa como segmentos CMAF, y un decoder en cada campus satélite que recibe, bufferiza profundamente y reproduce con timeslipping por campus. No hay servidor central, base de datos ni proveedor — el bucket es un almacén de archivos tonto, y toda la inteligencia está en los bordes.
MAIN CAMPUS YOUR BUCKET EACH CAMPUS
┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐
│ OBS + Multisite │upload ────→│ S3-compatible │ │ OBS + Multisite │
│ Encoder │ │ bucket you own │ │ Decoder │
│ │ ←── poll │ │ │ or │
│ capture → encode │ │ rooms/{room}/... │ │ Raspberry Pi 5 │
│ → CMAF → queue │ │ events/{ulid}/... │ │ campus player │
│ → upload, retry │ │ no server, no DB │ │ deep buffer │
└────────────────────┘ └────────────────────┘ └────────────────────┘
every campus polls the same objects
| Piece | Runs on | What it does |
|---|---|---|
| Multisite Encoder | OBS at the main site | Muxes OBS's own encoded frames into CMAF segments, writes each one to a durable local queue before it goes anywhere, then uploads with retry. A dropped link fills the queue rather than the gap. |
| Multisite Decoder | OBS at each campus | Finds what is live, downloads ahead of playout, verifies every segment, and exposes the feed as sources — the picture, plus each audio track separately, for local mixing and in-ears. |
| Campus player | A Raspberry Pi 5, no PC | The same receive core, headless: HDMI out, a browser control page, timeslipping, and AES67 onto the network if the room wants it. |
| Simulcast relay | Any Docker host | Reads the same files and pushes them to YouTube, Facebook or any RTMP/SRT destination. Optional, and never in the path between the sites. |
| Companion module | Bitfocus Companion | Its own repository: buttons and feedback on a Stream Deck, driving OBS or an appliance. |
Design priority, in order: reliability, then quality, then simplicity, and latency last — a satellite that is a minute behind but never drops is worth far more than one that is two seconds behind and stutters.
At a glance
- Latency — minutes, on purpose. A campus can hold the picture for its own welcome and then resume exactly where it paused, or stay a set number of minutes behind live all event. Latency is what this project spends to buy reliability, and it spends it willingly.
- Bandwidth — about 2.7 GB an hour of event at 6 Mbps. Every campus reads the same objects from the same bucket, so what it costs is your provider's egress policy — Cloudflare R2 charges none.
- Audio — up to all 6 OBS tracks: the programme mix, mics on their own tracks, a click for the band. They travel in the same fragment as the picture, so they cannot drift from it or from each other.
- Video — whatever OBS already encodes, H.264 or HEVC, through x264, NVENC, QuickSync or AMF.
- Network — outbound HTTPS only. No inbound ports, no port forwarding, no static IP, no VPN, and no firewall rules to negotiate with a building's IT.
- Retention — yours to set, in your provider's own console, and it doubles as your DVR depth: a campus can rewind as far back as it allows. Seven days is the design default, and nothing here deletes anything by itself.
- Platforms — Windows, macOS (Apple Silicon) and Linux at both ends, plus an ARM64 Raspberry Pi 5 tier for campuses that would rather not run a PC at all.
Quick start
A campus with no PC — one command on a fresh Raspberry Pi 5 running Raspberry Pi OS:
curl -fsSL --retry 5 https://raw.githubusercontent.com/stageaudioworks/obs-multisite/main/scripts/player/install.sh | sudo bashBoth ends running OBS — install the plugin from Releases, then:
- Set retention on the bucket first. Nothing in this project deletes anything by itself: add a lifecycle rule for
events/and another forrooms/. - Main site. Open the Multisite Encoder dock, enter the bucket details, pick a feed name, press Go live.
- Each campus. Open the Multisite Decoder dock, enter the same bucket, add a Multisite Source (Decoder) for the same feed name, then Load event and Play.
- Lock the event so nothing gets clicked by accident mid-service.
About twenty minutes, bucket included. The full walkthrough is QUICKSTART.md, and the readable introduction is the project website.
Why this exists
The longer story — who this is for, what it deliberately is not, what it asks of your network, and the licensing position.
This project is developed by the projects team at Stage Audio Works, a worship AVL integrator working across Africa, to support churches that are growing into multiple locations.
Multisite streaming is a solved problem if you are a large church in a well-connected part of the world. The commercial platforms that solve it are good, and the teams behind them have earned their place. But they are largely unavailable outside the developed world, and where they are available the recurring cost is out of reach for a congregation whose entire annual AV budget is smaller than a year of subscription.
What this is not
It is not a managed event. The commercial products are, and that is worth paying for. Someone answers the phone. Someone watches the infrastructure. Someone ships you a decoder that boots and works. If your church can afford one and it is available where you are, you should probably buy it.
This is a set of tools instead. Setting it up requires a reasonably technical person, or support from an integrator with the relevant expertise. There is no support contract, no uptime guarantee, and no one to call. What there is instead: you own your storage, you own your content, your ongoing cost is a few dollars a month of object storage, and nothing can be taken away from you or priced beyond your reach later.
It is not low latency, and it is not two-way. This carries an event from one site to others with a delay measured in tens of seconds. It cannot support a live conversation between campuses, a two-way interview, or anything else where people need to respond to each other in real time. For that, use SRT or WebRTC: both are in OBS already, and there are many good hardware products built on them. Those approaches trade differently, sitting much closer to the raw condition of the connection at the moment you need it. (The relay can send SRT — see Streaming to the public — but it sends from the bucket, minutes behind, so it inherits this project's trade rather than SRT's own.)
This project takes the opposite trade deliberately. Content is written to disk before it is sent, sent again until the storage confirms it, and buffered deeply at the far end before it is played. Minutes of the event can be held at the satellite in advance, so an outage part-way through is something the congregation never sees. Latency is the price, and for an event being relayed rather than a conversation being held, it is a price worth paying.
What it asks of your network
Very little, and this is deliberate. Everything moves over ordinary HTTPS to object storage. There are no inbound connections, no port forwarding, no static IP, no VPN, and no firewall rules to negotiate with a building's IT.
That means it works on connections that would defeat a direct stream: mobile data, LEO satellite, consumer fibre, and networks behind carrier-grade NAT. If a laptop at the site can load a web page, it can usually send or receive an event.
On intellectual property
This is a clean-room implementation built on published, open standards: CMAF fragmented MP4, the S3 object API, and OBS Studio's public plugin interface. It is not derived from, and does not reverse-engineer, any commercial product.
Where our design resembles existing products, it is because we are solving the same problem under the same constraints and arriving at similar answers, or because we have deliberately followed conventions that operators already understand. Familiarity is a feature in a room where a volunteer is running the event.
It is released under the GPLv3 in support of kingdom expansion and the enabling of local churches: free for any church to run, adapt and keep running — and if you distribute a changed version, those changes have to reach the next church too. That is the whole point of the choice. There is no intent to tread on anyone's intellectual property. If you believe something here does, please raise it with us and we will address it properly.
Status
Built and bench-proven; has not yet carried a real congregation's event. That is the one sentence that matters. A six-hour soak ran end to end repeatedly with zero upload failures and A/V in sync throughout; the pi appliance and the relay have each run their own multi-hour tests. None of them was a Sunday morning with people in the room. See the full current-state record for the numbers.
What works
- Durable store-and-forward upload: nothing is lost through an outage, a crash, or a mid-event restart. Six-hour soak: 3,661 segments, >15 GB, zero retries, zero failures, 10 lagged frames of 658,837.
- CMAF segments from any OBS encoder — H.264 or HEVC via x264, NVENC, QuickSync or AMF.
- Satellite receive with a deep local buffer, checksum verification, and timeslipping — hold, resume, catch up, scrub, jump to a marker. Playback waits until a minute is buffered before starting, so the picture never chases the live edge.
- Multi-track audio, up to 6 tracks, in the same fragment as the picture, exposed at the satellite as separate sources.
- AES67 audio on the appliance — sound onto the network instead of HDMI, switched from the player's page. Eight channels on a bench Pi, and PTP proven into a receiving console over a 24-hour run. See AES67 audio.
- One feed, several pictures — a 2×1 or 2×2 composite arrives as discrete, already-cropped sources, downloaded once and decoded once. See Choosing a satellite.
- Event browsing — the decoder lists a room's events, marks which is on air, which finished and which was cut short, and plays any of them.
- Finished and interrupted events play as video-on-demand from the beginning.
- Operator docks in plain language, plus hotkeys.
- Storage management from the encoder dock — list, size, delete by event or by age, with confirmation and a verification pass; the live event is never offered.
- A remote-control page on both sides — the campus player's interface, served from the plugin or the appliance, polled twice a second. Trusted network only: no password, no TLS.
- Public simulcast — a container reads the same segments and pushes to YouTube, Facebook or any RTMP/SRT destination, minutes behind on purpose. See Streaming to the public.
What does not, yet — see Known gaps.
How it works
The encoder muxes OBS's encoded frames into CMAF fragments and writes them to a bucket. The decoder polls two small JSON files to discover what is live, then downloads segments ahead of playback into a local cache.
rooms/{room_id}/live.json which event is live in this room
rooms/{room_id}/events/{ulid}.json one entry per event, so a room's recordings list in a single request
events/{ulid}/event.json codec config, audio layout, start time
events/{ulid}/init.mp4 codec configuration for the event
events/{ulid}/segments/…m4s the media
events/{ulid}/manifest.json rolling window of confirmed segments
events/{ulid}/markers.json the main site's cues
events/{ulid}/cues/{site}.json one object per site that has set a cueThe invariant that makes it reliable: a segment is listed in the manifest only after the bucket has confirmed it stored. If a decoder can see an entry, the object exists.
Repository layout
| Path | Description |
|---|---|
| .github/ | CI workflows and GitHub Actions |
| cmake/ | CMake build configuration |
| data/ | Test data and fixtures |
| docs/ | Documentation (OPERATOR.md, SATELLITE.md, STREAMING.md, DEVELOPER.md) |
| relay/ | Simulcast relay container code |
| scripts/ | Installation and utility scripts |
| site/ | Static website source (stageaudioworks.github.io) |
| src/ | C++ plugin implementation |
| test-data/ | Test fixtures and sample content |
| tests/ | Unit and integration tests |
Known gaps
See readme-current-state.md for the full list.
Roadmap
See roadmap.md for planned improvements.