视频模块

支持的芯片：[RTL8735C]

概述

video_module 是 video pipeline 在 AP 侧的主要接口。Camera、ISP 与 encoder 控制由 VP firmware 处理；应用程序通过 video_params_t 配置 stream，再将输出连接到 AP 侧的 MMF module。

../../_images/multimedia_pro_mmf_video_pipeline_ap_vp.drawio.svg — AP / VP 视频管线与运行时控制路径。

video_params_t video_params = {
    .stream_id = V1_STREAM_ID,
    .format    = VIDEO_H264,
    .width     = 1920,
    .height    = 1080,
    .fps       = 30,
    .gop       = 30,
    .bps       = 2000000,
    .rc_mode   = ENC_VBR,
    .min_qp    = 26,
    .max_qp    = 48,
    .qlevel    = 5,
    .ainr_en   = 0,
};

mm_context_t *video_ctx = mm_module_open(&video_module);
mm_module_ctrl(video_ctx, CMD_VIDEO_SET_PARAMS, (int)&video_params);
mm_module_ctrl(video_ctx, MM_CMD_SET_QUEUE_LEN, 60);
mm_module_ctrl(video_ctx, MM_CMD_INIT_QUEUE_ITEMS, MMQI_FLAG_DYNAMIC);
mm_module_ctrl(video_ctx, CMD_VIDEO_APPLY, 0);

stream_id

ISP 最多支持 5 个同时输出的 channel。每个 video_module instance 会占用其中一个 channel。

常量	数值	典型用途
`V1_STREAM_ID`	0	高分辨率编码 stream（录像 / 串流）
`V2_STREAM_ID`	1	中分辨率编码 stream（live streaming）
`V3_STREAM_ID`	2	低帧率编码 stream（JPEG snapshot）
`V4_STREAM_ID`	3	Raw NV12 输出（motion detection）
`V5_STREAM_ID`	4	Raw RGB 输出（NN inference input）

备注

硬件 encoder 仅支持前 3 个 channel（V1-V3）。V4 与 V5 输出 raw（未编码）ISP frame；gop、bps、rc_mode、min_qp 与 max_qp 对这些 channel 不会生效。

format

选择该 channel 的输出格式。

常量	数值	说明
`VIDEO_HEVC`	1	H.265 / HEVC encoded bitstream
`VIDEO_H264`	2	H.264 / AVC encoded bitstream
`VIDEO_JPEG`	4	JPEG encoded frame
`VIDEO_NV12`	8	Raw YUV 4:2:0 semi-planar (NV12)
`VIDEO_RGB`	16	Raw RGB888（V5 上用于 NN input）
`VIDEO_HEVC_JPEG`	5	双输出：同时输出 HEVC + JPEG
`VIDEO_H264_JPEG`	6	双输出：同时输出 H.264 + JPEG

fps / gop / bps

fps：该 channel 输出的目标 frame rate。
gop：I-frame 间隔，单位为 frame。常见设置是与 fps 相同（每秒一个 I-frame）。
bps：encoded stream 的目标 bitrate，单位为 bits per second。对 raw output（NV12、RGB）无效。

rc_mode

Encoder 的 rate control mode。

常量	数值	说明
`ENC_CVBR`	0	Constrained VBR，bitrate 受 `bps` 限制
`ENC_CBR`	1	Constant bitrate
`ENC_VBR`	2	Variable bitrate，优先维持质量，`bps` 作为参考值
`ENC_ABR`	3	Average bitrate
`ENC_CRF`	4	Constant rate factor，固定感知质量
`ENC_CQP`	5	Constant QP，固定 quantisation parameter

min_qp / max_qp

VBR/CVBR rate control 使用的 quantisation parameter 范围，用于限制画质变化。QP 越低，画质越高，frame size 也越大。典型值为：min_qp = 26，max_qp = 48。

qlevel

JPEG quality level（0-9）。仅当 format 包含 VIDEO_JPEG 时生效。数值越高，画质越好。

