Update README.md

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.
+> **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!**