A high-performance streaming service aggregator that combines multiple free streaming platforms into a single M3U playlist and EPG. Perfect for use with Channels DVR, Plex, or any IPTV client.

This application aggregates live TV channels from multiple streaming services into a unified playlist, making it easy to access thousands of free channels through your favorite IPTV client.

• 9 Streaming Providers: Xumo, Tubi, Plex, Pluto TV, Samsung TV Plus, DistroTV, LG Channels, and GitHub-based IPTV repositories
• Enhanced EPG System: Automatic fallback to reliable external EPG sources when native implementations fail
• High Performance: Concurrent channel fetching with ~15-20 second startup time
• Smart Caching: 2-hour cache with background refresh to keep channels ready
• Duplicate Removal: Automatically removes duplicate channels across providers
• Flexible Filtering: Regex-based channel and group filtering
• Country Filtering: Filter Git-based and LG providers by country codes or names
• Multiple Formats: M3U playlist, XMLTV EPG, and JSON channel data
• Debug Mode: Comprehensive logging for troubleshooting
• Health Monitoring: Built-in health checks and status endpoints
• Docker Ready: Fully containerized with Docker Compose

*Channel counts are approximate and vary by region and filtering

1. Create docker-compose.yml:

version: '3.8'

services:
  unified-streaming:
    image: ghcr.io/kpirnie/kptv-fast:latest
    ports:
      - "7777:7777"
    environment:
      - DEBUG=false
      - CACHE_DURATION=7200
      - WARM_CACHE_ON_STARTUP=true
      - WARM_EPG_ON_STARTUP=true
      - ENABLED_PROVIDERS=all
      - GIT_COUNTRY=us,ca,uk  # Filter Git providers to these countries
      - LG_COUNTRY=us,ca,uk   # Filter LG provider to these countries
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7777/status"]
      interval: 30s
      timeout: 10s
      retries: 3

2. Start the service:

docker-compose up -d

3. Access your content:
   • Status page: http://localhost:7777/status
   • M3U playlist: http://localhost:7777/playlist
   • EPG: http://localhost:7777/epg
   • EPG GZ: http://localhost:7777/epggz

git clone https://github.com/kpirnie/kptv-fast
cd kptv-fast
docker-compose build
docker-compose up -d

Both GIT_COUNTRY and LG_COUNTRY environment variables support flexible country filtering:

• 2-letter codes: us,ca,uk,de,fr
• 3-letter codes: usa,can,gbr,deu,fra
• Full names: united states,canada,united kingdom,germany,france
• Mixed formats: us,canada,united kingdom,de

# North America only
- GIT_COUNTRY=us,ca,mx
- LG_COUNTRY=us,ca,mx

# English-speaking countries
- GIT_COUNTRY=us,uk,ca,au
- LG_COUNTRY=us,uk,ca,au

# Major European countries
- GIT_COUNTRY=uk,de,fr,it,es,nl
- LG_COUNTRY=uk,de,fr,it,es,nl

# All countries (no filter)
- GIT_COUNTRY=
- LG_COUNTRY=

# Single country
- GIT_COUNTRY=united states
- LG_COUNTRY=us

environment:
  - PORT=7777
  - DEBUG=false
  - CACHE_DURATION=7200

environment:
  - MAX_WORKERS=8
  - PROVIDER_TIMEOUT=45
  - WARM_CACHE_ON_STARTUP=true
  - WARM_EPG_ON_STARTUP=true
  - STARTUP_CACHE_DELAY=5

environment:
  - ENABLED_PROVIDERS=pluto,plex,samsung,distrotv,lg
  - GIT_COUNTRY=us,ca,uk
  - LG_COUNTRY=us,ca,uk

environment:
  - CHANNEL_NAME_INCLUDE="news|cnn|fox|msnbc"
  - CACHE_DURATION=3600

The application features an advanced EPG system with automatic fallback support:

• Pluto TV: Native API + i.mjh.nz fallback
• Plex: Native API + i.mjh.nz fallback
• Samsung TV Plus: Native API + i.mjh.nz fallback
• Tubi: Native scraping + BuddyChewChew repository fallback
• Xumo: BuddyChewChew repository fallback
• DistroTV: EPGShare01 + vraomoturi repository fallback
• LG Channels: EPGShare01 fallback
• Git Providers: No EPG (playlist only)

