本说明介绍如何在 HMI 项目中播放 RTSP / 本地视频、控制画面、截图和录像,并补充 USB 摄像头、统一网页和多路配置的使用方法。
2026-11-02 更新:USB 摄像头请先阅读文末 USB 摄像头与统一视频网页,下载配套完整更新包及 C/C++ SDK。以下原安装包和 video_* 示例适用于 RTSP / 本地视频方案。
安装说明
安装/升级固件
将以下安装包解压至U盘根目录。U盘不要包含其他文件,U盘限制格式为Fat32,内存32G及以下
U盘根目录下包含以下内容

将U盘插到屏上,屏幕会自动下载固件,等待更新即可
使用前提
使用前提与视频要求
使用前,请根据视频分辨率设置 MMA:
| 播放内容 | MMA 设置 | 使用说明 |
|---|---|---|
| 1080P 流媒体或本地视频 | 44 | 1080P 主码流最多同时播放一路,最高支持 1920×1080 |
| 720P 及以下的视频或辅码流 | 24 | 日常使用建议优先选择辅码流,减少资源占用 |
设置示例:
Util::setMmaSize(44); // 播放 1080P 视频
或:
Util::setMmaSize(24); // 播放 720P 及以下的视频或辅码流
播放本地 1080P 视频前,请将视频转换为以下规格:
- 编码: H.264,Baseline,Level 4.0。
- 画面: 1920×1080,24 帧/秒,8 位 YUV420P。
- 压缩设置: 关闭 B 帧,参考帧设为 1,关键帧间隔设为 48 帧。
- 画质与码率: CRF 23,最大码率 4 Mbps,缓冲区 8 Mb。
- 音频: 移除音频,仅保留视频画面。
原视频服务提供 1~4 个通道,实际同时播放数量取决于分辨率、编码和可用资源;1080P 主码流按上表最多一路。播放前应先测试摄像头码流是否正常显示,日常建议优先使用 720P 及以下辅码流。USB 摄像头的路数和带宽限制见文末增补章节。
API说明
在需要使用视频功能的文件中包含:
#include "HmiVideo.h"
头文件.zip

