254 lines
6.3 KiB
Markdown
254 lines
6.3 KiB
Markdown
# 📺 GridTV
|
|
|
|
> A real-time IPTV TV guide, built for [Tunarr](https://github.com/chrisbenincasa/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
|
|
|
|
```bash
|
|
git clone https://github.com/Johnnybegood90/GridTV.git /var/www/gridtv
|
|
cd /var/www/gridtv
|
|
```
|
|
|
|
---
|
|
|
|
### 2. Set permissions
|
|
|
|
```bash
|
|
chmod 775 /var/www/gridtv
|
|
chown -R www-data:www-data /var/www/gridtv
|
|
```
|
|
|
|
---
|
|
|
|
### 3a. Configure Nginx
|
|
|
|
```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.
|
|
|
|
```bash
|
|
nginx -t && systemctl reload nginx
|
|
```
|
|
|
|
---
|
|
|
|
### 3b. Configure Apache
|
|
|
|
```apache
|
|
<VirtualHost *:80>
|
|
ServerName guide.your-domain.com
|
|
DocumentRoot /var/www/gridtv
|
|
|
|
<Directory /var/www/gridtv>
|
|
AllowOverride All
|
|
Require all granted
|
|
</Directory>
|
|
</VirtualHost>
|
|
```
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
nano /var/www/gridtv/config.json
|
|
```
|
|
|
|
```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:
|
|
|
|
```css
|
|
/*
|
|
* @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`:
|
|
|
|
```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](https://github.com/chrisbenincasa/tunarr)
|
|
- ✅ [xTeVe](https://github.com/xteve-project/xTeVe)
|
|
- ✅ [Jellyfin](https://jellyfin.org/) (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)
|