feat(waveform): precompute and store peaks in DB for instant rendering

Store waveform peaks inline in audio_versions (JSONB columns) so WaveSurfer
can render the waveform immediately on page load without waiting for audio
decode. Adds a 100-point mini-waveform for version selector thumbnails.

Backend:
- Migration 0006: adds waveform_peaks and waveform_peaks_mini JSONB columns
- Worker generates both resolutions (500-pt full, 100-pt mini) during transcode
  and stores them directly in DB — replaces file-based waveform_url approach
- AudioVersionRead schema exposes both fields inline (no extra HTTP round-trip)
- GET /versions/{id}/waveform reads from DB; adds ?resolution=mini support

Frontend:
- audioService.initialize() accepts peaks and calls ws.load(url, Float32Array)
  so waveform renders instantly without audio decode
- useWaveform hook threads peaks option through to audioService
- PlayerPanel passes waveform_peaks from the active version to the hook
- New MiniWaveform SVG component (no WaveSurfer) renders mini peaks in the
  version selector buttons

Fix: docker-compose.dev.yml now runs alembic upgrade head before starting
the API server, so a fresh volume gets the full schema automatically.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

web/src/components/MiniWaveform.test.tsx

@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+import { render } from "@testing-library/react";
+import { MiniWaveform } from "./MiniWaveform";
+
+describe("MiniWaveform", () => {
+  it("renders an SVG element", () => {
+    const peaks = Array.from({ length: 100 }, (_, i) => i / 100);
+    const { container } = render(<MiniWaveform peaks={peaks} width={120} height={32} />);
+    const svg = container.querySelector("svg");
+    expect(svg).not.toBeNull();
+  });
+
+  it("renders the correct number of bars matching peaks length", () => {
+    const peaks = Array.from({ length: 100 }, (_, i) => i / 100);
+    const { container } = render(<MiniWaveform peaks={peaks} width={120} height={32} />);
+    const rects = container.querySelectorAll("rect");
+    expect(rects.length).toBe(100);
+  });
+
+  it("renders a placeholder when peaks is null", () => {
+    const { container } = render(<MiniWaveform peaks={null} width={120} height={32} />);
+    const svg = container.querySelector("svg");
+    expect(svg).not.toBeNull();
+    // With null peaks, no bars — just the placeholder rect
+    const rects = container.querySelectorAll("rect");
+    expect(rects.length).toBe(1); // single placeholder bar
+  });
+
+  it("renders a placeholder when peaks is empty array", () => {
+    const { container } = render(<MiniWaveform peaks={[]} width={120} height={32} />);
+    const rects = container.querySelectorAll("rect");
+    expect(rects.length).toBe(1);
+  });
+
+  it("applies correct SVG dimensions", () => {
+    const peaks = [0.5, 0.5];
+    const { container } = render(<MiniWaveform peaks={peaks} width={200} height={48} />);
+    const svg = container.querySelector("svg");
+    expect(svg?.getAttribute("width")).toBe("200");
+    expect(svg?.getAttribute("height")).toBe("48");
+  });
+
+  it("uses the provided color for bars", () => {
+    const peaks = [0.5, 0.5];
+    const { container } = render(
+      <MiniWaveform peaks={peaks} width={100} height={32} color="#ff0000" />
+    );
+    const rect = container.querySelector("rect");
+    expect(rect?.getAttribute("fill")).toBe("#ff0000");
+  });
+});

web/src/components/MiniWaveform.tsx

