ersatztv/docs/m3u-xmltv.md

M3U/XMLTV Integration

Overview

ErsatzTV serves M3U playlists and XMLTV guide data via HTTP endpoints. Jellyfin consumes these as an IPTV tuner source.

Endpoints

Route	Purpose
GET /iptv/channels.m3u	M3U playlist (channel list + stream URLs)
GET /iptv/xmltv.xml	XMLTV guide (EPG data)
GET /iptv/logos/{fileName}.jpg	Uploaded channel logos
GET /iptv/logos/gen?text={name}	Generated text logos (SkiaSharp, 200x100 PNG)
GET /iptv/channel/{number}.ts	Transport stream
GET /iptv/channel/{number}.m3u8	HLS stream

All defined in ErsatzTV/Controllers/IptvController.cs (streams) and ErsatzTV/Controllers/ArtworkController.cs (logo generation).

M3U Generation

Code: ErsatzTV.Core/Iptv/ChannelPlaylist.cs → ToM3U()

The controller captures Request.Scheme, Request.Host, and Request.PathBase from the incoming HTTP request and passes them through MediatR to the playlist builder. All URLs in the M3U output use the request-derived host — they are not hardcoded.

Each channel entry includes:

• tvg-id — channel number as identifier
• tvg-chno — channel number for ordering
• tvg-name — channel display name
• tvg-logo — logo URL (uploaded artwork or generated text logo)
• tvc-stream-vcodec / tvc-stream-acodec — codec hints from FFmpeg profile
• CUID — base64-encoded UniqueId
• group-title — channel group for categorization
• Stream URL (format depends on channel's streaming mode)

The XMLTV guide URL is included as an #EXTM3U header attribute.

XMLTV Generation

Code: ErsatzTV.Application/Channels/Queries/GetChannelGuideHandler.cs

XMLTV data is pre-generated from Scriban templates (ErsatzTV/Resources/Templates/_channel.sbntxt) and cached as XML fragments. At request time, the handler:

1. Reads cached fragments from disk
2. Substitutes {RequestBase} with the actual scheme://host/base from the request
3. Substitutes {AccessTokenUri} with version + optional auth token
4. Filters channels by ShowInEpg
5. Combines channel list + program entries into the final XML

Jellyfin Integration

Current homelab topology (2026-06): Jellyfin does not tuner ErsatzTV directly — it funnels ErsatzTV through Dispatcharr (dispatcharr:9191), which ingests ErsatzTV and re-serves the channels/EPG. The direct-tuner setup below is the generic reference for pointing any tuner at ErsatzTV; see "Resolution (2026-06-27)" under the Logo URL Issue for the live pipeline.

Tuner Setup (direct — reference)

To point an IPTV tuner directly at ErsatzTV:

http://ersatztv:8409/iptv/channels.m3u

Jellyfin reads the M3U to discover channels and their stream URLs. The Host header in Jellyfin's request determines what host appears in all embedded URLs — so the hostname used in the tuner URL matters.

Guide Data

Jellyfin fetches the XMLTV URL embedded in the M3U header for EPG data. This provides program titles, descriptions, and timing for the TV guide.

Guide Refresh

Jellyfin periodically refreshes the guide data. Channel logos are fetched from the tvg-logo URLs in the M3U. If those URLs are unreachable from Jellyfin's network context, logos break.

Logo URL Issue (Gitea #1)

The Problem

Channel logos break after Jellyfin guide refreshes. The issue was originally reported as hardcoded localhost in tvg-logo URLs.

Investigation Findings

The M3U and XMLTV generation paths correctly use request-derived host:

• ChannelPlaylist.ToM3U() builds logo URLs from _scheme, _host, _baseUrl (all from the request)
• GetChannelGuideHandler substitutes {RequestBase} at request time

The actual hardcoded localhost is in ChannelLogoGenerator.GenerateChannelLogoUrl() (ErsatzTV.Core/Images/ChannelLogoGenerator.cs, line 82):

$"http://localhost:{Settings.StreamingPort}{GetRoute}?{GetRouteQueryParamName}={channel.WebEncodedName}"

This method is called only by WatermarkSelector.cs (lines 219, 268, 317, 385) — for watermark overlays during transcoding, not for M3U/XMLTV output. Since FFmpeg runs on the same host as ErsatzTV, localhost is correct for watermarks.

Confirmed Root Cause (2026-06-26)

Live experiment against the running ersatztv container on bumblebee (192.168.1.99:8409) proves the host in tvg-logo is entirely a function of the incoming Host header — there is no hardcoded localhost in the M3U/XMLTV path:

curl -H "Host: localhost:8409" .../iptv/channels.m3u  ->  tvg-logo="http://localhost:8409/iptv/logos/...jpg"
curl -H "Host: ersatztv:8409"  .../iptv/channels.m3u  ->  tvg-logo="http://ersatztv:8409/iptv/logos/...jpg"

So the http://localhost:8409 URLs that broke in Jellyfin were baked in because a client fetched ErsatzTV using Host: localhost:8409 (a misconfigured tuner/XMLTV URL in Jellyfin's Live TV settings, or a proxy passing that Host). The original issue framing ("hardcoded localhost in code") is a red herring — see Investigation Findings above.

This is therefore not a code bug in the M3U/XMLTV generators. The fix is operational, not code:

• Operational (server-management): Jellyfin's IPTV source must reach ErsatzTV via a host that is resolvable and correct from Jellyfin's network context (e.g. http://ersatztv:8409), never localhost. Owned by server-management (related: its issue #171).

Architecture: absolute-URL generation (relevant for future work)

ErsatzTV now has an optional "advertised base URL" setting for IPTV (iptv.base_url, #340 — see "IPTV base URL" below). When it is unset (the default), every absolute URL ErsatzTV emits is derived from the incoming request's Scheme + Host + PathBase, exactly as described below; when it is set, the two IPTV generators (M3U + XMLTV) use the configured scheme/host/base instead:

Output	Source of host
M3U stream URLs & tvg-logo	ChannelPlaylist ctor args _scheme/_host/_baseUrl, captured in IptvController.GetChannelPlaylist from Request.Scheme/Request.Host/Request.PathBase
XMLTV channel <icon> and programme artwork	{RequestBase} placeholder in the cached .xml fragments, substituted in GetChannelGuideHandler with request.Scheme://request.Host{request.BaseUrl}
FFmpeg watermark overlay logo	ChannelLogoGenerator.GenerateChannelLogoUrl() — hardcoded http://localhost:{StreamingPort} (correct: FFmpeg runs in-container). Not part of M3U/XMLTV.

Implications for future work:

• With iptv.base_url unset, any client that connects via a different host (localhost, a reverse-proxy alias, split-DNS name) still gets that host echoed back into stream + logo + artwork URLs. Setting iptv.base_url pins the M3U + XMLTV URLs to a fixed public origin regardless of the request Host, which is the mitigation for a reverse-proxy / split-DNS deployment (server-management). The HDHomeRun lineup URLs are not covered by iptv.base_url (deliberately out of scope for #340) and still echo the request host.
• Settings are stored in the ConfigElement table as simple key/value (ConfigElementKey in ErsatzTV.Core/Domain/ConfigElementKey.cs; read/write via IConfigElementRepository.GetValue<T> / upsert). Adding a new setting needs no EF migration — this is exactly how iptv.base_url (ConfigElementKey.IptvBaseUrl) was added.

Resolution (2026-06-27) — Gitea #1 closed as config/topology, no code change

A second live investigation (against the running stack on bumblebee, 192.168.1.99) confirmed the original symptom is not reproducible in the current architecture, because the topology changed since #1 was filed (Feb 2026):

Jellyfin no longer tuners ErsatzTV directly. Per Jellyfin's livetv.xml, its only Live TV source is Dispatcharr (http://dispatcharr:9191/output/m3u + /output/epg). ErsatzTV is funneled through Dispatcharr:

ErsatzTV ──(Dispatcharr fetches via ersatztv:8409)──▶ Dispatcharr ──▶ Jellyfin
  • channel logos   → Dispatcharr re-hosts as http://dispatcharr:9191/...   (HTTP 200 image/png ✓)
  • programme icons → passed through as http://ersatztv:8409/...  (3095 of them, HTTP 200 image/png ✓)
  • localhost references anywhere Jellyfin consumes: 0

Evidence gathered (all read-only):

• ErsatzTV fetched via ersatztv:8409 returns correct ersatztv:8409 URLs (no localhost).
• All 44 cached guide fragments under /config/cache/channel-guide/*.xml contain the {RequestBase} placeholder — zero baked localhost. Nothing is persisted absolute.
• Dispatcharr's M3U + EPG output contain 0 localhost; sample logo and icon both fetch HTTP 200 image/png from inside the Jellyfin container.

Root cause = configuration/topology, not code. The historical localhost:8409 came from a client fetching ErsatzTV with Host: localhost:8409; that path no longer exists. Closed without a code change.

Note — the forwarded-headers theory (KnownProxies.Clear() in Startup.cs making X-Forwarded-* be ignored) is incorrect: clearing both KnownProxies and KnownNetworks sets checkKnownIps = false, which trusts all proxies, not none. And there is no proxy between Jellyfin and ErsatzTV. Red herring.

Latent fragility (not currently broken) — now configurable via iptv.base_url (#340)

The EPG Jellyfin consumes still contains 3095 absolute http://ersatztv:8409/... programme-icon URLs. They work only because Dispatcharr fetches ErsatzTV with a Jellyfin-resolvable host, and Jellyfin shares the Docker network. By default every absolute URL is still hostage to the request Host, so if a client ever fetches ErsatzTV with a host that downstream consumers can't resolve, the same class of breakage returns.

The mitigation is now built-in: set the IPTV base URL (iptv.base_url, see below) to a fixed public origin and the M3U + XMLTV URLs stop depending on the request Host entirely. It stays opt-in — unset behaviour is byte-for-byte the request-derived behaviour described above, so nothing changes for a deployment that doesn't need it.

IPTV base URL (#340)

Originally logged here as "optional future hardening (NOT committed)"; implemented in #340. An optional advertised base URL for the IPTV surface:

• Config: stored as a single ConfigElement under ConfigElementKey.IptvBaseUrl (key iptv.base_url, key/value, no EF migration). Distinct from the ETV_BASE_URL environment variable, which only sets the ASP.NET Core PathBase (request routing) and does not advertise a host.
• Helper: a pure Core helper, ErsatzTV.Core/Iptv/AdvertisedBaseUrl.cs.
  • TryParse(string) validates the configured value and returns Option<(scheme, host, baseUrl)> — it must be an absolute http(s) URL with no credentials, query, or fragment; the port and any path prefix are preserved, and a trailing slash is normalized off. Anything that fails these rules parses to None.
  • Resolve(configured, requestScheme, requestHost, requestBaseUrl) returns the parsed override when the configured value is present and valid, and otherwise falls back to the request-derived scheme/host/base. So a blank or malformed value is transparently ignored.
• Where it's applied: resolution happens inside the two generation handlers, not in the controller — GetChannelPlaylistHandler (M3U guide/logo/stream URLs, via ChannelPlaylist) and GetChannelGuideHandler (both XMLTV {RequestBase} substitution sites). Because unset/invalid falls back to the request values, the golden tests (ChannelPlaylistGoldenTests, ChannelGuideGoldenTests) are unchanged.
• Scope: M3U + XMLTV only. Deliberately NOT applied to the HDHomeRun lineup URLs (out of scope for #340).
• API + UI: managed through a new "IPTV" settings group — GET/PUT /api/v1/settings/iptv on SettingsController (tier [RequiresAuthentication]), body { baseUrl }. A blank value clears the key; a non-blank malformed value → 422. A new "IPTV" section on the SPA Settings screen edits it.

Covered by unit tests on AdvertisedBaseUrl (parse/validate/resolve) plus the unchanged M3U/XMLTV goldens proving unset = today's output.

Historical Workaround (pre-Dispatcharr)

Before the Dispatcharr funnel, a script downloaded logos from ErsatzTV and base64-uploaded them directly to Jellyfin's /Items/{id}/Images/Primary API, bypassing the M3U logo URLs. Documented in server-management (issue #171). No longer needed for the current pipeline.