第一部分：RDK X5 运行 decode2display 演示程序完整步骤

环境：RDK X5 Ubuntu 系统，官方 hobot-multimedia 多媒体 SDK 示例

1. 前置条件

1）开发板系统镜像已预装 hobot-multimedia 多媒体库； 2）准备码流文件：.h264 / .h265 裸流文件（建议码流内置 SPS/PPS，防止花屏）； 3）HDMI 显示器接 RDK X5，确认显示输出正常； 4）安装编译依赖：

bash

运行

sudo apt update
sudo apt install cmake gcc g++

2. 获取源码

官方多媒体示例默认路径：

plaintext

/opt/tros/share/hobot-multimedia/sample/

示例目录：sample_decode2display

3. 编译示例

bash

运行

cd /opt/tros/share/hobot-multimedia/sample/sample_decode2display
mkdir build && cd build
cmake ..
make -j4

编译生成可执行文件 sample_decode2display

4. 启动程序

bash

运行

# 播放h265裸流
./sample_decode2display -i test.h265 -t 1
# 参数说明
# -i 输入码流文件路径
# -t 码流类型：0:H264  1:H265

5. 常见故障

1. 黑屏：先启动显示后启动解码器；检查分辨率是否超出 VO 硬件支持范围；
2. 花屏：裸流缺少 SPS/PPS，建议使用 mp4 提取带参数集的码流；
3. 权限报错：加上sudo运行；
4. 画面卡顿：调大解码器缓存队列深度。

---

第二部分：RDK X5 rtsp2display 演示（RTSP 流 → 硬解码 → HDMI 直显）

一、rtsp2display Demo 功能

rtsp2display 基于 hobot-multimedia + ffmpeg/RTSP 拉流组件，在 decode2display 基础上，把本地文件读取替换为网络 RTSP 实时拉流。

1. RTSP 客户端拉流：从 IPC、视频服务器接收 RTSP 网络 H264/H265 码流；
2. VPU 硬件解码：接收网络 NAL 码流送入硬件解码器，输出 NV12；
3. 硬件零拷贝链路：Decoder → VO Display，直接 HDMI 输出；
4. 全程图像数据硬件流转，CPU 仅负责网络接收、码流切片、模块调度（通信与调度）；
5. 支持实时监控预览，可扩展 splitter 分流：一路预览、一路送入 BPU 做 AI 检测。

和 decode2display 核心差异： decode2display：数据源 = 本地码流文件 rtsp2display：数据源 = 网络 RTSP 实时流

二、Demo 设计目标

1. 验证网络实时视频流 + 硬件多媒体流水线整套通路，适配机器人外接网络摄像头场景；
2. 验证实时流时序控制、网络抖动下缓冲区策略，保证画面流畅；
3. 提供网络摄像头实时预览标准工程模板；
4. 实现低 CPU 占用，不抢占 ROS2、运动控制算力资源。

三、完整代码执行流程

阶段 1：全局初始化

1. hobot_mm_init() 初始化多媒体框架，管理硬件连续物理内存；
2. 解析入参：RTSP 地址、编码类型 (H264/H265)、显示窗口参数；
3. 初始化 RTSP 客户端，建立网络套接字，配置接收缓冲区，用于对抗网络抖动。

阶段 2：创建多媒体模块实例（和 decode2display 一致）

1. 创建 Decoder 解码器实例，输出格式 NV12；
2. 创建 Display 显示实例，绑定 HDMI 输出；

阶段 3：模块绑定

plaintext

Decoder → Display
hobot_mm_bind(decoder_out_port, display_in_port)

如需 AI 推理拓展：Decoder → Splitter，一路 Display，一路 DNN (BPU)。

阶段 4：启动链路（固定顺序）

1. hobot_mm_start_display() 先启动显示；
2. hobot_mm_start_decoder() 启动解码器等待码流输入。

阶段 5：主线程【核心循环：RTSP 拉流 + 送码流至解码器】

plaintext

while(程序未收到退出信号)
{
    1. RTSP客户端持续接收网络RTP数据包；
    2. 组包、拼接成完整H264/H265 NAL单元；
    3. 调用 decoder_input() 将NAL码流送入硬件VPU解码器；
    4. VPU硬件解码生成NV12图像帧；
    5. NV12帧通过共享buffer自动流转到VO；
    6. VO硬件缩放、色域转换，HDMI输出画面；
}

重点区别： decode2display 从磁盘文件读 NAL； rtsp2display 从网络 socket 接收、组装 NAL。

阶段 6：退出触发（Ctrl+C / 网络断开）

1. 停止 RTSP 拉流，关闭网络连接；
2. 发送解码结束指令，排空解码器缓存帧；
3. hobot_mm_stop_decoder() → hobot_mm_stop_display()

阶段 7：逆序释放所有资源

1. unbind 模块连接；
2. 销毁 decoder、display 实例；
3. hobot_mm_deinit()，释放硬件内存；
4. 关闭 RTSP 客户端。

四、工程关键难点（落地重点）

1. 网络抖动处理 网络流存在时延波动，必须设置解码器内部缓冲队列，队列过长增加延迟；队列太短容易丢帧。
2. NAL 重组 RTSP RTP 分片传输，一段图像 NAL 会被拆成多个网络包；代码必须完成分片重组，不能直接送入解码器，否则解码花屏。
3. SPS/PPS 周期下发 网络长时间断开重连后，解码器丢失参数集，需要定时向解码器重新送入 SPS/PPS。
4. 时钟同步 实时预览场景需要丢弃过时帧，防止画面累积延迟持续走高。

五、总结：

rtsp2display 在 decode2display 硬件直显架构基础上，将数据源由本地码流文件替换为网络 RTSP 视频流。程序先初始化多媒体框架，创建解码器与显示模块并完成绑定；先启动显示，再启动解码器。主线程持续从网络拉取 RTSP 码流，完成数据包重组后送入硬件 VPU 解码，生成 NV12 图像直接通过硬件通道输出至 HDMI 显示器。程序退出后逆序停止模块并释放硬件资源。该示例验证网络摄像头实时预览硬件流水线，适合机器人外接网络相机监控场景。