IPTV to Jellyfin with Dispatcharr
Turning flat M3U playlists into proper Live TV with a guide.
I had a couple of large IPTV playlists and a Jellyfin server. I wanted the channels as proper Live TV with a guide, instead of a flat M3U file dumped into a player. Dispatcharr bridges the gap.
One rule first. Use only IPTV sources you are allowed to use. This post is about the plumbing, and it takes no position on where your playlists come from.
What Dispatcharr does
Dispatcharr is open source under AGPL v3. It manages IPTV streams, guide data and VOD. Its README lists these features: channel filtering, a DVR, XMLTV, Schedules Direct or dummy guide data, ffmpeg output profiles, failover, multiple users, plugins and VPN routing through a container such as Gluetun.
For my purposes, three things matter:
- It ingests M3U playlists and XMLTV guide data.
- It lets you dedupe and organize channels.
- It emulates an HDHomeRun tuner, so Plex, Emby or Jellyfin see it as one. Jellyfin also reads its XMLTV guide natively.
It proxies the streams too, so every client hits one stable endpoint.
Install
The README gives two lines:
docker pull ghcr.io/dispatcharr/dispatcharr:latest
docker run -d -p 9191:9191 --name dispatcharr -v dispatcharr_data:/data ghcr.io/dispatcharr/dispatcharr:latestThe web interface answers on port 9191.
The docker folder in the repository also holds compose files. docker-compose.aio.yml is a single container and the one the project recommends to start with. docker-compose.yml splits Dispatcharr, Celery, Redis and Postgres into separate services. docker-compose.dev.yml is for development.
Streams are not channels
This confused me at first. Importing an M3U creates streams. The lineup, and so Jellyfin, only shows channels. You generate channels from streams.
If you import a playlist and see an empty lineup, this is why. Create channels from the streams you want, then look again.
Dedupe early
Dedupe before anything else. About 2,000 raw streams collapsed to about 550 real channels once I merged the duplicate sources into failover groups. A channel with three sources then falls back to the next one when the first one dies.
Doing this later, after Jellyfin has mapped the guide, means mapping twice.
Behind a VPN
Fetching IPTV is best done through a VPN. So Dispatcharr runs inside the network namespace of a gluetun container. Every upstream request leaves through the tunnel. Jellyfin reaches Dispatcharr on the internal network.
The pattern, from the gluetun wiki, is network_mode: "service:gluetun" on the second service. A sketch:
services:
gluetun:
image: qmcgaw/gluetun
cap_add:
- NET_ADMIN
environment:
- VPN_SERVICE_PROVIDER=your-provider
# your provider's remaining settings go here, per the gluetun wiki
ports:
- "9191:9191"
dispatcharr:
image: ghcr.io/dispatcharr/dispatcharr:latest
network_mode: "service:gluetun"
volumes:
- dispatcharr_data:/dataThree details:
- The wiki says no
depends_onis needed. - Ports for the attached container belong on the gluetun service, because the two share one network stack. That is why 9191 sits under gluetun above.
- Jellyfin reaches Dispatcharr through the gluetun container, by its container name on the shared Docker network.
Adding the tuner in Jellyfin
- Open Admin Panel, then Live TV, then Tuner Devices, and click the plus.
- Choose Tuner Type HD Homerun.
- In Tuner IP Address, enter the address of the tuner in the form
http://HOST. With the setup above,HOSTis the gluetun container name and the port is the one you published.
Jellyfin lists two other tuner types, M3U Tuner and Other. M3U Tuner takes a file or URL, a user agent and a simultaneous stream limit, where 0 means unlimited. It also has an auto-loop option for live streams. Pointing an M3U tuner straight at a playlist works as a fallback. It costs more CPU.
Guide data
- Open Admin Panel, then Live TV.
- Click the plus beside TV Guide Data Providers.
- Choose Schedules Direct, which is paid, or XMLTV. Choose one, not both.
- For XMLTV, enter the guide address from Dispatcharr.
Then map the channels. Click the three dots beside the provider and choose Map Channels. Click the pencil icon on each channel, pick the guide entry, and click the left arrow to save. Open the Live TV Guide page to confirm the mapping took.
Free IPTV is flaky
Plenty of channels are dead upstream. That comes from the source and not your setup. If a channel fails in Jellyfin, test its stream in Dispatcharr before you start debugging anything else. Failover groups help, because a second source covers a dead first one.
The result
Live TV with a guide, inside Jellyfin, from about 550 channels instead of 2,000 streams.