fix(viewer): pi2/pi3 video via GStreamer HW pipeline (replace VLC) - #2972

Issue Fixed

pi2/pi3 (Qt5 linuxfb) video plays black fleet-wide. Reproduced + root-caused on a Pi 3B+ (across every OS version, so not a recent regression in itself): Showing asset … (video) is logged but nothing reaches the screen. Images/webpages are fine; pi4/pi5/x86 are fine (Qt6 in-process QtMultimedia).

Root cause

• These boards used to play video with VLC's Broadcom --vout=mmal_vout (HW decode, HW scale, HW color-convert, HW scanout — no DRM master). The Bookworm upgrade (Upgrade containers to use Bookworm #1980) dropped mmal and nothing replaced the vout.
• With no --vout, VLC falls back to outputs that can't drive a bare linuxfb console: the rpidistro drm_vout wants a compositor DRM lease (Failed to get xlease — there's no X/Wayland), and the KMS/master vouts need DRM master, which a uid-1000 viewer can't acquire (the viewer's python process already holds card0 → EBUSY/EPERM). mpv --vo=drm hits the same EBUSY.

Fix

Replace VLCMediaPlayer with GstFbdevMediaPlayer for the linuxfb boards (pi1/pi2/pi3): spawn gst-launch-1.0 playbin with a fully-hardware video sink that reaches /dev/fb0 without any DRM master / compositor:

playbin → v4l2h264dec (bcm2835 codec, HW decode)
        → v4l2convert (bcm2835 ISP, HW scale + YUV→fb-format)
        → fbdevsink /dev/fb0

This drives the same VPU + ISP silicon mmal used — decode, scale and color-convert all stay in hardware; only the final framebuffer write is a CPU memcpy. playbin gives container-agnostic demux, auto-plugs the HW decoder (v4l2h264dec at PRIMARY rank), and degrades gracefully when a clip has no audio track. Rotation rides videoflip, inserted only when the panel is actually rotated.

Why not ffmpeg → fbdev

An interim FFmpegFbdevMediaPlayer (ffmpeg HW-decode → CPU convert → -f fbdev) was built and then abandoned after benchmarking on the Pi 3: HW decode worked (~60 fps), but doing the YUV→RGB convert + scale on the ARM CPU via swscale managed only ~6 fps to rgb565 (no NEON rgb565 path) and ~28 fps to bgra — and any real scaling collapsed it further. v4l2convert moves that work back onto the ISP, which is what the ~40 fps, 0-drop benchmark above measures. (An earlier "decode hang" scare turned out to be a malformed trimmed test clip that didn't start on an IDR — the strict HW decoder waits for a random-access point; well-formed clips decode fine.)

Description

• New GstFbdevMediaPlayer: builds the gst-launch playbin argv, loops the on-screen slot by re-launching on EOS (breaks on error), and kills by process group so no gst-launch orphan keeps the framebuffer. Reads fb geometry/format from /sys/class/graphics/fb0 to pin the v4l2convert output caps.
• MediaPlayerProxy routes pi1/pi2/pi3 → GstFbdevMediaPlayer; everything else (incl. forced pi4-64/arm64) stays on MPVMediaPlayer.
• Image: add gstreamer1.0-{tools,plugins-base,plugins-good,plugins-bad} to the Qt5 viewer; drop the now-unused vlc apt package + python-vlc dep (+ its mypy override).
• Docs (docs/board-enablement.md), the upload-gate comment in processing.py, and C++/.pro comments updated.

On-device validation

Run on a live fleet Pi 3 (HDMI attached). This surfaced — and the PR fixes — two bugs that the headless benchmark could not (it used file:// URIs and fakesink audio):

1. Bare-path URI — local assets store a bare absolute path, but playbin's uri needs a scheme; _as_gst_uri() now wraps bare paths as file://.
2. Missing alsasink — Debian ships the ALSA sink in gstreamer1.0-alsa (not -plugins-base); without it the audio-sink=alsasink … fails pipeline construction and black-screens all video. Added to the image deps.

After both fixes the full pipeline renders correctly on real hardware.

Checklist

• I have performed a self-review of my own code.
• New and existing unit tests pass locally (962 passed) and lint/format are clean.
• End-to-end validated on a live balena Pi 3 (HDMI connected, 1920×1080 @16bpp rgb565): the full pipeline (v4l2h264dec → v4l2convert→RGB16 → fbdevsink + alsasink HDMI audio) constructs and writes motion video to the real /dev/fb0 with zero pipeline errors (verified by capturing the framebuffer across frames). HW decode + scale + convert benchmarked at ~40 fps / 0 drops.
• x86 — N/A (linuxfb-only path; x86 uses QtMultimedia).
• Documentation updated (docs/board-enablement.md).

🤖 Generated with Claude Code