A minimal, self-hosted web interface for IPTV streams.

We built neTV because we couldn't find a clean, lightweight interface for Xtream IPTV services. Existing solutions were either bloated media centers or clunky apps that didn't work well across devices.

neTV is intentionally minimal. It does one thing: play your IPTV streams with a clean UI that works on desktop, tablet, mobile, and Chromecast.

We also prioritize keyboard navigation throughout (though still rough around the edges). The entire app is theoretically usable with just arrow keys, Enter, and Escape -- perfect for media PCs, HTPCs, or anyone who prefers keeping hands on the keyboard (like me).

This is a player only -- it does not provide any content. You must have your own IPTV subscription that provides Xtream Codes API access or M3U playlists. Users are responsible for ensuring they have legal rights to access any content through their IPTV providers.

• Live TV with EPG grid guide
• Movies & Series with metadata, seasons, episodes
• AI Upscale - Real-time 4x upscaling via TensorRT (720p → 4K @ 85fps)
• Chromecast support (HTTPS required)
• Closed captions with style customization
• Search across all content (supports regex)
• Favorites with drag-and-drop ordering
• Resume playback for VOD content
• Responsive - works on desktop, tablet, mobile
• Keyboard navigation - 10-foot UI friendly

Extensively optimized for minimal latency and CPU usage:

• Smart passthrough - h264+aac streams remux without re-encoding (zero CPU)
• Full GPU pipeline - NVDEC decode → NVENC/VAAPI encode, CPU stays idle
• Probe caching - Streams probed once, series episodes share probe data
• Interlace detection - Auto-deinterlaces OTA/cable, skips progressive
• Smart seeking - Reuses segments for backward seeks, only transcodes gaps
• Session recovery - VOD sessions survive restarts, resume where you left off
• HTTPS passthrough - Auto-proxies HTTP streams when behind HTTPS

Real-time 4x upscaling using Real-ESRGAN via TensorRT. Transforms 480p/720p/1080p content to pristine 4K at 85fps (RTX 5090). Perfect for older shows and low-bitrate streams.

Before (720p source)	After (4K AI Upscale)

Requires NVIDIA GPU and the AI Upscale Docker image. The Settings page shows AI Upscale options when TensorRT engines are available.

If you want a full-featured media center, you might be happier with:

• Jellyfin - Free, open-source media system
• Emby - Media server with IPTV support
• Plex - Popular media platform with live TV

These are excellent, mature projects with large communities. neTV exists for users who find them overkill and just want a simple IPTV player.

Corrections welcome — open an issue.

Create a docker-compose.yml:

services:
  netv:
    image: ghcr.io/jvdillon/netv:latest
    ports:
      - "8000:8000"
    volumes:
      - ./cache:/app/cache
      - /etc/localtime:/etc/localtime:ro
    devices:
      - /dev/dri:/dev/dri  # for hardware transcoding (remove if no GPU)
    restart: unless-stopped

Then run:

docker compose up -d

Open http://localhost:8000. To update: docker compose pull && docker compose up -d

Requires nvidia-container-toolkit.

Check your driver and compute capability:

nvidia-smi --query-gpu=driver_version,compute_cap --format=csv,noheader
# Example: 580.87.02, 8.6 → Driver 580, compute ≥7.5 → use cuda13.0

Find your CUDA version (source):

Then run:

FFMPEG_IMAGE=ghcr.io/jvdillon/netv-ffmpeg:<cuda-version> docker compose --profile nvidia up -d

For real-time 4x AI upscaling (720p → 4K at 85fps on RTX 5090):

git clone https://github.com/jvdillon/netv.git
cd netv
docker build -f Dockerfile.ai_upscale -t netv-ai .
docker run --gpus all -v netv-models:/models -v ./cache:/app/cache -p 8000:8000 netv-ai

First start builds TensorRT engines for your GPU (~2-3 min). Engines are cached in the netv-models volume for instant subsequent starts.

Requirements:

• NVIDIA GPU (RTX 20xx or newer recommended)
• nvidia-container-toolkit
• Driver 535+ (CUDA 12.x)

For customization or development:

git clone https://github.com/jvdillon/netv.git
cd netv
docker compose build                              # optimized FFmpeg (default)
# FFMPEG_IMAGE=ubuntu:24.04 docker compose build  # or stock FFmpeg
docker compose up -d

To update: git pull && docker compose build && docker compose up -d

NETV_PORT=9000 docker compose up -d        # custom port
NETV_HTTPS=1 docker compose up -d          # enable HTTPS (mount certs first)

For peak FFMPEG performance, Chromecast (requires HTTPS), and auto-start:

# 1. Install prerequisites (uv, Python)
./tools/install-prereqs.sh

# 2. (Optional) Get HTTPS certificates (required for Chromecast)
./tools/install-letsencrypt.sh yourdomain.com

# 3. (Optional) Build FFmpeg (required for optimal NVidia encoding efficiency)
./tools/install-ffmpeg.sh

# 4. (Optional) Build AI Upscale engines (requires NVIDIA GPU + TensorRT)
uv sync --group ai_upscale
./tools/install-ai_upscale.sh

# 5. Install systemd service
sudo ./tools/install-netv.sh # default port=8000 or --port 9000

Manage with:

