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>

api/tests/integration/test_waveform_peaks_schema.py

@@ -0,0 +1,49 @@
+"""Integration tests for waveform peaks stored inline in audio_versions."""
+
+import pytest
+
+from tests.factories import create_audio_version, create_band, create_member, create_song
+
+
+@pytest.mark.asyncio
+@pytest.mark.integration
+async def test_audio_version_stores_waveform_peaks(db_session, current_member):
+    """AudioVersion can store waveform_peaks and waveform_peaks_mini JSONB data."""
+    from rehearsalhub.repositories.audio_version import AudioVersionRepository
+
+    band = await create_band(db_session, creator_id=current_member.id)
+    song = await create_song(db_session, band_id=band.id, creator_id=current_member.id)
+    version = await create_audio_version(db_session, song_id=song.id)
+
+    peaks_500 = [float(i) / 500 for i in range(500)]
+    peaks_100 = [float(i) / 100 for i in range(100)]
+
+    repo = AudioVersionRepository(db_session)
+    updated = await repo.update(
+        version,
+        waveform_peaks=peaks_500,
+        waveform_peaks_mini=peaks_100,
+    )
+    await db_session.commit()
+
+    fetched = await repo.get_by_id(updated.id)
+    assert fetched is not None
+    assert fetched.waveform_peaks is not None
+    assert len(fetched.waveform_peaks) == 500
+    assert fetched.waveform_peaks_mini is not None
+    assert len(fetched.waveform_peaks_mini) == 100
+    assert fetched.waveform_peaks[0] == pytest.approx(0.0)
+    assert fetched.waveform_peaks[1] == pytest.approx(1 / 500)
+
+
+@pytest.mark.asyncio
+@pytest.mark.integration
+async def test_audio_version_peaks_default_null(db_session, current_member):
+    """waveform_peaks and waveform_peaks_mini are null by default."""
+    band = await create_band(db_session, creator_id=current_member.id)
+    song = await create_song(db_session, band_id=band.id, creator_id=current_member.id)
+    version = await create_audio_version(db_session, song_id=song.id)
+    await db_session.commit()
+
+    assert version.waveform_peaks is None
+    assert version.waveform_peaks_mini is None

api/tests/unit/test_audio_version_schema.py

@@ -0,0 +1,64 @@
+"""Unit tests for AudioVersionRead schema — waveform peaks serialization."""
+
+import uuid
+from datetime import datetime, timezone
+from unittest.mock import MagicMock
+
+import pytest
+
+from rehearsalhub.db.models import AudioVersion
+from rehearsalhub.schemas.audio_version import AudioVersionRead
+
+
+def _make_version(peaks=None, peaks_mini=None) -> MagicMock:
+    """Build a mock AudioVersion ORM object."""
+    v = MagicMock(spec=AudioVersion)
+    v.id = uuid.uuid4()
+    v.song_id = uuid.uuid4()
+    v.version_number = 1
+    v.label = None
+    v.nc_file_path = "/bands/test/v1.wav"
+    v.nc_file_etag = "abc123"
+    v.cdn_hls_base = None
+    v.waveform_url = None
+    v.waveform_peaks = peaks
+    v.waveform_peaks_mini = peaks_mini
+    v.duration_ms = 5000
+    v.format = "wav"
+    v.file_size_bytes = 1024
+    v.analysis_status = "done"
+    v.uploaded_by = None
+    v.uploaded_at = datetime.now(timezone.utc)
+    return v
+
+
+def test_audio_version_read_includes_waveform_peaks():
+    peaks = [float(i) / 500 for i in range(500)]
+    peaks_mini = [float(i) / 100 for i in range(100)]
+    v = _make_version(peaks=peaks, peaks_mini=peaks_mini)
+
+    schema = AudioVersionRead.model_validate(v)
+
+    assert schema.waveform_peaks is not None
+    assert len(schema.waveform_peaks) == 500
+    assert schema.waveform_peaks_mini is not None
+    assert len(schema.waveform_peaks_mini) == 100
+
+
+def test_audio_version_read_peaks_default_null():
+    v = _make_version(peaks=None, peaks_mini=None)
+
+    schema = AudioVersionRead.model_validate(v)
+
+    assert schema.waveform_peaks is None
+    assert schema.waveform_peaks_mini is None
+
+
+def test_audio_version_read_peaks_values_preserved():
+    peaks = [0.0, 0.5, 1.0]
+    v = _make_version(peaks=peaks, peaks_mini=[0.25, 0.75])
+
+    schema = AudioVersionRead.model_validate(v)
+
+    assert schema.waveform_peaks == [0.0, 0.5, 1.0]
+    assert schema.waveform_peaks_mini == [0.25, 0.75]

api/tests/unit/test_versions_list_peaks.py

