mediamtx-failover-controller

Automatic failover for redundant SRT streams ingested by MediaMTX, with live source-switching in OBS Studio via obs-websocket.

Built for drop-free IRL / mobile live streaming: send the same feed over several independent links (e.g. multiple cellular modems or phones) as separate SRT streams into one MediaMTX server. This controller continuously scores each stream's health and keeps OBS showing whichever stream is healthy. If the active link freezes or dies it switches to a good one in ~3 seconds; when your preferred link recovers it switches back — with hysteresis and a cooldown so it never flaps.

This is the redundancy half of a no-dropout rig: you get "if one link drops, the show continues" with zero extra infrastructure — no VPS, works over IPv6.

How it works

sender A ─ SRT ─┐
sender B ─ SRT ─┤→ MediaMTX (paths: linkA, linkB, …) ──RTSP──> OBS (one source per stream)
sender C ─ SRT ─┘            │ HTTP API :9997                      ▲
                       controller.py ─ polls API, scores health, picks ACTIVE ─┘
                                     └─ obs-websocket: enable only the ACTIVE source

Per-stream health = online / bitrate / freeze (no new bytes for N polls) / decode errors / RTT & loss (from MediaMTX's SRT stats). A small state machine (GOOD / DEGRADED / DEAD, priority order, cooldown) picks the single active stream and drives OBS.

Files

• controller.py — the monitor + failover state machine. Runs headless (logs decisions to a file) or with a live terminal dashboard. OBS switching is optional — without OBS it still tracks and logs which stream is active.
• obs_helper.py — creates an OBS scene + one media source per stream automatically, and can screenshot the program output (handy for testing the switch).

Requirements

• MediaMTX with the HTTP API enabled (api: yes, default :9997) and paths that accept your SRT publishers.
• Python 3.
• For the OBS switching layer: OBS 28+ with the WebSocket server enabled, and pip install obsws-python.

Usage

1. Edit the config block at the top of controller.py (MediaMTX exe/config paths, the PRIORITY list of stream names, health thresholds, OBS host/port/scene).
2. Point your senders at MediaMTX with distinct stream IDs, e.g. srt://HOST:PORT?streamid=publish:linkA and ...publish:linkB.
3. (Optional, for OBS switching) python obs_helper.py setup to create the OBS scene + media sources (rtsp://localhost:8554/<stream>).
4. Run it:
   • python controller.py — supervise MediaMTX + live dashboard.
   • python controller.py --headless --no-supervise — just monitor an already-running MediaMTX (logs decisions).

Kill a stream and watch it fail over to a healthy one; bring it back and watch it return after the cooldown.

Why

Part of a personal project to build a no-dropout in-car IRL streaming setup over consumer cellular. Plain SRT over IPv6 is rock-solid per link; the hard part is surviving one link dropping mid-drive. This is the piece that makes that automatic.

License

MIT — see LICENSE.