MPP Multimedia Framework

This chapter covers the architecture of the Rockchip MPP (Media Process Platform) framework, API usage, and how it integrates with FFmpeg.

Overall block diagram

┌─────────────────────────────────────────┐
│           User application              │
├─────────────────────────────────────────┤
│              MPP API (C interface)      │
├──────────┬──────────┬───────────────────┤
│  VPU Enc │  VPU Dec │    RGA / ISP      │
├──────────┴──────────┴───────────────────┤
│        Hardware drivers (kernel)        │
├─────────────────────────────────────────┤
│          Hardware IP (VPU/RGA)          │
└─────────────────────────────────────────┘

About the RK182X codec capabilities: the RK182X is a coprocessor with no built-in VPU. The 8K / 4K codec capabilities listed in this chapter are the reference specifications of the Host SoC's (e.g. RK3588) VPU. The actual codec capability of MPP on the RK182X is determined by the Host SoC's VPU hardware; refer to the Host SoC TRM.

1. Supported Codec Formats (Host SoC reference)

Direction	Format	Max resolution
Encode	H.264	8K@30fps
Encode	H.265	8K@30fps
Decode	H.264	8K@30fps
Decode	H.265	8K@60fps
Decode	VP9	8K@60fps
Decode	AV1	4K@60fps

Actual capability is determined by the VPU hardware of the attached Host SoC.

2. Environment Verification

MPP headers:

ls /usr/include/rockchip/

Output:

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.h

MPP library files:

ls /usr/lib/aarch64-linux-gnu/librockchip_mpp.so*

Output:

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.0

ffmpeg installation (not pre-installed on the board):

sudo apt install -y ffmpeg
which ffmpeg && ffmpeg -version | head -1

Output (measured after installation):

/usr/bin/ffmpeg
ffmpeg version 5.1.9-0+deb12u1 Copyright (c) 2000-2026 the FFmpeg developers

ffmpeg is not pre-installed on the board; install it with sudo apt install -y ffmpeg. What gets installed is the Debian 12 community build 5.1.9-0+deb12u1.

RKMPP hardware encoders:

ffmpeg -encoders 2>/dev/null | grep -i rkmpp

Output (measured, empty):

(no output — the Debian 12 apt ffmpeg does not include rkmpp codecs)

Measured: the configuration in ffmpeg -version does not contain --enable-rkmpp — the Debian 12 apt build is the upstream community version, and the h264_rkmpp / hevc_rkmpp codecs do not exist. To use RKMPP hardware codecs you must compile Rockchip's customized FFmpeg yourself (source / buildroot provided by airockchip), or use the MPP C API / mpp_enc / mpp_dec tools directly.

Video devices:

ls /dev/video*

Output:

/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 are 20 regular nodes; video-dec0 / video-enc0 are dedicated MPP hardware codec nodes, and video-camera0 is the camera node.

3. MPP Initialization Flow

The following example code compiles and runs on the board against librockchip-mpp (headers under /usr/include/rockchip/; measured runtime version 520ab553, 2025-12-16, author 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>   /* control commands such as MPP_ENC_SET_CFG */
#include <rockchip/rk_venc_cfg.h>  /* mpp_enc_cfg_* encoding config API */

int main(void)
{
    MPP_RET  ret;
    MppCtx   ctx  = NULL;
    MppApi  *mpi  = NULL;

    // Create the MPP context
    ret = mpp_create(&ctx, &mpi);
    if (ret) return ret;

    // Initialize: specify the direction and coding type
    ret = mpp_init(ctx, MPP_CTX_ENC, MPP_VIDEO_CodingAVC);
    if (ret) return ret;

    // Configure encoding parameters
    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);

    // The config must be pushed down through mpi->control
    ret = mpi->control(ctx, MPP_ENC_SET_CFG, cfg);
    if (ret) return ret;

    // Encoding loop
    MppFrame  frame  = NULL;
    MppPacket packet = NULL;
    mpp_frame_init(&frame);
    // Fill in frame data (width/height/hor_stride/buf/fd/pts)
    ret = mpi->encode(ctx, frame, &packet);
    // Process the packet (length/pts/data)
    mpp_packet_deinit(&packet);
    mpp_frame_deinit(&frame);

    // Destroy
    mpp_destroy(ctx);
    mpp_enc_cfg_deinit(cfg);
    return MPP_OK;
}