ainr_en

启用 AI Noise Reduction (AINR)。设为 1 表示启用，设为 0 表示关闭。AINR 是插入在 image sensor 与 ISP 之间的处理模块，因此会在 channel split 之前处理 raw sensor data。只要任一 channel 启用 AINR，就会对所有 active channel 全局启用 AINR。AINR 可改善低照度下的图像质量，但也会增加处理负载。

video_params.ainr_en = 1;  /* enable AI noise reduction (applies to all channels) */

Encoder 参数配置时机

对 AP 应用来说，encoder open 前 指的是调用 CMD_VIDEO_APPLY 之前。常见流程如下：

填好 video_params_t 与其他 init-time stream 参数。
通过 CMD_VIDEO_SET_PARAMS 送入参数。
配置 MMF queue。
调用 CMD_VIDEO_APPLY。当 channel 使用 H.264、H.265 或 JPEG 时，此步骤会要求 VP firmware 建立 stream 并打开 encoder。

CMD_VIDEO_APPLY 之后，stream 已经启动，runtime 修改应限制在 AP/VP 路径与 encoder driver 可以安全排队处理的控制项。如果运行中的 stream 需要修改 codec、resolution、profile、VUI/header 或 HRD 行为，请先停止 stream，再用新的 init-time 配置重新打开。

客户常见需求速查

需求	支持时机	建议做法
修改 codec / output format	仅 init-time	在 `CMD_VIDEO_APPLY` 前设置 `format`。如果 stream 已经运行，请停止后重新打开。
修改 width / height	仅 init-time	在 `CMD_VIDEO_APPLY` 前设置 `width` 与 `height`，因为这些值会决定 buffer geometry 与 encoder instance setup。
修改初始 frame rate	Init-time 配置	在 `CMD_VIDEO_APPLY` 前设置 `fps`，作为 stream 启动时的 baseline。
Streaming 中调整 bitrate	支持 runtime 修改	使用 runtime bitrate control path。Joint test 示例中可用 `VAPP bps <ch> <bps>`。
Streaming 中调整 QP range	支持 runtime 修改	使用 runtime QP control path。Joint test 示例中可用 `VAPP qp <ch> <min_qp> <max_qp>`。
Streaming 中修改 GOP	支持 runtime 修改	使用 runtime GOP control path。Joint test 示例中可用 `VAPP gop <ch> <gop>`。
要求输出 I-frame	支持 runtime 操作	AP code 可调用 `CMD_VIDEO_FORCE_IFRAME`；joint test 示例中可用 `VAPP i <ch>`。
修改 profile / level / VUI / SEI / HRD	仅 init-time	在 stream start 前配置。Streaming 中途修改可能导致 decoder 状态不一致、播放异常，或需要 client 重新连接。
调整 slice / deblock / CIR / ROI	Encoder driver 支持 runtime 更新	仅使用 SDK 明确提供的 AP helper。相关 helper 会走 queued coding-control path。
启用 encoder rotation / mirror	不支持	RTL configuration 未启用 encoder preprocess rotation/mirror，因此不提供 AP API。

CMD_VIDEO_* 参数速查表

以下三张表按配置时机列出所有 encoder 相关参数，以及在 AP 应用代码中使用的对应 command 与 helper。

仅 Init-time — 在 CMD_VIDEO_APPLY 之前通过 video_params_t 或 video_params_set_* helper 配置。这些参数会进入 encoder open 流程（VCEncInit()、SPS/PPS/VUI header、profile/level 检查或 HRD model），修改需要先停止 stream 再重新打开。

本组参数有三种设置方式：

