📺 TVx — the warmth of modern nostalgia

This is the way - television you remember feeling: present, unhurried, analog.

• ❤️‍🔥 TVx brings back the ritual of watching—not scrolling, not seeking, just being with what's on.
• 🎞️ Like the grain of 35mm film or the crackle before a record drops, it trades sterile perfection for something alive.
• 📟 Curved glass. Gentle flicker. Scanlines that breathe.
• 🎥 The soft bokeh of vintage anamorphic lenses —edges that blur like looking through aged glass, chromatic fringing that feels organic, not digital.
• ⏱️ The glow of a neon clock counting Saturday mornings long past.

🎯 What it does

An IPTV + EPG viewer for Tunarr (Plex/Jellyfin) playlists and XMLTV guides. Built for channel surfing, not catalog anxiety. Anti‑algorithm. Pro‑moment. Vibing.

Architecture: TVx is a client-side web frontend that interfaces with your Tunarr backend alongside your Plex library. It consumes M3U playlists and XMLTV EPG data generated by Tunarr, while displaying rich metadata and artwork from your Plex media server.

💾 Install

docker run -d \
  --name tvx \
  -p 8777:80 \
  --restart unless-stopped \
  -e VITE_M3U_URL="http://your-tunarr-ip-address:8000/api/channels.m3u" \
  -e VITE_XMLTV_URL="http://your-tunarr-ip-address:8000/api/xmltv.xml" \
  ghcr.io/dopeytree/tvx:latest

docker run -d \
  --name tvx \
  -p 8777:80 \
  --restart unless-stopped \
  -e VITE_M3U_URL="http://your-tunarr-ip-address:8000/api/channels.m3u" \
  -e VITE_XMLTV_URL="http://your-tunarr-ip-address:8000/api/xmltv.xml" \
  ghcr.io/dopeytree/tvx:latest

services:
  tvx:
    image: ghcr.io/dopeytree/tvx:latest
    ports:
      - "8777:80"
    restart: unless-stopped
    environment:
      - TZ=UTC
      - VITE_M3U_URL=http://your-tunarr-ip-address:8000/api/channels.m3u
      - VITE_XMLTV_URL=http://your-tunarr-ip-address:8000/api/xmltv.xml
    volumes:
      - ./config:/config

docker-compose up -d

# Build the image
docker build -t tvx .

# Run it
docker run -d \
  -p 8777:80 \
  --name tvx \
  -e VITE_M3U_URL="http://your-tunarr-ip-address:8000/api/channels.m3u" \
  -e VITE_XMLTV_URL="http://your-tunarr-ip-address:8000/api/xmltv.xml" \
  tvx

Main View

Full TV Guide View

Full TV Guide View + Poster

Full screen (vintage filter off) View

Full screen (vintage filter on) View

Buy me a coffee

GitHub Sponsors Buy Me A Coffee

✨ Why it feels different

• ⚡ Instant channel surfing — hold ↑/↓ to skim; land when something catches your eye
• 📟 CRT warmth — curvature, chromatic aberration, scanlines, vignette
• 📅 Full TV guide — press G for a 12‑hour timeline across all channels with poster artwork
• 🎬 Theater modes — click the player to cycle views (guide → normal → immersive)
• 📊 Comprehensive logging — All user interactions logged to Docker container for monitoring and debugging
• 🏷️ Smart channel names — strips filler words, adds icons:
  • Pulp Fiction Movies → Pulp Fiction [🎬]
  • The Hitchhiker's Guide to the Galaxy Shows → The Hitchhiker's Guide to the Galaxy [📺]
  • Extreme Ironing Sports → Extreme Ironing [🏆]
  • The Tesla Files History → The Tesla Files [📜]
  • Cosmos Documentaries → Cosmos [📜]

🚀 Quick start

• You need to have set up Plex/Jellyfin media server
• Tunarr or Dizquetv for channel streaming
• Configure your M3U and XMLTV URLs via Docker environment variables (see Docker section below)
• Open - http://localhost:8777
• That's it
• Use the up/down arrow keys to browse your personal media

📚 Documentation

• Full Documentation - Complete documentation index

⌨️ Keyboard shortcuts

📊 Logging & Monitoring

TVx provides comprehensive logging of all user interactions directly to your Docker container logs, making it easy to monitor usage and troubleshoot issues in Unraid or other container environments.

Docker Compose Logs:

docker-compose logs -f tvx

Sample Log Output

2025-01-15 10:30:15 INFO: Opened: Program Popup for "Breaking Bad" on AMC
2025-01-15 10:30:20 INFO: Opened: Google Search for "Breaking Bad (2008)"
2025-01-15 10:30:25 INFO: Selected: Channel "HBO" in Sidebar
2025-01-15 10:30:30 INFO: Opened: Full TV Guide
2025-01-15 10:30:45 INFO: Closed: Program Popup

🛠️ Tech Stack

• ⚛️ React 18 + TypeScript — Modern, type-safe UI
• ⚡ Vite — Lightning-fast build tool
• 🎨 WebGL Fragment Shaders — Custom CRT effects and visual processing
• 📡 HLS.js — Adaptive HTTP Live Streaming
• 🎭 Radix UI + Tailwind CSS — Accessible components, utility-first styling
• 🎯 Lucide Icons — Beautiful, consistent iconography

🌐 Browser Support

Works best in modern browsers with WebGL support:

• 🟢 Chrome/Edge 90+
• 🟠 Firefox 88+
• 🔵 Safari 14+

📜 License

PolyForm Noncommercial 1.0.0

This project is licensed under the PolyForm Noncommercial License 1.0.0. You are free to use, modify, and share this software for any noncommercial purpose. Commercial use requires a separate license.

In brief: Use it for joy, learn from it, fork it, improve it - just don't sell it or use it to make money without permission.

🤝 Contributing

This is a personal passion project, but contributions, suggestions, and feedback are welcome! Feel free to open issues or submit pull requests.