EPG Management

class EPGSource:
    name = CharField(unique=True)
    source_type = CharField()  # xmltv, schedules_direct, dummy
    url = URLField()  # For XMLTV sources
    api_key = CharField()  # For Schedules Direct
    is_active = BooleanField()
    refresh_interval = IntegerField()  # Hours between refreshes
    priority = PositiveIntegerField()  # Higher = higher priority
    status = CharField()  # idle, fetching, parsing, success, error
    custom_properties = JSONField()  # Dummy EPG config

class EPGData:
    tvg_id = CharField(db_index=True)
    name = CharField()
    icon_url = URLField()
    epg_source = ForeignKey(EPGSource)
    
    # Unique per source + tvg_id
    class Meta:
        unique_together = ('tvg_id', 'epg_source')

class ProgramData:
    epg = ForeignKey(EPGData)
    start_time = DateTimeField()
    end_time = DateTimeField()
    title = CharField()
    sub_title = TextField()
    description = TextField()
    custom_properties = JSONField()  # Categories, ratings, etc.

{
  "custom_properties": {
    "regex_patterns": [
      "^(Sports|ESPN)",  // Match channel names
      "Soccer.*Live"
    ],
    "default_duration": 3600,  // 1 hour blocks
    "timezone": "America/New_York",
    "program_template": {
      "title": "Live Programming",
      "description": "Scheduled programming"
    }
  }
}

# From channels/tasks.py
def match_epg_channels():
    """Match all unmatched channels to EPG data"""
    channels_without_epg = Channel.objects.filter(epg_data__isnull=True)
    
    for channel in channels_without_epg:
        # Try TVG ID match first
        if channel.tvg_id:
            epg_matches = EPGData.objects.filter(tvg_id=channel.tvg_id)
            
            # Use priority if multiple matches
            if epg_matches.exists():
                epg = epg_matches.order_by('-epg_source__priority').first()
                channel.epg_data = epg
                channel.save()

class EPGSource:
    priority = PositiveIntegerField(default=0)

Channel: HBO
├── EPG Source A (Priority: 100) ← Selected
├── EPG Source B (Priority: 50)
└── EPG Source C (Priority: 10)

class EPGSource:
    refresh_interval = IntegerField(default=0)  # Hours
    refresh_task = ForeignKey(PeriodicTask)  # Celery scheduled task

POST /api/epg/sources/{id}/refresh/

class EPGSource:
    STATUS_IDLE = 'idle'
    STATUS_FETCHING = 'fetching'
    STATUS_PARSING = 'parsing'
    STATUS_SUCCESS = 'success'
    STATUS_ERROR = 'error'
    
    status = CharField(choices=STATUS_CHOICES)
    last_message = TextField()  # Error details or success stats

def send_epg_update(source_id, action, progress, **kwargs):
    send_websocket_update('updates', 'update', {
        'type': 'epg_refresh',
        'source': source_id,
        'action': action,  # downloading, parsing, parsing_programs
        'progress': progress,  # 0-100
        **kwargs
    })

<?xml version="1.0" encoding="UTF-8"?>
<tv generator-info-name="Dispatcharr">
  <channel id="cnn">
    <display-name>CNN</display-name>
    <icon src="https://example.com/cnn.png" />
  </channel>
  <programme start="20260303120000 +0000" stop="20260303130000 +0000" channel="cnn">
    <title>Breaking News</title>
    <desc>Latest news coverage</desc>
  </programme>
</tv>

{
  "epg_listings": [
    {
      "id": "12345",
      "epg_id": "cnn",
      "title": "Breaking News",
      "start": "2026-03-03 12:00:00",
      "end": "2026-03-03 13:00:00",
      "description": "Latest news coverage"
    }
  ]
}

EPG Setup:
├── XMLTV from Provider (Priority: 100)
│   └── Covers 80% of channels
├── Schedules Direct (Priority: 200)
│   └── Covers US channels with high accuracy
└── Dummy EPG (Priority: 10)
    └── Fallback for remaining channels

Result: Best available guide data for each channel

Scenario: Build custom guide for curated channels

1. Import multiple XMLTV sources
2. Set priorities based on accuracy
3. Auto-match channels to EPG data
4. Export unified XMLTV for Plex/Jellyfin

Large XMLTV: 50MB uncompressed
├── Download: 5MB gzipped (10x reduction)
├── Cache: Store compressed version
└── Parse: Stream from compressed file

Result: Minimal bandwidth and storage usage