直接赋值 — 适用于 stream_id、format、width、height 等基本字段，直接在 video_params_t struct initializer 中填写。
Helper 函数 (video_params_set_*) — 适用于 profile/level/tier、CABAC、SAR 与 driver SEI。Helper 会自动设置内部 flags，无需手动操作 rc_ext.flags 或 coding.flags。
rc_ext / coding flags — 适用于没有对应 helper 的高级选项。必须同时设置 flag 位 与 字段值。Flag 用于告知 VP 该字段是有意设置的——值为 0 同样有效（例如 pictureRc = 0 表示明确关闭 picture RC），VP 会忽略未设置 flag 的字段。

video_params_t video_params = {
    .stream_id = V1_STREAM_ID,
    .format    = VIDEO_H264,
    .width     = 1920,
    .height    = 1080,
    .fps       = 30,
    .gop       = 30,
    .bps       = 2000000,
    .rc_mode   = ENC_VBR,
};

/* Helper：自动设置 profile、level 与内部 flags */
video_params_set_profile_level(&video_params, ENC_H264_MAIN, 41);
video_params_set_cabac(&video_params, 1);        /* 启用 CABAC */
video_params_set_driver_sei(&video_params, 1);   /* picture timing SEI */

/* rc_ext flags：必须同时设置 flag 与字段值，VP 会忽略未设 flag 的字段 */
video_params.rc_ext.flags |= VPAP_ENC_RC_EXT_HRD;
video_params.rc_ext.hrd = 1;

/* coding flags：相同模式 */
video_params.coding.flags |= VPAP_ENC_CODING_FULL_RANGE;
video_params.coding.vuiVideoFullRange = 1;

mm_module_ctrl(video_ctx, CMD_VIDEO_SET_PARAMS, (int)&video_params);
mm_module_ctrl(video_ctx, CMD_VIDEO_APPLY, 0);

参数	`video_params_t` 字段 / helper	说明
串流 channel	`stream_id`	V1–V5 channel，决定 ISP 输出端口与 encoder instance。
输出格式 / codec	`format`	`VIDEO_H264` / `VIDEO_HEVC` / `VIDEO_JPEG` / `VIDEO_NV12` / `VIDEO_RGB`。Raw 格式不经过 encoder。
分辨率	`width` / `height`	决定 ISP crop 与 encoder buffer geometry，修改需重新打开 stream。
JPEG 品质等级	`qlevel`	JPEG 编码品质（0–9），对 H.264/H.265 无效。
Profile / Level	`video_params_set_profile_level()`	H.264/H.265 profile 与 level，影响 SPS signaling 与 decoder 兼容性。
Tier	`video_params_set_tier()`	H.265 Main / High tier，影响 level 定义中的最大 bitrate 上限。
HRD conformance	rc_ext.hrd``（flag：``VPAP_ENC_RC_EXT_HRD）	启用 HRD bitstream timing model，与 `vbr=1` 互斥。
CPB buffer / max rate	`rc_ext.hrdCpbSize` / cpbMaxRate``（flag：``VPAP_ENC_RC_EXT_CPB）	CPB 缓冲大小（bits）与最大 CPB bitrate，`0` 使用 level 默认值。
Filler data	rc_ext.fillerData``（flag：``VPAP_ENC_RC_EXT_FILLER_DATA）	插入 filler NAL unit 补足 target bitrate，需同时启用 `hrd` 与 `pictureRc`。
VUI full range	coding.vuiVideoFullRange``（flag：``VPAP_ENC_CODING_FULL_RANGE）	VUI 中的 full-range / limited-range 信号，影响 decoder 对亮度/色度的解读方式。
HEVC SAO	coding.enableSao``（flag：``VPAP_ENC_CODING_SAO）	启用 HEVC Sample Adaptive Offset filter，需 HW SAO 支持。
H.264 CABAC	`video_params_set_cabac()`	启用 CABAC 熵编码，H.264 Baseline profile 不支持。
采样宽高比（SAR）	`video_params_set_sar()`	VUI 中的非方形像素 SAR，标准方形像素内容可省略。
Driver SEI	`video_params_set_driver_sei()`	启用 driver 生成的 picture timing 与 buffering period SEI messages。