基本调用顺序如下:
| 使用时机 | 调用内容 |
|---|---|
| 应用启动 | video_start(),初始化一次 |
| 进入视频页面 | video_play(...),开始播放 |
| 点击功能按钮 | 调用截图、录像等接口 |
| 离开视频页面 | 按需要停止录像和播放 |
| 应用退出 | 先确认停止操作完成,再调用 video_shutdown() |
下面的代码分别放在对应事件中,不能全部放在一个按钮里连续执行。
初始化视频
如果使用视频 请将该启动放在HmiApp.cpp的onReady函数里面
/********************************
*
* 构建应用后调用此函数
*
* 注意:用户可添加代码
*
********************************/
void HmiApp::onReady(){
Util::setMmaSize(44);
// 立即返回,服务启动和后续命令由封装内部按顺序执行。
video_start();
}
/********************************
*
* 应用退出前调用此函数
*
* 注意:用户可添加代码
*
********************************/
void HmiApp::onQuit(){
video_shutdown();
}
播放视频
播放之前 需要将 视频的位置设置成以下格式
坐标 x y必须是偶数 视频 w大于 0,且是 32 的倍数 h为偶数
目前程序中 不符合要求的参数会自动匹配成符合要求的参数
video_play(1, "rtsp://user:password@192.168.1.10:554/stream",32, 88, 960, 500,0);
这表示:使用第 1 路通道,在屏幕坐标 (32, 88) 的位置播放视频,画面宽 960、高 500,不旋转。
常用参数说明
| 参数 | 通俗说明 | 填写要求 |
|---|---|---|
channel |
第几路视频 | 1~4,单路通常填 1 |
url |
视频地址 | RTSP 地址、存储设备文件地址或允许的板端绝对路径 |
x、y |
画面左上角的位置 | 非负偶数,单位为像素 |
width |
画面显示宽度 | 大于 0,且为 32 的倍数 |
height |
画面显示高度 | 大于 0,且为偶数 |
rotation |
顺时针旋转角度 | 0、90、180、270,默认 0 |
播放指定视频文件
//u盘下1.mp4文件
//指定路径
video_play(1, "/vendor/udisk_sda1/1.mp4", 32, 88, 960, 500);
//自动路径
video_play(1, "storage://usb/1.mp4", 32, 88, 960, 500);
//sd卡下1.mp4文件
//指定路径
video_play(1, "/vendor/sd/1.mp4", 32, 88, 960, 500);
//自动路径
video_play(1, "storage://sd/1.mp4", 32, 88, 960, 500);
停止视频
// 停止一路视频
video_stop(1);
// 停止所有视频
video_stop_all();
刷新视频
先停止指定通道,停止成功后,再按给定参数重新播放。
video_refresh(1,"rtsp://user:password@192.168.1.10:554/stream",32, 88, 960, 500, 0);
视频截图
video_snapshot(1);
表示对第 1 路截图,自动选择保存位置,不添加文字。
完整调用方式:
// 保存到U盘
video_snapshot(1, "设备运行正常", "usb", 24, "bottom");
// 保存到SD卡
video_snapshot(1, "设备运行正常", "sd", 24, "bottom");
| 参数 | 含义 |
|---|---|
1 |
对第 1 路截图 |
"设备运行正常" |
图片上的文字,填 "" 表示不加文字 |
"usb" |
保存到 U 盘 sd卡为“sd” 默认为“” |
24 |
字号,范围 12~96 |
"bottom" |
文字放在底部,"top" 表示顶部 |
文字使用 UTF-8 编码,最多 512 字节,可以用 \n 换行。默认字号为 24,位置为底部。
文字只出现在保存的 JPEG 图片上,不会加到实时画面或录像里。
截图请求成功只表示请求已受理,不代表文件已保存。应查询服务中对应截图任务的状态,确认完成且没有存储写入任务,再按设备的安全卸载流程拔出 U 盘;仅等待固定时长不能保证写入完成。
录像接口
开始录像
//U盘
video_record_start(1, "usb", 60, 100);
//sd卡
video_record_start(1, "sd", 60, 100);
表示:录制第 1 路,保存到 U 盘,每段目标时长 60 秒,最多保留 100 段。
| 参数 | 默认值 | 允许范围 |
|---|---|---|
| 保存位置 | "auto" |
"auto"、"usb"、"sd" |
| 每段目标时长 | 60 秒 | 10~3600 秒 |
| 最多保留段数 | 100 段 | 2~10000 段 |
使用默认参数时:
video_record_start(1);
录像前,需要先播放 RTSP 视频,或者通过 video_set_source() 配置 RTSP 视频源。
录像保存的是原始码流,格式为 MPEG-TS,不重新编码。实际分段需要等待视频关键帧,因此每段时长可能略有差异。
录像文件通常位于存储设备的 HMI_RECORD/CH01/ 等通道目录,实际路径以服务结果为准。
停止录像
//停止第 1 路录像,播放显示由播放接口单独控制。
video_record_stop(1);
//停止全部录像
video_record_stop_all();
其他常用接口
//video_set_source():设置视频地址
video_set_source(1,"rtsp://user:password@192.168.1.10:554/stream");
//video_set_rect():修改画面位置和大小--不更换视频地址,只调整显示区域。
video_set_rect(1, 32, 88, 640, 360);
//video_set_rotation():旋转画面--表示将第 1 路画面顺时针旋转 90°,不影响其他通道。
video_set_rotation(1, 90);
//video_hide():暂时隐藏画面--隐藏后,视频连接和解码仍在运行,仍会占用解码资源。
video_hide(1);
//video_show():恢复隐藏的画面--用于恢复被 video_hide() 隐藏的画面。如果已经调用 video_stop(),需要用 video_play() 重新播放。
video_show(1);
案例指南
示例获取
RTSPTest.zip案例mp4素材获取
USB 摄像头与统一视频网页(2026-11-02 增补)
安装 USB 视频更新包,再用 新版 HmiVideo.h 替换工程中的同名文件。

