ZLMediaKit 完整文档
本文档来自 zread.ai 对 ZLMediaKit/ZLMediaKit 仓库的解析，合并该站所有子页面内容。来源：https://zread.ai/ZLMediaKit/ZLMediaKit
目录
- 概述
- 快速开始
- 从源码构建
- [Docker 部署](#Docker 部署)
- 跨平台编译指南
- 最新更新
- 问题与反馈
- 关于贡献者
- 媒体来源管理系统
- 多协议转换框架
- [异步网络 I/O 模型](#异步网络 I/O 模型)
- [RTSP 协议栈与会话管理](#RTSP 协议栈与会话管理)
- [RTMP 协议与 Enhanced-RTMP 支持](#RTMP 协议与 Enhanced-RTMP 支持)
- [HTTP/WebSocket 流媒体 (FLV/TS/fMP4)](#HTTP/WebSocket 流媒体 (FLV/TS/fMP4))
- [RTP 与 GB28181 实现](#RTP 与 GB28181 实现)
- [WebRTC 传输与 ICE 会话](#WebRTC 传输与 ICE 会话)
- [NACK 与 TWCC 实现](#NACK 与 TWCC 实现)
- [WHIP/WHEP 协议支持](#WHIP/WHEP 协议支持)
- [单端口多线程 WebRTC 架构](#单端口多线程 WebRTC 架构)
- [MediaServer 架构概述](#MediaServer 架构概述)
- [RESTful API 参考](#RESTful API 参考)
- [WebHook 事件系统](#WebHook 事件系统)
- 认证与安全机制
- 并发连接处理
- 低延迟优化技术
- 内存管理与抖动缓冲
- 监控与统计收集
- [C API SDK 概述](#C API SDK 概述)
- 自定义播放器开发
- 自定义推流器开发
- 扩展协议支持
- 集群部署与负载均衡
- 虚拟主机配置
1. 概述
ZLMediaKit 是基于 C++11 的高性能、生产级流媒体服务框架，填补视频监控协议与直播协议之间的鸿沟，提供即用的 MediaServer 与可嵌入的 C API SDK。支持海量并发与 100--500ms 超低延迟。
ZLMediaKit 的独特之处
统一媒体源管理系统，实现 RTSP、RTMP、HLS、HTTP-FLV、WebSocket-FLV、GB28181、HTTP-TS、WebSocket-TS、HTTP-fMP4、WebSocket-fMP4、MP4、WebRTC、SRT 等协议间无缝转换；单机可支持 10 万+ 并发播放、100Gb/s 级 I/O。架构上采用智能指针、异步 I/O、集中式 MediaSource 抽象，协议实现从公共源消费或生产数据。
架构概览
分层：网络 I/O 层（异步事件驱动）→ 协议实现层 → 媒体源管理层 → 应用层（MediaServer / C API SDK）。MediaSource 为核心抽象，流由 vhost、app、流名唯一标识，跟踪编解码与轨道信息；MediaSourceEvent 支持生命周期、读者数、定位/暂停等通知。
核心特性一览
| 类别 | 能力 |
|---|---|
| 协议 | RTSPS、RTMPS、HLS、HTTP-FLV、WebSocket-FLV、GB28181、HTTP/WS-TS、HTTP/WS-fMP4、MP4、WebRTC、SRT，协议间全双向转换 |
| 视频 | H264、H265、VP8、VP9、AV1、JPEG、H266 |
| 音频 | AAC、G711、Opus、MP3、G722、G723、G729、ADPCM、SVAC |
| 传输 | RTP over UDP/TCP/HTTP、RTP 组播 |
| 性能 | 10 万+ 并发、100Gb/s I/O、100--500ms 延迟 |
| 安全 | Basic/Digest、TLS/SSL、API 密钥 |
| 特性 | 集群、按需转码、自动重连、画面堆叠 |
部署选项
MediaServer 独立部署（含 RESTful API、WebHook、HTTP 文件服务，INI 配置）；Docker 镜像；C API SDK 嵌入；Go/Java/C# 等绑定。CMake 可裁剪 ENABLE_WEBRTC、ENABLE_SRT、ENABLE_HLS 等。支持 Linux、macOS、iOS、Android、Windows；x86、ARM、RISC-V、MIPS、龙芯、申威。
生态系统
wvp-GB28181-pro、AKStream、BXC_SipServer 等 GB28181/NVR 平台；jessibuca、wsPlayer 等播放器；spring-boot-starter、Java/C# SDK、ZLMediaKit_exporter（Prometheus）等开发与监控工具。
2. 快速开始
三种使用方式：Docker 快速体验、MediaServer 独立部署、C API SDK 嵌入。MediaSource 为核心枢纽，任意协议入、任意协议出。
Docker： docker pull zlmediakit/zlmediakit:latest；运行映射 1935(RTMP)、80/443(HTTP)、554(RTSP)、8000(WebRTC) 等，可挂载 -v /path/to/config:/opt/media/conf。Web 管理：http://localhost/index/api/getServerConfig。
推流： ffmpeg -re -i test.mp4 -c:v libx264 -profile:v baseline -preset ultrafast -c:a aac -f flv rtmp://localhost/live/test。播放： ffplay rtmp://localhost/live/test 或 http://localhost/live/test.flv 或 rtsp://localhost/live/test。
配置： config.ini 控制行为。api 含 secret、snapRoot、downloadRoot；protocol 含 enable_hls/rtsp/rtmp 等、*_demand 按需转换；general 含 maxStreamWaitMS、streamNoneReaderDelayMS、mediaServerId、listen_ip。生产务必修改默认 secret。
RESTful API： 响应格式 { code, msg, data }。示例：getMediaList 列流、startStreamProxy 拉流代理。WebHook： hook enable、on_publish/on_unpublish/on_play/on_stop/on_stream_none_reader，端点返回 { code, msg } 表是否允许。项目结构： api/、server/、src/、tests/、conf/、www/。用例： 监控（GB28181、rtp）；直播（*_demand=0）；VOD（rtsp://host/vod/xx.mp4）。排错： logLevel、apiDebug。
3. 从源码构建
使用 CMake，支持 Linux、macOS、Windows、iOS、Android。依赖：OpenSSL、Git、CMake 必需；可选 FFmpeg、libsrtp、MySQL 等。步骤：安装依赖（apt/yum/brew）→ git clone → mkdir build && cd build → cmake ..（可加 -DENABLE_FFMPEG=ON、-DENABLE_WEBRTC=ON、-DCMAKE_BUILD_TYPE=Release 等）→ make -j$(nproc)。产物在 release/平台/构建类型/。运行：./MediaServer -s default.pem -c conf/config.ini。可选 ENABLE_JEMALLOC_STATIC 或 ENABLE_TCMALLOC；Windows 用 MSVC + CMake -G "Visual Studio 17 2022" -A x64。
4. Docker 部署
ZLMediaKit 提供多阶段构建的 Docker 镜像，编译与运行分离，镜像体积约减少 60%。支持 Ubuntu 20.04/18.04/16.04、CentOS 7 等基础镜像。
预构建镜像： docker pull zlmediakit/zlmediakit:Release.latest。运行示例（映射常用端口）：
bash
docker run -d \
-p 1935:1935 -p 554:554 -p 80:80 -p 443:443 \
-p 10000:10000 -p 10000:10000/udp \
-p 8000:8000 -p 8000:8000/udp -p 9000:9000 -p 9000:9000/udp \
zlmediakit/zlmediakit:Release.latest验证：访问 http://localhost:80 或向 rtmp://localhost/live/stream 推流。
自定义构建： docker build --build-arg MODEL=Release -t my-zlmediakit:release .；Debug 用 MODEL=Debug。构建脚本：build_docker_images.sh [-t build|push] [-m Debug|Release] [-p platform] [-v version]。传统变体：docker/ubuntu18.04/Dockerfile.runtime、Dockerfile.devel，docker/centos7/Dockerfile.runtime。
端口： 1935 RTMP、554 RTSP、80 HTTP、443 HTTPS、10000 RTP/WebRTC、8000/9000 WebRTC（TCP+UDP）。卷挂载： 配置 -v custom-config.ini:/opt/media/conf/config.ini，录像/快照可挂载 www/record、www/snap。环境变量： TZ、PATH 等。
Kubernetes： 使用 ConfigMap 提供 config.ini、Secret 提供 SSL 证书；Deployment 挂载 config 与 certs；Service 类型 LoadBalancer 暴露 RTMP/RTSP/HTTP/HTTPS/WebRTC；建议配置就绪探针检查 /index/api/getServerConfig。生产建议固定镜像版本标签、设置 CPU/内存限制，WebRTC 需放行 UDP。
5. 跨平台编译指南
CMake 统一构建，支持 Linux、macOS、Windows、iOS、Android；架构含 x86、ARM、RISC-V、MIPS、龙芯、申威。选项：ENABLE_API、ENABLE_FFMPEG、ENABLE_HLS、ENABLE_WEBRTC、ENABLE_SERVER、BUILD_SHARED_LIBS 等；Android/iOS 用 cmake/android.toolchain.cmake、cmake/ios.toolchain.cmake。Linux 需安装 build-essential、cmake、libssl-dev 等，可选 libsrtp、FFmpeg；git submodule update --init 后 cmake + make。
6. 最新更新
ZLMediaKit 作为基于 C++11 的流媒体服务器框架持续演进，支持 WebRTC、RTSP、RTMP、HTTP-FLV、HLS、WebSocket-FLV、HTTP-fMP4、GB28181、SRT、STUN、TURN 等协议。以下为 2025 年底至 2026 年 1 月的重要进展摘要。
近期增强和新功能
WebRTC 改进： 新增配置 nackAudioRtpSize（控制音频 NACK 的 RTP 包数量，值越低响应越快）、preferred_tcp（UDP 受限时优先走 TCP）；修复数据包重传被误判为重放攻击导致断连；修复 WebRtcSession 潜在内存泄漏。
HTTP 和 API： 支持 HTTP PUT；getAllSession 返回连接类型；事件视频录制支持负的前溯/后溯时间。
RTSP/RTMP： 优化 RTSP 点播（#4575/#4569/#4576）；修复 RTSP handleResPAUSE 未触发（#4625/#4631）；修复 RTMP 复杂模式 C2 不正确导致断连（#4591/#4598）。
流代理与缓存： 修复推流代理失败后无限重试；修复 GOP 缓存溢出后仅剩一个 GOP 导致播放异常（#4620/#4619）。
构建与平台
Windows： 修复 MinGW 编译（#4617）；更新 zltoolkit 子模块提升 wepoll 性能。构建系统： 整理 CMake 结构、默认配置支持注释与排序、修正 libavfilter/transcode 相关编译（#4587）。
媒体处理
快照滤镜支持在滤镜链中标记；播放器启动支持比例缩放（默认 720p，#4567/#4571）；转码模块 C++11 与运算符优先级修复。
社区与反馈
安全： #4623 提出通过 config.ini 配置 SSL 密码以支持 ECDHE 等前向保密。功能请求： 录制用 WS/fMP4 播放（#4639）、平滑升级不中断推流（#4641）、ICE-full 增强（#4636）。已报问题： aiortc SSL 密码（#4643）、RTSP SDP 异常音频导致视频无法拉取（#4642）、RtpSender SSRC 解析（#4637）、大疆 RTMP 防火墙（#4618）、麒麟系统 H265 WebRTC（#4616）等。
总结： 近期重点在 WebRTC 可靠性、协议互操作、构建与资源管理及社区反馈，项目在广泛协议支持与生产场景改进之间持续平衡。
7. 问题与反馈
本页记录用户报告的问题、常见反馈主题及开发团队应对，反映生产部署中的真实关切。
近期高优先级： 安全与配置 --- #4623：无法通过 config.ini 配置 SSL 加密套件，默认 RSA 缺乏前向保密，需支持 ECDHE。WebRTC 兼容 --- #4643 Python aiortc 与 ZLM DTLS 加密套件协商失败；#4616 麒麟系统 Chrome 上 H265 WebRTC 播放失败（SDP 校验）。RTSP/RTP --- #4642 SDP 异常音频导致整路失败（期望音频失败时仅丢弃视频）；#4626 GB28181 音频晚到时无法检测 G711A。网络 --- #4618 大疆无人机经端口映射推 RTMP 时在 onBwDone 后 RST（与 nginx-rtmp 对比更敏感）。实现 Bug --- #4637 RtpSender 用 atoi 解析 SSRC 导致 >0x7FFFFFFF 溢出，应使用 strtoul。
功能请求： 零停机升级（#4641/#4640）；WS/fMP4 播放历史录制（#4639）；ICE/STUN/TURN 改进与 RFC 8445 合规（#4636）；TCP 模式发送 RTCP SR（#4630/#1597）。
近期修复： WebRTC nackAudioRtpSize、preferred_tcp、重传误判、WebRtcSession 泄漏；RTSP handleResPAUSE、GOP 溢出、RTMP C2、代理无限重试；MinGW、libavfilter、zltoolkit wepoll。
常见主题： 跨平台不一致、与非浏览器/设备互操作摩擦、安全与高级配置文档不足、延迟预期需更好说明。建议： 新部署用实际设备充分测试、验证加密套件与 GOP 行为、保持更新；贡献可关注 ICE 合规、文档与国产 Linux 测试。
8. 关于贡献者
ZLMediaKit 支持 WebRTC、RTSP、RTMP、HTTP/HLS/FLV/fMP4、GB28181、SRT、STUN/TURN 等协议，由具备网络与流媒体专业知识的贡献者共同维护。本页介绍核心维护者与活跃贡献者。
核心维护者： xia-chu（项目负责人）--- 最活跃贡献者，近期负责：流代理无限重试修复、HTTP PUT 支持、WebRTC nackAudioRtpSize/preferred_tcp、重传误判修复、子模块与构建系统维护；提交信息为中文，项目植根中文开发者社区。
活跃贡献者： haorui wang --- RTSP handleResPAUSE 回调修复（#4625）；张传峰 --- Windows MinGW 编译修复（#4617）；xiongguangjie （与 xia-chu 合作）--- RTSP 点播优化；jeyawn --- RTMP 复杂模式 C2 修复（#4591）；wuliqqq --- GOP 缓存溢出修复（#4620/#4619）；Robo --- libavfilter/C++11 编译修复；PioLing --- 快照滤镜标记与播放器比例缩放（720p）。
开发文化： 快速 Bug 响应、安全意识（如 WebRTC 重放误判修复）、跨平台承诺、协作与共同作者提交。Issues 反映大疆 RTMP、aiortc SSL、ECDHE 配置、平滑升级等社区关切；维护者积极回复。贡献机会： ICE-full/STUN/TURN（#4636）、SSL 密码配置（#4623）、SDP 解析健壮性（#4634）、零停机升级（#4641）、麒麟等平台 H265 问题（#4616）。项目通过长期开放的预编译二进制 issue 等保持可访问性与社区参与。
9. 媒体来源管理系统
媒体源管理系统提供与协议无关的媒体流抽象层，支持无缝协议转换、多轨道管理与事件驱动操作。分层架构在保持协议特定优化的同时实现统一媒体处理。
MediaSource 核心： 所有媒体源（RTSP、RTMP、HLS 等）的抽象基类，由 schema + MediaTuple(vhost/app/stream) 唯一标识。职责包括：流标识与元数据（getSchema/getMediaTuple/getUrl）；全局注册与发现（find、findAsync、for_each_media）；源类型跟踪（MediaOriginType：rtmp_push、rtsp_push、rtp_push、pull、ffmpeg_pull、mp4_vod、device_chn、rtc_push、srt_push）。
MultiMediaSourceMuxer： 将单媒体源转为多协议格式，由 ProtocolOption 控制：enable_hls、enable_hls_fmp4、enable_mp4、enable_rtsp、enable_rtmp、enable_ts、enable_fmp4、modify_stamp；可通过 hook 按流动态配置。
事件驱动： MediaSourceEvent 提供 getOriginType/getOriginUrl、seekTo/pause/speed/close、totalReaderCount/onReaderChanged/onRegist、getMuxer/getRtpProcess 等；MediaSourceEventInterceptor 支持鉴权与统计而不改核心实现。生命周期：regist()→onRegist(true)→活动；析构时 unregist()→onRegist(false)。
读取器与统计： readerCount/totalReaderCount、getPlayerList；getBytesSpeed/getTotalBytes、getCreateStamp/getAliveSecond；onReaderChanged 异步通知监听器。高级： getOwnership() 引用计数所有权；时间戳策略 kModifyStampOff/System/Relative；setupRecord/isRecording 录制集成。协议实现： RtspMediaSource、RtmpMediaSourceImp、HlsMediaSource 等。配置： general enable_vhost；protocol modify_stamp、enable_audio、auto_close 等；hls/rtmp 分段与时间戳。性能： weak_ptr 防循环引用、按需 Muxer、递归锁与 EventPoller 线程安全。与 WebHook（onRegist）、播放器/推流器（读者计数）、录制无缝集成。
10. 多协议转换框架
多协议转换实现不同流协议间无缝转换（无转码）：统一内部表示、与来源无关且以接收端为中心，流水线为协议解析 → 帧提取 → 协议重新封装。三层模型：输入协议解码器、中间统一媒体表示、输出协议编码器。
核心组件： MediaSource 作流中央注册表（vhost/app/stream 元组）；MediaSourceEvent 提供状态与观看者变化通知；MediaOriginType 区分 rtmp_push、rtsp_push、rtp_push、pull、ffmpeg_pull、mp4_vod、device_chn、rtc_push、srt_push。Track 表示音/视频通道（SDP、编解码器元数据）；Frame 为统一载荷容器（CodecId：H264/H265/AAC/G711/Opus/VP8/VP9/AV1 等）。
MultiMediaSourceMuxer： 实现 MediaSink，消费帧并分发到各协议 Muxer（Rtsp/Rtmp/TS/FMP4、HLS、MP4 录制）；按需生成协议（*_demand 控制立即或请求时激活）。ProtocolOption：modify_stamp、enable_audio、add_mute_audio、auto_close、paced_sender_ms、enable_hls/rtsp/rtmp/ts/fmp4。
编解码层： CommonRtpDecoder/Encoder、H264Rtp（RFC3984 NAL/STAP-A/FU-A）；CommonRtmpDecoder/Encoder、H264Rtmp（SPS/PPS、AVC 头）。编解码器支持矩阵：H264/H265/AAC/G711 全协议；Opus/VP8/VP9/AV1 支持 RTP/HLS/WebRTC 等（部分不支持 RTMP/GB28181）；MP3 支持 RTP/RTMP/HLS。
帧分发： 单源多消费者、每帧只解码一次多路编码；MediaSink + FrameDispatcher。扩展新协议需：协议解码器（→Frame）、协议编码器（Frame→包）、MediaSource 实现；Factory.h 工厂模式。轨道经 resetTracks() 动态注册，onAllTrackReady() 后初始化 Muxer。性能： 零拷贝（共享指针）、paced_sender_ms、按需 Muxer、时间戳平滑、环形缓冲。
11. 异步网络 I/O 模型
基于 ZLToolKit 的异步、事件驱动 I/O，采用 Reactor 模式：有限线程监控多套接字，将事件分发给会话处理器，消除每连接一线程的开销。分层：Network Layer（TCP/UDP/SSL Socket）→ Poller Thread Pool（EventPoller 1...N）→ Protocol Sessions（Rtsp/Rtmp/Http/Rtp/WebRtcSession）→ MediaSource/MediaSink。
Session 基类： onRecv(buf)、onError(err)、onManager()（周期维护/超时）。协议服务器在 main.cpp 中按端口绑定：HTTP 80/443、RTSP 554/332、RTMP 1935/19350、RTP 10000、Shell 9000。EventPoller： Linux epoll、macOS kqueue、Windows IOCP/select；每轮询器一线程，可读/可写时回调会话。生命周期： 接受连接 → 创建 Session → 注册 FD → 就绪；数据路径：读事件 → Buffer → onRecv() → 协议解析 → 业务逻辑 → 响应；onError() 时记录、释放 MediaSource、通知断开。MediaSourceEvent 集成： getOwnerPoller、close、totalReaderCount、getOriginType/getOriginUrl/getOriginSock，实现无读者自动清理。配置与广播： loadIniConfig()、kBroadcastUpdateConfig；kBroadcastMediaChanged/Publish/Played、kBroadcastFlowReport、kBroadcastStreamNoneReader。性能： 低线程占用、单线程数千连接、Buffer 零拷贝与内存池。RtspSession 继承 Session+RtspSplitter+RtpReceiver+MediaSourceEvent；HttpSession 含 FlvMuxer、HttpRequestSplitter、WebSocketSplitter；RtmpSession 处理 AMF、分块、publish/play、重连。I/O 委托给 ZLToolKit（epoll/kqueue/IOCP、Socket、定时器、线程池）。
12. RTSP 协议栈与会话管理
RTSP 协议栈围绕协议解析、会话管理与媒体分发三层，支持 RTP over TCP（交错）、UDP、组播与 HTTP 隧道，并与 MediaSource 统一抽象集成，实现与 RTMP/HTTP-FLV/WebRTC 的无缝转换。
RtspSplitter： 继承 HttpRequestSplitter，解析 RTSP 请求/响应并在同一 TCP 上多路分解 RTP/RTCP；enableRecvRtp() 切换信令/数据传输；交错格式为 $ (0x24) + 通道 ID + 长度（RFC 2326 10.12），通道 0/1 通常为 RTP/RTCP。RtspSession： 继承 Session + RtspSplitter + RtpReceiver + MediaSourceEvent；方法分发：OPTIONS→handleReq_Options、DESCRIBE→SDP、SETUP→传输协商、PLAY/PAUSE/TEARDOWN、ANNOUNCE/RECORD 推流；握手超时约 10s、保活约 60s。RtpReceiver： PacketSortor 维护排序缓存、丢弃缓存与输出队列，处理乱序与序列号回绕，可配置 _max_buffer_ms、_max_distance。
RTP 传输： TCP 交错（4 字节头、SETUP 分配通道）；UDP（UDPServer、listenPeer 按对端注册）；组播（RtpMultiCaster、239.x.x.x、RingReader 扇出）；HTTP 隧道（x-sessioncookie 绑定 GET/POST，g_mapGetter 路由）。RtspMediaSource： MediaSource + RingDelegate，GOP 边界 RingBuffer（默认 512 包）、SDP 与 RTP 包抽象，零拷贝多读者。RTCP： RtcpContext 生成 RR/SR、带宽约 5%、丢包与 RTT 监控。认证： Basic/Digest（MD5、nonce 防重放）。客户端： RtspPlayer（OPTIONS→DESCRIBE→SETUP→PLAY）、RtspPusher（ANNOUNCE→SETUP→RECORD），支持暂停、倍速、重连。配置： Rtsp.kKeepAliveSecond、General.kFlowThreshold。零拷贝、EventPoller 并发、UDPServer 回收与 SO_REUSEADDR/SO_RCVBUF 优化。
13. RTMP 协议与 Enhanced-RTMP 支持
分层架构：RtmpProtocol（握手、分块、控制消息）→ RtmpSession（认证、流注册、MediaSource 桥接）→ 编解码器层（RtmpCodec 子类）。默认块长 128 字节，可 MSG_SET_CHUNK 协商；握手支持简单模式与复杂模式（OpenSSL 摘要）。RtmpHeader：chunk_id、fmt(0--3)、time_stamp、body_size、type_id、stream_index；消息类型含 MSG_SET_CHUNK/MSG_ACK/MSG_USER_CONTROL/MSG_WIN_SIZE、MSG_AUDIO/VIDEO/DATA/CMD 等。会话维护 _chunk_size_in/out 可不对称优化。
Enhanced RTMP： 视频头 RtmpVideoHeaderEnhanced（enhanced、frame_type、pkt_type、fourcc）；支持 avc1/hvc1/vp80/vp90/av01 与 PacketTypeSequenceStart/CodedFrames；音频 ex_header + FourCC（mp4a/Opus/.mp3/PCMU/PCMA）。配置 Rtmp::kEnhanced；解码器通过 ex_header 检测并回退传统解析。编解码器： RtmpCodec 基类 + Track；H264RtmpEncoder 使用 FrameMerger（mp4 nal size）；Opus/VPx 需 makeConfigPacket、SequenceStart。RtmpMediaSourceImp： 注册、RtmpDemuxer、MultiMediaSourceMuxer、GOP 环形缓冲、WebHook；setMetaData(AMF)、addTrack/addTrackCompleted。配置： protocol modify_stamp(0/1/2)、continue_push_ms、paced_sender_ms；rtmp_demand、enable_rtsp/ts/fmp4。推拉： RtmpPusher/RtmpPlayer 继承 RtmpProtocol，支持重连与元数据。扩展：实现 RtmpCodec 的 Encoder/Decoder、makeConfigPacket/inputRtmp、工厂注册。排错：增强流不兼容时 rtmp.enhanced=0；音画同步用 modify_stamp=2；CPU 高可 paced_sender_ms=0 或减小 GOP 缓冲。
14. HTTP/WebSocket 流媒体 (FLV/TS/fMP4)
基于 HTTP 与 WebSocket 的低延迟直播分发，支持 FLV、TS、fMP4；传输与媒体格式分离，HttpSession 负责协议与 WebSocket 升级，各媒体源维护环形缓冲。
HTTP： checkLiveStream 按 URL 后缀匹配（.live.flv / .live.ts / .live.mp4），解析 vhost/app/stream，经 BroadcastMediaPlayed 鉴权后挂载到对应媒体源 RingBuffer；TS 默认 GOP 512 包；setSocketFlags() 优化 TCP 以降低延迟。WebSocket： checkWebSocket 检测 Sec-WebSocket-Key，回 Sec-WebSocket-Accept；WebSocketSessionBase/SendInterceptor 透明封装，onBeforeSendCB 将数据打成 WS 帧；WS-FLV/TS/fMP4 与 HTTP 共用媒体源，仅多一层帧封装；WS-fMP4 握手后先发 init segment 再发媒体片段。
媒体源： HTTP-FLV 复用 RtmpMediaSource（FLV 与 RTMP 同 H.264/AAC）；TS 用 TSMediaSource（TSPacket、PacketCache 按 GOP、默认 512）、TSMediaSourceMuxer（ts_demand 按需）；fMP4 用 FMP4MediaSource（FMP4Packet、独立 init 缓冲，连接时先发）。缓冲： 环形缓冲 GOP 对齐、多读者独立位置、零拷贝；PacketCache onFlush 写完整 GOP；无视频时跳过 GOP 缓存（_have_video）。配置： http keepAliveSecond、maxReqSize、allowCrossDomains；protocol ts_demand。鉴权： BroadcastMediaPlayed 钩子；失败 401。协议对比：FLV 主要为 H.264/AAC+JS 播放器，TS/fMP4 支持 H.265、MSE；延迟 FLV/fMP4 低、TS 中；防火墙均走 80/443，WS 适合仅允许出站 WS 的反代/CDN。
15. RTP 与 GB28181 实现
RTP 支持接收（设备接入）与发送（下游分发），UDP/TCP、多负载类型，与 MediaSource 集成。分层：Transport（RtpServer UDP/TCP）→ RtpSession（RtpSplitter、SSRC/PS 检测）→ ProcessInterface（RtpProcess、GB28181Process）→ 编解码（H264/H265/CommonRtp、PSDecoder、TSDecoder）→ MediaSink/MultiMediaSourceMuxer。
RtpServer： local_port、local_ip、tcp_mode(NONE/PASSIVE/ACTIVE)、re_use_port、ssrc、only_track(kAll/kOnlyAudio/kOnlyVideo)。RtpSession： 继承 Session + RtpSplitter，自动 SSRC 检测、支持 TCP 交错 RTP、超时清理、对接 RtpProcess。RtpProcess： MediaSinkInterface + MediaSourceEvent，RTP 校验与时间戳、轨道与编解码发现、RTCP、多协议输出、超时清理。GB28181Process： 国标 GB/T 28181，MPEG-PS over RTP；PT 可配置（kH264PT/kH265PT/kPSPT/kOpusPT），PSDecoder 用 mpeg-ps 解析；设备非标 PT 可通过配置适配。编解码： RtpCodec+RtpRing+FrameDispatcher；H264/H265 符合 RFC3984/RFC7798（STAP-A/FU-A、DtsGenerator、SPS/PPS）；AAC/G711/Opus/MP3/L16 等。RtpSender： UDP/TCP、GB28181 PS 或原始 RTP、RTCP、SendRtpArgs（dst_url/port、ssrc、pt、is_udp、only_audio/video）。配置： general wait_track_ready_ms、wait_audio_track_data_ms、wait_add_track_ms；rtp_proxy h264_pt/h265_pt/ps_pt/opus_pt、dump_dir。场景：设备接入（inputRtp→rtsp://host/rtp/stream）、向平台发送（RtpSender+SendRtpArgs）、协议转换流水线。only_track 可加速单轨流；音频晚到时调大 wait_audio_track_data_ms。
16. WebRTC 传输与 ICE 会话
传输栈：WebRtcTransport（协调）、IceAgent（ICE 检查与候选）、IceServer（TURN）、DtlsTransport、SrtpSession、IceSession；与异步 I/O、媒体管线集成。
ICE 会话： 创建时 identifier=base64(ip+udp_port+tcp_port)+'_'+自增；用作 STUN 用户名片段。角色：PEER+WHEP 用 Lite 受控、CLIENT+WHIP 用 Full 控制；策略 kAll/kRelayOnly/kP2POnly 在连接检查前过滤。候选： Host、SRFLX（STUN）、RELAY（TURN）；gatheringCandidate 设置 IceServer 并收集；优先级 HOST>PRFLX>SRFLX>RELAY（RFC 8445）。状态机： Frozen→Waiting→InProgress→Succeeded/Failed→Nominated→Completed。STUN： USERNAME/MESSAGE-INTEGRITY、PRIORITY、USE-CANDIDATE、ICE-CONTROLLING/CONTROLLED、XOR-MAPPED-ADDRESS。TURN： ALLOCATE/REFRESH、CREATE-PERMISSION、CHANNEL-BIND；relayForwordingData/relayBackingData 转发。
DTLS： 双向认证、密钥协商、SRTP 密钥派生；状态 NEW→CONNECTING→CONNECTED/FAILED/CLOSED；SDP setup active/passive/actpass 决定角色。SRTP： 收/发双会话，AES-CM+HMAC-SHA1、AES-GCM；收路径 Socket→ICE→SRTP 解密→TWCC/NACK→媒体，发路径反向。配置： rtc.port/tcpPort、rtc.icePort/iceTcpPort、timeoutSec、enableTurn、iceTransportPolicy、iceUfrag/icePwd、externIP、preferred_tcp。集成： IceSessionManager（STUN 用户名→会话）；onGatheringCandidate、onIceTransportCompleted、OnDtlsTransportConnected、onRtp/onRtcp；getTransportInfo、收发速度与超时。
17. NACK 与 TWCC 实现
NACK 负责丢包恢复，TWCC 提供传输范围拥塞控制反馈；二者在 WebRTC 传输层内通过 RTP 拦截与 RTCP 反馈协同工作。
NACK： NackContext 监控 RTP 序列号检测丢包，处理序列号回绕、重传与重复过滤；makeNack() 按 RFC 4585 生成 PID+BLP 格式，视频/音频批量默认 8/4 包（nackRtpSize/nackAudioRtpSize）。NackList 维护重传缓存，时间与包数双限（默认 5000ms、2048 包）。重试逻辑：每丢包最多 15 次（nackMaxCount）、间隔为 RTT 倍数（nackIntervalRatio），NackStatus 跟踪请求计数，reSendNack() 定期重发。
TWCC： TwccContext 维护传输范围序列号与到达时间。checkSeqStatus() 处理正常递增、回绕与无效跳变。反馈触发条件：20 包或 256ms（以先到为准）；编码含参考时间（24 位、64ms 单位）、接收 delta（250μs 单位）、符号状态（2 位/包）。依赖 RTP 头部扩展 transport_cc，RtpExt/getTransportCCSeq 解析；扩展 URI 为 draft-holmer-rmcat-transport-wide-cc-extensions-01。
配置： rtc.maxRtpCacheMS/Size、rtc.nackMaxSize/MaxMS/MaxCount、rtc.nackIntervalRatio、rtc.nackRtpSize、rtc.nackAudioRtpSize。集成： WebRtcTransport 中 inputSockData → RtpExtContext → NackContext::received → 回调生成 RTCP NACK/TWCC → NackList::forEach 重传 → sendRtcpPacket。格式： FCI_NACK(pid, blp)；FCI_TWCC 可变长（基础序列、包状态计数、参考时间、包块 delta 编码）。性能： 每 100 包检查缓存、std::set 序列跟踪、双重限制防内存增长；错误处理含序列校验、回绕、重复过滤与状态清除。
18. WHIP/WHEP 协议支持
WHIP（WebRTC-HTTP 采集）与 WHEP（WebRTC-HTTP 播放）基于 HTTP 的标准化协议，无需自定义信令即可实现浏览器与服务器的 WebRTC 媒体交换。
端点： WHIP 推流 POST /index/api/whip（SDP Offer → 建立双向采集）；WHEP 播放 POST /index/api/whep（SDP Offer → 服务器到客户端单向）；会话终止 DELETE /index/api/delete_webrtc?id={session_id}&token={random_str}。统一处理函数 whip_whep_func(type=push/play)，经 WebRtcPluginManager 做 SDP 协商，WebRtcTransport 负责 ICE/DTLS/SRTP。
合规： POST 创建返回 201、Content-Type application/sdp、Location 含资源 URL（id+token）；DELETE 需 id+token 匹配，200/401/404；SDP 失败 406。会话： ServiceController 做注册/查找/清理；每会话唯一 id 与随机删除 token；safeShutdown 优雅释放。集成： WHIP 会话与 MediaSource 集成，自动多协议输出（RTSP/RTMP/HLS 等）；WebRtcArgsImp 连接 HTTP 参数与传输配置；信令抽象支持 HTTP(WHIP/WHEP) 与 WebSocket 并存。
流程： 客户端生成 SDP Offer → POST whip/whep（Content-Type: application/sdp）→ 201 + SDP Answer + Location → ICE/DTLS/SRTP 建立 → 媒体传输；终止时 DELETE Location URL。配置： 需 ENABLE_WEBRTC、OpenSSL、libsrtp；api.secret 保护端点；WebRTC 端口与编解码器配置通用。安全： API 认证、删除 token 防未授权终止、DTLS/SRTP 媒体加密；CORS 需按需配置。排错： 406 查编解码器、401 查 token、ICE 失败配 STUN/TURN；api.apiDebug=1 可打日志。WHIP 流可代理、录制、与 RTSP/GB28181 桥接。
19. 单端口多线程 WebRTC 架构
单端口架构通过基于 ICE 用户名的会话识别在单一 UDP/TCP 端口上复用大量 WebRTC 连接，配合 EventPoller 多线程实现高并发、低端口占用。
核心组件： WebRtcTransport（编排 DTLS/ICE/SRTP，标识符=服务器前缀+自增 key）；IceTransport（ICE 候选收集、连接检查、STUN）；DtlsTransport（DTLS 1.2、自签名证书、OpenSSL）。单端口解复用： 数据包到达共享端口 → 解析 STUN 取 ICE 用户名 → IceSessionManager 查会话 → 将包路由到该会话的 EventPoller 线程；queryIceTransport 用 StunPacket::parse + getUsername + getItem(username)。
配置： rtc.port/rtc.tcpPort 默认 8000；rtc.iceUfrag/rtc.icePwd（如 "ZLMediaKit"）；rtc.timeoutSec=15。多线程： 每传输绑定一个 EventPoller，queryPoller 在分发前按 STUN 用户名路由；IceSessionManager 用 mutex + unordered_map<username, weak_ptr<IceSession>> 做线程安全会话管理。
ICE： 支持 HOST/SRFLX/PRFLX/RELAY 候选及优先级计算（RFC 5245）；IceTransport::Pair 封装 socket、peer_host/port、TURN 时 relayed_addr。DTLS： DtlsEnvironment 单例管理证书与 SSL_CTX；状态 NEW→CONNECTING→CONNECTED/FAILED/CLOSED。生命周期： onCreate 中先建 DtlsTransport，再建 IceAgent（服务器 Full、WHEP/WHIP 客户端 Lite）；可选 ENABLE_SCTP 与 SctpAssociation 做数据通道。
性能： 单端口省 NAT 映射、线程池复用、每传输 64 个包池；水平扩展需多实例多端口（IceSessionManager 进程本地）。信令与策略： WHEP 消费者用 Lite、WHIP/WebSocket P2P 用 Full；rtc.iceTransportPolicy 支持 kAll/kRelayOnly/kP2POnly；TCP 回退可用。与 MediaSource、推拉流器、NACK/TWCC、数据通道回显集成。
20. MediaServer 架构概述
基于异步 I/O 的多协议流媒体平台，围绕与协议无关的 MediaSource 与多协议适配器构建。
初始化： main.cpp 中 start_main() 编排：命令行解析 → 日志（控制台/文件、轮转）→ 可选守护进程与崩溃捕获 → 异步日志写入 → loadIniConfig(config.ini)，拒绝默认 API secret、首次生成 32 字符 secret → 加载 SSL/TLS 证书（单文件或目录）。线程： EventPoller 网络 I/O 线程池 + WorkThreadPool 工作任务；--threads 控制 poller 数，可选 CPU 亲和性；I/O 与编解码分离以保持低延迟。
协议服务器： 各协议独立监听、共享媒体源；RTSP 554/322、RTMP 1935/19350、HTTP 80/443、Shell 9000、WebRTC UDP/TCP 8000、信令 8080/4433、ICE 3478、SRT 9000、RTP 代理 10000；会话类型 RtspSession、RtmpSession、HttpSession、WebRtcSession、WebRtcWebcosktSignalingSession、IceSession、SrtSession、RtpServer。媒体源： MediaSource + MediaTuple(schema/vhost/app/streamId)；MultiMediaSourceMuxer 统一帧并多格式输出；源类型含推流/拉流/文件/GB28181。代理： PlayerProxy（拉流、重试、重连）、PusherProxy（推流）；REST 动态增删。FFmpeg： FFmpegSource 子进程拉流并推入 MediaServer；FFmpegSnap 快照；config.ini 配命令模板。
API： WebApi 注册 URL→处理函数，支持 JSON/URL 编码，监听 kBroadcastHttpRequest；流管理、统计、流信息、配置、会话管理；secret 鉴权（本机可豁免）。WebHook： 异步 POST 到配置 URL；on_publish/on_unpublish/on_play/on_stop、on_record_mp4/on_record_hls、on_rtsp_auth、on_stream_changed 等；响应可拒绝发布或指定录制参数。录制： MP4 分段（mp4_save_path、可配时长）、HLS（m3u8+分段、HlsMediaSource 环形缓冲）。配置： config.ini 分 api/ffmpeg/protocol/general；SIGHUP 热重载；按需协议转换可关闭未用协议。信号： SIGINT/SIGTERM 优雅退出，SIGHUP 重载配置与证书；退出前注销 API/WebHook。性能： 按需转换、零拷贝帧分发、异步 I/O、paced_sender_ms、jemalloc、CPU 亲和性。
21. RESTful API 参考
基于注册式架构：端点初始化时注册到 s_map_api，api_regist() 支持多种处理函数签名；支持 URL 查询、表单、JSON 及同步/异步。
鉴权： 所有接口需 api.secret，CHECK_SECRET() 在逻辑前校验；可放在 query、form 或 JSON；WHIP/WHEP 删除端点为 token。响应： 统一 JSON：code（0 成功）、msg、data；错误码：-1 OtherFailed、-100 AuthFailed、-200 SqlFailed、-300 InvalidArgs、-400 Exception、-500 NotFound。
服务器： GET getServerConfig、POST setServerConfig（键值对即时生效并写回配置）、GET restartServer（优雅重启/SIGINT 或批处理）。流管理： GET getMediaList（schema/vhost/app/stream 过滤，含丢包等统计）、GET close_stream（schema/vhost/app/stream，支持强制/优雅）、startStreamProxy、close_stream 等。其他典型：录制启停、会话踢出、快照、WHIP/WHEP、流代理增删。详见 WebApi.cpp/WebApi.h 及官方 API 文档。
22. WebHook 事件系统
基于 NoticeCenter 的发布-订阅；内部事件触发向配置 URL 发送 HTTP POST（JSON），异步、非阻塞，带重试与超时。
配置 hook： hook.enable（总开关，需为 1）、hook.timeoutSec（默认 10）、hook.alive_interval、hook.retry、hook.retry_delay；各事件 URL 非空则启用，空则禁用；hook.stream_changed_schemas 过滤 on_stream_changed 协议。
认证类： on_publish（发布前，载荷含 app/stream/schema/vhost/ip/port/id/originType/params；响应 code=0 允许，可返回 enable_hls/enable_mp4/enable_rtsp/enable_rtmp）、on_play（播放前，可做访问控制）、on_rtsp_auth（RTSP 用户名密码，响应 encrypted+passwd）、on_http_access（HTTP 文件访问，含 path/params/header，响应 err/path/second，支持 Cookie 缓存）。流生命周期： on_stream_changed（regist true/false，schema/vhost/app/stream）、on_stream_none_reader（无观众超时，可自动关流）。另有 on_unpublish、on_stop、录制相关（on_record_mp4、on_record_hls 等）、服务器监控等共约 13 类。响应 code 非 0 可拒绝操作；用于鉴权、计费、录制策略与自动化。
23. 认证与安全机制
四层：应用级 API 安全、协议身份验证、传输加密、WebHook 外部授权。
HTTP API： api.secret，CHECK_SECRET() 校验；127.0.0.1 可豁免；restartServer、setServerConfig、closeStream、kick_sessions、getThreadsLoad 等均需 secret。WebHook 鉴权： on_publish/on_play 返回 code=0 允许、非 0 拒绝并可带 msg；on_rtsp_realm 决定是否需要认证（realm 非空），on_rtsp_auth 校验用户名密码（响应 encrypted+passwd）；请求异步执行不阻塞。RTSP： RFC 2326 摘要认证，realm 与凭证经 WebHook 查询。
WebRTC： DTLS 通道加密（DtlsEnvironment、自签名证书、指纹算法 SHA-1/224/256/384/512），SRTP 媒体加密（AES_CM_128_HMAC_SHA1_80/32、AEAD_AES_256/128_GCM）。SRT： PBKEYLEN 0/16/24/32 对应无加密/AES-128/192/256，基于密码的密钥派生与重放保护。实践： 更换默认 secret（≥32 字符）、启用 hook、WebHook 用 HTTPS、速率限制、强 SRT 密码、防火墙限制管理口、监控失败认证、DTLS 必开；可结合 JWT 等 token 减轻数据库压力。
24. 并发连接处理
三层：Event Poller Pool（I/O 多路复用，epoll/kqueue）、Work Thread Pool（CPU 密集）、会话管理层（各协议 Session 继承基类，与 MediaSource/MediaSink 交互）。
线程池： EventPollerPool::setPoolSize(threads)、WorkThreadPool::setPoolSize(threads)、enableCpuAffinity；threads 建议≈CPU 核数。会话： 每协议 TcpServer 创建监听，start<RtspSession> 等，共享同一 EventPoller 池；Session 实现 onRecv/onError/onManager、MediaSourceEvent（close、totalReaderCount、onReaderChanged、getOwnerPoller）。MediaSink： inputFrame、addTrack、addTrackCompleted，等轨道就绪再分发。优化： mergeWriteMS（写合并，非 0 增延迟换吞吐，低延迟用 0）；demand（hls/rtsp/rtmp/ts/fmp4 按需生成）；auto_close、streamNoneReaderDelayMS、on_stream_none_reader；maxStreamWaitMS（先播后推）；wait_track_ready_ms 等超时；flowThreshold、broadcast_player_count_changed。WebRTC/SRT： setOnCreateSocket 中 queryPoller(buf) 将包路由到会话所属 poller。其他： enable 关未用协议、fileBufSize、jemalloc。实践：轮询线程≈核数-1、专用机开 CPU 亲和、调超时与按需生成、监控流量与观众数。
25. 低延迟优化技术
网络、RTP、WebRTC 与缓冲多层面优化，在质量与稳定下最小化端到端延迟。
网络： general.mergeWriteMS=0 关闭合并写（最小延迟，CPU 更高）；protocol.paced_sender_ms=0 关闭步进发送，避免突发与排队延迟。RTP： rtp.lowLatency 控制到达即发或按帧聚合；rtp.videoMtuSize/audioMtuSize（默认 1400/600）平衡 MTU 与分片。WebRTC： NACK（nackMaxSize/MaxMS/MaxCount、nackIntervalRatio、nackRtpSize）可调；超低延迟建议 nackIntervalRatio 0.5--0.7、nackRtpSize 4。TWCC 按包数/时间间隔发报告，便于拥塞与比特率调整。
缓冲： wait_track_ready_ms、wait_audio_track_data_ms、wait_add_track_ms、unready_frame_cache 控制轨道就绪前等待与缓存；减小可降启动延迟。GOP： rtp_proxy.gop_cache 缓存最近 GOP，新观众即时起播。协议： rtsp.lowLatency=1 帧级即时传输；rtp_proxy.merge_frame 0 更快、1 更稳。按需： demand（hls/rtsp/rtmp/ts/fmp4）为 1 时按需生成，省资源但首观众略延迟。配置示例： 超低延迟（<100ms）mergeWriteMS=0、paced_sender_ms=0、rtsp.lowLatency=1、较小 wait 与 unready_frame_cache、nack 更激进；平衡型（100--300ms）可用默认或略保守。监控端到端延迟、丢包、抖动缓冲与 NACK 重传率、kBroadcastFlowReport 等。
26. 内存管理与抖动缓冲
ZLMediaKit 在零拷贝与智能引用计数之间做多层内存管理，核心是 Frame 抽象：统一数据接口，跨协议共享、带 DTS/PTS 与 cacheAble 等元数据；FrameImp 用 BufferLikeString，FrameFromPtr 包装外部缓冲区（不可缓存），FrameInternal 零拷贝分割复合帧（子帧持父帧 shared_ptr），FrameCacheAble 将不可缓存帧复制为可缓存以延长生命周期。JemallocUtil 提供分析/统计/堆转储；可选 ResourcePool 预分配 Frame 减少高吞吐下的 malloc，需权衡池大小。
抖动缓冲： PacketCache 按时间戳累积、可配置刷新策略（大小/时间/关键帧）；FlushPolicy 维护音视频时间戳。RTP 即使关闭合并写入仍会缓冲同时间戳包以减少 write 调用。RtpCache 派生：RtpCachePS（PS/TS，GB28181）、RtpCacheRaw（原始 RTP）；onFlushed 回调。WebRTC NACK： NackList 滑动窗口（deque + unordered_map），大小/时间双限（默认 2048 包、5000ms）；NackContext 做丢失检测与重传请求、指数退避；参数 kNackMaxSize、kNackMaxMS、kNackMaxCount、kNackIntervalRatio、kNackRtpSize（视频 8、音频 4）。
配置： General::kMergeWriteMS（合并写入最大缓冲 ms，0 禁用）、Rtsp::kLowLatency；Rtc::kMaxRtpCacheMS/Size、kNackMaxSize、kNackMaxMS、kNackMaxCount（mINI 可调）。高码率可增大 maxRtpCacheMS/Size、nackMaxSize；低延迟可减小缓存并接受略高丢包。扩展： 自定义帧从 FrameImp 派生或使用 FrameFromPtr/FrameCacheAble；自定义协议扩展 PacketCache、实现 onFlush/isFlushAble；NACK 集成需 NackContext received(seq)、onNack、NackList 与 forEach。监控： JemallocUtil 统计、NackContext 丢失率/恢复率/恢复时间、ObjectStatistic 跟踪 Frame 创建销毁。最佳实践：优先零拷贝、遵守 cacheAble 语义、按场景调缓存、先分析再优化、用真实负载验证。
27. 监控与统计收集
基于 REST 的监控与统计：getStatisticJson 聚合 20+ 类对象；分层收集（实例计数、全局内存、每线程）。
对象统计（ObjectStatistic）： 媒体（MediaSource、MultiMediaSourceMuxer）、网络（TcpServer/Session、UdpServer/Session、TcpClient、Socket）、媒体处理（Frame、FrameImp）、缓冲（Buffer、BufferRaw、BufferLikeString、BufferList）、协议包（RtpPacket、RtmpPacket）；线程安全原子计数。内存（ENABLE_MEM_DEBUG）： 总用量/块数、按大小分类、每线程内存与块类型分布；异步从 EventPollerPool/WorkThreadPool 收集，完成回调聚合。线程负载： getThreadsLoad（I/O 线程）、getWorkThreadsLoad（工作线程），每线程名称/延迟/队列深度；需 secret。会话： getAllSession（local_port、peer_ip 过滤）、kick_session、kick_sessions（防自终止）。流： getMediaList、isMediaOnline、getMediaInfo（编解码/码率/帧率/读者数）、getMediaPlayerList、close_stream/close_streams(force)。所有监控 API 需 api.secret；api.apiDebug 可打日志。可与仪表盘、告警、容量规划、排障集成。
28. C API SDK 概述
C 接口封装 ZLMediaKit 核心能力，供 C 或 FFI 语言（Python/Go/Java/C# 等）集成；分层：C++ 核心 → C API 封装 → 应用/绑定。
目录： api/include（mk_mediakit.h、mk_common.h、mk_player.h、mk_pusher.h、mk_media.h、mk_frame.h、mk_track.h、mk_events.h、mk_webrtc.h、mk_recorder.h、mk_rtp_server.h 等）、api/source、api/tests。初始化： mk_env_init()/mk_env_init2()（mk_config：线程数、日志、SSL）；mk_stop_all_server、mk_set_log、mk_ini_set_option。
模块概要： mk_player（create/play/pause/speed/seekto/seekto_pos、set_on_result/set_on_shutdown；on_mk_play_event 回传 mk_track 数组）。mk_pusher（create/create_src、publish、set_on_result/set_on_shutdown）。mk_media（create/create2、init_track/init_video/init_audio、input_frame、add_complete_config、release；直播 duration=0、点播>0）。mk_frame（create、ref/unref、get_codec_id/data/size/dts/pts、IS_KEY/IS_CONFIG/DROP_ABLE/NOT_DECODE_ABLE；编解码常量 MKCodec*）。mk_track（create、add_delegate、is_video、codec_name；on_mk_frame_out）。mk_events（on_mk_media_changed/publish/play/not_found/no_reader、on_mk_http_request、on_mk_log；mk_auth_invoker 批准/拒绝）。mk_webrtc（get_answer_sdp、add/del/list_room_keeper；echo/play/push 插件）。mk_recorder（flv/mp4 录制、mk_stop_all_record）。mk_rtp_server（GB28181、create/connect/get_port）。构建： CMake、libmk_api.so/DLL、API_EXPORT；Linux/Android/Windows/iOS/macOS。绑定： ctypes/cffi、cgo、JNI、P/Invoke；mk_ 前缀与引用计数便于 FFI。
29. 自定义播放器开发
协议与渲染解耦：播放器核心（连接与协议）、轨道系统（音视频分离）、帧通过委托回调交付。
C SDK： mk_player（创建、set_option、set_on_result/set_on_shutdown、play、release）、mk_track（add_delegate、is_video、codec_name、video_width/height/fps、audio_sample_rate/channel）、mk_frame（get_data/size、get_dts/pts、get_flags：IS_KEY/IS_CONFIG，回调外保留用 mk_frame_ref/unref）。选项： net_adapter、rtp_type、rtsp_user/rtsp_pwd、protocol_timeout_ms、media_timeout_ms、beat_interval_ms、wait_track_ready。流程： 创建→配置→设置回调→play(url)→on_play_result(err_code,tracks,track_count)，err_code==0 后对每 track 注册帧委托；帧在回调内处理，异步保留需 ref/unref。
编解码器： 视频 H.264/H.265(AnnexB)、VP8/VP9、AV1、JPEG；音频 AAC、G.711A/U、Opus、L16。点播： pause、speed、seekto(0~1)、seekto_pos(秒)、duration、progress、progress_pos。统计： mk_player_loss_rate、mk_track_frames/duration/bit_rate、视频 key_frames/gop_size/gop_interval。帧合并： mk_frame_merger_create、合并回调；集成 SDL2/FFmpeg 解码与重采样见 test_player。排错：超时查 URL/protocol_timeout_ms、认证查 rtsp_user/pwd、无帧查编解码与配置帧、绿屏先处理 SPS/PPS、延迟可调 media_timeout_ms 与 wait_track_ready=0。
30. 自定义推流器开发
分层设计：协议逻辑与通用操作分离；工厂按 URL scheme 选择实现，接口一致。
PusherBase： 抽象基类（继承 mINI 可配项）；publish(url)、teardown()、setOnPublished、setOnShutdown、getSendSpeed、getSendTotalBytes。createPusher(poller, src, url)： 工厂根据 scheme 实例化；支持 rtsp/rtsps→RtspMediaSource、rtmp/rtmps→RtmpMediaSource、srt→TSMediaSource、webrtc/webrtcs→RtspMediaSource；MediaSource 类型与 scheme 不匹配会抛 invalid_argument。MediaPusher： 用 PusherImp 模板委托；构造 MediaPusher(schema,vhost,app,stream,poller) 或 MediaPusher(src,poller)；setOnCreateSocket、EventPoller 集成。PusherProxy： 继承 MediaPusher，自动重试、指数退避（delay=max(2s, min(fail*3s, 60s))），retry_count<0 无限重试；getStatus、getLiveSecs、getRePublishCount。
自定义步骤： 继承 PusherBase 或用 PusherImp<PusherBase,PusherBase>，实现 publish（解析 URL、建连、握手、从 MediaSource 推帧）、teardown、getSendSpeed/getSendTotalBytes，重写 onPublishResult、onShutdown；在 createPusher 中增加 scheme 分支并做 MediaSource 类型校验。扩展协议时需同时扩展对应 MediaSource 与工厂注册。
31. 扩展协议支持
基于工厂模式与编解码器插件，运行时注册新编解码器/协议，协议逻辑与核心媒体处理分离。
CodecPlugin： getCodec、getTrackByCodecId/getTrackBySdp、getRtpEncoderByCodecId/getRtpDecoderByCodecId、getRtmpEncoderByTrack/getRtmpDecoderByTrack、getFrameFromPtr；Factory 作为中央注册表委托给插件。Track： 协议无关的轨道抽象，封装编解码元数据及 SDP/附加数据。
自定义编解码器步骤： ① 帧类：继承 FrameImp 或 FrameFromPtr，实现 keyFrame/configFrame/dropAble/decodeAble，设 _codec_id。② 轨道类：继承 VideoTrack/AudioTrack，实现 ready、getCodecId、getVideoWidth/Height/Fps 或音频等价、inputFrame、getExtraData/setExtraData、getConfigFrames、getSdp、clone。③ RTP：RtpCodec 子类实现 inputFrame（拆包/组包）、payload_type、sample_rate。④ 在 Factory 中注册 CodecPlugin，填齐上述函数指针。协议扩展需对应 MediaSource、Session、PusherBase::createPusher 等（参见自定义推流器与协议实现文档）。
32. 集群部署与负载均衡
边缘-源站架构：边缘处理客户端连接，按需从源站拉流；pullStreamFromOrigin 实现自动流追踪（kBroadcastNotFoundStream 监听）。
cluster 配置： origin_url（printf 模板，%s/%s 为 app/stream，支持 rtmp/rtsp/hls/http-ts；多源站用分号分隔）、timeout_sec（总超时，按源站数均分）、retry_count（0 不重试、正数次数、-1 无限）。追踪流程： 配置 origin_url 时绕过 on_stream_not_found；getPullUrl 附加 edge=1 与 vhost 标识边缘；轮询故障转移：单源超时=timeout_sec/源数，按索引依次尝试，失败则下一源，全失败则报错；原子计数器做负载分配。流生命周期： 无观众时 kBroadcastStreamNoneReader 对 MediaOriginType::pull 的边拉流自动关闭；遵循 protocol.auto_close，可绕过 on_stream_none_reader。
PlayerProxy： 拉流实现，retry_count、reconnect_delay_min/max/step 指数退避；getTranslationInfo 含编解码与传输统计。部署模式： 单源、多源主备、多源主主（轮询分配）。注意： maxStreamWaitMS 宜比 cluster 总超时大约 20--30%；mediaServerId、hook_index、日志便于监控；集群下 on_stream_not_found/on_stream_none_reader 被替代，on_publish/on_play 仍触发；vhost 与 http.allow_ip_range 支持多租户与访问控制。
33. 虚拟主机配置
多租户：流按 schema://vhost/app/stream_id 组织；vhost 隔离媒体资源、配置与鉴权。
启用： general enableVhost=1；为 0 时统一使用 defaultVhost 。配置： vhost_name 下可覆盖 protocol、hook、http、record、rtc 等；优先级 vhost 节 → 全局节 → 默认。MediaTuple： vhost、app、stream_id、params；源注册表分层 SchemaVhostAppStreamMap→VhostAppStreamMap→AppStreamMap→StreamMap；未启用或 vhost 为空则用 DEFAULT_VHOST。
URL： 启用后需带 vhost，如 ?vhost=vhost1.example.com（RTMP/RTSP/HTTP-FLV/HLS/WebRTC 等）。每 vhost 可配： 协议（modify_stamp、enable_audio、continue_push_ms 等）、Hook（on_publish/on_play/on_stream_not_found）、HTTP（rootPath、virtualPath、notFound）、录制（appName、fileBufSize、sampleMS）、RTC（externIP、preferredCodec、iceUfrag/icePwd）。事件： kBroadcastHttpBeforeAccess 可依 vhost 改 path；MediaInfo 含 vhost，WebHook 鉴权须校验 vhost 防越权。重载： kBroadcastReloadConfig 支持运行时更新 vhost 配置；已有流沿用旧配置直至重新注册。查找 O(1) 层级；迁移时可将原配置放入 **defaultVhost**，URL 加 ?vhost=。