🔧 Threadfin Configuration Guide 2026

Threadfin is a fork of xTeVe (inactive since 2022). It runs as a service between your IPTV provider and your media server.

What does it do?

• Combines multiple M3U / Xtream sources into a single playlist
• Merges and maps EPG XMLTV sources
• Emulates the HDHomeRun protocol (what Plex/Jellyfin expect)
• Buffers streams (FFmpeg or native streaming mode)
• Manages connection limits — prevents the provider from blocking you
• Filters channels — remove junk before it reaches Plex
• Custom channel logos and group names

version: "3"
services:
  threadfin:
    image: fyb3roptik/threadfin
    container_name: threadfin
    ports:
      - "34400:34400"
    volumes:
      - ./conf:/home/threadfin/conf
      - ./temp:/tmp/threadfin
    environment:
      - TZ=Europe/London
      - PUID=1000
      - PGID=1000
    restart: unless-stopped

Start and open

Run docker-compose up -d and open http://server-ip:34400/web/.

First login

By default there is no user — direct access. After that, go to Settings → User and create an admin (strong password!).

1. Tab Playlist
2. Click the "+" button
3. Name: e.g. "Provider X"
4. M3U URL: paste your URL
5. Update on start: on
6. Auto-update interval: 24h by default
7. Click Save and wait — channels are loaded

Multiple providers

Add multiple playlists — Threadfin combines them. Handy if you have 2 IPTV subscriptions or assemble your own XMLTV.

Xtream Codes instead of M3U?

Convert your Xtream credentials into an M3U URL: http://server.com/get.php?username=USER&password=PASS&type=m3u_plus&output=ts

1. Tab XMLTV
2. Click the "+" button
3. Name: e.g. "EPG.best"
4. URL: paste the XMLTV URL (see EPG sources)
5. Update interval: 12h (plenty)
6. Save

Multiple EPG sources

Add multiple XMLTVs — Threadfin merges them automatically. The first loaded source wins in case of a conflict.

Crucial: link each channel to an EPG entry, otherwise you get no program guide in Plex/Jellyfin.

Auto mapping

1. Tab Mapping
2. Select channels
3. Click "Set XMLTV" → choose source
4. Threadfin tries to match on name/tvg-id
5. Status column: ✅ matched or ⚠️ no match

Manually linking a channel to EPG

1. Click on the channel
2. XMLTV File: choose source
3. Channel ID: type the EPG channel id (e.g. bbcone.uk)
4. Save

Bulk actions

• Select 20+ channels → "Activate" to make them visible in Plex/Jellyfin
• "Deactivate" — hide trash channels
• "Set channel number" — for traditional channel numbering
• "Change group" — reorganize into categories

Settings → Buffer. Two options:

• FFmpeg — uses FFmpeg to buffer each stream. Recommended. Prevents buffering issues, more reliable.
• Streaming — direct pass-through. Lighter, but problematic with some streams.

For most users: enable FFmpeg mode.

FFmpeg buffer settings

• Buffer Size: 1024 KB (default is fine)
• Buffer Timeout: 1000 ms
• FFmpeg binary path: auto-detect or /usr/bin/ffmpeg

Settings → Streaming → Number of tuners. How many channels can stream simultaneously.

• Provider's connection limit: usually 3-5
• Set it to your provider's max
• Lower = safer (you won't get blocked)
• Plex/Jellyfin uses 1 tuner per simultaneous stream + 1 for DVR recording

Some providers block the default FFmpeg user-agent. Set a custom one:

Mozilla/5.0 (Linux; Android 10) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.45 Mobile Safari/537.36

Or: VLC/3.0.16 LibVLC/3.0.16

1. Plex → Settings → Live TV & DVR → Set Up Plex DVR
2. Plex automatically searches for HDHomeRun on the network → finds Threadfin on port 34400
3. Doesn't find it? Click "Don't see your device?" → manually: http://server-ip:34400
4. Select channels → Next
5. XMLTV: use Threadfin's XMLTV: http://server-ip:34400/xmltv/threadfin.xml
6. Continue → map channels → Done

1. Dashboard → Live TV → Add tuner → HDHomeRun
2. URL: http://server-ip:34400
3. Save
4. Add EPG → XMLTV → http://server-ip:34400/xmltv/threadfin.xml

Filters

Tab Filter → create rules to automatically show/hide channels:

• Filter: group-title contains "VOD" → action: hide
• Filter: name contains "##" → action: hide (remove placeholders)
• Filter: name contains "4K" → action: show + group "4K Channels"

Custom channel logos

Replace ugly logo URLs with your own:

1. Mapping → channel → Logo URL
2. Paste your own URL (e.g. hosted on your NAS)
3. Or: use the tv-logo/tv-logos GitHub repo (free HD logos)

• Settings → Streaming → increase "Number of tuners"
• Provider's max connections reached — wait until others finish
• FFmpeg crash — restart the Threadfin container

• Switch to FFmpeg buffer mode
• Increase buffer size to 2048 KB
• Check disk write speed to /tmp/threadfin

• Mapping not correct — check the Mapping tab "EPG" column
• Timezone not set correctly (TZ env variable)
• The XMLTV source itself is outdated — try another source

• Plex on a different subnet than Threadfin? Enter the URL manually
• Firewall blocks port 34400
• Threadfin not started — check Docker logs

The Threadfin config lives in the ./conf volume:

• Backup: copy the entire conf folder
• Important files: settings.json, data.json, xepg.json
• Restore: stop the container, replace the folder, start the container