Skip to content

feat(epg): support multiple EPG sources #501

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
stackia wants to merge 3 commits into
base: main
Choose a base branch
from
Open

feat(epg): support multiple EPG sources #501

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
273ff4e
feat(epg): support multiple EPG sources
stackia May 24, 2026
36921e3
fix(epg): handle invalid EPG source updates
stackia May 24, 2026
2cf7b99
fix(epg): report synchronous EPG fetch failures
stackia May 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 22 additions & 4 deletions docs/en/guide/m3u-integration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Write M3U content directly in the `[services]` section:
```ini
[services]
# Write M3U content directly, starting with #EXTM3U
#EXTM3U x-tvg-url="https://example.com/epg.xml.gz"
#EXTM3U x-tvg-url="https://example.com/epg.xml.gz,https://example.com/backup-epg.xml.gz"

# Basic channel configuration
#EXTINF:-1 tvg-id="CCTV1" tvg-name="CCTV1" tvg-logo="https://example.com/logo/CCTV1.png" group-title="CCTV",CCTV-1
Expand Down Expand Up @@ -65,12 +65,30 @@ http://192.168.1.1:5140/playlist.m3u

Add this URL to any M3U-compatible IPTV player (such as APTV, TiviMate, etc.) to use it.

## Multiple EPG Sources

`x-tvg-url` or `url-tvg` can contain multiple EPG sources separated by commas. rtp2httpd fetches these EPGs in order and converts them to local URLs in the exported playlist, for example:

```m3u
#EXTM3U x-tvg-url="https://example.com/epg.xml.gz,https://example.com/backup-epg.xml.gz"
```

After conversion, it becomes something like:

```m3u
#EXTM3U x-tvg-url="http://192.168.1.1:5140/epg.xml.gz,http://192.168.1.1:5140/epg/2.xml.gz"
```

The built-in web player matches channels by EPG source order. For the same channel, the first EPG source with matching programme data is used, and later EPG sources only fill channels that were not matched earlier.

To avoid splitting commas inside URLs, rtp2httpd only treats a comma as a new EPG source separator when the text after it (allowing spaces) starts with `http://`, `https://`, or `file://`.

## Conversion Example

### Input M3U

```m3u
#EXTM3U x-tvg-url="https://example.com/epg.xml.gz"
#EXTM3U x-tvg-url="https://example.com/epg.xml.gz,https://example.com/backup-epg.xml.gz"

#EXTINF:-1 tvg-id="CCTV1" tvg-name="CCTV1" tvg-logo="https://example.com/logo/CCTV1.png" group-title="CCTV" catchup="default" catchup-source="rtsp://10.0.0.50:554/catchup?auth=loremipsum&playseek={utc:YmdHMS}-{utcend:YmdHMS}",CCTV-1
rtp://239.253.64.120:5140
Expand All @@ -85,7 +103,7 @@ http://10.0.0.60/live/stream.m3u8
### Output M3U (After Conversion)

```m3u
#EXTM3U x-tvg-url="http://192.168.1.1:5140/epg.xml.gz"
#EXTM3U x-tvg-url="http://192.168.1.1:5140/epg.xml.gz,http://192.168.1.1:5140/epg/2.xml.gz"

#EXTINF:-1 tvg-id="CCTV1" tvg-name="CCTV1" tvg-logo="https://example.com/logo/CCTV1.png" group-title="CCTV" catchup="default" catchup-source="http://192.168.1.1:5140/CCTV-1/catchup?playseek={utc:YmdHMS}-{utcend:YmdHMS}",CCTV-1
http://192.168.1.1:5140/CCTV/CCTV-1
Expand All @@ -98,7 +116,7 @@ http://192.168.1.1:5140/Internal-HLS-Source
```

> [!NOTE]
> - EPG URL has been converted to rtp2httpd proxy address
> - EPG URLs have been converted to rtp2httpd proxy addresses in order
> - CCTV-1 and CCTV-2 URLs have been converted to rtp2httpd proxy addresses
> - CCTV-1's catchup-source has also been converted, preserving dynamic placeholders
> - The HLS source's HTTP URL is also converted to an rtp2httpd proxy address, so internal HLS sources can be exposed through rtp2httpd
Expand Down
2 changes: 2 additions & 0 deletions docs/en/reference/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -245,6 +245,8 @@ ffmpeg-args = -hwaccel none
# Similar to external-m3u functionality, but the M3U content is written directly in the config file
[services]
#EXTM3U x-tvg-url="https://example.com/epg.xml.gz"
# Multiple EPG sources can be separated by commas:
# #EXTM3U x-tvg-url="https://example.com/epg.xml.gz,https://example.com/backup-epg.xml.gz"
#EXTINF:-1 tvg-id="CCTV1" tvg-name="CCTV1" tvg-logo="https://example.com/logo/CCTV1.png" group-title="CCTV" catchup="default" catchup-source="rtsp://10.0.0.50:554/catchup?playseek={utc:YmdHMS}-{utcend:YmdHMS}",CCTV-1
rtp://239.253.64.120:5140
#EXTINF:-1 tvg-id="CCTV2" tvg-name="CCTV2" group-title="CCTV",CCTV-2
Expand Down
26 changes: 22 additions & 4 deletions docs/guide/m3u-integration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ external-m3u-update-interval = 7200
```ini
[services]
# 直接编写 M3U 内容，以 #EXTM3U 开头
#EXTM3U x-tvg-url="https://example.com/epg.xml.gz"
#EXTM3U x-tvg-url="https://example.com/epg.xml.gz,https://example.com/backup-epg.xml.gz"