• i.mjh.nz: Comprehensive EPG for major providers
• EPGShare01: Multi-provider EPG aggregation
• BuddyChewChew: Specialized repositories for Tubi/Xumo
• vraomoturi: DistroTV-specific EPG data

1. Native First: Attempts to use each provider's native EPG API
2. Automatic Fallback: If native fails, automatically uses external sources
3. Intelligent Mapping: Maps external channel IDs to internal format
4. Caching: Caches external EPG data to reduce requests
5. Error Recovery: Graceful degradation when all sources fail

• GET /playlist - M3U8 playlist with all channels
• GET /epg - XMLTV EPG data
• GET /epggz - Compressed XMLTV EPG data
• GET /channels - JSON formatted channel list

• GET /status - HTML status page with statistics
• GET /debug - JSON debug information
• GET /refresh - Force cache refresh: set a cronjob to curl/wget this endpoint to setup a regular refresh
• GET /clear_cache - Clear all cached data

The status page (/status) provides:

• Total channel count and EPG coverage
• Per-provider statistics with EPG status
• Cache status and performance metrics
• Enhanced EPG system status
• Git and LG country filter status
• Quick links to all endpoints

• Startup Time: 15-20 seconds with cache warming
• First Request: Instant (with cache warming enabled)
• Subsequent Requests: <100ms (cached)
• Memory Usage: ~200-300MB
• CPU Usage: Low (mostly I/O bound)

• External EPG Sources: ~2-5 seconds per provider (cached for 1 hour)
• Native EPG APIs: ~3-10 seconds per provider
• Fallback Activation: Automatic, no performance penalty
• Channel ID Mapping: Minimal performance impact

1. Enable Cache Warming: Set WARM_CACHE_ON_STARTUP=true and WARM_EPG_ON_STARTUP=true
2. Tune Worker Count: Adjust MAX_WORKERS based on your server
3. Regional Optimization: Use closer regions for better performance
4. Filter Channels: Use regex filters to reduce channel count
5. Country Filtering: Use GIT_COUNTRY and LG_COUNTRY to limit scope
6. GitHub Token: Set GITHUB_TOKEN for higher API rate limits
7. Monitor Debug Logs: Use DEBUG=true to identify slow providers

# Check provider status
curl http://localhost:7777/debug

# Check logs
docker-compose logs -f kptv-fast

# Force refresh
curl http://localhost:7777/refresh

# Check EPG status in debug endpoint
curl http://localhost:7777/debug | jq '.epg_stats'

# Check enhanced EPG system status
curl http://localhost:7777/status
# Look for "Enhanced EPG system: ✅ Active"

# Force EPG refresh
curl http://localhost:7777/clear_cache
curl http://localhost:7777/refresh

# Enable debug logging
docker-compose down
# Set DEBUG=true in docker-compose.yml
docker-compose up -d

# Check which provider is slow
docker-compose logs -f kptv-fast

DistroTV: Scraping issues

# DistroTV uses web scraping, may be affected by site changes
# Check logs for scraping errors
environment:
  - DEBUG=true  # Enable detailed scraping logs

LG Channels: Country filtering

environment:
  - LG_COUNTRY=us,ca,uk  # Ensure countries exist
  - DEBUG=true           # Enable debug logs

Git Providers: GitHub rate limits

environment:
  - GITHUB_TOKEN=your_github_personal_access_token

Enable comprehensive logging:

environment:
  - DEBUG=true

This provides:

• Function-level logging
• Performance timings
• Error stack traces
• Provider-specific debug info
• EPG fallback system details
• Web scraping debug information

The application includes built-in health monitoring:

# Check health
curl http://localhost:7777/status

# Docker health check
docker-compose ps

