From 9cfcd5f67a94ec183232a4a3c3696f54445ed053 Mon Sep 17 00:00:00 2001 From: daniel-c-harvey Date: Fri, 5 Jun 2026 16:58:38 -0400 Subject: [PATCH] docs: log WaveformSeeker W1-T2 completion in COMPLETED.md --- COMPLETED.md | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/COMPLETED.md b/COMPLETED.md index a6ed56a..7c35d21 100644 --- a/COMPLETED.md +++ b/COMPLETED.md @@ -8,7 +8,7 @@ Newest entries at the top. Group by phase/wave header (mirroring `PLAN.md` / `CM ## WaveformSeeker Wave 1 — Loudness profile + layout refactor -**Status:** W1-T1 (backend loudness computation) and W1-T3 (player layout refactor) landed on 2026-06-05. +**Status:** W1-T1 (backend loudness computation), W1-T2 (HTTP transport), and W1-T3 (player layout refactor) landed on 2026-06-05. ### W1-T1 — Backend waveform loudness profiling @@ -37,6 +37,33 @@ Implemented Phase 1 of the WaveformSeeker feature (`product-notes/spectrum-seeke - No external audio-processing dependency pulled in for RMS — reuses existing PCM parser from `AudioProcessor`. - Cost: one linear pass over PCM buffer at upload (few hundred ms for typical WAV); never on playback path. +### W1-T2 — Waveform profile HTTP transport + +**Landed 2026-06-05.** + +Implemented Phase 2 of the WaveformSeeker feature: HTTP transport layer for waveform profile data from backend to client, enabling client-side display of loudness profiles in future seeking UI. + +**API endpoint (`DeepDrftAPI`):** +- New `GET api/track/{trackId}/waveform` endpoint — unauthenticated, returns `WaveformProfileDto` (base64-encoded quantized bytes + `BucketCount`) on success, 404 if track or profile not found. +- Leverages existing `WaveformProfileService` to load profile from vault on demand. +- No authentication required — mirrors `GET api/track/{id}` streaming policy (public audio access). + +**Proxy forward (`DeepDrftPublic`):** +- Thin buffered forward in `TrackProxyController` — proxies request from client to `DeepDrftAPI` waveform endpoint with same path parameters. +- Preserves error semantics: 404 from API passes through to client; network errors surface as HTTP errors. + +**HTTP client (`DeepDrftPublic.Client`):** +- New `TrackMediaClient.GetWaveformProfileAsync(trackId, cancellationToken)` method on the content HTTP client. +- 404 response maps to `Result.Failure` (fail-result signal for WaveformSeeker to render flat fallback). +- Network/timeout errors map to separate `Result.Failure` with distinct code. +- Callsite can discriminate via result error code whether to retry (transient) or render fallback (not found). + +**Architecture notes:** +- Transport layer is independent of loudness algorithm (W1-T1) — client receives opaque quantized bytes; future algorithm changes on backend do not affect wire format, as long as `BucketCount` is included. +- HTTP caching via ETag/Last-Modified is deferred to Phase 2 optimization work. +- Profile loading from vault is on-demand (not pre-cached in memory) — load cost amortizes across all requests to the same track. +- 404 handling unambiguous: client renders flat fallback, distinguishing "track has no profile" from "track not found" via error code. + ### W1-T3 — Player layout refactor (SpectrumVisualizer relocation + VolumeZone rename) **Landed 2026-06-05.**