录像接口说明文档

文档版本	V1.0
修订日期	2026-08-24
对应头文件	`components/media/framework/api/include/api_record.h`
类型定义	`components/media/framework/api/include/api_record.h`、`components/media/framework/component_adapter/record/include/ss_record.h`
适用模块	MP4 录像与 SD 卡存储（Record / RECORD）

1 概述

本模块对外提供 hi_fw_record_* 系列接口，封装 MP4 录像与 SD 卡存储能力：应用配置编码类型、封装格式、VENC / AENC 通道等参数创建录像任务，框架内部通过 recorder（SS_REC_*）+ MP4 muxer（SS_MP4_*）+ 存储（SS_STORAGE_* / DCF）三层中间件完成取流、封装与落盘，录像文件按分片策略切分，文件关闭 / 存储异常等事件经回调上报。支持多任务（最多 4 路）独立录制。

支持两种运行模式：

直连模式（Direct）：应用与录像服务同进程，通过 hi_fw_record_direct_init() / hi_fw_record_direct_deinit() 启动 / 释放模式级资源，经 light_msg 通道直接调用中间件；
跨进程模式（Client / IPC）：应用与录像服务分进程，通过 hi_fw_record_client_init() / hi_fw_record_client_deinit() 建立 / 断开 channel 客户端，经 IPC 调用远端 record 服务。

模型层次：

录像模块（hi_fw_record_*）
  ├─ 存储（Storage：探测 SD 卡 / 回退目录 + 容量查询）
  ├─ recorder（SS_REC_*：取流、分片、事件回调）
  │    ├─ 视频轨（VENC 通道数据 → MP4 视频轨）
  │    └─ 音频轨（AENC 通道数据 → MP4 音频轨，可选）
  └─ MP4 muxer（SS_MP4_*：封装为 MP4 文件）
        └─ 录像任务（hi_fw_record_cfg，共 4 个槽位，task_id = 0~3）

2 接口总览

编号	接口	模块	功能概述
1	`hi_fw_record_direct_init`	模式管理	初始化直连模式录像模块
2	`hi_fw_record_direct_deinit`	模式管理	去初始化直连模式录像模块
3	`hi_fw_record_client_init`	模式管理	初始化跨进程模式录像客户端
4	`hi_fw_record_client_deinit`	模式管理	去初始化跨进程模式录像客户端
5	`hi_fw_record_init`	模块管理	初始化录像模块（存储 + recorder 引擎）
6	`hi_fw_record_deinit`	模块管理	去初始化录像模块（停止并销毁所有任务）
7	`hi_fw_record_create_task`	任务管理	创建录像任务并分配 task_id
8	`hi_fw_record_destroy_task`	任务管理	销毁录像任务并释放槽位
9	`hi_fw_record_start`	任务管理	按任务启动录像
10	`hi_fw_record_stop`	任务管理	按任务停止录像
11	`hi_fw_record_get_status`	状态查询	获取录像状态
12	`hi_fw_record_get_storage_info`	存储查询	获取 SD 卡存储信息
13	`hi_fw_record_register_event_cb`	事件	注册录像事件回调

3 API 参考

3.1 hi_fw_record_direct_init

【描述】

初始化直连模式录像模块：创建录像服务实现（record_impl）并建立 light_msg 客户端通道。仅在直连模式下调用。幂等：已初始化时重复调用直接返回成功。

【语法】

td_s32 hi_fw_record_direct_init(td_void);

【参数】

无。

【返回值】

返回值	描述
`0`	初始化成功。
`-1`	初始化失败（`TD_FAILURE`）。

【注意】

仅在直连模式下调用；跨进程模式应调用 hi_fw_record_client_init()；
需在 hi_fw_record_init() / hi_fw_record_create_task() 之前调用；
幂等：已初始化时重复调用返回成功；
与 hi_fw_record_direct_deinit() 成对调用（见 3.2）。

【举例】

td_s32 ret = hi_fw_record_direct_init();
if (ret != 0) {
    /* 处理失败 */
}

3.2 hi_fw_record_direct_deinit

【描述】

去初始化直连模式录像模块：释放 light_msg 通道与 record 引擎资源（light_msg_deinit + record_impl_destroy）。仅在直连模式下调用，始终成功。

【语法】

td_void hi_fw_record_direct_deinit(td_void);

【参数】

无。

【返回值】

无（td_void，始终成功）。

【注意】

