📺 GridTV

A real-time IPTV TV guide, built for Tunarr and any XMLTV/M3U source.

---

---

🌐 Demo

A public demo instance is available here:

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

This demo runs with a sample XMLTV feed and fake channels to showcase the interface.

---

✨ Features

• 🎛️ Timeline grid — horizontal EPG-style view with a live "now" indicator
• 📱 Responsive — optimized list view on mobile
• ⏱️ Live progress bar on the currently airing program
• 🕶️ Past programs automatically dimmed
• 📋 Hover tooltip — title, synopsis, season/episode, schedule, duration
• 🔗 One-click copy buttons for EPG & M3U URLs in the topbar
• ▶️ Built-in HLS player — click any channel or live program to watch in a PiP overlay
• 🔀 HTTP→HTTPS proxy — streams Tunarr over HTTP transparently from an HTTPS page
• 🎨 Theme system — drop a CSS file in themes/ and it appears in the menu automatically
• ⚙️ Guided setup on first launch — no config files to edit manually
• 🔄 Auto-reload EPG every 30 minutes
• 0️⃣ Zero JS dependencies — vanilla PHP, hls.js loaded from CDN

---

🚀 Installation

Requirements

• A web server running PHP 8.0+ with php-curl extension
• Apache or Nginx
• An EPG source in XMLTV format (e.g. Tunarr, Jellyfin, xTeVe...)
• (Optional) An M3U playlist — required for the built-in player

---

1. Clone the repo

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

---

2. Set permissions

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

---

3a. Configure Nginx

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;
    }
}

💡 Adjust the PHP version (php8.2-fpm) to match the one installed on your server.

nginx -t && systemctl reload nginx

---

3b. Configure Apache

<VirtualHost *:80>
    ServerName guide.your-domain.com
    DocumentRoot /var/www/gridtv

    <Directory /var/www/gridtv>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

a2enmod php8.4 rewrite
systemctl reload apache2

---

4. Install php-curl

The built-in player uses proxy.php to relay HTTP streams over HTTPS. This requires the php-curl extension:

# Debian/Ubuntu — adjust version to match your PHP
apt install php8.4-curl

# Then reload the web server
systemctl reload apache2   # or: systemctl reload nginx

---

5. First launch — Setup

Open your browser at http://guide.your-domain.com.

GridTV detects the missing config and automatically redirects you to the setup page:

Field	Description
Group name	Displayed top-left in the topbar (e.g. MyTV, FamilyTV...)
EPG URL (XMLTV)	Your electronic program guide URL
M3U URL (optional)	Your IPTV playlist — used by the built-in player to match channels to streams

Once submitted, config.json is created on the server. The setup page becomes inaccessible.

---

6. Editing the config later

nano /var/www/gridtv/config.json

{
  "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"
}

---

📁 Project structure

gridtv/
├── index.php            # The TV guide (redirects to setup if no config found)
├── setup.php            # First-launch configuration page
├── proxy.php            # HTTP→HTTPS stream proxy (required for the player)
├── config.example.json  # Config template
├── .gitignore           # config.json excluded from the repo
├── themes/              # CSS theme files
│   ├── default.css      # Dark studio (default)
│   ├── magazine.css     # Vintage newspaper
│   ├── cyberpunk.css    # Neon on black
│   └── steampunk.css    # Victorian copper
└── README.md

config.json is listed in .gitignore — your private URLs will never be pushed to GitHub.

---

🎨 Themes

GridTV ships with 4 built-in themes. To add your own, create a CSS file in themes/ with these metadata comments at the top:

/*
 * @name  My Theme
 * @emoji 🌙
 */

:root {
  --bg: #0a0b0d;
  --accent: #e8c842;
  /* ... */
}

Drop it in themes/ — it appears in the theme selector automatically, no code changes needed.

---

▶️ Built-in Player

Click on any channel name or currently airing program to open a PiP (picture-in-picture) player in the bottom-right corner.

The player requires:

• An M3U URL configured in setup (used to match channel names to stream URLs)
• The php-curl extension installed on the server

If your stream source (e.g. Tunarr) serves streams over HTTP while GridTV runs on HTTPS, proxy.php handles the relay transparently — no browser mixed-content errors.

---

⚙️ Advanced configuration

The following constants can be tweaked directly in index.php:

const PX_PER_MIN = 5;    // Horizontal zoom (pixels per minute)
const GRID_HOURS = 72;   // Total timeline duration (hours)
const ROW_H      = 80;   // Channel row height (px)

---

🧩 EPG Compatibility

GridTV parses the standard XMLTV format. Tested with:

• ✅ Tunarr
• ✅ xTeVe
• ✅ Jellyfin (via LiveTV plugin)
• ✅ Any XMLTV-compliant file

---

🤝 Contributing

PRs are welcome! Got an idea, a fix, or a feature request — open an issue or send a PR directly.

---

📄 License

GNU Affero (AGPLv3)