From aae167acf0f5ceb669d46d2b1415f35c53cde910 Mon Sep 17 00:00:00 2001 From: stoney420 Date: Fri, 27 Jun 2025 17:40:36 +0200 Subject: [PATCH] Update README.md --- README.md | 202 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 171 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 79e6cc8..629ff77 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,173 @@ -How it Works / How to Use -This system automates the creation of M3U playlists for IPTV directly within your Forgejo repository. You manage your channels in a simple text file, and Forgejo handles the rest. +# 📺 IPTV Playlist Manager -How it Works -channels.txt: This is your main list of channels. You define each channel's name, URL, group, and optional logo/EPG ID here. -bulk_import.m3u (Optional): If you upload an M3U file named bulk_import.m3u to your repository, the system will automatically process it, add those channels to channels.txt, and then delete bulk_import.m3u (needs fixed). -generate_playlist.py: This Python script reads channels.txt after any imports, converts the data into the standard M3U playlist format, and creates playlist.m3u. -Forgejo Actions: An automated workflow in your Forgejo repository detects changes to channels.txt or the upload of bulk_import.m3u. It then runs generate_playlist.py and commits the updated channels.txt, playlist.m3u, and a log file back to your repository. This keeps your playlist always up-to-date and publicly accessible. -playlist.m3u: This is your final, generated M3U playlist file, which you can use in any IPTV player. -How to Use -You primarily interact with this system by editing files directly in your Forgejo repository. +[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](../../actions) +[![Playlist Status](https://img.shields.io/badge/playlist-active-blue)](#) +[![Last Updated](https://img.shields.io/badge/updated-auto-green)](#) -1. Editing Channels Manually (channels.txt) -Go to your repository on Forgejo. -Click on channels.txt. -Click the "Edit this file" (pencil) icon. -Add, modify, or remove channel entries. -Format: Each channel is a block of Key = Value pairs (e.g., Stream name = My Channel, Stream URL = http://example.com/stream). -Separation: Ensure at least two blank lines separate each channel block. -Commit your changes with a descriptive message. -This action will automatically trigger the M3U generation. -2. Importing Channels (Using bulk_import.m3u) -Get an M3U file you want to import. -Go to your repository on Forgejo. -Click "Add file" and then "Upload file". -Upload your M3U file, but rename it to bulk_import.m3u during the upload process. -Commit your changes. -The system will process this file, add its channels to channels.txt, delete bulk_import.m3u, and regenerate playlist.m3u. -3. Accessing Your Playlist -After any changes and the Forgejo Action completes (check the "Actions" tab in your repository), your playlist.m3u will be updated. -You can access your playlist using a direct URL, typically: https://[your-forgejo-instance]/[your-username]/[your-repo-name]/raw/branch/main/playlist.m3u (Replace the bracketed parts with your actual Forgejo details) -Use this URL in your preferred IPTV player. -Tip: Always check the "Actions" tab in your Forgejo repository for logs if you encounter any issues. \ No newline at end of file +> **Automated IPTV playlist management system** that processes M3U files, manages channel databases, and generates clean playlists via Forgejo Actions. + +## 🚀 Quick Start + +### 📥 **Download Your Playlist** +- **[📺 Download playlist.m3u](./playlist.m3u)** - Ready to use in any IPTV player +- **[📋 View Channel List](./channels.txt)** - See all available channels +- **[📊 Check Logs](./logs/)** - View processing history + +### ⚡ **Add Channels (3 Easy Ways)** + +#### Method 1: Upload M3U File (Bulk Import) +1. Get your M3U file from your IPTV provider +2. Upload it to this repository as `bulk_import.m3u` +3. Commit the file - automatic processing begins! +4. Check logs for import results + +#### Method 2: Edit Channels Manually +1. Click **[channels.txt](./channels.txt)** and edit it +2. Add channels using this format: +``` +Group = Sports +Stream name = ESPN HD +Logo = https://example.com/espn-logo.png +EPG id = espn.us +Stream URL = http://your-stream-url-here + +Group = News +Stream name = CNN International +Logo = https://example.com/cnn-logo.png +EPG id = cnn.us +Stream URL = http://your-stream-url-here +``` +3. Commit your changes + +#### Method 3: Use the Template +1. Check **[templates/channel_template.txt](./templates/channel_template.txt)** for the exact format +2. Copy the template and fill in your channel details +3. Add to channels.txt + +## 📁 Repository Structure + +``` +📦 Your Repository +├── 📺 playlist.m3u # 🎯 Generated playlist (your main file!) +├── 📝 channels.txt # 🎯 Channel database (edit this!) +├── 📥 bulk_import.m3u # 🎯 Drop M3U files here for import +├── 📖 README.md # This guide +├── 📁 scripts/ # Processing scripts +├── 📁 config/ # Configuration files +├── 📁 logs/ # Processing logs & history +├── 📁 templates/ # Channel entry templates +└── 📁 .forgejo/workflows/ # Automation workflows +``` + +## 🎯 How It Works + +The system automatically: +1. **🔍 Duplicate Detection** - Removes duplicate channels intelligently +2. **📊 Data Validation** - Ensures all channels have required info +3. **🏷️ Smart Grouping** - Organizes channels by category +4. **📝 Logging** - Tracks all changes and imports +5. **✨ Clean Output** - Generates perfectly formatted M3U files + +## 🛠️ Advanced Configuration + +### Group Overrides +Edit `config/group_overrides.json` to customize channel grouping: +```json +{ + "ESPN": "Sports", + "Fox Sports": "Sports", + "CNN": "News", + "BBC": "News" +} +``` + +### Settings +Customize behavior in `config/settings.json`: +```json +{ + "remove_duplicates": true, + "sort_channels": true, + "validate_urls": false, + "backup_before_import": true +} +``` + +## 📊 Monitoring & Logs + +- **📋 Processing Logs**: [logs/playlist_update.log](./logs/playlist_update.log) +- **📥 Import History**: [logs/import_history.log](./logs/import_history.log) +- **❌ Error Tracking**: [logs/error.log](./logs/error.log) + +## 🎮 Using Your Playlist + +### Popular IPTV Players: +- **VLC Media Player**: File → Open Network Stream → Paste URL +- **Kodi**: Add-ons → PVR → Simple Client → M3U URL +- **Perfect Player**: Settings → Playlist → Add playlist → M3U URL +- **IPTV Smarters**: Add playlist → M3U URL + +### Your Playlist URL: +``` +https://forgejo.plainrock127.xyz/[your-username]/[repo-name]/raw/branch/main/playlist.m3u +``` + +## 🚨 Troubleshooting + +### Common Issues: + +**❓ Import file not processing?** +- ✅ Make sure file is named exactly `bulk_import.m3u` +- ✅ Check file format is valid M3U +- ✅ Look at logs for error details + +**❓ Channels missing after import?** +- ✅ Check logs for duplicate removal notices +- ✅ Verify channel format in original M3U +- ✅ Look for validation errors in logs + +**❓ Playlist not updating?** +- ✅ Check Actions tab for workflow status +- ✅ Ensure you committed your changes +- ✅ Review error logs for issues + +**❓ Need help?** +- 📋 Check the logs in the `logs/` folder +- 📖 Review templates in `templates/` folder +- 🐛 Create an issue if problems persist + +## 🎯 Pro Tips + +1. **📱 Mobile Friendly**: Repository works great on mobile browsers +2. **🔄 Auto-Sync**: Playlist updates automatically when you make changes +3. **💾 Backup**: Your channel data is version controlled - never lose channels! +4. **🏷️ Organization**: Use consistent group names for better organization +5. **📊 Monitoring**: Check logs regularly to catch issues early + +## 🔧 For Developers + +### Running Locally: +```bash +python scripts/generate_playlist.py +``` + +### File Structure: +- `scripts/generate_playlist.py` - Main processing engine +- `config/` - Configuration files +- `templates/` - User guidance templates +- `.forgejo/workflows/` - CI/CD automation + +### Contributing: +1. Fork the repository +2. Create feature branch +3. Test your changes +4. Submit pull request + +--- + +## 📈 Stats +- **Channels**: Auto-counted from channels.txt +- **Groups**: Auto-detected from channel data +- **Last Updated**: Auto-timestamp from last workflow run +- **Build Status**: Live from Forgejo Actions + +**🎉 Enjoy your automated IPTV playlist management!** \ No newline at end of file