3.1 Key API Points

API	Description
`MppCtx ctx` + `MppApi *mpi`	`mpp_create` must return the `MppApi**`; subsequent `control` / `encode` calls go through `mpi->`
`mpp_init(ctx, MPP_CTX_ENC, MppCodingType)`	The third parameter type is `MppCodingType` (e.g. `MPP_VIDEO_CodingAVC`), not `MppEncCodecId`
`mpi->control(ctx, MPP_ENC_SET_CFG, cfg)`	There is no top-level `mpp_enc_set_cfg()`; the config must go through `mpi->control`
`mpi->encode(ctx, frame, &packet)`	There is no top-level `mpp_encode()`; the encode function is a member of `MppApi`
`#include <rockchip/mpp_packet.h>`	Must be included; required for packet handling

Measured output of the minimal verification program:

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, exit

The actual MPP version is whatever the runtime mpp_info log reports (520ab553, 2025-12-16 on this machine); the mpi->version field measured as 0 (an unused field, not a version number).

4. MPP and FFmpeg Integration

Rockchip provides a customized FFmpeg that calls MPP hardware acceleration via the h264_rkmpp / hevc_rkmpp codecs.

Measured warning: the following commands do not work on the stock Debian 12 ffmpeg (5.1.9, without --enable-rkmpp) — the h264_rkmpp codec does not exist. You must first compile and install Rockchip's customized FFmpeg (github.com/airockchip, buildroot available), or use the MPP C API / mpp_enc / mpp_dec tools instead.

# Hardware encoding (requires the customized FFmpeg)
ffmpeg -f v4l2 -i /dev/video0 -c:v h264_rkmpp -b:v 4M output.mp4

# Hardware decoding (requires the customized FFmpeg)
ffmpeg -c:v h264_rkmpp -i input.mp4 -f null -

# List available hardware encoders
ffmpeg -encoders | grep rkmpp

5. Key Environment Variables

Extracting environment variable names from the library file:

strings /usr/lib/aarch64-linux-gnu/librockchip_mpp.so.1 2>/dev/null | grep -E "^mpp_(debug|buffer|rt|enc|dec)_debug" | head -10

Output:

mpp_enc_debug
mpp_dec_debug
mpp_buffer_debug
mpp_enc_debug
mpp_dec_debug
mpp_buffer_debug
mpp_rt_debug

Variable	Purpose
`mpp_debug`	Debug log level (`info` / `debug` / `warn` / `error` / `verbose`); runtime override for `mpp_set_log_level()`
`mpp_buffer_debug`	Per-submodule buffer debug logging
`mpp_rt_debug`	Per-submodule runtime debug logging
`mpp_enc_debug`	Per-submodule encoder debug logging
`mpp_dec_debug`	Per-submodule decoder debug logging

6. FAQ

Symptom	Cause	Resolution
`h264_rkmpp` codec does not exist	Debian 12 apt ffmpeg has no rkmpp support	Compile Rockchip's customized ffmpeg / use the MPP C API
ffmpeg not installed	Not pre-installed on the board	`sudo apt install -y ffmpeg`
`mpp_init` returns `MPP_ERR_INIT`	Wrong config / device busy	`lsof /dev/mpp_service` + restart the service
`mpi->version=0`	Field unused	Check the `mpp_info` log for the real version
`MPP_ENC_SET_CFG` returns -1	Wrong order	`mpp_init` must come before `MPP_ENC_SET_CFG`
`mpp_enc_set_cfg` not found	No such top-level function	Use `mpi->control(ctx, MPP_ENC_SET_CFG, cfg)`

7. Next Steps

RGA 2D Acceleration — hardware-accelerated image preprocessing
VPU Codecs — hardware video codec details
NPU Overview — combining AI inference with multimedia