2026–07–11: libva-v4l2_request – VA-API driver for V4L2 stateless decoders

I got a bit tired waiting for ffmpeg to merge v4l2 requests support, having to recompile mpv and ffmpeg, and having my stale builds constantly breaking my Arch Linux ARM upgrades, and just decided to write a proper VA-API driver for stateless video decoders using v4l2 media requests API, primarily for my Pinebook Pro which I use from time to time also as a portable media player, since it has a fairly good LCD.

In practical terms, this means I can now install a single driver package, just a single .so file basically, on a supported ARM board/device and get hardware video decoding acceleration in mpv and Firefox without patching either of them, let alone other dependencies that I had to patch before. :)

I developed it primarily on the Pinebook Pro (RK3399), with some testing on the Orange Pi 5+ (RK3588). The driver is written generically and should work on any SoC with an upstream Linux stateless video decode driver, though it may need a bit of tuning for optimal performance on other SoCs (I believe some Allwinner platforms use decoders with tilling output format, but I did not yet investigate the consequences of that for feasability of full 0-copy decode->display pipeline).

In any case, on Pinebook Pro, this VA-API driver achieves 5% CPU utilization regardless of codec, even for 10bit HEVC decodes, where this required also utilizing RK3399 RGA2 to transcode the decoded frames to 8bit format display pipeline can process. But thanks to RGA2, the whole pipeline is still 0-copy, from the PoV of the CPU, which was the goal.

What it does

The supported codec list depends on what the kernel uAPI headers expose, but in theory the driver support covers: MPEG-2, H.264, HEVC, VP8, VP9 and AV1. On RK3399, support is very good for all codecs the hardware can handle also in practice. :) On RK3588, HEVC is currently not possible to support over VA-API due to an API mismatch that I don't see a reasonable way around.

The most useful part is that once the driver is installed, applications just work:

export LIBVA_DRIVER_NAME=v4l2_request
mpv --hwdec=vaapi video.mp4

And for Firefox:

export LIBVA_DRIVER_NAME=v4l2_request
export MOZ_DISABLE_RDD_SANDBOX=1
firefox

The decoded frames are exported as dma-bufs, so --vo=dmabuf-wayland gives a fully zero-copy path on Wayland, and --vo=gpu imports them into the GPU render pipeline for both X11 and Wayland.

Pinebook Pro in action

Here's the Pinebook Pro running a test HEVC 1080p video with the driver:

And Firefox:

10-bit content and the RGA converter

Rockchip decoders output 10-bit content as packed NV15, which nothing in the normal display stack can import directly. The driver detects a V4L2 mem2mem converter (the Rockchip RGA), chains it behind the decoder, and converts NV15 to NV12 in hardware. Decode, 10-to-8 conversion and display all stay in dma-bufs and never touch the CPU.

This does need a small kernel patch for rockchip-rga to support NV15 sources, which is included in the repository under patches/. Sorry for that, but at least this should be mainlineable fairly easily, since it's just a small additive change to the driver.

Video processing: rotation and scaling

The same converter also implements the VA-API video processing entrypoint, so you can offload rotation, mirroring, cropping and scaling to the RGA. This is particularly handy on portrait devices like the Pinephone Pro, where landscape video can be rotated with:

mpv --hwdec=vaapi --vf=lavfi=[transpose_vaapi=dir=cclock] video.mp4

You can also scale at the same time:

mpv --hwdec=vaapi --vf=lavfi=[transpose_vaapi=dir=clock,scale_vaapi=720:1280] video.mp4

Pinephone Pro running mpv

The Pinephone Pro setup needs a bit of care because the panel is portrait 720×1440 and the VOP cannot rotate planes. A convenient way to watch landscape video is a Weston kiosk session that rotates the whole output, with mpv handing frames over via --vo=dmabuf-wayland. The README has the full step-by-step setup for Arch Linux ARM.

Here's the Pinephone Pro running mpv with hardware decoding of video of Pinebook Pro running mpv with HW decoding acceleration:

Repo

The driver is licensed under GPL-3.0+

The code is at: https://xff.cz/git/libva-v4l2_request/