u盘根目录下放置这些文件
1. 初始化
与上文一样,在 onReady() 中调用一次:
#include "HmiVideo.h"
video_start(); // 自动启动统一网页和视频服务
网页仍访问 http://屏幕IP:8555/,不用再写脚本路径和超时配置。退出时继续调用 video_shutdown()。
2. 播放 USB 摄像头
// 参数:通道、摄像头、X、Y、显示宽、显示高
video_usb_play(1, "/dev/video0", 0, 0, 512, 288);
// 第二只摄像头;只有一只时不调用这行。
video_usb_play(2, "/dev/video2", 512, 0, 512, 288);
接口自动切换 USB 模式。上面的设备路径仅为示例,实际设备和参数通过下方代码查询。只写前六个参数时,默认采集 640×480、30fps;这个默认值不会自动适配所有相机。
“采集档位”就是摄像头输出的分辨率和帧率组合。当前 USB 服务使用 YUYV(一种未压缩视频格式),所以必须选择该摄像头在 YUYV 下支持的组合,不能照搬它在 MJPEG/H.264 下的参数。
需要自行指定采集参数,在末尾追加采集宽、采集高、帧率。例如:
video_usb_play(1, "/dev/video0", 0, 0, 512, 288, 320, 240, 15);
| 参数 | 示例值 | 含义 |
|---|---|---|
| 通道 | 1 | 使用第 1 个显示窗口,范围 1~4;不是摄像头编号。 |
| 摄像头 | /dev/video0 | 从设备列表取得的设备路径,也可传返回的 id。 |
| X、Y | 0、0 | 窗口左上角在屏幕中的位置,单位为像素。 |
| 显示宽、显示高 | 512、288 | 画面在屏幕上占用的大小。 |
| 采集宽、采集高 | 320、240 | 摄像头实际输出的图像大小,影响清晰度和 USB 数据量。 |
| 帧率 | 15 | 请求每秒采集 15 帧,影响流畅度和 USB 数据量。 |
这行代码表示:从该摄像头采集 320×240、15fps 的图像,缩放到屏幕左上角的 512×288 窗口。显示尺寸和采集尺寸可以不同;放大窗口不会增加采集细节,宽高比例不同可能使画面变形。多只摄像头共用 Hub 时,降低采集分辨率或帧率可以减少 USB 带宽占用,单纯缩小显示窗口不能减少摄像头传输量。
通过代码获取设备和支持的采集参数:先完成上面的初始化,再在“刷新设备”按钮中调用 refreshUsbDevices(),在页面定时回调中调用 pollUsbDevices()。这是异步查询,不要在界面线程中循环等待。
#include "stdio.h"
static int usbQueryId = 0;
void refreshUsbDevices() {
usbQueryId = video_usb_devices(); // 返回请求号,不是设备数量
if (usbQueryId <= 0)
printf("USB query submit failed: %d\n", usbQueryId);
}
void pollUsbDevices() {
if (usbQueryId <= 0) return;
VideoResult r = video_result(usbQueryId);
if (!video_finished(r)) return; // 下次定时回调再查
usbQueryId = 0;
if (!video_ok(r)) {
printf("USB query failed: %d %s\n", r.code, r.reply.c_str());
return;
}
printf("%s\n", r.reply.c_str()); // JSON,可用于填充设备/档位下拉框
}
r.reply 是 JSON 字符串,下面是只保留关键字段的示例,实际值以设备返回为准:
{
"ok": true,
"devices": [{
"device": "/dev/video0",
"name": "RGB Camera",
"supported": true,
"format": "YUYV",
"profiles": [{ "width": 320, "height": 240, "fps": [30, 15] }]
}]
}
用工程里的 JSON 库解析后,遍历 devices[] 获取摄像头;选中设备后遍历它的 profiles[] 获取采集宽高,再从该条目的 fps[] 选择帧率。例如上面的结果支持 320、240、15,即可填到播放接口末尾。supported=false 或 profiles 为空表示本服务没有可用的采集档位;devices 为空表示没有枚举到设备。不要把不同档位的宽、高、帧率任意拼接。
3. 调整与停止
以下分别放在对应按钮中,调用方式与原视频相同:
video_set_rect(1, 32, 88, 640, 360); // 位置、大小
video_hide(1); // 隐藏
video_show(1); // 显示
video_stop(1); // 停止一路
video_stop_all(); // 停止全部
返回原模式调用 video_source_mode("rtsp"),成功后继续用 video_play()。接口返回请求号,结果按上文使用 video_result() 查询。
注意:同一摄像头多窗口须用相同采集档位;最多四个显示通道,多个实物摄像头需验收 Hub 带宽和供电。USB 暂不支持旋转、截图、录像和音频,也不能与 RTSP 同时显示。页面重绘造成的局部闪烁尚未修复。
同时调用USB和RTSP视频流
当需要同时调用的时候 切换rtsp流(包括视频mp4) 和usb摄像头,调用之前需要先切换模式
// 播放之前设置 切换为rtsp/视频mp4
video_source_mode("rtsp");
string url = "rtsp://hmi-read:1a1df07d07b61990d0d4ccf9f723b5a4992d6512fafc4d87@81.70.242.63:8554/xintongtai/01";
video_play(1, url, 32, 88,960, 500);
// 播放之前设置 切换为 usb
video_source_mode("usb");
video_usb_play(1, "/dev/video0", 32, 88,960, 500);