Update README.md
Some checks failed
📺 Generate M3U Playlist / build (push) Failing after 1m16s

This commit is contained in:
stoney420 2025-06-27 17:40:36 +02:00
parent ba38b275ee
commit aae167acf0

202
README.md
View file

@ -1,33 +1,173 @@
How it Works / How to Use # 📺 IPTV Playlist Manager
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.
How it Works [![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](../../actions)
channels.txt: This is your main list of channels. You define each channel's name, URL, group, and optional logo/EPG ID here. [![Playlist Status](https://img.shields.io/badge/playlist-active-blue)](#)
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). [![Last Updated](https://img.shields.io/badge/updated-auto-green)](#)
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.
1. Editing Channels Manually (channels.txt) > **Automated IPTV playlist management system** that processes M3U files, manages channel databases, and generates clean playlists via Forgejo Actions.
Go to your repository on Forgejo.
Click on channels.txt. ## 🚀 Quick Start
Click the "Edit this file" (pencil) icon.
Add, modify, or remove channel entries. ### 📥 **Download Your Playlist**
Format: Each channel is a block of Key = Value pairs (e.g., Stream name = My Channel, Stream URL = http://example.com/stream). - **[📺 Download playlist.m3u](./playlist.m3u)** - Ready to use in any IPTV player
Separation: Ensure at least two blank lines separate each channel block. - **[📋 View Channel List](./channels.txt)** - See all available channels
Commit your changes with a descriptive message. - **[📊 Check Logs](./logs/)** - View processing history
This action will automatically trigger the M3U generation.
2. Importing Channels (Using bulk_import.m3u) ### ⚡ **Add Channels (3 Easy Ways)**
Get an M3U file you want to import.
Go to your repository on Forgejo. #### Method 1: Upload M3U File (Bulk Import)
Click "Add file" and then "Upload file". 1. Get your M3U file from your IPTV provider
Upload your M3U file, but rename it to bulk_import.m3u during the upload process. 2. Upload it to this repository as `bulk_import.m3u`
Commit your changes. 3. Commit the file - automatic processing begins!
The system will process this file, add its channels to channels.txt, delete bulk_import.m3u, and regenerate playlist.m3u. 4. Check logs for import results
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. #### Method 2: Edit Channels Manually
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) 1. Click **[channels.txt](./channels.txt)** and edit it
Use this URL in your preferred IPTV player. 2. Add channels using this format:
Tip: Always check the "Actions" tab in your Forgejo repository for logs if you encounter any issues. ```
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!**