# 📺 GridTV

> A real-time IPTV TV guide, built for [Tunarr](https://github.com/chrisbenincasa/tunarr) and any XMLTV/M3U source.

![PHP](https://img.shields.io/badge/PHP-8.0+-777BB4?style=flat-square&logo=php&logoColor=white)
![Apache](https://img.shields.io/badge/Apache-ready-D22128?style=flat-square&logo=apache&logoColor=white)
![Nginx](https://img.shields.io/badge/Nginx-ready-009639?style=flat-square&logo=nginx&logoColor=white)
![License](https://img.shields.io/badge/license-AGPLv3-blue?style=flat-square)

---

![GridTV Preview](assets/preview.png)

---

## 🌐 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
- 📡 **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
- ⚙️ **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 |
| **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.**

---

### 6. Editing the config later

```bash
nano /var/www/gridtv/config.json
```

```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 — no manual action needed.

---

## 📁 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.

---

## 📡 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 (picture-in-picture) player in the bottom-right corner.

The player requires:
- An **M3U URL** configured in the active source (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)