--- url: /guide/url-formats.md --- # URL 格式说明 rtp2httpd 支持多种流媒体协议，通过不同的 URL 前缀进行区分。 基本格式：`http://服务器地址:端口/路径[?参数1=值1][&参数2=值2][&参数3=值3]` 如果配置了 `app-path-prefix`，所有路径都需要加上此前缀。例如 `app-path-prefix = /app/rtp2httpd` 时，`/rtp/...`、`/status`、`/player`、`/playlist.m3u` 等路径分别变为 `/app/rtp2httpd/rtp/...`、`/app/rtp2httpd/status`、`/app/rtp2httpd/player`、`/app/rtp2httpd/playlist.m3u`。 当配置了 `r2h-token（HTTP 请求认证令牌）` 时，所有 URL 都需要额外带上参数 `r2h-token=` 才能访问。 > \[!TIP] > 除了 URL 参数，也支持通过 Cookie 或者 User Agent 来传递 `r2h-token`。例如 `Cookie: r2h-token=xxx` 或 `User-Agent: R2HTOKEN/xxx`。 ## 组播 RTP 转 HTTP 单播流 ```url http://服务器地址:端口/rtp/组播地址:端口[?fcc=FCC服务器:端口][&fcc-type=协议类型][&fec=FEC端口] ``` **示例**： ```url http://192.168.1.1:5140/rtp/239.253.64.120:5140 http://192.168.1.1:5140/rtp/239.253.64.120:5140?fcc=10.255.14.152:15970 http://192.168.1.1:5140/rtp/239.253.64.120:5140?fcc=10.255.14.152:8027&fcc-type=huawei http://192.168.1.1:5140/rtp/239.81.0.195:4056?fec=4055 http://192.168.1.1:5140/rtp/239.253.64.120:5140?fcc=10.255.14.152:15970&r2h-ifname=eth0&r2h-ifname-fcc=eth1 ``` ### 参数说明 * **组播地址**：IPTV 运营商提供的组播地址 * **端口**：组播端口号 * **fcc**（可选）：FCC 快速换台服务器地址，格式为 `IP:端口` * **fcc-type**（可选）：FCC 协议类型，可选值： * `telecom`：电信/中兴/烽火 FCC 协议（默认） * `huawei`：华为 FCC 协议 * **fec**（可选）：FEC 前向纠错端口号，用于接收 FEC 冗余数据包来恢复丢包 * **r2h-ifname**（可选）：指定使用的上游网络接口（覆盖全局配置） * **r2h-ifname-fcc**（可选）：指定 FCC 使用的上游网络接口（覆盖全局配置） * **r2h-filename**（可选）：下载文件名，详见 [下载文件名](#下载文件名) ### 使用场景 * 将运营商 IPTV 组播流转换为 HTTP 单播流 * 在局域网内多设备共享 IPTV 流 * 配合 FCC 实现毫秒级换台 * 配合 FEC 实现丢包恢复，提高播放稳定性 ## RTSP 转 HTTP ```url http://服务器地址:端口/rtsp/RTSP服务器:端口/路径[?参数] ``` **示例**： ```url # 直播流 http://192.168.1.1:5140/rtsp/iptv.example.com:554/channel1 # 时移回看（使用 playseek 参数） http://192.168.1.1:5140/rtsp/iptv.example.com:554/channel1?playseek=20240101120000-20240101130000 # 时移回看（使用 tvdr 参数） http://192.168.1.1:5140/rtsp/iptv.example.com:554/channel1?tvdr=20240101120000GMT-20240101130000GMT # 自定义时移参数名 + 起止时间独立偏移 http://192.168.1.1:5140/rtsp/iptv.example.com:554/channel1?seek=20240101120000-20240101130000&r2h-seek-name=seek&r2h-seek-offset=12,-12 # 显式开启 RTSP 近实时优化（参见 r2h-seek-mode 文档） http://192.168.1.1:5140/rtsp/iptv.example.com:554/channel1?playseek=20240101120000&r2h-seek-mode=range(UTC%2B8/3600) # 指定上游网络接口 http://192.168.1.1:5140/rtsp/iptv.example.com:554/channel1?r2h-ifname=eth0 ``` ### 使用场景 * 将 IPTV RTSP 单播流转换为 HTTP 流 * 实现 RTSP 时移回看功能 > \[!IMPORTANT] > rtp2httpd 的 RTSP 支持仅适用于承载单路 MPEG-TS 流的场景（即 IPTV 单播/时移回看），不支持监控摄像头等其他 RTSP 用途。 ### 常见问题：时移回看时，实际回看时间比节目单早了/晚了 8 小时 这是由于时区未能匹配。需要做时区转换。你可以尝试以下几种方式。 * 修改播放器 User Agent 设置，加上 `TZ/UTC+8` 或 `TZ/UTC-8`。例如 `AptvPlayer/1.3.3 TZ/UTC+8`。 * 修改播放链接，加上参数 `&r2h-seek-offset=28800` 或 `&r2h-seek-offset=-28800`。如果只需要调整起始/结束边界，可以使用 `&r2h-seek-offset=12,-12` 这样的形式分别偏移起始和结束时间 关于时移回看的参数处理（时区、偏移），详见 [时间处理说明](./time-processing.md)。 ## 上游流 Metadata 响应头 RTSP、普通组播和 FCC 流会在 HTTP Headers 带上以下 `R2H-*` Metadata： | 响应头 | 含义 | | --- | --- | | `R2H-Upstream-Protocol` | 上游类型：`rtsp` 或 `multicast`。FCC 流也属于 `multicast`。 | | `R2H-Upstream-Transport` | RTSP 实际协商的传输方式：`tcp-interleaved` 或 `udp`。 | | `R2H-Upstream-Payload` | 已确认的 MPEG-TS 封装：`mp2t-rtp` 或 `mp2t-direct`。 | | `R2H-Playback-Scale` | RTSP `PLAY` 响应明确确认的播放速率。 | | `R2H-Playback-Range` | RTSP `PLAY` 响应明确确认的播放范围。 | | `R2H-Media-Duration` | SDP 有限 `npt` 范围的时长，单位为秒。 | | `R2H-FCC-Type` | 已配置的 FCC 协议：`telecom` 或 `huawei`。 | | `R2H-FCC-Status` | 从 FCC 单播起播为 `active`；从组播起播为 `fallback`。 | ## 下载文件名 组播 RTP 和 RTSP 的 MPEG-TS 响应支持 `r2h-filename` 查询参数。参数非空时，rtp2httpd 会输出 `Content-Disposition: attachment`，让浏览器按指定文件名保存下载。服务端会去掉路径分隔符和控制字符，并在缺少后缀时补上 `.ts`。 该参数只作用于 rtp2httpd 自身，不会转发给上游。HTTP/HLS 反向代理会在转发前剥离该参数，也不会设置 `Content-Disposition`。 ```url http://192.168.1.1:5140/rtp/239.253.64.120:5140?r2h-filename=CCTV-1.ts http://192.168.1.1:5140/rtsp/iptv.example.com:554/channel1?playseek=20240101120000-20240101130000&r2h-filename=CCTV-1_新闻联播_20240101-120000_20240101-130000.ts ``` 内置 Web 播放器复制媒体直链时会自动带上该参数。 ## HTTP 反向代理 ```url http://服务器地址:端口/http/上游服务器[:端口]/路径[?参数] ``` **示例**： ```url # 代理 HLS 流（指定端口） http://192.168.1.1:5140/http/upstream.example.com:8080/live/stream.m3u8 # 代理 HTTP 请求（省略端口，默认 80） http://192.168.1.1:5140/http/api.example.com/video?auth=xxx&quality=hd ``` ### 参数说明 * **上游服务器**：目标 HTTP 服务器地址 * **端口**（可选）：目标服务器端口，默认 80 * **路径**：请求路径，包括查询参数 ### 使用场景 * 代理上游 HLS/DASH 流媒体，统一认证和访问控制 * 为不支持直接访问的 IPTV 内网服务提供 HTTP 反向代理 ### 时移回看支持 HTTP 代理同样支持 `r2h-seek-name`、`r2h-seek-offset` 参数和 User-Agent 时区转换，处理方式与 RTSP 代理一致。 ```url # 自动识别 playseek 参数并进行时区转换 http://192.168.1.1:5140/http/iptv.example.com/channel1?playseek=20240101120000-20240101130000 # 使用自定义参数名 + 时间偏移 http://192.168.1.1:5140/http/iptv.example.com/channel1?catchup=20240101120000&r2h-seek-name=catchup&r2h-seek-offset=3600 # 指定上游网络接口 http://192.168.1.1:5140/http/iptv.example.com/channel1?r2h-ifname=eth0 ``` 详见 [时间处理说明](./time-processing.md)。 ### 上游 30x 重定向 当上游返回 `301` / `302` / `303` / `307` / `308` 时，rtp2httpd 会按协议改写 `Location`，让播放器继续走本实例： | 上游 `Location` | 转发给客户端 | | --- | --- | | `http://iptv.example.com:8080/path` | `/http/iptv.example.com:8080/path` | | `rtsp://iptv.example.com:554/path?auth=...` | `/rtsp/iptv.example.com:554/path?auth=...` | | `rtp://239.0.0.1:1234` | `/rtp/239.0.0.1:1234` | | `udp://239.0.0.1:1234` | `/udp/239.0.0.1:1234` | | `/rtsp/iptv.example.com:554/path`（根路径相对地址） | 原样转发 | | `https://...` 或其他未支持的协议 | 原样转发 | 改写范围与 M3U 可识别的 URL 格式一致：`http://`、`rtsp://`、`rtp://`、`udp://`。这适用于 `catchup-source` 先指向一个 HTTP 鉴权/换链服务，再由该服务 302 到真实播放地址的场景。如果配置了 `app-path-prefix`，改写后的地址会带上此前缀。 ### 注意事项 * 仅支持 HTTP 上游（不支持 HTTPS） * 可通过 `upstream-interface-http` 配置指定上游网络接口，也可以通过 `r2h-ifname` 参数在每次请求中指定 * 如果被代理的目标 URL 是 m3u 类型，其中所有 `http://` URL 会被自动改写为经过 rtp2httpd 代理后的地址（为了保证 HLS 流能被正确代理） ## IPv6 支持 所有 URL 中的主机地址均支持 IPv6。在 URL 中书写 IPv6 字面量时，需要使用方括号 `[]` 包裹： ```url # HTTP 反向代理（IPv6 上游） http://192.168.1.1:5140/http/[2001:db8::1]:8080/live/stream.m3u8 # RTSP 转 HTTP（IPv6 上游） http://192.168.1.1:5140/rtsp/[2001:db8::1]:554/channel1 # RTSP URL 带认证信息 rtsp://user:pass@[2001:db8::1]:554/live # IPv6 组播（需要系统和网络接口支持 IPv6 组播） http://192.168.1.1:5140/rtp/[ff3e::1]:1234 ``` ### 行为说明 * **域名自动双栈解析**：上游地址为域名时，按系统解析顺序依次尝试 IPv6 / IPv4 地址，连接失败时自动回退到下一个地址 * **Host 校验**：配置了 `hostname` 时，请求头中的 `[IPv6]:端口` 格式 Host 也能正确通过校验 * **服务监听**：`[bind]` 配置节和 `--listen` 参数均支持 IPv6 地址（如 `::1 5140` 或 `-l [::1]:5140`） ### 限制 * **`mcast-rejoin-interval` 不支持 IPv6** ## M3U 播放列表访问 ```url http://服务器地址:端口/playlist.m3u ``` **示例**： ```url http://192.168.1.1:5140/playlist.m3u ``` 获取转换后的 M3U 播放列表，包含所有通过配置文件和外部 M3U 定义的频道，并将 URL 转换成 rtp2httpd 监听的地址和端口，并使用频道名替换原始 IP、查询参数、认证信息。 ### 使用场景 * 一键导入别人维护的 m3u 频道源 * 隐藏频道源 IP、认证信息 * 自动更新频道信息 详见 [M3U 播放列表集成](./m3u-integration.md)。 ## 内置 Web 播放器 ```url http://服务器地址:端口/player ``` **示例**： ```url http://192.168.1.1:5140/player ``` 访问[内置 Web 播放器](./web-player.md)，可以在网页端播放已配置的 M3U 频道列表。 播放器页面路径可以通过配置项 `player-page-path` 自定义。设置为 `/` 可以实现不带任何路径直接访问。 ## 状态页面 ```url http://服务器地址:端口/status ``` **示例**： ```url http://192.168.1.1:5140/status ``` 访问 Web 状态页面，查看： * 实时客户端连接统计 * 每个连接的 IP、状态、带宽使用、传输数据量 * 系统日志查看 * 远程管理功能（强制断开连接、调整日志级别等） * 服务控制：重载配置、重启工作进程 强制断开某个客户端时，rtp2httpd 会立即关闭该连接，并在随后 5 秒内拒绝该客户端 IP 的所有新连接（返回 `HTTP 429 Too Many Requests`，并带有 `Retry-After`），避免播放器立刻重连。 **服务控制**（等效于向 supervisor 发送 Unix 信号）： | 操作 | 等效信号 | API | | --- | --- | --- | | 重载配置 | `SIGHUP` | `POST /status/api/reload-config` | | 重启工作进程 | `SIGUSR1` | `POST /status/api/restart-workers` | 将 `/status` 替换为实际的 `status-page-path` 配置值。详见 [配置参数详解 — 运行时配置管理](../reference/configuration.md#运行时配置管理)。 状态页面路径可以通过配置项 `status-page-path` 自定义。设置为 `/` 可以实现不带任何路径直接访问。 ## udpxy 兼容模式 rtp2httpd 完全兼容 udpxy URL 格式，可以无缝替换 udpxy / msd\_lite 等组播转单播服务。 ### udpxy 格式 ```url http://服务器地址:端口/udp/组播地址:端口 http://服务器地址:端口/rtp/组播地址:端口 ``` **示例**： ```url http://192.168.1.1:5140/udp/239.253.64.120:5140 http://192.168.1.1:5140/rtp/239.253.64.120:5140 ``` udpxy 兼容模式默认启用，可以通过配置参数 `udpxy = no` 禁用。禁用后仅支持通过 m3u 提供服务。 > \[!TIP] > 使用 `/udp/` 和 `/rtp/` 没有任何差别，选择任意一种即可。 ## 视频快照 在任意流媒体 URL 后添加 `snapshot=1` 参数，或在 HTTP 请求头中添加 `Accept: image/jpeg` 或 `X-Request-Snapshot: 1`，即可获取视频流的 JPEG 快照。 **示例**： ```url # 方式 1：URL 参数 http://192.168.1.1:5140/rtp/239.253.64.120:5140?snapshot=1 # 方式 2：HTTP 请求头 curl -H "Accept: image/jpeg" http://192.168.1.1:5140/rtp/239.253.64.120:5140 # 方式 3：自定义请求头 curl -H "X-Request-Snapshot: 1" http://192.168.1.1:5140/rtp/239.253.64.120:5140 ``` 详见 [视频快照配置](./video-snapshot.md)。 ## 相关文档 * [M3U 播放列表集成](./m3u-integration.md)：播放列表配置 * [FCC 快速换台配置](./fcc-setup.md)：启用毫秒级换台 * [视频快照配置](./video-snapshot.md)：频道预览图功能 * [配置参数详解](../reference/configuration.md)：查看完整配置选项