IPTV Guide

IPTV Guide is a Web-Based Electronic Program Guide Viewer for IPTV channels, providing a fast and user-friendly way to explore TV schedules in real time.

About The Project

This project is a self-hosted solution for browsing IPTV channels and their schedules in real time through a modern web interface.

The frontend is built with React and powered by Planby. It provides a fast and responsive interface where users can scroll through channels, view current and upcoming programs, filter by group, search by keywords, and open modals with detailed information or playback options.

The backend, implemented with Flask, is responsible for fetching, parsing and serving IPTV data. It supports M3U playlists and XML electronic program guides, transforming them into a consistent format for the frontend. It also includes caching, automatic scheduled updates, local backups as fallback, and file-based logging to ensure robustness and availability, even under unstable network conditions.

Note

While the system is minimally customizable, it is designed to run autonomously on a server, avoiding the need for manual downloads or additional tools on the client side.

How To Run

Tip

See Production Notes for guidance on deploying the app in a production environment.

Backend

Requirements

Make sure Python is installed on your system. Then install the required dependencies with:

pip install -r backend/requirements.txt

Configuration

Open the backend/config/config.py file to adjust settings such as update intervals, source URLs, backup locations, logging level, and more.

Warning

If you use the default M3U URL, ZeroNet must be installed and running.

Usage

Once the dependencies are installed, run the backend with:

python -m backend.app

The server will be available at http://localhost:5000, exposing the following API endpoints:

• /api/channels — returns the parsed IPTV channel list.
• /api/epg — returns the parsed electronic program guide.
• /api/health — returns a basic health check of the server.

Frontend

Requirements

Make sure Node.js is installed on your system. Then install the required dependencies with:

cd frontend
npm install

Configuration

Open the frontend/src/utils/constants.js file to adjust API URLs to match your backend server.

Important

If you use the default settings, the frontend will try to connect to the public backend server hosted by the author at https://api.tebas-ladron.me. This endpoint is not guaranteed to remain available and may be removed or changed at any time.

Build

Once the dependencies are installed, build the frontend with:

npm run build

Usage

Once the build is finished, run the frontend server with:

npm run preview

The app will be available at http://localhost:5173.

About the Code

This project is divided into two main parts: the backend, responsible for data processing and API serving; and the frontend, responsible for rendering the guide and handling user interaction.

Backend

The backend is built with Flask and performs the following tasks:

• Data fetching: downloads the IPTV playlist and program guide from configurable URLs.
• Parsing and transformation: parses raw data into a structured format, groups streams by channel, validates logos, filters program entries, and more.
• Caching and backups: stores the latest valid data in memory and saves local backups to disk to ensure resilience against network or source failures.
• Scheduled updates: runs periodic tasks to refresh the playlist and EPG in the background, ensuring the data is always up-to-date.
• Logging: records events and errors into timestamped log files for easy debugging and monitoring.
• API serving: exposes endpoints to retrieve channel and EPG data in JSON format for the frontend to consume.

Note

The backend is designed to be moderately customizable through the configuration file, allowing users to adapt it to their needs. It runs independently from the frontend and can be deployed almost anywhere.

Frontend

The frontend is a single-page application built with React and Planby, designed to render the IPTV guide as a timeline-based interface. It offers the following features:

• Channel browsing: scrollable view of all available IPTV channels.
• Timeline-based EPG: visual layout of programs over time, with support for horizontal scrolling and current-time tracking.
• Modals for channels and programs: clickable elements open overlays with detailed information or playback options.
• Filtering and search: filter channels by group or search by keywords across channel names, program titles, and descriptions.
• Responsive UI: optimized for both desktop and mobile use.

Note

The frontend is built to be lightweight and fast, considering the large amount of data it handles. All content is rendered dynamically at runtime using the backend API.

Warning

Some UI features are limited by the capabilities of the Planby free tier, such as support for only a single day of schedule data.

Production Notes

This project is designed to be self-hosted and can be deployed in production using different tools or setups depending on your environment and requirements.

Tip

The backend and frontend can be hosted on different machines, as long as the frontend is properly configured to point to the backend API URL.

A typical production setup might include:

• Running the backend with a production WSGI server such as Gunicorn.
• Serving the frontend as static files via GitHub Pages, NGINX, or a CDN.
• Using ZeroNet to access private or decentralized IPTV playlists.
• Setting up a reverse proxy to unify frontend and backend endpoints under a single domain.
• Setting up HTTPS with Let's Encrypt, especially when frontend and backend are served from different origins.
• Managing backend processes with a supervisor such as systemd to ensure automatic restarts and resilience.

Note

The application has been tested on a low-spec device (Raspberry Pi Zero W) and performed well under light usage. Actual performance may vary depending on the size of the data and number of concurrent users.