媒体框架接口说明文档
| 文档版本 | V1.0 |
|---|---|
| 修订日期 | 2026-08-17 |
| 对应头文件 | components/media/framework/api/include/api_media.h |
| 类型定义 | components/media/framework/component_adapter/media/include/ot_media_audio_define.h、ot_media_video_define.h、ot_media_sys_comm_define.h、ot_media_comm_define.h |
| 适用模块 | 媒体框架（Media Framework / MEDIA） |
说明：本模块的
hi_fw_media_*类型多为底层hi_mapi_*（components/media/pipeline/include/）类型的别名，文档中列出关键成员；完整成员以头文件为准。
1 概述
媒体框架对外提供 hi_fw_media_* 系列接口，统一封装了媒体系统、音视频采集 / 编码 / 解码、OSD 字符叠加、显示（DISP）以及抓拍等能力。框架屏蔽了底层海思 MPP / mapi 与消息通道细节，并支持两种运行模式：
- 直连模式（Direct）：应用与媒体实现同进程，通过
hi_fw_media_direct_init()启动。 - 跨进程模式（IPC / Client）：应用与媒体服务分进程，通过
hi_fw_media_client_init()建立客户端。
音频 / 视频均支持“场景（Scene）”配置，通过 hi_fw_media_audio_set_scene() / hi_fw_media_video_set_scene() 选择预定义的参数集（见 media_param.c），后续对应的 *_init() 调用自动套用该场景参数。
模型层次：
媒体（Media）
├─ 音频（Audio）
│ ├─ AI 音频输入
│ ├─ AO 音频输出
│ ├─ AENC 音频编码
│ ├─ ADEC 音频解码
│ └─ ACAP 音频采集（post-AFE PCM）
├─ 视频（Video）
│ ├─ VI 视频输入
│ └─ VENC 视频编码
├─ OSD 字符 / 时间 / Logo 叠加
├─ DISP 显示
└─ 抓拍（Capture）
2 接口总览
| 编号 | 接口 | 模块 | 功能概述 |
|---|---|---|---|
| 1 | hi_fw_media_client_init |
模式管理 | 初始化跨进程模式媒体客户端 |
| 2 | hi_fw_media_client_deinit |
模式管理 | 去初始化跨进程模式媒体客户端 |
| 3 | hi_fw_media_direct_init |
模式管理 | 初始化直连模式媒体 |
| 4 | hi_fw_media_direct_deinit |
模式管理 | 去初始化直连模式媒体 |
| 5 | hi_fw_media_capture_init |
抓拍 | 初始化抓拍功能 |
| 6 | hi_fw_media_capture_deinit |
抓拍 | 去初始化抓拍功能 |
| 7 | hi_fw_media_capture_jpeg |
抓拍 | 抓拍 JPG 图片 |
| 8 | hi_fw_media_init |
媒体系统 | 初始化媒体系统 |
| 9 | hi_fw_media_deinit |
媒体系统 | 去初始化媒体系统 |
| 10 | hi_fw_media_ai_init |
音频 AI | 初始化音频输入 |
| 11 | hi_fw_media_ai_deinit |
音频 AI | 去初始化音频输入 |
| 12 | hi_fw_media_ao_init |
音频 AO | 初始化音频输出 |
| 13 | hi_fw_media_ao_deinit |
音频 AO | 去初始化音频输出 |
| 14 | hi_fw_media_ao_set_vol |
音频 AO | 设置音频输出音量 |
| 15 | hi_fw_media_ao_set_mute |
音频 AO | 设置音频输出静音 |
| 16 | hi_fw_media_aenc_init |
音频 AENC | 初始化音频编码 |
| 17 | hi_fw_media_aenc_deinit |
音频 AENC | 去初始化音频编码 |
| 18 | hi_fw_media_aenc_start |
音频 AENC | 启动音频编码 |
| 19 | hi_fw_media_aenc_stop |
音频 AENC | 停止音频编码 |
| 20 | hi_fw_media_aenc_reg_cb |
音频 AENC | 注册音频编码回调 |
| 21 | hi_fw_media_aenc_unreg_cb |
音频 AENC | 注销音频编码回调 |
| 22 | hi_fw_media_acap_reg_cb |
音频 ACAP | 注册 ACAP 帧回调（post-AFE PCM） |
| 23 | hi_fw_media_acap_unreg_cb |
音频 ACAP | 注销 ACAP 帧回调 |
| 24 | hi_fw_media_adec_init |
音频 ADEC | 初始化音频解码 |
| 25 | hi_fw_media_adec_deinit |
音频 ADEC | 去初始化音频解码 |
| 26 | hi_fw_media_adec_send_stream |
音频 ADEC | 向解码器发送压缩音频数据 |
| 27 | hi_fw_media_adec_send_eos |
音频 ADEC | 发送音频流结束标记（EOS） |
| 28 | hi_fw_media_audio_set_scene |
场景 | 设置当前音频场景 |
| 29 | hi_fw_media_video_set_scene |
场景 | 设置当前视频场景 |
| 30 | hi_fw_media_vi_init |
视频 VI | 初始化视频输入 |
| 31 | hi_fw_media_vi_deinit |
视频 VI | 去初始化视频输入 |
| 32 | hi_fw_media_venc_init |
视频 VENC | 初始化视频编码 |
| 33 | hi_fw_media_venc_deinit |
视频 VENC | 去初始化视频编码 |
| 34 | hi_fw_media_venc_start |
视频 VENC | 启动视频编码 |
| 35 | hi_fw_media_venc_stop |
视频 VENC | 停止视频编码 |
| 36 | hi_fw_media_venc_get_status |
视频 VENC | 获取视频编码状态 |
| 37 | hi_fw_media_venc_get_attr |
视频 VENC | 获取视频编码属性 |
| 38 | hi_fw_media_venc_set_attr |
视频 VENC | 设置视频编码属性 |
| 39 | hi_fw_media_venc_reg_cb |
视频 VENC | 注册视频编码回调 |
| 40 | hi_fw_media_venc_unreg_cb |
视频 VENC | 注销视频编码回调 |
| 41 | hi_fw_media_osd_init |
OSD | 初始化 OSD |
| 42 | hi_fw_media_osd_deinit |
OSD | 去初始化 OSD |
| 43 | hi_fw_media_osd_start |
OSD | 启动 OSD |
| 44 | hi_fw_media_osd_stop |
OSD | 停止 OSD |
| 45 | hi_fw_media_osd_set_time |
OSD | 设置 OSD 时间显示 |
| 46 | hi_fw_media_osd_set_string |
OSD | 设置 OSD 字符串显示 |
| 47 | hi_fw_media_osd_set_logo |
OSD | 设置 OSD Logo 显示 |
| 48 | hi_fw_media_set_flip |
视频 | 设置视频翻转 |
| 49 | hi_fw_media_set_mirror |
视频 | 设置视频镜像 |
| 50 | hi_fw_media_disp_init |
DISP | 初始化显示 |
| 51 | hi_fw_media_disp_deinit |
DISP | 去初始化显示 |
| 52 | hi_fw_media_disp_get_screen_resolution |
DISP | 获取屏幕分辨率 |
| 53 | hi_fw_media_disp_get_video_screen |
DISP | 获取视频屏幕 |
| 54 | hi_fw_media_disp_release_video_screen |
DISP | 释放视频屏幕 |
| 55 | hi_fw_media_disp_send_frame |
DISP | 向显示窗口发送视频帧 |
| 56 | hi_fw_media_disp_set_window_attr |
DISP | 设置显示窗口属性 |
| 57 | hi_fw_media_disp_get_window_attr |
DISP | 获取显示窗口属性 |
| 58 | hi_fw_media_disp_start_window |
DISP | 启动显示窗口 |
| 59 | hi_fw_media_disp_stop_window |
DISP | 停止显示窗口 |
3 API 参考
3.1 hi_fw_media_client_init
【描述】
初始化跨进程模式媒体客户端，仅在跨进程模式开发中调用。建立应用进程到媒体服务进程的通道并完成客户端侧初始化。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
endpoint |
输入 | const td_char * |
端点地址（媒体服务端点标识），不能为 NULL。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
初始化成功。 |
非0 |
初始化失败。 |
【注意】
- 仅在跨进程（IPC）模式下调用；直连模式下应调用
hi_fw_media_direct_init()。 - 与
hi_fw_media_client_deinit()成对调用。
3.2 hi_fw_media_client_deinit
【描述】
去初始化跨进程模式媒体客户端，释放客户端侧资源。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
去初始化成功。 |
非0 |
去初始化失败。 |
【注意】
- 需在媒体相关资源释放完毕后调用，与
hi_fw_media_client_init()成对。
3.3 hi_fw_media_direct_init
【描述】
初始化直连模式媒体，仅在直连模式开发中调用。启动媒体实现线程并完成直连模式相关初始化，后续 hi_fw_media_init() 等接口依赖该初始化。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
初始化成功。 |
非0 |
初始化失败。 |
【注意】
- 直连模式下需在调用
hi_fw_media_init()前调用。 - 与
hi_fw_media_direct_deinit()成对调用（停止为逆序）。
3.4 hi_fw_media_direct_deinit
【描述】
去初始化直连模式媒体，逆序释放直连模式相关资源。
【语法】
【参数】
无。
【返回值】
无。
【注意】
- 停止顺序需为启动的逆序：先
*_deinit()各子模块，再hi_fw_media_deinit()，最后hi_fw_media_direct_deinit()。
3.5 hi_fw_media_capture_init
【描述】
初始化抓拍功能。内部按依赖顺序完成直连模式、媒体系统、视频输入（VI）、视频编码（VENC）的初始化，并注册抓拍所需 VENC 回调。该接口幂等：已初始化时直接返回成功。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
初始化成功。 |
非0 |
初始化失败。 |
【注意】
- 若不预先调用该接口，
hi_fw_media_capture_jpeg()内部会自动调用。 - 与
hi_fw_media_capture_deinit()成对调用。
3.6 hi_fw_media_capture_deinit
【描述】
去初始化抓拍功能。逆序释放抓拍期间初始化的 VENC、VI、媒体系统与直连模式资源，并释放内部 JPEG 缓冲区。该接口幂等：未初始化时直接返回成功。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
去初始化成功。 |
非0 |
去初始化失败（内部 VENC 去初始化失败时返回其错误码）。 |
【注意】
- 需在抓拍全部完成后调用。
3.7 hi_fw_media_capture_jpeg
【描述】
抓拍 JPG 图片。venc_hdl 对应的编码通道需为 JPEG 编码（payload 为 JPEG / MJPEG）。函数内部会临时 start/stop 编码通道并阻塞等待编码完成，将 JPEG 数据写入指定文件或目录。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
venc_hdl |
输入 | td_handle |
视频编码句柄（JPEG 通道）。 |
file_path |
输入 | td_char * |
保存的文件路径或目录路径，如 /mnt/pic。若目录存在则保存到该目录下，命名为 capture_[时间戳].jpg；若目录不存在则作为文件名前缀，单张保存为 pic.jpg，多张保存为 pic_[index].jpg。不能为 NULL 或空串。 |
num_of_pictures |
输入 | td_s32 |
要抓拍的图片数量，需 > 0。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
全部抓拍成功。 |
非0 |
抓拍失败（参数非法、初始化失败或某一帧编码 / 保存失败）。 |
【注意】
- 若抓拍未初始化，函数内部会自动调用
hi_fw_media_capture_init()。 - 单帧阻塞等待超时约 5 秒；失败即中断剩余帧。
- 抓拍期间会注册/注销内部 VENC 回调，应用不应重复注册同一通道的回调。
3.8 hi_fw_media_init
【描述】
初始化媒体系统，完成底层 MPP 公共资源（VB 池、VI-VPSS 模式、ISP 参数等）的初始化。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
初始化成功。 |
非0 |
初始化失败。 |
【注意】
- 直连模式下需先调用
hi_fw_media_direct_init()；跨进程模式下需先调用hi_fw_media_client_init()。 - 需在所有音视频子模块
*_init()之前调用。
3.9 hi_fw_media_deinit
【描述】
去初始化媒体系统，释放媒体公共资源。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
去初始化成功。 |
非0 |
去初始化失败。 |
【注意】
- 需在各音视频子模块
*_deinit()之后、hi_fw_media_direct_deinit()/hi_fw_media_client_deinit()之前调用。
3.10 hi_fw_media_ai_init
【描述】
初始化音频输入（AI），使用当前音频场景（hi_fw_media_audio_set_scene）预定义的 AI 参数集（含 VQE、AFE provider 等）。该接口幂等。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
初始化成功。 |
非0 |
初始化失败（场景未配置或底层初始化失败）。 |
【注意】
- 需在
hi_fw_media_init()之后、hi_fw_media_aenc_init()等依赖模块之前调用。 - 音频场景通过
hi_fw_media_audio_set_scene()设置，必须在hi_fw_media_ai_init()之前完成。
3.11 hi_fw_media_ai_deinit
【描述】
去初始化音频输入（AI）。该接口幂等。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
去初始化成功。 |
非0 |
去初始化失败。 |
【注意】
- 停止顺序为启动逆序：先停编码（AENC）再停采集（AI）。
3.12 hi_fw_media_ao_init
【描述】
初始化音频输出（AO），使用当前音频场景预定义的 AO 参数集。该接口幂等。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
初始化成功。 |
非0 |
初始化失败。 |
【注意】
- 需在
hi_fw_media_init()之后调用。
3.13 hi_fw_media_ao_deinit
【描述】
去初始化音频输出（AO）。该接口幂等。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
去初始化成功。 |
非0 |
去初始化失败。 |
【注意】
- 停止顺序为启动逆序。
3.14 hi_fw_media_ao_set_vol
【描述】
设置音频输出音量。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
ao_hdl |
输入 | td_handle |
音频输出句柄。 |
volume |
输入 | td_s32 |
音量值（百分比，0~100）。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
设置成功。 |
非0 |
设置失败。 |
【注意】
- 需在
hi_fw_media_ao_init()之后调用。
3.15 hi_fw_media_ao_set_mute
【描述】
设置音频输出静音。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
ao_hdl |
输入 | td_handle |
音频输出句柄。 |
enable |
输入 | td_bool |
TD_TRUE 启用静音，TD_FALSE 取消静音。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
设置成功。 |
非0 |
设置失败。 |
【注意】
- 需在
hi_fw_media_ao_init()之后调用。
3.16 hi_fw_media_aenc_init
【描述】
初始化音频编码（AENC），使用当前音频场景预定义的编码参数（编码格式、每帧采样点数、码率控制等）。该接口幂等。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
初始化成功。 |
非0 |
初始化失败。 |
【注意】
- 需在
hi_fw_media_ai_init()之后调用。 - 编码通道句柄由场景参数集内部创建，通过场景配置确定。
3.17 hi_fw_media_aenc_deinit
【描述】
去初始化音频编码（AENC）。该接口幂等。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
去初始化成功。 |
非0 |
去初始化失败。 |
【注意】
- 停止顺序为启动逆序：先
hi_fw_media_aenc_stop()，再hi_fw_media_aenc_deinit()，最后hi_fw_media_ai_deinit()。
3.18 hi_fw_media_aenc_start
【描述】
启动音频编码通道，开始编码并触发已注册的回调。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
aenc_hdl |
输入 | td_handle |
音频编码句柄。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
启动成功。 |
非0 |
启动失败。 |
【注意】
- 需在
hi_fw_media_aenc_init()之后调用。
3.19 hi_fw_media_aenc_stop
【描述】
停止音频编码通道。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
aenc_hdl |
输入 | td_handle |
音频编码句柄。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
停止成功。 |
非0 |
停止失败。 |
【注意】
- 需在
hi_fw_media_aenc_deinit()之前调用。
3.20 hi_fw_media_aenc_reg_cb
【描述】
注册音频编码回调，用于获取编码后的音频流（如 AAC / OPUS 码流数据）。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
aenc_hdl |
输入 | td_handle |
音频编码句柄。 |
aenc_cb |
输入 | const hi_fw_media_aenc_cb * |
音频编码回调，不能为 NULL，且其 proc_data_cb 不能为 NULL。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
注册成功。 |
非0 |
注册失败（参数为空指针等）。 |
【注意】
- 与
hi_fw_media_aenc_unreg_cb()成对使用。 - 回调在编码线程上下文中执行，不应在回调内阻塞过久。
【举例】
static td_s32 on_aenc_data(td_handle hdl, const hi_mapi_audio_stream *s, td_void *priv)
{
/* 处理编码后的音频数据 */
return 0;
}
hi_fw_media_aenc_cb cb = { .proc_data_cb = on_aenc_data, .private_data = NULL };
hi_fw_media_aenc_reg_cb(aenc_hdl, &cb);
3.21 hi_fw_media_aenc_unreg_cb
【描述】
注销音频编码回调。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
aenc_hdl |
输入 | td_handle |
音频编码句柄。 |
aenc_cb |
输入 | const hi_fw_media_aenc_cb * |
需注销的回调结构（与注册时一致）。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
注销成功。 |
非0 |
注销失败。 |
【注意】
- 注销后回调不再被触发。
3.22 hi_fw_media_acap_reg_cb
【描述】
注册 ACAP 帧回调，用于获取 post-AFE（前处理之后）的 PCM 数据。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
acap_hdl |
输入 | td_handle |
ACAP 句柄。 |
acap_cb |
输入 | const hi_fw_media_acap_cb * |
ACAP 帧回调，不能为 NULL。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
注册成功。 |
非0 |
注册失败。 |
【注意】
- 与
hi_fw_media_acap_unreg_cb()成对使用。
【举例】
static td_s32 on_acap_frame(td_handle hdl, const hi_mapi_audio_frame *f, td_void *priv)
{
/* 处理 post-AFE PCM */
return 0;
}
hi_fw_media_acap_cb cb = { .proc_frame_cb = on_acap_frame, .private_data = NULL };
hi_fw_media_acap_reg_cb(acap_hdl, &cb);
3.23 hi_fw_media_acap_unreg_cb
【描述】
注销 ACAP 帧回调。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
acap_hdl |
输入 | td_handle |
ACAP 句柄。 |
acap_cb |
输入 | const hi_fw_media_acap_cb * |
需注销的回调结构（与注册时一致）。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
注销成功。 |
非0 |
注销失败。 |
【注意】
- 注销后回调不再被触发。
3.24 hi_fw_media_adec_init
【描述】
初始化音频解码（ADEC），使用当前音频场景预定义的解码参数（如 MP3 解码通道及绑定目标）。该接口幂等。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
初始化成功。 |
非0 |
初始化失败。 |
【注意】
- 需在
hi_fw_media_init()之后调用。
3.25 hi_fw_media_adec_deinit
【描述】
去初始化音频解码（ADEC）。该接口幂等。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
去初始化成功。 |
非0 |
去初始化失败。 |
【注意】
- 停止顺序为启动逆序。
3.26 hi_fw_media_adec_send_stream
【描述】
向音频解码器发送一帧压缩音频数据（如 MP3 / AAC / OPUS）。
【语法】
td_s32 hi_fw_media_adec_send_stream(td_handle adec_hdl, const hi_fw_media_audio_packet *packet, td_bool block);
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
adec_hdl |
输入 | td_handle |
音频解码句柄。 |
packet |
输入 | const hi_fw_media_audio_packet * |
压缩音频数据包，含 data、data_len、time_stamp、seq；data 指向调用方提供的缓冲区，函数返回后不再引用。 |
block |
输入 | td_bool |
是否阻塞：TD_TRUE 阻塞（缓冲区满时等待），TD_FALSE 非阻塞。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
发送成功。 |
非0 |
发送失败。 |
【注意】
- 需在
hi_fw_media_adec_init()之后调用。
【举例】
hi_fw_media_audio_packet pkt = { .data = buf, .data_len = len, .time_stamp = pts, .seq = seq };
hi_fw_media_adec_send_stream(adec_hdl, &pkt, TD_TRUE);
3.27 hi_fw_media_adec_send_eos
【描述】
向音频解码器发送音频流结束标记（EOS），解码器收到后结束当前流。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
adec_hdl |
输入 | td_handle |
音频解码句柄。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
发送成功。 |
非0 |
发送失败。 |
【注意】
- 仅在播放停止前发送一次。
3.28 hi_fw_media_audio_set_scene
【描述】
设置当前音频场景。后续 hi_fw_media_ai_init() / hi_fw_media_ao_init() / hi_fw_media_aenc_init() / hi_fw_media_adec_init() 调用将使用该场景的预定义参数集。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
scene |
输入 | hi_fw_media_audio_scene |
音频场景枚举值，需小于 HI_FW_MEDIA_AUDIO_SCENE_MAX。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
设置成功。 |
非0 |
设置失败（场景枚举越界）。 |
【注意】
- 需在音频相关
*_init()之前调用，且需在媒体初始化完成之后。
3.29 hi_fw_media_video_set_scene
【描述】
设置当前视频场景。后续 hi_fw_media_vi_init() / hi_fw_media_venc_init() 调用将使用该场景的预定义参数集。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
scene |
输入 | hi_fw_media_video_scene |
视频场景枚举值，需小于 HI_FW_MEDIA_VIDEO_SCENE_MAX。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
设置成功。 |
非0 |
设置失败（场景枚举越界）。 |
【注意】
- 需在视频相关
*_init()之前调用，且需在媒体初始化完成之后。
3.30 hi_fw_media_vi_init
【描述】
初始化视频输入（VI），使用当前视频场景预定义的采集（VCAP）参数集。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
初始化成功。 |
非0 |
初始化失败。 |
【注意】
- 需在
hi_fw_media_init()之后、hi_fw_media_venc_init()之前调用。
3.31 hi_fw_media_vi_deinit
【描述】
去初始化视频输入（VI）。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
去初始化成功。 |
非0 |
去初始化失败。 |
【注意】
- 停止顺序为启动逆序：先停编码（VENC）再停采集（VI）。
3.32 hi_fw_media_venc_init
【描述】
初始化视频编码（VENC），使用当前视频场景预定义的编码参数集。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
初始化成功。 |
非0 |
初始化失败。 |
【注意】
- 需在
hi_fw_media_vi_init()之后调用。
3.33 hi_fw_media_venc_deinit
【描述】
去初始化视频编码（VENC）。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
去初始化成功。 |
非0 |
去初始化失败。 |
【注意】
- 停止顺序为启动逆序：先
hi_fw_media_venc_stop()，再hi_fw_media_venc_deinit()，最后hi_fw_media_vi_deinit()。
3.34 hi_fw_media_venc_start
【描述】
启动视频编码，开始编码指定帧数后自动停止；frame_cnt 为 -1 时持续编码直到调用 hi_fw_media_venc_stop()。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
venc_hdl |
输入 | td_handle |
视频编码句柄。 |
frame_cnt |
输入 | td_s32 |
要编码的帧数，-1 表示无限帧。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
启动成功。 |
非0 |
启动失败。 |
【注意】
- 需在
hi_fw_media_venc_init()之后调用。 - 启动后编码码流通过已注册的 VENC 回调返回。
3.35 hi_fw_media_venc_stop
【描述】
停止视频编码。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
venc_hdl |
输入 | td_handle |
视频编码句柄。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
停止成功。 |
非0 |
停止失败。 |
【注意】
- 需在
hi_fw_media_venc_deinit()之前调用。
3.36 hi_fw_media_venc_get_status
【描述】
获取视频编码通道的启动状态。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
venc_hdl |
输入 | td_handle |
视频编码句柄。 |
is_started |
输出 | td_bool * |
返回是否已启动，不能为 NULL。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
获取成功。 |
非0 |
获取失败（is_started 为 NULL 等）。 |
【注意】
- 仅在调用成功后读取
*is_started。
3.37 hi_fw_media_venc_get_attr
【描述】
获取视频编码通道属性。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
venc_hdl |
输入 | td_handle |
视频编码句柄。 |
attr |
输出 | hi_fw_media_venc_chn_attr * |
编码通道属性（payload 类型、RC 属性、GOP、帧率等），不能为 NULL。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
获取成功。 |
非0 |
获取失败。 |
【注意】
- 需在
hi_fw_media_venc_init()之后调用。
3.38 hi_fw_media_venc_set_attr
【描述】
设置视频编码通道属性，要求 venc_hdl 处于已初始化但未启动的状态。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
venc_hdl |
输入 | td_handle |
视频编码句柄。 |
attr |
输入 | const hi_fw_media_venc_chn_attr * |
编码通道属性，不能为 NULL。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
设置成功。 |
非0 |
设置失败。 |
【注意】
- 需在已初始化、未启动状态下调用；运行中修改属性可能失败或返回“不允许”类错误。
3.39 hi_fw_media_venc_reg_cb
【描述】
注册视频编码回调，用于获取编码后的码流数据（如 H.264 / H.265 / JPEG）。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
venc_hdl |
输入 | td_handle |
视频编码句柄。 |
venc_cb |
输入 | const hi_fw_media_venc_cb * |
视频编码回调，不能为 NULL，且其 proc_data_cb 不能为 NULL。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
注册成功。 |
非0 |
注册失败（参数为空指针等）。 |
【注意】
- 与
hi_fw_media_venc_unreg_cb()成对使用。 - 回调在编码线程上下文中执行，不应在回调内阻塞过久。
【举例】
static td_s32 on_venc_data(td_handle hdl, hi_mapi_venc_data_attr *s, td_void *priv)
{
/* 处理编码后的视频码流 */
return 0;
}
hi_fw_media_venc_cb cb = { .proc_data_cb = on_venc_data, .private_data = NULL };
hi_fw_media_venc_reg_cb(venc_hdl, &cb);
3.40 hi_fw_media_venc_unreg_cb
【描述】
注销视频编码回调。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
venc_hdl |
输入 | td_handle |
视频编码句柄。 |
venc_cb |
输入 | const hi_fw_media_venc_cb * |
需注销的回调结构（与注册时一致）。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
注销成功。 |
非0 |
注销失败。 |
【注意】
- 注销后回调不再被触发。
3.41 hi_fw_media_osd_init
【描述】
初始化 OSD，加载字体库（字体尺寸与字体获取回调），为后续 OSD 字符叠加做准备。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
font_attr |
输入 | const hi_fw_media_osd_font_attr * |
字体属性（font_width、font_height、get_font_mod_cb），不能为 NULL。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
初始化成功。 |
非0 |
初始化失败（font_attr 为 NULL 等）。 |
【注意】
- 需在
hi_fw_media_venc_init()之后、hi_fw_media_osd_start()之前调用。
【举例】
hi_fw_media_osd_font_attr font = { .font_width = 32, .font_height = 32, .get_font_mod_cb = my_get_font };
hi_fw_media_osd_init(&font);
3.42 hi_fw_media_osd_deinit
【描述】
去初始化 OSD，释放字体库资源。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
去初始化成功。 |
非0 |
去初始化失败。 |
【注意】
- 需在
hi_fw_media_osd_stop()之后调用。
3.43 hi_fw_media_osd_start
【描述】
启动 OSD，按配置叠加时间、字符串、Logo 等元素。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
osd_cfg |
输入 | const hi_fw_media_osd_cfg * |
OSD 配置（叠加元素数量、基准字号/图片尺寸、各 OSD 属性），不能为 NULL。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
启动成功。 |
非0 |
启动失败。 |
【注意】
- 需在
hi_fw_media_osd_init()之后调用。
3.44 hi_fw_media_osd_stop
【描述】
停止 OSD 叠加。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
停止成功。 |
非0 |
停止失败。 |
【注意】
- 需在
hi_fw_media_osd_deinit()之前调用。
3.45 hi_fw_media_osd_set_time
【描述】
设置指定摄像头的 OSD 时间显示开关。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
cam_idx |
输入 | td_u8 |
摄像头索引。 |
enable |
输入 | td_bool |
TD_TRUE 显示时间，TD_FALSE 隐藏。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
设置成功。 |
非0 |
设置失败。 |
【注意】
- 需在
hi_fw_media_osd_start()之后调用。
3.46 hi_fw_media_osd_set_string
【描述】
设置指定摄像头的 OSD 字符串显示开关。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
cam_idx |
输入 | td_u8 |
摄像头索引。 |
enable |
输入 | td_bool |
TD_TRUE 显示字符串，TD_FALSE 隐藏。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
设置成功。 |
非0 |
设置失败。 |
【注意】
- 需在
hi_fw_media_osd_start()之后调用。
3.47 hi_fw_media_osd_set_logo
【描述】
设置指定摄像头的 OSD Logo 显示开关。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
cam_idx |
输入 | td_u8 |
摄像头索引。 |
enable |
输入 | td_bool |
TD_TRUE 显示 Logo，TD_FALSE 隐藏。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
设置成功。 |
非0 |
设置失败。 |
【注意】
- 需在
hi_fw_media_osd_start()之后调用。
3.48 hi_fw_media_set_flip
【描述】
设置指定摄像头的视频翻转。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
cam_idx |
输入 | td_u8 |
摄像头索引。 |
enable |
输入 | td_bool |
TD_TRUE 启用翻转，TD_FALSE 关闭。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
设置成功。 |
非0 |
设置失败。 |
【注意】
- 需在
hi_fw_media_vi_init()之后调用。
3.49 hi_fw_media_set_mirror
【描述】
设置指定摄像头的视频镜像。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
cam_idx |
输入 | td_u8 |
摄像头索引。 |
enable |
输入 | td_bool |
TD_TRUE 启用镜像，TD_FALSE 关闭。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
设置成功。 |
非0 |
设置失败。 |
【注意】
- 需在
hi_fw_media_vi_init()之后调用。
3.50 hi_fw_media_disp_init
【描述】
初始化显示（DISP），配置显示设备与视频层。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
初始化成功。 |
非0 |
初始化失败。 |
【注意】
- 需在
hi_fw_media_init()之后调用。
3.51 hi_fw_media_disp_deinit
【描述】
去初始化显示（DISP）。
【语法】
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
去初始化成功。 |
非0 |
去初始化失败。 |
【注意】
- 停止顺序为启动逆序：先停窗口，再释放视频屏幕，最后
hi_fw_media_disp_deinit()。
3.52 hi_fw_media_disp_get_screen_resolution
【描述】
获取屏幕分辨率。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
disp_hdl |
输入 | td_handle |
显示设备句柄。 |
width |
输出 | td_u32 * |
返回屏幕宽度，不能为 NULL。 |
height |
输出 | td_u32 * |
返回屏幕高度，不能为 NULL。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
获取成功。 |
非0 |
获取失败。 |
【注意】
- 需在
hi_fw_media_disp_init()之后调用。
3.53 hi_fw_media_disp_get_video_screen
【描述】
获取视频屏幕指针（常用于与 LVGL 等 GUI 集成，向该屏幕绘制或获取屏幕缓冲）。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
disp_hdl |
输入 | td_handle |
显示设备句柄。 |
【返回值】
| 返回值 | 描述 |
|---|---|
非NULL |
视频屏幕指针。 |
NULL |
获取失败（媒体或显示未初始化）。 |
【注意】
- 获取的屏幕需在不再使用时通过
hi_fw_media_disp_release_video_screen()释放。
【举例】
td_void *screen = hi_fw_media_disp_get_video_screen(disp_hdl);
if (screen != NULL) {
/* 使用屏幕 ... */
hi_fw_media_disp_release_video_screen(disp_hdl, screen);
}
3.54 hi_fw_media_disp_release_video_screen
【描述】
释放由 hi_fw_media_disp_get_video_screen() 获取的视频屏幕。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
disp_hdl |
输入 | td_handle |
显示设备句柄。 |
video_screen |
输入 | td_void * |
视频屏幕指针，不能为 NULL。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
释放成功。 |
非0 |
释放失败。 |
【注意】
- 与
hi_fw_media_disp_get_video_screen()成对调用（获取/释放配对）。
3.55 hi_fw_media_disp_send_frame
【描述】
向显示窗口发送一帧视频数据。
【语法】
td_s32 hi_fw_media_disp_send_frame(td_handle disp_hdl, td_handle wnd_hdl, const hi_fw_media_frame_data *frame_data);
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
disp_hdl |
输入 | td_handle |
显示设备句柄。 |
wnd_hdl |
输入 | td_handle |
显示窗口句柄。 |
frame_data |
输入 | const hi_fw_media_frame_data * |
帧数据（宽高、格式、物理/虚拟地址、stride、PTS 等），不能为 NULL。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
发送成功。 |
非0 |
发送失败。 |
【注意】
- 需在
hi_fw_media_disp_init()及窗口启动后调用。
3.56 hi_fw_media_disp_set_window_attr
【描述】
设置显示窗口属性（窗口位置 / 大小、优先级）。
【语法】
td_s32 hi_fw_media_disp_set_window_attr(td_handle disp_hdl, td_handle wnd_hdl,
const hi_fw_media_disp_window_attr *wnd_attr);
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
disp_hdl |
输入 | td_handle |
显示设备句柄。 |
wnd_hdl |
输入 | td_handle |
显示窗口句柄。 |
wnd_attr |
输入 | const hi_fw_media_disp_window_attr * |
窗口属性（rect、priority），不能为 NULL。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
设置成功。 |
非0 |
设置失败。 |
【注意】
- 需在
hi_fw_media_disp_init()之后、窗口启动前或运行中按需求调用。
【举例】
hi_fw_media_disp_window_attr attr = { 0 };
attr.rect.x = 0; attr.rect.y = 0; attr.rect.width = 240; attr.rect.height = 320;
attr.priority = 0;
hi_fw_media_disp_set_window_attr(disp_hdl, wnd_hdl, &attr);
3.57 hi_fw_media_disp_get_window_attr
【描述】
获取显示窗口属性。
【语法】
td_s32 hi_fw_media_disp_get_window_attr(td_handle disp_hdl, td_handle wnd_hdl,
hi_fw_media_disp_window_attr *wnd_attr);
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
disp_hdl |
输入 | td_handle |
显示设备句柄。 |
wnd_hdl |
输入 | td_handle |
显示窗口句柄。 |
wnd_attr |
输出 | hi_fw_media_disp_window_attr * |
返回窗口属性，不能为 NULL。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
获取成功。 |
非0 |
获取失败。 |
【注意】
- 需在
hi_fw_media_disp_init()之后调用。
3.58 hi_fw_media_disp_start_window
【描述】
启动显示窗口，开始显示视频。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
disp_hdl |
输入 | td_handle |
显示设备句柄。 |
wnd_hdl |
输入 | td_handle |
显示窗口句柄。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
启动成功。 |
非0 |
启动失败。 |
【注意】
- 需在
hi_fw_media_disp_init()之后调用。
3.59 hi_fw_media_disp_stop_window
【描述】
停止显示窗口。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
disp_hdl |
输入 | td_handle |
显示设备句柄。 |
wnd_hdl |
输入 | td_handle |
显示窗口句柄。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
停止成功。 |
非0 |
停止失败。 |
【注意】
- 停止顺序为启动逆序：先停窗口，再
hi_fw_media_disp_deinit()。
4 数据类型
4.1 hi_fw_media_audio_packet
【说明】
音频解码输入的数据包结构，描述一帧压缩音频数据（虚拟地址、长度、时间戳、序号）。
【定义】
typedef struct {
const td_u8 *data; /* 压缩音频数据虚拟地址（调用方提供，send_stream 返回后不再引用） */
td_u32 seq; /* 帧序号 */
td_u32 data_len; /* 数据长度（字节） */
td_u64 time_stamp; /* 时间戳（PTS） */
td_u32 reserved[4];
} ot_media_audio_packet;
typedef ot_media_audio_packet hi_fw_media_audio_packet;
【成员】
| 成员名称 | 描述 |
|---|---|
data |
压缩音频数据地址；由调用方分配并保证生命周期覆盖到 hi_fw_media_adec_send_stream() 返回。 |
seq |
帧序号。 |
data_len |
数据长度（字节）。 |
time_stamp |
时间戳（PTS）。 |
reserved |
保留字段。 |
【注意事项】
data指向的缓冲区由调用方管理，send_stream返回后不再引用。
【相关数据类型及接口】
hi_fw_media_adec_send_stream。
4.2 hi_fw_media_audio_scene（音频场景枚举）
【说明】
音频场景枚举，调用方通过场景选择预定义的音频参数集。
【定义】
typedef enum {
HI_FW_MEDIA_AUDIO_SCENE_INNER_HISI_AAC = 0, /* 内置 Codec + hisi AFE + AAC 48k stereo */
HI_FW_MEDIA_AUDIO_SCENE_INNER_HISI_OPUS, /* 内置 Codec + hisi AFE + OPUS 16k mono（上云） */
HI_FW_MEDIA_AUDIO_SCENE_ES7210_EXT_OPUS, /* ES7210 + external AFE + OPUS 16k mono */
HI_FW_MEDIA_AUDIO_SCENE_INNER_HISI_MP3, /* 内置 Codec + hisi AFE + MP3 ADEC 16k mono（本地） */
HI_FW_MEDIA_AUDIO_SCENE_ZEROCLAW, /* zeroclaw: 双 AENC + TalkV2 AEC + MP3 ADEC/AO */
HI_FW_MEDIA_AUDIO_SCENE_2131_WEBRTC, /* 2131 LCD + WebRTC 对讲：AI0 16k MONO，VQE 由 webrtc attach 自建 */
HI_FW_MEDIA_AUDIO_SCENE_MAX
} ot_media_audio_scene_attr;
typedef ot_media_audio_scene_attr hi_fw_media_audio_scene;
【成员】
| 成员名称 | 描述 |
|---|---|
HI_FW_MEDIA_AUDIO_SCENE_INNER_HISI_AAC |
内置 Codec + hisi AFE + AAC 48k 立体声。 |
HI_FW_MEDIA_AUDIO_SCENE_INNER_HISI_OPUS |
内置 Codec + hisi AFE + OPUS 16k 单声道（上云）。 |
HI_FW_MEDIA_AUDIO_SCENE_ES7210_EXT_OPUS |
ES7210 + 外部 AFE + OPUS 16k 单声道。 |
HI_FW_MEDIA_AUDIO_SCENE_INNER_HISI_MP3 |
内置 Codec + hisi AFE + MP3 ADEC 16k 单声道（本地）。 |
HI_FW_MEDIA_AUDIO_SCENE_ZEROCLAW |
zeroclaw：双 AENC + TalkV2 AEC + MP3 ADEC/AO。 |
HI_FW_MEDIA_AUDIO_SCENE_2131_WEBRTC |
2131 LCD + WebRTC 对讲：AI0 16k MONO（增益 50dB），VQE 由 webrtc attach 自建。 |
HI_FW_MEDIA_AUDIO_SCENE_MAX |
场景上限，非法值边界。 |
【注意事项】
- 该值仅用于选择参数集，实际参数见
api/direct/media/media_param.c。
【相关数据类型及接口】
hi_fw_media_audio_set_scene。
4.3 hi_fw_media_video_scene（视频场景枚举）
【说明】
视频场景枚举，每个场景对应一套预定义视频参数集。
【定义】
typedef enum {
HI_FW_MEDIA_VIDEO_SCENE_DEFAULT = 0, /* 4M 编码 + VPSS chn1 240x320 -> LCD（兼容现有默认） */
HI_FW_MEDIA_VIDEO_SCENE_FACTORY_LCD, /* 4M 编码 + VPSS chn1 240x320 -> LCD */
HI_FW_MEDIA_VIDEO_SCENE_CAPTURE, /* 仅拍照：venc0 JPEG 全分辨率，无裁剪 */
HI_FW_MEDIA_VIDEO_SCENE_ZEROCLAW, /* 双 VENC：JPEG + H.265 推流 */
HI_FW_MEDIA_VIDEO_SCENE_DUAL_SENSOR, /* 双 VI → 双 VPSS → 双 VENC(H.265) */
HI_FW_MEDIA_VIDEO_SCENE_FACTORY_LCD_2131_WEBRTC, /* 2131 LCD + WebRTC 对讲 */
HI_FW_MEDIA_VIDEO_SCENE_MAX
} ot_media_video_scene_attr;
typedef ot_media_video_scene_attr hi_fw_media_video_scene;
【成员】
| 成员名称 | 描述 |
|---|---|
HI_FW_MEDIA_VIDEO_SCENE_DEFAULT |
4M 编码 + VPSS chn1 240x320 → LCD（兼容默认）。 |
HI_FW_MEDIA_VIDEO_SCENE_FACTORY_LCD |
4M 编码 + VPSS chn1 240x320 → LCD。 |
HI_FW_MEDIA_VIDEO_SCENE_CAPTURE |
仅拍照：venc0 JPEG 全分辨率，无裁剪。 |
HI_FW_MEDIA_VIDEO_SCENE_ZEROCLAW |
双 VENC：JPEG + H.265 推流。 |
HI_FW_MEDIA_VIDEO_SCENE_DUAL_SENSOR |
双 VI → 双 VPSS → 双 VENC(H.265)。 |
HI_FW_MEDIA_VIDEO_SCENE_FACTORY_LCD_2131_WEBRTC |
2131 LCD + WebRTC 对讲。 |
HI_FW_MEDIA_VIDEO_SCENE_MAX |
场景上限，非法值边界。 |
【注意事项】
- 该值仅用于选择参数集，实际参数见
api/direct/media/media_param.c。
【相关数据类型及接口】
hi_fw_media_video_set_scene。
4.4 hi_fw_media_venc_chn_attr
【说明】
视频编码通道属性，包含编码负载类型、码率控制、GOP、帧率等。
【定义】
typedef struct {
hi_mapi_venc_payload_type_attr payload_type_attr;
ot_media_rc_attr rc_attr; /* 码率控制（CBR/VBR/QVBR/CVBR/AVBR，H.264/H.265/MJPEG） */
hi_mapi_venc_gop_attr gop_attr;
ot_media_rc_param rc_param;
hi_mapi_venc_intra_refresh intra_refresh;
hi_mapi_frame_rate_ctrl frame_rate;
td_bool framelost_strategy;
} hi_fw_media_venc_chn_attr;
【成员】
| 成员名称 | 描述 |
|---|---|
payload_type_attr |
编码负载类型属性（H.264 / H.265 / MJPEG 及缓冲区大小等）。 |
rc_attr |
码率控制属性（含各编码格式的 CBR / VBR / QVBR / CVBR / AVBR 子结构）。 |
gop_attr |
GOP 属性。 |
rc_param |
码率控制参数（首帧起始 QP）。 |
intra_refresh |
帧内刷新属性。 |
frame_rate |
帧率控制。 |
framelost_strategy |
丢帧策略。 |
【注意事项】
- 通过
hi_fw_media_venc_set_attr()修改时，通道需处于已初始化、未启动状态。
【相关数据类型及接口】
hi_fw_media_venc_get_attr、hi_fw_media_venc_set_attr。
4.5 hi_fw_media_osd_cfg
【说明】
OSD 启动配置，描述叠加元素数量、基准字号 / 图片尺寸及各 OSD 属性。
【定义】
typedef struct {
td_u32 osd_cnt;
hi_mapi_size base_font_size;
hi_mapi_size base_image_size;
hi_mapi_osd_attr osd_attr[OT_MEDIA_OSD_MAX_CNT];
} hi_fw_media_osd_cfg;
【成员】
| 成员名称 | 描述 |
|---|---|
osd_cnt |
OSD 叠加元素数量。 |
base_font_size |
基准字体尺寸。 |
base_image_size |
基准图片尺寸。 |
osd_attr |
各 OSD 元素属性数组。 |
【注意事项】
osd_cnt不能超过OT_MEDIA_OSD_MAX_CNT。
【相关数据类型及接口】
hi_fw_media_osd_start。
4.6 hi_fw_media_osd_font_attr
【说明】
OSD 字体库属性，定义字体像素尺寸与字体获取回调。
【定义】
typedef hi_mapi_sys_font_attr hi_fw_media_osd_font_attr;
/* hi_mapi_sys_font_attr: */
typedef struct {
td_u32 font_width; /* OSD 字体宽度（像素） */
td_u32 font_height; /* OSD 字体高度（像素） */
hi_mapi_sys_get_font_mod_cb get_font_mod_cb; /* 字体取模回调 */
} hi_mapi_sys_font_attr;
【成员】
| 成员名称 | 描述 |
|---|---|
font_width |
字体宽度（像素）。 |
font_height |
字体高度（像素）。 |
get_font_mod_cb |
字体取模回调，由应用提供字形数据。 |
【注意事项】
get_font_mod_cb需在初始化前设置，否则 OSD 无法渲染字符。
【相关数据类型及接口】
hi_fw_media_osd_init。
4.7 hi_fw_media_aenc_cb
【说明】
音频编码回调结构，编码完成后由框架回调 proc_data_cb 返回码流。
【定义】
typedef hi_mapi_aenc_callback hi_fw_media_aenc_cb;
/* hi_mapi_aenc_callback:*/
typedef td_s32 (*hi_mapi_aenc_proc_data_cb)(td_handle aenc_hdl,
const hi_mapi_audio_stream *audio_stream_data, td_void *private_data);
typedef struct {
hi_mapi_aenc_proc_data_cb proc_data_cb;
td_void *private_data;
} hi_mapi_aenc_callback;
【成员】
| 成员名称 | 描述 |
|---|---|
proc_data_cb |
数据回调，参数为音频编码句柄、编码后码流、私有数据。 |
private_data |
私有数据，回调原样返回。 |
【注意事项】
proc_data_cb不能为 NULL。
【相关数据类型及接口】
hi_fw_media_aenc_reg_cb、hi_fw_media_aenc_unreg_cb。
4.8 hi_fw_media_venc_cb
【说明】
视频编码回调结构，编码完成后由框架回调 proc_data_cb 返回码流。
【定义】
typedef hi_mapi_venc_call_back hi_fw_media_venc_cb;
/* hi_mapi_venc_call_back:*/
typedef td_s32 (*hi_mapi_venc_proc_data)(td_handle venc_hdl, hi_mapi_venc_data_attr *stream_data,
td_void *private_data);
typedef struct {
hi_mapi_venc_proc_data proc_data_cb;
td_void *private_data;
} hi_mapi_venc_call_back;
【成员】
| 成员名称 | 描述 |
|---|---|
proc_data_cb |
数据回调，参数为视频编码句柄、码流数据、私有数据。 |
private_data |
私有数据，回调原样返回。 |
【注意事项】
proc_data_cb不能为 NULL。
【相关数据类型及接口】
hi_fw_media_venc_reg_cb、hi_fw_media_venc_unreg_cb。
4.9 hi_fw_media_acap_cb
【说明】
ACAP 帧回调结构，用于获取 post-AFE PCM 数据。
【定义】
typedef td_s32 (*hi_fw_media_acap_proc_cb)(td_handle acap_hdl,
const hi_mapi_audio_frame *frame, td_void *priv_data);
typedef struct {
hi_fw_media_acap_proc_cb proc_frame_cb;
td_void *private_data;
} hi_fw_media_acap_cb;
【成员】
| 成员名称 | 描述 |
|---|---|
proc_frame_cb |
帧回调，参数为 ACAP 句柄、音频帧（PCM）、私有数据。 |
private_data |
私有数据，回调原样返回。 |
【注意事项】
proc_frame_cb不能为 NULL。
【相关数据类型及接口】
hi_fw_media_acap_reg_cb、hi_fw_media_acap_unreg_cb。
4.10 hi_fw_media_disp_window_attr
【说明】
显示窗口属性，定义窗口位置 / 大小与优先级。
【定义】
typedef hi_mapi_disp_window_attr hi_fw_media_disp_window_attr;
/* hi_mapi_disp_window_attr:*/
typedef struct {
hi_mapi_rect rect; /* 窗口位置与大小 */
td_u32 priority; /* 窗口优先级 */
} hi_mapi_disp_window_attr;
【成员】
| 成员名称 | 描述 |
|---|---|
rect |
窗口矩形（x、y、width、height）。 |
priority |
窗口优先级，数值越大越靠前（取决于平台实现）。 |
【注意事项】
- 窗口位置 / 大小不能超出屏幕范围。
【相关数据类型及接口】
hi_fw_media_disp_set_window_attr、hi_fw_media_disp_get_window_attr。
4.11 hi_fw_media_frame_data
【说明】
视频帧数据，描述一帧图像的分辨率、格式、地址与时间戳等信息。
【定义】
typedef hi_mapi_frame_data hi_fw_media_frame_data;
/* hi_mapi_frame_data（关键成员）:*/
typedef struct {
hi_mapi_frame_data_type frame_data_type;
td_u32 width;
td_u32 height;
hi_mapi_pixel_format pixel_format;
hi_mapi_video_format video_format;
td_u64 phy_addr[HI_MAPI_FRAME_DATA_ADDR_NUM]; /* 物理地址 */
td_u64 vir_addr[HI_MAPI_FRAME_DATA_ADDR_NUM]; /* 虚拟地址 */
td_u32 stride[HI_MAPI_FRAME_DATA_ADDR_NUM]; /* 行跨度 */
...
td_u64 pts; /* 时间戳 */
td_u32 pool_id;
hi_mapi_video_supplement video_supplement;
} hi_mapi_frame_data;
【成员】
| 成员名称 | 描述 |
|---|---|
frame_data_type |
帧数据类型（RAW / YUV）。 |
width / height |
帧宽高。 |
pixel_format |
像素格式。 |
video_format |
视频格式。 |
phy_addr / vir_addr / stride |
各平面的物理地址、虚拟地址与行跨度。 |
pts |
时间戳。 |
pool_id |
VB 池 ID。 |
video_supplement |
视频补充信息。 |
【注意事项】
【相关数据类型及接口】
hi_fw_media_disp_send_frame。
5 错误码
本模块接口统一返回 0（TD_SUCCESS）表示成功，非 0 表示失败。失败时接口返回值可能来自以下三类错误。
5.1 框架层错误（OT_MEDIA_E*）
适配层（ss_media_*.c）内部使用一组自有错误码，定义于 components/media/framework/component_adapter/media/include/ot_media_comm_define.h：
| 错误码 | 值 | 描述 |
|---|---|---|
OT_MEDIA_EINVAL |
-1 | 输入参数非法（空指针、枚举越界、计数不合法等）。 |
OT_MEDIA_ENOTINIT |
-2 | 前置模块未初始化（如未调用 hi_fw_media_init 即启动 VENC）。 |
OT_MEDIA_EUNSUPPORT |
-3 | 当前操作 / 类型不支持。 |
OT_MEDIA_EINITIALIZED |
-4 | 重复初始化。 |
OT_MEDIA_EINTER |
-5 | 框架内部处理失败。 |
透传说明：
OT_MEDIA_E*属于框架内部错误码，是否到达hi_fw_media_xxx接口取决于运行模式与具体接口的返回值处理：
- 直连模式（Direct）：消息处理函数把适配层返回值通过 light_msg 原样带回调用侧。多数接口（如
hi_fw_media_ai_init、hi_fw_media_adec_init、hi_fw_media_aenc_reg_cb等）直接返回该值，此时OT_MEDIA_E*会透传出来；但部分接口（如hi_fw_media_init）会把任何非0返回值统一收敛为TD_FAILURE（-1）。因此直连模式下OT_MEDIA_E*可能透传也可能被收敛，不能依赖其具体数值。- 跨进程模式（IPC / Client）：客户端把服务端适配层返回的任何非
0值统一映射为TD_FAILURE（-1），OT_MEDIA_E*不会透传到客户端接口，调用方只能看到成功（0）或失败（-1）。
5.2 底层错误码（hi_mapi_*）
直连模式下，部分 ss_media_* 实现会把底层 hi_mapi_* 模块的返回值直接透传（如 ss_media_init_venc 直接返回 media_init_venc 的结果）。这些错误码格式（见 components/media/pipeline/include/hi_mapi_errno.h）与常见公共错误码如下：
错误码格式：
#define HI_MAPI_ERR_APPID (0x80000000L + 0x23000000L) /* 0xA3000000 */
#define HI_MAPI_DEF_ERR(module, level, errid) \
((td_s32)((HI_MAPI_ERR_APPID) | ((module) << 16) | ((level) << 13) | (errid)))
其中 level 固定为 4（MAPI_EN_ERR_LEVEL_ERROR），module 为模块 ID（8 位，因模块而异），errid 为错误 ID（低 13 位，下表）。实际错误码数值以头文件宏展开为准。
| 错误 ID（errid） | 宏定义 | 描述 |
|---|---|---|
| 0x0001 | MAPI_EN_ERR_INVALID_DEVID |
设备号无效。 |
| 0x0002 | MAPI_EN_ERR_INVALID_CHNID |
通道号无效。 |
| 0x0003 | MAPI_EN_ERR_ILLEGAL_PARAM |
输入参数非法。 |
| 0x0004 | MAPI_EN_ERR_EXIST |
资源已存在。 |
| 0x0005 | MAPI_EN_ERR_UNEXIST |
资源不存在。 |
| 0x0006 | MAPI_EN_ERR_NULL_PTR |
输入参数空指针。 |
| 0x0007 | MAPI_EN_ERR_NOT_CONFIG |
未配置属性即尝试启用 / 初始化。 |
| 0x0008 | MAPI_EN_ERR_NOT_SUPPORT |
当前不支持的操作 / 类型。 |
| 0x0009 | MAPI_EN_ERR_NOT_PERM |
操作不被允许（如修改静态属性）。 |
| 0x000C | MAPI_EN_ERR_NOMEM |
内存分配失败。 |
| 0x000D | MAPI_EN_ERR_NOBUF |
缓冲区分配失败。 |
| 0x000E | MAPI_EN_ERR_BUF_EMPTY |
缓冲区无数据。 |
| 0x000F | MAPI_EN_ERR_BUF_FULL |
缓冲区已满。 |
| 0x0010 | MAPI_EN_ERR_SYS_NOTREADY |
系统未初始化 / 未就绪。 |
| 0x0012 | MAPI_EN_ERR_BUSY |
设备 / 资源忙。 |
| 0x0014 | MAPI_EN_ERR_ILLEGAL_HANDLE |
句柄非法（越界）。 |
| 0x0015 | MAPI_EN_ERR_NOT_INITED |
系统 / 模块未初始化。 |
| 0x0016 | MAPI_EN_ERR_OPERATE_FAIL |
模块操作失败（如启动设备失败）。 |
| 0x0017 | MAPI_EN_ERR_TIME_OUT |
操作超时。 |
5.3 通信 / 通道错误
- 直连模式（Direct）：
light_msg自身错误码可能作为返回值出现（如消息超时LIGHT_MSG_EMSG_SYNC_MSG_TIMEOUT=0x80002005、参数非法LIGHT_MSG_EINVALARG=0x80000003等），数值远大于-5，可据此与框架层 / 底层错误区分。 - 跨进程模式（IPC / Client）：
channel_client通信失败统一返回TD_FAILURE（-1）。
说明：
module因模块而异（如HI_MAPI_MOD_VENC、HI_MAPI_MOD_DISP等）；跨进程模式下所有失败统一收敛为TD_FAILURE（-1），无法从返回值区分具体错误类型，如需定位具体原因需结合服务端日志（HI_LOGE）。
6 使用注意事项
-
句柄范围：
venc_hdl、aenc_hdl、adec_hdl、acap_hdl、ao_hdl、disp_hdl、wnd_hdl等句柄均由场景参数集或初始化流程创建，应用只使用、不自行构造；句柄合法性由底层校验，非法句柄返回MAPI_EN_ERR_ILLEGAL_HANDLE等错误。 -
时序依赖：遵循以下启停顺序（停止为逆序）：
direct_init / client_init // 模式初始化 → media_init // 媒体系统 → set_scene(audio / video) // 选择场景参数集（在 *_init 之前） → vi_init → venc_init // 视频：VI → VENC → ai_init → aenc_init // 音频：AI → AENC → ao_init / adec_init // 音频输出 / 解码 → osd_init → osd_start // OSD → disp_init → start_window // 显示 → venc_start / aenc_start // 启动编码停止（逆序）：
venc_stop / aenc_stop
→ osd_stop → osd_deinit
→ stop_window → disp_deinit
→ adec_deinit / ao_deinit
→ aenc_deinit → ai_deinit
→ venc_deinit → vi_deinit
→ media_deinit
→ direct_deinit / client_deinit
-
资源配对：
hi_fw_media_disp_get_video_screen()与hi_fw_media_disp_release_video_screen()成对调用；hi_fw_media_venc_reg_cb()/hi_fw_media_venc_unreg_cb()、hi_fw_media_aenc_reg_cb()/hi_fw_media_aenc_unreg_cb()、hi_fw_media_acap_reg_cb()/hi_fw_media_acap_unreg_cb()成对调用；- 各
*_init()/*_deinit()成对调用（部分接口幂等，重复调用返回成功）。
-
属性语义：
hi_fw_media_venc_set_attr()为静态属性，需在通道已初始化、未启动状态下调用；- 音量（
hi_fw_media_ao_set_vol）、静音（hi_fw_media_ao_set_mute）、翻转 / 镜像（hi_fw_media_set_flip/hi_fw_media_set_mirror）为动态属性，可在运行中修改。
-
模式差异：
- 直连模式（Direct）：调用
hi_fw_media_direct_init()，同进程消息转发，回调直接执行； - 跨进程模式（IPC）：调用
hi_fw_media_client_init(endpoint)，经消息通道转发，回调由客户端侧分发，行为与直连模式保持一致。
- 直连模式（Direct）：调用
-
回调线程：VENC / AENC / ACAP 回调在编码 / 采集线程上下文中执行，回调内应避免长时间阻塞或调用可能导致死锁的接口。
7 附注 / 关联文档
- 底层媒体实现：
components/media/framework/api/direct/media/media_impl.c - 场景参数集：
components/media/framework/api/direct/media/media_param.c/media_param.h - 跨进程桥接：
components/media/framework/api/ipc_bridge/media/ - 组件适配层：
components/media/framework/component_adapter/media/ - 底层 mapi 定义：
components/media/pipeline/include/hi_mapi_*.h、hi_mapi_errno.h