与 hi_fw_record_direct_init() 成对调用；未初始化时调用安全（内部对空句柄判空后返回）；
本接口只释放模式级资源（light_msg 通道 + record 引擎），模块级资源（存储 / recorder）由 hi_fw_record_deinit()（见 3.6）释放；
跨进程模式应调用 hi_fw_record_client_deinit()（见 3.4）。

【举例】

hi_fw_record_direct_deinit();

3.3 hi_fw_record_client_init

【描述】

初始化跨进程模式录像客户端，建立应用进程到远端 record 服务的 channel 通道。仅在跨进程模式下调用。

【语法】

td_s32 hi_fw_record_client_init(const td_char *endpoint);

【参数】

参数名称	输入/输出	类型	描述
`endpoint`	输入	`const td_char *`	IPC 端点路径，如 `/tmp/ipc_record.sock`；为 `NULL` 或空串时使用默认端点 `/tmp/ipc_record.sock`。

【返回值】

返回值	描述
`0`	初始化成功。
`-1`	初始化失败（`TD_FAILURE`）。

【注意】

仅在跨进程模式下调用；直连模式应调用 hi_fw_record_direct_init()；
endpoint 为 NULL 或空串时使用默认端点 /tmp/ipc_record.sock（可由编译宏 API_RECORD_CLIENT_ENDPOINT 覆盖）；
幂等：已初始化时重复调用返回成功；
与 hi_fw_record_client_deinit() 成对调用（见 3.4）。

【举例】

td_s32 ret = hi_fw_record_client_init("/tmp/ipc_record.sock");
if (ret != 0) {
    /* 处理失败 */
}

3.4 hi_fw_record_client_deinit

【描述】

去初始化跨进程模式录像客户端：断开与远端 record 服务的连接（channel_client_unregister + channel_client_deinit）。仅在跨进程模式下调用。

【语法】

td_s32 hi_fw_record_client_deinit(td_void);

【参数】

无。

【返回值】

返回值	描述
`0`	去初始化成功（`TD_SUCCESS`）。

【注意】

与 hi_fw_record_client_init() 成对调用；
幂等：未初始化时调用返回 TD_SUCCESS（0），安全；
本接口只断开客户端连接，远端服务端录像模块资源由对端 hi_fw_record_deinit() 释放。

【举例】

hi_fw_record_client_deinit();

3.5 hi_fw_record_init

【描述】

初始化录像模块：初始化存储（探测 SD 卡）与 recorder 引擎。未检测到 SD 卡时不会返回错误，而是回退到 /mnt 目录继续。幂等：已初始化时重复调用返回成功。

【语法】

td_s32 hi_fw_record_init(td_void);

【参数】

无。

【返回值】

返回值	描述
`0`	初始化成功。
`-1`	初始化失败（`TD_FAILURE`）。

【注意】

需在模式初始化（direct_init / client_init）之后调用；
SD 卡探测：/mnt/sd 存在且可写则作为录制路径，否则回退到 /mnt（头文件注释"未检测到存储设备时返回错误码"与实现不符，以实际行为为准）；
幂等：已初始化时重复调用返回成功；
存储 / DCF 为全局共享资源，所有任务共用。

【举例】

td_s32 ret = hi_fw_record_init();
if (ret != 0) {
    /* 处理失败 */
}

3.6 hi_fw_record_deinit

【描述】

去初始化录像模块：停止并销毁所有已创建的录像任务，释放 recorder / muxer / 存储等全局资源。Client模式幂等：未初始化时调用返回成功。

【语法】

td_s32 hi_fw_record_deinit(td_void);

【参数】

无。

【返回值】

返回值	描述
`0`	去初始化成功。
`-1`	去初始化失败（`TD_FAILURE`，直连模式未初始化时）。

【注意】

与 hi_fw_record_init() 成对调用；
内部自动销毁所有任务，无需先逐个 hi_fw_record_destroy_task()；
直连模式：hi_fw_record_deinit() 负责模块级（存储 / recorder）反初始化，模式级资源由 hi_fw_record_direct_deinit()（见 3.2）单独释放；
客户端模式：未初始化时调用返回 TD_SUCCESS。

【举例】

hi_fw_record_deinit();

3.7 hi_fw_record_create_task

【描述】

创建录像任务并分配 task_id。创建即完成底层 recorder 实例创建（SS_REC_Create）并注册事件回调，任务处于 IDLE（就绪）态，之后可 start / stop / destroy。task_id 由本接口分配并返回（0 ~ 3），调用方不应自行指定，后续 start / stop / destroy 均使用该返回值。

