sazonovanton/ffmpeg-opencv repository overview

⁠Hardware-Accelerated FFmpeg & OpenCV for Rockchip SoCs

This Docker image provides a fully configured environment for hardware-accelerated video processing and computer vision on Rockchip platforms (such as the RK3588, RK3568, Orange Pi 5, Radxa Rock 5, etc.).

It includes a custom-compiled FFmpeg with MPP (Media Process Platform) and RGA (Raster Graphic Acceleration) support, alongside OpenCV 4.9.0 with Python 3.11 bindings, heavily optimized for Rockchip's VPU and GPU.

⁠🌟 Features

• Base OS: Ubuntu 22.04
• Python: 3.11
• FFmpeg: Built from nyanmisaka/ffmpeg-rockchip⁠ fork.
  • MPP (rkmpp): Hardware decoding and encoding for H.264, HEVC (H.265), VP9, and more.
  • RGA (rkrga): 2D hardware acceleration for zero-copy scaling, cropping, and pixel format conversion (e.g., NV12 to RGB).
• OpenCV: Version 4.9.0 compiled with:
  • FFMPEG backend (leveraging the hardware-accelerated FFmpeg).
  • OpenCL backend (utilizing the Mali GPU).

⁠🚀 How to Run

To utilize the hardware acceleration blocks (VPU, GPU, RGA, and DMA heaps), the container requires extensive device access. It is highly recommended to run the container with --privileged and map the /dev directory.

Additionally, mapping the device tree prevents the mpp_soc: open /proc/device-tree/compatible error warning.

⁠Basic Interactive Shell

docker run -it --rm \
  --privileged \
  -v /dev:/dev \
  -v /sys/firmware/devicetree/base:/proc/device-tree:ro \
  -v "$(pwd):/workspace" \
  sazonovanton/ffmpeg-opencv:rockchip-python3.11 bash

⁠🛠️ Usage Examples

All examples assume you have a video file named INPUT.MP4 in your current host directory.

⁠1. Hardware Transcoding (H.264 to HEVC)

Decode a heavy 4K H.264 video and encode it to HEVC (H.265) at 15Mbps using the hardware VPU (vepu511a on RK3588):

docker run -it --rm --privileged -v /dev:/dev -v /sys/firmware/devicetree/base:/proc/device-tree:ro -v "$(pwd):/workspace" sazonovanton/ffmpeg-opencv:rockchip-python3.11 \
  ffmpeg -hwaccel rkmpp -i INPUT.MP4 \
  -c:v hevc_rkmpp -b:v 15M \
  -c:a copy -y OUTPUT_HEVC.MP4

⁠2. Hardware Scaling pipeline (4K to 1080p)

Full hardware pipeline: Decode (MPP) ➡️ Scale & Convert (RGA) ➡️ Encode (MPP). The -hwaccel_output_format drm_prime flag ensures zero-copy memory transfers between the decoder and the RGA scaler using DRM PRIME buffers.

docker run -it --rm --privileged -v /dev:/dev -v /sys/firmware/devicetree/base:/proc/device-tree:ro -v "$(pwd):/workspace" sazonovanton/ffmpeg-opencv:rockchip-python3.11 \
  ffmpeg -hwaccel rkmpp -hwaccel_output_format drm_prime -i INPUT.MP4 \
  -vf "scale_rkrga=w=1920:h=1080:format=nv12" \
  -c:v h264_rkmpp -b:v 8M \
  -c:a copy -y OUTPUT_1080P.MP4

⁠3. OpenCV Python (Quick frame reading test)

Verify that OpenCV can rapidly decode frames using the FFmpeg backend:

docker run -it --rm --privileged -v /dev:/dev -v /sys/firmware/devicetree/base:/proc/device-tree:ro -v "$(pwd):/workspace" sazonovanton/ffmpeg-opencv:rockchip-python3.11 \
  python3 -c "
import cv2
import time
cap = cv2.VideoCapture('INPUT.MP4', cv2.CAP_FFMPEG)
start = time.time(); count = 0
while count < 300:
    ret, frame = cap.read()
    if not ret: break
    count += 1
elapsed = time.time() - start
print(f'Read {count} frames in {elapsed:.2f} sec (FPS: {count/elapsed:.2f})')
cap.release()
"

⁠4. Hardware Decoding Speed Test

Quickly test the maximum hardware decoding speed (e.g., H.264/HEVC) without writing any output to disk. Keep an eye on the fps and speed values in the console!

docker run -it --rm --privileged -v /dev:/dev -v /sys/firmware/devicetree/base:/proc/device-tree:ro -v "$(pwd):/workspace" sazonovanton/ffmpeg-opencv:rockchip-python3.11 \
  ffmpeg -hwaccel rkmpp -i INPUT.MP4 -f null -

⁠5. Hardware JPEG Extraction (1 Frame Per Second)

Extract frames from a video stream using the hardware JPEG encoder (mjpeg_rkmpp). Extremely useful for AI object detection pipelines.

docker run -it --rm --privileged -v /dev:/dev -v /sys/firmware/devicetree/base:/proc/device-tree:ro -v "$(pwd):/workspace" sazonovanton/ffmpeg-opencv:rockchip-python3.11 \
  ffmpeg -hwaccel rkmpp -i INPUT.MP4 -vf "fps=1" -c:v mjpeg_rkmpp -q:v 2 -y frame_%03d.jpg