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>

worker/src/worker/db.py

@@ -26,6 +26,8 @@ class AudioVersionModel(Base):
     nc_file_etag: Mapped[Optional[str]] = mapped_column(String(255))
     cdn_hls_base: Mapped[Optional[str]] = mapped_column(Text)
     waveform_url: Mapped[Optional[str]] = mapped_column(Text)
+    waveform_peaks: Mapped[Optional[list]] = mapped_column(JSONB)
+    waveform_peaks_mini: Mapped[Optional[list]] = mapped_column(JSONB)
     duration_ms: Mapped[Optional[int]] = mapped_column(Integer)
     format: Mapped[Optional[str]] = mapped_column(String(10))
     file_size_bytes: Mapped[Optional[int]] = mapped_column(BigInteger)

worker/src/worker/main.py

@@ -21,7 +21,7 @@ from worker.db import AudioVersionModel, JobModel
 from worker.pipeline.analyse_full import run_full_analysis
 from worker.pipeline.analyse_range import run_range_analysis
 from worker.pipeline.transcode import get_duration_ms, transcode_to_hls
-from worker.pipeline.waveform import generate_waveform_file
+from worker.pipeline.waveform import extract_peaks, generate_waveform_file
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s")
 log = logging.getLogger("worker")
@@ -59,20 +59,24 @@ async def handle_transcode(payload: dict, session: AsyncSession, settings) -> No
         hls_dir = os.path.join(tmp, "hls")
         await transcode_to_hls(local_path, hls_dir)
 
-        waveform_path = os.path.join(tmp, "waveform.json")
-        await generate_waveform_file(audio, waveform_path)
+        # Generate waveform peaks at two resolutions:
+        # - 500-point full peaks passed to WaveSurfer for instant render in player
+        # - 100-point mini peaks for the library/overview SVG thumbnail
+        loop = asyncio.get_event_loop()
+        peaks_500 = await loop.run_in_executor(None, extract_peaks, audio, 500)
+        peaks_100 = await loop.run_in_executor(None, extract_peaks, audio, 100)
 
-        # TODO: Upload HLS segments and waveform back to Nextcloud / object storage
+        # TODO: Upload HLS segments back to Nextcloud / object storage
         # For now, store the local tmp path in the DB (replace with real upload logic)
         hls_nc_path = f"hls/{version_id}"
