splitscore 0.1.0__py3-none-any.whl

app/__init__.py

@@ -0,0 +1,3 @@
+"""SplitScore — stem separation + MIDI transcription."""
+
+__version__ = "0.1.0"

app/__main__.py

@@ -0,0 +1,4 @@
+from app.main import main
+
+if __name__ == "__main__":
+    main()

app/cli.py

@@ -0,0 +1,87 @@
+"""CLI entry point for `uvx splitscore`.
+
+Detects NVIDIA GPU, installs the correct torch CUDA backend if missing,
+then starts the server.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+import webbrowser
+
+CUDA_TAG_MAP: dict[str, str] = {
+    "11.8": "cu118",
+    "12.1": "cu121",
+    "12.4": "cu124",
+    "12.6": "cu126",
+    "12.8": "cu128",
+}
+
+
+def _detect_cuda() -> str | None:
+    """Return best-matching CUDA wheel tag (e.g. 'cu126') or None."""
+    nvidia_smi = shutil.which("nvidia-smi")
+    if not nvidia_smi:
+        return None
+    try:
+        out = subprocess.check_output(
+            [nvidia_smi, "--query-gpu=driver_version", "--format=csv,noheader"],
+            text=True,
+            timeout=5,
+        )
+        driver = out.strip().splitlines()[0].strip()
+        major = int(driver.split(".")[0])
+        if major >= 570:
+            version = "12.8"
+        elif major >= 560:
+            version = "12.6"
+        elif major >= 550:
+            version = "12.4"
+        elif major >= 535:
+            version = "12.2"
+        else:
+            return None
+        return CUDA_TAG_MAP.get(version)
+    except (subprocess.SubprocessError, IndexError, ValueError):
+        return None
+
+
+def _install_torch(tag: str) -> None:
+    """Install the correct torch CUDA wheel into the current environment."""
+    index_url = f"https://download.pytorch.org/whl/{tag}"
+    print(f"Installing torch ({tag}) into current environment ...")
+    subprocess.check_call(
+        [
+            sys.executable, "-m", "pip", "install",
+            "--index-url", index_url,
+            "torch>=2.7",
+        ],
+    )
+
+
+def _ensure_torch() -> None:
+    """Make sure torch is importable; auto-install if missing."""
+    try:
+        import torch  # noqa: F401
+        return
+    except ImportError:
+        pass
+
+    tag = _detect_cuda()
+    if tag:
+        print(f"NVIDIA GPU detected — installing torch {tag}")
+        _install_torch(tag)
+    else:
+        print("No NVIDIA GPU detected — installing CPU-only torch")
+        subprocess.check_call(
+            [sys.executable, "-m", "pip", "install", "torch>=2.7"],
+        )
+
+
+def main() -> None:
+    _ensure_torch()
+    import uvicorn
+    url = "http://127.0.0.1:8000"
+    webbrowser.open(url)
+    uvicorn.run("app.main:app", host="127.0.0.1", port=8000)

app/main.py

@@ -0,0 +1,162 @@
+"""FastAPI backend: routes, SSE event stream, static frontend."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import webbrowser
+from dataclasses import asdict
+from pathlib import Path
+
+from fastapi import FastAPI, File, HTTPException, UploadFile
+from fastapi.responses import FileResponse, StreamingResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+from app.pipeline import STATUS_CREATED, STATUS_DONE, STATUS_FAILED, STATUS_READY, Pipeline
+from app.separator import STEMS
+from app.settings import Settings, load_settings, save_settings
+from app.transcribe import list_instruments
+
+ALLOWED_EXTENSIONS = {"wav", "mp3", "flac", "ogg", "m4a", "aiff"}
+
+app = FastAPI(title="SplitScore")
+PIPELINE = Pipeline(load_settings())
+
+_HEARTBEAT = ":" + " " * 15 + "\n\n"  # SSE comment keeps the connection alive
+
+TERMINAL_EVENTS = {"done", "failed", "cancelled"}
+
+
+class TranscribeBody(BaseModel):
+    stems: list[str]
+
+
+@app.post("/api/jobs")
+async def create_job(file: UploadFile = File(...)):
+    name = Path(file.filename or "").name  # basename only, strips any ../ or drive segments
+    if not name:
+        raise HTTPException(400, "Invalid filename")
+    if "/" in name or "\\" in name:
+        raise HTTPException(400, "Invalid filename")
+    ext = name.rsplit(".", 1)[-1].lower() if "." in name else ""
+    if ext not in ALLOWED_EXTENSIONS:
+        raise HTTPException(400, f"Unsupported extension '.{ext}'; allowed: {sorted(ALLOWED_EXTENSIONS)}")
+    data = await file.read()
+    if not data:
+        raise HTTPException(400, "Empty file upload")
+    job = PIPELINE.create_job(Path(name).stem, "unused")
+    in_dir = job.output_dir / "input"
+    in_dir.mkdir(parents=True, exist_ok=True)
+    job.input_path = in_dir / name
+    job.input_path.write_bytes(data)
+    asyncio.create_task(PIPELINE.separate(job))
+    return {"job_id": job.id}
+
+
+@app.get("/api/jobs/{job_id}")
+async def get_job(job_id: str):
+    job = PIPELINE.jobs.get(job_id)
+    if not job:
+        raise HTTPException(404, "Unknown job")
+    midi = [p.name for p in (job.output_dir / "midi").glob("*.mid")]
+    return {"job_id": job.id, "status": job.status, "error": job.error,
+            "song_name": job.song_name, "midi": midi}
+
+
+@app.post("/api/jobs/{job_id}/transcribe")
+async def transcribe(job_id: str, body: TranscribeBody):
+    job = PIPELINE.jobs.get(job_id)
+    if not job:
+        raise HTTPException(404, "Unknown job")
+    if job.status not in (STATUS_READY, STATUS_DONE, STATUS_FAILED):
+        raise HTTPException(409, f"Job not ready (status={job.status})")
+    bad = [s for s in body.stems if s not in STEMS]
+    if bad:
+        raise HTTPException(400, f"Unknown stems: {bad}")
+    s = PIPELINE.settings
+    asyncio.create_task(PIPELINE.transcribe(
+        job, body.stems, s.instrument_by_stem, s.temperature, s.beam_size, s.batch_size))
+    return {"job_id": job.id}
+
+
+@app.post("/api/jobs/{job_id}/cancel")
+async def cancel(job_id: str):
+    job = PIPELINE.jobs.get(job_id)
+    if not job:
+        raise HTTPException(404, "Unknown job")
+    job.cancel.set()
+    # Idle job (post-separation, waiting to transcribe): no worker coroutine
+    # observes the flag, so finish the cancel here and discard the stems.
+    if job.status in (STATUS_CREATED, STATUS_READY):
+        PIPELINE._finish_cancelled(job)
+    return {"ok": True}
+
+
+@app.get("/api/jobs/{job_id}/events")
+async def events(job_id: str):
+    job = PIPELINE.jobs.get(job_id)
+    if not job:
+        raise HTTPException(404, "Unknown job")
+
+    async def gen():
+        while True:
+            try:
+                event = await asyncio.wait_for(job.events.get(), timeout=15.0)
+                yield f"data: {json.dumps(event)}\n\n"
+                if event["type"] in TERMINAL_EVENTS:
+                    return
+            except asyncio.TimeoutError:
+                yield _HEARTBEAT
+    return StreamingResponse(gen(), media_type="text/event-stream")
+
+
+@app.get("/api/instruments")
+async def get_instruments():
+    # First call shells out to `muscriptor list-instruments` (~seconds); run it
+    # off the event loop. Result is cached in transcribe.list_instruments.
+    instruments = await asyncio.to_thread(list_instruments)
+    return {"instruments": instruments}
+
+
+@app.get("/api/settings")
+async def get_settings():
+    return load_settings()
+
+
+@app.put("/api/settings")
+async def put_settings(body: dict):
+    merged = asdict(load_settings())
+    merged.update({k: v for k, v in body.items() if k in merged})
+    updated = Settings(**merged)
+    save_settings(updated)
+    PIPELINE.settings = updated
+    return merged
+
+
+@app.get("/output/{job_id}/midi/{filename}")
+async def download_midi(job_id: str, filename: str):
+    base = Path(PIPELINE.settings.output_folder).resolve()
+    path = (base / job_id / "midi" / filename).resolve()
+    if not path.is_relative_to(base) or not path.is_file():
+        raise HTTPException(404, "MIDI not found")
+    return FileResponse(path, media_type="audio/midi", filename=filename)
+
+
+@app.get("/output/{job_id}/stems/{filename}")
+async def download_stem(job_id: str, filename: str):
+    base = Path(PIPELINE.settings.output_folder).resolve()
+    path = (base / job_id / "stems" / filename).resolve()
+    if not path.is_relative_to(base) or not path.is_file():
+        raise HTTPException(404, "Stem not found")
+    return FileResponse(path, media_type="audio/wav")
+
+
+app.mount("/", StaticFiles(directory=Path(__file__).parent / "static", html=True), name="static")
+
+
+def main() -> None:
+    import uvicorn
+    url = "http://127.0.0.1:8000"
+    webbrowser.open(url)
+    uvicorn.run(app, host="127.0.0.1", port=8000)

