diff --git a/backend/api/routes/review.py b/backend/api/routes/review.py
index dc9cacaa..0bf188ad 100644
--- a/backend/api/routes/review.py
+++ b/backend/api/routes/review.py
@@ -19,7 +19,7 @@ import json
import os
import tempfile
from pathlib import Path
-from typing import Dict, Any, List, Optional, Set, Tuple
+from typing import Dict, Any, List, Literal, Optional, Set, Tuple
from fastapi import APIRouter, HTTPException, Request, Depends, Form, File, UploadFile
from fastapi.responses import RedirectResponse
@@ -372,6 +372,15 @@ async def get_correction_data(
raise HTTPException(status_code=500, detail=t("en", "review.correctionsLoadFailed", error=str(e)))
+@router.get("/{job_id}/audio/vocals")
+async def get_vocals_audio(
+ job_id: str,
+ auth_info: Tuple[str, str] = Depends(require_review_auth)
+):
+ """Stream the vocals audio file for playback."""
+ return await _stream_audio(job_id, stem="vocals")
+
+
@router.get("/{job_id}/audio/{audio_hash}")
async def get_audio_with_hash(
job_id: str,
@@ -392,7 +401,7 @@ async def get_audio_no_hash(
return await _stream_audio(job_id)
-async def _stream_audio(job_id: str):
+async def _stream_audio(job_id: str, stem: Literal["input"] | Literal["vocals"] = "input"):
"""
Redirect to a signed GCS URL for audio playback in the review interface.
@@ -407,7 +416,22 @@ async def _stream_audio(job_id: str):
if not job:
raise HTTPException(status_code=404, detail=t("en", "review.jobNotFound"))
- audio_gcs_path = job.input_media_gcs_path
+ audio_gcs_path = None
+ if stem == "input":
+ audio_gcs_path = job.input_media_gcs_path
+ elif stem == "vocals":
+ stems = job.file_urls.get("stems", {}) if job.file_urls else {}
+ # Stem keys vary by separation model. We want the full vocal mix
+ # (lead + backing) so every word can be lined up against the waveform:
+ # - "vocals" : full vocal from a 2-stem split (rare)
+ # - "vocals_clean" : full vocal from the primary vocal/instrumental
+ # split (present on essentially all cloud jobs)
+ # - "lead_vocals" : last-resort fallback (misses backing lines)
+ # Use .get() so a missing key yields a clean 404 below, not a KeyError/500.
+ for key in ("vocals", "vocals_clean", "lead_vocals"):
+ if stems.get(key):
+ audio_gcs_path = stems[key]
+ break
if not audio_gcs_path:
raise HTTPException(status_code=404, detail=t("en", "review.audioNotFound"))
diff --git a/backend/tests/test_routes_review.py b/backend/tests/test_routes_review.py
index bbed73ca..3396743e 100644
--- a/backend/tests/test_routes_review.py
+++ b/backend/tests/test_routes_review.py
@@ -1132,3 +1132,71 @@ class TestGetPreviewVideoRedirect:
self._call(mock_storage)
assert exc_info.value.status_code == 404
mock_storage.generate_signed_url.assert_not_called()
+
+
+class TestGetVocalsAudio:
+ """The vocals waveform endpoint streams the full vocal stem for the timeline.
+
+ Real jobs never store a plain 'vocals' key — separation writes
+ 'vocals_clean' / 'lead_vocals' / 'backing_vocals'. The endpoint must select
+ the fullest vocal mix (vocals_clean) rather than KeyError on 'vocals'.
+ """
+
+ def _call(self, stems):
+ import asyncio
+ from backend.api.routes.review import _stream_audio
+
+ job = MagicMock()
+ job.input_media_gcs_path = "jobs/j/input.flac"
+ job.file_urls = {"stems": stems}
+
+ job_manager = MagicMock()
+ job_manager.get_job.return_value = job
+
+ transcoding = MagicMock()
+ transcoding.get_review_audio_url_async = AsyncMock(
+ return_value="https://signed.example/vocals.ogg?sig=xyz"
+ )
+
+ with patch("backend.api.routes.review.JobManager", return_value=job_manager), patch(
+ "backend.services.audio_transcoding_service.AudioTranscodingService",
+ return_value=transcoding,
+ ):
+ resp = asyncio.run(
+ _stream_audio(job_id="j", stem="vocals")
+ )
+ return resp, transcoding
+
+ def test_selects_vocals_clean_when_no_plain_vocals_key(self):
+ from starlette.responses import RedirectResponse
+
+ # The shape produced by real cloud jobs (no plain "vocals").
+ resp, transcoding = self._call(
+ {
+ "instrumental_clean": "jobs/j/stems/instrumental_clean.flac",
+ "vocals_clean": "jobs/j/stems/vocals_clean.flac",
+ "lead_vocals": "jobs/j/stems/lead_vocals.flac",
+ "backing_vocals": "jobs/j/stems/backing_vocals.flac",
+ }
+ )
+
+ assert isinstance(resp, RedirectResponse)
+ assert resp.status_code == 302
+ # Must pick the full vocal mix (vocals_clean), not lead_vocals or KeyError.
+ assert transcoding.get_review_audio_url_async.call_args[0][0] == "jobs/j/stems/vocals_clean.flac"
+
+ def test_prefers_plain_vocals_then_falls_back_to_lead(self):
+ # 2-stem split exposes a plain "vocals" — preferred.
+ _, transcoding = self._call({"vocals": "jobs/j/stems/vocals.flac"})
+ assert transcoding.get_review_audio_url_async.call_args[0][0] == "jobs/j/stems/vocals.flac"
+
+ # Only lead_vocals available — last-resort fallback.
+ _, transcoding = self._call({"lead_vocals": "jobs/j/stems/lead_vocals.flac"})
+ assert transcoding.get_review_audio_url_async.call_args[0][0] == "jobs/j/stems/lead_vocals.flac"
+
+ def test_404_when_no_vocal_stem_present(self):
+ from fastapi import HTTPException
+
+ with pytest.raises(HTTPException) as exc_info:
+ self._call({"instrumental_clean": "jobs/j/stems/instrumental_clean.flac"})
+ assert exc_info.value.status_code == 404
diff --git a/frontend/components/lyrics-review/EditTimelineSection.tsx b/frontend/components/lyrics-review/EditTimelineSection.tsx
index b5898f56..dcf78d03 100644
--- a/frontend/components/lyrics-review/EditTimelineSection.tsx
+++ b/frontend/components/lyrics-review/EditTimelineSection.tsx
@@ -1,8 +1,9 @@
'use client'
import { memo, useRef, useCallback } from 'react'
+import { useTranslations } from 'next-intl'
import { Button } from '@/components/ui/button'
-import { Play, XCircle, Hand } from 'lucide-react'
+import { Hand } from 'lucide-react'
import { Word } from '@/lib/lyrics-review/types'
import TimelineEditor from './TimelineEditor'
import { cn } from '@/lib/utils'
@@ -17,6 +18,7 @@ const TapButton = memo(function TapButton({
onTapStart: () => void
onTapEnd: () => void
}) {
+ const t = useTranslations('lyricsReview.editTimeline')
const isPressedRef = useRef(false)
const handleTapStart = useCallback(() => {
@@ -51,7 +53,7 @@ const TapButton = memo(function TapButton({
)}
>
- {isSpacebarPressed ? 'HOLD...' : 'TAP'}
+ {isSpacebarPressed ? t('hold') : t('tap')}
)
})
@@ -60,17 +62,12 @@ interface EditTimelineSectionProps {
words: Word[]
startTime: number
endTime: number
- originalStartTime: number | null
- originalEndTime: number | null
- currentStartTime: number | null
- currentEndTime: number | null
currentTime?: number
isManualSyncing: boolean
syncWordIndex: number
isSpacebarPressed: boolean
onWordUpdate: (index: number, updates: Partial) => void
onPlaySegment?: (time: number) => void
- startManualSync: () => void
isGlobal?: boolean
onTapStart?: () => void
onTapEnd?: () => void
@@ -80,21 +77,17 @@ export default function EditTimelineSection({
words,
startTime,
endTime,
- originalStartTime,
- originalEndTime,
- currentStartTime,
- currentEndTime,
currentTime,
isManualSyncing,
syncWordIndex,
isSpacebarPressed,
onWordUpdate,
onPlaySegment,
- startManualSync,
isGlobal = false,
onTapStart,
onTapEnd,
}: EditTimelineSectionProps) {
+ const t = useTranslations('lyricsReview.editTimeline')
// Simple mobile detection
const isMobile = typeof window !== 'undefined' && window.innerWidth < 640
@@ -110,8 +103,9 @@ export default function EditTimelineSection({
return (
<>
- {/* Timeline Editor */}
-
+ {/* Timeline Editor — height hugs its content (ruler + word bars + waveform)
+ instead of a fixed min-height, to avoid dead vertical space. */}
+
- {/* Time range info and controls */}
-
- {/* Time range info - hidden on mobile to save space */}
- {!isMobile && (
-
-
- Original Time Range: {originalStartTime?.toFixed(2) ?? 'N/A'} -{' '}
- {originalEndTime?.toFixed(2) ?? 'N/A'}
-
-
- Current Time Range: {currentStartTime?.toFixed(2) ?? 'N/A'} -{' '}
- {currentEndTime?.toFixed(2) ?? 'N/A'}
-
-
- )}
-
- {/* Controls */}
+ {/* Sync helper — only visible while manually syncing. The Tap To Sync
+ toggle and the time-range readout now live in the modal header to
+ reclaim the vertical space above the word list. */}
+ {(currentWordInfo || (isMobile && isManualSyncing)) && (
- {/* Tap To Sync button */}
-
-
{/* Current word info during sync */}
{currentWordInfo && (
- Word {currentWordInfo.index} of {currentWordInfo.total}:{' '}
+ {t('wordProgress', {
+ index: currentWordInfo.index,
+ total: currentWordInfo.total,
+ })}{' '}
{currentWordInfo.text}
{isSpacebarPressed
- ? 'Holding... Release when word ends'
+ ? t('holdingRelease')
: isMobile
- ? 'Tap the button when word starts'
- : 'Press spacebar when word starts (tap for short words, hold for long words)'}
+ ? t('tapWhenStarts')
+ : t('pressSpacebarHint')}