Short answer: Threadfin sits between your M3U playlist and your media server. It filters the playlist down to the channels you want, matches them to a guide, and presents the result as if it were an HDHomeRun tuner, which is the only kind of live TV source Plex accepts. Run it in Docker on port 34400, complete the setup wizard with your tuner count, playlist and XMLTV, activate the channels you want in the Mapping tab, then point Plex, Jellyfin or Channels DVR at it. The catch: only channels you've activated are passed on, so an empty lineup after setup almost always means nothing has been mapped yet.
At a glance
Threadfin in brief
| What it is | Free M3U proxy, a maintained fork of xTeVe |
| Pretends to be | An HDHomeRun network tuner |
| Default address | http://[server]:34400/web/ |
| Works with | Plex, Emby, Jellyfin, Channels DVR |
| Key rule | Only mapped, active channels are exported |
Do you actually need it?
Threadfin solves specific problems. If you don't have one of them, skip it and add your playlist to your server directly.
| Your situation | Need Threadfin? | Why |
|---|---|---|
| Plex, with an M3U playlist | Yes | Plex's Live TV only accepts HDHomeRun-type tuners, not playlists |
| Channels DVR, playlist over 750 channels | Helpful | Channels caps a custom playlist at 750; Threadfin filters it down |
| Jellyfin or Emby, small clean playlist | No | Both accept M3U directly |
| Jellyfin or Emby, huge playlist with films mixed in | Helpful | Filtering and guide mapping in one place |
| Guide IDs don't match your playlist | Helpful | Its mapping screen fixes matches once, for every server |
| You only watch in a player app like TiviMate | No | Players read playlists directly |
One more thing before starting: Threadfin is plumbing. It doesn't supply channels and it doesn't make an unreliable source reliable. Use it with a playlist you're entitled to, whether that's from a licensed service, your own encoder or free broadcaster streams. How M3U playlists work is useful background.
Install with Docker
Docker is the easiest route on a NAS, a Linux box or a Mac or Windows machine running Docker Desktop. The image is fyb3roptik/threadfin, with more than a million pulls on Docker Hub. A minimal compose file:
services:
threadfin:
image: fyb3roptik/threadfin
container_name: threadfin
ports:
- "34400:34400"
volumes:
- ./threadfin/conf:/home/threadfin/conf
restart: unless-stoppedRun docker compose up -d, then open http://[server-ip]:34400/web/. The configuration volume keeps your settings and backups when the container updates.
Two practical notes. If your media server also runs in Docker, put both on the same Docker network or use the host's LAN IP, not localhost, which means something different inside each container. And give the host a fixed IP address; Plex in particular remembers the tuner by address.
No Docker? The project also publishes builds you can run directly, and a Helm chart for Kubernetes. The steps after installation are the same.
The first-run wizard, field by field
The first time you open the web page, Threadfin walks you through four settings. Threadfin's own documentation still points to the xTeVe docs for detail, which is where these definitions come from.
| Setting | What to choose | Why it matters |
|---|---|---|
| Tuner count | Your plan's simultaneous connection limit | Each live view or recording uses one tuner. Set it higher than your plan allows and the provider will reject streams |
| EPG source | XEPG | Threadfin builds and serves the guide. The alternative, PMS, leaves the guide to Plex and disables mapping |
| M3U playlist | Your playlist URL or a local file | If you have an Xtream login, use the M3U link version of it |
| XMLTV file | Your guide URL | Only asked for with XEPG |
When it finishes, Threadfin downloads the playlist and guide and shows a dashboard with your playlist's stream count and a "tvg-id" percentage. That percentage tells you how many entries carry a guide ID; the higher it is, the more channels will map themselves. How Xtream logins relate to M3U links.
Filter the playlist
A provider playlist might have 20,000 entries, most of them films and series. You want the forty or four hundred live channels you'll actually watch.
In the Filter tab, add rules:
-
Group filters include whole groups from the playlist's
group-title, such as a "US News" or "Sports" group. This is the quick route. - Custom filters match text in the channel's name or other M3U fields, with include and exclude words. Use them to drop duplicates like low-resolution or backup versions of channels you've already got.
Save, and the stream count on the dashboard drops. Aim for comfortably under 750 if Channels DVR is the destination, and as small as practical for Plex, whose guide gets sluggish with hundreds of channels.
Map and activate channels
This is where most first-time setups stall. In the Mapping tab, every filtered channel is listed. Only channels marked active, shown in green, are passed on to Plex, Emby, Jellyfin or the exported playlist. Everything else stays behind.
- Channels whose
tvg-idmatches the XMLTV are usually matched already. - For the rest, open a channel and pick its XMLTV entry from the list. Multi-select lets you edit many at once.
- Set each channel's number, and make sure each one is active.
- Save.
Threadfin can also store backup streams for a channel, up to three, so if the primary fails it tries the next one. Handy when a source offers the same channel in several qualities.
If a channel has no guide data at all, you can still activate it; it'll show as a generic programme block. A full checklist for missing guide data is on the EPG troubleshooting page.
Buffer settings
Under Settings, the streaming buffer controls whether Threadfin sits in the middle of the video stream or just passes the address along.
| Buffer | What happens | Use when |
|---|---|---|
| None | Clients connect straight to the source | Everything works and you want the lightest setup |
| Threadfin | Threadfin fetches and relays the stream, buffering in memory | The default choice; also lets it enforce the tuner count |
| FFmpeg | FFmpeg fetches the stream | Streams stutter or won't start with the built-in buffer; HLS sources |
| VLC | VLC fetches the stream | Rarely; a fallback for odd sources |
Start with the Threadfin buffer. Switch to FFmpeg if specific channels fail; you'll need FFmpeg installed in the container or on the host and its path set in the same settings page. A recent release improved compatibility with the FFmpeg 7 builds that Jellyfin uses.
Connect Plex, Jellyfin or Channels DVR
Threadfin's dashboard shows the addresses to use. They follow this pattern:
- Tuner address:
[server-ip]:34400 - Playlist:
http://[server-ip]:34400/m3u/threadfin.m3u - Guide:
http://[server-ip]:34400/xmltv/threadfin.xml(a.gzversion also exists)
Plex
- In Plex Web, go to Settings > Live TV & DVR and choose Set Up Plex DVR.
- If Threadfin isn't found automatically, choose the option to enter the device's network address manually and type
[server-ip]:34400. - When asked for the guide, choose the option to use an XMLTV guide instead of Plex's, and enter the uncompressed
threadfin.xmlURL. Plex can't read the gzipped version. - Confirm the channel list and finish.
More on how Plex handles live channels is in Plex and M3U.
Jellyfin or Emby
Add Threadfin as an HDHomeRun tuner using [server-ip]:34400, or as an M3U Tuner using the threadfin.m3u URL. Then add the threadfin.xml address as an XMLTV guide and map channels. Set Jellyfin's stream limit to the same number as Threadfin's tuner count. Full Jellyfin live TV setup.
Channels DVR
Add a Custom Channels source with the threadfin.m3u URL, MPEG-TS as the stream format, and threadfin.xml as the XMLTV source. Set the stream limit to match the tuner count. Full Channels DVR setup.
Whichever server you use, refresh its guide after any change in Threadfin's mapping. Servers cache the lineup and won't notice otherwise.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Plex finds the tuner but no channels | Nothing activated in Mapping | Activate channels (green), save, rescan in Plex |
| Plex guide import fails | Gzipped XMLTV URL | Use threadfin.xml, not .xml.gz
|
| Plex can't find the tuner at all | Different network or Docker isolation | Enter [LAN-ip]:34400 manually; check port mapping |
| Channels disappear after a playlist update | Channels matched by name, and names changed | Use a playlist with stable tvg-id values |
| "All tuners in use" | Tuner count reached | Stop a stream; raise the count only if your plan allows |
| Stream starts then freezes | Buffer type | Switch buffer to FFmpeg for that source |
| Guide shows old data | Cached XMLTV | Update the XMLTV in Threadfin, then refresh the server's guide |
| Fails in Threadfin and in VLC | The source | Nothing to fix locally; contact the provider |
That last row matters. If the original stream won't play in VLC on the same machine, no proxy will fix it. How to run the VLC test.
Quick answers
What is Threadfin? A free, open-source M3U proxy based on xTeVe. It filters IPTV playlists, maps them to a guide, and presents them to Plex, Emby, Jellyfin and Channels DVR as an HDHomeRun tuner.
What port does Threadfin use? 34400 by default. The web interface is at http://[server-ip]:34400/web/.
Why does Plex need Threadfin? Plex Live TV only accepts tuner devices like HDHomeRun, not M3U playlists. Threadfin emulates one.
Why are no channels showing after setup? Only channels activated in Threadfin's Mapping tab are exported. Activate them, save, and rescan in your server.
What tuner count should I set? The number of simultaneous streams your plan allows. Any higher and the source will reject extra streams.
Is Threadfin the same as xTeVe? It's a fork that continues development, with a new interface, memory-based buffering and bulk mapping.
Does Threadfin give me channels? No. It only reorganises a playlist you already have.
Based on the Threadfin repository, its Docker image and the xTeVe documentation it references; menu names can change between releases. Use Threadfin only with playlists you're licensed to watch. Checked September 2026.