Pull TV schedules from XMLTV sources and serve them to your ɳTV channels. Channels get show metadata, episode info, and cover art automatically — no manual schedule entry.
nself license set nself_pro_...
nself plugin install epg
nself build
nself startnself-epg fetches XMLTV-format EPG data on a configurable schedule (default: every 12 hours), parses program listings, and stores them in Postgres mapped to your ɳTV channels. The ɳTV app reads the EPG API to show what is on now, what is coming next, and a full 7-day grid.
Channel-to-EPG mapping is flexible: you can match by TVG-ID (the standard XMLTV channel identifier embedded in M3U playlists) or by channel name. Unmatched channels still play but show no guide data. You can also enter manual EPG entries for channels with no public XMLTV source.
EPG data enriches the nself-tmdb integration: when a program title matches a TMDB entry, the plugin attaches high-resolution poster art, ratings, cast, and description automatically.
| Variable | Required | Description |
|---|---|---|
DATABASE_URL | Yes | Postgres connection string (auto-set by nself) |
EPG_SOURCES | Yes | Comma-separated XMLTV URLs, e.g. https://example.com/guide.xml,https://other.com/epg.xml |
EPG_REFRESH_HOURS | No | How often to re-fetch EPG data. Default: 12 |
EPG_TMDB_ENRICH | No | Enrich programs with TMDB metadata when nself-tmdb is installed. Default: true |
EPG_RETENTION_DAYS | No | Keep historical EPG data for N days. Default: 7 |
| Endpoint | Method | Description |
|---|---|---|
/epg/now | GET | Current program on all channels |
/epg/channels/:id/schedule | GET | 7-day schedule for a specific channel |
/epg/grid | GET | Full grid (all channels × time window) |
/epg/refresh | POST | Trigger an immediate EPG data fetch |
/epg/channels/:id/manual | POST | Add a manual program entry for a channel |
/health | GET | Plugin health and last-fetch timestamp |
| Table | Purpose |
|---|---|
np_epg_channels | EPG channel registry with TVG-ID and nself channel mapping |
np_epg_programs | Program listings: title, description, start/end, TMDB enrichment |
| Event | Payload |
|---|---|
epg.refreshed | Source URL, programs imported, channels matched |
epg.program.started | Channel ID, program title, TMDB ID (if enriched) |
Configure EPG_SOURCES with your XMLTV provider URLs (Schedules Direct, EPG.best, or any self-hosted XMLTV source). The ɳTV app reads /epg/grid to render the channel guide and /epg/now for the "what's on" overview. Pair with nself-tmdb for automatic poster art and ratings.
No guide data showing: Run POST /epg/refresh and check nself plugin logs epg for fetch errors. XMLTV sources must be HTTPS and return valid XML; gzipped responses are supported.
Channels not matching: The TVG-ID in your M3U playlist must match the EPG channel ID in the XMLTV source. Edit the channel mapping at /epg/channels/:id to manually link mismatched channels.
Port: 3512 (moved from 3090) | Bundle: ɳTV ($0.99/mo) or ɳSelf+ ($3.99/mo) | Last Updated: May 2026 | Plugin Version 1.0.13