📺 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 sample XMLTV feeds 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
• 📡 Multi-EPG sources — configure multiple EPG/M3U sources, switch from the topbar
• 👤 Personal EPG — optionally let visitors use your instance with their own EPG/M3U URLs (saved in localStorage)
• ⚙️ 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 — or just use Docker
• An EPG source in XMLTV format (e.g. Tunarr, Jellyfin, xTeVe...)
• (Optional) An M3U playlist — required for the built-in player

---

Option A — Docker (recommended)

git clone https://github.com/Johnnybegood90/GridTV.git
cd GridTV
docker compose up -d

Then open http://localhost:8080 and follow the setup wizard.

To run on a custom port:

PORT=9000 docker compose up -d

---

Option B — Apache / Nginx

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
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
EPG sources	Add one or more XMLTV sources, each with an optional M3U URL
Personal EPG	Toggle to allow visitors to use your instance with their own EPG/M3U

Once submitted, config.json is created on the server. The setup page becomes inaccessible until you re-enter your admin key.

---

Editing the config later

You can re-open the setup page at any time using the admin key generated during first setup:

http://guide.your-domain.com/setup.php

Or edit config.json directly:

nano /var/www/gridtv/config.json

{
  "group_name": "MyGroup TV",
  "epg_sources": [
    {
      "name": "Main",
      "epg_url": "http://192.168.0.3:8000/api/xmltv.xml",
      "m3u_url": "http://192.168.0.3:8000/api/channels.m3u"
    },
    {
      "name": "Sports",
      "epg_url": "http://192.168.0.3:8001/api/xmltv.xml",
      "m3u_url": ""
    }
  ],
  "allow_personal_epg": true
}

Instances running the old single-source format (epg_url at root) are migrated automatically on first load.

---

📁 Project structure

gridtv/
├── index.php            # Entry point
├── setup.php            # First-launch + re-configuration page
├── proxy.php            # HTTP→HTTPS stream proxy
├── config.example.json  # Config template
├── Dockerfile
├── docker-compose.yml
├── .gitignore           # config.json excluded
├── themes/              # CSS theme files
│   ├── default.css
│   ├── magazine.css
│   ├── cyberpunk.css
│   └── steampunk.css
└── src/
    ├── config.php       # Config loader + migration
    ├── tpl/             # HTML templates
    │   ├── head.php
    │   ├── topbar.php
    │   ├── grid.php
    │   ├── modals.php
    │   └── footer.php
    └── js/              # JavaScript modules
        ├── config.js    # Constants + PHP-injected vars
        ├── utils.js     # Helpers, clock, EPG fetch
        ├── epg.js       # Grid rendering
        ├── mobile.js    # Mobile list view
        ├── tooltip.js   # Hover tooltip
        ├── sources.js   # Multi-EPG switcher
        ├── m3u.js       # M3U parser
        ├── player.js    # HLS PiP player
        ├── themes.js    # Theme switcher
        └── live.js      # Live updates + responsive

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.

---

📡 Multiple EPG Sources

Configure as many EPG/M3U sources as you want in config.json. A dropdown appears in the topbar when more than one source is defined.

If allow_personal_epg is true, a "✏ Personal EPG" option appears in the dropdown, letting any visitor enter their own XMLTV/M3U URLs. Their choice is saved in localStorage — zero server impact.

---

▶️ Built-in Player

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

Requires an M3U URL in the active source and the php-curl extension. The proxy.php handles HTTP→HTTPS relay transparently.

---

⚙️ Advanced configuration

Tweak these constants in src/js/config.js:

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
• ✅ Any XMLTV-compliant source

---

🤝 Contributing

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

---

📄 License

GNU Affero General Public License v3.0 (AGPLv3)

---

🗺️ Roadmap

✅ Done

• Timeline grid with live "now" indicator
• Mobile responsive list view
• Built-in HLS PiP player
• HTTP→HTTPS proxy
• Theme system (4 built-in themes)
• Multi-EPG sources with topbar switcher
• Personal EPG (localStorage)
• Modular codebase (src/tpl + src/js)
• Docker support
• Search — filter grid by channel name or program title/synopsis

🔜 Coming soon

• Favorites — pin channels to the top of the grid (localStorage)
• Setup re-editable — reopen setup.php with an admin key, no SSH required
• Dark/Light auto mode — follow system preference when using the default theme
• Grid export — export today's schedule as PDF or image