diff --git a/README.md b/README.md index 0e5646a..ff1c497 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ lalmax.conf.json 配置主要由 2 部分组成 (1) lalmax: lalmax 扩展能力配置，例如 SRT、RTC、HTTP-FMP4、GB28181 等，具体配置说明见[config.md](./document/config.md) -(2) lal: lal 原生配置，例如 RTMP、RTSP、HTTP-FLV、HLS-TS、录制、鉴权等，具体配置说明见[lal配置](https://pengrl.com/lal/#/ConfigBrief) +(2) lal: lal 原生配置，例如 RTMP、RTSP、HTTP-FLV、HLS-TS、录制、鉴权等，具体配置说明见[lal_config.md](./document/lal_config.md)，原生 HTTP API 见[lal_api.md](./document/lal_api.md) 旧版平铺配置和 lal_config_path 仍兼容，但推荐使用 lalmax/lal 两个顶层标签维护单个配置文件。 @@ -40,9 +40,7 @@ docker run -it -p 1935:1935 -p 8080:8080 -p 4433:4433 -p 5544:5544 -p 8083:8083 (5) GB28181 -具体的推流url地址（除了srt/whip） - -https://pengrl.com/lal/#/streamurllist +具体的推流 URL 地址见[流地址说明](./document/stream_url.md) ## 拉流 (1) RTSP @@ -64,7 +62,7 @@ https://pengrl.com/lal/#/streamurllist (9) HLS(S)-FMP4/LLHLS -具体的拉流url地址见https://pengrl.com/lal/#/streamurllist（除了srt/whep） +具体的拉流 URL 地址见[流地址说明](./document/stream_url.md) ## [SRT](./document/srt.md) （1）使用gosrt库 diff --git a/conf/lalmax.conf.json b/conf/lalmax.conf.json index f9ca88d..a348ea8 100644 --- a/conf/lalmax.conf.json +++ b/conf/lalmax.conf.json @@ -45,7 +45,7 @@ } }, "lal": { - "# doc of config": "https://pengrl.com/lal/#/ConfigBrief", + "# doc of config": "./document/lal_config.md", "conf_version": "v0.4.1", "rtmp": { "enable": true, diff --git a/document/lal_api.md b/document/lal_api.md new file mode 100644 index 0000000..90b12d9 --- /dev/null +++ b/document/lal_api.md @@ -0,0 +1,330 @@ +# lal 原生 HTTP API + +本文档说明 `conf/lalmax.conf.json` 中 `lal.http_api` 暴露的 lal 原生 HTTP API。默认配置为： + +```json +{ + "http_api": { + "enable": true, + "addr": ":8083" + } +} +``` + +默认访问地址： + +```text +http://127.0.0.1:8083 +``` + +lalmax 自身也在 `lalmax.http_config.http_listen_addr` 上提供 `/api/stat` 和 `/api/ctrl` 兼容接口，并会补充 lalmax hook 订阅信息。只需要管理 lal 原生流状态时，可以直接使用本文档中的 lal 原生 API。 + +## 通用响应 + +所有 API 都返回 JSON，基础结构如下： + +```json +{ + "error_code": 0, + "desp": "succ", + "data": {} +} +``` + +常见 `error_code`： + +| error_code | desp | 说明 | +| --- | --- | --- | +| 0 | succ | 调用成功 | +| 404 | page not found | API 路径不存在 | +| 1001 | group not found | 流分组不存在 | +| 1002 | param missing | 必填参数缺失 | +| 1003 | session not found | 会话不存在 | +| 2001 | 失败原因见 desp | `start_relay_pull` 失败 | +| 2002 | 失败原因见 desp | `start_rtp_pub` 监听端口失败 | + +## Web UI + +### `GET /lal.html` + +返回 lal 原生 Web UI 页面。 + +```bash +curl http://127.0.0.1:8083/lal.html +``` + +## 查询接口 + +### `GET /api/stat/lal_info` + +查询 lal 服务信息。 + +```bash +curl http://127.0.0.1:8083/api/stat/lal_info +``` + +响应示例： + +```json +{ + "error_code": 0, + "desp": "succ", + "data": { + "server_id": "1", + "bin_info": "GitTag=unknown. GitCommitLog=unknown.", + "lal_version": "v0.37.4", + "api_version": "v0.1.2", + "notify_version": "v0.0.4", + "WebUiVersion": "", + "start_time": "2026-04-22 10:00:00.000" + } +} +``` + +### `GET /api/stat/all_group` + +查询所有流分组。 + +```bash +curl http://127.0.0.1:8083/api/stat/all_group +``` + +响应中的 `data.groups` 是数组，每个元素结构与 `/api/stat/group` 的 `data` 相同。 + +### `GET /api/stat/group` + +查询指定流分组。 + +```bash +curl "http://127.0.0.1:8083/api/stat/group?stream_name=test110" +``` + +请求参数： + +| 参数 | 必填 | 说明 | +| --- | --- | --- | +| `stream_name` | 是 | 流名称 | + +响应示例： + +```json +{ + "error_code": 0, + "desp": "succ", + "data": { + "stream_name": "test110", + "app_name": "live", + "audio_codec": "AAC", + "video_codec": "H264", + "video_width": 1920, + "video_height": 1080, + "pub": { + "session_id": "RTMPPUBSUB1", + "protocol": "RTMP", + "base_type": "PUB", + "remote_addr": "127.0.0.1:50000", + "start_time": "2026-04-22 10:00:00", + "read_bytes_sum": 1024, + "wrote_bytes_sum": 0, + "bitrate_kbits": 800, + "read_bitrate_kbits": 800, + "write_bitrate_kbits": 0 + }, + "subs": [], + "pull": { + "session_id": "", + "protocol": "", + "base_type": "" + }, + "in_frame_per_sec": [] + } +} +``` + +字段说明： + +| 字段 | 说明 | +| --- | --- | +| `stream_name` | 流名称 | +| `app_name` | 应用名或路径前缀 | +| `audio_codec` | 音频编码，例如 `AAC`、`PCMA`、`PCMU`、`OPUS` | +| `video_codec` | 视频编码，例如 `H264`、`H265` | +| `pub` | 推流会话统计 | +| `subs` | 拉流会话统计数组 | +| `pull` | 回源拉流会话统计 | +| `in_frame_per_sec` | 输入帧率采样 | + +会话统计字段： + +| 字段 | 说明 | +| --- | --- | +| `session_id` | 会话唯一标识 | +| `protocol` | 协议，例如 `RTMP`、`RTSP`、`FLV`、`TS` | +| `base_type` | 会话类型，常见为 `PUB`、`SUB`、`PULL` | +| `remote_addr` | 对端地址 | +| `start_time` | 会话开始时间 | +| `read_bytes_sum` | 累计读取字节数 | +| `wrote_bytes_sum` | 累计写出字节数 | +| `bitrate_kbits` | 统计周期内码率，单位 kbit/s | +| `read_bitrate_kbits` | 统计周期内读取码率，单位 kbit/s | +| `write_bitrate_kbits` | 统计周期内写出码率，单位 kbit/s | + +## 控制接口 + +### `POST /api/ctrl/start_relay_pull` + +让 lal 主动从远端拉流到本地。 + +```bash +curl -H "Content-Type: application/json" \ + -X POST \ + -d '{"url":"rtmp://127.0.0.1/live/test110","pull_retry_num":0}' \ + http://127.0.0.1:8083/api/ctrl/start_relay_pull +``` + +请求参数： + +| 参数 | 必填 | 默认值 | 说明 | +| --- | --- | --- | --- | +| `url` | 是 | 无 | 远端拉流地址，支持 RTMP、RTSP | +| `stream_name` | 否 | 从 `url` 解析 | 本地流名称 | +| `pull_timeout_ms` | 否 | `10000` | 建立拉流连接的超时时间 | +| `pull_retry_num` | 否 | `0` | 重试次数，`-1` 表示一直重试，`0` 表示不重试 | +| `auto_stop_pull_after_no_out_ms` | 否 | `-1` | 没有输出订阅时自动停止拉流，`-1` 表示关闭 | +| `rtsp_mode` | 否 | `0` | RTSP 拉流模式，`0` 为 TCP，`1` 为 UDP | +| `debug_dump_packet` | 否 | 空字符串 | 调试用抓包文件路径，生产环境建议为空 | + +响应示例： + +```json +{ + "error_code": 0, + "desp": "succ", + "data": { + "stream_name": "test110", + "session_id": "RTMPPULL1" + } +} +``` + +注意：返回成功只表示命令已被接受，不保证远端流已经拉取成功。实际状态可通过 `/api/stat/group` 或 HTTP Notify 判断。 + +### `GET /api/ctrl/stop_relay_pull` + +停止指定流的回源拉流。 + +```bash +curl "http://127.0.0.1:8083/api/ctrl/stop_relay_pull?stream_name=test110" +``` + +请求参数： + +| 参数 | 必填 | 说明 | +| --- | --- | --- | +| `stream_name` | 是 | 需要停止回源拉流的流名称 | + +响应示例： + +```json +{ + "error_code": 0, + "desp": "succ", + "data": { + "session_id": "RTMPPULL1" + } +} +``` + +### `POST /api/ctrl/kick_session` + +关闭指定会话。会话可以是推流、拉流或回源拉流。 + +```bash +curl -H "Content-Type: application/json" \ + -X POST \ + -d '{"stream_name":"test110","session_id":"FLVSUB1"}' \ + http://127.0.0.1:8083/api/ctrl/kick_session +``` + +请求参数： + +| 参数 | 必填 | 说明 | +| --- | --- | --- | +| `stream_name` | 是 | 流名称 | +| `session_id` | 是 | 会话唯一标识，可从 `/api/stat/group` 获取 | + +响应示例： + +```json +{ + "error_code": 0, + "desp": "succ" +} +``` + +### `POST /api/ctrl/start_rtp_pub` + +打开 RTP/PS 接收端口。常用于 GB28181 或外部系统向 lal 投递 RTP/PS 流。 + +```bash +curl -H "Content-Type: application/json" \ + -X POST \ + -d '{"stream_name":"test110","port":0,"timeout_ms":60000,"is_tcp_flag":0}' \ + http://127.0.0.1:8083/api/ctrl/start_rtp_pub +``` + +请求参数： + +| 参数 | 必填 | 默认值 | 说明 | +| --- | --- | --- | --- | +| `stream_name` | 是 | 无 | 绑定到 lal 内部的流名称 | +| `port` | 否 | `0` | 接收端口，`0` 表示自动分配 | +| `timeout_ms` | 否 | `60000` | 超时时间，`0` 表示不超时 | +| `is_tcp_flag` | 否 | `0` | `0` 表示 UDP，`1` 表示 TCP | +| `debug_dump_packet` | 否 | 空字符串 | 调试用抓包文件路径，生产环境建议为空 | + +响应示例： + +```json +{ + "error_code": 0, + "desp": "succ", + "data": { + "stream_name": "test110", + "session_id": "PSSUB1", + "port": 20000 + } +} +``` + +## lalmax 兼容 API + +lalmax 在自己的 HTTP 服务上也提供兼容接口，默认地址来自 `lalmax.http_config.http_listen_addr`： + +```text +http://127.0.0.1:1290/api/stat/group +http://127.0.0.1:1290/api/stat/all_group +http://127.0.0.1:1290/api/stat/lal_info +http://127.0.0.1:1290/api/ctrl/start_relay_pull +http://127.0.0.1:1290/api/ctrl/stop_relay_pull +http://127.0.0.1:1290/api/ctrl/kick_session +http://127.0.0.1:1290/api/ctrl/start_rtp_pub +``` + +lalmax 兼容 API 的请求和响应结构与 lal 原生 API 基本一致，但会在统计结果中补充 lalmax hook 订阅者信息。控制类接口还可能受 `lalmax.http_config.ctrl_auth_whitelist` 限制。 + +## 鉴权说明 + +lal 原生 HTTP API 本身不使用 `simple_auth` 中的流鉴权配置。`simple_auth` 主要控制 RTMP、RTSP、HTTP-FLV、HTTP-TS、HLS 等流访问鉴权。 + +如果启用流鉴权，请在流地址参数中携带： + +```text +lal_secret= +``` + +如果配置了 `dangerous_lal_secret`，也可以直接传： + +```text +lal_secret= +``` diff --git a/document/lal_config.md b/document/lal_config.md new file mode 100644 index 0000000..db721d1 --- /dev/null +++ b/document/lal_config.md @@ -0,0 +1,136 @@ +# lal 原生配置说明 + +本文档说明 `conf/lalmax.conf.json` 中 `lal` 配置段的常用字段。`lal` 配置段会直接传给 lal 原生服务，用于 RTMP、RTSP、HTTP-FLV、HLS-TS、HTTP-TS、录制、鉴权和原生 HTTP API。 + +## rtmp + +- `enable`: 是否启用 RTMP 服务。 +- `addr`: RTMP 监听地址，例如 `:1935`。 +- `rtmps_enable`: 是否启用 RTMPS。 +- `rtmps_addr`: RTMPS 监听地址，例如 `:4935`。 +- `rtmps_cert_file`: RTMPS 证书文件路径。 +- `rtmps_key_file`: RTMPS 私钥文件路径。 +- `gop_num`: RTMP 拉流 GOP 缓存数量。 +- `single_gop_max_frame_num`: 单个 GOP 最大缓存帧数，`0` 表示不限制。 +- `merge_write_size`: 合并写大小，`0` 表示关闭合并写。 + +## in_session + +- `add_dummy_audio_enable`: 没有音频时是否补静音音频。 +- `add_dummy_audio_wait_audio_ms`: 等待真实音频的时间，超过后才补静音音频。 + +## default_http + +HTTP 类协议的默认监听配置。HTTP-FLV、HTTP-TS、HLS-TS 未单独配置监听地址时，会使用这里的地址。 + +- `http_listen_addr`: 默认 HTTP 监听地址，例如 `:8080`。 +- `https_listen_addr`: 默认 HTTPS 监听地址，例如 `:4433`。 +- `https_cert_file`: HTTPS 证书文件路径。 +- `https_key_file`: HTTPS 私钥文件路径。 + +## httpflv + +- `enable`: 是否启用 HTTP-FLV。 +- `enable_https`: 是否启用 HTTPS HTTP-FLV。 +- `url_pattern`: URL 路径匹配前缀。示例配置为 `/`，因此 `/live/test110.flv` 可用。 +- `gop_num`: HTTP-FLV GOP 缓存数量。 +- `single_gop_max_frame_num`: 单个 GOP 最大缓存帧数。 + +## hls + +这里是 lal 原生 HLS-TS 配置，不是 lalmax 的 HLS-FMP4/LLHLS 配置。 + +- `enable`: 是否启用 HLS-TS。 +- `enable_https`: 是否启用 HTTPS HLS-TS。 +- `url_pattern`: HLS-TS URL 路径前缀，常用 `/hls/`。 +- `out_path`: HLS-TS 文件输出目录。 +- `fragment_duration_ms`: 单个 TS 分片时长。 +- `fragment_num`: m3u8 中保留的分片数量。 +- `delete_threshold`: 清理旧分片的阈值。 +- `cleanup_mode`: 清理模式。 +- `use_memory_as_disk_flag`: 是否使用内存模拟磁盘。 +- `sub_session_timeout_ms`: HLS 拉流会话超时时间。 +- `sub_session_hash_key`: HLS 会话哈希 key。 + +## httpts + +- `enable`: 是否启用 HTTP-TS。 +- `enable_https`: 是否启用 HTTPS HTTP-TS。 +- `url_pattern`: URL 路径匹配前缀。示例配置为 `/`，因此 `/live/test110.ts` 可用。 +- `gop_num`: HTTP-TS GOP 缓存数量。 +- `single_gop_max_frame_num`: 单个 GOP 最大缓存帧数。 + +## rtsp + +- `enable`: 是否启用 RTSP。 +- `addr`: RTSP 监听地址，例如 `:5544`。 +- `rtsps_enable`: 是否启用 RTSPS。 +- `rtsps_addr`: RTSPS 监听地址，例如 `:5322`。 +- `rtsps_cert_file`: RTSPS 证书文件路径。 +- `rtsps_key_file`: RTSPS 私钥文件路径。 +- `out_wait_key_frame_flag`: RTSP 拉流是否等待关键帧后再输出。 +- `auth_enable`: 是否启用 RTSP 鉴权。 +- `auth_method`: 鉴权方式。 +- `username`: RTSP 鉴权用户名。 +- `password`: RTSP 鉴权密码。 + +## record + +- `enable_flv`: 是否启用 FLV 录制。 +- `flv_out_path`: FLV 录制输出目录。 +- `enable_mpegts`: 是否启用 MPEG-TS 录制。 +- `mpegts_out_path`: MPEG-TS 录制输出目录。 + +## relay_push + +- `enable`: 是否启用静态转推。 +- `addr_list`: 转推目标地址列表。 + +## static_relay_pull + +- `enable`: 是否启用静态回源拉流。 +- `addr`: 静态回源地址。 + +## http_api + +- `enable`: 是否启用 lal 原生 HTTP API。 +- `addr`: lal 原生 HTTP API 监听地址，例如 `:8083`。 + +接口说明见 [lal_api.md](./lal_api.md)。 + +## simple_auth + +简单鉴权配置，鉴权值通常按 `key + streamName` 计算。 + +- `key`: 鉴权 key。 +- `dangerous_lal_secret`: 管理类接口使用的 secret。 +- `pub_rtmp_enable`: 是否启用 RTMP 推流鉴权。 +- `sub_rtmp_enable`: 是否启用 RTMP 拉流鉴权。 +- `sub_httpflv_enable`: 是否启用 HTTP-FLV 拉流鉴权。 +- `sub_httpts_enable`: 是否启用 HTTP-TS 拉流鉴权。 +- `pub_rtsp_enable`: 是否启用 RTSP 推流鉴权。 +- `sub_rtsp_enable`: 是否启用 RTSP 拉流鉴权。 +- `hls_m3u8_enable`: 是否启用 HLS m3u8 鉴权。 + +## pprof + +- `enable`: 是否启用 pprof。 +- `addr`: pprof 监听地址，例如 `:8084`。 + +## log + +- `level`: 日志级别。 +- `filename`: 日志文件路径。 +- `is_to_stdout`: 是否输出到标准输出。 +- `is_rotate_daily`: 是否按天切分日志。 +- `short_file_flag`: 是否打印短文件名。 +- `timestamp_flag`: 是否打印时间戳。 +- `timestamp_with_ms_flag`: 时间戳是否包含毫秒。 +- `level_flag`: 是否打印日志级别。 +- `assert_behavior`: 断言行为。 + +## debug + +- `log_group_interval_sec`: group 状态日志输出间隔。 +- `log_group_max_group_num`: 单次最多输出的 group 数量。 +- `log_group_max_sub_num_per_group`: 单个 group 最多输出的订阅者数量。 diff --git a/document/stream_url.md b/document/stream_url.md new file mode 100644 index 0000000..1f3d866 --- /dev/null +++ b/document/stream_url.md @@ -0,0 +1,175 @@ +# 流地址说明 + +本文档使用 `conf/lalmax.conf.json` 的默认配置举例，默认流名为 `test110`。 + +## 基本规则 + +- `lal` 原生能力使用 `lal` 配置段中的端口，例如 RTMP、RTSP、HTTP-FLV、HLS-TS、HTTP-TS。 +- `lalmax` 扩展能力使用 `lalmax` 配置段中的端口，例如 SRT、WHIP/WHEP、HTTP-FMP4、HLS-FMP4/LLHLS。 +- 当前 lal 使用简单流管理时主要按 `streamName` 匹配。示例中的 `/live/test110` 里，`test110` 是流名，`live` 可作为常用路径前缀。 +- HTTP-FLV、HTTP-TS、HLS-TS 的路径还受 `lal.httpflv.url_pattern`、`lal.httpts.url_pattern`、`lal.hls.url_pattern` 影响。示例配置中 HTTP-FLV 的 `url_pattern` 为 `/`，因此 `/live/test110.flv` 可用。 +- HTTPS、RTMPS、RTSPS 依赖配置中的证书文件，浏览器或播放器可能需要信任测试证书。 + +## 推流地址 + +### RTMP + +```text +rtmp://127.0.0.1:1935/live/test110 +``` + +FFmpeg 示例： + +```bash +ffmpeg -re -i demo.flv -c:a copy -c:v copy -f flv rtmp://127.0.0.1:1935/live/test110 +``` + +如果开启 RTMPS： + +```text +rtmps://127.0.0.1:4935/live/test110 +``` + +### RTSP + +```text +rtsp://127.0.0.1:5544/live/test110 +``` + +FFmpeg 示例： + +```bash +ffmpeg -re -i demo.flv -c:a copy -c:v copy -f rtsp rtsp://127.0.0.1:5544/live/test110 +``` + +如果开启 RTSPS： + +```text +rtsps://127.0.0.1:5322/live/test110 +``` + +### SRT + +```text +srt://127.0.0.1:6001?streamid=#!::h=test110,m=publish +``` + +`h` 表示流名，`m=publish` 表示推流。 + +### WebRTC WHIP + +```text +http://127.0.0.1:1290/webrtc/whip?streamid=test110 +https://127.0.0.1:1233/webrtc/whip?streamid=test110 +``` + +WHIP 使用 HTTP POST 传输 SDP offer，通常由 OBS、WHIP 客户端或 WebRTC 工具调用。 + +### GB28181 + +GB28181 不是普通 URL 推流。设备通过 SIP 注册到 lalmax，平台再通过 API 控制播放。详见 [gb28181.md](./gb28181.md)。 + +## 拉流地址 + +### RTMP + +```text +rtmp://127.0.0.1:1935/live/test110 +``` + +ffplay 示例： + +```bash +ffplay rtmp://127.0.0.1:1935/live/test110 +``` + +### RTSP + +```text +rtsp://127.0.0.1:5544/live/test110 +``` + +ffplay 示例： + +```bash +ffplay rtsp://127.0.0.1:5544/live/test110 +``` + +如果开启 RTSPS： + +```text +rtsps://127.0.0.1:5322/live/test110 +``` + +### HTTP-FLV + +```text +http://127.0.0.1:8080/live/test110.flv +https://127.0.0.1:4433/live/test110.flv +``` + +ffplay 示例： + +```bash +ffplay http://127.0.0.1:8080/live/test110.flv +``` + +### HTTP-TS + +需要启用 `lal.httpts.enable`。 + +```text +http://127.0.0.1:8080/live/test110.ts +https://127.0.0.1:4433/live/test110.ts +``` + +### HLS-TS + +需要启用 `lal.hls.enable`。 + +```text +http://127.0.0.1:8080/hls/test110/playlist.m3u8 +http://127.0.0.1:8080/hls/test110/record.m3u8 +http://127.0.0.1:8080/hls/test110.m3u8 +``` + +### SRT + +```text +srt://127.0.0.1:6001?streamid=#!::h=test110,m=request +``` + +`h` 表示流名，`m=request` 表示拉流。 + +### WebRTC WHEP + +```text +http://127.0.0.1:1290/webrtc/whep?streamid=test110 +https://127.0.0.1:1233/webrtc/whep?streamid=test110 +``` + +WHEP 使用 HTTP POST 传输 SDP offer，通常由 WHEP 播放器或 WebRTC 工具调用。 + +### Jessibuca DataChannel + +```text +webrtc://127.0.0.1:1290/webrtc/play/live/test110 +``` + +### HTTP-FMP4 + +```text +http://127.0.0.1:1290/live/m4s/test110.mp4 +https://127.0.0.1:1233/live/m4s/test110.mp4 +``` + +### HLS-FMP4/LLHLS + +需要启用 `lalmax.hls_config.enable`。 + +```text +http://127.0.0.1:1290/live/hls/test110/index.m3u8 +https://127.0.0.1:1233/live/hls/test110/index.m3u8 +``` + +如果需要低延迟 HLS，设置 `lalmax.hls_config.low_latency` 为 `true`。