brxdy22/m3u-failover repository overview

⁠Dispatcharr M3U Failover

A small proxy that gives a Dispatcharr⁠ M3U account several provider URLs.

Dispatcharr stores one server URL per account. This proxy gives each account a local port and forwards every request to the first working URL on that account's list. It is one Python file with no dependencies.

Docker image: brxdy22/m3u-failover⁠ (amd64 and arm64).

⁠What it does

• Fails over before playback starts. Connection errors, timeouts, 403 and 5xx answers move on to the next URL.
• Leaves account errors alone. 401, 458 and 460 (connection limit) are passed straight through, because another URL would give the same answer.
• Double-checks 404s. A 404 or 511 on a video is checked on other URLs, because a mirror can fail for every title while the others still work.
• Avoids hammering the provider. Attempts per request are capped. If everything fails, the account pauses for a while, and the pause doubles if failures continue.
• Tells a refused VPN exit from a missing title. When every URL answers 404 for a movie or episode, it asks a title that played before for one byte. If that is refused too, Gluetun AutoSwitch⁠ 1.7 or later moves the exit, and the same request plays on the new exit.
• Sorts URLs every night. The most reliable and fastest URLs move to the top of upstreams.conf. URLs are never removed.
• Edits from Dispatcharr. With the Failover Manager⁠ plugin (1.5 or later; called VOD Failover before 1.6), you can see and change each account's URLs on the plugin page.

Tested on Dispatcharr 0.33.0.

Works with Failover Manager⁠ and Gluetun AutoSwitch⁠. All three together cover provider URL failover, account failover for VOD, and VPN exit switching.

See Dispatcharr Failover Stack⁠ to install all three side by side.

⁠Install

1. Make a folder for the config, and copy upstreams.conf.example into it as upstreams.conf. Add your URLs.
2. Add the service from docker-compose.example.yml⁠ to your Compose file. Set network_mode to match your setup, and the volume to your config folder.
3. Start the container: docker compose up -d m3u-failover.
4. In Dispatcharr, set each account's Server URL to http://127.0.0.1:<port>, using the port from upstreams.conf.

The examples use brxdy22/m3u-failover:latest. To update, pull the image and start the container again: docker compose pull m3u-failover && docker compose up -d m3u-failover. Each release⁠ also has a version tag, for example brxdy22/m3u-failover:1.3.1.1, if you prefer to pin one.

To run it without the image, mount failover.py into python:3.12-alpine at /app/failover.py and use command: ["python", "-u", "/app/failover.py"].

Usernames and passwords stay in Dispatcharr. The proxy holds them in memory for the nightly sort, and never logs or saves them.

⁠Check it

# Table of accounts, URLs and current streams
docker exec m3u-failover python /app/failover.py --status

# Run the sort now
docker exec m3u-failover python /app/failover.py --sort-now

An account is skipped by the sort until Dispatcharr has sent a request through the proxy since it started.

⁠Settings

Set these as environment variables. The full list is at the top of failover.py.

GET /__drop_live on an account's port closes its live streams at once, so clients reconnect right after a VPN exit change instead of waiting for a read timeout. Gluetun AutoSwitch calls it after every switch.

GET /__before_move?hold=N on an account's port closes all its streams, VOD included, and holds new requests for up to 6 seconds while the exit moves. /__drop_live ends the hold early. Gluetun AutoSwitch 1.8.2 calls it just before every switch.

GET /__status shows stuck_slot_seconds for an account whose provider keeps answering with a connection limit (458 or 460) while nothing is streaming. During that time the proxy answers repeat requests itself, so the provider sees about one try every 15 seconds.

POST /__urls with {"urls": [...]} on an account's port replaces that account's URLs in upstreams.conf and uses them at once. Notes on URLs that stay are kept. It is accepted only from loopback, and only base URLs (scheme://host[:port]) without logins. The Failover Manager⁠ plugin 1.5 uses it to show and edit the lists from Dispatcharr. GET /__status lists the full URLs under urls.

GET /__vod_check asks the remembered titles for one byte and answers whether the exit is refused. Gluetun AutoSwitch calls it in the background while nobody is watching. Add ?forget=1 to also forget titles that were refused.

⁠Security

The proxy has no login of its own, so keep BIND on 127.0.0.1 unless you trust everything that can reach it.

Keep upstreams.conf out of Git. It is already in .gitignore.

⁠More by Brxdy22

• Failover Manager⁠: Retries a failed VOD stream on the next provider account that carries the title.
• Gluetun AutoSwitch⁠: Moves Gluetun to another VPN exit when streams slow down, VOD is refused or speed tests fail.
• Clean Titles⁠: Renames VOD movies and series to their official TMDB titles and tidies provider categories.
• Teamarr Assistant⁠: Tags regional sports networks with their teams and starts Teamarr generations when new streams appear.

⁠Release notes

See Releases⁠.

⁠Licence

MIT