📺 IPTV Playlist Manager

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 - Ready to use in any IPTV player
• 📋 View Channel List - See all available channels
• 📊 Check 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 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 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:

{
  "ESPN": "Sports",
  "Fox Sports": "Sports", 
  "CNN": "News",
  "BBC": "News"
}

Settings

Customize behavior in config/settings.json:

{
  "remove_duplicates": true,
  "sort_channels": true,
  "validate_urls": false,
  "backup_before_import": true
}

📊 Monitoring & Logs

• 📋 Processing Logs: logs/playlist_update.log
• 📥 Import History: logs/import_history.log
• ❌ Error Tracking: 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:

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!