# 📺 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)
![Docker](https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&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 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)

```bash
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:

```bash
PORT=9000 docker compose up -d
```

---

### Option B — Apache / Nginx

#### 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
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:

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

---

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

```css
/*
 * @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`:

```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/)
- ✅ 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)