# 基础频道配置
#EXTINF:-1 tvg-id="CCTV1" tvg-name="CCTV1" tvg-logo="https://example.com/logo/CCTV1.png" group-title="央视",CCTV-1
Expand Down Expand Up @@ -65,12 +65,30 @@ http://192.168.1.1:5140/playlist.m3u

将此 URL 添加到支持 M3U 的 IPTV 播放器（如 APTV、TiviMate 等）即可使用。

## 多个 EPG 源

`x-tvg-url` 或 `url-tvg` 可以配置多个 EPG 源，使用逗号分隔。rtp2httpd 会按顺序抓取这些 EPG，并在导出的播放列表中转换为本机地址，例如：

```m3u
#EXTM3U x-tvg-url="https://example.com/epg.xml.gz,https://example.com/backup-epg.xml.gz"
```

转换后会变成类似：

```m3u
#EXTM3U x-tvg-url="http://192.168.1.1:5140/epg.xml.gz,http://192.168.1.1:5140/epg/2.xml.gz"
```

内置 Web 播放器会按 EPG 源顺序匹配频道。对于同一个频道，第一个匹配到节目数据的 EPG 会被使用，后续 EPG 只会补充前面没有匹配到的频道。

为避免误拆 URL 中的逗号，rtp2httpd 只有在逗号后面（允许有空格）是 `http://`、`https://` 或 `file://` 时才会把它识别为新的 EPG 源。

## 转换示例

### 输入 M3U

```m3u
#EXTM3U x-tvg-url="https://example.com/epg.xml.gz"
#EXTM3U x-tvg-url="https://example.com/epg.xml.gz,https://example.com/backup-epg.xml.gz"

#EXTINF:-1 tvg-id="CCTV1" tvg-name="CCTV1" tvg-logo="https://example.com/logo/CCTV1.png" group-title="央视" catchup="default" catchup-source="rtsp://10.0.0.50:554/catchup?auth=loremipsum&playseek={utc:YmdHMS}-{utcend:YmdHMS}",CCTV-1
rtp://239.253.64.120:5140
Expand All @@ -85,7 +103,7 @@ http://10.0.0.60/live/stream.m3u8
### 输出 M3U（转换后）

```m3u
#EXTM3U x-tvg-url="http://192.168.1.1:5140/epg.xml.gz"
#EXTM3U x-tvg-url="http://192.168.1.1:5140/epg.xml.gz,http://192.168.1.1:5140/epg/2.xml.gz"

#EXTINF:-1 tvg-id="CCTV1" tvg-name="CCTV1" tvg-logo="https://example.com/logo/CCTV1.png" group-title="央视" catchup="default" catchup-source="http://192.168.1.1:5140/CCTV-1/catchup?playseek={utc:YmdHMS}-{utcend:YmdHMS}",CCTV-1
http://192.168.1.1:5140/央视/CCTV-1
Expand All @@ -98,7 +116,7 @@ http://192.168.1.1:5140/内网HLS源
```

> [!NOTE]
> - EPG 的 URL 已转换为 rtp2httpd 代理地址
> - EPG 的 URL 已按顺序转换为 rtp2httpd 代理地址
> - CCTV-1 和 CCTV-2 的 URL 已转换为 rtp2httpd 代理地址
> - CCTV-1 的 catchup-source 也已转换，并保留动态占位符
> - HLS 源的 HTTP URL 也会被转换为 rtp2httpd 代理地址，便于通过 rtp2httpd 为内网 HLS 源提供外网访问
Expand Down
2 changes: 2 additions & 0 deletions docs/reference/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -245,6 +245,8 @@ ffmpeg-args = -hwaccel none
# 和 external-m3u 功能类似，只是直接把 m3u 写在了配置文件内
[services]
#EXTM3U x-tvg-url="https://example.com/epg.xml.gz"
# 多个 EPG 源可用逗号分隔：
# #EXTM3U x-tvg-url="https://example.com/epg.xml.gz,https://example.com/backup-epg.xml.gz"
#EXTINF:-1 tvg-id="CCTV1" tvg-name="CCTV1" tvg-logo="https://example.com/logo/CCTV1.png" group-title="央视" catchup="default" catchup-source="rtsp://10.0.0.50:554/catchup?playseek={utc:YmdHMS}-{utcend:YmdHMS}",CCTV-1
rtp://239.253.64.120:5140
#EXTINF:-1 tvg-id="CCTV2" tvg-name="CCTV2" group-title="央视",CCTV-2
Expand Down
Loading
Loading