RK3588 V4L2-request FFmpeg and mpv build guide for Radxa ROCK 5T

rk3588-v4l2request-mpv-build.md

RK3588 V4L2-request FFmpeg + mpv build guide

This builds the tested RK3588 V4L2-request stack on a Radxa ROCK 5T using:

• ryanfitz/FFmpeg branch rk3588-hevc-rps-controls
• ryanfitz/mpv-rockchip branch rk3588-nv15-gpu-next
• libplacebo v7 pinned to the revision used during testing
• installation prefix /opt/v4l2player

The FFmpeg branch adds the extended HEVC SPS short- and long-term RPS controls required by the RK3588 VDPU381/383 stateless decoder. The mpv branch adds V4L2-request DRM PRIME integration and GPU unpacking of the RK3588 NV15 10-bit format.

1. Kernel and device prerequisites

Use a recent RK3588-enabled kernel containing the stateless rkvdec2 VDPU381/383 HEVC driver and the extended HEVC SPS RPS controls. The validated machine used Linux 7.1.0-edge-rockchip64.

Confirm that the media and video devices exist:

uname -a
ls -l /dev/media* /dev/video* /dev/dri/*
v4l2-ctl --list-devices

Your login user must be able to access the relevant video, media, and render devices. On Debian/Ubuntu, add the user to the usual device groups if necessary, then log out and back in:

sudo usermod -aG video,render "$USER"

2. Install build dependencies

These commands target a current Debian/Ubuntu or Armbian-style installation:

sudo apt update

sudo apt install -y \
  build-essential git pkg-config meson ninja-build python3 python3-jinja2 \
  linux-libc-dev v4l-utils media-types \
  libdrm-dev libudev-dev libdisplay-info-dev \
  libegl1-mesa-dev libgles2-mesa-dev libgbm-dev libvulkan-dev \
  libwayland-dev wayland-protocols libxkbcommon-dev \
  libass-dev libasound2-dev libpulse-dev libpipewire-0.3-dev \
  libuchardet-dev libarchive-dev libjpeg-dev liblcms2-dev \
  liblua5.2-dev libcurl4-openssl-dev \
  zlib1g-dev libbz2-dev liblzma-dev \
  glslang-dev glslang-tools

Create the private installation prefix:

sudo mkdir -p /opt/v4l2player
sudo chown -R "$USER":"$USER" /opt/v4l2player
mkdir -p "$HOME/src"

3. Build and install the patched FFmpeg

cd "$HOME/src"

git clone \
  --branch rk3588-hevc-rps-controls \
  --single-branch \
  https://github.com/ryanfitz/FFmpeg.git \
  ffmpeg-v4l2request

cd ffmpeg-v4l2request

./configure \
  --prefix=/opt/v4l2player \
  --bindir=/opt/v4l2player/bin \
  --libdir=/opt/v4l2player/lib \
  --shlibdir=/opt/v4l2player/lib \
  --incdir=/opt/v4l2player/include \
  --pkgconfigdir=/opt/v4l2player/lib/pkgconfig \
  --enable-shared \
  --disable-static \
  --enable-pic \
  --enable-libdrm \
  --disable-doc \
  --disable-debug

make -j"$(nproc)"
make checkheaders
make install

Verify that this is the custom build and that v4l2request is available:

export LD_LIBRARY_PATH=/opt/v4l2player/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}

/opt/v4l2player/bin/ffmpeg -version
/opt/v4l2player/bin/ffmpeg -hide_banner -hwaccels

The hardware-acceleration list should contain v4l2request.

4. Check out and build mpv

cd "$HOME/src"

git clone \
  --branch rk3588-nv15-gpu-next \
  --single-branch \
  https://github.com/ryanfitz/mpv-rockchip.git \
  mpv-v4l2request

cd mpv-v4l2request

Use the tested libplacebo v7 revision as an mpv subproject:

git clone https://code.videolan.org/videolan/libplacebo.git subprojects/libplacebo
git -C subprojects/libplacebo checkout 22ee762e8e0890fc54068beb670310f0edce7263

Configure and build mpv against /opt/v4l2player:

export PKG_CONFIG_PATH=/opt/v4l2player/lib/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH}
export LD_LIBRARY_PATH=/opt/v4l2player/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}

meson setup build \
  --prefix=/opt/v4l2player \
  --libdir=lib \
  --buildtype=release \
  -Dv4l2request=enabled \
  -Dwayland=enabled \
  -Ddmabuf-wayland=enabled \
  -Ddrm=enabled \
  -Dmanpage-build=disabled

ninja -C build

Verify the resulting build:

LD_LIBRARY_PATH=/opt/v4l2player/lib ./build/mpv --version
LD_LIBRARY_PATH=/opt/v4l2player/lib ./build/mpv --no-config --hwdec=help

The hardware-decoder list should contain v4l2request.

To install mpv into the same prefix as FFmpeg, optionally run:

meson install -C build

5. List DRM output modes

Direct DRM playback must be run from a local virtual terminal with access to the DRM device. List the connector modes first:

cd "$HOME/src/mpv-v4l2request"

LD_LIBRARY_PATH=/opt/v4l2player/lib \
./build/mpv \
  --no-config \
  --vo=gpu-next \
  --gpu-context=drm \
  --drm-device=/dev/dri/card0 \
  --drm-mode=help

On the validated display, mode 5 was 1920x1080 at 119.88 Hz, which is an exact 5:5 cadence for 23.976 fps material. Mode numbers are display-specific, so always check the list on a fresh machine.

6. Run mpv with RK3588 hardware decoding

Replace 5 with the appropriate mode number for the connected display and replace the media path:

cd "$HOME/src/mpv-v4l2request"

export LD_LIBRARY_PATH=/opt/v4l2player/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}

./build/mpv \
  --no-config \
  --vo=gpu-next \
  --gpu-api=opengl \
  --gpu-context=drm \
  --drm-device=/dev/dri/card0 \
  --drm-mode=5 \
  --hwdec=v4l2request \
  --hwdec-codecs=all \
  --hwdec-software-fallback=no \
  '/path/to/video.mkv'

For a silent video-only diagnostic run, add:

--audio=no

7. Optional HDR tone-mapping baseline

The default gpu-next tone mapper is already high quality. A useful advanced baseline is:

--tone-mapping=spline
--gamut-mapping-mode=perceptual
--hdr-compute-peak=yes
--allow-delayed-peak-detect=yes
--hdr-contrast-recovery=0.25

Only set --target-peak=<nits> when the display's usable peak brightness is known. Otherwise leave it on auto.

8. Updating later

Both repositories intentionally use feature branches. Update without switching away from them:

cd "$HOME/src/ffmpeg-v4l2request"
git pull --ff-only
make -j"$(nproc)"
make install

cd "$HOME/src/mpv-v4l2request"
git pull --ff-only
git -C subprojects/libplacebo checkout 22ee762e8e0890fc54068beb670310f0edce7263

export PKG_CONFIG_PATH=/opt/v4l2player/lib/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH}
export LD_LIBRARY_PATH=/opt/v4l2player/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}

meson setup --reconfigure build
ninja -C build

If FFmpeg's ABI changes, reconfiguring and rebuilding mpv is required.