Home

polyemesis

Generated from docs/ — do not edit here. Run node scripts/publish-wiki.mjs --push to regenerate.

Self-hosted live multistreaming: ingest once, fan out to YouTube, Twitch, Facebook and Kick with a different audio mix per destination.

Getting it running

Install it, point an encoder at it, and put a certificate in front of it.

• Quickstart: from nothing to a live restream — Five minutes: run it, set a password, point OBS at the SRT ingest, name the tracks, add one destination, and check the fan-out is actually right.
• Install polyemesis — an SRT server on your own box — One binary and FFmpeg 6.0 or newer, built with SRT. Docker, the systemd unit, the macOS and Windows paths, and how to verify the install really works.
• OBS SRT setup: multitrack audio to one ingest — Sending OBS multitrack audio over SRT is a Custom Output on the Recording tab, not the Stream tab. Encoder settings that work, plus RTMP fallback.
• TLS certificates for a self-hosted SRT server — Let's Encrypt when the box has a public name, a built-in CA when it does not, and what changes behind a reverse proxy. Plus why HSTS is opt-in here.

The routing

The part the rest of the product exists to serve: a different audio mix per destination.

• Audio routing: a different mix per destination — Up to 32 tracks in, one FFmpeg filter graph per destination out. The mix matrix, per-cell gain, and how the two-mix egress is built.
• Renditions: one shared video encode — A named video profile several destinations share, for platforms that refuse your source. What it re-encodes, when it runs, and what passthrough costs.
• Encoding: what is copied and what is encoded — Video is stream-copied by default; audio is encoded once per destination mix. Where a GPU actually helps, rate control, frame rate, and the cost.
• Hardware encoding: NVENC, QSV, VA-API, AMF — GPU encoding for renditions, what each vendor needs, running it under Docker, and an explicit account of what this project has and has not observed.

Operating it

Configuration, platforms, upgrades, and what to do when it will not connect.

• Configuration: config.yaml and the web UI — Two places a setting can live, and they are not interchangeable. Every config.yaml key, its default, the data directory, and the environment variables.
• Streaming platforms: what can be automated — YouTube, Twitch, Kick, Facebook and Rumble. Anything taking RTMP or SRT works with a pasted key; this is what each platform's API lets you automate.
• Broadcasting from a file, on a schedule — Go live from a recorded file at a time you choose, with no encoder attached. A file:// pull ingest plus a schedule, and a failover playlist as filler.
• What a settings change restarts, and what it does not — The rule is mechanical: a value that reaches an FFmpeg command line replaces the process running it. What a restart costs, and what a save now tells you.
• Upgrading polyemesis and its database — Stop, replace the binary, start — the database migrates itself forward. What to back up first, the version-specific notes, and how to roll back.
• Troubleshooting: SRT, RTMP and audio problems — Organised by what you can observe. SRT handshake failures, an ingest that never goes live, a destination producing nothing, and audio that is wrong.

Automating it

Metrics, webhooks, MQTT and the HTTP API — everything that lets something else drive.

• Monitoring: Prometheus metrics and alerts — Everything the dashboard draws, as metrics. The endpoint and why it needs authentication, metric conventions, queries to start from, and built-in alerts.
• Lifecycle webhooks: one signed POST per event — A signed JSON POST when a stream starts or stops and when a destination goes live or drops. The envelope, verifying a signature, ordering and gaps.
• MQTT telemetry and Home Assistant — Retained state on an MQTT 5.0 broker, so a consumer that was offline still gets the current answer. The topic tree, the payloads, and Home Assistant.
• HTTP API reference — polyemesis /api/v1 — Everything the web UI does, it does through this API. Authentication, conventions, every route, the WebSocket, and a worked example end to end.

Understanding it

How it fits together, what it depends on, and how it compares.

• Architecture: relay hub, engines, FFmpeg children — Ingest once, fan out to N destinations. The process graph, the audio routing engine, the shared rendition encode, and the package layout.
• polyemesis FAQ — self-hosted multistreaming — What it is for, how it differs from Restreamer and restream.io, whether your video is re-encoded, how many destinations, and whether SRT is required.
• Testing polyemesis without OBS or a camera — FFmpeg only. Generate a multitrack SRT stream of distinct sine tones, route the tracks differently per destination, and measure what actually came out.
• Dependencies, and why each one is here — Why every Go and frontend dependency is present, why some obvious alternatives are not, and why FFmpeg is a subprocess rather than a linked library.
• polyemesis vs Restreamer, restream.io, obs-multi-rtmp — An honest comparison, including where polyemesis loses. Sourced from the competitors' own trackers and plan pages, with every claim dated.