splitscore 0.1.1__tar.gz

splitscore-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sean D
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

splitscore-0.1.1/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: splitscore
+Version: 0.1.1
+Summary: Separate audio into stems with BS-RoFormer-SW, then transcribe to MIDI with MuScriptor
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SeanDolan0/splitscore
+Project-URL: Repository, https://github.com/SeanDolan0/splitscore
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: <3.14,>=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.7
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn[standard]>=0.30
+Requires-Dist: onnxruntime-gpu<1.27,>=1.21
+Requires-Dist: soundfile>=0.12
+Requires-Dist: huggingface-hub>=0.24
+Requires-Dist: muscriptor==0.3.0
+Dynamic: license-file
+
+# SplitScore
+
+Separate an audio file into 6 stems with **BS-RoFormer-SW**, then transcribe the stems
+you choose to **MIDI** with **MuScriptor**. A local web console (FastAPI + vanilla JS).
+
+```
+audio ──▶ BS-RoFormer-SW ──▶ 6 stems ──▶ MuScriptor ──▶ per-stem .mid
+```
+
+## Quick start
+
+```bash
+uvx splitscore
+```
+
+This auto-detects your NVIDIA GPU and installs the correct CUDA torch backend.
+First run downloads models (~3 GB total) into `~/.cache/`.
+
+## Requirements
+
+- Windows 11 / Linux, Python 3.13, [uv](https://docs.astral.sh/uv/)
+- NVIDIA GPU recommended — requires [CUDA 12.x Toolkit](https://developer.nvidia.com/cuda-downloads) installed for GPU acceleration (auto-detected; falls back to CPU if missing)
+- Apple Silicon (MPS) and AMD (ROCm) GPUs are also supported
+
+## Setup (development)
+
+```bash
+uv run python sync.py          # auto-detect GPU, install correct CUDA torch
+uv run python -m app           # start server
+```
+
+MuScriptor weights are **gated**: you need a free Hugging Face account.
+
+1. Open https://huggingface.co/muscriptor/muscriptor and accept the **CC BY-NC 4.0**
+   (non-commercial) license.
+2. Log in from the terminal:
+   ```bash
+   uv run hf auth login
+   ```
+   (or export `HF_TOKEN=hf_...` in your shell).
+
+## Usage
+
+1. Drop an audio file (wav / mp3 / flac / ogg / m4a / aiff).
+2. Separation runs automatically — wait for the 6 stems to appear.
+3. Tick the stems you want, adjust per-stem instrument (empty = auto), hit **Transcribe selected to MIDI**.
+4. Download the `.mid` files. Each stem is named `<song>_<stem>.mid`.
+
+Every setting (model size, device, precision, temperature, beam/batch size, output folder)
+is adjustable in the Settings panel and persists across runs.
+
+## Notes & limitations
+
+- MuScriptor does not preserve velocity — output is timing, pitch, and instrument.
+- Drums and "other" stems tend to transcribe poorly to readable MIDI; melodic stems
+  (vocals, piano, guitar, bass) give the best results.
+- MIDI + stem WAVs are written under the configured output folder
+  (`./output/<job_id>/stems|midi/`).
+- One job at a time by design.
+
+## License
+
+- **Code:** MIT — see [LICENSE](LICENSE).
+- **Models:** the separation model and the MuScriptor weights are separate and
+  distributed under their own licenses. In particular, MuScriptor's weights are
+  **CC BY-NC 4.0** (non-commercial) and gated on Hugging Face; that restriction
+  applies to the models regardless of this project's MIT license.

splitscore-0.1.1/README.md

@@ -0,0 +1,67 @@
+# SplitScore
+
+Separate an audio file into 6 stems with **BS-RoFormer-SW**, then transcribe the stems
+you choose to **MIDI** with **MuScriptor**. A local web console (FastAPI + vanilla JS).
+
+```
+audio ──▶ BS-RoFormer-SW ──▶ 6 stems ──▶ MuScriptor ──▶ per-stem .mid
+```
+
+## Quick start
+
+```bash
+uvx splitscore
+```
+
+This auto-detects your NVIDIA GPU and installs the correct CUDA torch backend.
+First run downloads models (~3 GB total) into `~/.cache/`.
+
+## Requirements
+
+- Windows 11 / Linux, Python 3.13, [uv](https://docs.astral.sh/uv/)
+- NVIDIA GPU recommended — requires [CUDA 12.x Toolkit](https://developer.nvidia.com/cuda-downloads) installed for GPU acceleration (auto-detected; falls back to CPU if missing)
+- Apple Silicon (MPS) and AMD (ROCm) GPUs are also supported
+
+## Setup (development)
+
+```bash
+uv run python sync.py          # auto-detect GPU, install correct CUDA torch
+uv run python -m app           # start server
+```
+
+MuScriptor weights are **gated**: you need a free Hugging Face account.
+
+1. Open https://huggingface.co/muscriptor/muscriptor and accept the **CC BY-NC 4.0**
+   (non-commercial) license.
+2. Log in from the terminal:
+   ```bash
+   uv run hf auth login
+   ```
+   (or export `HF_TOKEN=hf_...` in your shell).
+
+## Usage
+
+1. Drop an audio file (wav / mp3 / flac / ogg / m4a / aiff).
+2. Separation runs automatically — wait for the 6 stems to appear.
+3. Tick the stems you want, adjust per-stem instrument (empty = auto), hit **Transcribe selected to MIDI**.
+4. Download the `.mid` files. Each stem is named `<song>_<stem>.mid`.
+
+Every setting (model size, device, precision, temperature, beam/batch size, output folder)
+is adjustable in the Settings panel and persists across runs.
+
+## Notes & limitations
+
+- MuScriptor does not preserve velocity — output is timing, pitch, and instrument.
+- Drums and "other" stems tend to transcribe poorly to readable MIDI; melodic stems
+  (vocals, piano, guitar, bass) give the best results.
+- MIDI + stem WAVs are written under the configured output folder
+  (`./output/<job_id>/stems|midi/`).
+- One job at a time by design.
+
+## License
+
+- **Code:** MIT — see [LICENSE](LICENSE).
+- **Models:** the separation model and the MuScriptor weights are separate and
+  distributed under their own licenses. In particular, MuScriptor's weights are
+  **CC BY-NC 4.0** (non-commercial) and gated on Hugging Face; that restriction
+  applies to the models regardless of this project's MIT license.

splitscore-0.1.1/app/__init__.py

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

splitscore-0.1.1/app/__main__.py

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

splitscore-0.1.1/app/cli.py

@@ -0,0 +1,121 @@
+"""CLI entry point for `uvx splitscore`.
+
+Detects GPU vendor, installs the correct torch + onnxruntime backends,
+then starts the server.
+"""
+from __future__ import annotations
+
+import platform
+import shutil
+import subprocess
+import sys
+import webbrowser
+
+
+def _detect_vendor() -> str:
+    """Return gpu vendor: nvidia | amd | intel | apple | none."""
+    system = platform.system()
+
+    # NVIDIA
+    if shutil.which("nvidia-smi"):
+        return "nvidia"
+
+    # Apple Silicon
+    if system == "Darwin" and platform.machine() == "arm64":
+        return "apple"
+
+    # AMD (Linux only — ROCm)
+    if system == "Linux":
+        try:
+            lspci = subprocess.check_output(["lspci"], text=True, timeout=5)
+            if "amd" in lspci.lower():
+                return "amd"
+        except (subprocess.SubprocessError, FileNotFoundError):
+            pass
+
+    # Intel (Windows — DirectML)
+    if system == "Windows":
+        try:
+            lspci = subprocess.check_output(["lspci"], text=True, timeout=5)
+            if "intel" in lspci.lower():
+                return "intel"
+        except (subprocess.SubprocessError, FileNotFoundError):
+            pass
+
+    return "none"
+
+
+def _install_onnxruntime(vendor: str) -> None:
+    """Install the correct onnxruntime variant for the GPU vendor."""
+    pkgs = {
+        "nvidia": "onnxruntime-gpu>=1.21,<1.27",
+        "amd": "onnxruntime-rocm",
+        "intel": "onnxruntime-directml",
+        "apple": "onnxruntime",
+        "none": "onnxruntime",
+    }
+    pkg = pkgs[vendor]
+    print(f"Installing {pkg} ...")
+    subprocess.check_call([sys.executable, "-m", "pip", "install", pkg])
+
+
+def _install_torch(vendor: str) -> None:
+    """Install the correct torch variant for the GPU vendor."""
+    try:
+        import torch
+        # Check if the correct backend is actually available
+        if vendor == "nvidia" and torch.cuda.is_available():
+            return
+        if vendor == "amd" and torch.cuda.is_available():  # ROCm uses cuda device
+            return
+        if vendor in ("apple", "none"):
+            return  # default torch is fine
+    except ImportError:
+        pass
+
+    index_urls = {
+        "nvidia": "https://download.pytorch.org/whl/cu130",
+        "amd": "https://download.pytorch.org/whl/rocm6.2",
+    }
+    if vendor in index_urls:
+        print(f"Installing torch ({vendor}) ...")
+        subprocess.check_call([
+            sys.executable, "-m", "pip", "install",
+            "--index-url", index_urls[vendor],
+            "--trusted-host", "download.pytorch.org",
+            "torch>=2.7",
+        ])
+    else:
+        print("Installing torch (default) ...")
+        subprocess.check_call([sys.executable, "-m", "pip", "install", "torch>=2.7"])
+
+
+def _ensure_backends() -> None:
+    """Make sure torch and onnxruntime are importable with correct backends."""
+    # Check torch
+    try:
+        import torch  # noqa: F401
+    except ImportError:
+        vendor = _detect_vendor()
+        print(f"GPU detected: {vendor}")
+        _install_torch(vendor)
+    else:
+        vendor = _detect_vendor()
+
+    # Check onnxruntime GPU provider
+    try:
+        import onnxruntime as ort
+        providers = ort.get_available_providers()
+        has_gpu = any(p not in ("CPUExecutionProvider",) for p in providers)
+        if not has_gpu and vendor not in ("apple", "none"):
+            _install_onnxruntime(vendor)
+    except ImportError:
+        _install_onnxruntime(vendor)
+
+
+def main() -> None:
+    _ensure_backends()
+    import uvicorn
+    url = "http://127.0.0.1:8000"
+    webbrowser.open(url)
+    uvicorn.run("app.main:app", host="127.0.0.1", port=8000)

splitscore-0.1.1/app/gpu.py

@@ -0,0 +1,119 @@
+"""GPU detection and backend resolution for onnxruntime and torch."""
+from __future__ import annotations
+
+import platform
+import shutil
+import subprocess
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class GpuInfo:
+    vendor: str          # nvidia | amd | intel | apple | none
+    name: str            # human-readable name, e.g. "NVIDIA GeForce RTX 4060"
+    preferred_device: str  # cuda | mps | xpu | cpu
+
+
+def _run(cmd: list[str], timeout: float = 5) -> str | None:
+    try:
+        return subprocess.check_output(cmd, text=True, timeout=timeout).strip()
+    except (subprocess.SubprocessError, FileNotFoundError):
+        return None
+
+
+def _detect_nvidia() -> GpuInfo | None:
+    if not shutil.which("nvidia-smi"):
+        return None
+    out = _run(["nvidia-smi", "--query-gpu=name", "--format=csv,noheader"])
+    if not out:
+        return None
+    name = out.splitlines()[0].strip()
+    return GpuInfo(vendor="nvidia", name=name, preferred_device="cuda")
+
+
+def _detect_amd() -> GpuInfo | None:
+    if platform.system() != "Linux":
+        return None
+    lspci = _run(["lspci"])
+    if not lspci or "amd" not in lspci.lower():
+        return None
+    # Check for ROCm runtime
+    if not shutil.which("rocminfo"):
+        return GpuInfo(vendor="amd", name="AMD GPU (no ROCm)", preferred_device="cpu")
+    return GpuInfo(vendor="amd", name="AMD GPU (ROCm)", preferred_device="cuda")
+
+
+def _detect_intel() -> GpuInfo | None:
+    if platform.system() != "Windows":
+        return None  # DirectML is Windows-only
+    lspci = _run(["lspci"])  # may not exist on Windows
+    if not lspci:
+        return None
+    if "intel" not in lspci.lower():
+        return None
+    return GpuInfo(vendor="intel", name="Intel GPU (DirectML)", preferred_device="cpu")
+
+
+def _detect_apple_silicon() -> GpuInfo | None:
+    if platform.system() != "Darwin":
+        return None
+    if platform.machine() != "arm64":
+        return None
+    return GpuInfo(vendor="apple", name="Apple Silicon (MPS)", preferred_device="mps")
+
+
+def detect_gpu() -> GpuInfo:
+    """Detect the best available GPU and return device info.
+
+    Detection order: NVIDIA → AMD → Intel → Apple Silicon → CPU fallback.
+    """
+    for detector in (_detect_nvidia, _detect_amd, _detect_intel, _detect_apple_silicon):
+        result = detector()
+        if result:
+            return result
+    return GpuInfo(vendor="none", name="No GPU detected", preferred_device="cpu")
+
+
+# --- onnxruntime provider resolution ---
+
+# Maps device string → ordered list of onnxruntime execution providers to try.
+_PROVIDER_MAP: dict[str, list[str]] = {
+    "cuda": ["CUDAExecutionProvider", "CPUExecutionProvider"],
+    "rocm": ["ROCMExecutionProvider", "CPUExecutionProvider"],
+    "directml": ["DmlExecutionProvider", "CPUExecutionProvider"],
+    "mps": ["CPUExecutionProvider"],   # ONNX has no Apple GPU provider
+    "xpu": ["CPUExecutionProvider"],   # ONNX has no Intel XPU provider
+    "cpu": ["CPUExecutionProvider"],
+}
+
+
+def resolve_onnx_provider(device: str) -> list[str]:
+    """Return ordered list of onnxruntime providers for the given device."""
+    return _PROVIDER_MAP.get(device, ["CPUExecutionProvider"])
+
+
+# --- torch device resolution ---
+
+def resolve_torch_device(device: str) -> str:
+    """Resolve a device string ('auto', 'cuda', 'mps', 'xpu', 'cpu').
+
+    Returns a torch-compatible device string. Falls back to 'cpu' if the
+    requested backend is not available.
+    """
+    import torch
+
+    if device == "auto":
+        gpu = detect_gpu()
+        device = gpu.preferred_device
+
+    if device == "cuda" and torch.cuda.is_available():
+        return "cuda"
+    if device == "mps" and hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+        return "mps"
+    if device == "xpu" and hasattr(torch, "xpu") and torch.xpu.is_available():
+        return "xpu"
+    if device in ("cuda", "mps", "xpu"):
+        # Requested but unavailable — fall back to CPU with a warning
+        import warnings
+        warnings.warn(f"{device} requested but not available, falling back to CPU")
+    return "cpu"

splitscore-0.1.1/app/main.py

@@ -0,0 +1,232 @@
+"""FastAPI backend: routes, SSE event stream, static frontend."""
+
+from __future__ import annotations
+
+import asyncio
+import io
+import json
+import webbrowser
+import zipfile
+from dataclasses import asdict
+from pathlib import Path
+
+from fastapi import FastAPI, File, HTTPException, UploadFile
+from fastapi.responses import FileResponse, Response, 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
+from app.gpu import detect_gpu
+
+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/hardware")
+async def get_hardware():
+    """Report what compute hardware is available and which provider the models use."""
+    import importlib
+    info = {"torch": None, "onnxruntime": None, "gpu": None,
+            "settings_device": PIPELINE.settings.separation_device,
+            "separator_actual": None}
+
+    # torch
+    try:
+        torch = importlib.import_module("torch")
+        info["torch"] = {
+            "version": torch.__version__,
+            "cuda_available": torch.cuda.is_available(),
+            "cuda_version": torch.version.cuda or None,
+            "gpu_name": torch.cuda.get_device_name(0) if torch.cuda.is_available() else None,
+            "gpu_memory_gb": round(torch.cuda.get_device_properties(0).total_memory / 1e9, 1) if torch.cuda.is_available() else None,
+        }
+    except Exception:
+        info["torch"] = {"version": "not installed", "cuda_available": False}
+
+    # onnxruntime
+    try:
+        ort = importlib.import_module("onnxruntime")
+        info["onnxruntime"] = {
+            "version": ort.__version__,
+            "providers": ort.get_available_providers(),
+        }
+    except Exception:
+        info["onnxruntime"] = {"version": "not installed", "providers": []}
+
+    # gpu detection (runtime)
+    gpu = detect_gpu()
+    info["gpu"] = {"vendor": gpu.vendor, "name": gpu.name, "preferred_device": gpu.preferred_device}
+
+    # actual device used by the separator (if any job has run)
+    for job in PIPELINE.jobs.values():
+        if hasattr(job, "_separator_device"):
+            info["separator_actual"] = job._separator_device
+            break
+
+    return info
+
+
+@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.get("/output/{job_id}/stems")
+async def download_stems_zip(job_id: str):
+    """Return all stems as a zip archive for bulk download."""
+    base = Path(PIPELINE.settings.output_folder).resolve()
+    stems_dir = (base / job_id / "stems").resolve()
+    if not stems_dir.is_relative_to(base) or not stems_dir.is_dir():
+        raise HTTPException(404, "Stems not found")
+    wav_files = sorted(stems_dir.glob("*.wav"))
+    if not wav_files:
+        raise HTTPException(404, "No stems found")
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+        for wav in wav_files:
+            zf.write(wav, wav.name)
+    buf.seek(0)
+    zip_name = f"{stems_dir.parent.name}_stems.zip"
+    return Response(
+        content=buf.read(),
+        media_type="application/zip",
+        headers={"Content-Disposition": f'attachment; filename="{zip_name}"'},
+    )
+
+
+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)