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, and seamless XML hot-reloading.

---

✨ Features

• 🕒 Interactive Schedule Grid: Vertical time layout with customizable scale zoom (15m, 30m, 1h, 2h, 4h).
• ⚡ High Performance: Streaming XML parsing using lxml.etree.iterparse to handle massive EPG files with low memory usage.
• 🔄 Hot Reloading: Automatically detects modifications to local epg.xml files and updates the in-memory cache on the fly.
• 🔍 Instant Search & Filters: Filter by keyword, channel, category, HD resolution, premieres, or new episodes.
• 📋 Selectable & Copyable Modal: Detailed metadata view for every programme, with selectable text and JSON export capabilities.
• 🎯 First Available Date Detection: Automatically snaps the default view to the earliest available date in your XML dataset.
• 🎨 Responsive Dark Mode: Sleek dark UI powered by Tailwind CSS.

---

🚀 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
   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 (http://raiza.dev/capbox.data/xmltv.xml)
4. Launch the server:\

   python main.py
   

📦 Building a Standalone Windows Executable (.exe)

1. Install pyinstaller:

   pip install pyinstaller
   

2. Build Command:

   pyinstaller --noconfirm --onefile --console --name "EPGViewer" --add-data "app/static;app/static" --add-data "app/templates;app/templates" --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" main.py
   

3. How to Run the Executable:
4. Navigate to the generated dist/ directory.
5. Place your epg.xml file in the same folder as EPGViewer.exe.
6. Double-click EPGViewer.exe.
7. A console window will pop up, automatically start the server, and open your web browser.
8. 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)