GridTV/README.md

📺 GridTV

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

---

---

✨ 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
• ⚙️ Guided setup on first launch — no config files to edit manually
• 🔄 Auto-reload EPG every 30 minutes
• 0️⃣ Zero dependencies — vanilla PHP + nginx, that's it

---

🚀 Installation

Requirements

• A web server running PHP 8.0+ with php-fpm
• Nginx (or Apache)
• An EPG source in XMLTV format (e.g. Tunarr, Jellyfin, xTeVe...)
• (Optional) An M3U playlist

---

1. Clone the repo

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

---

2. Set permissions

# The web server needs write access to create config.json during setup
chmod 775 /var/www/gridtv
chown -R www-data:www-data /var/www/gridtv

---

3. 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

---

4. 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, for quick copy from the topbar

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

---

5. Editing the config later

# Via SSH
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
├── config.example.json  # Config template (copy to config.json and fill in)
├── .gitignore           # config.json excluded from the repo
└── README.md

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

---

⚙️ Advanced configuration

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

const PX_PER_MIN   = 5;   // Horizontal zoom (pixels per minute)
const HOURS_BEFORE = 1;   // Past hours visible in the grid
const HOURS_AFTER  = 3;   // Future hours visible in the grid
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)