-        waveform_nc_path = f"waveforms/{version_id}.json"
 
         stmt = (
             update(AudioVersionModel)
             .where(AudioVersionModel.id == version_id)
             .values(
                 cdn_hls_base=hls_nc_path,
-                waveform_url=waveform_nc_path,
+                waveform_peaks=peaks_500,
+                waveform_peaks_mini=peaks_100,
                 duration_ms=duration_ms,
                 analysis_status="running",
             )

worker/tests/test_handle_transcode.py

@@ -0,0 +1,71 @@
+"""Unit tests for handle_transcode waveform peaks storage."""
+
+from unittest.mock import AsyncMock, MagicMock, patch, call
+import uuid
+
+import numpy as np
+import pytest
+
+
+@pytest.fixture
+def mock_audio(sine_440hz):
+    audio, sr = sine_440hz
+    return audio, sr
+
+
+@pytest.mark.asyncio
+async def test_handle_transcode_stores_both_peak_resolutions(mock_audio):
+    """After handle_transcode, waveform_peaks (500) and waveform_peaks_mini (100) are stored in DB."""
+    audio, sr = mock_audio
+    version_id = uuid.uuid4()
+
+    # Capture the statement passed to session.execute
+    executed_stmts = []
+
+    async def capture_execute(stmt):
+        executed_stmts.append(stmt)
+        return MagicMock()
+
+    mock_session = AsyncMock()
+    mock_session.execute = capture_execute
+    mock_session.commit = AsyncMock()
+
+    mock_settings = MagicMock()
+    mock_settings.nextcloud_url = "http://nc.test"
+    mock_settings.nextcloud_user = "user"
+    mock_settings.nextcloud_pass = "pass"
+    mock_settings.target_sample_rate = 44100
+    mock_settings.audio_tmp_dir = "/tmp"
+
+    payload = {
+        "version_id": str(version_id),
+        "nc_file_path": "/bands/test/songs/test/v1.wav",
+    }
+
+    with (
+        patch("worker.main.load_audio", return_value=(audio, sr, "/tmp/v1.wav")),
+        patch("worker.main.get_duration_ms", return_value=5000),
+        patch("worker.main.transcode_to_hls", new_callable=AsyncMock),
+        patch("worker.main.run_full_analysis", new_callable=AsyncMock),
+    ):
+        from worker.main import handle_transcode
+        await handle_transcode(payload, mock_session, mock_settings)
+
+    assert len(executed_stmts) == 1, "Expected exactly one UPDATE statement"
+    stmt = executed_stmts[0]
+
+    # Extract the values dict from the SQLAlchemy Update statement
+    values = stmt._values
+    value_keys = {col.key for col, _ in values.items()}
+
+    assert "waveform_peaks" in value_keys, f"waveform_peaks not in UPDATE values: {value_keys}"
+    assert "waveform_peaks_mini" in value_keys, f"waveform_peaks_mini not in UPDATE values: {value_keys}"
+
+    # Resolve the actual peak lists from the BindParameter objects
+    peaks_500 = next(val.value for col, val in values.items() if col.key == "waveform_peaks")
+    peaks_100 = next(val.value for col, val in values.items() if col.key == "waveform_peaks_mini")
+
+    assert len(peaks_500) == 500, f"Expected 500 peaks, got {len(peaks_500)}"
+    assert len(peaks_100) == 100, f"Expected 100 mini peaks, got {len(peaks_100)}"
+    assert all(0.0 <= p <= 1.0 for p in peaks_500), "Full peaks out of [0, 1] range"
+    assert all(0.0 <= p <= 1.0 for p in peaks_100), "Mini peaks out of [0, 1] range"

worker/tests/test_waveform.py

@@ -14,6 +14,12 @@ def test_extract_peaks_returns_correct_length(sine_440hz):
     assert len(peaks) == 500
 
 
+def test_extract_peaks_mini_returns_correct_length(sine_440hz):
+    audio, sr = sine_440hz
+    peaks = extract_peaks(audio, num_points=100)
+    assert len(peaks) == 100
+
+
 def test_extract_peaks_normalized_between_0_and_1(sine_440hz):
     audio, sr = sine_440hz
     peaks = extract_peaks(audio, num_points=200)
@@ -21,6 +27,13 @@ def test_extract_peaks_normalized_between_0_and_1(sine_440hz):
     assert max(peaks) == pytest.approx(1.0, abs=0.01)
 
 
+def test_extract_peaks_mini_normalized_between_0_and_1(sine_440hz):
+    audio, sr = sine_440hz
+    peaks = extract_peaks(audio, num_points=100)
+    assert all(0.0 <= p <= 1.0 for p in peaks)
+    assert max(peaks) == pytest.approx(1.0, abs=0.01)
+
+
 def test_extract_peaks_empty_audio():
     audio = np.array([], dtype=np.float32)
     peaks = extract_peaks(audio, num_points=100)
@@ -28,6 +41,14 @@ def test_extract_peaks_empty_audio():
     assert all(p == 0.0 for p in peaks)
 
 
+def test_extract_peaks_custom_num_points(sine_440hz):
+    audio, _ = sine_440hz
+    for n in [50, 100, 250, 500]:
+        peaks = extract_peaks(audio, num_points=n)
+        assert len(peaks) == n, f"Expected {n} peaks, got {len(peaks)}"
+        assert all(0.0 <= p <= 1.0 for p in peaks)
+
+
 def test_peaks_to_json_valid_structure(sine_440hz):
     audio, _ = sine_440hz
     peaks = extract_peaks(audio)
@@ -46,4 +67,5 @@ async def test_generate_waveform_file_writes_json(tmp_path, sine_440hz):
     with open(output) as f:
         data = json.load(f)
     assert data["version"] == 2
-    assert len(data["data"]) == 1000
+    # generate_waveform_file uses the default num_points=500
+    assert len(data["data"]) == 500