deepdrft/PLAN-level-meter-fab.md

# PLAN — LevelMeterFab

Product spec for a new self-contained Blazor control in `DeepDrftPublic.Client`. This document is decision-grade: a developer should be able to implement it without further design questions. Once landed, the implemented points move to `COMPLETED.md` per the project convention.

---

## 1. Component identity

- **Name:** `LevelMeterFab`
- **Files:**
  - `DeepDrftPublic.Client/Controls/AudioPlayerBar/LevelMeterFab.razor`
  - `DeepDrftPublic.Client/Controls/AudioPlayerBar/LevelMeterFab.razor.cs`
  - `DeepDrftPublic.Client/Controls/AudioPlayerBar/LevelMeterFab.razor.css`
- **Purpose:** A floating-action button that replaces the static music-note FAB in the minimized player dock and tints its icon by live output level (green / yellow / orange) while a track plays, reverting to a static untinted icon when idle.

It is a drop-in replacement for the existing `<MudFab>` in the `_isMinimized` branch of `AudioPlayerBar.razor`. It owns its own level subscription and lifecycle; the parent bar only supplies the click handler.

---

## 2. Level-data pipeline

**Decision: reduce the existing spectrum callback array to a single dB value on the C# side. No new TypeScript surface for v1.**

### Rationale

`SpectrumAnalyzer` already broadcasts normalized 0–1 bucket arrays to all subscribers at ~30fps via `addCallback`, and `AudioInteropService.StartSpectrumAnimationAsync` / `StopSpectrumAnimationAsync` already expose this to C# with per-subscriber callback IDs (multiple subscribers per player are supported — `SpectrumVisualizer` and `LevelMeterFab` can both attach to the same player without conflict). Reusing this path means:

- Zero changes to `SpectrumAnalyzer.ts`, `AudioPlayer.ts`, or `index.ts`.
- Zero new interop methods on `AudioInteropService.cs`.
- Identical subscribe/animate/unsubscribe lifecycle to the already-proven `SpectrumVisualizer`, so the seam is well-trodden.

The cost: the spectrum buckets are perceptually log-mapped, filtered (high-pass / low-pass / slope), and already normalized into 0–1 against a fixed −80..0 dB window. Reducing them back to a dB figure is **an approximation of program loudness, not a faithful RMS of the output bus.** For a three-band FAB tint (a coarse "is it quiet / loud / hot" indicator), this is entirely sufficient — the eye reads three colors, not a calibrated meter. We are not building a mastering tool; we are tinting an icon.

### C#-side reduction

The callback delivers `double[]` buckets, each in 0–1 where `value = (clampedDb + 80) / 80` (from `SpectrumAnalyzer.getFrequencyData`). To get a representative level:

1. Take the **peak** bucket value across the array (peak reads more responsively than mean for a "hot signal" indicator; mean would feel sluggish and never reach the orange band on transient-heavy electronic material).
2. Convert back to dB: `db = peak * 80 - 80` (inverse of the normalization). Range is −80..0 dB.
3. Apply a short **attack-fast / release-slow** smoothing on the dB value so the color does not strobe at 30fps (see §4).

Band thresholds operate on this reconstructed dB:

| Reconstructed dB | Band |
|---|---|
| ≤ −18 dB | green |
| −18 to −6 dB | yellow |
| > −6 dB | orange |

These thresholds are the spec's contract; if the reconstructed scale reads systematically low against listening tests, the implementer may apply a single fixed offset constant (documented in code) rather than re-deriving the math — keep the three boundaries' *spacing* intact.

### Noted upgrade path (NOT in v1 scope)

If a faithful meter is ever wanted (e.g. for a future expanded-player VU meter), add `getLevelDb(playerId: number): number` to `AudioPlayer` / `index.ts` that reads `AnalyserNode.getFloatTimeDomainData` and computes true RMS over the time-domain samples, exposed via a new `AudioInteropService.GetLevelDbAsync`. Deferred deliberately: it adds TS surface and a second animation path for no v1 benefit. Captured here so the seam is known, not built. This aligns with "one source, multiple views" — a future VU meter and this FAB should consume the *same* level signal, so when that day comes, prefer adding `getLevelDb` and migrating *both* consumers rather than letting them diverge.

---

## 3. Color mapping

The FAB background is `Color.Primary`, which is **navy `#17283f` on light** and **green `#3D7A68` on dark** (per `DeepDrftPalettes`). The tint colors must read as punchy signal-meter colors against *both* grounds, so they are defined as fixed, theme-independent hues with enough luminance to pop on navy and enough saturation to separate from the green dark-mode ground.

