deepdrft/product-notes/phase-12-waveform-visualizer-generalization.md

Phase 12 — Waveform Visualizer Generalization + NowPlayingHero Rewire (Design Spec)

Status: design-complete, implementation-ready. Daniel resolved the three §8 open questions on 2026-06-17 — committing Direction B (high-res compute for all media), correcting the datum model to per-track, not per-release, and resolving §8b to full parity on the lava controls: the visualizer rides every Release Detail host (Mix, Cut, Session) and the seven-knob bar + lava-lamp toggle ride all three — not Mix-only. The three-hosting-mode layout framing (visualizer-is-the-page on Mix / ambient environment on Cut/Session / contained on NowPlaying) is retained; the change is that controls are now present on all three detail-page hosts, not suppressed on Cut/Session. The spec below is revised to those three. One small sub-question remains open (§8b-followup): whether full-parity controls also extend onto the small NowPlaying home card (default: no — the card stays controls-suppressed). Author: product-designer. Date: 2026-06-17. No code has been written by this doc.

This phase has two deliverables that share one engine:

1. Generalize the landed Mix waveform visualizer (the WebGL2 lava renderer + its seven-knob controls) from a Mix-only treatment into a track-cardinal visualizer that every Release Detail page can host — Cuts, Sessions, and Mixes alike — rendering the waveform of whatever track is currently playing/selected on that page.
2. Overhaul the home-page NowPlayingHero (NowPlayingCard) so its "Now Playing" animation is the real waveform visualizer driven by live playback, replacing the 20 hardcoded CSS-animated bars (the "stochastic bullshit").

The explicit ask is DRY / SOLID: one reusable visualizer engine serving Mix detail, all Release Detail pages, and the NowPlayingHero — not three forks. This spec's central finding makes that cheap: the engine is already track-cardinal below the surface. The work is extraction, a per-track high-res compute generalization (Direction B), and three hosting modes of the one engine — not a rebuild.

