EPG

Kiln downloads the XMLTV sources you enable, matches their programs to your channels, and merges the results into one guide. Players only need /v1/epg.xml.gz, regardless of how many sources are behind it.

How it works

• Sources are managed on the EPG page of the admin console and stored in SQLite. No config file edit is required.
• Every built-in preset source ships disabled. Enable at least one, or add a custom source, before you expect any data.
• [[epg.sources]] in the config file seeds the database once, and only while no source rows exist. After that the database wins.
• There is no EPG master switch. Whether a guide is served depends solely on whether any source is enabled. The lite build has no EPG at all, and refuses to start when the config carries an enabled EPG source.

[epg]
cache = true
cache_dir = "./data/epg"
refresh_interval_min = 360
max_refresh_concurrency = 0
max_source_bytes = 67108864
default_timezone = "UTC"
serve_timezone = "keep"

Cache modes

cache and cache_dir together select one of three behaviors for the raw XMLTV payloads.

Refreshing

• refresh_interval_min defaults to 360. Kiln refreshes once at startup, then on that interval.
• max_refresh_concurrency = 0 refreshes every source in parallel. A positive value caps how many sources are in flight at once.
• Under server.resource_mode = "auto" (the default), both 0 and oversized values are clamped from the detected CPU and memory limits, and any constrained profile pins it to 1. constrained also pins it to 1; performance applies no adaptation at all. See the configuration reference.

For a manual run, call POST /v1/admin/epg/refresh with the refresh scope. It returns 409 when no source is enabled. Sources refresh independently, so one failing source does not block the others, and the response carries the latest per-source status.

Size limit

max_source_bytes defaults to 64 MiB (67108864) and applies to the decompressed XMLTV body.

• An oversized download fails the round. Existing data stays available and is flagged as stale rather than being replaced by a truncated body.
• A cached entry that already exceeds the limit is discarded and never used as a fallback.
• Under auto the limit is lowered with memory: below 256 MiB of memory it drops to 4 MiB, and other constrained profiles land somewhere between 4 MiB and 64 MiB depending on available memory.

Time zones

• Every source carries its own IANA time zone, used when parsing timestamps that lack an explicit offset. Custom sources created in the console default to UTC.
• default_timezone is the fallback for sources that declare no zone. It must be a valid IANA name; an invalid value fails config validation at startup.
• serve_timezone currently accepts only keep: the published guide preserves each program’s original UTC offset instead of converting everything to one serving zone. Any other value fails validation.

Per-source egress

Each source has its own egress setting that plugs into the global outbound routing.

What gets published

• Only matched channels are published. Kiln rewrites their channel IDs and the associated programs to its own channel IDs, so tvg-id in the M3U matches the guide automatically.
• /v1/playlist.m3u and the playlist behind an access token carry x-tvg-url on the #EXTM3U line, pointing at /v1/epg.xml.gz.
• With no source enabled, both endpoints return a valid but empty XMLTV document rather than a 404.
• The gzipped output is cached in memory and invalidated whenever source data or the channel list changes. Payloads larger than a quarter of max_source_bytes (capped at 8 MiB) are returned without being cached.
• The logo endpoint normalizes the channel’s epg_name (or its title when empty), looks it up in the built-in logo table, and tries each candidate URL in order. Images are limited to 2 MiB and served with a one-hour public cache and an X-Kiln-Logo-Source header. The endpoint returns 404 when there is no candidate and 502 when candidates exist but every download fails. Logo requests follow the channel’s outbound route.

Admin endpoints

Updates and deletes require an If-Match revision and return 409 on conflict. Deleting a preset source hides it rather than removing it permanently. Full details are in the API reference.