feat: Spotify Canvas plugin — automatic per-track sourcing (slice 2 of #442)

[InstaZDLL]

Goal

Follow-up to #442 (slice 2). The manual-mp4 per-track Canvas shipped in #467 (core-only). This issue tracks the automatic sourcing path: a plugin that resolves the current track to a directly-playable loop and hands it to the existing Canvas pipeline — no manual drop.

A viable source exists: Spotify Canvas

Spotify serves Canvas clips as directly-playable mp4 from its CDN (https://canvaz.scdn.co/.../<hash>.cnvs.mp4) — no HLS, so it plays in the desktop webview via <video src> exactly like the manual Canvas and the Apple Motion Artwork overlay.

Resolution flow (reference: two local GPL-3.0 projects — a Python original and a clean Rust rewrite, spotify-canvas-downloader-rs v0.2.0, GET /api/canvas/{track_id} → {canvas_url}):

1. A Spotify track ID (22 chars) is turned into an access token derived from a logged-in session's sp_dc cookie (TOTP token dance — totp-rs).
2. The private Canvas API (spclient.wg.spotify.com/canvaz-cache/) returns a protobuf pointing at the .cnvs.mp4 on canvaz.scdn.co.
3. The core loops the mp4 through the existing CanvasStage / MotionCoverOverlay plumbing — slice 1 already proves the rendering works.

Why this stays a separate, non-signed plugin repo (not the core)

Same line #442 drew for YouTube. Spotify does not publish a Canvas API; this relies on private endpoints, and the token endpoint's own terms state its use is not permitted under Spotify's Developer Terms/Policy (quoted verbatim in the RS project's README). So:

• Never in the signed core. Grey-area sourcing lives in its own plugin repo (liability isolation), exactly like the YT-plugin carve-out in feat: track Canvas — looping clip behind the now-playing view #442. The core only ever loops an mp4 URL a plugin returns.
• License is fine (both reference projects are GPL-3.0-only, matching WaveFlow) — the constraint is Spotify's ToS, not code licensing.

Open problems (all real, none blocking-forever)

1. Per-user sp_dc cookie. Only works for users with a Spotify account willing to paste their cookie; it's their account carrying the risk. Needs a plugin-options field + clear consent copy.
2. Local track → Spotify track ID matching. Local files have no Spotify ID; the plugin must search by artist+title (or ISRC when present) first, then fetch the Canvas. Fuzzy, may mismatch.
3. Private API fragility. Can break without notice; the plugin must fail soft (fall back to motion cover → slideshow → static cover, the existing precedence).

Prerequisites (blocked)

• feat: Release Radar plugin + waveflow:ui/v1 plugin UI surface #443's plugin.wasm CI-rebuild prerequisite — same brick every plugin slice waits on.
• Metadata world extended to per-track Canvas (the current motion field is album-keyed).
• Authenticated HTTP + protobuf decode reachable from the plugin host — verify waveflow:host/* can carry the sp_dc token flow, or extend it.

Related

• Parent: feat: track Canvas — looping clip behind the now-playing view #442 (Canvas, slice 1 shipped in feat(canvas): per-track looping Canvas behind the now-playing view (#442) #467).
• Prerequisite: feat: Release Radar plugin + waveflow:ui/v1 plugin UI surface #443 (plugin.wasm CI + waveflow:ui/v1).
• Reference implementations: spotify-canvas-downloader (Python, GPL-3.0) + spotify-canvas-downloader-rs (Rust, GPL-3.0-only).
• Not to be confused with feat: cover slideshow — album ↔ artist crossfade on the now-playing view #466 (cover slideshow — still-image crossfade, core, already shipped in feat(now-playing): cover ↔ artist crossfade slideshow (#466) #470).

[InstaZDLL]

Decided sourcing UX — cookie-once, resolver embedded in the plugin

Settled the source dilemma (direct-Spotify vs third-party site vs self-hosted service):

• Chosen: the plugin resolves Spotify directly, on its own. The user installs the plugin and pastes their sp_dc cookie once into the plugin's ⚙️ options (same friction as a Last.fm API key — WaveFlow already has generic [[options]] type = text). The token/TOTP/protobuf/HTTP dance happens inside the plugin. No separate service to run, no localhost.
• Rejected — public third-party site (canvasdownloader.com / canvastify): zero setup, but it leaks the user's now-playing to a third party on every track — a real regression for a local-first, privacy-oriented player — plus infra we don't control (rate-limits, blocks, format drift) and it hands back a blob: rather than the direct scdn link. Same ToS-grey either way; laundering through an intermediary doesn't clean it.
• Rejected as default — self-hosted spotify-canvas-downloader-rs: best privacy but too much setup (run a separate service and install the plugin). Kept only as a power-user mention, not the path.

Irreducible trade-off: either the user pastes a cookie once, or their now-playing leaks to a third party. Cookie-once wins on accessibility without the leak.

The one open question this hinges on (→ #443)

Can a WASM plugin do authenticated HTTPS + TOTP (crypto) + protobuf decode internally? If the plugin host can carry that, the self-contained plugin is clean and low-friction. If not, the fallback is a native side-path (like the offline web-radio catalogue) — which would drag the grey-area code back into the signed core, the thing we're isolating. So the plugin-host capability set is the real gate here.

[InstaZDLL]

Required: account-ban warning next to the cookie field

The sp_dc cookie is the user's own Spotify session, used against a private API that Spotify's Developer Terms forbid. Worst case, Spotify can suspend or ban that account. So the plugin's ⚙️ options must show an explicit, unmissable warning right next to the cookie field (not buried in a README):

⚠️ This uses your personal Spotify account against an unofficial API. Spotify may rate-limit, suspend or ban the account. Use at your own risk; a throwaway account is safer.

Informed consent at the point of entry — the user opts in with eyes open. Pair it with fail-soft (missing/expired cookie or a ban just falls back to the motion cover → slideshow → static cover precedence, never breaks playback).

[InstaZDLL]

Livré end-to-end.

Monde core waveflow:canvas/v1 (PR #478) : provider par-piste track-canvas(artist,title,album?,duration-ms?) -> result<option<canvas>,string>, fanout fetch_track_canvas (per-plugin lock + timeout 20 s + garde SSRF is_safe_motion_url, fail-soft total → repli motion → slideshow → cover, jamais casser la lecture). Précédence backdrop manual > plugin > motion > slideshow > cover. Fixture plugins/canvas-fixture/ + tests/plugin_canvas.rs.

Cache local opt-in (PR #479) : app_setting['canvas.cache_enabled'] (défaut OFF), LRU partagée avec le motion cache. Durci côté SSRF au passage (CacheError { UnsafeUrl, Other } — un redirect non-sûr = skip du plugin au lieu de streamer l'url brute au <video>, redaction des urls loggées, limite de redirects testée).

download_url registry (PR #480) : décorrèle le store de GitHub → permet l'auto-hébergement du binaire.

Plugin Spotify Canvas : construit, validé live end-to-end (TOTP → token → client-token → pathfinder v2 → protobuf canvaz → canvaz.scdn.co/*.cnvs.mp4) et testé in-app. Reste hors du core signé (repo privé, zone grise ToS Spotify), distribué en binaire via waveflow.app — même carve-out que le YouTube de #442. Fail-soft, warning ban à côté du champ cookie.

Les « prerequisites (blocked)» du ticket (plugin.wasm CI, canvas per-track, HTTP authentifié + protobuf depuis le host) ont tous été résolus. L'install via le store s'activera avec la release ≥ 1.8.0 (min_app_version) ; le sideload fonctionne déjà.

Parent #442 (slice 1 #467). À ne pas confondre avec #466/#470 (slideshow).