feat(viewer,server): per-board HW decode + envelope-driven asset processor

src/anthias_viewer/media_player.py

@@ -172,43 +172,59 @@ def play(self) -> None:
         # effect without a viewer restart, matching VLCMediaPlayer.
         settings.load()
 
-        # Pin to 1080p on Pi4-64/Pi5: mpv's default --drm-mode=preferred
-        # reads the connector's EDID-preferred mode (4K on most modern
-        # TVs) and runs CPU zimg upscale, which drops below real-time
-        # on the A72. Software decode of 1080p H.264 fits 4 cores fine.
+        # Software-decode tuning for Pi4-64 (A72) / Pi5 (A76). mpv 0.40
+        # in Debian Trixie has v4l2m2m-copy but not v4l2request hwdec,
+        # so --hwdec=auto-safe falls through to software decode on
+        # H.264/HEVC; pinning 4 threads keeps 1080p decode well above
+        # real-time on both SoCs.
         device_type = os.environ.get('DEVICE_TYPE', '')
         extra_args: list[str] = []
         if device_type in ('pi4-64', 'pi5'):
-            extra_args = [
-                '--drm-mode=1920x1080@60',
-                '--vd-lavc-threads=4',
-            ]
-
-        # x86 runs under `cage` (a wlroots kiosk compositor — see
-        # bin/start_viewer.sh); cage holds DRM master, so --vo=drm is
-        # denied. Route mpv through the GL VO over a Wayland EGL
-        # context, which is the generic path mpv supports on every x86
-        # GPU with Mesa or vendor GL drivers. Paired with
-        # --hwdec=auto-safe, VAAPI-capable iGPUs (Intel iHD/i965, AMD
-        # radeonsi, …) decode in hardware and hand frames to the GL
-        # context as DMA-BUFs via dmabuf-interop-gl; software decode
-        # still works via the same VO for codecs without HW support.
-        # --vo=dmabuf-wayland would skip the GL upload entirely but
-        # segfaults under cage in the viewer's background-spawn path
-        # (mpv 0.40.0 + wlroots-0.18 + libplacebo dies between hwdec
-        # init and file open). Pi boards (pi4-64/pi5) keep --vo=drm —
-        # they own the framebuffer directly with no compositor.
+            extra_args = ['--vd-lavc-threads=4']
+
+        # Per-board VO selection:
+        #
+        # * x86 runs under `cage` (a wlroots kiosk compositor — see
+        #   bin/start_viewer.sh); cage holds DRM master, so --vo=drm
+        #   is denied. Route mpv through the GL VO over a Wayland EGL
+        #   context, the generic path mpv supports on every x86 GPU
+        #   with Mesa or vendor GL drivers. Paired with
+        #   --hwdec=auto-safe, VAAPI-capable iGPUs (Intel iHD/i965,
+        #   AMD radeonsi, …) decode in hardware and hand frames to
+        #   the GL context as DMA-BUFs via dmabuf-interop-gl; software
+        #   decode still works via the same VO. --vo=dmabuf-wayland
+        #   would skip the GL upload entirely but segfaults under
+        #   cage in the viewer's background-spawn path (mpv 0.40.0 +
+        #   wlroots-0.18 + libplacebo dies between hwdec init and
+        #   file open).
+        #
+        # * Pi4-64 / Pi5 own the framebuffer directly (no compositor)
+        #   and go through the same GL VO with --gpu-context=drm.
+        #   mpv talks to KMS via libgbm and runs scaling on the V3D
+        #   at the connector's preferred mode (typically 4K on a
+        #   modern TV). The previous --vo=drm path ran the same scale
+        #   on CPU zimg and ran out of headroom on the A72; the
+        #   previous --drm-mode=1920x1080@60 pin sidestepped that by
+        #   forcing the output to 1080p. Under --gpu-context=drm
+        #   neither workaround is needed — the V3D upscales for free
+        #   and the --drm-mode flag actively *hurts* throughput here
+        #   (verified on Pi4-64: 294 drops/30s with the pin vs 3-6
+        #   without, on the same clip). So no pin, no extra mpv VO
+        #   args beyond --vd-lavc-threads above.
         if device_type == 'x86':
             vo_args = ['--vo=gpu', '--gpu-context=wayland']
+        elif device_type in ('pi4-64', 'pi5'):
+            vo_args = ['--vo=gpu', '--gpu-context=drm']
         else:
             vo_args = ['--vo=drm']
 
         # Issue #2856. On x86, cage/wlroots is rotated via wlr-randr and
         # mpv's wayland VO inherits the compositor transform — passing
-        # --video-rotate here too would double-rotate. On Pi --vo=drm
-        # writes straight to the framebuffer with no compositor in the
-        # path, so the rotation has to happen inside mpv. Skip the arg
-        # at 0° so unrotated displays stay on the existing CLI.
+        # --video-rotate here too would double-rotate. On Pi mpv talks
+        # to KMS directly (no compositor in the path, whether via the
+        # legacy --vo=drm or today's --vo=gpu --gpu-context=drm), so
+        # the rotation has to happen inside mpv. Skip the arg at 0° so
+        # unrotated displays stay on the existing CLI.
         rotation = _screen_rotation()
         rotate_args: list[str] = []
         if rotation and device_type != 'x86':

