xTeVe

M3U proxy for Plex and Emby live TV

xTeVe is an application that simulates a TV tuner, allowing you to have IPTV channels via Plex or Emby without physical hardware. It can merge multiple M3U playlists and XMLTV files into a single unified source, providing your media server with access to live TV channels.

Removing xTeVe

New xTeVe installs are no longer offered. If you have an existing install, you can remove it from the dashboard or the CLI.

From App Dashboard → Package Management (/dashboard?mode=packages), open your xTeVe row and choose Remove. From the CLI:

qb remove xteve -u username

Accessing xTeVe

After installation, access xTeVe at:

https://your-server-ip/username/xteve

First-Time Setup:

1. Complete the setup wizard
2. Add your M3U playlist sources
3. Configure XMLTV EPG sources (optional)
4. Map and filter channels
5. Connect to Plex or Emby

Initial Configuration

1. Add M3U Playlist Sources

Configure your IPTV providers:

1. Go to Playlist tab in xTeVe
2. Click + to add a new playlist
3. Enter playlist details:
   • Name: Descriptive name (e.g., “IPTV Provider 1”)
   • M3U URL: Your IPTV provider’s M3U playlist URL
   • Type: Select M3U (most common)
4. Click Save to add the playlist
5. Repeat for additional IPTV providers
6. Click Update to fetch channels from all playlists

2. Add XMLTV EPG Sources (Optional)

Add Electronic Program Guide data for channel listings:

1. Go to XMLTV tab
2. Click + to add a new XMLTV source
3. Enter EPG details:
   • Name: EPG source name (e.g., “TV Guide Data”)
   • XMLTV URL: XMLTV file URL from your provider
4. Click Save to add the EPG source
5. Click Update to fetch program data

3. Map and Filter Channels

Organize your channels:

1. Go to Mapping tab
2. View all channels from merged playlists
3. Filter channels:
   • Enable/Disable: Toggle checkboxes to show/hide channels
   • Groups: Filter by channel groups
   • Search: Find specific channels by name
4. Map channels (optional):
   • Custom Numbers: Assign channel numbers
   • Custom Names: Rename channels for clarity
   • VOD Categories: Organize video-on-demand content
5. Click Save when done

4. Connect to Plex or Emby

Link xTeVe to your media server:

For Plex:

1. In Plex, go to Settings → Live TV & DVR
2. Click Set Up Plex DVR
3. Plex will auto-detect xTeVe (HDHomeRun device)
4. Select the xTeVe tuner from the list
5. Map channels and select TV guide source
6. Complete the setup wizard

For Emby:

1. In Emby, go to Settings → Live TV
2. Select Tuner Devices → Add
3. Choose HDHomeRun as device type
4. Emby will auto-detect xTeVe
5. Select channels and configure EPG
6. Save configuration

Service Management

xTeVe runs as a per-user systemd service.

systemctl status xteve@username     # Check status
systemctl restart xteve@username    # Restart service
journalctl -u xteve@username -f     # View live logs
systemctl enable xteve@username     # Start on boot (already enabled)
systemctl disable xteve@username    # Prevent auto-start

Troubleshooting

xTeVe Won’t Start

journalctl -u xteve@username -f

Check binary exists and is executable:

ls -la /opt/username/xTeVe/xteve
# Should show executable permissions (rwxr-xr-x)
sudo chmod +x /opt/username/xTeVe/xteve

Plex/Emby Can’t Detect xTeVe Tuner

M3U Playlist Not Updating

# Manually update playlists in xTeVe
# Playlist tab → Update button
 
# Check M3U URL is accessible
curl -I "your-m3u-url"
 
# Verify xTeVe can fetch the playlist
journalctl -u xteve@username -f | grep -i "playlist"
 
# Check for authentication or format errors in logs

Channels Buffering or Not Playing

# Increase buffer settings in xTeVe
# Settings → Streaming → Buffer Size
 
# Check IPTV provider stream quality and bandwidth
 
# Verify network connectivity to IPTV servers
ping your-iptv-provider.com
 
# Test stream URL directly with VLC or ffmpeg
ffplay "stream-url"

EPG Data Not Showing

# Manually update XMLTV data in xTeVe
# XMLTV tab → Update button
 
# Verify XMLTV URL is accessible
curl -I "your-xmltv-url"
 
# Check channel IDs match between M3U and XMLTV
# Mapping tab → verify tvg-id attributes
 
# Force refresh in Plex/Emby
# Plex: Settings → Live TV & DVR → Refresh Guide Data

Configuration Reset

# Backup current configuration
cp -r ~/.config/xTeVe ~/.config/xTeVe.backup
 
# Stop service
systemctl stop xteve@username
 
# Remove configuration (will be regenerated)
rm -rf ~/.config/xTeVe/*
 
# Restart service
systemctl start xteve@username

Best Practices

Related Applications

Additional Resources