sudo systemctl status netv       # Check status
sudo systemctl restart netv      # Restart after updates
journalctl -u netv -f            # View logs
sudo systemctl edit netv --full  # Change port or other settings
sudo ./tools/uninstall-netv.sh   # Uninstall

There's also some gems in tools/:

• zap2xml.py: Scrape guide data into XML (I crontab this at 5am daily).
• alignm3u.py: Useful for reworking your HDHomeRun m3u to align with guide.
• xtream2m3u.py: Dump xtream to m3u, useful for making Emby work with IPTV.

Requires Python 3.11+ and uv:

git clone https://github.com/jvdillon/netv.git
cd netv
uv run ./main.py --port 8000  # --https

Or with pip:

pip install .
./main.py --port 8000

Open http://localhost:8000, create an admin account, and add your IPTV source.

Enable verbose logs to diagnose EPG, M3U parsing, or other issues.

Docker:

In docker-compose.yml, change LOG_LEVEL=INFO to LOG_LEVEL=DEBUG, then restart:

docker compose down && docker compose up -d
docker compose logs -f

Systemd:

sudo systemctl edit netv

Add:

[Service]
Environment="LOG_LEVEL=DEBUG"

Then restart and view logs:

sudo systemctl restart netv
journalctl -u netv -f

Manual / Development:

LOG_LEVEL=DEBUG ./main.py
# or
./main.py --debug

Check out iptv-org/iptv -- a community-maintained collection of publicly available IPTV channels from around the world.

The free choice is iptv-org/epg, but this has never worked reliably for me.

For a more robust solution, consider Schedules Direct -- your membership helps fund Open Source projects.

Alternatively you can use tools/zap2xml.py. I've used this for over a year and found it to be very reliable -- it scrapes guide data from zap2it/gracenote.

HDHomeRun devices provide an M3U playlist, but it lacks EPG channel IDs. Use the tools/ to fetch guide data and align it:

# 1. Get your HDHomeRun lineup (replace IP with your device's IP)
wget http://192.168.1.87/lineup.m3u -O tools/lineup.m3u

# 2. Fetch TV guide data for your area
./tools/zap2xml.py --zip 90210

# 3. Align the M3U with the guide (adds tvg-id for EPG matching)
./tools/alignm3u.py --input tools/lineup.m3u --xmltv tools/xmltv.xml --output tools/ota.m3u

Then add tools/ota.m3u as an M3U source in neTV settings.

And set up a cron job to refresh the guide daily (e.g., 0 5 * * * /usr/bin/python3 /path/to/netv/tools/zap2xml.py --zip 90210 && cp /path/to/netv/tools/xmltv.xml /var/www/html/).

Hardware transcoding is auto-detected. Check Settings to see available encoders.

• Intel/AMD (VAAPI): Works automatically if /dev/dri exists.
• NVIDIA: Requires nvidia-container-toolkit. See NVIDIA GPU (NVENC) installation section for driver/compute compatibility table.
• No GPU / VPS: If /dev/dri doesn't exist, comment out the devices section in docker-compose.yml or compose will fail to start

Tested on Ubuntu 24.04 LTS, 25.04, and 25.10.

# Step 1: Remove existing NVIDIA packages
sudo apt purge -y '^nvidia-.*' '^libnvidia-.*' '^cuda-.*' '^libcuda-.*' '^cudnn[0-9]*-.*' '^libcudnn[0-9]*-.*'
sudo apt autoremove -y

# Step 2: Add NVIDIA CUDA repository
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt modernize-sources || true
sudo apt update

# Step 3: Install driver and CUDA toolkit
# For Turing+ GPUs (RTX 20 series and newer, compute >=7.5):
sudo apt install -y nvidia-open cuda-toolkit-13 cudnn9-cuda-13 libcudnn9-dev-cuda-13

# For Maxwell/Pascal GPUs (GTX 900/1000 series, compute <7.5):
# Driver 590 dropped support. Pin to 580 and use CUDA 12.9.
# Note: Maxwell/Pascal requires nvidia-driver (proprietary), not nvidia-open.
# sudo apt install -y nvidia-driver-pinning-580
# sudo apt install -y nvidia-driver-580 cuda-toolkit-12-9 cudnn9-cuda-12-9 libcudnn9-dev-cuda-12
# sudo update-alternatives --set cuda /usr/local/cuda-12.9

# Step 4: Configure environment
tee -a ~/.bashrc << 'EOF'
export CUDA_HOME=/usr/local/cuda
if [ -d $CUDA_HOME ]; then
    export PATH="${CUDA_HOME}/bin${PATH:+:${PATH}}"
    export LD_LIBRARY_PATH="${CUDA_HOME}/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}"
fi
unset CUDA_HOME
EOF
source ~/.bashrc

# Step 5: Verify installation
nvidia-smi --query-gpu=name,compute_cap,driver_version --format=csv,noheader
nvcc --version

Yes.

We leave pronunciation and meaning as an exercise for your idiom:

• N-E-T-V -- "Any TV", say it out loud
• ≠TV -- "Not Equals TV", because we're != traditional cable
• Net-V -- "Net Vision", because it streams video over your network
• Ni!-TV -- For the Knights who say Ni

We will also accept a shrubbery. One that looks nice. And not too expensive.

If you find neTV useful, consider buying me a coffee:

Apache License 2.0