<img src="https://img.shields.io/badge/PHP-8.0+-777BB4?style=flat-square&logo=php&logoColor=white">{=html} <img src="https://img.shields.io/badge/Nginx-ready-009639?style=flat-square&logo=nginx&logoColor=white">{=html} <img src="https://img.shields.io/badge/license-AGPLv3-blue?style=flat-square">{=html}

</p>

🌐 Demo

A public demo instance is available:

👉 https://guide.demo.johnnybegood.fr/

The demo runs with fake channels and sample XMLTV data to showcase the interface.

✨ Features

GridTV focuses on simplicity and usability.

Interface

Timeline grid similar to classic EPG interfaces\
Horizontal scrolling with a live "Now" indicator
Past programs automatically dimmed
Live progress bar on currently airing program
Hover tooltip with full program details

Mobile

Responsive layout
Automatic switch to list view on mobile

Convenience

One-click copy buttons for EPG and M3U URLs
Automatic EPG refresh every 30 minutes
Guided setup on first launch

Architecture

Zero dependencies
Pure PHP + HTML + JS
Works behind nginx or apache

🧩 Compatibility

GridTV parses the standard XMLTV format and works with any compatible source.

Tested with:

Tunarr
xTeVe
Jellyfin Live TV
Any XMLTV-compliant generator

🚀 Installation

Requirements

PHP 8.0+ with php-fpm
nginx or apache
An XMLTV EPG source
Optional M3U playlist

1. Clone the repository

git clone https://github.com/Johnnybegood90/GridTV.git /var/www/gridtv
cd /var/www/gridtv

2. Set permissions

The web server must be able to create the configuration file.

chmod 775 /var/www/gridtv
chown -R www-data:www-data /var/www/gridtv

3. Configure nginx

Example configuration:

server {
    listen 80;
    server_name guide.your-domain.com;

    root /var/www/gridtv;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    }
}

Reload nginx:

nginx -t && systemctl reload nginx

⚙️ First launch

Open your browser:

http://guide.your-domain.com

GridTV automatically detects the missing configuration and opens the setup page.

You will need to provide:

Field Description

Group name Displayed in the interface header EPG URL XMLTV program guide M3U URL Optional IPTV playlist

Once submitted, config.json is created automatically.

The setup page then becomes inaccessible.

🛠 Editing the configuration later

nano /var/www/gridtv/config.json

Example configuration:

{
  "group_name": "MyGroup TV",
  "epg_url": "http://192.168.0.3:8000/api/xmltv.xml",
  "m3u_url": "http://192.168.0.3:8000/api/channels.m3u"
}

⚙️ Advanced configuration

These constants can be adjusted in index.php:

const PX_PER_MIN   = 5;
const HOURS_BEFORE = 1;
const HOURS_AFTER  = 3;
const ROW_H        = 80;

Meaning:

PX_PER_MIN → zoom level of the timeline\
HOURS_BEFORE → past hours visible\
HOURS_AFTER → future hours visible\
ROW_H → height of channel rows

📁 Project structure

gridtv/
│
├── index.php
├── setup.php
├── config.example.json
├── .gitignore
└── README.md

config.json is ignored by git to prevent leaking private URLs.

🤝 Contributing

Pull requests are welcome.

Feel free to open issues for:

bug reports
feature requests
improvements

📄 License

GNU Affero General Public License v3 (AGPLv3)