【语法】

td_s32 hi_fw_record_create_task(td_s32 *task_id, const hi_fw_record_cfg *cfg);

【参数】

参数名称	输入/输出	类型	描述
`task_id`	输出	`td_s32 *`	输出分配到的任务标识（0 ~ 3），不能为 `NULL`。
`cfg`	输入	`const hi_fw_record_cfg *`	录像配置（`cfg.venc_chn` 决定录像通道），内部复制保存，不能为 `NULL`。

【返回值】

返回值	描述
`0`	创建成功，`task_id` 为有效任务标识。
`-1`	创建失败（`TD_FAILURE`）。`task_id` / `cfg` 为 `NULL`、槽位已满、底层 `SS_REC_Create` 失败等。

【注意】

前置条件：已完成模式初始化（direct_init / client_init）且 hi_fw_record_init() 已调用；
最多同时 4 路任务（槽位 0 ~ 3），槽位用尽返回 -1；
创建即创建 SS_REC 实例并注册事件回调；事件回调统一注册到 task 0，get_status 亦返回 task 0 状态；
cfg 内部复制保存，调用方可复用同一结构体创建多路任务。

【举例】

hi_fw_record_cfg cfg = {0};
hi_fw_record_cfg cfg2 = {0};
td_s32 task_id = -1;

/* 视频轨：H.265，VENC chn0，码率 4096 kbps，分片 60s */
cfg.codec_type     = HI_FW_RECORD_CODEC_H265;
cfg.format         = HI_FW_RECORD_FMT_MP4;
cfg.venc_chn       = 0;
cfg.aenc_chn       = HI_FW_RECORD_AENC_CHN_NONE; /* 不录音频 */
cfg.bitrate        = 4096;
cfg.file_duration  = 60;
snprintf(cfg.save_path, sizeof(cfg.save_path), "record");
snprintf(cfg.file_prefix, sizeof(cfg.file_prefix), "cam");

td_s32 ret = hi_fw_record_create_task(&task_id, &cfg);
if (ret != 0) {
    /* 处理失败 */
}

3.8 hi_fw_record_destroy_task

【描述】

销毁录像任务并释放 task_id 槽位：任务仍在录制时会先自动停止（仅停止，不反复销毁），随后释放底层 recorder 实例（SS_REC_Destroy）并回收槽位。幂等：任务已销毁 / 槽位未创建时调用返回成功。

【语法】

td_s32 hi_fw_record_destroy_task(td_s32 task_id);

【参数】

参数名称	输入/输出	类型	描述
`task_id`	输入	`td_s32`	由 `hi_fw_record_create_task()` 返回的任务标识。

【返回值】

返回值	描述
`0`	销毁成功。
`-1`	销毁失败（`TD_FAILURE`）。`task_id` 越界（< 0 或 >= 4）等。

【注意】

与 hi_fw_record_create_task() 成对调用；
内部先停止录制再销毁实例，无需先调用 hi_fw_record_stop()；
已销毁 / 未创建的槽位调用返回成功（幂等）；
销毁后槽位可被后续 create_task 复用。

【举例】

hi_fw_record_destroy_task(task_id);

3.9 hi_fw_record_start

【描述】

按任务启动录像：底层 SS_REC_Start 开始录制，注册 VENC / AENC 数据回调取流并封装落盘。任务配置已在 create_task 时传入，本接口仅按 task_id 启动。若该任务已在录制，会先自动停止再重新开始（重复 start 有效）。

【语法】

td_s32 hi_fw_record_start(td_s32 task_id);

【参数】

参数名称	输入/输出	类型	描述
`task_id`	输入	`td_s32`	任务标识，由 `hi_fw_record_create_task()` 返回。

【返回值】

返回值	描述
`0`	启动成功。
`-1`	启动失败（`TD_FAILURE`）。`task_id` 越界、任务未创建、底层 `SS_REC_Start` 失败等。

【注意】

需在 hi_fw_record_create_task() 成功之后调用；
不同 task_id 独立运行，互不影响；
已在录制的任务重复 start 会先停止再重新开始（非直接返回成功）；
录制数据来自 cfg.venc_chn / cfg.aenc_chn 对应通道，需先建立好 VENC / AENC 通道（媒体框架 hi_fw_media_*）。

【举例】

td_s32 ret = hi_fw_record_start(task_id);
if (ret != 0) {
    /* 处理失败 */
}