app/pipeline.py

@@ -0,0 +1,170 @@
+"""Job orchestration: separate then transcribe, with SSE event stream + cancel."""
+
+from __future__ import annotations
+
+import asyncio
+import shutil
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from app.separator import STEMS, Separator
+from app.settings import Settings
+from app.transcribe import Transcriber
+
+STATUS_CREATED = "created"
+STATUS_SEPARATING = "separating"
+STATUS_READY = "ready"
+STATUS_TRANSCRIBING = "transcribing"
+STATUS_DONE = "done"
+STATUS_FAILED = "failed"
+STATUS_CANCELLED = "cancelled"
+
+
+@dataclass
+class Job:
+    id: str
+    song_name: str = ""
+    status: str = STATUS_CREATED
+    input_path: Path | None = None
+    output_dir: Path | None = None
+    error: str | None = None
+    cancel: asyncio.Event = field(default_factory=asyncio.Event)
+    events: asyncio.Queue = field(default_factory=asyncio.Queue)
+
+
+def _hf_setup_hint(exc: Exception) -> str:
+    """Append a setup hint when the error looks like a missing/rejected HF token."""
+    text = str(exc).lower()
+    if any(s in text for s in ("401", "gated", "authentication", "forbidden", "hf_token", "huggingface")):
+        return f"{exc}\n\nSetup hint: run `uv run hf auth login` with a Hugging Face token to download the models."
+    return str(exc)
+
+
+def _is_cuda_oom(exc: Exception) -> bool:
+    text = f"{type(exc).__name__}: {exc}".lower()
+    return "out of memory" in text or "cuda error" in text
+
+
+_OOM_MESSAGE = (
+    "CUDA ran out of memory while transcribing. Lower Beam size or Batch size in "
+    "Settings (or pick a smaller model), then try again.")
+
+
+class Pipeline:
+    def __init__(self, settings: Settings, separator_factory=None, transcriber_factory=None):
+        self.settings = settings
+        self._sep_factory = separator_factory or Separator
+        self._tr_factory = transcriber_factory or Transcriber
+        self._lock = asyncio.Lock()
+        self.jobs: dict[str, Job] = {}
+
+    def create_job(self, song_name: str, input_path: str | Path) -> Job:
+        job = Job(id=uuid.uuid4().hex[:12], song_name=song_name, input_path=Path(input_path))
+        out = Path(self.settings.output_folder) / job.id
+        job.output_dir = out
+        (out / "stems").mkdir(parents=True, exist_ok=True)
+        (out / "midi").mkdir(parents=True, exist_ok=True)
+        self.jobs[job.id] = job
+        return job
+
+    @staticmethod
+    def _emit(job: Job, event: dict) -> None:
+        """Push an event from the event loop thread (plain put_nowait)."""
+        job.events.put_nowait(event)
+
+    def _finish_cancelled(self, job: Job) -> None:
+        """Idempotent cancel: mark cancelled, discard this job's output, notify SSE."""
+        if job.status == STATUS_CANCELLED:
+            return
+        job.status = STATUS_CANCELLED
+        job.error = "Cancelled"
+        if job.output_dir:
+            shutil.rmtree(job.output_dir, ignore_errors=True)
+        self._emit(job, {"type": "cancelled", "message": "Cancelled"})
+
+    async def separate(self, job: Job) -> None:
+        if job.cancel.is_set():
+            self._finish_cancelled(job)
+            return
+        job.status = STATUS_SEPARATING
+        async with self._lock:
+            try:
+                if job.cancel.is_set():
+                    self._finish_cancelled(job)
+                    return
+                loop = asyncio.get_running_loop()
+
+                def emit(event: dict) -> None:
+                    # Called from the separator's worker thread -> thread-safe push.
+                    loop.call_soon_threadsafe(job.events.put_nowait, event)
+
+                sep = await asyncio.to_thread(
+                    self._sep_factory, precision=self.settings.separation_precision,
+                    device=self.settings.separation_device)
+                await asyncio.to_thread(
+                    sep.separate, str(job.input_path), job.output_dir / "stems",
+                    lambda pct: emit({"type": "progress", "phase": "separating", "pct": pct}))
+                if job.cancel.is_set():
+                    self._finish_cancelled(job)
+                    return
+                job.status = STATUS_READY
+                emit({"type": "stems", "stems": STEMS})
+            except asyncio.CancelledError:
+                self._finish_cancelled(job)
+            except Exception as exc:
+                msg = _hf_setup_hint(exc)
+                job.status = STATUS_FAILED
+                job.error = msg
+                self._emit(job, {"type": "failed", "message": msg})
+
+    async def transcribe(self, job: Job, stems: list[str], instrument_by_stem: dict[str, str],
+                         temperature: float, beam_size: int, batch_size: int) -> None:
+        job.status = STATUS_TRANSCRIBING
+        async with self._lock:
+            try:
+                tr = await asyncio.to_thread(
+                    self._tr_factory, model_size=self.settings.model_size,
+                    device=self.settings.transcription_device)
+                loop = asyncio.get_running_loop()
+                for stem in stems:
+                    if job.cancel.is_set():
+                        self._finish_cancelled(job)
+                        return
+                    self._emit(job, {"type": "progress", "phase": "transcribing",
+                                     "stem": stem, "pct": 0})
+                    try:
+                        def on_chunk(completed, total, stem=stem):
+                            # Called from the worker thread -> thread-safe push.
+                            loop.call_soon_threadsafe(
+                                job.events.put_nowait,
+                                {"type": "progress", "phase": "transcribing",
+                                 "stem": stem, "pct": round(100.0 * completed / total)})
+                        midi_bytes = await asyncio.to_thread(
+                            tr.transcribe, job.output_dir / "stems" / f"{stem}.wav", stem,
+                            instrument_by_stem.get(stem) or None, temperature, beam_size,
+                            batch_size, on_chunk)
+                        out = job.output_dir / "midi" / f"{job.song_name}_{stem}.mid"
+                        out.write_bytes(midi_bytes)
+                        self._emit(job, {"type": "midi", "stem": stem, "file": out.name})
+                    except Exception as exc:
+                        if _is_cuda_oom(exc):
+                            # VRAM exhausted at the KV-cache stage: continuing to
+                            # the next stem would OOM again, so fail the job.
+                            job.status = STATUS_FAILED
+                            job.error = _OOM_MESSAGE
+                            self._emit(job, {"type": "failed", "message": _OOM_MESSAGE})
+                            return
+                        # One stem failing must not stop the others (non-terminal).
+                        self._emit(job, {"type": "error", "message": f"{stem}: {exc}"})
+            except Exception as exc:
+                msg = _hf_setup_hint(exc)
+                job.status = STATUS_FAILED
+                job.error = msg
+                self._emit(job, {"type": "failed", "message": msg})
+                return
+        if job.cancel.is_set():
+            self._finish_cancelled(job)
+        else:
+            job.status = STATUS_DONE
+            self._emit(job, {"type": "done"})

