Edit readme
This commit is contained in:
Johnnybegood90
@@ -1,74 +1,123 @@
|
||||
# 📺 GridTV
|
||||
|
||||
> A real-time IPTV TV guide, built for [Tunarr](https://github.com/chrisbenincasa/tunarr) and any XMLTV/M3U source.
|
||||
A lightweight **real-time IPTV TV guide** designed for **Tunarr** and
|
||||
any **XMLTV / M3U source**.
|
||||
|
||||
|
||||
|
||||
|
||||
GridTV displays your EPG in a clean horizontal timeline similar to
|
||||
traditional TV guides, accessible from any browser.
|
||||
|
||||
---
|
||||
```{=html}
|
||||
<p align="center">
|
||||
```
|
||||
`<img src="assets/preview.png" width="75%">`{=html}
|
||||
`<img src="assets/previewmobile.png" width="18%">`{=html}
|
||||
```{=html}
|
||||
</p>
|
||||
```
|
||||
```{=html}
|
||||
<p align="center">
|
||||
```
|
||||
`<img src="https://img.shields.io/badge/PHP-8.0+-777BB4?style=flat-square&logo=php&logoColor=white">`{=html}
|
||||
`<img src="https://img.shields.io/badge/Nginx-ready-009639?style=flat-square&logo=nginx&logoColor=white">`{=html}
|
||||
`<img src="https://img.shields.io/badge/license-AGPLv3-blue?style=flat-square">`{=html}
|
||||
```{=html}
|
||||
</p>
|
||||
```
|
||||
|
||||
 
|
||||
------------------------------------------------------------------------
|
||||
|
||||
---
|
||||
# 🌐 Demo
|
||||
|
||||
## 🌐 Demo
|
||||
|
||||
A public demo instance is available here:
|
||||
A public demo instance is available:
|
||||
|
||||
👉 https://guide.demo.johnnybegood.fr/
|
||||
|
||||
This demo runs with a sample XMLTV feed and fake channels to showcase the interface.
|
||||
The demo runs with **fake channels and sample XMLTV data** to showcase
|
||||
the interface.
|
||||
|
||||
---
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## ✨ Features
|
||||
# ✨ 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
|
||||
GridTV focuses on simplicity and usability.
|
||||
|
||||
---
|
||||
## Interface
|
||||
|
||||
## 🚀 Installation
|
||||
- Timeline grid similar to classic EPG interfaces\
|
||||
- Horizontal scrolling with a live **"Now" indicator**
|
||||
- **Past programs automatically dimmed**
|
||||
- **Live progress bar** on currently airing program
|
||||
- **Hover tooltip** with full program details
|
||||
|
||||
### Requirements
|
||||
## Mobile
|
||||
|
||||
- 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**
|
||||
- Responsive layout
|
||||
- Automatic switch to **list view on mobile**
|
||||
|
||||
---
|
||||
## Convenience
|
||||
|
||||
### 1. Clone the repo
|
||||
- One-click **copy buttons** for EPG and M3U URLs
|
||||
- **Automatic EPG refresh** every 30 minutes
|
||||
- **Guided setup on first launch**
|
||||
|
||||
```bash
|
||||
## Architecture
|
||||
|
||||
- Zero dependencies
|
||||
- Pure **PHP + HTML + JS**
|
||||
- Works behind **nginx or apache**
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 🧩 Compatibility
|
||||
|
||||
GridTV parses the standard **XMLTV format** and works with any
|
||||
compatible source.
|
||||
|
||||
Tested with:
|
||||
|
||||
- Tunarr
|
||||
- xTeVe
|
||||
- Jellyfin Live TV
|
||||
- Any XMLTV-compliant generator
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 🚀 Installation
|
||||
|
||||
## Requirements
|
||||
|
||||
- PHP **8.0+** with **php-fpm**
|
||||
- nginx or apache
|
||||
- An **XMLTV EPG source**
|
||||
- Optional **M3U playlist**
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 1. Clone the repository
|
||||
|
||||
``` bash
|
||||
git clone https://github.com/Johnnybegood90/GridTV.git /var/www/gridtv
|
||||
cd /var/www/gridtv
|
||||
```
|
||||
|
||||
---
|
||||
------------------------------------------------------------------------
|
||||
|
||||
### 2. Set permissions
|
||||
## 2. Set permissions
|
||||
|
||||
```bash
|
||||
# The web server needs write access to create config.json during setup
|
||||
The web server must be able to create the configuration file.
|
||||
|
||||
``` bash
|
||||
chmod 775 /var/www/gridtv
|
||||
chown -R www-data:www-data /var/www/gridtv
|
||||
```
|
||||
|
||||
---
|
||||
------------------------------------------------------------------------
|
||||
|
||||
### 3. Configure Nginx
|
||||
## 3. Configure nginx
|
||||
|
||||
```nginx
|
||||
Example configuration:
|
||||
|
||||
``` nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name guide.your-domain.com;
|
||||
@@ -87,38 +136,46 @@ server {
|
||||
}
|
||||
```
|
||||
|
||||
> 💡 Adjust the PHP version (`php8.2-fpm`) to match the one installed on your server.
|
||||
Reload nginx:
|
||||
|
||||
```bash
|
||||
``` bash
|
||||
nginx -t && systemctl reload nginx
|
||||
```
|
||||
|
||||
---
|
||||
------------------------------------------------------------------------
|
||||
|
||||
### 4. First launch — Setup
|
||||
# ⚙️ First launch
|
||||
|
||||
Open your browser at `http://guide.your-domain.com`.
|
||||
Open your browser:
|
||||
|
||||
GridTV detects the missing config and automatically redirects you to the setup page:
|
||||
http://guide.your-domain.com
|
||||
|
||||
| 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 |
|
||||
GridTV automatically detects the missing configuration and opens the
|
||||
**setup page**.
|
||||
|
||||
Once submitted, `config.json` is created on the server. **The setup page becomes inaccessible.**
|
||||
You will need to provide:
|
||||
|
||||
---
|
||||
Field Description
|
||||
------------ -----------------------------------
|
||||
Group name Displayed in the interface header
|
||||
EPG URL XMLTV program guide
|
||||
M3U URL Optional IPTV playlist
|
||||
|
||||
### 5. Editing the config later
|
||||
Once submitted, **config.json is created automatically**.
|
||||
|
||||
```bash
|
||||
# Via SSH
|
||||
The setup page then becomes inaccessible.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 🛠 Editing the configuration later
|
||||
|
||||
``` bash
|
||||
nano /var/www/gridtv/config.json
|
||||
```
|
||||
|
||||
```json
|
||||
Example configuration:
|
||||
|
||||
``` json
|
||||
{
|
||||
"group_name": "MyGroup TV",
|
||||
"epg_url": "http://192.168.0.3:8000/api/xmltv.xml",
|
||||
@@ -126,53 +183,54 @@ nano /var/www/gridtv/config.json
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 📁 Project structure
|
||||
# ⚙️ Advanced configuration
|
||||
|
||||
```
|
||||
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
|
||||
These constants can be adjusted in **index.php**:
|
||||
|
||||
``` js
|
||||
const PX_PER_MIN = 5;
|
||||
const HOURS_BEFORE = 1;
|
||||
const HOURS_AFTER = 3;
|
||||
const ROW_H = 80;
|
||||
```
|
||||
|
||||
> `config.json` is listed in `.gitignore` — your private URLs will never be pushed to GitHub.
|
||||
Meaning:
|
||||
|
||||
---
|
||||
- PX_PER_MIN → zoom level of the timeline\
|
||||
- HOURS_BEFORE → past hours visible\
|
||||
- HOURS_AFTER → future hours visible\
|
||||
- ROW_H → height of channel rows
|
||||
|
||||
## ⚙️ Advanced configuration
|
||||
------------------------------------------------------------------------
|
||||
|
||||
The following constants can be tweaked directly in `index.php`:
|
||||
# 📁 Project structure
|
||||
|
||||
```js
|
||||
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)
|
||||
```
|
||||
gridtv/
|
||||
│
|
||||
├── index.php
|
||||
├── setup.php
|
||||
├── config.example.json
|
||||
├── .gitignore
|
||||
└── README.md
|
||||
|
||||
---
|
||||
`config.json` is ignored by git to prevent leaking private URLs.
|
||||
|
||||
## 🧩 EPG Compatibility
|
||||
------------------------------------------------------------------------
|
||||
|
||||
GridTV parses the standard **XMLTV format**. Tested with:
|
||||
# 🤝 Contributing
|
||||
|
||||
- ✅ [Tunarr](https://github.com/chrisbenincasa/tunarr)
|
||||
- ✅ [xTeVe](https://github.com/xteve-project/xTeVe)
|
||||
- ✅ [Jellyfin](https://jellyfin.org/) (via LiveTV plugin)
|
||||
- ✅ Any XMLTV-compliant file
|
||||
Pull requests are welcome.
|
||||
|
||||
---
|
||||
Feel free to open issues for:
|
||||
|
||||
## 🤝 Contributing
|
||||
- bug reports
|
||||
- feature requests
|
||||
- improvements
|
||||
|
||||
PRs are welcome! Got an idea, a fix, or a feature request — open an issue or send a PR directly.
|
||||
------------------------------------------------------------------------
|
||||
|
||||
---
|
||||
# 📄 License
|
||||
|
||||
## 📄 License
|
||||
|
||||
GNU Affero (AGPLv3)
|
||||
GNU Affero General Public License v3 (AGPLv3)
|
||||
|
||||
Reference in New Issue
Block a user