feat(api,viewer): viewer REST shim + rename AnthiasWebview → AnthiasViewer

[vpetersson]

Issues Fixed

First step of #2906. Lands two of the five phases that issue lays
out: Phase 1 (server-side REST shim) and the safe-now subset of
Phase 4 (binary / D-Bus / runtime-path renames). The source-tree
rename src/anthias_webview/ → src/anthias_viewer/ is deferred to
Phase 5 because the directory name collides with the still-extant
Python viewer package.

Description

REST shim (Phase 1). Two new endpoints, both internal-auth
gated (same shared token as /api/v2/assets/<id>/recheck):

• GET /api/v2/viewer/playlist — server-evaluated active assets,
  shuffled if shuffle_playlist is set, plus the next
  re-evaluation deadline and the server's notion of now.
  Mirrors anthias_viewer.scheduling.generate_asset_list() but
  returns Asset rows so AssetSerializerV2 can render them.
• GET /api/v2/viewer/settings — viewer-relevant subset only
  (shuffle_playlist, show_splash, screen_rotation,
  audio_output, debug_logging). Narrower than
  DeviceSettingsViewV2 on purpose: keeps operator credential
  fields off the viewer-facing path.

The Python viewer keeps using its own copy of generate_asset_list
for now — the C++ viewer (Phase 3) will switch to these endpoints
and the Python duplicate goes away in Phase 5.

Rename (partial Phase 4). Binary AnthiasWebview → AnthiasViewer
and D-Bus service anthias.webview → anthias.viewer, applied
atomically:

• .pro file renamed; Qt 6 + Qt 5 builder Dockerfiles updated.
• sh.Command('AnthiasViewer') spawn from the Python viewer; the
  D-Bus rename is safe because client and service ship in the same
  image.
• bin/start_viewer.sh now writes to
  /data/.local/share/AnthiasViewer and /data/.cache/AnthiasViewer
  with a one-shot symlink from the old paths so upgraded devices
  keep QtWebEngine cookies / local-storage.
