Threadfin vs xTeVe vs TVHeadEnd: Self-Hosted IPTV Proxy Guide 2026

Why Self-Host an IPTV Proxy?

If you have access to IPTV playlists (M3U/M3U8 files) and want to integrate them with media servers like Plex, Jellyfin, or Emby, an IPTV proxy is the essential bridge. These tools transform raw playlist URLs into a format that media servers understand — specifically, the HDHomeRun tuner API protocol. Without a proxy, most IPTV providers offer direct stream URLs that media servers cannot natively consume as live TV channels.

Self-hosting an IPTV proxy gives you full control over channel mapping, EPG (Electronic Program Guide) data, stream filtering, and recording scheduling — all without relying on third-party cloud services. Whether you’re building a complete self-hosted media server or adding live TV to an existing setup, the right IPTV proxy makes the difference between a seamless experience and constant configuration headaches.

What Is an IPTV Proxy?

An IPTV proxy acts as a middleware layer between your IPTV provider’s M3U playlist and your media server. It performs several critical functions:

• M3U Parsing: Downloads and parses M3U playlist files containing channel lists and stream URLs
• HDHomeRun Emulation: Presents itself as a physical HDHomeRun tuner device, which Plex, Jellyfin, and Emby all natively support
• EPG Integration: Downloads XMLTV guide data and maps it to individual channels
• Stream Transcoding: Optionally transcodes streams to compatible formats (TVHeadEnd only)
• Channel Filtering: Removes duplicate channels, filters by language, or reorganizes channel groups
• Caching: Buffers stream data to prevent timeouts and improve reliability

The three most popular open-source options are xTeVe (the original), Threadfin (the actively maintained fork), and TVHeadEnd (the full-featured TV streaming server). Let’s break down what makes each one different.

xTeVe: The Original M3U Proxy

xTeVe was one of the first open-source M3U proxy servers designed specifically for Plex DVR integration. Written in Go, it became the go-to solution for self-hosted live TV enthusiasts who wanted to pipe IPTV streams into their media servers.

Current status: xTeVe has 2,222 GitHub stars but has not seen a significant update since August 2024. The original project has effectively stalled, which is why the community fork Threadfin emerged.

Key Features

• M3U playlist parsing and channel mapping
• XMLTV EPG integration
• HDHomeRun tuner emulation
• Web-based configuration interface
• Channel filtering and grouping
• Buffer server for stream stability

Installation

xTeVe is available as a single Go binary or Docker container. The easiest deployment method is via Docker:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# Create data directories
mkdir -p /opt/xteve/config /opt/xteve/cache

# Run xTeVe container
docker run -d \
  --name xteve \
  --restart unless-stopped \
  -p 34400:34400 \
  -v /opt/xteve/config:/root/.xteve:rw \
  -v /opt/xteve/cache:/tmp/xteve-cache:rw \
  -e TZ=UTC \
  ghcr.io/alturismo/xteve-docker:latest

After starting, access the web interface at http://your-server-ip:34400/web/ to configure your M3U playlist and EPG source.

Limitations

The primary concern with xTeVe is its lack of active development. New IPTV stream formats, updated API requirements, and bug fixes are no longer being addressed by the original maintainer. This is the main reason the community created Threadfin.

Threadfin: The Active Fork

Threadfin is a community-maintained fork of xTeVe that addresses the original project’s stagnation. With 1,552 GitHub stars and updates as recently as October 2025, Threadfin adds modern features, bug fixes, and ongoing compatibility improvements for Plex, Jellyfin, and Emby live TV integrations.

What Threadfin Adds Over xTeVe

• Active maintenance: Regular bug fixes and compatibility updates
• Improved EPG handling: Better XMLTV parsing and faster guide data refresh
• Enhanced buffer management: More stable streaming with lower memory usage
• Multi-provider support: Manage multiple M3U playlists from different providers
• Modernized codebase: Updated dependencies and improved error handling

Docker Setup

Threadfin uses the official Docker image with a similar configuration pattern to xTeVe:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

