VideoNode Documentation

Appearance

Installing VideoNode ​

VideoNode is distributed as a Debian package for Linux arm64. This page covers installing it from the APT repository on an RK3588-based board running a Debian-compatible OS with V4L2 capture support.

Prerequisites:

  • Linux, arm64 (aarch64). The packaged build targets Rockchip RK3588 boards (recommended: the FriendlyElec NanoPC-T6, 8GB / 64GB eMMC or higher). See supported hardware for the full matrix and the software-only paths.
  • Debian 13 (trixie) or newer. The native binaries link trixie-era shared libraries (libplacebo349, libabsl20240722, and the t64 builds of gRPC and protobuf), so apt refuses to install VideoNode on bookworm or older with a base-files (>= 13~) dependency error. Upgrade the board's OS to trixie first if it is still on bookworm.
  • A V4L2-capable capture device (e.g. /dev/video0): USB or MIPI-CSI cameras, HDMI capture cards. Verify with v4l2-ctl --list-devices.
  • curl, gpg, and apt available
  • A Linux account with sudo for the install steps below

Install required runtime dependencies ​

ffmpeg with h264_rkmpp ​

The daemon shells out to ffmpeg from PATH. On a Rockchip board you need a build with h264_rkmpp and hevc_rkmpp enabled; stock Debian's ffmpeg does not include them. Use the ffmpeg that ships with your board's vendor OS image if it advertises Rockchip support, or install a community build like nyanmisaka/ffmpeg-rockchip. Confirm with:

bash
ffmpeg -encoders 2>&1 | grep rkmpp

After install, run videonode validate-encoders to verify the probe finds the hardware encoder. See Encoders for the precedence rules and example output.

Rockchip userspace libraries (RGA + MPP) ​

The native binaries dynamically link librga and librockchip-mpp. VideoNode's CI builds against pinned releases from tsukumijima/mpp-rockchip and tsukumijima/librga-rockchip. Install matching .deb files from those release pages, or use the equivalents your vendor OS provides. The MPP kernel module must also be loaded (/proc/mpp_service/load must exist); vendor images for the NanoPC-T6 load it by default.

Enable device-tree overlays (GPU + HDMI input) ​

The composer GPU-composites onto a canvas using the Mali GPU, which is only usable when the kernel binds it through the panthor driver. panthor creates a DRM render node under /dev/dri/ (e.g. renderD130). If that node is missing, the composer cannot initialize and logs errors like:

egl_ctx: open(/dev/dri/renderD130): No such file or directory
pl_compose: both Vulkan and OpenGL backends failed
canvas_loop: pl_compose init 1920x1080 failed

On Armbian/RK3588 the GPU is enabled by a device-tree overlay. Capturing from the onboard HDMI-RX port needs a second overlay.

Edit /boot/armbianEnv.txt and add both overlays to the overlays= line:

ini
# /boot/armbianEnv.txt
overlay_prefix=rockchip-rk3588
overlays=panthor-gpu rk3588-hdmirx
  • panthor-gpu: binds the Mali GPU to the panthor driver (required for the composer). With overlay_prefix=rockchip-rk3588 it resolves to /boot/dtb/rockchip/overlay/rockchip-rk3588-panthor-gpu.dtbo.
  • rk3588-hdmirx: enables the HDMI-RX capture input (only needed if you capture from the onboard HDMI-in port).

The same overlays can be toggled from a menu with sudo armbian-config (System → Hardware). GPU compositing also benefits from a larger CMA pool; if the canvas fails to allocate, raise it on the kernel cmdline in the same file:

ini
extraargs=cma=1G

Reboot to apply, then confirm a render node is bound to panthor:

bash
sudo reboot
# after reboot:
for n in /sys/class/drm/renderD*; do
  echo "$(basename "$n") -> $(basename "$(readlink -f "$n/device/driver")")"
done

You should see a line ending in -> panthor alongside rockchip-drm and RKNPU. If no panthor node appears, re-check the overlays= line and that the board booted a trixie-based image.

Install from the APT repository ​

Follow these steps in order.

  1. To trust the repository's signing key, download and install it:

    bash
    curl -fsSL https://mazurov.dev/videonode/public.key \
  | gpg --dearmor \
  | sudo tee /usr/share/keyrings/videonode-archive-keyring.gpg > /dev/null

  2. To add the repository to your APT sources, write the sources entry:

    bash
    echo "deb [arch=arm64 signed-by=/usr/share/keyrings/videonode-archive-keyring.gpg] \
  https://mazurov.dev/videonode stable main" \
  | sudo tee /etc/apt/sources.list.d/videonode.list

  3. To fetch the updated package index, run:

    bash
    sudo apt update

  4. To install VideoNode, run:

    bash
    sudo apt install videonode

The post-install script creates a videonode system user, writes default configuration to /etc/videonode/config.toml, enables videonode.service, and starts it immediately.

The package installs the Go daemon (/usr/bin/videonode), the three native pipeline binaries (videonode-source, videonode-sink, videonode-composer), the videonode-session login helper with its PAM stack (/etc/pam.d/videonode), the videonode.service systemd unit, and the default /etc/videonode/config.toml. It does not bundle the Rockchip hardware stack (ffmpeg with h264_rkmpp, RGA, MPP); install that separately as described under Install required runtime dependencies. The service logs a warning when those libraries are missing.

Web UI authentication ​

VideoNode authenticates web UI logins against the Linux user database via PAM. Two things must be true for a user to log in:

  1. The user has a regular Linux account on the box.
  2. The user is a member of the videonode group.

If you ran apt install with sudo, the postinst script enrolls $SUDO_USER into the videonode group automatically. Log in to the UI with your usual username and password. Otherwise, add yourself manually:

bash
sudo adduser "$USER" videonode

You'll need to log out and back in (or run newgrp videonode) for the new group membership to take effect for new shells. The daemon itself never reads /etc/shadow: password checks run in videonode-session, a setuid-root helper installed with the package that performs the PAM conversation and returns a yes/no verdict.

To add another operator later, run the same adduser ... videonode command for their account.

Bypassing Linux auth (basic credentials) ​

If you'd rather skip the Linux account / group setup entirely (for example on a single-user box, or during initial bring-up), switch the daemon to basic auth. Edit /etc/videonode/config.toml:

toml
[auth]
type     = "basic"
username = "admin"
password = "change-me"

Then sudo systemctl restart videonode. Log in with the username and password from the file. Change the defaults before exposing the daemon to a network: basic auth ships passwords in cleartext over HTTP unless you terminate TLS upstream.

For the full list of [auth] and other settings, see config.toml reference.

Verify the service is running ​

To confirm the service started, check its status:

bash
systemctl status videonode.service

To follow live logs:

bash
journalctl -u videonode.service -f

The API is available at http://localhost:8090 once the service is up. See the quickstart for first steps after installation.