3.10 hi_fw_record_stop

【描述】

按任务停止录像：仅停止录制（SS_REC_Stop），不销毁 recorder 实例，停止后仍可再次 start。幂等：任务未在录制时调用返回成功。

【语法】

td_s32 hi_fw_record_stop(td_s32 task_id);

【参数】

参数名称	输入/输出	类型	描述
`task_id`	输入	`td_s32`	任务标识，由 `hi_fw_record_create_task()` 返回。

【返回值】

返回值	描述
`0`	停止成功。
`-1`	停止失败（`TD_FAILURE`）。`task_id` 越界、任务未创建等。

【注意】

与 hi_fw_record_start() 成对调用；
停止后任务回到 IDLE 态，可再次 start（重新开始计数）；
停止会关闭当前录像文件并产生 HI_FW_RECORD_EVENT_FILE_CLOSED 事件（若已注册回调）。

【举例】

hi_fw_record_stop(task_id);

3.11 hi_fw_record_get_status

【描述】

获取录像状态（状态、文件数、当前文件大小等）。

【语法】

td_s32 hi_fw_record_get_status(hi_fw_record_status *status);

【参数】

参数名称	输入/输出	类型	描述
`status`	输出	`hi_fw_record_status *`	输出状态信息，不能为 `NULL`。

【返回值】

返回值	描述
`0`	获取成功，`status` 有效。
`-1`	获取失败（`TD_FAILURE`）。`status` 为 `NULL`、直连模式未初始化等。

【注意】

无 task_id 参数，固定返回 task 0 的状态（兼容旧接口），多任务场景无法区分各路状态；
status->duration_ms 字段当前未填充（恒为 0）；state / file_count / file_size 有效；
直连模式下未初始化时返回的状态为 HI_FW_RECORD_STATUS_IDLE。

【举例】

hi_fw_record_status status = {0};
td_s32 ret = hi_fw_record_get_status(&status);
if (ret == 0 && status.state == HI_FW_RECORD_STATUS_RECORDING) {
    /* 录制中 */
}

3.12 hi_fw_record_get_storage_info

【描述】

获取 SD 卡存储信息（挂载路径、总容量、可用空间、是否已挂载）。

【语法】

td_s32 hi_fw_record_get_storage_info(hi_fw_storage_info *info);

【参数】

参数名称	输入/输出	类型	描述
`info`	输出	`hi_fw_storage_info *`	输出存储信息，不能为 `NULL`。

【返回值】

返回值	描述
`0`	获取成功，`info` 有效。
`-1`	获取失败（`TD_FAILURE`）。`info` 为 `NULL`、模块未初始化、存储路径查询失败（`mounted` 置 `TD_FALSE`）。

【注意】

mount_path 为实际录制路径：有 SD 卡时为 /mnt/sd，回退时为 /mnt；
容量信息经 statvfs 查询，单位为 KB（total_kb / free_kb）；
直连模式下未初始化时返回失败，mounted 置 TD_FALSE。IPC 模式恒返回成功，以 mounted 判断。

【举例】

hi_fw_storage_info info = {0};
td_s32 ret = hi_fw_record_get_storage_info(&info);
if (ret == 0 && info.mounted) {
    /* info.mount_path / info.total_kb / info.free_kb 有效 */
}

3.13 hi_fw_record_register_event_cb

【描述】

注册录像事件回调（文件关闭、存储满、存储错误等）。仅直连模式有效；跨进程模式下函数指针无法跨进程传递，仅记录注册意图，回调不会触发。

【语法】

td_s32 hi_fw_record_register_event_cb(hi_fw_record_event_cb cb,
    TD_MW_PTR user_data);

【参数】

参数名称	输入/输出	类型	描述
`cb`	输入	`hi_fw_record_event_cb`	回调函数指针，可为 `NULL`（注销）。
`user_data`	输入	`TD_MW_PTR`	用户数据，随回调原样回传。

【返回值】

返回值	描述
`0`	注册成功。
`-1`	注册失败（`TD_FAILURE`）。直连模式未初始化时。

【注意】

回调注册到 task 0（全局回调），仅 task 0 的事件会触发；
回调在中间件事件线程上下文中执行，回调内应避免长时间阻塞；
事件映射见 hi_fw_record_event_e；
跨进程（Client）模式下：头文件已明确"IPC 跨进程无法安全转发回调，注册返回成功但回调不会触发"；实际实现中服务端仅记录注册意图（record_msg.c 恒返回 TD_SUCCESS），回调不会触发。

