video控件¶

1. 使用场景¶

该视频控件基于 LVGL 框架开发、由 LVGL 图片对象扩展实现，为嵌入式 GUI 场景提供轻量级视频播放能力，核心适用场景如下：
单视频或批量视频列表播放、循环播放、顺序播放等常规业务场景；
适配需要单独控制「视频显示 / 音频播放」开关的差异化播放需求。

2. 接口介绍¶

2.1 基础功能¶

接口函数	功能说明	参数说明
lv_obj_t lv_video_create(lv_obj_t parent);`	创建视频自定义控件实例，基于LVGL图片对象扩展	parent：父对象（如屏幕、容器），NULL表示默认屏幕
void lv_video_set_default_cfg(lv_obj_t *video, lv_video_play_mode_t mode, bool audio_en, bool video_en, bool forward, bool auto_size);`	初始化视频播放核心配置，配置后全局生效	mode：初始播放模式；audio_en：使能音频；video_en：使能视频；forward：正向播放；auto_size：自适应尺寸
void lv_video_set_src(lv_obj_t video, const void video_data, const void *surface_data);`	绑定单个待播放视频资源，覆盖原有单资源配置	video_data：视频资源地址或完整路径；surface_data：视频封面图像，传 NULL 则不显示封面
lv_video_player_t lv_video_add_src(lv_obj_t video, const void video_data, const void surface_data);`	向播放列表中追加视频资源，支持多路视频轮播播放	video_data：视频资源地址或完整路径；surface_data：对应视频封面图像，传 NULL 则不显示封面
void lv_video_set_to_playback(lv_obj_t video, const void video_data, const void *surface_data);`	从已添加的批量资源列表中，精准匹配并播放指定视频	video_data：目标视频资源地址或完整路径；surface_data：目标视频封面图像

2.2 播放控制¶

接口函数	功能说明	参数说明
void lv_video_player_open(lv_obj_t *video, uint16_t period);`	预加载视频资源，初始化解码计时器，设置帧刷新周期	period：帧间隔（单位：ms）；delay：延迟播放时间（单位：ms，0表示立即播放）
void lv_video_player_resume(lv_obj_t *video);`	启动视频播放 / 从暂停状态恢复播放，启动解码计时器	video：已初始化的视频控件实例
void lv_video_player_pause(lv_obj_t *video);`	暂停视频播放，暂停解码计时器，画面定格当前帧	video：已初始化的视频控件实例
void lv_video_player_close(lv_obj_t *video);`	关闭视频资源，释放解码缓存及计时器，清空播放画面	关闭视频资源
void lv_video_play_next(lv_obj_t *video);`	切换至播放列表下一个视频并自动播放
void lv_video_play_prev(lv_obj_t *video);`	切换至播放列表上一个视频并自动播放
void lv_video_set_play_mode(lv_obj_t *video, lv_video_play_mode_t mode);`	动态配置视频播放模式，配置后实时生效	mode：播放模式枚举值

3. 使用案例¶

3.1 创建一组视频¶

1.示例代码

lv_obj_t *video = lv_video_create(lv_scr_act());
// 设置控件尺寸 与父容器一致
lv_obj_set_size(video, LV_HOR_RES, LV_VER_RES);
// 控件居中显示
lv_obj_center(video);
// 配置播放参数：单次播放、使能音频、使能视频画面、正向播放、画面自适应
lv_video_set_default_cfg(video, LV_VIDEO_PLAY_LOOP_ONE, true, true, true, true);
// 绑定视频资源，无封面图传NULL
lv_video_set_src(video, APP_GET_H264(Tom_and_Jerry), NULL);
// 打开视频资源，使用屏幕默认刷新率作为帧间隔
lv_video_player_open(video, LV_DISP_DEF_REFR_PERIOD);
// 启动视频播放
lv_video_player_resume(video);

2.示例资源目录

3.2 案例效果展示¶

4. 注意事项¶

控件创建后，建议先配置默认参数 lv_video_set_default_cfg，再启动播放，确保配置参数生效。
调用播放接口 lv_video_player_resume 前，必须先执行 lv_video_player_open 打开视频资源，否则播放无响应。
lv_video_set_src 为覆盖式设置单条视频资源，lv_video_add_src 为追加式添加视频资源至播放列表，二者区分使用。
视频资源路径支持绝对路径与 LVGL 内置资源地址两种形式，传参时保证路径有效性。
页面销毁或切换时，建议先调用 lv_video_player_close 释放资源，再销毁控件，防止内存泄漏。
播放模式枚举值为框架内置定义，传入非法值时，控件将默认使用 LV_VIDEO_PLAY_ONCE 单次播放模式。
auto_size = true 时视频画面自适应控件尺寸，false 则使用视频原始分辨率展示。
支持音频单独控制，即可以关闭音频仅播放画面，暂不支持关闭视频仅播放音频。
批量视频切换播放时，仅对通过 lv_video_add_src 添加的资源列表生效。
帧间隔 period 建议传入 LV_DISP_DEF_REFR_PERIOD，适配屏幕默认刷新率，保证播放流畅度。