tests/test_media_player.py

@@ -47,19 +47,21 @@ def mpv() -> Iterator[_MPVFixtures]:
     return_value='sysdefault:CARD=vc4hdmi0',
 )
 @patch('anthias_viewer.media_player.subprocess.Popen')
-def test_play_invokes_popen_with_expected_args(
+def test_play_invokes_popen_with_expected_args_on_pi4_64(
     mock_popen: Any, _mock_detect: Any, mpv: _MPVFixtures
 ) -> None:
     mpv.player.set_asset('file:///test/video.mp4', 30)
-    with patch.dict('os.environ', {'DEVICE_TYPE': 'pi4'}):
+    with patch.dict('os.environ', {'DEVICE_TYPE': 'pi4-64'}):
         mpv.player.play()
 
     mock_popen.assert_called_once_with(
         [
             'mpv',
             '--no-terminal',
-            '--vo=drm',
+            '--vo=gpu',
+            '--gpu-context=drm',
             '--hwdec=auto-safe',
+            '--vd-lavc-threads=4',
             '--audio-device=alsa/sysdefault:CARD=vc4hdmi0',
             '--',
             'file:///test/video.mp4',
@@ -70,35 +72,39 @@ def test_play_invokes_popen_with_expected_args(
 
 
 @patch('anthias_viewer.media_player.subprocess.Popen')
-def test_play_pins_1080p_mode_on_pi4_64(
+def test_play_tunes_decoder_threads_on_pi4_64(
     mock_popen: Any, mpv: _MPVFixtures
 ) -> None:
     mpv.player.set_asset('file:///test/video.mp4', 30)
     with patch.dict('os.environ', {'DEVICE_TYPE': 'pi4-64'}):
         mpv.player.play()
 
     args, _ = mock_popen.call_args
-    assert '--drm-mode=1920x1080@60' in args[0]
     assert '--vd-lavc-threads=4' in args[0]
     assert '--hwdec=auto-safe' in args[0]
     assert '--hwdec=v4l2m2m-copy' not in args[0]
+    # --drm-mode pinning was used on the legacy --vo=drm path to dodge
+    # CPU zimg upscale at 4K; under --gpu-context=drm the V3D handles
+    # scaling, the pin is no longer needed, and it actively hurts
+    # throughput when combined with GBM (verified on Pi4 hardware).
+    assert '--drm-mode=1920x1080@60' not in args[0]
 
 
 @patch('anthias_viewer.media_player.subprocess.Popen')
-def test_play_pins_1080p_mode_on_pi5(
+def test_play_tunes_decoder_threads_on_pi5(
     mock_popen: Any, mpv: _MPVFixtures
 ) -> None:
     mpv.player.set_asset('file:///test/video.mp4', 30)
     with patch.dict('os.environ', {'DEVICE_TYPE': 'pi5'}):
         mpv.player.play()
 
     args, _ = mock_popen.call_args
-    assert '--drm-mode=1920x1080@60' in args[0]
     assert '--vd-lavc-threads=4' in args[0]
+    assert '--drm-mode=1920x1080@60' not in args[0]
 
 
 @patch('anthias_viewer.media_player.subprocess.Popen')
-def test_play_does_not_pin_mode_on_x86(
+def test_play_omits_pi_tuning_on_x86(
     mock_popen: Any, mpv: _MPVFixtures
 ) -> None:
     mpv.player.set_asset('file:///test/video.mp4', 30)
@@ -124,6 +130,26 @@ def test_play_uses_wayland_vo_on_x86(
     assert '--vo=drm' not in args[0]
 
 
+@pytest.mark.parametrize('device_type', ['pi4-64', 'pi5'])
+@patch('anthias_viewer.media_player.subprocess.Popen')
+def test_play_uses_drm_gpu_context_on_pi4_64_and_pi5(
+    mock_popen: Any, mpv: _MPVFixtures, device_type: str
+) -> None:
+    # Pi4-64 and Pi5 own the framebuffer directly (no compositor)
+    # and use mpv's GL VO with --gpu-context=drm. This offloads the
+    # 1080p->4K upscale to the V3D instead of the A72/A76 CPU zimg
+    # path that --vo=drm took.
+    mpv.player.set_asset('file:///test/video.mp4', 30)
+    with patch.dict('os.environ', {'DEVICE_TYPE': device_type}):
+        mpv.player.play()
+
+    args, _ = mock_popen.call_args
+    assert '--vo=gpu' in args[0]
+    assert '--gpu-context=drm' in args[0]
+    assert '--vo=drm' not in args[0]
+    assert '--gpu-context=wayland' not in args[0]
+
+
 @patch('anthias_viewer.media_player.subprocess.Popen')
 def test_play_uses_local_audio_device_when_configured(
     mock_popen: Any, mpv: _MPVFixtures