【举例】

static td_s32 on_record_event(hi_fw_record_event_e event, TD_MW_PTR user_data)
{
    printf("record event=%d\n", event);
    return 0;
}

hi_fw_record_register_event_cb(on_record_event, NULL);

4 数据类型

4.1 hi_fw_record_codec_e（编码类型枚举）

【说明】

录像编码类型，用于 hi_fw_record_cfg.codec_type。

【定义】

typedef enum {
    HI_FW_RECORD_CODEC_H264 = 0,
    HI_FW_RECORD_CODEC_H265 = 1,
    HI_FW_RECORD_CODEC_MJPEG = 2,
    HI_FW_RECORD_CODEC_BUTT
} hi_fw_record_codec_e;

【成员】

成员名称	值	描述
`HI_FW_RECORD_CODEC_H264`	0	H.264 编码。
`HI_FW_RECORD_CODEC_H265`	1	H.265 编码。
`HI_FW_RECORD_CODEC_MJPEG`	2	MJPEG 编码（枚举保留）。
`HI_FW_RECORD_CODEC_BUTT`	3	枚举结束标志（非法值）。

【注意事项】

当前实现仅区分 H.264 / H.265（MJPEG 会落入 H.264 分支），实际以 VENC 通道输出码流为准。

【相关数据类型及接口】

类型：hi_fw_record_cfg
接口：hi_fw_record_create_task

4.2 hi_fw_record_format_e（存储格式枚举）

【说明】

录像文件封装格式，用于 hi_fw_record_cfg.format。

【定义】

typedef enum {
    HI_FW_RECORD_FMT_MP4 = 0,
    HI_FW_RECORD_FMT_TS  = 1,
    HI_FW_RECORD_FMT_BUTT
} hi_fw_record_format_e;

【成员】

成员名称	值	描述
`HI_FW_RECORD_FMT_MP4`	0	MP4 封装（当前唯一实现）。
`HI_FW_RECORD_FMT_TS`	1	TS 封装（枚举保留，未实现）。
`HI_FW_RECORD_FMT_BUTT`	2	枚举结束标志（非法值）。

【注意事项】

当前仅支持 MP4 封装，TS 未实现。

【相关数据类型及接口】

类型：hi_fw_record_cfg
接口：hi_fw_record_create_task

4.3 hi_fw_record_status_e（录像状态枚举）

【说明】

录像运行状态，用于 hi_fw_record_status.state。

【定义】

typedef enum {
    HI_FW_RECORD_STATUS_IDLE      = 0,
    HI_FW_RECORD_STATUS_RECORDING = 1,
    HI_FW_RECORD_STATUS_PAUSED    = 2,
    HI_FW_RECORD_STATUS_ERROR     = 3,
    HI_FW_RECORD_STATUS_BUTT
} hi_fw_record_status_e;

【成员】

成员名称	值	描述
`HI_FW_RECORD_STATUS_IDLE`	0	空闲（未录制 / 已停止）。
`HI_FW_RECORD_STATUS_RECORDING`	1	录制中。
`HI_FW_RECORD_STATUS_PAUSED`	2	已暂停（枚举保留）。
`HI_FW_RECORD_STATUS_ERROR`	3	错误状态（枚举保留）。
`HI_FW_RECORD_STATUS_BUTT`	4	枚举结束标志（非法值）。

【注意事项】

当前实现仅产生 IDLE / RECORDING 两种状态；PAUSED / ERROR 为预留。

【相关数据类型及接口】

类型：hi_fw_record_status
接口：hi_fw_record_get_status

4.4 hi_fw_record_event_e（录像事件枚举）

【说明】

录像事件类型，经 hi_fw_record_event_cb 回调上报。

【定义】

typedef enum {
    HI_FW_RECORD_EVENT_FILE_CLOSED     = 0,  /* 文件关闭 (分裂/停止)  */
    HI_FW_RECORD_EVENT_STORAGE_FULL    = 1,  /* 存储空间满            */
    HI_FW_RECORD_EVENT_STORAGE_ERROR   = 2,  /* 存储错误 (卡拔出等)   */
    HI_FW_RECORD_EVENT_WRITE_SLOW      = 3,  /* 写入速度慢            */
    HI_FW_RECORD_EVENT_BUTT
} hi_fw_record_event_e;

【成员】

