Skip to main content
EPG (Electronic Program Guide) sources provide schedule information for your IPTV channels. Dispatcharr supports multiple EPG formats and matching strategies.

​
Supported EPG Types

XMLTV

Standard XMLTV format from URL

Schedules Direct

Official TV listings API

Custom Dummy EPG

Generated placeholder schedules

​
Adding an EPG Source

1

Navigate to EPG Sources

Go to Settings > EPG Sources in the admin panel
2

Create New Source

Click Add EPG Source and select source type
3

Configure Source Details

Enter connection details based on EPG type
4

Set Refresh Schedule

Configure automatic refresh intervals
5

Configure Matching

Adjust EPG matching settings for channel association

​
Configuration Fields

​
Basic Settings

​
name
string
required
Unique identifier for this EPG source
​
source_type
enum
required
EPG source type:
  • xmltv - XMLTV URL
  • schedules_direct - Schedules Direct API
  • dummy - Custom Dummy EPG
​
is_active
boolean
default:true
Enable or disable this EPG source

​
Source-Specific Configuration

​
url
url
required
Direct URL to XMLTV file. Supports:
  • Plain XML: http://provider.com/epg.xml
  • Gzip compressed: http://provider.com/epg.xml.gz
  • Zip archives: http://provider.com/epg.zip
Dispatcharr automatically detects file compression (gzip/zip) and extracts the XML content.
The system stores downloaded files in MEDIA_ROOT/cached_epg/ and tracks both:
  • file_path - Original downloaded file
  • extracted_file_path - Decompressed XML file
​
api_key
string
required
Your Schedules Direct API key
Schedules Direct requires a paid subscription. Visit schedulesdirect.org to sign up.
Use custom_properties JSON field to configure dummy EPG generation:
{
  "regex_patterns": [
    {
      "pattern": "^Sport.*",
      "title_template": "Live Sports Event",
      "description": "Sports programming"
    }
  ],
  "timezone": "UTC",
  "program_duration": 60,
  "days_ahead": 7
}
​
custom_properties.regex_patterns
array
Array of pattern matching rules for channel names
​
custom_properties.timezone
string
default:"UTC"
Timezone for generated schedules
​
custom_properties.program_duration
integer
default:60
Default program duration in minutes
​
custom_properties.days_ahead
integer
default:7
Number of days to generate ahead

​
Refresh Configuration

​
refresh_interval
integer
default:0
Automatic refresh interval in seconds (0 = manual only)Recommended intervals:
  • XMLTV: 43200 (12 hours) or 86400 (24 hours)
  • Schedules Direct: 21600 (6 hours)
  • Dummy EPG: 86400 (24 hours)
​
refresh_task
reference
Auto-managed periodic task for scheduled refreshes (managed by django-celery-beat)

​
Priority and Matching

​
priority
integer
default:0
EPG source priority for matching (higher = higher priority)When multiple EPG sources have matching entries for a channel, the highest priority source is used.

​
EPG Matching Configuration

Dispatcharr matches EPG data to channels using tvg-id attributes. Configure global matching behavior in Settings > EPG Settings.

​
Match Modes

​
epg_match_mode
enum
default:"default"
Channel matching strategy:
  • default - Match by tvg-id exactly
  • Custom modes can be implemented via settings

​
Match Filtering

Remove common prefixes/suffixes that interfere with matching:
​
epg_match_ignore_prefixes
array
default:[]
Array of prefixes to strip before matching:
["HD ", "SD ", "FHD ", "4K "]
​
epg_match_ignore_suffixes
array
default:[]
Array of suffixes to strip before matching:
[" HD", " FHD", " 4K", " +1"]
​
epg_match_ignore_custom
array
default:[]
Custom regex patterns to remove before matching:
["\\s*\\[.*?\\]", "\\s*\\(.*?\\)"]
These settings are configured in CoreSettings under the epg_settings key, not per EPG source.

​
EPG Data Structure

​
EPGData Model

Each channel in the EPG source creates an EPGData record:
​
tvg_id
string
Original tvg-id from the XMLTV file
​
name
string
Channel display name from EPG
​
icon_url
url
Channel logo URL (if provided in EPG)
​
epg_source
reference
Reference to parent EPG source
Each (tvg_id, epg_source) combination is unique in the database.

​
ProgramData Model

Schedule entries for each EPG channel:
​
epg
reference
required
Reference to EPGData parent record
​
start_time
datetime
required
Program start time (timezone-aware)
​
end_time
datetime
required
Program end time (timezone-aware)
​
title
string
required
Program title
​
sub_title
string
Episode title or subtitle
​
description
text
Full program description
​
tvg_id
string
Channel identifier (duplicated for query optimization)
​
custom_properties
json
Additional metadata from XMLTV:
  • Category/genre
  • Episode numbers
  • Credits (actors, directors)
  • Ratings
  • Language

​
Source Status Tracking

​
status
enum
Current EPG source status:
StatusDescription
idleWaiting for next refresh
fetchingDownloading EPG file
parsingProcessing XML and updating database
successLast refresh successful
errorLast refresh failed
disabledSource inactive
​
last_message
string
Status message including:
  • Success: Number of channels/programs imported
  • Error: Detailed error information
​
updated_at
datetime
Timestamp of last successful refresh
​
created_at
datetime
Source creation timestamp

​
Example Configurations

{
  "name": "IPTV EPG",
  "source_type": "xmltv",
  "url": "https://provider.com/epg.xml.gz",
  "is_active": true,
  "refresh_interval": 43200,
  "priority": 10
}

​
Best Practices

Use priority to control fallback behavior:
  1. High priority (10-20): Premium sources (Schedules Direct)
  2. Medium priority (5-9): XMLTV from providers
  3. Low priority (0-4): Dummy EPG as fallback
  • Don’t refresh more often than source updates
  • XMLTV files typically update every 12-24 hours
  • Avoid excessive API calls to Schedules Direct
  • Monitor status and last_message for issues
  • Configure ignore patterns to handle provider naming inconsistencies
  • Use consistent tvg-id values across M3U and EPG sources
  • Check EPG match settings if channels aren’t linking properly
Large XMLTV files (100MB+) may take several minutes to parse. Monitor system resources during EPG refresh operations.