my-private-iptv-m3u/README.md

# 📺 IPTV Playlist Manager

[![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)](#)

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