• Flask Web Server: HTTP API and status endpoints
• Provider System: Modular provider architecture with 9 providers
• Enhanced EPG System: Native + fallback EPG with external source integration
• Caching Layer: Redis-like in-memory caching with TTL
• Background Tasks: Cache warming and refresh threads for both channels and EPG
• Concurrent Processing: ThreadPoolExecutor for parallel fetching
• Web Scraping: BeautifulSoup + regex fallback for DistroTV
• External Integration: Multiple external M3U and EPG sources

Each provider implements:

• get_channels(): Fetch channel list
• get_epg_data(): Fetch EPG data with automatic fallback
• Built-in validation and normalization
• Error handling and logging
• Caching support

EPG system features:

• Native provider EPG APIs
• Automatic fallback to external sources
• Channel ID mapping between formats
• Compressed EPG file handling
• Multi-source EPG aggregation
• Error recovery and graceful degradation

1. Add source in Channels DVR
2. Use M3U URL: http://your-server:7777/playlist
3. Use EPG URL: http://your-server:7777/epg

1. Install the IPTV plugin
2. Configure with M3U URL
3. Set EPG source

vlc http://your-server:7777/playlist

1. Install PVR IPTV Simple Client
2. Set M3U path to your server URL
3. Configure EPG source

• INFO: General operations and status
• WARNING: Non-critical issues
• ERROR: Critical failures
• DEBUG: Detailed troubleshooting info

Production (DEBUG=false):
2025-08-22 13:00:00 - INFO - 🚀 1794 channels ready in 15.2s
2025-08-22 13:00:00 - INFO - 📺 Total EPG data collected for 1247 channels

Debug (DEBUG=true):
2025-08-22 13:00:00 - providers.distrotv - DEBUG - Scraping with BeautifulSoup
2025-08-22 13:00:00 - providers.lg - DEBUG - Fetching LG channels for us from https://www.apsattv.com/uslg.m3u

EPG System Examples:
2025-08-22 13:00:00 - INFO - Native EPG successful for pluto: 387 channels
2025-08-22 13:00:00 - INFO - Using fallback EPG for xumo: 79 channels  
2025-08-22 13:00:00 - INFO - External EPG mapping for plex: 156/200 our channels matched

• Run as non-root user (built into Docker image)
• Use reverse proxy for external access
• Enable health checks
• Monitor logs for unusual activity
• Keep Docker images updated
• Use GitHub tokens for API access

# Restrict to local network
ports:
  - "127.0.0.1:7777:7777"

# Or use reverse proxy
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.streaming.rule=Host(`streaming.local`)"

The application is designed to support metrics collection:

• Channel count per provider
• EPG coverage per provider
• Request response times
• Cache hit/miss ratios
• Provider success rates
• External EPG source reliability

For production deployments, consider:

• ELK Stack for log analysis
• Grafana for visualization
• Alert manager for notifications

# Clone repository
git clone https://github.com/kpirnie/kptv-fast
cd kptv-fast

# Install dependencies
pip install -r requirements.txt

# Run locally
DEBUG=true GIT_COUNTRY=us,ca LG_COUNTRY=us,ca python app.py

1. Create new provider class inheriting from BaseProvider
2. Implement get_channels() and get_epg_data() methods
3. Add EPG fallback support in utils/epg_fallback.py
4. Add to provider imports in app.py
5. Test with debug mode enabled

1. Fork the repository
2. Create feature branch
3. Add tests for new functionality
4. Submit pull request

MIT License - see LICENSE file for details.

• https://github.com/jgomez177 - Inspiration for Tubi, Plex, & Pluto implementations
• https://github.com/BuddyChewChew - Inspiration for the Xumo implementation and EPG sources
• https://github.com/matthuisman - Inspiration for the Samsung TVPlus implementation and i.mjh.nz EPG sources
• https://github.com/iptv-org/iptv - Community IPTV repository
• https://github.com/Free-TV/IPTV - Free TV IPTV repository
• https://epgshare01.online - EPG data aggregation
• https://www.apsattv.com - External M3U sources for DistroTV and LG
• All the streaming services for providing free content
• The open-source community for the excellent libraries used

• Issues: GitHub Issues

• Additional streaming providers
• Enhanced EPG source redundancy

⭐ If this project helps you, please give it a star on GitHub!