[Emerald-Railroad]

External XMLTV EPG Support

Jellyfin.Xtream can optionally use an external XMLTV file for Live TV guide data while continuing to use Xtream for channel discovery and stream playback.

This can be useful when an Xtream provider has missing or incomplete EPG information, or when a separate XMLTV source provides richer metadata such as program descriptions.

EPG Modes

Three EPG modes are available:

• Xtream EPG — Uses the EPG supplied by the Xtream provider. This is the default behavior.
• Custom XMLTV — Uses the configured XMLTV file for mapped channels instead of the Xtream EPG.
• Custom XMLTV + Xtream Fallback — Uses XMLTV for mapped channels and falls back to the Xtream EPG when no XMLTV mapping is configured.

The XMLTV setting affects guide information only. Channel playback continues to use the existing Xtream stream.

Configure an XMLTV File

1. Open the Jellyfin Dashboard.
2. Go to Plugins → Jellyfin Xtream → TV Overrides.
3. Under Custom EPG, select the desired EPG mode.
4. Enter the full local path to the XMLTV file on the Jellyfin server.

Example:

D:\EPG\guide.xmltv

5. Save the plugin configuration.
6. Reopen the TV Overrides page.

The plugin will read the <channel> entries contained in the XMLTV file.

Map Xtream Channels to XMLTV Channels

Each Xtream channel has an optional Custom EPG ID field.

Select or enter the XMLTV channel ID that should provide guide information for that Xtream channel.

For example:

Xtream Channel:
CBS

Custom EPG ID:
EPG123.10367.schedulesdirect.org

The XMLTV file would contain a corresponding channel entry similar to:

<channel id="EPG123.10367.schedulesdirect.org">
    <display-name>CBS</display-name>
</channel>

Program entries using that channel ID will then be supplied to Jellyfin for the mapped Xtream channel.

Refresh the Guide

After configuring channel mappings:

1. Open Dashboard → Live TV.
2. Run Refresh Guide Data.

Jellyfin should then populate the guide using the configured XMLTV data.

Depending on the XMLTV source, guide information may include:

• Program titles
• Program descriptions
• Episode titles
• Categories
• Season and episode numbers
• Start and end times
• Program images

Building From Source

Jellyfin.Xtream currently requires the .NET 9 SDK.

Clone the repository and run:

dotnet restore
dotnet build Jellyfin.Xtream.sln -c Release

The resulting plugin DLL will normally be located at:

Jellyfin.Xtream\bin\Release\net9.0\Jellyfin.Xtream.dll

Installing a Custom Build

Before replacing an existing Jellyfin.Xtream installation, stop the Jellyfin server and back up the currently installed Jellyfin.Xtream.dll.

Replace the existing DLL with the newly compiled version, then restart Jellyfin.

If the custom build needs to be removed, stop Jellyfin and restore the original DLL.

External XMLTV changes guide-data retrieval only. Existing Xtream stream playback remains unchanged.