成员名称	值	描述
`HI_FW_RECORD_EVENT_FILE_CLOSED`	0	文件关闭（分片结束 / 停止时触发）。
`HI_FW_RECORD_EVENT_STORAGE_FULL`	1	存储空间满（当前水线告警禁用，实际不触发）。
`HI_FW_RECORD_EVENT_STORAGE_ERROR`	2	存储错误（创建 / 写 / 关文件失败、内部操作失败）。
`HI_FW_RECORD_EVENT_WRITE_SLOW`	3	写入速度慢（枚举保留，当前不触发）。
`HI_FW_RECORD_EVENT_BUTT`	4	枚举结束标志（非法值）。

【注意事项】

底层事件映射：NEW_FILE_END / NEW_MANUAL_SPLIT_FILE_END → FILE_CLOSED；创建 / 写 / 关文件失败、内部操作失败 → STORAGE_ERROR；ringbuf 高水位 → STORAGE_FULL（当前水线禁用，不触发）。

【相关数据类型及接口】

回调：hi_fw_record_event_cb
接口：hi_fw_record_register_event_cb

4.5 hi_fw_record_cfg（录像配置）

【说明】

创建录像任务所需的配置：编码类型、封装格式、VENC / AENC 通道、码率、分片、存储目录与文件名前缀。

【定义】

typedef struct {
    hi_fw_record_codec_e    codec_type;     /* 编码类型              */
    hi_fw_record_format_e   format;         /* 文件封装格式          */
    td_u32                  venc_chn;       /* VENC 通道号           */
    td_u32                  aenc_chn;       /* AENC 通道号, HI_FW_RECORD_AENC_CHN_NONE=不录音频 */
    td_u32                  bitrate;        /* 目标码率 (kbps)       */
    td_u32                  file_duration;  /* 文件分裂间隔 (秒), 0=不分裂 */
    td_char                 save_path[128]; /* 存储子目录            */
    td_char                 file_prefix[64]; /* 文件名前缀            */
} hi_fw_record_cfg;

【成员】

成员名称	描述
`codec_type`	编码类型（见 `hi_fw_record_codec_e`）。
`format`	文件封装格式（见 `hi_fw_record_format_e`，当前仅 MP4）。
`venc_chn`	VENC 通道号，决定录像视频源（必填）。
`aenc_chn`	AENC 通道号；`HI_FW_RECORD_AENC_CHN_NONE`（`0xFFFFFFFF`）表示不录音频。
`bitrate`	目标码率（kbps），作为 MP4 视频轨 bitrate。
`file_duration`	文件分裂间隔（秒）；`0` 时使用默认值 60 秒。
`save_path`	存储子目录（当前实现拼接在 `DCIM/100HSCAM/` 下，详见注意）。
`file_prefix`	文件名前缀（当前实现固定为 `100HSCAM_`，见注意）。

【注意事项】

音频轨当前固定为 AAC（48 kHz / 2 声道 / 16 bit / 每帧 1024 采样），由 aenc_chn 决定是否添加；
实际录制路径固定为 <mount>/DCIM/100HSCAM/，文件名为 100HSCAM_YYYYMMDDHHMMSS_XXXX.MP4；save_path / file_prefix 当前未参与实际文件名生成；
文件保留策略：SD 卡路径（/mnt/sd）最多保留 30 个文件，回退路径（/mnt）最多保留 10 个，超限删除最老文件；
分片默认 60 秒，文件系统单文件大小上限 4 GB（maxFileSizeGB）。

【相关数据类型及接口】

类型：hi_fw_record_codec_e、hi_fw_record_format_e
接口：hi_fw_record_create_task

4.6 hi_fw_record_status（录像运行状态）

【说明】

录像运行状态信息，经 hi_fw_record_get_status() 获取。

【定义】

typedef struct {
    hi_fw_record_status_e   state;          /* 当前状态              */
    td_u64                  duration_ms;    /* 已录像时长 (毫秒)     */
    td_u64                  file_size;      /* 当前文件大小 (字节)   */
    td_s32                  file_count;     /* 已生成文件数           */
} hi_fw_record_status;

【成员】

成员名称	描述
`state`	当前状态（见 `hi_fw_record_status_e`）。
`duration_ms`	已录像时长（毫秒），当前实现未填充（恒为 0）。
`file_size`	当前文件大小（字节）。
`file_count`	已生成文件数。

【注意事项】

get_status 固定返回 task 0 的状态；duration_ms 当前不填充。

【相关数据类型及接口】