@@ -0,0 +1,62 @@
+/**
+ * MiniWaveform — pure SVG component for rendering waveform_peaks_mini.
+ *
+ * Renders pre-computed 100-point peaks as vertical bars. No WaveSurfer dependency —
+ * lightweight enough to use in library/song list views for every song card.
+ *
+ * Props:
+ *   peaks   — array of 0-1 normalized peak values (ideally 100 points), or null
+ *   width   — SVG width in px
+ *   height  — SVG height in px
+ *   color   — bar fill color (default: teal accent)
+ */
+
+interface MiniWaveformProps {
+  peaks: number[] | null;
+  width: number;
+  height: number;
+  color?: string;
+}
+
+export function MiniWaveform({
+  peaks,
+  width,
+  height,
+  color = "#14b8a6",
+}: MiniWaveformProps) {
+  const isEmpty = !peaks || peaks.length === 0;
+
+  if (isEmpty) {
+    return (
+      <svg width={width} height={height} viewBox={`0 0 ${width} ${height}`} aria-hidden="true">
+        <rect x={0} y={0} width={width} height={height} fill="rgba(255,255,255,0.06)" rx={2} />
+      </svg>
+    );
+  }
+
+  const barCount = peaks.length;
+  const gap = 1;
+  const barWidth = Math.max(1, (width - gap * (barCount - 1)) / barCount);
+  const midY = height / 2;
+
+  return (
+    <svg width={width} height={height} viewBox={`0 0 ${width} ${height}`} aria-hidden="true">
+      {peaks.map((peak, i) => {
+        const barHeight = Math.max(1, peak * height);
+        const x = i * (barWidth + gap);
+        const y = midY - barHeight / 2;
+        return (
+          <rect
+            key={i}
+            x={x}
+            y={y}
+            width={barWidth}
+            height={barHeight}
+            fill={color}
+            rx={0.5}
+          />
+        );
+      })}
+    </svg>
+  );
+}

web/src/components/PlayerPanel.tsx

@@ -4,6 +4,7 @@ import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
 import { api } from "../api/client";
 import type { MemberRead } from "../api/auth";
 import { useWaveform } from "../hooks/useWaveform";
+import { MiniWaveform } from "./MiniWaveform";
 
 // ── Types ─────────────────────────────────────────────────────────────────────
 
@@ -24,6 +25,8 @@ interface SongVersion {
   version_number: number;
   label: string | null;
   analysis_status: string;
+  waveform_peaks: number[] | null;
+  waveform_peaks_mini: number[] | null;
 }
 
 interface SongComment {
@@ -214,12 +217,14 @@ export function PlayerPanel({ songId, bandId, onBack }: PlayerPanelProps) {
   });
 
   const activeVersion = selectedVersionId ?? versions?.[0]?.id ?? null;
+  const activeVersionData = versions?.find((v) => v.id === activeVersion) ?? versions?.[0] ?? null;
 
   // ── Waveform ──────────────────────────────────────────────────────────────
 
   const { isPlaying, isReady, currentTime, duration, play, pause, seekTo, error } = useWaveform(waveformRef, {
     url: activeVersion ? `/api/v1/versions/${activeVersion}/stream` : null,
-    peaksUrl: activeVersion ? `/api/v1/versions/${activeVersion}/waveform` : null,
+    peaksUrl: null,
+    peaks: activeVersionData?.waveform_peaks ?? null,
     songId,
     bandId,
   });
