EPG Viewer 📺

A modern, fast, and memory-efficient EPG (Electronic Program Guide) web viewer built with FastAPI, lxml, Tailwind CSS, and modern JavaScript. It provides a vertical-time / horizontal-channel schedule grid, live full-text search, timezone-aware XMLTV parsing, customizable channel views, local logo support, and seamless XML hot-reloading.

---

✨ Features

• 🕒 Interactive Schedule Grid: Vertical time layout with customizable scale zoom (15m, 30m, 1h, 2h, 4h) and direct auto-scroll to the top of the first programme in the view.
• 📺 Channel & Favorites Management:
  • Filter schedule grid to Show Favorites Only.
  • Quick Select/Deselect All batch controls for setting favorites or hiding channels.
  • Reset to Defaults button to restore initial settings and channel selections.
• 📤 Custom XML Upload & Session Loading: Load custom XMLTV files directly on the fly via the UI.
• 🔊 Enhanced Multi-Track Audio Support: Parses multiple audio streams (<audio id="...">, <desc>, <extdesc>) and translates IDs into clear English descriptions (e.g., Stereo (2.0), Surround Sound (5.1), Surround Sound ( 22.2)) displayed on separate lines.
• 🖼️ Flexible Video Resolution Parsing: Auto-detects 4K/QFHD and 8K broadcasts with Ultra High Definition labeling in programme details.
• 🖼️ Local Logo Bundling: Embedded and external local channel logo support (app/static/logos/ or logos/ next to .exe) with automatic fallback to XMLTV <icon src="..." /> tags. (W.I.P.)
• ⚡ High Performance: Streaming XML parsing using lxml.etree.iterparse to handle massive EPG files with low memory usage.
• 🔄 Hot Reloading & Reset: Automatically detects modifications to local epg.xml files and resets to default disk files on browser page refresh.
• 🔍 Instant Search & Filters: Filter by keyword, channel, category, HD resolution, premieres, or new episodes.
• 📋 Detailed Metadata View: Programme details modal with multi-track specs, selectable text, and JSON export capabilities.
• 🎯 First Available Date Detection: Automatically snaps the view to the earliest available programme date in your XML dataset.
• 🎨 Responsive Dark UI: Sleek dark theme powered by Tailwind CSS.
• 🖥️ Lightweight Native Desktop GUI: Run without browser using --gui via pywebview (uses native OS Edge WebView2 / WebKit for a tiny ~30MB executable).
• 📅 ICS Export: Export .ics events directly to your calendar.

---

🚀 Quick Start (Running from Source)

Prerequisites

• Python 3.10+ (tested on Python 3.13.2)

Installation

1. Clone the repository:

   git clone [https://git.raiza.dev/Raiza.dev/EPGViewer.git](https://git.raiza.dev/Raiza.dev/EPGViewer.git)
   cd EPGViewer
   

2. Create a virtual environment & install dependencies:

   python -m venv venv
   
   # On Windows:
   venv\Scripts\activate
   # On macOS/Linux:
   source venv/bin/activate
   
   pip install -r requirements.txt
   

3. Provide an EPG file:
   Place your epg.xml or xmltv.xml in the root directory. You can download a sample XMLTV file here:
   👉 Sample XMLTV File (~9 MB)
4. If you're on Linux: (Optional: GUI only)

    sudo apt install gir1.2-ayatanaappindicator3-0.1 gir1.2-appindicator3-0.1 -y
   

5. Launch the server:

   python main.py
   

---

📦 Building a Standalone Executable (.exe)

1. Install pyinstaller:

   pip install pyinstaller
   

2. Build Command:

   pyinstaller --noconfirm --clean --onefile --console --noupx --name "EPGViewer" --add-data "app/static;app/static" --add-data "app/templates;app/templates" --add-data "app/static/logos;app/static/logos" --hidden-import "uvicorn.logging" --hidden-import "uvicorn.loops" --hidden-import "uvicorn.loops.auto" --hidden-import "uvicorn.protocols" --hidden-import "uvicorn.protocols.http" --hidden-import "uvicorn.protocols.http.auto" --hidden-import "uvicorn.lifespan" --hidden-import "uvicorn.lifespan.on" --hidden-import "PyQt6" --hidden-import "PyQt6.QtCore" --hidden-import "PyQt6.QtWidgets" --hidden-import "PyQt6.QtWebEngineCore" --hidden-import "PyQt6.QtWebEngineWidgets" main.py
   

3. How to Run the Executable:
   • Navigate to the generated dist/ directory.
   • Place your epg.xml file in the same folder as EPGViewer.exe.
   • (Optional) Place custom channel logo images inside a logos/ folder next to EPGViewer.exe.
   • Double-click EPGViewer.exe.
   • A console window will pop up, automatically start the server, and open your web browser.
   • To stop the application, press CTRL + C in the console window or close the terminal.

---

⚙️ Configuration & Environment Variables

You can configure execution via environment variables:

Variable	Default	Description
HOST	127.0.0.1	Host IP address for Uvicorn binding.
PORT	8000	Port number for Uvicorn binding.
XMLTV_PATH	(Auto-scan)	Comma-separated paths to XMLTV files (e.g. EPG1.xml,EPG2.xml)