类型：hi_fw_record_status_e
接口：hi_fw_record_get_status

4.7 hi_fw_storage_info（SD 卡存储信息）

【说明】

SD 卡存储信息，经 hi_fw_record_get_storage_info() 获取。

【定义】

typedef struct {
    td_char     mount_path[128];            /* 挂载路径              */
    td_u64      total_kb;                   /* 总容量 (KB)           */
    td_u64      free_kb;                    /* 可用空间 (KB)         */
    td_bool     mounted;                    /* 是否已挂载             */
} hi_fw_storage_info;

【成员】

成员名称	描述
`mount_path`	实际录制路径（`/mnt/sd` 或回退 `/mnt`）。
`total_kb`	总容量（KB）。
`free_kb`	可用空间（KB）。
`mounted`	存储是否已挂载 / 可查询。

【注意事项】

容量信息经 statvfs 查询；查询失败时 mounted 置 TD_FALSE。

【相关数据类型及接口】

接口：hi_fw_record_get_storage_info

4.8 hi_fw_record_event_cb（事件回调）

【说明】

录像事件回调类型，经 hi_fw_record_register_event_cb() 注册。

【定义】

typedef td_s32 (*hi_fw_record_event_cb)(hi_fw_record_event_e event,
    TD_MW_PTR user_data);

【成员】

参数名称	描述
`event`	录像事件（见 `hi_fw_record_event_e`）。
`user_data`	注册时传入的用户数据，原样回传。

【注意事项】

回调注册到 task 0，仅在 task 0 的事件触发时调用；
回调在中间件事件线程上下文中执行，回调内应避免长时间阻塞；
跨进程（Client）模式下回调不可用。

【相关数据类型及接口】

类型：hi_fw_record_event_e
接口：hi_fw_record_register_event_cb

4.9 关键常量

常量	取值	说明
`HI_FW_RECORD_AENC_CHN_NONE`	`0xFFFFFFFF`	AENC 通道无效值，表示不录音频。
`RECORD_MAX_INSTANCE`	4	最大录像任务数（task_id 0 ~ 3，内部常量）。
`RECORD_DEF_SPLIT_TIME_SEC`	60	默认分片时长（秒，`file_duration` 为 0 时）。
`RECORD_MAX_FILE_SD`	30	SD 卡路径保留录像文件上限（内部常量）。
`RECORD_MAX_FILE_LOCAL`	10	回退路径（`/mnt`）保留录像文件上限（内部常量）。
`RECORD_STORAGE_PARTITION`	`/mnt/sd`	默认 SD 卡挂载路径（内部常量）。
`RECORD_STORAGE_FALLBACK_PATH`	`/mnt`	无 SD 卡时的回退录制目录（内部常量）。

5 错误码

本模块接口统一返回 0（TD_SUCCESS）表示成功，非 0 表示失败。失败时的返回值来源分三类，且两种模式的行为不同。

5.1 API 层参数校验错误（TD_FAILURE）

API 层对入参做前置校验，不合法直接返回 -1（TD_FAILURE），不进入消息通道：

错误码	触发场景
`-1`（`TD_FAILURE`）	`task_id` / `cfg` / `status` / `info` 指针为 `NULL`；`task_id` 越界（< 0 或 >= 4）；槽位已满。

5.2 底层 / 业务错误（统一收敛为 TD_FAILURE）

直连（Direct）模式：与 aidetect / media 模块"底层错误码透传"不同，record 直连模式把中间件（SS_REC_* / SS_MP4_* / SS_STORAGE_*）的失败统一收敛为 TD_FAILURE（-1），不对外暴露具体错误码：

record_impl 消息处理函数把 ss_record_* 返回值写入响应缓冲，并据此返回 LIGHT_MSG_EFAIL；
直连 api 的 record_send_sync() 检测到非 LIGHT_MSG_EOK 即返回 TD_FAILURE，原始错误码被丢弃。

典型失败场景：模块未初始化即调用、SS_REC_Create / SS_REC_Start / SS_REC_Stop 失败、VENC / AENC 通道无效、statvfs 查询失败等。

5.3 通信 / 通道错误