Init + Runtime — 可在 CMD_VIDEO_APPLY 之前写入 video_params_t 作为初始值，也可在 stream 启动后通过 mm_module_ctrl() 使用下列 CMD_VIDEO_* 动态更新。

Runtime 更新时，标量参数直接将新值作为第三个参数传入；结构体参数则传入指针并 cast 为 int：

/* 标量：直接传值 */
mm_module_ctrl(video_ctx, CMD_VIDEO_BITRATE, 1000000);
mm_module_ctrl(video_ctx, CMD_VIDEO_GOP,     60);
mm_module_ctrl(video_ctx, CMD_VIDEO_FPS,     15);
mm_module_ctrl(video_ctx, CMD_VIDEO_RCMODE,  ENC_CBR);

/* 结构体：填写 local struct，将地址 cast 为 int 传入 */
video_qp_range_t qp = { .min_qp = 28, .max_qp = 45 };
mm_module_ctrl(video_ctx, CMD_VIDEO_SET_QP, (int)&qp);

video_moving_bitrate_t moving = { .tolerance = 200, .frames = 30 };
mm_module_ctrl(video_ctx, CMD_VIDEO_MOVING_BITRATE, (int)&moving);

video_deblock_t deblock = { .disable = 0, .tc_offset = 0, .beta_offset = 0 };
mm_module_ctrl(video_ctx, CMD_VIDEO_DEBLOCK, (int)&deblock);

Init 字段	Runtime CMD	API 函数	说明
`fps`	`CMD_VIDEO_FPS`	`video_set_fps()`	输出 frame rate。
`gop`	`CMD_VIDEO_GOP`	`video_set_gop()`	I-frame 间隔（单位：frame）。
`bps`	`CMD_VIDEO_BITRATE`	`video_set_bitrate()`	目标 bitrate（bps）。
`rc_mode`	`CMD_VIDEO_RCMODE`	`video_set_rcmode()`	Rate control mode（CVBR / CBR / VBR / ABR / CRF / CQP）。
`min_qp`	`CMD_VIDEO_MINQP`	`video_set_minqp()`	全局 QP 下限。
`max_qp`	`CMD_VIDEO_MAXQP`	`video_set_maxqp()`	全局 QP 上限。
`min_qp` + `max_qp`	`CMD_VIDEO_SET_QP`	`video_set_qp()`	一次同时设置全局 min/max QP。
`ainr_en`	`CMD_VIDEO_AINR`	`video_ainr_enable()`	AI Noise Reduction，在 V1 上配置，全局作用于所有 channel。
`rc_ext.qpHdr`	`CMD_VIDEO_QP_HDR`	`video_set_qp_hdr()`	初始 picture QP（`-1` 由 RC 自动选择）。
`rc_ext.minIQp` / `maxIQp`	`CMD_VIDEO_SET_I_QP`	`video_set_i_qp()`	I-frame QP 范围，覆盖全局 min/max QP 对 intra frame 的限制。
`rc_ext.intraQpDelta`	`CMD_VIDEO_INTRA_QP_DELTA`	`video_set_intra_qp_delta()`	Intra frame 相对 inter frame 的 QP 偏移量（−51 至 +51）。
`rc_ext.fixedIntraQp`	`CMD_VIDEO_FIXED_INTRA_QP`	`video_set_fixed_intra_qp()`	将 intra QP 固定为常数，`0` 表示不固定。
`rc_ext.pictureRc`	`CMD_VIDEO_PIC_RC`	`video_set_pic_rc()`	启用 picture-level rate control。
`rc_ext.ctbRc`	`CMD_VIDEO_CTB_RC`	`video_set_ctb_rc()`	CTB-level RC 模式（0=关 / 1=主观 / 2=精确 / 3=混合）。
`rc_ext.blockRCSize`	`CMD_VIDEO_BLOCK_RC_SIZE`	`video_set_block_rc_size()`	CTB RC 粒度（0=64×64 / 1=32×32 / 2=16×16）。
`rc_ext.pictureSkip`	`CMD_VIDEO_PICTURE_SKIP`	`video_set_picture_skip()`	允许 RC 通过跳帧维持 bitrate 目标。
`rc_ext.bitrateWindow`	`CMD_VIDEO_BITRATE_WINDOW`	`video_set_bitrate_window()`	RC 平均窗口（1–300 frames）。
`rc_ext.tolMovingBitRate` / `monitorFrames`	`CMD_VIDEO_MOVING_BITRATE`	`video_set_moving_bitrate()`	Moving bitrate 容忍度（0–2000 %）与监控窗口（10–120 frames）。
`rc_ext.crf`	`CMD_VIDEO_CRF`	`video_set_crf()`	Constant Rate Factor（`-1` 禁用 CRF）。
`rc_ext.vbr`	`CMD_VIDEO_VBR`	`video_set_vbr()`	VBR 质量控制模式，与 `hrd=1` 互斥。
`coding.sliceSize`	`CMD_VIDEO_SLICE_SIZE`	`video_set_slice_size()`	每个 slice 的 CTB 行数，`0` 表示不分 slice。
`coding.seiUserData`	`CMD_VIDEO_SEI_USER_DATA`	`video_set_sei_user_data()`	在每个编码帧前插入 user_data_unregistered SEI。
`coding.disableDeblockingFilter` + offsets	`CMD_VIDEO_DEBLOCK`	`video_set_deblock()`	Deblocking filter 开关及 tc/beta 偏移量（−6 至 +6）。

