562 lines
17 KiB
Markdown
562 lines
17 KiB
Markdown
# ZLMediaKit API 核心概念与使用指南
|
||
|
||
## 一、核心概念解析
|
||
|
||
### 1. 流（Stream）的概念
|
||
在 ZLMediaKit 中，**流**是指一个媒体数据源，由四元组唯一标识：
|
||
- **schema**: 协议类型（rtsp/rtmp/rtc等）
|
||
- **vhost**: 虚拟主机（通常是 `__defaultVhost__`）
|
||
- **app**: 应用名（如 live、rtp）
|
||
- **stream**: 流ID（如 test、camera01）
|
||
|
||
**完整流标识**: `schema://vhost/app/stream`
|
||
例如: `rtsp://__defaultVhost__/live/test`
|
||
|
||
### 2. Session（会话）
|
||
**Session** 是指客户端与服务器之间的 **TCP/UDP 连接**。
|
||
- 每个播放器连接、推流连接都会创建一个 Session
|
||
- Session 包含：连接ID、本地端口、对端IP、协议类型等信息
|
||
- 通过 `getAllSession` 可以查看所有活跃连接
|
||
- 通过 `kick_session` 可以断开指定连接
|
||
|
||
**Session 与 Stream 的关系**：
|
||
- 一个 Stream 可以有多个 Session（多个播放器观看同一个流）
|
||
- 一个 Session 只对应一个 Stream
|
||
|
||
### 3. 拉流代理（StreamProxy）
|
||
**拉流代理**是指 ZLMediaKit 作为客户端，从远程服务器拉取流，然后在本地提供服务。
|
||
|
||
**使用场景**：
|
||
- 从其他流媒体服务器拉取流到本地
|
||
- 协议转换（拉取 RTMP 流，提供 RTSP/HLS 等多协议播放）
|
||
- 流的中转和分发
|
||
|
||
**API**: `addStreamProxy`
|
||
```
|
||
GET /index/api/addStreamProxy?
|
||
secret=xxx&
|
||
vhost=__defaultVhost__&
|
||
app=live&
|
||
stream=test&
|
||
url=rtmp://remote.server.com/live/stream
|
||
```
|
||
|
||
**工作原理**：
|
||
```
|
||
远程服务器 --拉流--> ZLMediaKit --提供多协议--> 播放器
|
||
(RTMP源) (代理) (RTSP/RTMP/HLS/FLV等)
|
||
```
|
||
|
||
### 4. FFmpeg 拉流代理（FFmpegSource）
|
||
**FFmpeg 代理**是通过调用 FFmpeg 进程来拉取流，支持更多格式和协议。
|
||
|
||
**与普通拉流代理的区别**：
|
||
- **StreamProxy**: 使用 ZLMediaKit 内置播放器，性能高，但支持协议有限
|
||
- **FFmpegSource**: 使用 FFmpeg，支持任意协议/格式，但性能较低，占用资源多
|
||
|
||
**使用场景**：
|
||
- 拉取 ZLMediaKit 不支持的协议（如某些特殊 HLS、DASH）
|
||
- 需要 FFmpeg 的转码能力
|
||
- 拉取文件流
|
||
|
||
**API**: `addFFmpegSource`
|
||
```
|
||
GET /index/api/addFFmpegSource?
|
||
secret=xxx&
|
||
src_url=http://example.com/live.m3u8&
|
||
dst_url=rtmp://127.0.0.1/live/stream&
|
||
timeout_ms=10000
|
||
```
|
||
|
||
### 5. 推流代理（StreamPusherProxy）
|
||
**推流代理**是指将 ZLMediaKit 上的流推送到其他流媒体服务器。
|
||
|
||
**使用场景**：
|
||
- 将本地流推送到 CDN
|
||
- 多平台分发（同时推送到多个平台）
|
||
- 流的备份
|
||
|
||
**API**: `addStreamPusherProxy`
|
||
```
|
||
GET /index/api/addStreamPusherProxy?
|
||
secret=xxx&
|
||
schema=rtmp&
|
||
vhost=__defaultVhost__&
|
||
app=live&
|
||
stream=test&
|
||
dst_url=rtmp://cdn.server.com/live/push
|
||
```
|
||
|
||
### 6. 断流（close_stream）
|
||
**断流**是指关闭一个媒体流源，而不是断开客户端连接。
|
||
|
||
**断流的含义**：
|
||
- 停止流的源头（推流端或拉流代理）
|
||
- 所有观看该流的播放器会断开
|
||
- 流从服务器上移除
|
||
|
||
**与 kick_session 的区别**：
|
||
- `close_stream`: 关闭流源，影响所有观看者
|
||
- `kick_session`: 只断开某个客户端连接，不影响流本身
|
||
|
||
### 7. RTP 服务器
|
||
**RTP 服务器**用于接收 GB28181 设备推送的 RTP 流。
|
||
|
||
**工作流程**：
|
||
1. `openRtpServer`: 创建 RTP 接收端口
|
||
2. GB28181 设备推送 RTP 流到该端口
|
||
3. ZLMediaKit 自动将 RTP 流转换为标准流
|
||
4. 可通过 RTSP/RTMP/HLS 等协议播放
|
||
|
||
---
|
||
|
||
## 二、完整使用流程示例
|
||
|
||
### 场景 1: GB28181 设备推流
|
||
```bash
|
||
# 1. 创建 RTP 服务器（监听端口接收 GB28181 推流）
|
||
GET /index/api/openRtpServer?
|
||
secret=xxx&
|
||
port=10000&
|
||
tcp_mode=1&
|
||
stream_id=camera01
|
||
|
||
# 返回: {"code":0, "port":10000}
|
||
|
||
# 2. GB28181 设备推流到 10000 端口（设备端配置）
|
||
|
||
# 3. 查看流是否在线
|
||
GET /index/api/isMediaOnline?
|
||
secret=xxx&
|
||
schema=rtsp&
|
||
vhost=__defaultVhost__&
|
||
app=rtp&
|
||
stream=camera01
|
||
|
||
# 4. 获取流信息（包含所有播放地址）
|
||
GET /index/api/getMediaInfo?
|
||
secret=xxx&
|
||
schema=rtsp&
|
||
vhost=__defaultVhost__&
|
||
app=rtp&
|
||
stream=camera01
|
||
|
||
# 返回包含:
|
||
# - RTSP: rtsp://server:554/rtp/camera01
|
||
# - RTMP: rtmp://server:1935/rtp/camera01
|
||
# - HTTP-FLV: http://server:80/rtp/camera01.live.flv
|
||
# - HLS: http://server:80/rtp/camera01/hls.m3u8
|
||
# - WebRTC: webrtc://server/rtp/camera01
|
||
```
|
||
|
||
### 场景 2: RTMP 推流
|
||
```bash
|
||
# 1. 使用 OBS 或 FFmpeg 推流
|
||
ffmpeg -re -i input.mp4 -c copy -f flv rtmp://server:1935/live/mystream
|
||
|
||
# 推流地址格式: rtmp://服务器IP:端口/app/stream
|
||
# - app: 应用名（如 live）
|
||
# - stream: 流ID（如 mystream）
|
||
|
||
# 2. 查看流列表
|
||
GET /index/api/getMediaList?secret=xxx
|
||
|
||
# 返回所有在线流，包含:
|
||
# {
|
||
# "code": 0,
|
||
# "data": [{
|
||
# "app": "live",
|
||
# "stream": "mystream",
|
||
# "vhost": "__defaultVhost__",
|
||
# "schema": "rtmp",
|
||
# "readerCount": 0, // 观看人数
|
||
# "totalReaderCount": 0,
|
||
# "originType": 0, // 0=推流，1=拉流代理，2=点播
|
||
# "originUrl": "",
|
||
# "createStamp": 1234567890
|
||
# }]
|
||
# }
|
||
|
||
# 3. 获取该流的详细信息和播放地址
|
||
GET /index/api/getMediaInfo?
|
||
secret=xxx&
|
||
schema=rtmp&
|
||
vhost=__defaultVhost__&
|
||
app=live&
|
||
stream=mystream
|
||
|
||
# 4. 播放地址:
|
||
# - RTSP: rtsp://server:554/live/mystream
|
||
# - RTMP: rtmp://server:1935/live/mystream
|
||
# - HTTP-FLV: http://server:80/live/mystream.live.flv
|
||
# - HLS: http://server:80/live/mystream/hls.m3u8
|
||
# - WebSocket-FLV: ws://server:80/live/mystream.live.flv
|
||
```
|
||
|
||
### 场景 3: 录制流
|
||
```bash
|
||
# 1. 开始录制（MP4 格式）
|
||
GET /index/api/startRecord?
|
||
secret=xxx&
|
||
type=1& # 0=HLS, 1=MP4
|
||
vhost=__defaultVhost__&
|
||
app=live&
|
||
stream=mystream&
|
||
max_second=3600 # 每小时切片
|
||
|
||
# 2. 检查是否正在录制
|
||
GET /index/api/isRecording?
|
||
secret=xxx&
|
||
type=1&
|
||
vhost=__defaultVhost__&
|
||
app=live&
|
||
stream=mystream
|
||
|
||
# 3. 获取录像文件列表
|
||
GET /index/api/getMp4RecordFile?
|
||
secret=xxx&
|
||
vhost=__defaultVhost__&
|
||
app=live&
|
||
stream=mystream&
|
||
period=2025-12-09 # 指定日期
|
||
|
||
# 返回:
|
||
# {
|
||
# "code": 0,
|
||
# "data": {
|
||
# "paths": [
|
||
# "/path/to/record/live/mystream/2025-12-09/10-30-00.mp4",
|
||
# "/path/to/record/live/mystream/2025-12-09/11-30-00.mp4"
|
||
# ],
|
||
# "rootPath": "/path/to/record"
|
||
# }
|
||
# }
|
||
|
||
# 4. 停止录制
|
||
GET /index/api/stopRecord?
|
||
secret=xxx&
|
||
type=1&
|
||
vhost=__defaultVhost__&
|
||
app=live&
|
||
stream=mystream
|
||
```
|
||
|
||
### 场景 4: 截图
|
||
```bash
|
||
# 1. 获取实时截图
|
||
GET /index/api/getSnap?
|
||
secret=xxx&
|
||
url=rtsp://server/live/mystream&
|
||
timeout_sec=10&
|
||
expire_sec=60 # 缓存时间
|
||
|
||
# 返回: JPEG 图片数据
|
||
|
||
# 2. 如果配置了定时截图，查看截图列表
|
||
# 截图通常保存在配置的 snap 目录下
|
||
# 目录结构: /snap/vhost/app/stream/timestamp.jpg
|
||
|
||
# 3. 删除截图
|
||
GET /index/api/deleteSnapDirectory?
|
||
secret=xxx&
|
||
vhost=__defaultVhost__&
|
||
app=live&
|
||
stream=mystream&
|
||
file=1234567890.jpg # 可选，不指定则删除整个目录
|
||
```
|
||
|
||
### 场景 5: 下载录像文件
|
||
```bash
|
||
# 1. 获取录像文件列表（见场景3）
|
||
GET /index/api/getMp4RecordFile?
|
||
secret=xxx&
|
||
vhost=__defaultVhost__&
|
||
app=live&
|
||
stream=mystream&
|
||
period=2025-12-09
|
||
|
||
# 2. 下载指定文件
|
||
GET /index/api/downloadFile?
|
||
file_path=/path/to/record/live/mystream/2025-12-09/10-30-00.mp4&
|
||
save_name=mystream_20251209_103000.mp4
|
||
|
||
# 浏览器会直接下载该文件
|
||
```
|
||
|
||
---
|
||
|
||
## 三、API 分类与关系图
|
||
|
||
### 1. 流管理类
|
||
```
|
||
getMediaList # 获取所有流列表
|
||
getMediaInfo # 获取单个流详细信息
|
||
isMediaOnline # 检查流是否在线
|
||
close_stream # 关闭单个流
|
||
close_streams # 批量关闭流
|
||
getMediaPlayerList # 获取流的播放者列表
|
||
```
|
||
|
||
### 2. 连接管理类
|
||
```
|
||
getAllSession # 获取所有TCP/UDP连接
|
||
kick_session # 断开单个连接
|
||
kick_sessions # 批量断开连接
|
||
```
|
||
|
||
### 3. 代理管理类
|
||
```
|
||
# 拉流代理
|
||
addStreamProxy # 添加拉流代理
|
||
delStreamProxy # 删除拉流代理
|
||
listStreamProxy # 列出所有拉流代理
|
||
getProxyInfo # 获取代理详细信息
|
||
|
||
# 推流代理
|
||
addStreamPusherProxy # 添加推流代理
|
||
delStreamPusherProxy # 删除推流代理
|
||
listStreamPusherProxy # 列出所有推流代理
|
||
getProxyPusherInfo # 获取推流代理信息
|
||
|
||
# FFmpeg 代理
|
||
addFFmpegSource # 添加 FFmpeg 拉流
|
||
delFFmpegSource # 删除 FFmpeg 拉流
|
||
listFFmpegSource # 列出所有 FFmpeg 拉流
|
||
```
|
||
|
||
### 4. RTP/GB28181 类
|
||
```
|
||
openRtpServer # 创建 RTP 接收端口
|
||
closeRtpServer # 关闭 RTP 端口
|
||
connectRtpServer # TCP 主动连接模式
|
||
listRtpServer # 列出所有 RTP 服务器
|
||
getRtpInfo # 获取 RTP 推流信息
|
||
updateRtpServerSSRC # 更新 SSRC 过滤
|
||
pauseRtpCheck # 暂停超时检查
|
||
resumeRtpCheck # 恢复超时检查
|
||
```
|
||
|
||
### 5. RTP 推流类
|
||
```
|
||
startSendRtp # 主动模式推送 RTP
|
||
startSendRtpPassive # 被动模式推送 RTP
|
||
startSendRtpTalk # 双向对讲
|
||
stopSendRtp # 停止推送 RTP
|
||
listRtpSender # 列出 RTP 发送器
|
||
```
|
||
|
||
### 6. 录制类
|
||
```
|
||
startRecord # 开始录制
|
||
stopRecord # 停止录制
|
||
isRecording # 检查录制状态
|
||
getMp4RecordFile # 获取录像文件列表
|
||
deleteRecordDirectory # 删除录像目录
|
||
setRecordSpeed # 设置录像播放速度
|
||
seekRecordStamp # 设置录像播放位置
|
||
startRecordTask # 事件录制（前后录制）
|
||
```
|
||
|
||
### 7. 截图类
|
||
```
|
||
getSnap # 获取实时截图
|
||
deleteSnapDirectory # 删除截图目录
|
||
```
|
||
|
||
### 8. 文件类
|
||
```
|
||
loadMP4File # 点播 MP4 文件
|
||
downloadFile # 下载文件
|
||
```
|
||
|
||
### 9. 系统管理类
|
||
```
|
||
getApiList # 获取 API 列表
|
||
getServerConfig # 获取服务器配置
|
||
setServerConfig # 设置服务器配置
|
||
restartServer # 重启服务器
|
||
getStatistic # 获取统计信息
|
||
getThreadsLoad # 获取网络线程负载
|
||
getWorkThreadsLoad # 获取后台线程负载
|
||
version # 获取版本信息
|
||
```
|
||
|
||
---
|
||
|
||
## 四、关键流程图
|
||
|
||
### 流的生命周期
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 流的来源 │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 1. 推流: RTMP/RTSP/WebRTC 推流 │
|
||
│ 2. 拉流代理: addStreamProxy │
|
||
│ 3. FFmpeg 代理: addFFmpegSource │
|
||
│ 4. GB28181: openRtpServer + 设备推流 │
|
||
│ 5. 点播: loadMP4File │
|
||
└─────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 流在 ZLMediaKit 中 │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ - 唯一标识: vhost/app/stream │
|
||
│ - 自动协议转换: RTSP/RTMP/HLS/FLV/WebRTC 等 │
|
||
│ - 可被多个客户端同时播放 │
|
||
│ - 可被录制、截图、转推 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 流的消费 │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 1. 播放: 多协议播放地址 │
|
||
│ 2. 录制: startRecord │
|
||
│ 3. 截图: getSnap │
|
||
│ 4. 转推: addStreamPusherProxy │
|
||
│ 5. RTP 推送: startSendRtp │
|
||
└─────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 流的结束 │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 1. 推流端断开 │
|
||
│ 2. 主动关闭: close_stream │
|
||
│ 3. 无人观看超时（配置决定） │
|
||
│ 4. 删除代理: delStreamProxy/delFFmpegSource │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### GB28181 完整流程
|
||
```
|
||
1. 创建 RTP 服务器
|
||
openRtpServer(port=10000, stream_id=camera01)
|
||
↓
|
||
2. 配置 GB28181 设备推流到 10000 端口
|
||
↓
|
||
3. 流自动注册为: rtsp://__defaultVhost__/rtp/camera01
|
||
↓
|
||
4. 查看流信息
|
||
getMediaInfo(schema=rtsp, app=rtp, stream=camera01)
|
||
↓
|
||
5. 获取所有播放地址并播放
|
||
- RTSP: rtsp://server:554/rtp/camera01
|
||
- RTMP: rtmp://server:1935/rtp/camera01
|
||
- HTTP-FLV: http://server/rtp/camera01.live.flv
|
||
- HLS: http://server/rtp/camera01/hls.m3u8
|
||
↓
|
||
6. 录制/截图/转推
|
||
startRecord(app=rtp, stream=camera01)
|
||
getSnap(url=rtsp://server/rtp/camera01)
|
||
addStreamPusherProxy(app=rtp, stream=camera01, dst_url=...)
|
||
↓
|
||
7. 关闭流
|
||
closeRtpServer(stream_id=camera01)
|
||
```
|
||
|
||
---
|
||
|
||
## 五、常见问题
|
||
|
||
### Q1: 如何知道流的 stream_id？
|
||
**A**:
|
||
- **推流时**: stream_id 由推流端指定（推流地址的最后一部分）
|
||
- **GB28181**: 在 `openRtpServer` 时指定
|
||
- **拉流代理**: 在 `addStreamProxy` 时指定
|
||
- **查询**: 使用 `getMediaList` 查看所有在线流
|
||
|
||
### Q2: 流的各种播放地址如何获取？
|
||
**A**: 使用 `getMediaInfo` 接口，返回结果包含所有协议的播放地址。
|
||
|
||
### Q3: 录像文件保存在哪里？
|
||
**A**:
|
||
- 默认路径在配置文件中设置（通常是 `./www/record`）
|
||
- 目录结构: `record/vhost/app/stream/日期/时间.mp4`
|
||
- 可通过 `getMp4RecordFile` 查询
|
||
|
||
### Q4: 如何实现多平台推流？
|
||
**A**: 使用 `addStreamPusherProxy`，同一个流可以添加多个推流代理（不同 dst_url）。
|
||
|
||
### Q5: 拉流代理和 FFmpeg 代理如何选择？
|
||
**A**:
|
||
- **优先使用拉流代理**: 性能高，资源占用少
|
||
- **使用 FFmpeg 代理的场景**:
|
||
- 源协议 ZLMediaKit 不支持
|
||
- 需要转码
|
||
- 需要 FFmpeg 的特殊功能
|
||
|
||
### Q6: 如何实现按需拉流？
|
||
**A**: 配置 `on_play` hook，当有人播放时才调用 `addStreamProxy` 拉取源流。
|
||
|
||
---
|
||
|
||
## 六、最佳实践
|
||
|
||
### 1. 流命名规范
|
||
```
|
||
app: 按业务分类（live, record, vod, gb28181）
|
||
stream: 使用有意义的ID（camera_01, user_123_live）
|
||
```
|
||
|
||
### 2. 录制策略
|
||
```
|
||
- 重要流: 实时录制（startRecord）
|
||
- 事件流: 使用 startRecordTask（前后录制）
|
||
- 定时录制: 通过配置文件设置
|
||
```
|
||
|
||
### 3. 性能优化
|
||
```
|
||
- 使用拉流代理而非 FFmpeg 代理
|
||
- 合理设置录制切片时间
|
||
- 使用 HLS 时注意切片数量
|
||
- 监控 getThreadsLoad 和 getWorkThreadsLoad
|
||
```
|
||
|
||
### 4. 安全建议
|
||
```
|
||
- 修改默认 secret
|
||
- 启用推流鉴权（on_publish hook）
|
||
- 启用播放鉴权（on_play hook）
|
||
- 限制 API 访问 IP
|
||
```
|
||
|
||
---
|
||
|
||
## 七、快速参考
|
||
|
||
### 推流地址格式
|
||
```
|
||
RTMP: rtmp://server:1935/app/stream
|
||
RTSP: rtsp://server:554/app/stream (需要服务器支持 RTSP 推流)
|
||
```
|
||
|
||
### 播放地址格式
|
||
```
|
||
RTSP: rtsp://server:554/app/stream
|
||
RTMP: rtmp://server:1935/app/stream
|
||
HTTP-FLV: http://server:80/app/stream.live.flv
|
||
WebSocket-FLV: ws://server:80/app/stream.live.flv
|
||
HLS: http://server:80/app/stream/hls.m3u8
|
||
HTTP-TS: http://server:80/app/stream.live.ts
|
||
HTTP-fMP4: http://server:80/app/stream.live.mp4
|
||
WebRTC: webrtc://server/app/stream
|
||
```
|
||
|
||
### 常用 API 速查
|
||
```bash
|
||
# 查看所有流
|
||
curl "http://server:80/index/api/getMediaList?secret=xxx"
|
||
|
||
# 查看流信息
|
||
curl "http://server:80/index/api/getMediaInfo?secret=xxx&schema=rtsp&vhost=__defaultVhost__&app=live&stream=test"
|
||
|
||
# 开始录制
|
||
curl "http://server:80/index/api/startRecord?secret=xxx&type=1&vhost=__defaultVhost__&app=live&stream=test"
|
||
|
||
# 获取截图
|
||
curl "http://server:80/index/api/getSnap?secret=xxx&url=rtsp://server/live/test&timeout_sec=10" -o snap.jpg
|
||
|
||
# 关闭流
|
||
curl "http://server:80/index/api/close_stream?secret=xxx&schema=rtsp&vhost=__defaultVhost__&app=live&stream=test"
|
||
```
|