Skip to content

Update README.md #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
thehack904 merged 1 commit into from
Oct 7, 2025
Merged

Update README.md #4

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
194 changes: 127 additions & 67 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,100 +3,160 @@
![Version](https://img.shields.io/badge/version-v3.0.1-blue)

RetroIPTVGuide is an IPTV Web Interface inspired by 90s/2000s cable TV guides.
It is designed to work with [ErsatzTV](https://ersatztv.org/) [(GitRepo)](https://github.com/ErsatzTV/ErsatzTV/tree/main) but should support any `.m3u` and `.xml` IPTV source.
It is designed to work with [ErsatzTV](https://ersatztv.org/) [(GitRepo)](https://github.com/ErsatzTV/ErsatzTV/tree/main) but supports any `.m3u`, `.m3u8`, and `.xml` IPTV source.

โ��๏ธ� **Note:** This is still a BETA release. It is not recommended for direct Internet/public-facing deployments.
⚠️ **Note:** This is still a BETA release. It is not recommended for direct Internet/public-facing deployments.

- [Installation / Uninstall Guide](INSTALL.md)
- [Changelog](CHANGELOG.md)
- [Roadmap](ROADMAP.md)
- [License](LICENSE)

## โ�จ Features (v3.0.0)
- ๐�”‘ **User Authentication**
- Login/logout system with hashed passwords.
- Admin and regular user accounts.
- Password change functionality.
- Admin-only user management (add/delete users).
- ๐�“ก **Tuner Management**
- Multiple tuner support stored in `tuners.db`.
- Switch between active tuners via the web UI.
- Update `.m3u` and `.xml` tuner URLs (persisted in DB).
- ๐�“บ **Guide & Playback**
- Program guide rendered from XMLTV with automatic fallback for missing data.
- Channels without guide entries display “No Guide Data Available”.
- Video playback using HTML5 + HLS.js.
- Playback events logged with user + channel + timestamp.
- ๐�“‘ **Logging**
- Activity log (`activity.log`) records authentication events, tuner changes, playback, and admin actions.
- Admin-only **Logs page** with real-time log viewing.
- Log file size display with color coding.
- Admin-only โ€�Clear Logsโ€� button to truncate logs.
- ๐��จ **UI Enhancements**
- Unified header across all pages (Guide, Logs, Add User, Delete User, Change Password, Change Tuner, Login).
- Active tuner display + live clock in header.
- **Themes submenu** with multiple options:
- Light
- Dark
- AOL/CompuServe
- TV Guide Magazine
- Theme persistence stored in browser localStorage, applied instantly across all pages.
- **About Page under Settings menu** โ€” shows version, Python, OS, uptime, paths.
- โ��๏ธ� **System**
- Automatic initialization of `users.db` and `tuners.db` on first run.
- SQLite databases use WAL mode for better concurrency.
- Preloads tuner/channel/guide data from DB on startup.
- **Cross-platform installers (Linux/Windows) (v3.0.0)**.
- **Uninstaller scripts (Linux/Windows) (v3.0.0)**.
- **Automated version bump tool (`bump_version.py`) (v3.0.0)**.
---

## ✨ Features (v3.0.1)

### 🔑 User Authentication
- Login/logout system with hashed passwords.
- Admin and regular user accounts.
- Password change functionality.
- Admin-only user management (add/delete users).

### 📡 Tuner Management
- Multiple tuner support stored in `tuners.db`.
- Switch between active tuners via the web UI.
- Update `.m3u`, `.m3u8`, and `.xml` tuner URLs (persisted in DB).
- Active tuner refreshes instantly when changed — **no logout required**.
- Detection for invalid XML inputs (e.g., `.m3u` pasted into `.xml` field).

### 📺 Guide & Playback
- Program guide rendered from XMLTV data.
- **Automatic fallback:** Channels missing XMLTV data display *“No Guide Data Available”*.
- Channel list parsed from M3U playlist.
- Video playback using HTML5 + HLS.js.
- Playback events logged with user + channel + timestamp.
- Scalable time grid and responsive EPG layout.

### 📑 Logging
- `activity.log` records authentication events, tuner changes, playback, and admin actions.
- Admin-only **Logs page** with real-time log viewing.
- Log file size display with color coding.
- Admin-only “Clear Logs” button to truncate logs.

### 🎨 UI Enhancements
- Unified header across all pages: Guide, Logs, Add User, Delete User, Change Password, Change Tuner, and Login.
- Active tuner display + live clock in header.
- “No Guide Data Available” placeholders styled in gray/italic with dashed border.
- **Themes submenu** with multiple options:
- Light
- Dark
- AOL/CompuServe
- TV Guide Magazine
- Theme persistence stored in browser localStorage, applied instantly across all pages.
- **About Page under Settings** — shows version, Python, OS, uptime, and paths.
- **Login Page Redesign (v3.0.1)**:
- Floating centered login box with 3D shadow.
- RetroIPTVGuide logo positioned upper-right.

### ⚙️ System
- Automatic initialization of `users.db` and `tuners.db` on first run.
- SQLite databases use WAL mode for better concurrency.
- Preloads tuner/channel/guide data from DB on startup.
- **Cross-platform installers (Linux/Windows)**.
- **Uninstaller scripts (Linux/Windows)**.
- **Automated version bump tool (`bump_version.py`)**.

---

## ๐��� Browser Compatibility
This project is designed to work with **all major browsers**.
It has been tested on:
## 🧩 Version History

| Version | Date | Key Features |
|----------|------|---------------|
| **v3.0.1** | 2025-10-07 | EPG fallback system, tuner refresh fix, login redesign |
| **v3.0.0** | 2025-10-03 | Windows installer/uninstaller, cross-platform setup, unified UI |
| **v2.3.x** | 2025-09 | Unified theming, About page, installer logging, tuner rename/delete |
| **v2.0.0** | 2025-09 | Persistent tuners.db, user logs, unified headers |
| **v1.x.x** | 2025-08 | Initial IPTV Flask prototype |

---

## 🌐 Browser Compatibility
RetroIPTVGuide is compatible with all modern browsers:

- Firefox
- Chrome
- Safari
- Edge

## ๐�’ป Tested Devices & OS
The web interface has been tested on:
- **Ubuntu (desktop/server)**
---

## 💻 Tested Devices & Operating Systems
- **Ubuntu 24.04 (desktop/server)**
- **TrueNAS SCALE (Docker/Podman)**
- **Windows 10 / 11**
- **macOS Monterey / Ventura**
- **iOS (mobile/tablet)**
- **Android (Samsung Mobile Phone)**
- **macOS**
- **Windows 10/11**
- **MacOS**
- **Windows**
- **Android (Samsung / Pixel)**

---

## 🛠️ Installation Platforms
- Debian-based Linux (Ubuntu, Pop!\_OS, Mint)
- Windows 10/11 (via PowerShell + NSSM)
- MacOS (manual install or future installer support)

## ๐���๏ธ� Installation Platform
- **Debian Based Linux (desktop/server)**
- **Windows 10/11**
---

## ๐�“บ Screenshots
## 📸 Screenshots

## ๐�“บ Guide Page
### 📺 Guide Page
![Guide Screenshot](docs/screenshots/guide.png)

## ๐�“บ Video Pop Out
![Video Pop Out](docs/screenshots/guide_with_video_breakout.png)
### 📺 Video Pop Out
![Guide Pop Out](docs/screenshots/guide_with_video_breakout.png)

## ๐�“บ Video Pop Out on Desktop
### 💻 Desktop Pop Out
![Desktop Pop Out](docs/screenshots/video_breakout_desktop.png)

## ๐�“บ TV Guide Magazine Theme
### 📰 TV Guide Magazine Theme
![TV Guide Theme](docs/screenshots/TV_Guide_Theme.png)

## ๐�“บ AOL / CompuServe Theme
![AOL / CompuServe Theme](docs/screenshots/AOL_Compuserve_Theme.png)
### 💾 AOL / CompuServe Theme
![AOL Theme](docs/screenshots/AOL_Compuserve_Theme.png)

---

## ๐�ค� Contributing
Contributions are welcome! Hereโ€�s how you can help:
1. **Report Issues**: Found a bug or want to suggest a feature? Open an [issue](../../issues).
2. **Submit Pull Requests**: Fork the repo, make changes, and submit a PR. Please ensure code is tested before submitting.
3. **Improve Documentation**: Help refine the installation guide, add screenshots, or improve explanations in the README.
## 🤝 Contributing

Contributions are welcome! Here’s how you can help:

1. **Report Issues** – Found a bug or want to suggest a feature? Open an [issue](../../issues).
2. **Submit Pull Requests** – Fork, modify, test, and submit PRs for new features or fixes.
3. **Improve Documentation** – Add screenshots, examples, or clearer explanations.

All contributions will be reviewed before merging into the main branch.

---

## 🧭 Roadmap (Next Planned Features)
- [ ] `.m3u8` single-channel tuner support
- [ ] Log filtering and pagination
- [ ] Guide search/filter
- [ ] Favorites and notifications
- [ ] Responsive mobile layout
- [ ] Auto-refresh EPG schedule

See [ROADMAP.md](ROADMAP.md) for full details.

---

## 🧰 Maintainer Notes
- **Repo:** [RetroIPTVGuide](https://github.com/thehack904/RetroIPTVGuide)
- **Maintainer:** J.H.
- **License:** [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0)](https://creativecommons.org/licenses/by-nc-sa/4.0/)
- **Version:** v3.0.1
- **Release Date:** 2025-10-07

---

All contributions will be reviewed by the project maintainer before merging.
© 2025 RetroIPTVGuide Project — *Licensed under CC BY-NC-SA 4.0. Inspired by the golden era of cable TV.*