feat(ui-refactor): DAW redesign, library overhaul, sections, analysis, and transport

app/api/jobs.py

@@ -10,7 +10,7 @@
 from pathlib import Path
 
 from fastapi import APIRouter, HTTPException, Request
-from pydantic import BaseModel
+from pydantic import BaseModel, field_validator
 
 from app.core.config import (
     JOB_ID_RE,
@@ -271,6 +271,82 @@ def cancel_job(job_id: str) -> dict:
     return job.to_state()
 
 
+_SECTION_ID_RE = re.compile(r"^[a-zA-Z0-9_\-]{1,64}$")
+_COLOR_RE = re.compile(r"^#[0-9a-fA-F]{3,8}$")
+
+
+class SectionItem(BaseModel):
+    id: str
+    name: str
+    start: float
+    end: float
+    color: str
+
+    @field_validator("id")
+    @classmethod
+    def _check_id(cls, v: str) -> str:
+        if not _SECTION_ID_RE.match(v):
+            raise ValueError("invalid section id")
+        return v
+
+    @field_validator("name")
+    @classmethod
+    def _check_name(cls, v: str) -> str:
+        return v.strip()[:64] or "Section"
+
+    @field_validator("color")
+    @classmethod
+    def _check_color(cls, v: str) -> str:
+        if not _COLOR_RE.match(v):
+            raise ValueError("invalid color")
+        return v
+
+    @field_validator("start", "end")
+    @classmethod
+    def _check_time(cls, v: float) -> float:
+        if not (0 <= v < 86400):
+            raise ValueError("time out of range")
+        return round(v, 3)
+
+
+class SectionsBody(BaseModel):
+    sections: list[SectionItem]
+
+
+@router.patch("/{job_id}/sections")
+def update_sections(job_id: str, body: SectionsBody) -> dict:
+    if not JOB_ID_RE.match(job_id):
+        raise HTTPException(status_code=404, detail="job not found")
+    job = registry_get(job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="job not found")
+
+    validated = [s.model_dump() for s in body.sections]
+    job.sections = validated
+
+    job_dir = (JOBS_DIR / job_id).resolve()
+    if not job_dir.is_relative_to(JOBS_DIR.resolve()):
+        raise HTTPException(status_code=404, detail="job not found")
+    meta_path = job_dir / "metadata.json"
+
+    meta: dict = {}
+    if meta_path.is_file():
+        try:
+            meta = json.loads(meta_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            pass
+    meta["sections"] = validated
+    try:
+        meta_path.write_text(json.dumps(meta, indent=2) + "\n", encoding="utf-8")
+    except OSError as exc:
+        logger.exception("failed to write sections for %s: %s", job_id, exc)
+        raise HTTPException(status_code=500, detail="failed to save sections") from exc
+
+    registry_persist(JOBS_DIR)
+
+    return {"job_id": job_id, "sections": validated}
+
+
 @router.delete("/{job_id}")
 def delete_job(job_id: str) -> dict[str, str]:
     if not JOB_ID_RE.match(job_id):

app/api/stems.py

@@ -1,9 +1,11 @@
 from __future__ import annotations
 
+import asyncio
+
 from fastapi import APIRouter, HTTPException
-from fastapi.responses import FileResponse
+from fastapi.responses import FileResponse, StreamingResponse
 
-from app.core.config import JOB_ID_RE, JOBS_DIR, STEM_NAMES
+from app.core.config import JOB_ID_RE, JOBS_DIR, STEM_NAMES, ffmpeg_executable
 from app.core.registry import get as registry_get
 
 router = APIRouter(tags=["stems"])
@@ -30,3 +32,43 @@ def get_stem(job_id: str, name: str) -> FileResponse:
     if not path.is_file() or not path.is_relative_to(JOBS_DIR.resolve()):
         raise HTTPException(status_code=404, detail="stem not found")
     return FileResponse(path, media_type="audio/wav", filename=f"{name}.wav")
+
+
+@router.get("/jobs/{job_id}/stems/{name}.mp3")
+async def get_stem_mp3(job_id: str, name: str) -> StreamingResponse:
+    if not JOB_ID_RE.match(job_id):
+        raise HTTPException(status_code=404, detail="job not found")
+    if name not in _ALLOWED_NAMES:
+        raise HTTPException(status_code=404, detail="unknown stem")
+    job = registry_get(job_id)
+    if job is None or job.status != "done":
+        raise HTTPException(status_code=404, detail="job not ready")
+    wav_path = (JOBS_DIR / job_id / "stems" / f"{name}.wav").resolve()
+    if not wav_path.is_file() or not wav_path.is_relative_to(JOBS_DIR.resolve()):
+        raise HTTPException(status_code=404, detail="stem not found")
+
+    async def _stream():
+        proc = await asyncio.create_subprocess_exec(
+            ffmpeg_executable(),
+            "-nostdin", "-loglevel", "error",
+            "-i", str(wav_path),
+            "-q:a", "2",  # VBR ~190 kbps
+            "-f", "mp3", "pipe:1",
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+        try:
+            while True:
+                chunk = await proc.stdout.read(65536)
+                if not chunk:
+                    break
+                yield chunk
+        finally:
+            proc.stdout.close()
+            await proc.wait()
+
+    return StreamingResponse(
+        _stream(),
+        media_type="audio/mpeg",
+        headers={"Content-Disposition": f'attachment; filename="{name}.mp3"'},
+    )

app/core/models.py

@@ -27,6 +27,11 @@ class Job:
     key_confidence: int | None = None  # 0-100 percent
     lufs: float | None = None  # ITU-R BS.1770 integrated loudness (dB)
     peak_db: float | None = None  # sample peak in dBFS (close to true peak)
+    dynamic_range: float | None = None  # peak_db - integrated LUFS (dB)
+    tempo_stability: int | None = None  # 0-100, beat interval consistency
+    stem_presence: dict[str, int] | None = None  # per-stem RMS 0-100
+    sections: list[dict] | None = None  # [{id, name, start, end, color}]
+    tags: list[str] | None = None  # YouTube tags + categories, lowercased, max 8
     stems: list[dict[str, str]] = field(default_factory=list)
     # Subset of stems the user chose at submit. The pipeline produces all
     # 6 regardless (Demucs htdemucs_6s is fixed), but after collect we
@@ -58,11 +63,17 @@ def to_state(self) -> dict[str, Any]:
             "key_confidence": self.key_confidence,
             "lufs": self.lufs,
             "peak_db": self.peak_db,
+            "dynamic_range": self.dynamic_range,
+            "tempo_stability": self.tempo_stability,
+            "stem_presence": self.stem_presence,
+            "sections": self.sections,
+            "tags": self.tags,
             "stems": self.stems,
             "selected_stems": self.selected_stems,
             "mix_url": self.mix_url,
             "source_url": self.source_url,
             "error": self.error,
+            "created_at": self.created_at,
         }
 
     def to_record(self) -> dict[str, Any]:

app/core/registry.py

@@ -153,6 +153,11 @@ def _recover_done_job(job_dir: Path) -> Job | None:
         key_confidence=meta.get("key_confidence"),
         lufs=meta.get("lufs"),
         peak_db=meta.get("peak_db"),
+        dynamic_range=meta.get("dynamic_range"),
+        tempo_stability=meta.get("tempo_stability"),
+        stem_presence=meta.get("stem_presence"),
+        sections=meta.get("sections"),
+        tags=meta.get("tags"),
     )
 
 

app/pipeline/analyze.py

@@ -215,6 +215,38 @@ def _load_audio_ffmpeg(
     return y, sr
 
 
+def compute_stem_presence(stems_dir: Path, selected_stems: list[str]) -> dict[str, int]:
+    """Load each extracted stem WAV, compute mean absolute amplitude, normalize
+    to 0-100. Only the stems that were selected (and therefore extracted) are
+    measured; the rest are omitted from the returned dict."""
+    import numpy as np
+
+    result: dict[str, int] = {}
+    rms_values: dict[str, float] = {}
+
+    for name in selected_stems:
+        wav_path = stems_dir / f"{name}.wav"
+        if not wav_path.is_file():
+            continue
+        loaded = _load_audio_ffmpeg(wav_path, sr=22050, duration=180.0)
+        if loaded is None:
+            continue
+        y, _ = loaded
+        rms_values[name] = float(np.sqrt(np.mean(y ** 2)))
+
+    if not rms_values:
+        return result
+
+    max_rms = max(rms_values.values())
+    if max_rms < 1e-9:
+        return {name: 0 for name in rms_values}
+
+    for name, rms in rms_values.items():
+        result[name] = max(0, min(100, round(rms / max_rms * 100)))
+
+    return result
+
+
 def analyze(job: Job, source: Path) -> tuple[int | None, str | None]:
     """Best-effort BPM and key detection. On failure, returns (None, None)
     and leaves job fields untouched -- the chips stay as placeholders."""
@@ -241,7 +273,7 @@ def analyze(job: Job, source: Path) -> tuple[int | None, str | None]:
         # smear, no kick fundamentals leaking in).
         y_harmonic, y_percussive = librosa.effects.hpss(y)
 
-        tempo_arr, _ = librosa.beat.beat_track(y=y_percussive, sr=sr)
+        tempo_arr, beat_frames = librosa.beat.beat_track(y=y_percussive, sr=sr)
         try:
             tempo = float(tempo_arr[0])  # type: ignore[index]
         except (TypeError, IndexError):
@@ -263,6 +295,22 @@ def analyze(job: Job, source: Path) -> tuple[int | None, str | None]:
         # it's good enough for a UI display and adds ~50 ms to analyze.
         lufs, peak_db = _measure_loudness(y, sr)
 
+        dynamic_range: float | None = None
+        if lufs is not None and peak_db is not None:
+            dynamic_range = round(peak_db - lufs, 1)
+
+        # Beat interval coefficient of variation → stability 0-100.
+        # CV = std/mean of inter-beat intervals; CV=0 is perfectly metronomic.
+        tempo_stability: int | None = None
+        import numpy as np
+        beat_times = librosa.frames_to_time(beat_frames, sr=sr)
+        if len(beat_times) > 2:
+            intervals = np.diff(beat_times)
+            mean_iv = float(intervals.mean())
+            if mean_iv > 0:
+                cv = float(intervals.std() / mean_iv)
+                tempo_stability = max(0, min(100, round((1 - min(cv, 1)) * 100)))
+
         _set(
             job,
             bpm=bpm,
@@ -271,6 +319,8 @@ def analyze(job: Job, source: Path) -> tuple[int | None, str | None]:
             key_confidence=key_confidence,
             lufs=lufs,
             peak_db=peak_db,
+            dynamic_range=dynamic_range,
+            tempo_stability=tempo_stability,
             progress=1.0,
             stage="Analysis complete",
         )

app/pipeline/download.py

@@ -213,6 +213,15 @@ def hook(d: dict) -> None:
         thumbnail=info.get("thumbnail") or meta.get("thumbnail"),
     )
 
+    raw_tags = [
+        t.strip().lower()
+        for t in (info.get("tags") or []) + (info.get("categories") or [])
+        if isinstance(t, str) and t.strip()
+    ]
+    seen: set[str] = set()
+    deduped = [t for t in raw_tags if not (t in seen or seen.add(t))]  # type: ignore[func-returns-value]
+    _set(job, tags=deduped[:8] or None)
+
     candidates = sorted(job_dir.glob("source.*"))
     if not candidates:
         raise RuntimeError("yt-dlp finished but no source file was produced")

app/pipeline/runner.py

@@ -10,7 +10,7 @@
 from app.core.config import TIMEOUT_FFMPEG
 from app.core.models import Job, JobCancelled
 from app.core.registry import persist as persist_registry
-from app.pipeline.analyze import analyze
+from app.pipeline.analyze import analyze, compute_stem_presence
 from app.pipeline.collect import cleanup_source, collect, make_original_track, make_selected_mix
 from app.pipeline.download import _set, download
 from app.pipeline.separate import separate
@@ -83,6 +83,7 @@ def _run_common(job: Job, source: Path, job_dir: Path) -> None:
     stems_root = separate(job, source, job_dir)
     found = collect(job, stems_root, job_dir)
     stems_dir = job_dir / "stems"
+    job.stem_presence = compute_stem_presence(stems_dir, found)
     # Source (100-300 MB or the local upload) is no longer needed after
     # collect; delete it before the ffmpeg amix steps in case scratch space
     # is tight.
@@ -129,6 +130,10 @@ def _write_metadata(job: Job, job_dir: Path) -> None:
         "key_confidence": job.key_confidence,
         "lufs": job.lufs,
         "peak_db": job.peak_db,
+        "dynamic_range": job.dynamic_range,
+        "tempo_stability": job.tempo_stability,
+        "stem_presence": job.stem_presence,
+        "tags": job.tags,
     }
     try:
         (job_dir / "metadata.json").write_text(json.dumps(meta, indent=2) + "\n", encoding="utf-8")