@@ -304,7 +309,15 @@ export function PlayerPanel({ songId, bandId, onBack }: PlayerPanelProps) {
           <div style={{ display: "flex", gap: 4, flexShrink: 0 }}>
             {versions.map((v) => (
               <button key={v.id} onClick={() => setSelectedVersionId(v.id)}
-                style={{ background: v.id === activeVersion ? "rgba(20,184,166,0.12)" : "transparent", border: `1px solid ${v.id === activeVersion ? "rgba(20,184,166,0.3)" : "rgba(255,255,255,0.09)"}`, borderRadius: 6, padding: "4px 10px", color: v.id === activeVersion ? "#2dd4bf" : "rgba(232,233,240,0.38)", cursor: "pointer", fontSize: 11, fontFamily: "monospace" }}>
+                style={{ background: v.id === activeVersion ? "rgba(20,184,166,0.12)" : "transparent", border: `1px solid ${v.id === activeVersion ? "rgba(20,184,166,0.3)" : "rgba(255,255,255,0.09)"}`, borderRadius: 6, padding: "4px 10px", color: v.id === activeVersion ? "#2dd4bf" : "rgba(232,233,240,0.38)", cursor: "pointer", fontSize: 11, fontFamily: "monospace", display: "flex", alignItems: "center", gap: 6 }}>
+                {v.waveform_peaks_mini && (
+                  <MiniWaveform
+                    peaks={v.waveform_peaks_mini}
+                    width={32}
+                    height={16}
+                    color={v.id === activeVersion ? "#2dd4bf" : "rgba(232,233,240,0.25)"}
+                  />
+                )}
                 v{v.version_number}{v.label ? ` · ${v.label}` : ""}
               </button>
             ))}

web/src/hooks/useWaveform.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import type { RefObject } from "react";
+
+// ── Hoist mocks so they're available in vi.mock factories ─────────────────────
+
+const { audioServiceMock } = vi.hoisted(() => ({
+  audioServiceMock: {
+    initialize: vi.fn().mockResolvedValue(undefined),
+    play: vi.fn().mockResolvedValue(undefined),
+    pause: vi.fn(),
+    seekTo: vi.fn(),
+    getDuration: vi.fn(() => 0),
+    isWaveformReady: vi.fn(() => false),
+  },
+}));
+
+vi.mock("../services/audioService", () => ({
+  audioService: audioServiceMock,
+}));
+
+vi.mock("../stores/playerStore", () => ({
+  usePlayerStore: vi.fn((selector: (s: unknown) => unknown) =>
+    selector({ isPlaying: false, currentTime: 0, duration: 0 })
+  ),
+}));
+
+// ── Import after mocks ─────────────────────────────────────────────────────────
+
+import { useWaveform } from "./useWaveform";
+
+// ── Tests ──────────────────────────────────────────────────────────────────────
+
+describe("useWaveform", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    audioServiceMock.initialize.mockResolvedValue(undefined);
+  });
+
+  it("forwards peaks to audioService.initialize when provided", async () => {
+    const containerRef: RefObject<HTMLDivElement> = {
+      current: document.createElement("div"),
+    };
+    const peaks = Array.from({ length: 500 }, (_, i) => i / 500);
+
+    renderHook(() =>
+      useWaveform(containerRef, {
+        url: "http://localhost/song.mp3",
+        peaksUrl: null,
+        peaks,
+        songId: "song-1",
+        bandId: "band-1",
+      })
+    );
+
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 0));
+    });
+
+    expect(audioServiceMock.initialize).toHaveBeenCalledOnce();
+    const [, , passedPeaks] = audioServiceMock.initialize.mock.calls[0];
+    expect(passedPeaks).toEqual(peaks);
+  });
+
+  it("passes undefined when no peaks provided", async () => {
+    const containerRef: RefObject<HTMLDivElement> = {
+      current: document.createElement("div"),
+    };
+
+    renderHook(() =>
+      useWaveform(containerRef, {
+        url: "http://localhost/song.mp3",
+        peaksUrl: null,
+        songId: "song-1",
+        bandId: "band-1",
+      })
+    );
+
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 0));
+    });
+
+    expect(audioServiceMock.initialize).toHaveBeenCalledOnce();
+    const [, , passedPeaks] = audioServiceMock.initialize.mock.calls[0];
+    expect(passedPeaks).toBeUndefined();
+  });
+});

web/src/hooks/useWaveform.ts