mkdir -p /opt/threadfin/config /opt/threadfin/data

docker run -d \
  --name threadfin \
  --restart unless-stopped \
  -p 34400:34400 \
  -v /opt/threadfin/config:/home/threadfin/conf:rw \
  -v /opt/threadfin/data:/home/threadfin/data:rw \
  -e TZ=UTC \
  -e THREADFIN_BRANCH=main \
  ghcr.io/threadfin/threadfin:main

Access the web interface at http://your-server-ip:34400/web/. The setup wizard will guide you through:

1. Adding your M3U playlist URL
2. Configuring XMLTV EPG data source
3. Mapping channels and removing duplicates
4. Setting up the HDHomeRun tuner for your media server

Docker Compose Configuration

For users who prefer Docker Compose management, here’s a complete configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

services:
  threadfin:
    image: ghcr.io/threadfin/threadfin:main
    container_name: threadfin
    restart: unless-stopped
    ports:
      - "34400:34400"
    volumes:
      - /opt/threadfin/config:/home/threadfin/conf:rw
      - /opt/threadfin/data:/home/threadfin/data:rw
    environment:
      - TZ=UTC
      - THREADFIN_BRANCH=main
    networks:
      - media-net

networks:
  media-net:
    driver: bridge

This setup integrates seamlessly with other self-hosted media request managers in your stack.

TVHeadEnd: The Full-Featured TV Server

TVHeadEnd is not just an M3U proxy — it’s a complete TV streaming server with support for DVB-C/C2, DVB-S/S2, DVB-T/T2, ATSC, IPTV, SAT>IP, and Unix pipe inputs. With 3,401 GitHub stars and active development as of April 2026, it’s the most feature-rich option but also the most complex to configure.

Key Features

• Multiple input sources: Over-the-air antennas, satellite tuners, IPTV streams, SAT>IP
• Built-in transcoder: Convert streams to web-friendly formats on the fly
• Advanced EPG management: Multiple EPG grabbers with automatic scheduling
• User access control: Granular permissions for different users
• Recording scheduler: Built-in DVR functionality with series recording support
• API access: REST and JSON-RPC APIs for programmatic control
• Channel icon management: Automatic channel logo fetching
• Timeshift: Pause and rewind live TV

Docker Setup

TVHeadEnd’s Docker image requires mapping hardware devices if you’re using physical tuners, but for IPTV-only setups, a simpler configuration works:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

mkdir -p /opt/tvheadend/config /opt/tvheadend/recordings

docker run -d \
  --name tvheadend \
  --restart unless-stopped \
  -p 9981:9981 \
  -p 9982:9982 \
  -v /opt/tvheadend/config:/config:rw \
  -v /opt/tvheadend/recordings:/recordings:rw \
  -e TZ=UTC \
  -e RUN_OPTS="--http_port 9981 --htsp_port 9982" \
  linuxserver/tvheadend:latest

Access the web interface at http://your-server-ip:9981. Initial setup involves:

1. Creating an admin account
2. Adding your IPTV network (M3U URL)
3. Configuring the EPG grabber
4. Mapping services to channels
5. Creating a user for media server access

Docker Compose with Full Configuration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

services:
  tvheadend:
    image: linuxserver/tvheadend:latest
    container_name: tvheadend
    restart: unless-stopped
    ports:
      - "9981:9981"  # Web interface
      - "9982:9982"  # HTSP protocol
    volumes:
      - /opt/tvheadend/config:/config:rw
      - /opt/tvheadend/recordings:/recordings:rw
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=UTC
      - RUN_OPTS=--http_port 9981 --htsp_port 9982
    networks:
      - media-net

networks:
  media-net:
    driver: bridge

If you’re using a reverse proxy like Caddy or Traefik, you can front TVHeadEnd’s web interface for HTTPS access.

Head-to-Head Comparison

Which Should You Choose?

Choose Threadfin if:

• You want an actively maintained xTeVe replacement
• Your only goal is IPTV proxy for Plex, Jellyfin, or Emby
• You prefer a simple setup with minimal configuration
• You don’t need transcoding or DVR recording in the proxy itself

Choose xTeVe if:

• You have an existing xTeVe setup that works perfectly
• You don’t need any new features or bug fixes
• You prefer the original project’s interface

Choose TVHeadEnd if:

• You need a full TV server with DVB/OTA tuner support
• You want built-in transcoding for format conversion
• You need advanced recording scheduling and series management
• You want user access control and API automation
• You’re running a multi-user media environment

Integrating With Your Media Server

Once your IPTV proxy is running, connect it to your media server:

For Jellyfin/Plex/Emby

1. Navigate to Live TV settings in your media server
2. Add a new tuner device
3. Select HDHomeRun as the tuner type
4. Enter the proxy URL: http://your-server-ip:34400 (Threadfin/xTeVe) or http://your-server-ip:9981 (TVHeadEnd)
5. Add the guide data source (XMLTV URL from your proxy)
6. Map channels and save

For Kodi

1. Install the PVR IPTV Simple Client addon
2. Configure it with your M3U playlist URL
3. Set the EPG source to your XMLTV URL
4. Enable the addon and restart Kodi

If you manage your media library with a request system, your live TV channels will be available alongside your on-demand content. Check out our guide on media request managers to complete your self-hosted entertainment stack.

Frequently Asked Questions

What is the difference between xTeVe and Threadfin?

Threadfin is a community fork of xTeVe created because the original xTeVe project stopped receiving updates after August 2024. Threadfin adds bug fixes, improved EPG handling, better buffer management, and multi-provider support. If you’re starting fresh, Threadfin is the recommended choice.

Can I use Threadfin with Jellyfin?

Yes, absolutely. Threadfin emulates an HDHomeRun tuner, which Jellyfin natively supports. Simply add Threadfin as an HDHomeRun device in Jellyfin’s Live TV settings using the URL http://your-server-ip:34400.

Does TVHeadEnd support IPTV without a physical tuner?

Yes. TVHeadEnd can use IPTV as its sole input source without any DVB or ATSC hardware. During setup, create a new “IPTV Automatic Network” and provide your M3U playlist URL. TVHeadEnd will parse the playlist and create channels automatically.

How do I fix EPG data not loading in my IPTV proxy?

Common causes include: (1) Incorrect XMLTV URL — verify the URL works in a browser, (2) Timezone mismatch — ensure your container’s TZ environment variable matches your local timezone, (3) EPG format incompatibility — some providers use non-standard XMLTV formats. For Threadfin, try refreshing the EPG manually from the web interface. For TVHeadEnd, check the EPG Grabber Channels tab for mapping errors.

Can I run multiple IPTV proxies on the same server?

Yes, but you must use different ports to avoid conflicts. For example, run Threadfin on port 34400 and TVHeadEnd on port 9981. Each proxy can manage a different M3U playlist from a different provider. However, only one proxy should feed a given media server’s Live TV tuner to avoid channel conflicts.

Do I need a reverse proxy for my IPTV setup?

A reverse proxy is not required for the IPTV proxy to function — the HDHomeRun protocol works over direct HTTP. However, if you want HTTPS access to the web configuration interface, or if you want to expose the proxy to external networks securely, a reverse proxy like Caddy or Nginx is recommended.

How much bandwidth does an IPTV proxy consume?

The proxy itself uses minimal bandwidth — it passes through the stream data between the provider and the media server. The actual bandwidth depends on the number of concurrent streams and their quality. A single HD stream typically uses 3-8 Mbps. If you’re transcoding (TVHeadEnd only), additional CPU resources are needed.

Can I record live TV with Threadfin or xTeVe?

No — Threadfin and xTeVe are M3U proxies only. They don’t include recording functionality. Recording is handled by the media server (Plex DVR, Jellyfin Live TV recording) using the proxy as the tuner source. TVHeadEnd, on the other hand, has a built-in DVR with full recording and series scheduling support.