Note: the root `CLAUDE.md` still references a retired "Charleston in the Day / Lowcountry Summer Nights" palette; the live palette is the navy/green `DeepDrftPalettes`. Ground all color decisions in `DeepDrftPalettes`, not the stale doc. (Flagged for doc-keeper — out of this spec's scope to fix.)

| Band | Color | Hex | Notes |
|---|---|---|---|
| green | vivid spring green | `#2ECC71` | Reads clearly on navy and separates from the `#3D7A68` dark ground by being brighter and more saturated. |
| yellow | warm amber-yellow | `#F4C430` | Saffron — punchy on both grounds, not the muddy pure `#FFFF00`. |
| orange | hot signal orange | `#FF6B35` | Reads as "hot / near clip" without being literal red. |
| idle | inherit FAB foreground | `currentColor` | No tint; icon uses MudFab's default `Color.Primary` contrast text (see §4). |

These are exposed as CSS custom properties in `LevelMeterFab.razor.css` (`--lmf-green`, `--lmf-yellow`, `--lmf-orange`) so they can be retuned in one place. The component sets a band class (`lmf-green` / `lmf-yellow` / `lmf-orange` / no class) on the icon element; the CSS maps each class to the corresponding variable via `color`.

A subtle `text-shadow`/glow (`0 0 6px` of the active band color at low alpha) is permitted to lift the tint off the FAB ground — optional polish, not required for acceptance.

---

## 4. Animation behavior

### Idle (no track loaded, or paused/stopped)

- **Static, full-opacity, untinted** music-note icon (default FAB foreground color). Not dimmed, not hidden — the dock must remain a clear, tappable affordance to reopen the player even when nothing is playing.
- The component is not subscribed to the level callback while idle (no animation cost when nothing plays).

### Active (track playing)

- Subscribed to the level callback; icon color reflects the current band.
- **Color transitions are eased, not snapped.** A snap at 30fps strobes harshly on transient-heavy material. Apply:
  - **dB smoothing (C# side):** attack-fast, release-slow envelope on the reconstructed dB before banding — e.g. on each frame, if new dB > current, jump most of the way (attack coefficient ~0.6); if lower, ease down slowly (release coefficient ~0.15). This prevents flicker between adjacent bands on every kick drum while still feeling responsive.
  - **CSS transition (render side):** `transition: color 120ms ease-out` on the icon so even a band change glides rather than cuts.
- Net effect: the icon "breathes" through green → yellow → orange and settles, rather than buzzing.

### Transitions between states

- Play starts → subscribe, begin tinting from green (lowest band) and rise.
- Pause/stop/track-end → unsubscribe, CSS-transition back to idle untinted over the same 120ms.
- Track change while playing → stays subscribed; level simply tracks the new stream (the player id is stable across track changes).

The driving state signal is `IStreamingPlayerService.IsPlaying`, observed via the `StateChanged` multicast event — identical to how `SpectrumVisualizer` decides when to animate. **Reuse that exact pattern** (subscribe in `OnParametersSetAsync` with a reference guard, resubscribe-safe, start/stop the level animation off `IsPlaying`).

---

## 5. Component interface

```csharp
public partial class LevelMeterFab : ComponentBase, IAsyncDisposable
{
    [Inject] public required AudioInteropService AudioInterop { get; set; }
    [CascadingParameter] public IStreamingPlayerService? PlayerService { get; set; }

    [Parameter] public EventCallback OnClick { get; set; }
    [Parameter] public Size Size { get; set; } = Size.Large;
    [Parameter] public Color Color { get; set; } = Color.Primary;
}
```

- **Player access: cascade, not inject** — matches `SpectrumVisualizer` and `AudioPlayerBar`. The player id is read from `PlayerService as AudioPlayerService` → `.PlayerId`, exactly as `SpectrumVisualizer` does (`if (PlayerService is AudioPlayerService baseService) _playerId = baseService.PlayerId;`).
- `OnClick` — forwarded to the rendered `<MudFab OnClick>`. The parent passes its existing `ToggleMinimized` handler. The component does **not** know about minimize state; it only relays the click.
- `Size` / `Color` — passed through to `<MudFab>` so the FAB keeps its current `Size.Large` / `Color.Primary` look without the parent hardcoding inside the control. Defaults match today's markup, so the swap is visually identical at idle.
- Owns its own `_instanceId = Guid.NewGuid().ToString()` for the spectrum callback id, its own `_isAnimating` guard, and unsubscribes in `DisposeAsync`. Copy the subscribe/unsubscribe/`StateChanged` lifecycle from `SpectrumVisualizer` verbatim in shape.

---

## 6. Integration point

In `DeepDrftPublic.Client/Controls/AudioPlayerBar/AudioPlayerBar.razor`, replace the `_isMinimized` branch:

```razor
@* before *@
@if (_isMinimized)
{
    <div class="minimized-dock">
        <MudFab Color="Color.Primary"
                StartIcon="@Icons.Material.Filled.MusicNote"
                Size="Size.Large"
                OnClick="@ToggleMinimized"/>
    </div>
}

@* after *@
@if (_isMinimized)
{
    <div class="minimized-dock">
        <LevelMeterFab Size="Size.Large"
                       Color="Color.Primary"
                       OnClick="@ToggleMinimized" />
    </div>
}
```

- `LevelMeterFab` reads `PlayerService` from the same cascade `AudioPlayerBar` already lives under (`AudioPlayerProvider`), so no extra wiring is needed in the parent.
- The music-note icon is owned **inside** `LevelMeterFab` (it renders its own `<MudFab StartIcon="@Icons.Material.Filled.MusicNote">`), so the parent no longer specifies the glyph.
- No `.razor.cs` change to `AudioPlayerBar` is required — `ToggleMinimized` already exists and is passed as the callback.

---

## 7. TypeScript changes

**None for v1.** The existing `startSpectrumAnimation` / `stopSpectrumAnimation` surface on `index.ts` and the multi-subscriber `SpectrumAnalyzer.addCallback` already support a second concurrent subscriber on the same player. Confirmed: `SpectrumAnalyzer.callbacks` is a `Map<string, ...>` keyed by callback id and broadcasts to all entries.

Deferred (documented in §2, not implemented):
```ts
// AudioPlayer.ts  — only if a faithful meter is later needed
getLevelDb(): number  // true RMS over getFloatTimeDomainData, returns dBFS
// index.ts
getLevelDb: (playerId: string): number => audioPlayers.get(playerId)?.getLevelDb() ?? -Infinity
```

---

## 8. C# interop changes

**None.** `LevelMeterFab` calls the existing:
- `AudioInterop.StartSpectrumAnimationAsync(playerId, instanceId, OnLevelData)`
- `AudioInterop.StopSpectrumAnimationAsync(playerId, instanceId)`

`OnLevelData(double[] buckets)` is the component-local callback that performs the §2 reduction (peak → dB → smoothing → band) and calls `StateHasChanged` when the band changes.

Deferred (only if §7's `getLevelDb` is ever built): `AudioInteropService.GetLevelDbAsync(string playerId)` wrapping `DeepDrftAudio.getLevelDb`. Not in v1.

---

## 9. Acceptance criteria

1. When the player is minimized and **no track is loaded**, the dock shows a static, full-opacity, untinted music-note FAB identical in size/position to today's. Clicking it expands the player.
2. When the player is minimized and a track is **playing**, the music-note icon is tinted, and the tint changes between green / yellow / orange as the track's level moves through the bands.
3. Band mapping holds: sustained quiet passages read green (≤ −18 dB reconstructed), moderate read yellow (−18 to −6 dB), loud/hot passages read orange (> −6 dB).
4. Color changes are smooth (no per-frame strobing): adjacent-band flicker on percussive transients is visibly damped, and band changes glide over ~120ms rather than snapping.
5. **Pausing** the track transitions the icon back to the idle untinted state within ~120ms; **resuming** re-engages tinting.
6. Track-end and stop both return the icon to idle untinted.
7. Changing tracks while playing keeps the meter live against the new stream with no re-subscription glitch.
8. Clicking the FAB in any state expands the player (the `OnClick` → `ToggleMinimized` path is unchanged).
9. No new TypeScript or `AudioInteropService` methods are introduced; the component reuses `StartSpectrumAnimationAsync` / `StopSpectrumAnimationAsync`.
10. `LevelMeterFab` and `SpectrumVisualizer` can be mounted against the same player simultaneously without one starving the other's callbacks (verify by expanding the bar — both the spectrum bars and, on a return to minimized, the FAB tint, animate correctly).
11. On dispose / navigation teardown, the component unsubscribes its spectrum callback (no leaked `DotNetObjectReference`, no orphaned animation frame).
12. The tint colors are legible against both the light (navy) and dark (green) `Color.Primary` FAB grounds.

---

## Open questions

None blocking. One judgment call left to the implementer: the exact attack/release smoothing coefficients and any fixed dB offset (§2) are tuning values — pick by ear against a few representative tracks; the three band *boundaries* and their spacing are the fixed contract.