@@ -5,6 +5,7 @@ import { usePlayerStore } from "../stores/playerStore";
 export interface UseWaveformOptions {
   url: string | null;
   peaksUrl: string | null;
+  peaks?: number[] | null;
   onReady?: (duration: number) => void;
   onTimeUpdate?: (currentTime: number) => void;
   songId?: string | null;
@@ -39,7 +40,7 @@ export function useWaveform(
 
     const initializeAudio = async () => {
       try {
-        await audioService.initialize(containerRef.current!, options.url!);
+        await audioService.initialize(containerRef.current!, options.url!, options.peaks ?? undefined);
 
         // Restore playback if this song was already playing when the page loaded.
         // Read as a one-time snapshot — these values must NOT be reactive deps or

web/src/services/audioService.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { AudioService } from "./audioService";
+
+// ── WaveSurfer mock ────────────────────────────────────────────────────────────
+
+const mockLoad = vi.fn();
+const mockOn = vi.fn();
+const mockUnAll = vi.fn();
+const mockDestroy = vi.fn();
+const mockGetDuration = vi.fn(() => 180);
+const mockSetOptions = vi.fn();
+const mockCreate = vi.fn();
+
+vi.mock("wavesurfer.js", () => ({
+  default: {
+    create: (opts: unknown) => {
+      mockCreate(opts);
+      return {
+        load: mockLoad,
+        on: mockOn,
+        unAll: mockUnAll,
+        destroy: mockDestroy,
+        getDuration: mockGetDuration,
+        setOptions: mockSetOptions,
+        isPlaying: vi.fn(() => false),
+      };
+    },
+  },
+}));
+
+// ── Zustand store mock ─────────────────────────────────────────────────────────
+
+vi.mock("../stores/playerStore", () => ({
+  usePlayerStore: {
+    getState: vi.fn(() => ({
+      isPlaying: false,
+      currentTime: 0,
+      duration: 0,
+      currentSongId: null,
+      currentBandId: null,
+      batchUpdate: vi.fn(),
+      setDuration: vi.fn(),
+      setCurrentSong: vi.fn(),
+    })),
+    subscribe: vi.fn(),
+  },
+}));
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+function makeContainer(): HTMLDivElement {
+  return document.createElement("div");
+}
+
+function triggerWaveSurferReady() {
+  // WaveSurfer fires the "ready" event via ws.on("ready", cb)
+  const readyCb = mockOn.mock.calls.find(([event]) => event === "ready")?.[1];
+  readyCb?.();
+}
+
+// ── Tests ──────────────────────────────────────────────────────────────────────
+
+describe("AudioService.initialize()", () => {
+  let service: AudioService;
+
+  beforeEach(() => {
+    AudioService.resetInstance();
+    service = AudioService.getInstance();
+    vi.clearAllMocks();
+    mockGetDuration.mockReturnValue(180);
+  });
+
+  afterEach(() => {
+    AudioService.resetInstance();
+  });
+
+  it("calls ws.load(url) without peaks when no peaks provided", async () => {
+    const container = makeContainer();
+    const url = "http://localhost/audio/song.mp3";
+
+    const initPromise = service.initialize(container, url);
+    triggerWaveSurferReady();
+    await initPromise;
+
+    expect(mockLoad).toHaveBeenCalledOnce();
+    const [calledUrl, calledPeaks] = mockLoad.mock.calls[0];
+    expect(calledUrl).toBe(url);
+    expect(calledPeaks).toBeUndefined();
+  });
+
+  it("calls ws.load(url, [Float32Array]) when peaks are provided", async () => {
+    const container = makeContainer();
+    const url = "http://localhost/audio/song.mp3";
+    const peaks = Array.from({ length: 500 }, (_, i) => i / 500);
+
+    const initPromise = service.initialize(container, url, peaks);
+    triggerWaveSurferReady();
+    await initPromise;
+
+    expect(mockLoad).toHaveBeenCalledOnce();
+    const [calledUrl, calledChannelData] = mockLoad.mock.calls[0];
+    expect(calledUrl).toBe(url);
+    expect(calledChannelData).toHaveLength(1);
+    expect(calledChannelData[0]).toBeInstanceOf(Float32Array);
+    expect(calledChannelData[0]).toHaveLength(500);
+    expect(calledChannelData[0][0]).toBeCloseTo(0);
+    expect(calledChannelData[0][499]).toBeCloseTo(499 / 500);
+  });
+
+  it("does not re-initialize for the same url and container", async () => {
+    const container = makeContainer();
+    const url = "http://localhost/audio/song.mp3";
+    const peaks = [0.5, 0.5, 0.5];
+
+    const p1 = service.initialize(container, url, peaks);
+    triggerWaveSurferReady();
+    await p1;
+
+    vi.clearAllMocks();
+
+    // Second call with same URL + container: should no-op
+    await service.initialize(container, url, peaks);
+    expect(mockLoad).not.toHaveBeenCalled();
+  });
+});

web/src/services/audioService.ts

@@ -41,7 +41,7 @@ class AudioService {
     return el;
   }
 
-  public async initialize(container: HTMLElement, url: string): Promise<void> {
+  public async initialize(container: HTMLElement, url: string, peaks?: number[] | null): Promise<void> {
     if (!container) throw new Error('Container element is required');
     if (!url) throw new Error('Valid audio URL is required');
 
@@ -98,7 +98,14 @@ class AudioService {
 
       ws.on('ready', () => { onReady().catch(reject); });
       ws.on('error', (err) => reject(err instanceof Error ? err : new Error(String(err))));
-      ws.load(url);
+
+      // Pass pre-computed peaks to WaveSurfer so the waveform renders immediately
+      // without waiting for the full audio to decode (WaveSurfer v7 feature).
+      if (peaks && peaks.length > 0) {
+        ws.load(url, [new Float32Array(peaks)]);
+      } else {
+        ws.load(url);
+      }
     });
   }