first doc
This commit is contained in:
commit
1300b62958
|
|
@ -0,0 +1,82 @@
|
||||||
|
# ZLMediaKit 架构文档
|
||||||
|
|
||||||
|
## 1. 项目概述
|
||||||
|
ZLMediaKit 是一个高性能流媒体服务器框架，支持 RTMP/RTSP/WebRTC/SRT 等多种协议，采用 C++11 编写，具有跨平台、高并发、低延迟等特点。
|
||||||
|
|
||||||
|
## 2. 核心模块架构
|
||||||
|
|
||||||
|
### 2.1 基础设施层
|
||||||
|
- **`3rdpart/ZLToolKit`**
|
||||||
|
- 网络库基础：提供 [Socket](3rdpart/ZLToolKit/src/network/Socket.h)、[EventPoller](3rdpart/ZLToolKit/src/poller/EventPoller.h) 等核心组件
|
||||||
|
- 内存管理：[ObjectPool](3rdpart/ZLToolKit/src/util/ObjectPool.h) 对象池实现
|
||||||
|
|
||||||
|
- **`src/Common`**
|
||||||
|
- 配置系统：[config.cpp](src/Common/config.cpp) 实现 `MediaServer` 配置项管理
|
||||||
|
- 工具集：[Util.cpp](src/Common/Util.cpp) 提供时间处理、Base64 编码等通用功能
|
||||||
|
- 日志系统：[Logger.cpp](src/Common/Logger.cpp) 实现多级日志输出
|
||||||
|
|
||||||
|
### 2.2 协议处理层
|
||||||
|
|
||||||
|
#### RTMP 协议栈
|
||||||
|
- **`src/Rtmp`**
|
||||||
|
- 协议解析：[RtmpProtocol.cpp](src/Rtmp/RtmpProtocol.cpp) 实现 AMF0 解析
|
||||||
|
- 会话管理：[RtmpSession.cpp](src/Rtmp/RtmpSession.cpp) 处理推流/拉流会话
|
||||||
|
- 转发服务：[RtmpMuxer.cpp](src/Rtmp/RtmpMuxer.cpp) 实现流媒体转发
|
||||||
|
|
||||||
|
#### RTSP 协议栈
|
||||||
|
- **`src/Rtsp`**
|
||||||
|
- 信令处理：[RtspSession.cpp](src/Rtsp/RtspSession.cpp) 实现 SETUP/PLAY/TEARDOWN 等方法
|
||||||
|
- 传输层：[RtpProcess.cpp](src/Rtsp/RtpProcess.cpp) 处理 RTP/RTCP 传输
|
||||||
|
|
||||||
|
#### WebRTC 协议栈
|
||||||
|
- **`webrtc` 目录**
|
||||||
|
- 信令交互：[WebRtcSignalingSession.cpp](webrtc/WebRtcSignalingSession.cpp)
|
||||||
|
- 媒体传输：[DtlsTransport.cpp](webrtc/DtlsTransport.cpp) 和 [SrtpSession.cpp](webrtc/SrtpSession.cpp)
|
||||||
|
- ICE 处理：[IceTransport.cpp](webrtc/IceTransport.cpp)
|
||||||
|
|
||||||
|
#### SRT 协议支持
|
||||||
|
- **`srt` 目录**
|
||||||
|
- 核心传输：[SrtTransport.cpp](srt/SrtTransport.cpp)
|
||||||
|
- 会话管理：[SrtSession.cpp](srt/SrtSession.cpp)
|
||||||
|
- 重传机制：[NackContext.cpp](srt/NackContext.cpp)
|
||||||
|
|
||||||
|
### 2.3 媒体处理层
|
||||||
|
|
||||||
|
#### 编解码模块
|
||||||
|
- **`ext-codec` 目录**
|
||||||
|
- 视频编解码：[H264.cpp](ext-codec/H264.cpp) 和 [H265.cpp](ext-codec/H265.cpp)
|
||||||
|
- 音频编解码：[AAC.cpp](ext-codec/AAC.cpp) 和 [G711.cpp](ext-codec/G711.cpp)
|
||||||
|
- 封装处理：[H264Rtmp.cpp](ext-codec/H264Rtmp.cpp) 实现 RTMP 封装
|
||||||
|
|
||||||
|
- **`src/Codec` 目录**
|
||||||
|
- 软件编解码：[SoftDecoder.cpp](src/Codec/SoftDecoder.cpp)
|
||||||
|
- 硬件加速：[Hardware.cpp](src/Codec/Hardware.cpp)
|
||||||
|
|
||||||
|
#### 流媒体处理
|
||||||
|
- **`src/Player`**
|
||||||
|
- 播放器核心：[PlayerBase.cpp](src/Player/PlayerBase.cpp)
|
||||||
|
- 协议适配：[RtspPlayer.cpp](src/Player/RtspPlayer.cpp)
|
||||||
|
|
||||||
|
- **`src/Pusher`**
|
||||||
|
- 推流器实现：[RtmpPusher.cpp](src/Pusher/RtmpPusher.cpp)
|
||||||
|
- 协议转换：[FlvMuxer.cpp](src/Pusher/FlvMuxer.cpp)
|
||||||
|
|
||||||
|
### 2.4 服务管理层
|
||||||
|
|
||||||
|
- **`server` 目录**
|
||||||
|
- 主服务入口：[main.cpp](server/main.cpp)
|
||||||
|
- Web API：[WebApi.cpp](server/WebApi.cpp) 实现 RESTful 接口
|
||||||
|
- 事件回调：[WebHook.cpp](server/WebHook.cpp) 处理业务事件
|
||||||
|
|
||||||
|
- **`api` 目录**
|
||||||
|
- 接口定义：[include/api-api.h](api/include/api-api.h)
|
||||||
|
- 测试用例：[tests/test_httpApi.cpp](api/tests/test_httpApi.cpp)
|
||||||
|
|
||||||
|
## 3. 扩展能力
|
||||||
|
- **`player` 目录**：SDL 音频输出 ([SDLAudioDevice.cpp](player/SDLAudioDevice.cpp)) 和 YUV 渲染
|
||||||
|
- **`FFmpegSource.cpp`**：基于 FFmpeg 的媒体源处理
|
||||||
|
- **`docker` 支持**：通过 [build_docker_images.sh](docker/build_docker_images.sh) 构建容器镜像
|
||||||
|
|
||||||
|
## 4. 测试体系
|
||||||
|
- **`tests` 目录**：协议测试 ([test_rtmp.cpp](tests/test_rtmp.cpp)) 和性能测试 ([test_bench.cpp](tests/test_bench.cpp))
|
||||||
|
- **`postman` 集合**：[ZLMediaKit.postman_collection.json](postman/ZLMediaKit.postman_collection.json) 提供 API 测试用例
|
||||||
|
|
@ -0,0 +1,162 @@
|
||||||
|
# Frame 模块设计与实现
|
||||||
|
|
||||||
|
## 1. 模块概述
|
||||||
|
`Frame.h`/`Frame.cpp` 是 ZLMediaKit 中处理媒体帧的核心模块，提供统一的帧数据抽象、时间戳管理、编解码信息转换和帧合并功能。该模块通过面向对象设计实现协议无关的媒体帧处理，支撑 RTMP/RTSP/WebRTC 等多种协议的媒体传输。
|
||||||
|
|
||||||
|
## 2. 核心数据结构
|
||||||
|
|
||||||
|
### 2.1 媒体类型定义
|
||||||
|
|
||||||
|
#### 2.1.1 轨道类型（[TrackType](src/Extension/Frame.h#L20-L28)）
|
||||||
|
```cpp
|
||||||
|
enum {
|
||||||
|
TrackInvalid = -1,
|
||||||
|
TrackVideo = 0, // 视频轨道
|
||||||
|
TrackAudio, // 音频轨道
|
||||||
|
TrackTitle, // 字幕轨道
|
||||||
|
TrackApplication // 应用数据轨道
|
||||||
|
};
|
||||||
|
```
|
||||||
|
- **功能**：区分媒体数据的逻辑类型
|
||||||
|
- **使用场景**：流媒体会话建立时标识数据类型
|
||||||
|
|
||||||
|
#### 2.1.2 编解码标识（[CodecId](src/Extension/Frame.h#L54-L78)）
|
||||||
|
```cpp
|
||||||
|
#define CODEC_MAP(XX) \
|
||||||
|
XX(CodecH264, TrackVideo, 0, "H264", PSI_STREAM_H264, MOV_OBJECT_H264) \
|
||||||
|
// ... 其他编解码定义
|
||||||
|
|
||||||
|
typedef enum {
|
||||||
|
CodecInvalid = -1,
|
||||||
|
CODEC_MAP(XX)
|
||||||
|
CodecMax
|
||||||
|
} CodecId;
|
||||||
|
```
|
||||||
|
- **特点**：
|
||||||
|
- 通过宏定义统一管理编解码参数
|
||||||
|
- 包含协议标识（mpeg_id）、容器标识（mp4_id）等扩展信息
|
||||||
|
- **关键函数**：
|
||||||
|
- `[getTrackType(CodecId)](src/Extension/Frame.cpp#L15-L23)`：获取轨道类型
|
||||||
|
- `[getMovIdByCodec()](src/Extension/Frame.cpp#L35-L43)`：获取 MP4 容器标识
|
||||||
|
- `[getMpegIdByCodec()](src/Extension/Frame.cpp#L70-L78)`：获取 MPEG-TS 标识
|
||||||
|
|
||||||
|
### 2.2 帧抽象基类（[Frame](src/Extension/Frame.h#L137-L177)）
|
||||||
|
```cpp
|
||||||
|
class Frame : public toolkit::Buffer, public CodecInfo {
|
||||||
|
virtual uint64_t dts() const = 0; // 解码时间戳
|
||||||
|
virtual uint64_t pts() const; // 显示时间戳
|
||||||
|
virtual size_t prefixSize() const = 0; // 帧前缀长度
|
||||||
|
virtual bool keyFrame() const = 0; // 是否关键帧
|
||||||
|
virtual bool configFrame() const = 0; // 是否配置帧(sps/pps)
|
||||||
|
virtual bool cacheAble() const; // 是否可缓存
|
||||||
|
};
|
||||||
|
```
|
||||||
|
- **设计要点**：
|
||||||
|
- 继承自 `Buffer` 实现内存管理
|
||||||
|
- 通过 `CodecInfo` 关联编解码信息
|
||||||
|
- 所有方法均为虚函数支持多态操作
|
||||||
|
- **典型派生类**：
|
||||||
|
|
||||||
|
| 类名 | 作用 | 实现文件 |
|
||||||
|
|------|------|----------|
|
||||||
|
| `[FrameImp](src/Extension/Frame.h#L191-L220)` | 基础帧实现 | Frame.h |
|
||||||
|
| `[FrameFromPtr](src/Extension/Frame.h#L233-L263)` | 指针包装帧（不可缓存） | Frame.h |
|
||||||
|
| `[FrameCacheAble](src/Extension/Frame.h#L336-L367)` | 可缓存帧包装 | Frame.h |
|
||||||
|
| `[FrameStamp](src/Extension/Frame.h#L381-L407)` | 时间戳覆盖实现 | Frame.h |
|
||||||
|
|
||||||
|
## 3. 核心处理工具
|
||||||
|
|
||||||
|
### 3.1 帧合并器（[FrameMerger](src/Extension/Frame.cpp#L235-L338)）
|
||||||
|
```cpp
|
||||||
|
class FrameMerger {
|
||||||
|
enum { none, h264_prefix, mp4_nal_size };
|
||||||
|
bool inputFrame(const Frame::Ptr &frame, onOutput cb, BufferLikeString *buffer = nullptr);
|
||||||
|
void flush();
|
||||||
|
};
|
||||||
|
```
|
||||||
|
- **核心功能**：
|
||||||
|
- 合并时间戳相同的帧（如 AAC 复合帧）
|
||||||
|
- 支持三种输出模式：
|
||||||
|
- `none`：原始数据拼接（用于 PS 流）
|
||||||
|
- `h264_prefix`：添加 `00 00 00 01` 前缀
|
||||||
|
- `mp4_nal_size`：添加 4 字节 NALU 长度
|
||||||
|
- **工作流程**：
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
A[输入帧] --> B{是否需要合并?}
|
||||||
|
B -->|是| C[缓存帧]
|
||||||
|
B -->|否| D[直接输出]
|
||||||
|
C --> E{是否触发flush?}
|
||||||
|
E -->|是| F[合并输出]
|
||||||
|
E -->|否| C
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 帧分发器（[FrameDispatcher](src/Extension/Frame.h#L465-L526)）
|
||||||
|
```cpp
|
||||||
|
class FrameDispatcher : public FrameWriterInterface {
|
||||||
|
FrameWriterInterface* addDelegate(FrameWriterInterface::Ptr delegate);
|
||||||
|
bool inputFrame(const Frame::Ptr &frame) override;
|
||||||
|
};
|
||||||
|
```
|
||||||
|
- **设计特点**：
|
||||||
|
- 代理模式实现多路帧分发
|
||||||
|
- 线程安全的递归锁保护
|
||||||
|
- 自动统计 GOP 信息（`_gop_size`, `_gop_interval_ms`）
|
||||||
|
- **典型应用场景**：
|
||||||
|
- 同时推送到 RTMP 服务器和 HLS 切片
|
||||||
|
- 媒体流录制与实时分析并行处理
|
||||||
|
|
||||||
|
## 4. 关键方法解析
|
||||||
|
|
||||||
|
### 4.1 帧缓存转换（[getCacheAbleFrame](src/Extension/Frame.cpp#L9-L13)）
|
||||||
|
```cpp
|
||||||
|
Frame::Ptr Frame::getCacheAbleFrame(const Frame::Ptr &frame){
|
||||||
|
if(frame->cacheAble()) return frame;
|
||||||
|
return std::make_shared<FrameCacheAble>(frame);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
- **解决痛点**：原始帧可能指向临时内存（如网络包缓冲区），通过 `FrameCacheAble` 复制数据确保生命周期
|
||||||
|
- **性能优化**：仅当 `cacheAble()=false` 时进行深拷贝
|
||||||
|
|
||||||
|
### 4.2 时间戳修正（[FrameStamp](src/Extension/Frame.cpp#L27-L33)）
|
||||||
|
```cpp
|
||||||
|
FrameStamp::FrameStamp(Frame::Ptr frame, Stamp &stamp, int modify_stamp) {
|
||||||
|
stamp.revise(frame->dts(), frame->pts(), _dts, _pts,
|
||||||
|
modify_stamp == ProtocolOption::kModifyStampSystem);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
- **时间戳模式**：
|
||||||
|
- `kModifyStampSystem`：使用系统绝对时间戳
|
||||||
|
- `kModifyStampRelative`：保持相对时间戳
|
||||||
|
- **应用场景**：
|
||||||
|
- 播放器同步控制
|
||||||
|
- WebRTC 中的 RTP 时间戳转换
|
||||||
|
|
||||||
|
## 5. 使用示例
|
||||||
|
|
||||||
|
### 5.1 创建可缓存帧
|
||||||
|
```cpp
|
||||||
|
// 从网络包创建原始帧（不可缓存）
|
||||||
|
auto raw_frame = std::make_shared<FrameFromPtr>(
|
||||||
|
CodecH264, ptr, size, dts, pts, 4, is_key);
|
||||||
|
|
||||||
|
// 转换为可缓存帧（自动深拷贝）
|
||||||
|
Frame::Ptr cache_frame = Frame::getCacheAbleFrame(raw_frame);
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.2 合并 H.264 帧
|
||||||
|
```cpp
|
||||||
|
FrameMerger merger(FrameMerger::h264_prefix);
|
||||||
|
merger.inputFrame(frame1, [](uint64_t dts, uint64_t pts, Buffer::Ptr buffer, bool key) {
|
||||||
|
// 处理合并后的完整帧
|
||||||
|
rtmp_muxer->inputFrame(buffer, dts, pts, key);
|
||||||
|
});
|
||||||
|
merger.inputFrame(frame2);
|
||||||
|
merger.flush(); // 强制输出剩余缓存
|
||||||
|
```
|
||||||
|
|
||||||
|
## 6. 设计哲学
|
||||||
|
1. **零拷贝优先**：通过 `FrameInternal` 等类避免不必要的内存复制
|
||||||
|
2. **协议无关性**：帧操作不依赖具体传输协议
|
||||||
|
3. **资源精确控制**：通过 `cacheAble()` 明确内存生命周期
|
||||||
|
4. **扩展性设计**：宏定义 `CODEC_MAP` 支持便捷添加新编解码器
|
||||||
Loading…
Reference in New Issue