• bin/test_webview_cpp.sh, comment trail in
  src/anthias_viewer/*.py, tests/test_viewer.py /
  tests/test_media_player.py assertions, src/anthias_webview/README.md.

Test plan

• uv run ruff check . and uv run ruff format --check . clean
• uv run pytest -m "not integration" — 876 passed, 42 deselected
• New tests/test_viewer_api.py covers auth (no token / wrong token),
  empty playlist, active-only filter, play_order ordering, deadline
  = soonest end_date, deadline = scheduled start_date, windowed
  60s cap, shuffle membership, settings subset, screen_rotation
  clamp (12 cases total)
• End-to-end test on Raspberry Pi devices (binary rename, symlink
  migration, D-Bus service rename)
• End-to-end test on x86

Checklist

• I have performed a self-review of my own code.
• New and existing unit tests pass locally and on CI with my changes.
• I have done an end-to-end test for Raspberry Pi devices.
• I have tested my changes for x86 devices.
• I added a documentation for the changes I have made (when necessary).

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[vpetersson]

End-to-end verification on real hardware

Tagged the build db999f1 and deployed via docker save | gzip | ssh 'gunzip | docker load' to all four test devices. Re-rendered each device's docker-compose.yml from this PR's template so the test runs against what this PR ships, not against the older template the devices already had.

Board	Image	Binary rename	D-Bus rename	Symlink migration	/api/v2/viewer/playlist	/api/v2/viewer/settings	403 no-token
x86 (192.168.200.207)	db999f1-x86	✅ /usr/local/bin/AnthiasViewer	✅ viewer up via new D-Bus name	✅ AnthiasViewer → AnthiasWebview symlink in both /data/.local/share and /data/.cache	✅ 200, empty playlist	✅ 200, 5 keys	✅ 403
Pi 5 (192.168.200.237)	db999f1-pi5	✅	✅	✅ symlinks present	✅ 200	✅ 200	✅ 403
Pi 4 (192.168.200.141)	db999f1-pi4-64	✅	✅	✅ symlinks present	✅ 200	✅ 200	✅ 403
Rock Pi 4 (192.168.200.155, arm64)	db999f1-arm64	✅	✅	n/a — build post-dates the symlink-migration removal commit, so AnthiasViewer + AnthiasWebview coexist as separate dirs (the simplified behavior)	✅ 200, BBB asset rendered with is_active: true	✅ 200	✅ 403

Symlink-migration follow-up

Per discussion, dropped the elaborate symlink-migration block from bin/start_viewer.sh (commit 2822fe61) — the QtWebEngine cache rebuilds itself on the next page load, so it's not worth the code. Three of the boards above were deployed with the pre-removal image and show the symlink working; the fourth (Rock Pi 4) was built after the removal and shows the cleaner state-coexistence behavior. Both code paths validated.

Video playback (#2905 follow-up on Rock Pi)

The Rock Pi 4 was specifically flagged as having had no #2905 validation. Running through it now:

• Sample H.264 (320×240) — plays cleanly via the renamed AnthiasViewer (QtMultimedia + libavcodec/v4l2_request → rkvdec). Viewer 4.4 % CPU, 147 MB / 773 MB cgroup, load avg 0.56.
• Sample HEVC (320×240) — plays cleanly via the same path. Viewer 0.55 % CPU, 163 MB / 773 MB, load avg 0.36. Low CPU under HEVC playback is itself evidence the H.265 hwdec block on the RK3399 is engaged.
• Pre-existing BBB 4K60 HEVC asset — wedged the device (SSH unresponsive ~3 min into playback after deploy). Reproduces the validation gap referenced in your note about feat(viewer,webview): embed QtMultimedia in AnthiasWebview, eliminate two-process DRM contention + Pi 4 drops #2905. Power-cycled, disabled the asset, and proceeded with smaller content. Not introduced by this PR — same playback pipeline as feat(viewer,webview): embed QtMultimedia in AnthiasWebview, eliminate two-process DRM contention + Pi 4 drops #2905 shipped, just renamed. Filed as a separate concern.
• BBB 1080p30 H.264 + HEVC + 4K30 H.264 + HEVC — burn-in running now (15 s per asset, cycling all four; viewer at ~9.5 % CPU / 207 MB at start). Will report back when several hours have elapsed.

Open

• 4K60 burn-in still skipped on Rock Pi pending the feat(viewer,webview): embed QtMultimedia in AnthiasWebview, eliminate two-process DRM contention + Pi 4 drops #2905 wedge investigation.
• Cross-board playback validation on x86 / Pi 5 / Pi 4 still uses small sample assets — none of those devices were flagged in your note, but happy to extend the burn-in there if you want symmetric coverage.

🤖 Generated with Claude Code

[vpetersson]

Burn-in update — Rock Pi 4 (1 GB variant), realistic mix

Followed the 1080p HEVC + H.264 baseline with a graduated realistic-mix burn-in: HEVC video → JPG image → webpage. Findings, working from healthiest to most stressful:

What works cleanly

• HEVC video alone — three full 15-min windows, 0 compositor drops, viewer settled at ~280 MB / 10-80 % of one core (decoder phase dependent), load avg ~1.0. HEVC is hardware-decoded via rkvdec (hevc_v4l2request).
• HEVC video + JPG image — same picture. Viewer ~220 MB / 9 % CPU, load avg ~0.25 in steady state. 0 drops.
• HEVC video + image + lightweight webpage (example.com) — also fine. Viewer crept to 250 MB while the WebEngine renderer was active, dropped back to 220 MB after navigation away. Clean cycles.

Where it falls over

• engadget.com as the webpage — graduated approach (adding it last after example.com was already cycling) survived one full mixed cycle, but within ~20 min sustained cycling it drove the host into hard memory thrash:
  • Host total: 966 MB RAM, 921 MB used, swap fully consumed (483 / 483 MB).
  • kswapd0 pinned a core; SSH went unresponsive for minutes at a time; eventually the device fully hangs.
  • Viewer container itself stays cgroup-isolated at ~170 MB — the pressure comes from the QtWebEngine renderer/GPU/sandbox helper processes spawned outside the container's accounting, plus libheif/decoder state.
  • Restarting the viewer container freed ~240 MB resident immediately, confirming the engadget renderer was the squatter.
• The earlier wedge after INSERT OR REPLACE + PUBLISH reload of all three new assets at once is the same root cause — the asset-loop tried to render engadget while the new playlist was still settling, and got compounded by the renderer/sandbox churn.

Diagnosis

Not a viewer bug, not a regression. This Rock Pi 4 is the 1 GB RAM variant (visible in /proc/meminfo). The QtWebEngine renderer for a modern JS-heavy page like engadget.com routinely runs 100-300 MB, and the helper-process model means every page reload reseats the renderer. On a heatsink-less SBC with 1 GB total, that's not survivable as a steady-state diet — pretty much regardless of what code Anthias is running.

The video pipeline itself (after #2905) is fine on this hardware as long as the webpage assets in rotation are light.

Open follow-ups (separate from this PR)

1. feat(viewer,webview): embed QtMultimedia in AnthiasWebview, eliminate two-process DRM contention + Pi 4 drops #2905 4K decode on Rock Pi — both 4K30 H.264 and 4K60 HEVC wedge the device. Resolution, not codec or fps. Worth a dedicated issue.
2. H.264 HW decode on RK3399 — small-sample isolation showed 4.4 % CPU for 320×240 H.264 vs 0.55 % for HEVC. The +rpt1 ffmpeg appears to engage hevc_v4l2request but not h264_v4l2request. Worth checking the build flags.
3. WebEngine memory guard / page-size warning — Anthias could refuse (or at least warn on) webpage assets when target device RAM is below some threshold. Out of scope here, but the engadget experiment is a textbook example of why it's needed.

None of the above gate this PR; everything its diff actually changes (rename, endpoints, simpler start_viewer.sh) is validated.

🤖 Generated with Claude Code