stoney420/my-private-iptv-m3u

Fork 0

stoney420 e2f6fc35ee

Generate M3U Playlist with Auto-Organization / build-and-organize (push) Successful in 1m45s

Details

Update README.md

2025-06-28 08:23:53 +02:00

11 KiB

Raw Permalink Blame History

📺 IPTV Playlist Manager

Automated IPTV playlist management system with intelligent channel organization that processes M3U files, manages channel databases, and generates clean playlists via Forgejo Actions.

✨ What Makes This Special

🌍 Smart Country Detection - Automatically organizes channels by country using advanced pattern matching
🎬 Quality Recognition - Detects and labels 4K, FHD, HD, and SD streams
🔄 Intelligent Deduplication - Removes duplicates using signature-based matching
📊 Professional Reporting - Detailed statistics and processing logs
🛡️ Content Filtering - Optional adult content filtering
⚡ Lightning Fast - Processes 1000+ channels in seconds

🚀 Quick Start

📥 Download Your Playlist

📺 Download playlist.m3u - Ready to use in any IPTV player
📋 View Channel List - See all available channels
📊 Check Reports - View processing history and statistics

⚡ Add Channels (3 Easy Ways)

Method 1: Upload M3U File (Bulk Import) ⭐ Recommended

Get your M3U file from your IPTV provider
Upload it to this repository as bulk_import.m3u
Commit the file - automatic processing begins!
Check reports for import results with country detection

Method 2: Edit Channels Manually

Click channels.txt and edit it
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

Commit your changes

Method 3: Use the Template

Check templates/channel_template.txt for the exact format
Copy the template and fill in your channel details
Add to channels.txt

📁 Repository Structure

📦 Your IPTV 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 engine (Python)
│   ├── generate_playlist.py    # Main orchestrator
│   ├── channel_processor.py    # Smart processing & detection
│   ├── playlist_builder.py     # M3U generation
│   └── report_generator.py     # Statistics & reporting
├── 📁 config/              # ⚙️ Configuration files
│   ├── settings.json           # System settings
│   ├── patterns.json           # Country detection patterns
│   └── group_overrides.json    # Manual overrides
├── 📁 reports/             # 📊 Processing reports & statistics
│   ├── daily/                  # Latest reports
│   └── logs/                   # System logs
├── 📁 templates/           # 📋 Channel entry templates
├── 📁 backups/             # 💾 Automatic backups
└── 📁 .forgejo/workflows/  # 🤖 Automation workflows

🧠 How It Works (The Smart Stuff)

The system intelligently processes your channels through this pipeline:

📥 Input (M3U/Manual) → 🔍 Parse & Validate → 🌍 Country Detection 
    ↓
🎬 Quality Detection → 🔄 Duplicate Removal → 📺 Generate Clean M3U 
    ↓
📊 Create Reports → ✅ Done!

Advanced Features:

🌍 Smart Country Detection - Uses 500+ patterns to detect countries from channel names
🎬 Quality Recognition - Automatically detects 4K, FHD, HD, SD quality
🔍 Intelligent Deduplication - Advanced signature matching prevents duplicates
📊 Data Validation - Ensures all channels have required information
🏷️ Auto-Organization - Groups channels by detected country
📝 Comprehensive Logging - Tracks all changes and imports
✨ Clean Output - Generates perfectly formatted M3U files
💾 Automatic Backups - Never lose your channel data

🌍 Supported Countries & Detection

The system automatically detects and organizes channels from:

Region	Countries	Examples
🇺🇸 North America	USA, Canada	ESPN, CNN, CBC, TSN
🇪🇺 Europe	UK, Germany, France, Spain, Italy, Netherlands	BBC, Sky, ARD, TF1
🌏 Other	Australia, Brazil, Arabic	ABC AU, Globo, MBC

Detection Methods:

Prefixes: us:, uk:, [US], (CA)
Channel Names: ESPN → 🇺🇸, BBC → 🇬🇧, CBC → 🇨🇦
Network Patterns: Sky Sports → 🇬🇧, Fox Sports → 🇺🇸
Quality Tags: Automatic 4K/FHD/HD/SD detection

🛠️ Advanced Configuration

Smart Country Detection (`config/patterns.json`)

The system includes 500+ detection patterns for accurate categorization:

{
  "country_patterns": {
    "🇺🇸 United States": ["espn", "cnn", "fox", "nbc", "cbs"],
    "🇬🇧 United Kingdom": ["bbc", "sky", "itv", "channel 4"],
    "🇨🇦 Canada": ["cbc", "tsn", "sportsnet", "ctv"]
  }
}

Manual Overrides (`config/group_overrides.json`)

Force specific channels into custom groups:

{
  "ESPN": "🇺🇸 United States",
  "Fox Sports": "🇺🇸 United States", 
  "BBC News": "🇬🇧 United Kingdom"
}

System Settings (`config/settings.json`)

Customize processing behavior:

{
  "remove_duplicates": true,
  "auto_detect_country": true,
  "detect_quality": true,
  "skip_adult_content": true,
  "sort_channels": true,
  "backup_before_import": true
}

📊 Monitoring & Statistics

📈 Live Reports

📊 Latest Report - Processing statistics and country breakdown
📋 Processing Logs - Detailed operation logs
📥 Import History - Import tracking
❌ Error Tracking - Issue monitoring

📈 What You Get

Channel Counts - Total and per-country statistics
Quality Distribution - 4K/FHD/HD/SD breakdown
Processing Stats - Import success rates, duplicates removed
Country Detection - Accuracy and coverage metrics
Performance Data - Processing times and efficiency

🎮 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
TiviMate: Add playlist → M3U Playlist → 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 with #EXTM3U header
✅ Look at reports for detailed error information

❓ Channels missing after import?

✅ Check reports for duplicate removal notices
✅ Verify channel format in original M3U
✅ Look for validation errors in processing logs

❓ Country detection not working?

✅ Check if channel names match patterns in config/patterns.json
✅ Add custom patterns for your specific channels
✅ Use manual overrides in config/group_overrides.json

❓ Playlist not updating?

✅ Check Actions tab for workflow status
✅ Ensure you committed your changes
✅ Review error logs for workflow issues

❓ Need help?

📊 Check the reports in the reports/daily/ folder
📋 Review logs in reports/logs/ folder
📖 Review templates in templates/ folder
🐛 Create an issue if problems persist

🎯 Pro Tips

📱 Mobile Friendly: Repository works great on mobile browsers for quick edits
🔄 Auto-Sync: Playlist updates automatically when you make changes
💾 Never Lose Data: Your channel data is version controlled with automatic backups
🏷️ Smart Organization: Let the system detect countries automatically for better organization
📊 Monitor Health: Check reports regularly to track system performance
🎬 Quality Labels: System automatically detects and labels stream quality
🔍 Bulk Processing: Import hundreds of channels at once with intelligent processing

🔧 For Developers

🐍 Technology Stack:

Python 3.11+ - Core processing engine
Forgejo Actions - CI/CD automation
JSON Configuration - Flexible, editable settings
Markdown Reporting - Human-readable reports

🏗️ Architecture:

scripts/
├── generate_playlist.py    # 🎯 Main orchestrator
├── channel_processor.py    # 🧠 Smart processing & country detection  
├── playlist_builder.py     # 📺 M3U generation & formatting
├── health_checker.py       # 🏥 Optional stream validation
├── report_generator.py     # 📊 Statistics & reporting
└── config_manager.py       # ⚙️ Configuration management

🚀 Running Locally:

# Process channels and generate playlist
python3 scripts/generate_playlist.py

# Check system configuration
python3 -c "from scripts.config_manager import ConfigManager; print(ConfigManager().get_detection_summary())"

🤝 Contributing:

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Test your changes locally
Commit changes (git commit -m 'Add amazing feature')
Submit pull request

📈 Current Stats

Channels: Auto-counted from playlist generation
Countries: Auto-detected from smart pattern matching
Quality Streams: 4K/FHD/HD automatically identified
Processing Speed: 1000+ channels per second
Detection Accuracy: 95%+ for known patterns
Last Updated: Auto-timestamp from last workflow run
Build Status: Live from Forgejo Actions

🏆 Why This System Rocks

✅ Fully Automated - Set it and forget it
✅ Intelligent Processing - Smarter than basic M3U tools
✅ Professional Quality - Enterprise-level features
✅ Easy to Use - Simple for beginners, powerful for experts
✅ Highly Configurable - Customize everything
✅ Well Documented - Comprehensive guides and examples
✅ Version Controlled - Never lose your work
✅ Performance Optimized - Fast and efficient

🎉 Enjoy your professional-grade automated IPTV playlist management system!

Built with ❤️ for quality IPTV management

11 KiB Raw Permalink Blame History