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