app/separator.py

@@ -0,0 +1,187 @@
+"""BS-RoFormer-SW separation: torch DSP around the ONNX model."""
+
+from __future__ import annotations
+
+import torch
+
+SR = 44100
+N_FFT = 2048
+HOP_LENGTH = 512
+WIN_LENGTH = 2048
+CHUNK_FRAMES = 345        # model traced at 4 s @ 44.1 kHz (176400 samples)
+CHUNK_HOP_FRAMES = 220    # 125-frame overlap (~1.45 s) for crossfading
+OVERLAP_FRAMES = CHUNK_FRAMES - CHUNK_HOP_FRAMES  # 125
+
+# Order must match the ONNX output channels.
+STEMS = ["bass", "drums", "other", "vocals", "guitar", "piano"]
+
+
+def _window():
+    return torch.hann_window(WIN_LENGTH)
+
+
+def stft(audio: torch.Tensor) -> torch.Tensor:
+    """[2, N] float32 @44.1kHz -> [2, 1025, F] complex spectrogram."""
+    return torch.stft(
+        audio, n_fft=N_FFT, hop_length=HOP_LENGTH, win_length=WIN_LENGTH,
+        window=_window(), center=True, return_complex=True,
+    )
+
+
+def istft(spec: torch.Tensor, length: int | None = None) -> torch.Tensor:
+    """[2, 1025, F] -> [2, N] audio. Pass length to reconstruct the exact N."""
+    return torch.istft(
+        spec, n_fft=N_FFT, hop_length=HOP_LENGTH, win_length=WIN_LENGTH,
+        window=_window(), center=True, length=length,
+    )
+
+
+def split_into_chunks(spec: torch.Tensor) -> list[torch.Tensor]:
+    """Split [2,1025,F] into [2,1025,345] chunks, stride CHUNK_HOP_FRAMES, pad last."""
+    total = spec.shape[-1]
+    if total <= CHUNK_FRAMES:
+        return [torch.nn.functional.pad(spec, (0, CHUNK_FRAMES - total))]
+    n_chunks = (total - CHUNK_FRAMES + CHUNK_HOP_FRAMES - 1) // CHUNK_HOP_FRAMES + 1
+    chunks = []
+    for i in range(n_chunks):
+        start = i * CHUNK_HOP_FRAMES
+        piece = spec[..., start:start + CHUNK_FRAMES]
+        if piece.shape[-1] < CHUNK_FRAMES:
+            piece = torch.nn.functional.pad(piece, (0, CHUNK_FRAMES - piece.shape[-1]))
+        chunks.append(piece)
+    return chunks
+
+
+def overlap_add(chunks: list[torch.Tensor], total_frames: int) -> torch.Tensor:
+    """Reverse of split_into_chunks with a linear crossfade over the overlap.
+
+    Chunk i starts at frame i*CHUNK_HOP_FRAMES. The overlap region gets a
+    linear ramp 0->1 on the incoming chunk and 1->0 on existing content, which
+    sums to exactly 1 for identical overlap content (exact reconstruction).
+    """
+    if not chunks:
+        raise ValueError("no chunks to overlap-add")
+    out = chunks[0][..., :total_frames].clone()
+    for i in range(1, len(chunks)):
+        chunk = chunks[i]
+        start = i * CHUNK_HOP_FRAMES
+        if start >= total_frames:
+            break
+        end = min(start + CHUNK_FRAMES, total_frames)
+        over = min(OVERLAP_FRAMES, end - start)
+        ramp = torch.linspace(0.0, 1.0, over).reshape(1, 1, over)  # float32
+        out[..., start:start + over] = (
+            out[..., start:start + over] * (1 - ramp) + chunk[..., :over] * ramp)
+        if end > out.shape[-1]:
+            tail = end - out.shape[-1]
+            out = torch.cat([out, chunk[..., over:over + tail]], dim=-1)
+    return out[..., :total_frames]
+
+
+def mask_and_synthesize(input_spec: torch.Tensor, mask: torch.Tensor,
+                        length: int | None = None) -> torch.Tensor:
+    """Apply a per-stem mask [2,1025,F] to input_spec, ISTFT back to audio [2,N]."""
+    return istft(input_spec * mask, length=length)
+
+
+from pathlib import Path
+
+import numpy as np
+import onnxruntime as ort
+import soundfile as sf
+
+
+MODEL_ID = "elicwhite/bs-roformer-sw-6stem-onnx"
+MODEL_FILES = {"fp16": "bs_roformer_sw_6stem_fp16.onnx", "fp32": "bs_roformer_sw_6stem_fp32.onnx"}
+MODEL_CACHE = Path.home() / ".cache" / "audio-to-midi" / "separator"
+
+
+def load_audio(path: str | Path) -> tuple[torch.Tensor, int]:
+    """Decode any soundfile-readable file to stereo float32 @ 44.1 kHz."""
+    data, sr = sf.read(str(path), always_2d=True, dtype="float32")  # [N, ch]
+    if data.shape[1] == 1:
+        data = np.repeat(data, 2, axis=1)
+    elif data.shape[1] > 2:
+        data = data[:, :2]
+    audio = torch.from_numpy(data.T).float()  # [ch, N]
+    if sr != SR:
+        target = int(audio.shape[1] * SR / sr)
+        audio = torch.stack([
+            torch.nn.functional.interpolate(
+                audio[c:c+1, None, :], size=target, mode="linear", align_corners=False)[0, 0]
+            for c in range(2)])
+    return audio, SR
+
+
+def _download_model(precision: str) -> Path:
+    """Return the ONNX path from MODEL_CACHE, downloading only if absent.
+
+    local_files_only first: the plain call does a Hub HEAD check on every
+    invocation, which retries ~25s (x2, the CPU fallback re-calls this) before
+    any session is created when the machine's Python TLS stack is broken.
+    """
+    from huggingface_hub import hf_hub_download
+    MODEL_CACHE.mkdir(parents=True, exist_ok=True)
+    kw = dict(repo_id=MODEL_ID, filename=MODEL_FILES[precision], cache_dir=MODEL_CACHE)
+    try:
+        return Path(hf_hub_download(**kw, local_files_only=True))
+    except Exception:
+        # Not cached yet (fresh machine) -> normal download.
+        return Path(hf_hub_download(**kw))
+
+
+def _default_session_factory(precision: str, device: str) -> ort.InferenceSession:
+    model_path = _download_model(precision)
+    providers = (["CUDAExecutionProvider", "CPUExecutionProvider"]
+                 if device == "cuda" else ["CPUExecutionProvider"])
+    return ort.InferenceSession(str(model_path), providers=providers)
+
+
+class Separator:
+    def __init__(self, precision: str = "fp16", device: str = "auto", session_factory=None):
+        self.precision = precision if precision in MODEL_FILES else "fp16"
+        from app.settings import resolve_device
+        self.device = resolve_device(device)
+        factory = session_factory or _default_session_factory
+        try:
+            self.session = factory(self.precision, self.device)
+        except Exception:
+            # GPU runtime failed (missing provider, download hiccup) -> CPU.
+            self.session = _default_session_factory(self.precision, "cpu")
+            self.device = "cpu"
+
+    def _run_chunk(self, spec_chunk: torch.Tensor):
+        """[2,1025,345] complex -> ([6,2,1025,345] real, [6,2,1025,345] imag) as tensors.
+
+        The ONNX model emits the ALREADY-MASKED (separated) spectrograms per stem.
+        See: https://huggingface.co/elicwhite/bs-roformer-sw-6stem-onnx
+        Wrapper docstring: "Do not multiply them by the input again."
+        """
+        r = spec_chunk[None, ...].real.float().numpy()
+        i = spec_chunk[None, ...].imag.float().numpy()
+        out_r, out_i = self.session.run(None, {"spec_real": r, "spec_imag": i})
+        return torch.from_numpy(out_r), torch.from_numpy(out_i)
+
+    def separate(self, in_path, out_dir, on_progress=None) -> list[Path]:
+        audio, _ = load_audio(in_path)
+        spec = stft(audio.to("cpu"))
+        chunks = split_into_chunks(spec)
+        out_dir = Path(out_dir)
+        out_dir.mkdir(parents=True, exist_ok=True)
+        acc = [None] * len(STEMS)  # per-stem separated chunk lists
+        for idx, chunk in enumerate(chunks):
+            sep_r, sep_i = self._run_chunk(chunk)
+            for s in range(len(STEMS)):
+                separated_spec = sep_r[0, s] + 1j * sep_i[0, s]  # [2,1025,345]
+                acc[s] = acc[s] or []
+                acc[s].append(separated_spec)
+            if on_progress:
+                on_progress(100.0 * (idx + 1) / len(chunks))
+        results = []
+        for s, name in enumerate(STEMS):
+            recon = overlap_add(acc[s], spec.shape[-1])
+            audio_s = istft(recon, length=audio.shape[1]).clamp(-1.0, 1.0)
+            path = out_dir / f"{name}.wav"
+            sf.write(str(path), audio_s.T.numpy(), SR)
+            results.append(path)
+        return results

