17 KiB
17 KiB
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 流。
工作流程：
openRtpServer: 创建 RTP 接收端口- GB28181 设备推送 RTP 流到该端口
- ZLMediaKit 自动将 RTP 流转换为标准流
- 可通过 RTSP/RTMP/HLS 等协议播放
二、完整使用流程示例
场景 1: GB28181 设备推流
# 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 推流
# 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: 录制流
# 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: 截图
# 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: 下载录像文件
# 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 速查
# 查看所有流
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"