ErsatzTV generates XMLTV (Electronic Program Guide) data for all channels. You can fully customize how programs appear in the EPG using Scriban templates.
Overview The EPG system uses Scriban templates to generate XMLTV data. Each media type (movies, episodes, music videos, etc.) has its own template that controls what appears in the guide.
Template Locations Default templates (included with ErsatzTV):ErsatzTV/Resources/Templates/ _channel.sbntxt # Channel definition _episode.sbntxt # TV episodes _movie.sbntxt # Movies _musicVideo.sbntxt # Music videos _song.sbntxt # Audio-only songs _otherVideo.sbntxt # Other videos _remoteStream.sbntxt # Remote streams
Custom templates (user overrides):/config/templates/ channel.sbntxt # Override channel template episode.sbntxt # Override episode template movie.sbntxt # Override movie template musicVideo.sbntxt # Override music video template song.sbntxt # Override song template otherVideo.sbntxt # Override other video template remoteStream.sbntxt # Override remote stream template
Default templates start with an underscore (_). Create custom templates WITHOUT the underscore to override defaults. Never edit the default templates directly.
Guide Mode ErsatzTV supports two guide modes that control EPG visibility:
All scheduled content appears in the EPG guide. Use cases:
Standard TV channels
When viewers should see all content
Content is hidden from the EPG guide. Use for commercials, bumpers, or other interstitial content that shouldn’t appear in program listings. Use cases:
Commercial breaks
Channel bumpers
Station IDs
Filler content between programs
Setting Guide Mode In Classic Schedules:
Edit schedule item
Set Guide Mode to Normal or Filler
Filler items won’t appear in EPG but will still play
In Block Schedules: Guide mode is determined by the deco configuration and block item settings.
Movie Template Default Movie Template < programme start = "{{ programme_start }}" stop = "{{ programme_stop }}" channel = "{{ channel_id }}" > {{ if has_custom_title }} < title lang = "en" > {{ custom_title }} </ title > {{ else }} < title lang = "en" > {{ movie_title }} </ title > {{ if movie_has_plot }} < desc lang = "en" > {{ movie_plot }} </ desc > {{ end }} {{ if movie_has_year }} < date > {{ movie_year }} </ date > {{ end }} < category lang = "en" > Movie </ category > {{ for genre in movie_genres }} < category lang = "en" > {{ genre }} </ category > {{ end }} {{ if movie_has_artwork }} < icon src = "{{ movie_artwork_url }}" /> {{ end }} {{ end }} {{ if movie_has_content_rating }} {{ for rating in movie_content_rating | string.split '/' }} {{ if rating | string.starts_with 'us:' }} < rating system = "MPAA" > {{ else }} < rating > {{ end }} < value > {{ rating | string.replace 'us:' '' }} </ value > </ rating > {{ end }} {{ end }} < previously-shown /> </ programme >
Available Movie Variables Variable Type Description programme_startstring Start time (XMLTV format) programme_stopstring Stop time (XMLTV format) channel_idstring Channel identifier channel_id_legacystring Legacy channel ID channel_numberstring Channel number has_custom_titlebool True if custom title set custom_titlestring Custom EPG title movie_titlestring Movie title movie_has_plotbool True if plot exists movie_plotstring Movie plot/description movie_has_yearbool True if year exists movie_yearint Release year movie_genresarray List of genres movie_has_artworkbool True if artwork exists movie_artwork_urlstring Poster URL movie_has_content_ratingbool True if rating exists movie_content_ratingstring Content rating movie_guidsarray External IDs (IMDb, TMDb, etc.)
Episode Template Default Episode Template < programme start = "{{ programme_start }}" stop = "{{ programme_stop }}" channel = "{{ channel_id }}" > {{ if has_custom_title }} < title lang = "en" > {{ custom_title }} </ title > {{ else }} < title lang = "en" > {{ show_title }} </ title > {{ if episode_has_title }} < sub-title lang = "en" > {{ episode_title }} </ sub-title > {{ end }} {{ if episode_has_plot }} < desc lang = "en" > {{ episode_plot }} </ desc > {{ end }} < category lang = "en" > Series </ category > {{ for genre in show_genres }} < category lang = "en" > {{ genre }} </ category > {{ end }} {{ if episode_has_artwork }} < icon src = "{{ episode_artwork_url }}" /> < image type = "poster" size = "3" > {{ episode_artwork_url }} </ image > {{ end }} {{ if episode_has_thumbnail }} < image type = "still" orient = "L" size = "3" > {{ episode_thumbnail_url }} </ image > {{ end }} {{ end }} < episode-num system = "onscreen" > S{{ season_number | math.format '00' }}E{{ episode_number | math.format '00' }} </ episode-num > < episode-num system = "xmltv_ns" > {{ season_number - 1 }}.{{ episode_number - 1 }}.0/1 </ episode-num > {{ if show_has_content_rating }} {{ for rating in show_content_rating | string.split '/' }} {{ if rating | string.downcase | string.starts_with 'us:' }} < rating system = "VCHIP" > {{ else }} < rating > {{ end }} < value > {{ rating | string.replace 'us:' '' | string.replace 'US:' '' }} </ value > </ rating > {{ end }} {{ end }} < previously-shown /> </ programme >
Available Episode Variables Variable Type Description programme_startstring Start time programme_stopstring Stop time channel_idstring Channel identifier has_custom_titlebool Custom title flag custom_titlestring Custom EPG title show_titlestring TV show title episode_has_titlebool Episode title exists episode_titlestring Episode title episode_has_plotbool Episode plot exists episode_plotstring Episode description show_has_yearbool Show year exists show_yearint Show release year show_genresarray Show genres episode_has_artworkbool Episode poster exists episode_artwork_urlstring Episode poster URL episode_has_thumbnailbool Episode thumbnail exists episode_thumbnail_urlstring Episode still URL season_numberint Season number episode_numberint Episode number show_has_content_ratingbool Show rating exists show_content_ratingstring Show content rating show_guidsarray Show external IDs episode_guidsarray Episode external IDs
Music Video Template Available Music Video Variables Variable Type Description artist_titlestring Artist name music_video_titlestring Song/video title music_video_has_plotbool Description exists music_video_plotstring Video description music_video_has_yearbool Release year exists music_video_yearint Release year music_video_genresarray Video genres artist_genresarray Artist genres music_video_has_artworkbool Artwork exists music_video_artwork_urlstring Artwork URL music_video_has_trackbool Track number exists music_video_trackint Track number music_video_has_albumbool Album exists music_video_albumstring Album name music_video_has_release_datebool Release date exists music_video_release_datestring Release date music_video_all_artistsarray All artists (featuring, etc.) music_video_studiosarray Studios/labels music_video_directorsarray Video directors
Custom EPG Data You can expose custom data to the graphics engine using the etv: XML namespace:
< programme start = "{{ programme_start }}" stop = "{{ programme_stop }}" channel = "{{ channel_id }}" > < title lang = "en" > {{ movie_title }} </ title > <!-- Custom data for graphics engine --> < etv:custom_field > {{ movie_year }} </ etv:custom_field > < etv:rating_text > {{ movie_content_rating }} </ etv:rating_text > </ programme >
All etv: nodes are:
Passed to the graphics engine as EPG template data
Stripped from XMLTV when requested by clients
Available as strings (not numbers) in graphics templates
XMLTV Settings Configure EPG behavior in Settings > General :
XMLTV Days to Build Controls how many days of EPG data to generate.
Must be ≤ Playout Days To Build
Smaller values improve performance
Larger values provide more guide data
Set Playout Days To Build to 7 for scheduling, but XMLTV Days To Build to 1-2 for performance if your IPTV client doesn’t need a full week of EPG data.
XMLTV Time Zone Controls time zone in generated XMLTV:
Uses local server time zone (from TZ environment variable) Uses UTC time zone (recommended for international use) XMLTV Block Behavior Controls how block schedules appear in EPG:
Split Time Evenly
Use Actual Times
Default behavior. Block time is split evenly among all visible items. XMLTV Block Behavior: Split Time Evenly
Example:
1-hour block with 3 visible items
Each item shows as 20 minutes in EPG
Uses real playback times for items in EPG. XMLTV Block Behavior: Use Actual Times
Note: This creates EPG gaps when filler is used or items are hidden.Instance ID Disambiguate EPG data when running multiple ErsatzTV instances:
Channel identifiers become:
100.home.ersatztv.org # Instead of 100.ersatztv.org
Accessing XMLTV Data URLs Without authentication: http://localhost:8409/iptv/xmltv.xml
With access token: http://localhost:8409/iptv/xmltv.xml?access_token=YOUR_TOKEN
Behind reverse proxy with base URL: http://yourdomain.com/ersatztv/iptv/xmltv.xml
M3U Playlist The channel playlist already includes the XMLTV URL:
http://localhost:8409/iptv/channels.m3u
Advanced Template Examples Add Director to Movie EPG < programme start = "{{ programme_start }}" stop = "{{ programme_stop }}" channel = "{{ channel_id }}" > < title lang = "en" > {{ movie_title }} </ title > {{ if movie_has_plot }} < desc lang = "en" > {{ movie_plot }} </ desc > {{ end }} <!-- Add director if available --> {{ if movie_directors }} {{ for director in movie_directors }} < credits > < director > {{ director }} </ director > </ credits > {{ end }} {{ end }} < category lang = "en" > Movie </ category > </ programme >
Check default templates for available variables like movie_directors, movie_actors, etc. These may vary by media type.
Conditional Categories {{ if movie_year >= 2020 }} < category lang = "en" > New Release </ category > {{ else if movie_year >= 2010 }} < category lang = "en" > Recent </ category > {{ else }} < category lang = "en" > Classic </ category > {{ end }}
Multiple Images {{ if episode_has_artwork }} < icon src = "{{ episode_artwork_url }}" /> < image type = "poster" size = "3" > {{ episode_artwork_url }} </ image > {{ end }} {{ if episode_has_thumbnail }} < image type = "still" orient = "L" size = "3" > {{ episode_thumbnail_url }} </ image > {{ end }}
Scriban Functions Useful Scriban functions for templates:
String Functions {{ movie_title | string.upcase }} # UPPERCASE {{ movie_title | string.downcase }} # lowercase {{ movie_title | string.capitalize }} # Capitalize {{ movie_plot | string.truncate 100 }} # Limit to 100 chars {{ movie_title | string.replace "The" "" }} # Remove "The"
Math Functions {{ season_number | math.format '00' }} # Zero-pad: 01, 02 {{ movie_year + 10 }} # Add 10 to year {{ episode_number | math.abs }} # Absolute value
Array Functions {{ movie_genres | array.first }} # First genre {{ movie_genres | array.last }} # Last genre {{ movie_genres | array.size }} # Count genres
Troubleshooting Template Syntax Errors Check ErsatzTV logs for template parsing errors:docker-compose logs -f ersatztv | grep template
Common issues:
Missing {{ end }} tags
Unclosed {{ if }} blocks
Typos in variable names
EPG Not Updating
Trigger manual rebuild : Edit and save any scheduleCheck XMLTV URL : Visit http://localhost:8409/iptv/xmltv.xml directlyClear IPTV client cache : Some clients cache EPG data
Verify metadata : Check if source media has the data (NFO files, media server)Deep scan library : Trigger a deep scan to update metadataCheck template variables : Use {{ if variable_exists }} guards
500 Errors Serving XMLTV Fixed in v26.2.0+. If experiencing issues:
Update to latest ErsatzTV version
Check for concurrent XMLTV reads/writes in logs
Ensure sufficient disk space in /config
Next Steps
Graphics Engine Use EPG data in custom graphics overlays
Channel Configuration Configure channel settings
Classic Schedules Set guide mode and custom titles
Scriban Documentation Learn more about Scriban template syntax
