全部手册
SIMTUTAI / DOCUMENTATION

开发手册

开发手册、使用视频,应用案例。

本说明介绍如何在 HMI 项目中播放 RTSP / 本地视频、控制画面、截图和录像,并补充 USB 摄像头、统一网页和多路配置的使用方法。

2026-11-02 更新:USB 摄像头请先阅读文末 USB 摄像头与统一视频网页,下载配套完整更新包及 C/C++ SDK。以下原安装包和 video_* 示例适用于 RTSP / 本地视频方案。

安装说明

安装/升级固件

将以下安装包解压至U盘根目录。U盘不要包含其他文件,U盘限制格式为Fat32,内存32G及以下

视频更新.zip

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素材获取

1.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);