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/alembic/versions/0006_waveform_peaks_in_db.py

@@ -0,0 +1,35 @@
+"""Store waveform peaks inline in audio_versions table.
+
+Replaces file-based waveform_url approach with two JSONB columns:
+- waveform_peaks: 500-point peaks for the player (passed directly to WaveSurfer)
+- waveform_peaks_mini: 100-point peaks for library/overview mini-waveform SVG
+
+Revision ID: 0006_waveform_peaks_in_db
+Revises: 0005_comment_tag
+Create Date: 2026-04-10
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB
+
+revision = "0006_waveform_peaks_in_db"
+down_revision = "0005_comment_tag"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "audio_versions",
+        sa.Column("waveform_peaks", JSONB, nullable=True),
+    )
+    op.add_column(
+        "audio_versions",
+        sa.Column("waveform_peaks_mini", JSONB, nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("audio_versions", "waveform_peaks_mini")
+    op.drop_column("audio_versions", "waveform_peaks")

api/src/rehearsalhub/db/models.py

@@ -232,6 +232,8 @@ class AudioVersion(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)

api/src/rehearsalhub/routers/versions.py

@@ -180,49 +180,27 @@ async def create_version(
 @router.get("/versions/{version_id}/waveform")
 async def get_waveform(
     version_id: uuid.UUID,
+    resolution: str = Query("full", pattern="^(full|mini)$"),
     session: AsyncSession = Depends(get_session),
     current_member: Member = Depends(get_current_member),
 ) -> Any:
+    """Return pre-computed waveform peaks from the database.
+
+    - `resolution=full` (default): 500-point peaks for the WaveSurfer player
+    - `resolution=mini`: 100-point peaks for the library overview thumbnail
+    """
     version, _ = await _get_version_and_assert_band_membership(version_id, session, current_member)
-    if not version.waveform_url:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Waveform not ready")
 
-    # Use the uploader's NC credentials — invited members may not have NC configured
-    uploader: Member | None = None
-    if version.uploaded_by:
-        uploader = await MemberRepository(session).get_by_id(version.uploaded_by)
-    storage = NextcloudClient.for_member(uploader) if uploader else NextcloudClient.for_member(current_member)
-    if storage is None:
-        raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="No storage provider configured for this account"
-        )
-    try:
-        data = await _download_with_retry(storage, version.waveform_url)
-    except httpx.ConnectError:
-        raise HTTPException(
-            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
-            detail="Storage service unavailable."
-        )
-    except httpx.HTTPStatusError as e:
-        if e.response.status_code == 404:
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail="Waveform file not found in storage."
-            )
-        else:
-            raise HTTPException(
-                status_code=status.HTTP_502_BAD_GATEWAY,
-                detail="Storage returned an error."
-            )
-    except Exception:
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail="Failed to fetch waveform."
-        )
-    import json
+    if resolution == "mini":
+        peaks = version.waveform_peaks_mini
+        if peaks is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Mini waveform not ready")
+    else:
+        peaks = version.waveform_peaks
+        if peaks is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Waveform not ready")
 
-    return json.loads(data)
+    return {"version": 2, "channels": 1, "length": len(peaks), "data": peaks}
 
 
 @router.get("/versions/{version_id}/stream")

api/src/rehearsalhub/schemas/audio_version.py

@@ -22,6 +22,8 @@ class AudioVersionRead(BaseModel):
     nc_file_etag: str | None = None
     cdn_hls_base: str | None = None
     waveform_url: str | None = None
+    waveform_peaks: list[float] | None = None
+    waveform_peaks_mini: list[float] | None = None
     duration_ms: int | None = None
     format: str | None = None
     file_size_bytes: int | None = None

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