@@ -0,0 +1,38 @@
+"""Confirm that list_versions returns waveform_peaks inline (no extra request needed)."""
+
+import uuid
+from datetime import datetime, timezone
+from unittest.mock import MagicMock
+
+from rehearsalhub.db.models import AudioVersion
+from rehearsalhub.schemas.audio_version import AudioVersionRead
+
+
+def test_audio_version_read_includes_peaks_in_list_serialization():
+    """AudioVersionRead (used by list_versions) serializes waveform_peaks inline."""
+    peaks = [0.1, 0.5, 0.9]
+    mini = [0.3, 0.7]
+
+    v = MagicMock(spec=AudioVersion)
+    v.id = uuid.uuid4()
+    v.song_id = uuid.uuid4()
+    v.version_number = 1
+    v.label = None
+    v.nc_file_path = "/test/v1.wav"
+    v.nc_file_etag = "etag"
+    v.cdn_hls_base = None
+    v.waveform_url = None
+    v.waveform_peaks = peaks
+    v.waveform_peaks_mini = mini
+    v.duration_ms = 3000
+    v.format = "wav"
+    v.file_size_bytes = 512
+    v.analysis_status = "done"
+    v.uploaded_by = None
+    v.uploaded_at = datetime.now(timezone.utc)
+
+    schema = AudioVersionRead.model_validate(v)
+    serialized = schema.model_dump()
+
+    assert serialized["waveform_peaks"] == peaks
+    assert serialized["waveform_peaks_mini"] == mini

api/tests/unit/test_waveform_endpoint.py

@@ -0,0 +1,120 @@
+"""Unit tests for GET /versions/{id}/waveform endpoint — reads peaks from DB."""
+
+import uuid
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from rehearsalhub.db.models import AudioVersion, Member, Song
+
+
+def _make_member() -> MagicMock:
+    m = MagicMock(spec=Member)
+    m.id = uuid.uuid4()
+    m.nc_url = "http://nc.test"
+    m.nc_username = "user"
+    m.nc_password = "pass"
+    return m
+
+
+def _make_version(peaks=None, peaks_mini=None, has_waveform_url=False) -> MagicMock:
+    v = MagicMock(spec=AudioVersion)
+    v.id = uuid.uuid4()
+    v.song_id = uuid.uuid4()
+    v.uploaded_by = None
+    v.waveform_url = "waveforms/test.json" if has_waveform_url else None
+    v.waveform_peaks = peaks
+    v.waveform_peaks_mini = peaks_mini
+    v.cdn_hls_base = None
+    v.nc_file_path = "/bands/test/v1.wav"
+    return v
+
+
+def _make_song(band_id: uuid.UUID) -> MagicMock:
+    s = MagicMock(spec=Song)
+    s.id = uuid.uuid4()
+    s.band_id = band_id
+    return s
+
+
+@pytest.mark.asyncio
+async def test_waveform_returns_full_peaks_from_db(mock_session):
+    """GET /versions/{id}/waveform returns 500-point peaks from DB column."""
+    from rehearsalhub.routers.versions import get_waveform
+
+    peaks = [float(i) / 500 for i in range(500)]
+    version = _make_version(peaks=peaks)
+    member = _make_member()
+    band_id = uuid.uuid4()
+    song = _make_song(band_id)
+
+    with (
+        patch("rehearsalhub.routers.versions._get_version_and_assert_band_membership",
+              return_value=(version, song)),
+    ):
+        result = await get_waveform(version_id=version.id, session=mock_session, current_member=member)
+
+    assert result["data"] == peaks
+    assert result["length"] == 500
+    assert "mini" not in result
+
+
+@pytest.mark.asyncio
+async def test_waveform_returns_mini_peaks_with_resolution_param(mock_session):
+    """GET /versions/{id}/waveform?resolution=mini returns 100-point peaks."""
+    from rehearsalhub.routers.versions import get_waveform
+
+    peaks_mini = [float(i) / 100 for i in range(100)]
+    version = _make_version(peaks=[0.5] * 500, peaks_mini=peaks_mini)
+    member = _make_member()
+    band_id = uuid.uuid4()
+    song = _make_song(band_id)
+
+    with (
+        patch("rehearsalhub.routers.versions._get_version_and_assert_band_membership",
+              return_value=(version, song)),
+    ):
+        result = await get_waveform(version_id=version.id, session=mock_session, current_member=member, resolution="mini")
+
+    assert result["data"] == peaks_mini
+    assert result["length"] == 100
+
+
+@pytest.mark.asyncio
+async def test_waveform_404_when_no_peaks_in_db(mock_session):
+    """GET /versions/{id}/waveform returns 404 when no peaks stored yet."""
+    from fastapi import HTTPException
+    from rehearsalhub.routers.versions import get_waveform
+
+    version = _make_version(peaks=None, peaks_mini=None)
+    member = _make_member()
+    song = _make_song(uuid.uuid4())
+
+    with (
+        patch("rehearsalhub.routers.versions._get_version_and_assert_band_membership",
+              return_value=(version, song)),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await get_waveform(version_id=version.id, session=mock_session, current_member=member)
+
+    assert exc_info.value.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_waveform_mini_404_when_no_mini_peaks(mock_session):
+    """GET /versions/{id}/waveform?resolution=mini returns 404 when no mini peaks stored."""
+    from fastapi import HTTPException
+    from rehearsalhub.routers.versions import get_waveform
+
+    version = _make_version(peaks=[0.5] * 500, peaks_mini=None)
+    member = _make_member()
+    song = _make_song(uuid.uuid4())
+
+    with (
+        patch("rehearsalhub.routers.versions._get_version_and_assert_band_membership",
+              return_value=(version, song)),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await get_waveform(version_id=version.id, session=mock_session, current_member=member, resolution="mini")
+
+    assert exc_info.value.status_code == 404