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.

What the Update Does

The next system update removes xTeVe for every account that has it, and qb update xteve does the same for one account. You do not need to take any action first.

For each account, the removal:

• Stops and removes the xTeVe service, files, and web proxy site.
• Copies the account’s xTeVe settings and M3U playlists to /home/username/.QuickBox/software/xteve/default, then removes ~/.config/xTeVe.
• Prints where the settings were kept and the command to install Dispatcharr.

If the copy fails, the settings stay in ~/.config/xTeVe and nothing is deleted.

You can also remove it yourself at any time. From App Dashboard → Package Management (/dashboard?mode=packages), open your xTeVe row and choose Remove. From the CLI:

qb remove xteve -u username

Moving to Dispatcharr

Install Dispatcharr, then add your M3U and XMLTV URLs again. The URLs are in the settings that were kept.

qb install dispatcharr -u username
ls /home/username/.QuickBox/software/xteve/default

See the Dispatcharr guide for setup and for connecting Plex, Emby, or Jellyfin.

Accessing xTeVe

Until the update removes it, xTeVe is available at:

Original Setup Flow:

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

Configuration Reference

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