跨进程模式（Client / IPC）：channel_client_send_sync 通信失败时，返回 CHN_* 错误码（定义于 channel_msg.h，如超时 CHN_EMSG_SYNC_MSG_TIMEOUT = 0x80002005、参数非法 CHN_EINVALARG = 0x80000003 等），数值远大于框架错误，可据此区分；通信成功后返回服务端 ret_code（TD_SUCCESS / TD_FAILURE）。
直连模式（Direct）：light_msg 通道错误（如消息超时 LIGHT_MSG_EMSG_SYNC_MSG_TIMEOUT = 0x80002005）经 record_send_sync() 统一映射为 TD_FAILURE，不会对外透传。

说明：调用方应只依赖"0 = 成功、非 0 = 失败"的语义；直连模式所有失败均为 TD_FAILURE，需结合服务端日志（模块名 record / record_impl / record_msg / record_api）定位具体原因。

6 使用注意事项

任务标识：task_id 由 hi_fw_record_create_task() 分配（0 ~ 3），共 4 路任务；start / stop / destroy 均使用该返回值，不要自行指定。

时序依赖：遵循以下启停顺序（停止为逆序）：

direct_init / client_init           // 模式初始化
  → init()                          // 初始化存储 + recorder 引擎
    → create_task(&task_id, &cfg)   // 创建任务（SS_REC_Create + 注册事件回调）
    → start(task_id)                // 启动录制（注册 VENC/AENC 回调取流）
    → [循环] get_status / get_storage_info

停止（逆序）：

stop(task_id)                       // 仅停止录制，不销毁实例
  → destroy_task(task_id)           // 停止 + 释放 SS_REC 实例 + 回收槽位
  → deinit()                        // 模块去初始化（内部销毁所有剩余任务）
  → direct_deinit() / client_deinit()  // 模式去初始化（对应启动时的 direct_init / client_init）

资源配对：
- hi_fw_record_direct_init() / hi_fw_record_direct_deinit() 与 hi_fw_record_client_init() / hi_fw_record_client_deinit() 二选一（模式级配对）；
- hi_fw_record_init() / hi_fw_record_deinit() 成对调用（模块级配对）；
- hi_fw_record_create_task() / hi_fw_record_destroy_task() 成对调用（deinit 会自动兜底销毁剩余任务）；
- hi_fw_record_start() / hi_fw_record_stop() 成对调用（destroy 会先自动停止）。
多任务限制：最多 4 路任务并发；get_status 与事件回调当前仅覆盖 task 0（get_status 无 task_id 参数、事件回调注册到 task 0），多任务场景的状态区分能力有限。
存储与文件：
- 录制路径：有 SD 卡（/mnt/sd 可写）时使用 /mnt/sd/DCIM/100HSCAM/，无卡回退 /mnt/DCIM/100HSCAM/；
- 文件名 100HSCAM_YYYYMMDDHHMMSS_XXXX.MP4，按时间戳 + 序号自动生成；
- 文件保留：SD 卡 30 个、回退路径 10 个，超限自动删除最老文件；
- 分片：file_duration（秒），0 时默认 60 秒；单文件大小上限 4 GB。
模式差异：
- 直连模式（Direct）：direct_init / direct_deinit 成对启动 / 释放模式级资源，事件回调有效（注册到 task 0），底层失败统一收敛为 TD_FAILURE；
- 跨进程模式（Client）：client_init(endpoint) / client_deinit 成对建立 / 断开连接（endpoint 为 NULL 时用默认端点 /tmp/ipc_record.sock），通信失败返回 CHN_* 错误码、服务端失败返回 TD_FAILURE，事件回调不可用（仅记录注册意图）。
数据源依赖：录像数据来自 cfg.venc_chn / cfg.aenc_chn 对应通道，需先用媒体框架（hi_fw_media_*）建立 VENC / AENC 通道；录像取流通过注册通道回调实现（hi_mapi_venc_register_callback / hi_mapi_aenc_register_callback）。
回调线程：事件回调在中间件事件线程上下文中执行，回调内应避免长时间阻塞或调用可能导致死锁的接口。

7 附注 / 关联文档

直连实现：components/media/framework/api/direct/record/api_record.c、record_impl.c、record_msg_def.h
跨进程客户端：components/media/framework/api/client/record/api_record.c
跨进程桥接：components/media/framework/api/ipc_bridge/record/（record_client.c、record_msg.c、record_payload.h、record_msg_id.h）
组件适配层：components/media/framework/component_adapter/record/（ss_record.h / ss_record.c）
消息通道：components/media/framework/api/direct/light_msg/light_msg.h、components/media/framework/ipc/interface/channel_msg.h
关联接口：媒体框架 hi_fw_media_*（VENC / AENC 通道建立，见 api_media.md）