Denver OTA XMLTV Guide

Fastify API that serves a Jellyfin-compatible XMLTV feed for the Denver OTA lineup USA-OTA80022 using EPGShare US_LOCALS1.

Source

Primary source:

• XMLTV: https://epgshare01.online/epgshare01/epg_ripper_US_LOCALS1.xml.gz
• ID list: https://epgshare01.online/epgshare01/epg_ripper_US_LOCALS1.txt
• Denver callsigns: KUSA,KCNC,KMGH,KDVR,KRMA,KWGN,KTVD,KBDI

Open-EPG is not wired into runtime. Its public files are documented as an emergency manual fallback only because the public guide page advertises 2 days of guide data, daily updates, 20 downloads/day per file, and an unstable migration period.

References:

• EPGShare README
• EPGShare index
• Open-EPG public guide page
• Open-EPG FAQ

Local Colima Setup

Install Docker CLI and Compose first if docker version or docker compose version fails.

colima start --cpu 4 --memory 6 --disk 40
docker version
docker compose version
cp .env.local.example .env.local
docker compose --env-file .env.local up --build

If docker compose is not available but standalone Compose is installed, use docker-compose --env-file .env.local up --build.

The API is exposed at http://localhost:3330.

Smoke checks:

curl http://localhost:3330/healthz
curl http://localhost:3330/guide/status
curl http://localhost:3330/channels/denver
curl 'http://localhost:3330/lineups/USA-OTA80022/xmltv?days=4'

Endpoints

• GET /healthz
• GET /metrics.json
• GET /guide/status
• GET /channels/denver
• GET /lineups/USA-OTA80022/channels
• GET /lineups/USA-OTA80022/xmltv?days=4
• POST /refresh
• GET /ui

Retired source-specific endpoints return 410 Gone, including /xmltv/tvpass, /tvpass/playlist.m3u, /tvpass/playlist.meta, /epgshare/xmltv, and /epgshare/xmltv/match.

USA-OTA800222 is treated as an invalid lineup typo; use USA-OTA80022.

Cache Behavior

The app stores the filtered Denver XMLTV and metadata in cache_items.

• Refreshes are skipped while the cache is younger than GUIDE_REFRESH_INTERVAL_MINUTES.
• Conditional request headers are sent when EPGShare provides ETag or Last-Modified.
• If EPGShare fails and a previous feed exists, the app serves stale XMLTV and marks /guide/status as degraded.
• Cache is stale when older than GUIDE_STALE_AFTER_HOURS.

Environment

See .env.local.example for Docker/Colima and .env.example for local process defaults.

Important values:

• DEFAULT_LINEUP_ID=USA-OTA80022
• GUIDE_SOURCE=epgshare
• GUIDE_TIMEZONE=America/Denver
• EPGSHARE_ID=US_LOCALS1
• DENVER_CALLSIGNS=KUSA,KCNC,KMGH,KDVR,KRMA,KWGN,KTVD,KBDI
• PUBLIC_PORT=3330

Tests

npm run typecheck
npm run test:run