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);`	设置视频播放默认配置	`video`：视频控件；`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` 则不显示封面
`int lv_video_remove_src(lv_obj_t video, const void video_data, const void *surface_data);`	从播放列表中移除指定视频资源	`video_data` / `surface_data`：用于匹配待移除资源
`void lv_video_set_to_playback(lv_obj_t video, const void video_data, const void *surface_data);`	从已添加的批量资源列表中，精准匹配并播放指定视频	`video_data`：目标视频资源地址或完整路径；`surface_data`：目标视频封面图像
`void lv_video_set_zoom(lv_obj_t *video, uint16_t zoom);`	设置视频画面缩放比例	`zoom`：LVGL 图片缩放值，256 表示原始尺寸
`void lv_video_set_err_cb(lv_obj_t *video, lv_video_err_cb cb);`	设置播放错误回调	`cb`：错误回调函数
`void lv_video_set_play_done_cb(lv_obj_t *video, lv_video_play_done_cb cb);`	设置播放完成回调	`cb`：播放完成回调函数
`void lv_video_set_cache_all(lv_obj_t *video, bool cache_all);`	设置是否缓存全部视频数据	`cache_all`：是否启用缓存
`void lv_video_enable_anim_buf(lv_obj_t *video, uint8_t en);`	设置是否启用动画缓冲	`en`：非 0 表示启用

2.2 播放控制¶

接口函数	功能说明	参数说明
`void lv_video_player_open(lv_obj_t *video, uint16_t period);`	预加载视频资源，初始化解码计时器，设置帧刷新周期	`period`：帧间隔（单位：ms）
`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);`	关闭视频资源，释放解码缓存及计时器，清空播放画面	`video`：已初始化的视频控件实例
`void lv_video_play_next(lv_obj_t *video);`	切换至播放列表下一个视频并自动播放	`video`：已初始化的视频控件实例
`void lv_video_play_prev(lv_obj_t *video);`	切换至播放列表上一个视频并自动播放	`video`：已初始化的视频控件实例
`void lv_video_set_play_mode(lv_obj_t *video, lv_video_play_mode_t mode);`	动态配置视频播放模式，配置后实时生效	`mode`：播放模式枚举值
`void lv_video_get_first_frame(lv_obj_t *video);`	获取视频首帧	`video`：已初始化的视频控件实例
`void lv_video_first_frame_destroy(lv_obj_t *video);`	销毁首帧缓存	`video`：已初始化的视频控件实例

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_SHUFFLE 在头文件中标注为暂不支持。
auto_size = true 时视频画面自适应控件尺寸，false 则使用视频原始分辨率展示。
audio_en 和 video_en 分别控制音频与视频使能；业务上通常用于关闭音频仅播放画面，关闭视频仅播放音频的场景需结合项目验证。
批量视频切换播放时，仅对通过 lv_video_add_src 添加的资源列表生效。
帧间隔 period 建议传入 LV_DISP_DEF_REFR_PERIOD，适配屏幕默认刷新率，保证播放流畅度。