HDHomeRun Emulation
Presents itself as an HDHomeRun network tuner via SSDP, /discover.json, and /lineup.json. Plex, Emby, and Jellyfin auto-discover xTeVe on the LAN — no manual configuration needed.
Overview
What is xTeVe 2?
xTeVe 2 is an open-source IPTV proxy server written in Go. It sits between your IPTV provider and your media server, solving a fundamental incompatibility: Plex, Emby, and Jellyfin want a standard cable tuner, but your IPTV provider gives you an M3U playlist. xTeVe bridges that gap.
✓ Auto-discovered via SSDP
✓ No Plex Pass required for basic use
Go 1.24+
React 19 Web UI
Docker-ready
When Plex, Emby, or Jellyfin scan your local network for tuners, they speak the HDHomeRun protocol — a standard used by physical network tuner hardware. xTeVe speaks that same protocol, so your media server discovers it automatically via SSDP broadcast, just as it would discover a real hardware tuner. From the media server's perspective, xTeVe is the tuner. Behind the scenes, xTeVe fetches your M3U playlist, merges it with XMLTV programme guide data, and proxies each channel stream through one of three buffer backends.
Capabilities
Everything you need to run IPTV with Plex, Emby, or Jellyfin
A complete IPTV management layer — from playlist ingestion to EPG mapping and stream delivery.
M3U Playlist Management
Fetches your M3U playlist from any URL and refreshes it on a configurable interval. Enable or disable individual channels, assign custom names and logos, and set channel numbers — all from the web UI.
XMLTV EPG Integration
Imports XMLTV programme guide data and maps it to your channels automatically via tvg-id, display name, or manual mapping. The merged guide is served at /xmltv/ for direct consumption by your media server.
Configurable Buffer Backends
Three stream delivery modes: HLS pass-through for low latency, FFmpeg re-encode for format conversion and compatibility, or VLC transcoding for maximum flexibility.
Tuner Limit Enforcement
Configurable tuner count prevents more simultaneous streams than your IPTV provider allows. Additional stream requests receive a clean 503 response, keeping your subscription and bandwidth within limits.
React Web UI
A full admin dashboard built with React 19 and TypeScript. Manage channels, configure EPG mappings, set M3U and XMLTV sources, adjust settings, and watch live server logs — all in the browser at port 34400.
Real-time Log Stream
WebSocket-based live log feed pushes server events to the Logs page in real time. No page refresh, no polling — events appear the moment they happen, making debugging effortless.
Optional Authentication
Enable password protection for the admin API and web UI. Sessions are managed with bcrypt-hashed passwords and secure HTTP-only cookies. The HDHomeRun and stream endpoints remain public for media server compatibility.
Docker-Ready
Official multi-arch Docker image at ghcr.io/jskoetsier/xteve2:latest. Single environment variable configuration — point XTEVE_M3U_URL and XTEVE_XMLTV_URL at your sources and you're running.
Architecture
How xTeVe 2 Works
xTeVe sits in the middle of your IPTV stack, translating between the M3U world of IPTV providers and the HDHomeRun world of media servers.
[PHASE 01]
Ingest M3U playlist
xTeVe fetches your M3U URL and parses every channel entry — name, tvg-id, logo, group, and stream URL. It refreshes automatically on a configurable interval so channel changes are always picked up.
[PHASE 02]
Merge XMLTV data
xTeVe fetches your XMLTV EPG source and maps programme schedules to channels using tvg-id matching, display name matching, or manual channel mapping you configure in the UI.
[PHASE 03]
Emulate HDHomeRun
xTeVe broadcasts its presence on the LAN via SSDP and answers HDHomeRun discovery requests at /discover.json, /lineup.json, and /device.xml. Media servers find it automatically.
[PHASE 04]
Proxy on demand
When your media server requests a channel, xTeVe checks the tuner limit, opens the upstream stream from your IPTV provider, and proxies it through to the client via HLS, FFmpeg, or VLC.
Your IPTV Provider ├── M3U Playlist URL ──────────────────────┐ └── XMLTV EPG URL ─────────────────────────┤ ▼ xTeVe 2 (:34400) ├── /discover.json ← HDHomeRun protocol ├── /lineup.json ← channel list + stream URLs ├── /device.xml ← device description ├── /m3u/ ← merged M3U playlist ├── /xmltv/ ← merged EPG ├── /stream/:id ← proxied stream ├── /api/v1/* ← REST API ├── /ws ← live log feed └── / ← React admin UI │ ┌──────────────────────────────┴──────────────────────────┐ │ │ │ Plex DVR Emby Live TV Jellyfin (auto-discovers (auto-discovers (M3U or HDHomeRun via SSDP) via SSDP) source)
Installation
Quick Start Guide
xTeVe runs as a single binary with no external dependencies. Download, run, open the UI, and connect your M3U source.
Linux (x86-64)
bash
# Download the binary
curl -L https://github.com/jskoetsier/xteve2/releases/latest/download/xteve_linux_amd64 -o xteve
chmod +x xteve
# Run (config stored in ~/.xteve by default)
./xteve
# Open the admin UI
# http://localhost:34400
Command-line flags
flags
./xteve -port 34400 # HTTP listen port (default: 34400)
./xteve -config ~/.xteve # Config directory (default: ~/.xteve)
Connect your IPTV source
STEP 02
Add M3U
Go to Settings and paste your IPTV provider's M3U playlist URL. xTeVe fetches it immediately.
STEP 03
Add XMLTV
Paste your XMLTV EPG URL in Settings. xTeVe maps programme schedules to channels automatically.
STEP 04
Connect
Add a Live TV tuner. Your media server discovers xTeVe via SSDP or you can enter the URL manually.
Deployment
Docker Container
Official multi-arch images at ghcr.io/jskoetsier/xteve2:latest.
RUN COMMAND
shell
docker run -d \
--name xteve \
-p 34400:34400 \
-v ~/.xteve:/config \
-e XTEVE_BASE_URL=http://YOUR_SERVER_IP:34400 \
-e XTEVE_M3U_URL=http://your-iptv-provider/playlist.m3u \
-e XTEVE_XMLTV_URL=http://your-iptv-provider/epg.xml \
ghcr.io/jskoetsier/xteve2:latest
DOCKER-COMPOSE.YML
yaml
services:
xteve:
image: ghcr.io/jskoetsier/xteve2:latest
container_name: xteve
restart: unless-stopped
ports:
- "34400:34400"
volumes:
- ~/.xteve:/config
environment:
- XTEVE_BASE_URL=http://YOUR_SERVER_IP:34400
- XTEVE_M3U_URL=http://your-iptv-provider/playlist.m3u
- XTEVE_XMLTV_URL=http://your-iptv-provider/epg.xml
ENVIRONMENT VARIABLES
XTEVE_BASE_URL Public URL xTeVe uses to build stream URLs
XTEVE_M3U_URL URL to your M3U playlist
XTEVE_XMLTV_URL URL to your XMLTV EPG file
XTEVE_M3U_REFRESH_MINS Playlist refresh interval (default: 15)
Compatibility
Media Stack Integration
Full support for any server consuming HDHomeRun or M3U/XMLTV.
Plex Media Server
xTeVe appears as an HDHomeRun tuner in Plex. Add it under Live TV & DVR → Add Tuner Device.
Emby Server
Add xTeVe as an HDHomeRun tuner or as an M3U tuner under Live TV → Add Tuner Device.
Jellyfin
Jellyfin supports both M3U and HDHomeRun sources. Add xTeVe's stream URL as an M3U playlist.
Any IPTV Client
The /m3u/ endpoint serves a standard M3U playlist compatible with VLC, Kodi, and TiviMate.
Build Targets
Linux
x86-64 · ARM64
macOS
Intel · Silicon
Windows
x86-64
Docker
amd64 · arm64
Kubernetes
via Helm/Manifest
FreeBSD
x86-64
Release
Download xTeVe 2
Pre-built binaries are attached to every GitHub Release. Current version: 2.3.0. No runtime dependencies — just download and run.
Available downloads — v2.3.0
| Platform | Architecture | Filename |
|---|---|---|
| Linux | x86-64 | xteve_linux_amd64 |
| Linux | ARM64 | xteve_linux_arm64 |
| macOS | x86-64 (Intel) | xteve_darwin_amd64 |
| macOS | Apple Silicon | xteve_darwin_arm64 |
| Windows | x86-64 | xteve_windows_amd64.exe |
| FreeBSD | x86-64 | xteve_freebsd_amd64 |
QUERY
Frequently Asked Questions
Common questions about setting up xTeVe with Plex, Emby, and Jellyfin.
What is xTeVe 2?
xTeVe 2 is an open-source M3U proxy server that bridges your IPTV subscription with media servers like Plex, Emby, and Jellyfin. It emulates an HDHomeRun network tuner so these apps discover xTeVe automatically and treat your IPTV channels as live TV. It merges M3U playlists with XMLTV programme guide data, manages channel mapping, and proxies streams through configurable buffer backends.
Does xTeVe work with Plex DVR?
Yes. xTeVe presents itself as an HDHomeRun tuner on your local network. Plex discovers it automatically via SSDP and uses the
/discover.json and /lineup.json endpoints to list channels and stream URLs. You add it the same way you'd add a real HDHomeRun device under Live TV & DVR settings.
Does xTeVe work with Emby and Jellyfin?
Yes. Both Emby and Jellyfin support HDHomeRun tuners and M3U playlists as Live TV sources. xTeVe works with both methods — either as an emulated HDHomeRun tuner (auto-discovered via SSDP) or by pointing Emby/Jellyfin directly at the
/m3u/ and /xmltv/ endpoints that xTeVe exposes.
How do I add my IPTV M3U playlist to xTeVe?
Open the xTeVe web interface at
http://localhost:34400, go to Settings, and paste your M3U URL in the "M3U URL" field. Save settings and xTeVe will fetch the playlist immediately. Channels appear in the channel list where you can enable or disable them, set custom names, and map EPG data.
What is XMLTV and does xTeVe support EPG?
XMLTV is a standard format for Electronic Programme Guide (EPG) data — the TV schedules your media server shows for each channel. xTeVe fetches your XMLTV source and maps programme data to channels automatically via tvg-id, display name matching, or manual channel mapping. The merged guide is served at
/xmltv/ for Plex, Emby, and Jellyfin to consume.
How many simultaneous streams does xTeVe support?
xTeVe enforces a configurable tuner count (default: 1). When all tuner slots are full, additional stream requests receive a 503 response, preventing overloading your IPTV provider or network connection. Set
tuner_count in settings to match what your provider allows.
Can I run xTeVe in Docker or on a NAS?
Yes. xTeVe ships an official multi-arch Docker image at
ghcr.io/jskoetsier/xteve2:latest supporting amd64 and arm64. It runs on any Docker host including Synology NAS, QNAP, Unraid, TrueNAS, and Raspberry Pi. Mount a config directory for persistence and set your M3U URL as an environment variable.
What buffer type should I use: HLS, FFmpeg, or VLC?
HLS (default) is the simplest — xTeVe passes the stream through without re-encoding. Use this if your IPTV streams are already in a format your media server handles.
FFmpeg re-encodes the stream. Use it when you need format conversion, your IPTV provider uses codecs your media server doesn't support, or you want to normalize bitrates.
VLC offers maximum compatibility and transcoding options. Use it as a fallback if FFmpeg doesn't meet your needs.
FFmpeg re-encodes the stream. Use it when you need format conversion, your IPTV provider uses codecs your media server doesn't support, or you want to normalize bitrates.
VLC offers maximum compatibility and transcoding options. Use it as a fallback if FFmpeg doesn't meet your needs.
Is xTeVe a fork of the original xTeVe?
xTeVe 2 is a full rewrite of the original xTeVe project created by marmei. The core concept — M3U proxy with HDHomeRun emulation for Plex and Emby — is entirely theirs. xTeVe 2 modernizes the codebase with Go 1.24, a React 19 frontend, a clean internal package structure, and active development.