This commit is contained in:
parent
ba38b275ee
commit
aae167acf0
1 changed files with 171 additions and 31 deletions
202
README.md
202
README.md
|
@ -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
|
[](../../actions)
|
||||||
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.
|
|
||||||
|
|
||||||
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!**
|
Loading…
Add table
Add a link
Reference in a new issue