app/settings.py

@@ -0,0 +1,49 @@
+"""Persistent app settings."""
+
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+import torch
+
+# Order must match the BS-RoFormer-SW ONNX output channels (0-5).
+STEMS = ["bass", "drums", "other", "vocals", "guitar", "piano"]
+
+SETTINGS_FILE = Path(__file__).parent / "settings.json"
+
+
+@dataclass
+class Settings:
+    separation_device: str = "auto"      # auto | cuda | cpu
+    separation_precision: str = "fp16"   # fp16 | fp32
+    model_size: str = "large"            # small | medium | large
+    instrument_by_stem: dict = field(default_factory=dict)  # stem -> instrument name or "" (auto)
+    temperature: float = 0.0             # 0 = deterministic
+    beam_size: int = 4                   # 1 = greedy
+    batch_size: int = 1                  # >1 disables prelude forcing & multiplies KV-cache VRAM
+    transcription_device: str = "auto"   # auto | cuda | cpu
+    output_folder: str = "./output"
+    keep_stems: bool = True
+    remember_selection: bool = True
+
+
+DEFAULT_SETTINGS = Settings()
+
+
+def load_settings() -> Settings:
+    if not SETTINGS_FILE.exists():
+        return DEFAULT_SETTINGS
+    data = json.loads(SETTINGS_FILE.read_text(encoding="utf-8"))
+    merged = asdict(DEFAULT_SETTINGS)
+    merged.update({k: v for k, v in data.items() if k in merged})
+    return Settings(**merged)
+
+
+def save_settings(settings: Settings) -> None:
+    SETTINGS_FILE.write_text(json.dumps(asdict(settings), indent=2), encoding="utf-8")
+
+
+def resolve_device(requested: str) -> str:
+    if requested in ("cuda", "cpu"):
+        return requested
+    return "cuda" if torch.cuda.is_available() else "cpu"