The keystone model correction (Daniel, 2026-06-17). The waveform datum is per-track, not per-release. "Each track in the release must get the metadata. The waveform visualizer metadata should be tied to the track, right? The release is just the host." Every track gets its own high-res waveform datum; the release is merely the host surface, and the visualizer renders the datum of whatever track is currently playing/selected. This simplifies the design — it aligns with the bridge already keying on TrackId, and it dissolves the old "what is a multi-track Cut's waveform?" question (there is no release-level datum to choose; the visualizer just shows the current track's). Threaded through §4, §5, the endpoint shape, and the acceptance criteria below.

Cross-references (read before implementing):

• product-notes/phase-10-mix-visualizer-lava-reframe.md — the lava renderer this generalizes. The CPU-physics wax-blob model, the OKLab three-color gradient, the seven-knob control model, the bridge contract, and the read-only contract all carry forward unchanged. This spec does not re-derive any of them; it changes where the engine lives, what feeds it, and who hosts it.
• product-notes/mix-visualizer-webgl-renderer.md — the renderer architecture (pipeline, datum-as-texture, bridge, rAF loop). The §2 contract carries forward; §4/§7 are already superseded by the reframe.
• DeepDrftPublic.Client/Controls/MixWaveformVisualizer.razor[.cs/.css] — the Blazor bridge. Already keyed on ReleaseEntryKey + TrackId, not on Mix. Renamed and re-pointed by this phase (§3, §4).
• DeepDrftPublic.Client/Controls/MixVisualizerControls.razor[.cs/.css], DeepDrftPublic.Client/Services/MixVisualizerControlState.cs, DeepDrftPublic.Client/Controls/MixZoomMapping.cs — the controls + state + mapping. Renamed, otherwise unchanged.
• DeepDrftPublic/Interop/visualizer/MixVisualizer.ts — the WebGL2 renderer module. Renamed; the only logic change is how the datum's time-mapping is established when no high-res mix datum exists (§5).
• DeepDrftPublic.Client/Controls/ReleaseDetailScaffold.razor — the shared detail chrome. The visualizer becomes a scaffold-level concern via a new optional Ambient slot (§3c, §3f).
• DeepDrftPublic.Client/Pages/MixDetail.razor, SessionDetail.razor, CutDetail.razor — the three release-detail hosts (three distinct hosting modes — §3f).
• DeepDrftPublic.Client/Controls/NowPlayingCard.razor[.css], NowPlaying.razor — the home-page now-playing card carrying the stochastic bars (§6).
• DeepDrftAPI/Controllers/TrackController.cs, ReleaseController.cs — the waveform endpoints; under the per-track model the datum resolves for a track (§5), with the release as addressing context.
• DeepDrftContent/Processors/WaveformProfileService.cs, MixWaveformResolution.cs, Constants/VaultConstants.cs — the compute/store path and the vaults; Direction B generalizes the high-res compute here to every track (§5).
• DeepDrftAPI/Services/UnifiedTrackService.cs — the upload path; Direction B adds a per-track high-res compute at upload (§5, §8a-new).
• DeepDrftManager CMS generate action (the Mix-only "generate waveform" trigger) — Direction B generalizes it off Mix-only to any track (§5).

---

1. The central finding — the engine is already release-cardinal

Before any plan: a read of the live code shows the "Mix coupling" is mostly nominal, not structural. The visualizer is named Mix* throughout, but its architecture is release-generic:

Layer	Reality on disk today	Mix-coupled?
MixWaveformVisualizer bridge inputs	ReleaseEntryKey (string) + TrackId (long?) + cascaded player	No — already track-cardinal (keys on TrackId)
Playback coupling	IsActivePlayer gates on TrackId matching the cascaded player's current track	No — works for any track
Renderer (MixVisualizer.ts)	datum texture + scroll/zoom geometry + wax-blob physics + OKLab gradient	No — pure function of a loudness datum + duration
Controls + state	seven normalized dials, scoped persistence, Changed seam	No — renderer-agnostic
Datum fetch	IReleaseDataService.GetMixWaveform(entryKey) → GET api/release/{entryKey}/mix/waveform	Yes — 404s unless Medium == Mix; resolves per release, not per track
Datum source	the high-res mix-waveforms vault, keyed by MixMetadata.WaveformEntryKey	Yes — only the Mix's single track gets the high-res datum
Names / comments	Mix* everywhere	cosmetic

So the genuinely Mix-specific surface is exactly two things: the fetch endpoint that gates on Medium == Mix and resolves per-release, and the high-res datum that only Mix tracks have. Everything else is a rename.

This is the SOLID seam the whole phase turns on. The renderer and bridge already obey the right abstraction ("render a loudness datum coupled to a playing track"); they were just named for their first consumer. Generalizing is: rename to the abstraction, give the abstraction a per-track datum source that exists for every track, and let three hosts mount it. No new renderer, no fork.

The crucial data fact (verified): every uploaded track already has a waveform profile. UnifiedTrackService.UploadAsync calls WaveformProfileService.ComputeAndStoreAsync(...) at upload time for every track, storing a 512-bucket profile in the waveform-profiles vault keyed by the track's EntryKey (this is the datum the player-bar WaveformSeeker already consumes). Mix tracks additionally get a duration-derived high-res datum (~333 samples/sec) in the separate mix-waveforms vault, triggered by a CMS action. So the high-res datum is the only gap — and under Daniel's per-track model it is a gap per track, not per release: every track should carry its own high-res datum, computed at upload and (for existing tracks) backfilled. Direction B (committed) makes the high-res compute a per-track compute for all media, keyed by track EntryKey (§5). The cheaper road — serving the existing 512-bucket profile to non-Mix and skipping new compute (old "Direction A") — was the road not taken (§5).

---

2. Goal and scope boundary

Goal. One reusable WaveformVisualizer (renamed from MixWaveformVisualizer) + its lava renderer + its controls, mounted in three hosting modes (§3f) — visualizer-is-the-page on Mix detail, ambient environment on Cut/Session detail, contained live element on the home-page NowPlaying card — each fed by a per-track high-res datum that exists for every track (Direction B, §5). The visualizer always renders the currently playing/selected track's datum; the release is the host, not the datum's owner. The lava controls ride every Release Detail host — Mix, Cut, and Session all get the seven-knob bar + lava-lamp toggle (full parity, §3d). The NowPlaying card drives the same engine off live playback (§6) and stays controls-suppressed by default (the one open sub-question, §8b-followup).

In scope.

• Rename + relocate the visualizer engine to a track-cardinal identity (MixWaveformVisualizer → WaveformVisualizer, MixVisualizerControls → WaveformVisualizerControls, MixVisualizerControlState → WaveformVisualizerControlState, MixVisualizer.ts → WaveformVisualizer.ts, MixZoomMapping → WaveformZoomMapping). Pure renames; no behavior change. (§3a)
• Generalize the high-res compute to every track (Direction B, §5). This is now the load-bearing data change — and it is larger than a single endpoint. It touches: (a) the content compute path (WaveformProfileService / MixWaveformResolution) — generalize the duration-derived high-res compute off Mix-only to any track; (b) the upload path (UnifiedTrackService.UploadAsync) — compute the high-res per-track datum at upload for every new track; (c) the CMS generate action — generalize the Mix-only "generate waveform" trigger to any track; (d) a backfill of the high-res datum for every existing track that lacks one (§8a-new); (e) a per-track datum fetch endpoint (§5) the bridge calls.
• Host the visualizer in three modes — via a new optional Ambient slot on ReleaseDetailScaffold for the Cut/Session ambient mode (§3c, §3f), Mix keeping its visualizer-is-the-page full-bleed mount, and a contained mount on the NowPlaying card. The slot lets scaffold-composing pages mount without re-implementing the wrapper.
• Rewire the NowPlayingHero to mount the visualizer driven by the live cascaded player, replacing the 20 hardcoded CSS bars (§6).
• Mount the lava controls on every detail-page host — Mix, Cut, and Session all carry the seven-knob bar + lava-lamp toggle (full parity, §3d). The NowPlaying card mounts controls-suppressed by default (§3d, §8b-followup).

Out of scope / unchanged.

• No renderer rewrite. The wax-blob physics, the OKLab gradient, the collision model, the seven dials — all carry forward from the Phase 10 reframe exactly. This phase moves and renames the engine and changes its input plumbing and its compute breadth, never its art.
• No bridge redesign. The single-owner bridge, the idempotent datum guard, the IsActivePlayer gating, the isPlaying-gated rAF loop — all preserved. Extend the fetch, not the contract.
• No new control model. The seven knobs and …ControlState stay as-is (renamed). No new dials.
• No new high-res algorithm. Direction B generalizes the existing duration-derived compute to run per-track for all media; it does not redesign how the high-res datum is computed (MixWaveformResolution carries forward — the same ~333 samples/sec duration-derived model).
• No playback-control change. Read-only contract holds everywhere, including the NowPlaying card — the home card visualizes, it does not become a transport.

---

3. Generalizing the visualizer onto every Release Detail page

3a. The rename (Wave 12.A — pure, mechanical, no behavior change)

Rename the engine to its abstraction. This is a mechanical sweep with zero behavior change, done first so every later wave references the generalized names:

Today (Mix-named)	Generalized
MixWaveformVisualizer.razor[.cs/.css]	WaveformVisualizer.razor[.cs/.css]
MixVisualizerControls.razor[.cs/.css]	WaveformVisualizerControls.razor[.cs/.css]
MixVisualizerControlState.cs (+ DI registration)	WaveformVisualizerControlState.cs
MixZoomMapping.cs	WaveformZoomMapping.cs
MixVisualizer.ts (+ the ./js/visualizer/MixVisualizer.js import path)	WaveformVisualizer.ts
DDIcons.LavaLamp / LavaLampFilled	keep (the lava-lamp glyph is the controls affordance, now on every detail-page host — §3d)

The ReleaseEntryKey / TrackId parameters and the fetch keep working unchanged through the rename. The mix-waveforms vault name and MixMetadata.WaveformEntryKey stay (they are still where the high-res mix datum lives — generalizing the fetch doesn't require renaming the mix-specific high-res store; see §5). Acceptance: the Mix detail page looks and behaves identically after the rename; the only diff is identifiers.

DRY note. The temptation is to skip the rename and "just reuse MixWaveformVisualizer on other pages." Resist it: a MixWaveformVisualizer mounted on a Cut page is a lie that every future reader has to decode, and it cements the wrong mental model right when we're trying to break it. The rename is cheap and it is the SOLID move — name the thing for its abstraction, not its first caller.

3b. What stays specialized (the abstraction boundary)

Generalizing does not mean flattening every medium to the same look. The clean Liskov boundary:

• Shared (the engine): the renderer, the bridge, the controls component, the state, the datum contract, the playback coupling, the read-only contract. One copy, consumed by all hosts.
• Per-host (the composition): whether the visualizer is mounted, whether the lava controls are exposed, and what datum the host points it at. These ride host composition (slots + parameters), never a switch (medium) inside the engine. A medium that wants no visualizer mounts none; a medium that wants the ambient backdrop but no knobs mounts the backdrop with controls suppressed.

This is the same "variance rides a slot, never a flag" discipline the scaffold already uses for Header/Hero/TopRightAction (Phase 9 §5.3) — extended to the ambient mount.

3c. The hosting seam — an Ambient slot on ReleaseDetailScaffold (Wave 12.C)

Naming note. This slot was first drafted as Backdrop. Daniel pushed back: on the Mix page the visualizer is not a backdrop — it is the full-bleed centerpiece that is the page. "Backdrop" only describes what the visualizer does on Cut/Session (ambient environment behind the hero+content). The slot is named for that mode — the ambient mode — because Mix doesn't use the slot at all (it keeps its own visualizer-is-the-page mount; see §3f). So: Ambient, not Backdrop.

Today the Mix page mounts the visualizer outside the scaffold (a sibling <MixWaveformVisualizer> then a .mix-detail-foreground wrapper, with the scaffold inside MudContainer). Session mounts nothing. Cut mounts nothing. To let Cut/Session host the visualizer as ambient environment DRY-ly:

Add an optional RenderFragment? Ambient slot to ReleaseDetailScaffold, rendered as the full-bleed position: fixed; inset: 0 layer behind the scaffold's content (the scaffold's existing container becomes the foreground stacking context — promote the mix-detail-foreground stacking pattern into the scaffold so it is the default, not a Mix bespoke). A host that supplies no Ambient gets today's plain background (Liskov: absent slot = no ambient layer, no regression).

• Cut (composes the scaffold) supplies <WaveformVisualizer ReleaseEntryKey=… TrackId=… /> to Ambient with the full seven-knob bar + lava-lamp toggle exposed (full parity, §3d) — a living waveform field behind the album hero + track list, rendering the currently selected/playing track's datum, tunable in place. §8b is resolved: Cut and Session get the ambient layer AND the controls (full parity, not Mix-only). The ambient layout (visualizer behind hero+content) is unchanged; the difference from the earlier draft is that the controls are no longer suppressed here.
• Session does not compose the scaffold (§3e) — it mounts the ambient visualizer directly behind its own hero overlay, the same engine, its own thin full-bleed wrapper.
• Mix does not use this slot. Mix is the visualizer-is-the-page mode (§3f) and keeps its existing full-bleed mount + TopRowCenter knob-bar + lava-lamp toggle exactly as the Phase 10 reframe landed them. The Ambient slot is for the ambient mode only — folding Mix into it would force the slot to carry both "the page" and "behind the page," which is the conflation §3f exists to avoid.

Why the scaffold, not each page. The full-bleed wrapper, the foreground stacking context, and the footer-clip plumbing (the dynamic-footer overflow clip from the reframe §2c) are all chrome, and the scaffold is where chrome lives. Putting the ambient layer on the scaffold means the clip logic, the stacking context, and the mount point are written once. SessionDetail is the lone holdout that doesn't compose the scaffold today — see §3e.

3d. Where do the lava controls live per host? (the controls boundary — full parity, resolved)

The seven-knob lava bar is an expert tuning surface whose identity is "the lava lamp." Daniel's §8b call: full parity on the detail pages. The controls ride every Release Detail host:

• Mix, Cut, and Session detail pages all carry the seven-knob bar + lava-lamp toggle. The WaveformVisualizerControls mount is no longer Mix-suppressed — it rides every detail-page mount. On Mix (mode A) the bar sits in TopRowCenter over the full-bleed visualizer as the Phase 10 reframe landed it; on Cut and Session (mode B) the same controls bar + lava-lamp toggle ride the ambient mount, letting a visitor tune the living field behind the release. The layout still differs per mode (§3f) — visualizer-is-the-page vs. ambient-behind-content — but the controls presence is uniform across all three detail hosts. Rationale (Daniel): the lava is a signature affordance of the site; giving every release page the tuning surface makes the whole site feel alive and consistent, not just the Mix page. The shared WaveformVisualizerControlState supplies the dial values and is where each mount reads/writes, so tuning behaves identically wherever the bar appears (see the state-scoping note below).
• The NowPlaying home card (mode C) stays controls-suppressed by default. Full parity was resolved against the Release Detail pages; the NowPlaying card is the contained mode-C host — a small hero panel, not a full page — where a seven-knob tuning bar may be awkward. Default: the card mounts the ambient/contained field with no knobs, no lava-lamp button, rendering at the shared tuned defaults. This is the one open sub-question — see §8b-followup. The seam supports controls-on-the-card either way (the controls are a separate component over shared state), so flipping it later is a one-line composition change, not an engine change.

State-scoping note (raised by full parity, staff-engineer's call at 12.C). With the controls now present on Mix and Cut and Session, decide whether WaveformVisualizerControlState is one shared tuning (a knob turned on a Cut page is the same lava everywhere — single source of truth, simplest, and consistent with the "one engine" framing) or per-host/per-mode scoped (each surface remembers its own dial positions). Recommend one shared state — it matches the single-engine model, it is what the persisted WaveformVisualizerControlState already is, and "the lava lamp has one set of dials" is the simpler mental model. Flag only; not a product blocker.

3e. The SessionDetail scaffold question

SessionDetail deliberately does not compose ReleaseDetailScaffold (it wraps its own MudContainer + ReleaseHeroOverlay). If Session is to host the ambient layer via the scaffold's new slot, either (a) SessionDetail adopts the scaffold (a larger refactor, out of scope here — Session's divergence was a deliberate Phase 11 call), or (b) Session mounts <WaveformVisualizer> directly with its own full-bleed wrapper (small, local, mirrors what Mix does inline today). Recommend (b) if Session gets the ambient layer at all — don't reopen the Session-vs-scaffold decision for this. Cut does compose the scaffold, so Cut gets the ambient layer for free via the slot. This asymmetry is fine: the slot serves scaffold-composing pages; the one non-composing page mounts the shared engine directly. The engine is still single-source either way — only the mount differs, which is exactly the per-host variance §3b sanctions. Under full parity (§3d), Session's direct mount also carries the seven-knob bar + lava-lamp toggle — the controls bar rides Session's own top-row composition the same way Cut's rides the scaffold's, so Session is full-parity even though it doesn't compose the scaffold.

3f. Three hosting modes of the one engine (the elaboration §8b asked for)

Daniel's pushback on "backdrop": "backdrop?? MIXES doesn't really have a backdrop?" — and he is right. The one engine is hosted in three distinct modes, and "backdrop" only fits one of them. Spelling them out surface-by-surface, because the slot design and the naming follow from this distinction:

Mode	Surfaces	What the visualizer is on screen	Controls	Mount mechanism
A — Visualizer-is-the-page	Mix detail	The full-bleed centerpiece. The lava field is the page; the mix details sit over it as a thin overlay. You came here to watch the lava.	Seven-knob bar + lava-lamp toggle (TopRowCenter)	Mix's own full-bleed mount (unchanged from Phase 10 reframe) — not the Ambient slot
B — Ambient environment	Cut detail, Session detail	Living texture behind and around the hero + content. The album cover / track list / session hero is the subject; the waveform is environment that makes the page feel alive. You came here for the release; the lava is atmosphere.	Seven-knob bar + lava-lamp toggle (full parity, §3d)	ReleaseDetailScaffold.Ambient slot (Cut) / direct full-bleed mount (Session, §3e)
C — Contained live element	NowPlaying card (home)	A small, bounded live panel inside the card. Not full-bleed, not "behind" anything — a contained element that shows the real signal of whatever is playing.	Suppressed by default (§8b-followup)	Contained mount, Fill-mode canvas sized to the card, not the viewport (§6c)

Why three modes and not "backdrop everywhere": the three differ in what the user's eye treats as the subject. On Mix the visualizer is the subject (mode A). On Cut/Session the release is the subject and the visualizer is environment (mode B — this is the only mode that is genuinely a "backdrop"). On the home card the visualizer is a bounded live readout of current playback (mode C). Same engine, same datum contract, same renderer — three compositions. This is the SOLID payoff stated precisely: the variance is entirely in hosting composition (full-bleed vs. slot vs. contained; viewport-sized vs. container-sized; controls present on all three detail hosts, suppressed-by-default only on the contained home card), never in the engine. Note the controls are no longer a per-mode discriminator on the detail pages — modes A and B both carry the full seven-knob bar (§3d, §8b resolved to full parity); only the mode-C home card suppresses them by default (§8b-followup).

What this resolves about the slot. Because Mix (mode A) keeps its own mount and the NowPlaying card (mode C) is a contained mount, the ReleaseDetailScaffold slot serves mode B only — and that is why it is named Ambient, not Backdrop and not Visualizer. A Visualizer slot would imply Mix routes through it too; an Ambient slot says exactly what it carries: the behind-the-content environment layer for scaffold-composing detail pages. Mode A and mode C mount the engine without the slot.

§8b status: RESOLVED — modes A + B + C all live, with FULL PARITY on the controls across all three detail hosts (Daniel, 2026-06-17). All three hosting modes ship (Mix is the page, Cut/Session are ambient, the home card is contained) and the seven-knob lava bar + lava-lamp toggle ride every Release Detail host — Mix, Cut, and Session — not Mix-only. The earlier "mode 1 (Mix + NowPlaying only, Cut/Session plain)" fallback is closed; the earlier "controls Mix-only" default is overridden by Daniel's full-parity call. The Cut/Session ambient treatment plus its in-place tuning controls is the distinctive-feel win the generalization buys; the Ambient slot carries the field and the controls bar rides the host composition alongside it, so each detail page is a one-mount-plus-controls-bar composition. One sub-question remains (§8b-followup): whether full parity also extends the seven-knob bar onto the small NowPlaying home card (mode C) — default no (the card stays controls-suppressed), flagged for Daniel.

---

4. The bridge, generalized (Wave 12.B)

The bridge (WaveformVisualizer.razor.cs, ex-MixWaveformVisualizer) needs one real change beyond the rename: its datum fetch must resolve the high-res datum for the current track, not for a Mix release.

Today: await ReleaseData.GetMixWaveform(ReleaseEntryKey) → resolves per-release, 404 for non-Mix → blank. This is the per-release fetch the model correction supersedes.

Generalized (per-track model). The visualizer renders the currently playing/selected track's waveform, and the bridge already knows that track — it is the TrackId it gates IsActivePlayer on. So the fetch should be keyed to the track, with the release as addressing context. Two shapes for the fetch are viable; the spec recommends the first and leaves the exact route to staff-engineer (§5):

• Track-keyed (recommended): await ReleaseData.GetTrackWaveform(trackEntryKey) → returns the per-track high-res datum from the generalized waveform vault, keyed by the track's EntryKey. This is the cleanest expression of "the datum is the track's." The bridge needs the current track's EntryKey; it currently carries TrackId (the SQL PK) — see §5 on reconciling TrackId → EntryKey.
• Release-addressed, track-resolved: GET api/release/{releaseEntryKey}/track/{trackId}/waveform — the release locates the track, the track owns the datum. Heavier route, but keeps the release as the addressing root the bridge already holds (ReleaseEntryKey). Use this if resolving TrackId → EntryKey client-side is awkward.

The bridge stays otherwise identical:

• Re-fetch key changes from release to track. The fetch-once guard must re-arm when the track changes, not (only) when the release changes — because on a multi-track Cut the release is fixed while the track scrolls. (Today's guard keys on _loadedReleaseKey == ReleaseEntryKey; under the per-track model it keys on the current track identity.) This is the one bridge subtlety the model correction introduces — and it is exactly the behavior the NowPlaying card already needs (§6c), so the two converge.
• Still derives duration from the cascaded player (PlayerDurationSeconds) — the duration source is the player, which already reflects the current track, so the time↔sample mapping is correct per-track for free.
• Still gates playback coupling on TrackId via IsActivePlayer.
• Still pushes the seven control dials, the datum, playback, and theme through the unchanged handle.

The PlaybackPosition composability fallback (the no-player-cascade path) stays as the documented escape hatch.

No open data question remains here — Direction B (committed, §5) means every track has a high-res datum, so the fetch always resolves to high-res. The open items the model created are operational, not design: the backfill (§8a-new) and the upload-time compute cost (§8b-new).

---

5. The datum source — Direction B, per-track (committed)

The visualizer renders a loudness datum + a duration. Daniel's model correction makes the datum per-track: every track carries its own high-res waveform datum; the release is just the host. And Daniel chose Direction B: compute that high-res datum for all media, not the 512-bucket fallback. Together these settle §5 — no remaining product call here; the work is a generalization + a backfill.

Datums in the system today:

Datum	Vault	Resolution	Who has it today	Keyed by
Per-track profile	waveform-profiles	512 buckets (fixed)	every track (computed at upload)	track EntryKey
High-res datum	mix-waveforms	~333 samples/sec (duration-derived)	Mix tracks only (CMS-triggered)	MixMetadata.WaveformEntryKey (= the mix track's EntryKey)

The 512-bucket profile already exists per-track and stays (the player-bar WaveformSeeker consumes it — untouched). The high-res datum is the one the lava visualizer wants, and today only Mix tracks have it. Direction B closes that gap per-track for every medium.

5a. The generalization (Direction B), end to end

Direction B is not just a new endpoint — under the per-track model it touches five surfaces:

1. Content compute path. Generalize the duration-derived high-res compute (WaveformProfileService + MixWaveformResolution) off its Mix-only framing so it computes a per-track high-res datum for any track from that track's audio. The algorithm is unchanged (the same ~333 samples/sec duration-derived model MixWaveformResolution already defines); only its applicability widens from "the mix track" to "any track." Store keyed by the track's EntryKey.
2. Store / vault. The high-res datum becomes per-track-cardinal. Either rename/repurpose the mix-waveforms vault to a medium-neutral track-waveforms (cleaner; consistent with the rename discipline) or keep the vault and drop the Mix-only key assumption — staff-engineer's call, but the name should stop saying "mix" once it holds every track's datum. MixMetadata.WaveformEntryKey is no longer the only pointer; the datum keys directly off the track's EntryKey (the same key the waveform-profiles profile uses).
3. Upload path. UnifiedTrackService.UploadAsync already computes the 512-bucket profile for every track at upload; add the per-track high-res compute alongside it so every new track gets its high-res datum at upload time, no CMS step required. (Cost flagged — §8b-new.)
4. CMS generate action. Generalize the Mix-only "generate waveform" trigger to any track — so a CMS operator can (re)generate a track's high-res datum on demand (the backfill mechanism, and the repair path if a compute fails at upload). This is the action that drives the backfill (§8a-new).
5. Backfill. Every existing track that predates Direction B has a 512-bucket profile but no high-res datum. Backfill computes the per-track high-res datum for all of them. This is a real operational step, Daniel-gated — see §8a-new (does it run as a one-shot migration/script, or as a CMS batch action over the generalized generate action?).

5b. The per-track datum fetch endpoint

Under the per-track model the fetch resolves a datum for a track, addressed with the release as context. Recommended shape: GET api/track/{trackEntryKey}/waveform (track-cardinal, on TrackController) returning the per-track high-res datum, 404 → graceful blank. This is the natural home once the datum is the track's, and it sits beside the existing per-track surfaces.

• Reconciling with the bridge's identifiers. The bridge today carries ReleaseEntryKey + TrackId (the SQL PK), not the track's EntryKey. The fetch needs the track's EntryKey. Two ways to bridge: (i) the player/track view-model the bridge already cascades exposes the current track's EntryKey (preferred — the player knows the track it loaded, and EntryKey is how audio is keyed), so the bridge reads CurrentTrack.EntryKey directly; or (ii) keep the release as the addressing root and resolve server-side — GET api/release/{releaseEntryKey}/track/{trackId}/waveform — if the client can't cleanly reach the track's EntryKey. Recommend (i); it makes the route track-cardinal and matches the datum's ownership. Final identifier plumbing is staff-engineer's, but the route should be track-cardinal.
• /mix/waveform fate. The Mix-gated GET api/release/{entryKey}/mix/waveform can be retired (folded into the track-cardinal fetch — the Mix's single track resolves through the same path) or kept as a thin delegate during transition. Staff-engineer's call; the spec's intent is one track-cardinal fetch.
• IReleaseDataService (or a track-cardinal ITrackDataService if cleaner) gains GetTrackWaveform( trackEntryKey); the bridge calls it.

The road not taken (one-line, per Daniel). A cheaper v1 — serve the existing 512-bucket per-track profile to non-Mix surfaces and skip new compute entirely ("Direction A") — was considered and declined in favor of uniform high-res. Recorded so the trade isn't relitigated: A was zero-compute but coarse for the lava; Daniel chose quality + uniformity over the cheaper road.

---

6. Overhauling the NowPlayingHero (Wave 12.D)

6a. What's there now

NowPlayingCard.razor shows the now-playing title/sub plus, when Player.IsLoaded, a waveform-bars div of 20 hardcoded <div class="waveform-bar"> elements, each with fixed --h-lo/--h-hi/--dur CSS custom properties driving a CSS keyframe bounce. It is purely synthetic — no audio data, no coupling to the actual signal; it bounces on a fixed loop whenever anything is loaded. This is the "stochastic bullshit."

6b. The rewire — mount the real engine, driven by live playback

Replace the waveform-bars block with a mounted <WaveformVisualizer> scoped to the card, driven by the live cascaded player:

• The NowPlaying card already cascades IStreamingPlayerService (it reads Player.CurrentTrack).
• Mount <WaveformVisualizer ReleaseEntryKey="@Player.CurrentTrack.Release?.EntryKey" TrackId="@Player.CurrentTrack.Id" /> — the same bridge, the same playback coupling. Because the card is inside the cascade, IsActivePlayer is true for whatever is actually playing, and the visualizer scrolls/animates to the real signal. When nothing is playing, it sits at its at-rest slice (the bridge already handles the no-active-player state → static), which replaces the waveform-placeholder.
• The datum comes from §5's per-track fetch keyed on the current track (CurrentTrack.EntryKey) — so the home card shows the real high-res waveform of whatever track the listener started, Mix or not. This is the cleanest illustration of the per-track model: the card has no "release" of its own to speak of; it follows the track, and the datum is the track's.

This is the payoff of the generalization: the NowPlaying card is just another host (mode C, §3f) of the same engine, pointed at "whatever track is playing right now." No NowPlaying-specific renderer, no fork — the DRY win the brief demands. And because the datum is per-track and every track now has a high-res datum (Direction B), the home card renders at full fidelity for any track, not just Mixes.

6c. Constraints specific to the NowPlaying context

• Live, not static. Unlike a single-track detail page, the NowPlaying card's track changes as playback advances. Under the per-track model (§4) the fetch-once guard re-arms on track change (not release change), so track-change → new per-track datum is handled — and this is the same guard change the per-track model already requires for a multi-track Cut (where the release is fixed but the track scrolls). The two converge on one behavior: re-fetch when the current track's identity changes. Verify the guard keys on the current track, not the release.
• Small surface, controls-suppressed by default. The card is a small hero panel, not a full-bleed page. Mount the visualizer controls-suppressed by default (no lava-lamp, no knob bar) and sized to the card, not position: fixed. Note this is now the exception, not the rule: under Daniel's §8b full-parity call the controls ride every Release Detail page (Mix, Cut, Session — §3d); the NowPlaying card is the one host that suppresses them by default, because a seven-knob tuning bar on a small home-card may be awkward. Whether full parity extends here too is the open sub-question, §8b-followup — the seam supports it either way (the controls are a separate component over shared state). Flagged for staff-engineer (§8d): the renderer's footer-clip + full-viewport assumptions (position: fixed; inset: 0, clip-to-footer) are written for a full-page backdrop; mounting it in a contained card needs the canvas to size to its container instead of the viewport. This is a real renderer-hosting wrinkle — the engine assumes full-window today. Either (i) parameterize the visualizer's sizing (full-viewport vs. fill-container), or (ii) the NowPlaying card is the forcing function to make the canvas container-relative. Recommend (i) — a Fill mode parameter — because it also future-proofs any contained mount (an embed, a CMS preview). This is the one genuine engineering subtlety in the NowPlaying rewire; everything else is composition.
• Performance. A WebGL2 lava render on the home page (the highest-traffic, first-paint surface) is a heavier ask than on a detail page the user navigated to deliberately. Keep the existing MAX_DPR = 2 cap and the isPlaying-gated rAF loop (it burns no frames when nothing plays — so an idle home page pays nothing). If the lava is too heavy for the home card specifically, the controls-suppressed ambient backdrop can run a cheaper preset (fewer blobs) via a density default — but do not fork the renderer; use the existing density dial. Flagged, not committed (§8d).

6d. What the card keeps

The title/sub text block (np-title/np-sub) and the "Now Playing" label stay — only the synthetic waveform-bars / waveform-placeholder block is replaced by the mounted visualizer. The pulsing circle-deco rings in NowPlaying.razor are unrelated decor; leave them.

---

7. Wave decomposition + dependency shape

Sequenced so the mechanical rename de-risks everything, the per-track high-res generalization (now the heaviest wave) unblocks the new hosts, and the NowPlaying rewire (the trickiest, per §6c) comes last on a proven engine. Direction B re-costs 12.B materially — it is no longer "a new endpoint" but a content + upload + CMS + backfill + fetch slice; the spec splits it into 12.B1 (compute generalization + backfill) and 12.B2 (the bridge's per-track fetch) so the heavy data work and the thin client rewire can be sequenced and tested apart.

• 12.A — Rename to the abstraction (mechanical, no behavior change). Mix* → Waveform* across the five files + the TS module + the import path + the DI registration (§3a). Load-bearing prerequisite — every later wave references the generalized names. Acceptance: Mix detail behaves identically; diff is identifiers only.
• 12.B1 — Generalize the high-res compute to every track + backfill (the data change, Direction B). Generalize the duration-derived compute off Mix-only (WaveformProfileService / MixWaveformResolution), store per-track keyed by EntryKey in the (renamed) track-waveforms vault, add the per-track high-res compute to UnifiedTrackService.UploadAsync, generalize the CMS generate action to any track, and run the backfill for existing tracks (§5a, §8a-new — backfill is Daniel-gated). Independent of 12.A (it is server/content-side, no renamed client identifiers). Acceptance: every track — Mix, Session, and each Cut track — has a high-res datum; new uploads get one automatically; the generate action works for any track.
• 12.B2 — Per-track datum fetch + bridge rewire. New track-cardinal GET api/track/{trackEntryKey}/waveform (§5b); GetTrackWaveform; bridge resolves the current track's EntryKey and re-fetches on track-change (§4). Depends on 12.A (renamed bridge) + 12.B1 (a datum to fetch). Acceptance: the Mix detail page renders the same high-res lava via the new track-cardinal fetch; a non-Mix track now returns a high-res datum.
• 12.C — Ambient slot on the scaffold + mount on detail pages (mode B, §3f). Promote the full-bleed/foreground/footer-clip pattern into ReleaseDetailScaffold as an optional Ambient slot (§3c); Cut mounts the ambient layer with the full seven-knob bar + lava-lamp toggle (full parity, §3d); Session mounts directly also full-parity (§3e). Mix is unchanged (mode A keeps its own mount + controls). Depends on 12.B2 (a datum to render). §8b is resolved (full parity, no longer gated) — Cut and Session ship with both the ambient layer and the controls. This wave also makes the state-scoping call (§3d note — recommend one shared WaveformVisualizerControlState). Acceptance: Mix unchanged; Cut and Session each show an ambient living layer with a working seven-knob bar + lava-lamp toggle, rendering the current track's datum, no regression to the hero/content.
• 12.D — NowPlayingHero rewire (mode C, §3f). Replace the synthetic bars with a contained, controls-suppressed <WaveformVisualizer> driven by the live player, pointed at the current track (§6); add the Fill/container-sizing mode (§6c). Depends on 12.A + 12.B2 (renamed engine + a per-track datum for whatever's playing). Independent of 12.C (different host; doesn't need the scaffold slot). Acceptance: the home card shows the real high-res waveform of the playing track and sits at-rest when nothing plays; no synthetic bars remain.

Dependency shape: 12.A → 12.B2 → (12.C ‖ 12.D), with 12.B1 a parallel server-side track that 12.B2 depends on (12.B1 → 12.B2) but that can start cold day one (it needs no renamed client identifiers). 12.A is the cheap mechanical unblock; 12.B1 is the new load-bearing heavy (compute + backfill); 12.B2 is the thin client rewire that consumes it; 12.C (detail-page ambient hosts, full-parity controls) and 12.D (NowPlaying host, controls-suppressed by default) are independent siblings off 12.B2. The cold-start items are 12.A (touches everything, risks nothing) and 12.B1 (the data work — start it early; the backfill gate is the only thing blocking it). With §8b resolved to full parity, 12.C no longer carries a mode-1 fallback branch — Cut and Session are in, with controls.

---

8. Open product decisions

Resolved by Daniel (2026-06-17), kept visible per file convention:

• §8a (was: non-Mix datum resolution) → Direction B. High-res compute for all media, not the 512-bucket fallback. The cheaper "Direction A" (serve the existing 512-bucket profile to non-Mix) is the road not taken (§5). Re-cost lands in 12.B1 (compute + backfill).
• §8c (was: multi-track Cut's waveform) → dissolved by the per-track model. The datum is per-track; the visualizer renders the current track's datum, so there is no release-level "which track represents the album" choice to make. The old "first track by TrackNumber" recommendation is moot.
• §8b (Cut/Session hosting + controls) → RESOLVED: all three modes live, FULL PARITY on controls. Daniel chose option (3) — full parity on the lava controls (over option (2) Mix-only controls): the visualizer rides every Release Detail host (Mix, Cut, Session) and the seven-knob bar + lava-lamp toggle ride all three, not just Mix. The three-hosting-mode layout framing (§3f — visualizer-is-the-page on Mix, ambient on Cut/Session, contained on NowPlaying) is retained; "backdrop" stays retired as the wrong word for Mix. The only thing the flip changed: the WaveformVisualizerControls mount is no longer Mix-suppressed on Cut/Session. The earlier mode-1 fallback (Mix + NowPlaying only) and the "controls Mix-only" default are both closed. One sub-question spun out — §8b-followup below.

Newly open (created by the full-parity flip and by Direction B + the per-track model):

§8b-followup — Do the full-parity controls extend onto the NowPlaying home card (mode C)? Daniel's §8b full-parity call (option 3) was answered against the Release Detail-page framing — Mix, Cut, and Session all get the seven-knob bar + lava-lamp toggle. The NowPlaying home card is a different host: the contained mode-C panel, a small hero card on the highest-traffic surface, not a full detail page. The spec applies full-parity controls to the three detail pages and keeps the NowPlaying card controls-suppressed by default (a living waveform readout with no knobs). Open: does Daniel want the seven-knob bar on the home card too, or does it stop at the detail pages? A seven-knob tuning bar on a small now-playing card may be awkward — it competes with the card's compact title/sub layout and puts an expert affordance on the landing surface — which is why the default is suppressed. But the seam supports it either way (the controls are a separate component over shared WaveformVisualizerControlState), so flipping the card to controls-on is a one-line composition change in 12.D, not an engine change. Recommend keeping the card controls-suppressed (full parity = detail pages; the home card stays a clean ambient readout) — but this is a Daniel call, surfaced not buried. Affects only 12.D's mount; everything else in the phase is settled by the full-parity resolution.

§8a-new — How does the high-res backfill run, and is it gated? Direction B means every existing track needs its per-track high-res datum computed once. Two shapes: (1) a one-shot migration/script run against the content store (like the Daniel-gated EF migrations in Phase 11 — authored, applied on Daniel's go-ahead); or (2) a CMS batch action over the generalized generate action (an operator triggers "generate all," visible progress, re-runnable for failures). Recommend (2) — it reuses the generalized generate action 12.B1 builds anyway, needs no separate one-shot tooling, and the CMS already has the generate-status surface (Phase 8 §8.2's in-grid status column + generate actions) to hang it on. This is a Daniel-gated operational step either way — like the Phase 11 release migrations, the backfill is authored in 12.B1 but run on Daniel's word. Open: which shape, and when it runs relative to shipping the per-track fetch (the fetch 404s gracefully for not-yet-backfilled tracks, so the fetch can ship before the backfill completes — the visualizer just blanks until a track is backfilled).

§8b-new — Per-track high-res compute at upload: perf + storage cost (flag for Daniel). Direction B adds a duration-derived high-res compute (~333 samples/sec) to every track upload, on top of the existing 512-bucket profile. Two costs to surface:

• Upload latency. The high-res compute walks the full audio at upload time. For a long Mix this is already paid (Mixes compute it today); for short Cut tracks it is small. But it is now on the upload hot path for every track, where before only the cheap 512-bucket profile was. If upload latency matters, the compute could be deferred (upload returns; high-res computes async/queued, the generate action the backfill uses doubling as the async worker) rather than inline. Recommend: inline for now (simplest; the 512-bucket compute is already inline and the high-res isn't dramatically heavier for typical tracks), flag deferral as the escape hatch if upload feels slow.
• Storage. A per-track high-res datum (~333 samples/sec × duration) is materially larger than the fixed 512-bucket profile, and now every track stores one (a multi-track Cut stores N of them). For an album of short tracks this is modest; for a library of long Sessions it adds up. Not a blocker — disk is cheap and the datum is loudness samples, not audio — but flagged so the storage growth from "every track gets a high-res datum" is a known consequence, not a surprise. No action recommended; surface only.

§8d — NowPlaying container-sizing + home-page performance (engineering subtleties, staff-engineer-owned but flag for Daniel). The renderer assumes full-viewport (position: fixed; inset: 0, clip-to-footer); the NowPlaying card (mode C, §3f) needs it container-relative (§6c) — recommend a Fill mode parameter. And a WebGL2 lava render on the home page's first paint is heavier than on a detail page — the isPlaying-gated rAF means an idle home page pays nothing, but a cheaper blob-density preset for the card is a fallback if needed. Neither blocks; both are tuning/hosting calls surfaced so Daniel isn't surprised by a lava lamp on the landing page.

---

9. Acceptance criteria (observable)

1. Rename clean. The engine is named for its abstraction (WaveformVisualizer*); the Mix detail page is visually and behaviorally identical to before the rename.
2. Per-track high-res datum everywhere (Direction B). Every track — Mix, Session, and each track of a Cut — has a high-res duration-derived datum keyed by its EntryKey; new uploads get one automatically; the generalized CMS generate action produces one for any track; the backfill has populated all pre-existing tracks.
3. Track-cardinal fetch. GET api/track/{trackEntryKey}/waveform (or the agreed track-cardinal route) returns the current track's high-res datum, 404 → graceful blank. The bridge resolves the current track and re-fetches on track change.
4. Mix unchanged (mode A). The Mix detail page still renders the high-res lava with the seven-knob bar + lava-lamp toggle, visualizer-is-the-page, at parity with the Phase 10 reframe — now via the track-cardinal fetch.
5. Ambient + controls on Cut/Session (mode B, full parity). A Cut and a Session detail page show an ambient living waveform layer rendering the currently selected/playing track's datum, with a working seven-knob bar + lava-lamp toggle (full parity — controls are present and tunable in place, not suppressed), with no regression to the hero/content.
6. NowPlaying is real (mode C), controls-suppressed by default. The home NowPlaying card shows the actual high-res waveform of the playing track (scrolls/animates to the real signal, changes with track changes), sits at-rest when nothing plays, and mounts controls-suppressed by default (no knob bar, no lava-lamp — pending §8b-followup). No hardcoded synthetic bars remain.
7. One engine, three modes. Mix (mode A), the Cut/Session ambient layer (mode B), and the NowPlaying card (mode C) all consume the same WaveformVisualizer component + renderer + state — verified by there being exactly one of each, no per-host fork; the differences are hosting composition only (full-bleed vs. Ambient slot vs. contained; viewport- vs. container-sized; controls present on all three detail hosts, suppressed-by-default on the contained home card).
8. Read-only everywhere. No host (including the NowPlaying card) exposes a seek/scrub/transport via the visualizer; the read-only contract holds on every mount.
9. Bridge intact, re-keyed to track. Single-owner handle, idempotent datum guard, IsActivePlayer gating, and the isPlaying-gated rAF loop are unchanged across all mounts; the datum guard now re-arms on track change (the multi-track Cut and the NowPlaying card both rely on this — they converge).