MPP 多媒体处理框架
本章讲 Rockchip MPP（Media Process Platform）框架的架构、API 用法、与 FFmpeg 集成方式。
整体框图
┌─────────────────────────────────────────┐
│ 用户应用程序 │
├─────────────────────────────────────────┤
│ MPP API (C接口) │
├──────────┬──────────┬───────────────────┤
│ VPU Enc │ VPU Dec │ RGA / ISP │
├──────────┴──────────┴───────────────────┤
│ 硬件驱动 (kernel) │
├─────────────────────────────────────────┤
│ 硬件 IP (VPU/RGA) │
└─────────────────────────────────────────┘关于 RK182X 的编解码能力：RK182X 是协处理器，不内置 VPU。本章列出的 8K / 4K 编解码能力是 Host SoC（如 RK3588）VPU 的参考规格。RK182X 上的 MPP 实际编解码能力由 Host SoC 的 VPU 硬件决定，请以 Host SoC TRM 为准。
1. 支持的编解码格式（Host SoC 参考）
| 方向 | 格式 | 最大分辨率 |
|---|---|---|
| 编码 | H.264 | 8K@30fps |
| 编码 | H.265 | 8K@30fps |
| 解码 | H.264 | 8K@30fps |
| 解码 | H.265 | 8K@60fps |
| 解码 | VP9 | 8K@60fps |
| 解码 | AV1 | 4K@60fps |
实际能力由所挂 Host SoC 的 VPU 硬件决定。
2. 环境验证
MPP 头文件：
ls /usr/include/rockchip/输出：
mpp_buffer.h
mpp_compat.h
mpp_err.h
mpp_frame.h
mpp_log_def.h
mpp_log.h
mpp_meta.h
mpp_packet.h
mpp_rc_api.h
mpp_rc_defs.h
mpp_sys_cfg.h
mpp_sys_cfg_st.h
mpp_task.h
rk_hdr_meta_com.h
rk_mpi_cmd.h
rk_mpp_cfg.h
rk_mpi.h
rk_type.h
rk_vdec_cfg.h
rk_vdec_cmd.h
rk_vdec_kcfg.h
rk_venc_cfg.h
rk_venc_cmd.h
rk_venc_kcfg.h
rk_venc_rc.h
rk_venc_ref.h
vpu_api.h
vpu.hMPP 库文件：
ls /usr/lib/aarch64-linux-gnu/librockchip_mpp.so*输出：
lrwxrwxrwx 1 root root 20 2021年 5月20日 librockchip_mpp.so -> librockchip_mpp.so.1
-rw-r--r-- 1 root root 2646312 2021年 5月20日 librockchip_mpp.so.0
lrwxrwxrwx 1 root root 20 2021年 5月20日 librockchip_mpp.so.1 -> librockchip_mpp.so.0ffmpeg 安装（板端未预装）：
sudo apt install -y ffmpeg
which ffmpeg && ffmpeg -version | head -1输出（装好后实测）：
/usr/bin/ffmpeg
ffmpeg version 5.1.9-0+deb12u1 Copyright (c) 2000-2026 the FFmpeg developers板端 ffmpeg 未预装，需
sudo apt install -y ffmpeg；装的是 Debian 12 社区版 5.1.9-0+deb12u1。
RKMPP 硬件编码器：
ffmpeg -encoders 2>/dev/null | grep -i rkmpp输出（实测为空）：
（无输出 —— Debian 12 apt 版 ffmpeg 不含 rkmpp 编解码器）实测
ffmpeg -version的 configuration 里没有--enable-rkmpp——Debian 12 apt 装的是上游社区版，h264_rkmpp/hevc_rkmpp编解码器不存在。要用 RKMPP 硬件编解码须自行编译 Rockchip 定制版 FFmpeg（airockchip 提供的源码 / buildroot），或直接用 MPP C API /mpp_enc/mpp_dec工具。
视频设备：
ls /dev/video*输出：
/dev/video0 /dev/video1 /dev/video10 /dev/video11
/dev/video12 /dev/video13 /dev/video14 /dev/video15
/dev/video16 /dev/video17 /dev/video18 /dev/video19
/dev/video2 /dev/video3 /dev/video4 /dev/video5
/dev/video6 /dev/video7 /dev/video8 /dev/video9
/dev/video-camera0
/dev/video-dec0
/dev/video-enc0
video0~video19共 20 个常规节点；video-dec0/video-enc0是 MPP 硬件编解码专用节点，video-camera0为摄像头节点。
3. MPP 初始化流程
以下示例代码在板端 librockchip-mpp（头文件在 /usr/include/rockchip/，实测运行版本 520ab553，2025-12-16，作者 Herman Chen）下编译、运行通过：
#include <stdio.h>
#include <rockchip/mpp_buffer.h>
#include <rockchip/mpp_frame.h>
#include <rockchip/mpp_packet.h>
#include <rockchip/rk_mpi.h>
#include <rockchip/rk_mpi_cmd.h> /* MPP_ENC_SET_CFG 等控制命令 */
#include <rockchip/rk_venc_cfg.h> /* mpp_enc_cfg_* 编码配置 API */
int main(void)
{
MPP_RET ret;
MppCtx ctx = NULL;
MppApi *mpi = NULL;
// 创建 MPP 上下文
ret = mpp_create(&ctx, &mpi);
if (ret) return ret;
// 初始化：指定编码方向与编码类型
ret = mpp_init(ctx, MPP_CTX_ENC, MPP_VIDEO_CodingAVC);
if (ret) return ret;
// 配置编码参数
MppEncCfg cfg = NULL;
mpp_enc_cfg_init(&cfg);
mpp_enc_cfg_set_s32(cfg, "prep:width", 1920);
mpp_enc_cfg_set_s32(cfg, "prep:height", 1080);
mpp_enc_cfg_set_s32(cfg, "rc:bps_target", 4000000);
mpp_enc_cfg_set_s32(cfg, "rc:fps_in", 30);
// 配置必须通过 mpi->control 推下去
ret = mpi->control(ctx, MPP_ENC_SET_CFG, cfg);
if (ret) return ret;
// 编码循环
MppFrame frame = NULL;
MppPacket packet = NULL;
mpp_frame_init(&frame);
// 填充 frame 数据 (width/height/hor_stride/buf/fd/pts)
ret = mpi->encode(ctx, frame, &packet);
// 处理 packet (length/pts/data)
mpp_packet_deinit(&packet);
mpp_frame_deinit(&frame);
// 销毁
mpp_destroy(ctx);
mpp_enc_cfg_deinit(cfg);
return MPP_OK;
}3.1 关键 API 要点
| API | 说明 |
|---|---|
MppCtx ctx + MppApi *mpi | mpp_create 必须把 MppApi** 取出来，后续 control / encode 都通过 mpi-> 调用 |
mpp_init(ctx, MPP_CTX_ENC, MppCodingType) | 第三个参数类型是 MppCodingType（如 MPP_VIDEO_CodingAVC），不是 MppEncCodecId |
mpi->control(ctx, MPP_ENC_SET_CFG, cfg) | 不存在 mpp_enc_set_cfg() 顶层函数，配置必须走 mpi->control |
mpi->encode(ctx, frame, &packet) | 不存在顶层 mpp_encode()，编码函数是 MppApi 成员 |
#include <rockchip/mpp_packet.h> | 必须包含；处理 packet 必需 |
实测最小化验证程序运行输出：
mpp[6401]: mpp_info: mpp version: 520ab553 author: Herman Chen 2025-12-16 fix[sys_cfg]: Fix decoder sys_cfg crash
[OK] mpp_create, ctx=0x559dc44e80 mpi=0x7fb64b38b8
[OK] mpp_init(MPP_CTX_ENC, MPP_VIDEO_CodingAVC)
[MPP version] mpi->version=0x00000000 (major=0 minor=0)
[control probe] MPP_ENC_GET_HDR_SYNC ret=0
[OK] mpp_destroy, exitMPP 实际版本以运行时
mpp_info日志为准（本机 520ab553，2025-12-16）；mpi->version字段实测为 0（未使用的字段，不是版本号）。
4. MPP 与 FFmpeg 集成
Rockchip 提供定制版 FFmpeg，通过 h264_rkmpp / hevc_rkmpp 编解码器调用 MPP 硬件加速。
实测警告：以下命令在标准 Debian 12 的 ffmpeg（5.1.9，无
--enable-rkmpp）上跑不通——h264_rkmpp编解码器不存在。需先编译安装 Rockchip 定制版 FFmpeg（github.com/airockchip，可用其 buildroot），或改用 MPP C API /mpp_enc/mpp_dec工具。
# 硬件编码（需定制版 FFmpeg）
ffmpeg -f v4l2 -i /dev/video0 -c:v h264_rkmpp -b:v 4M output.mp4
# 硬件解码（需定制版 FFmpeg）
ffmpeg -c:v h264_rkmpp -i input.mp4 -f null -
# 查看可用硬件编码器
ffmpeg -encoders | grep rkmpp5. 关键环境变量
从库文件中提取环境变量名：
strings /usr/lib/aarch64-linux-gnu/librockchip_mpp.so.1 2>/dev/null | grep -E "^mpp_(debug|buffer|rt|enc|dec)_debug" | head -10输出：
mpp_enc_debug
mpp_dec_debug
mpp_buffer_debug
mpp_enc_debug
mpp_dec_debug
mpp_buffer_debug
mpp_rt_debug| 变量 | 作用 |
|---|---|
mpp_debug | 调试日志级别（info / debug / warn / error / verbose），用于 mpp_set_log_level() 的运行时覆盖 |
mpp_buffer_debug | 按子模块启用 buffer 调试日志 |
mpp_rt_debug | 按子模块启用 runtime 调试日志 |
mpp_enc_debug | 按子模块启用编码器调试日志 |
mpp_dec_debug | 按子模块启用解码器调试日志 |
6. 常见问题
| 现象 | 原因 | 处理 |
|---|---|---|
h264_rkmpp 编解码器不存在 | Debian 12 apt 版 ffmpeg 无 rkmpp 支持 | 编译 Rockchip 定制版 ffmpeg / 用 MPP C API |
| ffmpeg 未装 | 板端未预装 | sudo apt install -y ffmpeg |
mpp_init 报 MPP_ERR_INIT | 配置错 / 设备忙 | lsof /dev/mpp_service + 重启服务 |
mpi->version=0 | 字段未使用 | 看 mpp_info 日志获取真实版本 |
MPP_ENC_SET_CFG 报 -1 | 顺序错 | mpp_init 必须在 MPP_ENC_SET_CFG 之前 |
mpp_enc_set_cfg 找不到 | 不存在该顶层函数 | 改用 mpi->control(ctx, MPP_ENC_SET_CFG, cfg) |