仅 Runtime — 只能在 CMD_VIDEO_APPLY 之后使用，在 open command 中没有对应的 init-time 设置。

CMD	API 函数	说明
`CMD_VIDEO_FORCE_IFRAME`	`video_force_iframe()`	强制下一个编码帧为 I-frame。
`CMD_VIDEO_CIR`	`video_set_cir()`	Cyclic Intra Refresh：持续刷新一个循环滚动的 CTB 带，不产生完整 I-frame。
`CMD_VIDEO_ROI`	`video_set_roi()`	Region of Interest：对最多 `VPAP_ENC_MAX_ROI` 个区域单独设置 QP delta。
`CMD_VIDEO_SET_OSD_BITMAP`	`video_set_osd_bitmap()`	配置 OSD overlay（位置、尺寸、alpha、YUV buffer 指针）。
`CMD_VIDEO_DISABLE_OSD`	`video_disable_osd()`	按硬件 index 关闭指定 OSD overlay。
`CMD_VIDEO_STREAM_STOP`	`video_close()`	停止并关闭 encoder stream。
`CMD_VIDEO_SET_RC_EXT` / `CMD_VIDEO_GET_RC_EXT`	`video_set_rc_ext()` / `video_get_rc_ext()`	批量更新或读取 rate-control 扩展字段，通过 `vpap_shared_enc_rc_ext_t.flags` 指定哪些字段生效。
`CMD_VIDEO_SET_CODING` / `CMD_VIDEO_GET_CODING`	`video_set_coding()` / `video_get_coding()`	批量更新或读取 coding-control 字段，通过 `vpap_shared_enc_coding_t.flags` 指定哪些字段生效。

本节术语说明

RC：Rate control，用于控制 encoder bitrate 与画质的机制。
QP：Quantisation parameter。QP 越低，通常画质越高，frame size 也越大。
GOP：Group of pictures。本文主要指 I-frame 间隔。
SPS / PPS / VUI：Decoder 用于解析 H.264/H.265 stream 的 bitstream header/signaling。
HRD / CPB：Decoder buffering 与 bitstream timing model。
CIR / ROI：Coding-control 功能；当 SDK 提供对应 runtime helper 时，可通过 encoder coding-control path 更新。

关于媒体示例的使用方式，请参考媒体示例。