deploy from local repo (runtime files only)

README.md

@@ -1,13 +1,61 @@
 ---
-title: Stemflipper
-emoji: 😻
-colorFrom: gray
-colorTo: yellow
+title: StemFlipper
+emoji: 🎛️
+colorFrom: purple
+colorTo: blue
 sdk: gradio
 sdk_version: 6.19.0
-python_version: '3.13'
 app_file: app.py
+python_version: "3.10.13"
 pinned: false
+license: mit
+short_description: Song → stems → MIDI → editable instruments → DAW bundle
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🎛️ StemFlipper
+
+Upload a song → AI source-separation into stems → each stem becomes **transcribed MIDI +
+a playable sliced-sample instrument (SFZ)** → download a **DAW project bundle**:
+
+```
+song/
+  stems/*.wav          separated stems (htdemucs)
+  midi/song.mid        multitrack SMF Format 1 (tempo map) + per-stem .mid
+  instruments/*/*.sfz  sliced-sample instruments (load in sfizz / Sforzando / DecentSampler)
+  project.RPP          Reaper project with the stems arranged at the right tempo
+  manifest.json        tempo, key, stem→file map
+  README.txt           how to import into any DAW
+```
+
+## Run locally
+
+```bash
+python3.10 -m venv .venv && .venv/bin/pip install -r requirements.txt
+.venv/bin/python -m stemflipper song.mp3 -o out/     # CLI
+.venv/bin/python app.py                              # Gradio UI at :7860
+.venv/bin/pytest -m "not slow"                       # tests
+```
+
+## Hardware notes
+
+- **This Space runs on free CPU hardware** — separation of a 3–4 min song takes several
+  minutes. The queue + progress bar handle it; just wait.
+- **ZeroGPU upgrade path** (needs a PRO account): Space Settings → Hardware → ZeroGPU.
+  The code is already compatible — `app.py` wraps only the separation stage in
+  `@spaces.GPU(duration=180)`; everything else stays on CPU.
+
+## Honest limitations (MVP)
+
+- Transcription is an *editable starting point*, not a perfect score. Drums use an onset
+  heuristic that misses overlapping hits.
+- Sampler slices inherit any bleed/reverb baked into the separated stems.
+- Separation weights (htdemucs) are trained on MUSDB18 (non-commercial training data) —
+  this app is a **research/educational demo**, not a commercial service. See `PLAN.md`
+  ("Licensing") for the retrain-before-monetization gate.
+
+## Repo map
+
+`stemflipper/` pipeline library (CLI: `python -m stemflipper`) · `app.py` Gradio adapter ·
+`tests/` pytest suite with a deterministic synthetic test song · `PLAN.md` + `research/`
+the research/architecture brief · `HANDOFF.md` build state, task queue, invariants ·
+`dataset/`, `web/` upcoming (see HANDOFF.md).

app.py

@@ -0,0 +1,105 @@
+"""StemFlipper Gradio app — thin adapter over stemflipper.pipeline.
+
+The same file runs locally, on a free CPU Space, and on ZeroGPU: only the
+separation stage is GPU-relevant, so it alone is wrapped with @spaces.GPU
+(a no-op everywhere else).
+"""
+
+import tempfile
+from pathlib import Path
+
+import gradio as gr
+
+from stemflipper import separate
+from stemflipper.audio_io import duration_of
+from stemflipper.pipeline import run_pipeline
+
+MAX_AUDIO_MINUTES = 8
+PREVIEW_STEMS = ("vocals", "drums", "bass", "other")
+
+try:
+    import spaces
+
+    _separate_fn = spaces.GPU(duration=180)(separate.separate_stems)
+except Exception:
+    _separate_fn = separate.separate_stems
+
+_HEADER = """\
+# 🎛️ StemFlipper
+
+Upload a song → AI separates it into stems → each stem becomes **MIDI + a playable
+sliced-sample instrument (SFZ)** → download a **DAW project bundle** (stems, MIDI,
+instruments, Reaper project, manifest).
+
+*Research/educational demo. Separation runs on CPU on this Space — a 3–4 min song takes
+several minutes; the progress bar keeps moving. Transcription is an editable starting
+point, not a perfect score.*
+"""
+
+
+def flip(audio_path, model, progress=gr.Progress()):
+    if not audio_path:
+        raise gr.Error("Upload an audio file first.")
+    if duration_of(audio_path) > MAX_AUDIO_MINUTES * 60:
+        raise gr.Error(f"Please keep songs under {MAX_AUDIO_MINUTES} minutes for this demo.")
+
+    workdir = Path(tempfile.mkdtemp(prefix="stemflipper_"))
+    result = run_pipeline(
+        audio_path,
+        workdir,
+        model=model,
+        progress=lambda frac, desc: progress(frac, desc=desc),
+        separate_fn=_separate_fn,
+    )
+    manifest = result["manifest"]
+
+    lines = [
+        f"**tempo** {manifest['tempo']} BPM · **key** {manifest['key']} · "
+        f"**duration** {manifest['duration']:.0f}s · model `{manifest['separation_model']}`",
+        "",
+        "| stem | notes | instrument |",
+        "|---|---|---|",
+    ]
+    for name, meta in manifest["stems"].items():
+        notes = "silent" if meta["silent"] else str(meta["n_notes"])
+        sfz = "SFZ ✓" if meta["instrument_sfz"] else "—"
+        lines.append(f"| {name} | {notes} | {sfz} |")
+    summary = "\n".join(lines)
+
+    bundle = result["bundle_dir"]
+    previews = [
+        str(bundle / "stems" / f"{name}.wav")
+        if (bundle / "stems" / f"{name}.wav").exists()
+        else None
+        for name in PREVIEW_STEMS
+    ]
+    return str(result["zip_path"]), summary, *previews
+
+
+with gr.Blocks(title="StemFlipper") as demo:
+    gr.Markdown(_HEADER)
+    with gr.Row():
+        audio_in = gr.Audio(type="filepath", label="Song (wav/mp3/flac/m4a, ≤8 min)")
+        with gr.Column():
+            model_in = gr.Dropdown(
+                choices=list(separate.MODELS),
+                value=separate.DEFAULT_MODEL,
+                label="Separation model",
+                info="htdemucs = 4 stems (default). htdemucs_6s adds guitar+piano (piano is weak).",
+            )
+            go_btn = gr.Button("Flip it 🎚️", variant="primary")
+    zip_out = gr.File(label="DAW project bundle (.zip)")
+    summary_out = gr.Markdown()
+    with gr.Row():
+        preview_outs = [
+            gr.Audio(label=name, interactive=False) for name in PREVIEW_STEMS
+        ]
+    go_btn.click(
+        flip,
+        inputs=[audio_in, model_in],
+        outputs=[zip_out, summary_out, *preview_outs],
+        api_name="flip",
+    )
+
+if __name__ == "__main__":
+    demo.queue(default_concurrency_limit=1).launch(max_file_size="30mb")

packages.txt

@@ -0,0 +1,2 @@
+ffmpeg
+libsndfile1

requirements.txt

@@ -0,0 +1,11 @@
+# StemFlipper MVP dependency set (staged — frontier deps land with their milestones; see HANDOFF.md)
+audio-separator[cpu]>=0.44,<0.45
+basic-pitch>=0.4,<0.5
+tflite-runtime; sys_platform == "linux"  # basic-pitch inference runtime on the Space (CoreML covers macOS)
+librosa>=0.10,<0.12
+numba>=0.61
+pretty_midi>=0.2.10
+mido>=1.3
+soundfile>=0.12
+gradio>=4
+spaces

stemflipper/__init__.py

@@ -0,0 +1,3 @@
+"""StemFlipper — song -> stems -> MIDI -> editable instruments -> DAW bundle."""
+
+__version__ = "0.1.0"

stemflipper/__main__.py

@@ -0,0 +1,55 @@
+"""CLI: python -m stemflipper song.mp3 -o out/"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from .pipeline import run_pipeline
+from .separate import DEFAULT_MODEL, MODELS
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="stemflipper",
+        description="song -> stems -> MIDI -> editable instruments -> DAW bundle",
+    )
+    parser.add_argument("input", help="audio file (wav/mp3/flac/m4a)")
+    parser.add_argument("-o", "--output", default="out", help="output directory")
+    parser.add_argument(
+        "--model",
+        default=DEFAULT_MODEL,
+        help=f"separation model: {', '.join(MODELS)} (or any audio-separator filename)",
+    )
+    parser.add_argument("--model-dir", default=None, help="model weight cache dir")
+    parser.add_argument("--no-zip", action="store_true", help="skip bundle zip")
+    args = parser.parse_args(argv)
+
+    if not Path(args.input).exists():
+        print(f"error: no such file: {args.input}", file=sys.stderr)
+        return 2
+
+    def progress(frac, desc):
+        print(f"[{frac * 100:5.1f}%] {desc}", flush=True)
+
+    result = run_pipeline(
+        args.input,
+        args.output,
+        model=args.model,
+        model_dir=args.model_dir,
+        progress=progress,
+        make_zip=not args.no_zip,
+    )
+    manifest = result["manifest"]
+    print(f"\nbundle:  {result['bundle_dir']}")
+    if result["zip_path"]:
+        print(f"zip:     {result['zip_path']}")
+    print(f"tempo:   {manifest['tempo']} BPM   key: {manifest['key']}")
+    for name, meta in manifest["stems"].items():
+        note = "silent" if meta["silent"] else f"{meta['n_notes']} notes"
+        sfz = " +sfz" if meta["instrument_sfz"] else ""
+        print(f"  {name:8s} {note}{sfz}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

stemflipper/analyze.py

@@ -0,0 +1,67 @@
+"""Song-level analysis: tempo, beat grid, key."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+# Krumhansl-Schmuckler key profiles (Krumhansl & Kessler 1982).
+_MAJOR_PROFILE = np.array(
+    [6.35, 2.23, 3.48, 2.33, 4.38, 4.09, 2.52, 5.19, 2.39, 3.66, 2.29, 2.88]
+)
+_MINOR_PROFILE = np.array(
+    [6.33, 2.68, 3.52, 5.38, 2.60, 3.53, 2.54, 4.75, 3.98, 2.69, 3.34, 3.17]
+)
+_PITCH_NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]
+
+
+@dataclass
+class Analysis:
+    tempo: float
+    beat_times: list[float]
+    key: str
+    duration: float
+    time_signature: str = "4/4"
+    sr: int = 44100
+
+
+def estimate_tempo(y: np.ndarray, sr: int) -> tuple[float, list[float]]:
+    import librosa
+
+    tempo, beat_frames = librosa.beat.beat_track(y=y, sr=sr)
+    bpm = float(np.atleast_1d(tempo)[0])
+    # octave-error sanity clamp: prefer 70-180 BPM (see PLAN.md quantization pitfalls)
+    while bpm and bpm < 70:
+        bpm *= 2
+    while bpm > 180:
+        bpm /= 2
+    beat_times = librosa.frames_to_time(beat_frames, sr=sr).tolist()
+    return bpm, beat_times
+
+
+def estimate_key(y: np.ndarray, sr: int) -> str:
+    import librosa
+
+    chroma = librosa.feature.chroma_cqt(y=y, sr=sr).mean(axis=1)
+    if chroma.max() <= 0:
+        return "unknown"
+    best_score, best_key = -np.inf, "unknown"
+    for tonic in range(12):
+        rotated = np.roll(chroma, -tonic)
+        for profile, mode in ((_MAJOR_PROFILE, "major"), (_MINOR_PROFILE, "minor")):
+            score = np.corrcoef(rotated, profile)[0, 1]
+            if score > best_score:
+                best_score, best_key = score, f"{_PITCH_NAMES[tonic]} {mode}"
+    return best_key
+
+
+def analyze_audio(y: np.ndarray, sr: int) -> Analysis:
+    tempo, beat_times = estimate_tempo(y, sr)
+    return Analysis(
+        tempo=round(tempo, 2),
+        beat_times=beat_times,
+        key=estimate_key(y, sr),
+        duration=len(y) / sr,
+        sr=sr,
+    )

stemflipper/audio_io.py

@@ -0,0 +1,38 @@
+"""Audio loading/saving helpers. librosa handles mp3/m4a via soundfile/audioread+ffmpeg."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import soundfile as sf
+
+
+def load_audio(path: str | Path, sr: int | None = None, mono: bool = True):
+    """Return (audio, sr). Resamples only if sr is given."""
+    import librosa
+
+    y, out_sr = librosa.load(str(path), sr=sr, mono=mono)
+    return y, int(out_sr)
+
+
+def save_audio(path: str | Path, audio: np.ndarray, sr: int) -> Path:
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    sf.write(str(path), audio, sr)
+    return path
+
+
+def duration_of(path: str | Path) -> float:
+    try:
+        info = sf.info(str(path))
+        return info.frames / info.samplerate
+    except Exception:  # formats libsndfile can't probe (some mp3/m4a) — decode instead
+        import librosa
+
+        return float(librosa.get_duration(path=str(path)))
+
+
+def is_silent(audio: np.ndarray, threshold: float = 1e-4) -> bool:
+    """True when a stem carries no usable signal (e.g. vocals stem of an instrumental)."""
+    return float(np.sqrt(np.mean(audio**2))) < threshold

stemflipper/export.py

@@ -0,0 +1,166 @@
+"""Bundle export: SMF Format-1 MIDI, manifest.json, README.txt, Reaper .RPP, zip.
+
+MVP scope per plan: the .RPP carries tempo + stem audio tracks only (plain-text
+template); MIDI files sit alongside for drag-drop. Inline MIDI embedding in RPP is a
+later task (see HANDOFF.md).
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+
+# GM programs (0-indexed) per canonical stem name
+_STEM_PROGRAMS = {
+    "vocals": 53,  # Voice Oohs
+    "bass": 33,    # Electric Bass (finger)
+    "guitar": 24,  # Nylon Guitar
+    "piano": 0,    # Acoustic Grand
+    "other": 48,   # String Ensemble
+}
+
+_RPP_TRACK = """\
+  <TRACK
+    NAME "{name}"
+    <ITEM
+      POSITION 0
+      LENGTH {length}
+      NAME "{name}"
+      <SOURCE WAVE
+        FILE "{file}"
+      >
+    >
+  >
+"""
+
+_README = """\
+StemFlipper export — {source}
+=================================
+
+tempo: {tempo} BPM   key: {key}   time signature: {timesig}
+
+What's in this folder
+---------------------
+stems/          separated audio stems (drag into any DAW)
+midi/           transcribed MIDI — song.mid is the full multitrack (Format 1,
+                tempo map included); per-stem .mid files for single-track import
+instruments/    sliced-sample instruments (.sfz) built from each stem — load in a
+                free SFZ player (sfizz, Sforzando) or convert with DecentSampler
+project.RPP     Reaper project: opens the stems arranged on tracks at the right
+                tempo. Import midi/*.mid onto tracks, then drop the matching .sfz
+                on an instrument track to make parts editable.
+manifest.json   machine-readable metadata (tempo, key, stem->file mapping)
+
+Honest limitations (MVP)
+------------------------
+- Transcription quality varies by stem; drums use an onset heuristic that misses
+  overlapping hits. Treat MIDI as an editable starting point, not a perfect score.
+- Sampler slices inherit any bleed/reverb baked into the separated stems.
+"""
+
+
+def write_midi(
+    tracks: dict[str, dict], tempo: float, midi_dir: str | Path
+) -> dict[str, Path]:
+    """tracks: {stem_name: {"notes": [...], "is_drum": bool}} -> song.mid + per-stem mids."""
+    import pretty_midi
+
+    midi_dir = Path(midi_dir)
+    midi_dir.mkdir(parents=True, exist_ok=True)
+    written: dict[str, Path] = {}
+
+    def make_pm(subset: dict[str, dict]) -> "pretty_midi.PrettyMIDI":
+        pm = pretty_midi.PrettyMIDI(initial_tempo=tempo)
+        for name, data in subset.items():
+            inst = pretty_midi.Instrument(
+                program=_STEM_PROGRAMS.get(name, 0),
+                is_drum=data["is_drum"],
+                name=name,
+            )
+            for n in data["notes"]:
+                inst.notes.append(
+                    pretty_midi.Note(
+                        velocity=n.get("velocity", 100),
+                        pitch=n["pitch"],
+                        start=n["start"],
+                        end=max(n["end"], n["start"] + 0.02),
+                    )
+                )
+            pm.instruments.append(inst)
+        return pm
+
+    with_notes = {k: v for k, v in tracks.items() if v["notes"]}
+    if with_notes:
+        song_path = midi_dir / "song.mid"
+        make_pm(with_notes).write(str(song_path))
+        written["song"] = song_path
+        for name, data in with_notes.items():
+            p = midi_dir / f"{name}.mid"
+            make_pm({name: data}).write(str(p))
+            written[name] = p
+    return written
+
+
+def write_rpp(
+    bundle_dir: str | Path,
+    tempo: float,
+    stems: dict[str, str],
+    duration: float,
+) -> Path:
+    """stems: {name: bundle-relative wav path}."""
+    tracks = "".join(
+        _RPP_TRACK.format(name=name, length=round(duration, 3), file=rel)
+        for name, rel in stems.items()
+    )
+    content = (
+        f'<REAPER_PROJECT 0.1 "7.0" 0\n'
+        f"  TEMPO {tempo} 4 4\n"
+        f"{tracks}"
+        f">\n"
+    )
+    path = Path(bundle_dir) / "project.RPP"
+    path.write_text(content)
+    return path
+
+
+def write_manifest(bundle_dir: str | Path, meta: dict) -> Path:
+    path = Path(bundle_dir) / "manifest.json"
+    path.write_text(json.dumps(meta, indent=2))
+    return path
+
+
+def write_readme(bundle_dir: str | Path, source: str, analysis) -> Path:
+    path = Path(bundle_dir) / "README.txt"
+    path.write_text(
+        _README.format(
+            source=source,
+            tempo=analysis.tempo,
+            key=analysis.key,
+            timesig=analysis.time_signature,
+        )
+    )
+    return path
+
+
+def make_manifest_meta(source: str, analysis, model: str, stems_meta: dict) -> dict:
+    return {
+        "app": "stemflipper",
+        "version": "0.1.0",
+        "created_utc": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "source_file": source,
+        "separation_model": model,
+        "tempo": analysis.tempo,
+        "key": analysis.key,
+        "time_signature": analysis.time_signature,
+        "duration": round(analysis.duration, 3),
+        "sample_rate": analysis.sr,
+        "stems": stems_meta,
+    }
+
+
+def zip_bundle(bundle_dir: str | Path) -> Path:
+    bundle_dir = Path(bundle_dir)
+    zip_path = shutil.make_archive(str(bundle_dir), "zip", root_dir=bundle_dir.parent, base_dir=bundle_dir.name)
+    return Path(zip_path)

stemflipper/pipeline.py

@@ -0,0 +1,109 @@
+"""Pipeline orchestrator: the one entry point the CLI, tests, and Gradio app share."""
+
+from __future__ import annotations
+
+import re
+import shutil
+from pathlib import Path
+
+from . import analyze, audio_io, export, sampler, separate, transcribe
+
+
+def run_pipeline(
+    input_path: str | Path,
+    output_dir: str | Path,
+    model: str = separate.DEFAULT_MODEL,
+    model_dir: str | Path | None = None,
+    progress=None,
+    make_zip: bool = True,
+    separate_fn=None,
+) -> dict:
+    """Full flow: analyze -> separate -> transcribe -> sampler -> bundle.
+
+    separate_fn lets app.py swap in a GPU-decorated separation call (ZeroGPU);
+    defaults to separate.separate_stems.
+    Returns {"bundle_dir", "zip_path", "manifest"}.
+    """
+
+    def report(frac: float, desc: str) -> None:
+        if progress is not None:
+            progress(frac, desc)
+
+    input_path = Path(input_path)
+    slug = re.sub(r"[^\w-]+", "_", input_path.stem).strip("_") or "song"
+    bundle_dir = Path(output_dir) / slug
+    if bundle_dir.exists():
+        shutil.rmtree(bundle_dir)
+    stems_dir = bundle_dir / "stems"
+    stems_dir.mkdir(parents=True)
+
+    report(0.02, "Loading audio")
+    y, sr = audio_io.load_audio(input_path, mono=True)
+
+    report(0.05, "Analyzing tempo & key")
+    analysis = analyze.analyze_audio(y, sr)
+
+    report(0.12, f"Separating stems ({model}) — the slow part")
+    do_separate = separate_fn or separate.separate_stems
+    raw_stems = do_separate(input_path, stems_dir, model=model, model_dir=model_dir)
+
+    # normalize to stems/<name>.wav
+    stem_paths: dict[str, Path] = {}
+    for name, path in raw_stems.items():
+        target = stems_dir / f"{name}.wav"
+        if path != target:
+            path.rename(target)
+        stem_paths[name] = target
+
+    tracks: dict[str, dict] = {}
+    stems_meta: dict[str, dict] = {}
+    ordered = [s for s in separate.KNOWN_STEMS if s in stem_paths]
+    for i, name in enumerate(ordered):
+        report(0.55 + 0.25 * i / len(ordered), f"Transcribing {name}")
+        stem_audio, stem_sr = audio_io.load_audio(stem_paths[name], mono=True)
+        silent = audio_io.is_silent(stem_audio)
+        result = (
+            {"notes": [], "is_drum": name == "drums"}
+            if silent
+            else transcribe.transcribe_stem(name, stem_paths[name])
+        )
+        tracks[name] = result
+        stems_meta[name] = {
+            "audio": f"stems/{name}.wav",
+            "silent": silent,
+            "n_notes": len(result["notes"]),
+            "midi": f"midi/{name}.mid" if result["notes"] else None,
+            "instrument_sfz": None,
+        }
+
+    for i, name in enumerate(ordered):
+        report(0.8 + 0.08 * i / len(ordered), f"Building {name} instrument")
+        built = sampler.build_sampler(
+            name,
+            stem_paths[name],
+            tracks[name]["notes"],
+            bundle_dir / "instruments" / name,
+            is_drum=tracks[name]["is_drum"],
+        )
+        if built:
+            stems_meta[name]["instrument_sfz"] = f"instruments/{name}/{name}.sfz"
+
+    report(0.9, "Writing MIDI, manifest, Reaper project")
+    export.write_midi(tracks, analysis.tempo, bundle_dir / "midi")
+    manifest = export.make_manifest_meta(input_path.name, analysis, model, stems_meta)
+    export.write_manifest(bundle_dir, manifest)
+    export.write_readme(bundle_dir, input_path.name, analysis)
+    export.write_rpp(
+        bundle_dir,
+        analysis.tempo,
+        {n: m["audio"] for n, m in stems_meta.items()},
+        analysis.duration,
+    )
+
+    zip_path = None
+    if make_zip:
+        report(0.96, "Zipping bundle")
+        zip_path = export.zip_bundle(bundle_dir)
+
+    report(1.0, "Done")
+    return {"bundle_dir": bundle_dir, "zip_path": zip_path, "manifest": manifest}

stemflipper/sampler.py

@@ -0,0 +1,105 @@
+"""Sliced-sample instrument builder: transcribed MIDI boundaries -> wav slices + SFZ.
+
+SFZ is plain text — generated with string templates on purpose (pysfz is abandoned;
+see PLAN.md §4). One representative slice per distinct pitch, regions cover the full
+key range via midpoints, single velocity layer. Loadable in sfizz / DecentSampler /
+Sforzando.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import soundfile as sf
+
+_MIN_SLICE_S = 0.03
+_RELEASE_PAD_S = 0.05
+
+_SFZ_HEADER = """\
+// StemFlipper sliced instrument: {stem}
+// Generated from transcribed note boundaries; load in sfizz, Sforzando or DecentSampler.
+<control>
+default_path=samples/
+
+<global>
+ampeg_release=0.4
+{global_extra}
+"""
+
+_SFZ_REGION = (
+    "<region> sample={sample} lokey={lokey} hikey={hikey} "
+    "pitch_keycenter={center}{extra}\n"
+)
+
+
+def build_sampler(
+    stem_name: str,
+    audio_path: str | Path,
+    notes: list[dict],
+    out_dir: str | Path,
+    is_drum: bool = False,
+) -> dict | None:
+    """Write instruments/<stem>/{<stem>.sfz, samples/*.wav}; return metadata or None."""
+    if not notes:
+        return None
+    y, sr = sf.read(str(audio_path))
+    if y.ndim > 1:
+        y = y.mean(axis=1)
+
+    picked = _pick_representatives(notes, is_drum)
+    out_dir = Path(out_dir)
+    samples_dir = out_dir / "samples"
+    samples_dir.mkdir(parents=True, exist_ok=True)
+
+    regions = []
+    for pitch, note in sorted(picked.items()):
+        start = int(note["start"] * sr)
+        end = int((note["end"] + _RELEASE_PAD_S) * sr)
+        seg = y[start : min(end, len(y))]
+        if len(seg) < int(_MIN_SLICE_S * sr):
+            continue
+        sample_name = f"{stem_name}_{pitch:03d}.wav"
+        sf.write(str(samples_dir / sample_name), seg, sr)
+        regions.append((pitch, sample_name))
+    if not regions:
+        return None
+
+    sfz_path = out_dir / f"{stem_name}.sfz"
+    sfz_path.write_text(_render_sfz(stem_name, regions, is_drum))
+    return {
+        "sfz": sfz_path,
+        "samples_dir": samples_dir,
+        "n_regions": len(regions),
+    }
+
+
+def _pick_representatives(notes: list[dict], is_drum: bool) -> dict[int, dict]:
+    """One note per distinct pitch: loudest for drums, longest for pitched."""
+    best: dict[int, dict] = {}
+    for n in notes:
+        cur = best.get(n["pitch"])
+        if cur is None:
+            best[n["pitch"]] = n
+        elif is_drum and n["velocity"] > cur["velocity"]:
+            best[n["pitch"]] = n
+        elif not is_drum and (n["end"] - n["start"]) > (cur["end"] - cur["start"]):
+            best[n["pitch"]] = n
+    return best
+
+
+def _render_sfz(stem_name: str, regions: list[tuple[int, str]], is_drum: bool) -> str:
+    global_extra = "loop_mode=one_shot" if is_drum else ""
+    out = _SFZ_HEADER.format(stem=stem_name, global_extra=global_extra)
+    pitches = [p for p, _ in regions]
+    for i, (pitch, sample) in enumerate(regions):
+        if is_drum:
+            lokey = hikey = pitch
+        else:
+            # midpoints to neighbors; outermost regions cover the full keyboard
+            lokey = 0 if i == 0 else (pitches[i - 1] + pitch) // 2 + 1
+            hikey = 127 if i == len(regions) - 1 else (pitch + pitches[i + 1]) // 2
+        out += _SFZ_REGION.format(
+            sample=sample, lokey=lokey, hikey=hikey, center=pitch, extra=""
+        )
+    return out

stemflipper/separate.py

@@ -0,0 +1,74 @@
+"""Source separation via audio-separator (wraps Demucs v4 / MDX / BS-RoFormer).
+
+This module is the ONLY GPU-relevant stage. app.py wraps `separate_stems` in
+`@spaces.GPU` when running on ZeroGPU; everywhere else it runs as-is (CPU or CUDA,
+auto-detected by audio-separator).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+# canonical stem names, in bundle order
+KNOWN_STEMS = ("vocals", "drums", "bass", "guitar", "piano", "other")
+
+# model name -> audio-separator model_filename
+MODELS = {
+    "htdemucs": "htdemucs.yaml",        # 4 stems, default (speed / CPU-viable)
+    "htdemucs_6s": "htdemucs_6s.yaml",  # 6 stems; piano documented-weak, gate it
+    "htdemucs_ft": "htdemucs_ft.yaml",  # bag-of-4, ~4x slower, +0.2 dB
+}
+DEFAULT_MODEL = "htdemucs"
+
+
+def default_model_dir() -> Path:
+    env = os.environ.get("STEMFLIPPER_MODEL_DIR")
+    if env:
+        return Path(env)
+    return Path.home() / ".cache" / "stemflipper" / "models"
+
+
+def separate_stems(
+    input_path: str | Path,
+    output_dir: str | Path,
+    model: str = DEFAULT_MODEL,
+    model_dir: str | Path | None = None,
+) -> dict[str, Path]:
+    """Run separation; return {canonical_stem_name: wav_path}."""
+    from audio_separator.separator import Separator
+
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    model_filename = MODELS.get(model, model)  # allow raw model filenames too
+
+    separator = Separator(
+        output_dir=str(output_dir),
+        model_file_dir=str(model_dir or default_model_dir()),
+        output_format="WAV",
+    )
+    separator.load_model(model_filename=model_filename)
+    output_files = separator.separate(str(input_path))
+
+    stems: dict[str, Path] = {}
+    for f in output_files:
+        path = Path(f)
+        if not path.is_absolute():
+            path = output_dir / path
+        name = _stem_name_from_filename(path.name)
+        if name:
+            stems[name] = path
+    if not stems:
+        raise RuntimeError(f"separation produced no recognizable stems: {output_files}")
+    return stems
+
+
+def _stem_name_from_filename(filename: str) -> str | None:
+    """audio-separator names outputs like 'song_(Vocals)_htdemucs.wav'."""
+    match = re.search(r"\(([^)]+)\)", filename)
+    candidate = (match.group(1) if match else filename).strip().lower()
+    for stem in KNOWN_STEMS:
+        if stem in candidate:
+            return stem
+    return None

stemflipper/transcribe.py

@@ -0,0 +1,97 @@
+"""Per-stem transcription to note events.
+
+Notes are plain dicts {pitch, start, end, velocity} — JSON-friendly, no cross-module types.
+Pitched stems: basic-pitch (Apache-2.0, TFLite/CoreML — CPU-fast).
+Drums: librosa onset detection + spectral-band heuristic -> GM map (known-weak on
+overlapping hits; the honest MVP baseline per PLAN.md; ADT upgrade is out for licensing).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+
+GM_KICK, GM_SNARE, GM_HAT = 36, 38, 42
+
+# fmin/fmax clamps per stem type; bass clamp kills the #1 failure mode (octave errors)
+_PITCH_RANGES = {
+    "bass": (30.0, 350.0),
+    "vocals": (60.0, 1500.0),
+}
+
+
+def transcribe_pitched(audio_path: str | Path, stem_name: str = "other") -> list[dict]:
+    from basic_pitch.inference import predict
+
+    fmin, fmax = _PITCH_RANGES.get(stem_name, (None, None))
+    kwargs = {}
+    if fmin is not None:
+        kwargs = {"minimum_frequency": fmin, "maximum_frequency": fmax}
+    _, midi_data, _ = predict(str(audio_path), **kwargs)
+
+    notes = []
+    for inst in midi_data.instruments:
+        for n in inst.notes:
+            notes.append(
+                {
+                    "pitch": int(n.pitch),
+                    "start": round(float(n.start), 4),
+                    "end": round(float(n.end), 4),
+                    "velocity": int(n.velocity),
+                }
+            )
+    notes.sort(key=lambda n: (n["start"], n["pitch"]))
+    return notes
+
+
+def transcribe_drums(audio_path: str | Path) -> list[dict]:
+    import librosa
+
+    y, sr = librosa.load(str(audio_path), sr=None, mono=True)
+    if not len(y):
+        return []
+    onset_times = librosa.onset.onset_detect(
+        y=y, sr=sr, units="time", backtrack=False, delta=0.05
+    )
+    window = int(0.05 * sr)
+    freqs = np.fft.rfftfreq(window, 1 / sr)
+    peak = float(np.abs(y).max()) or 1.0
+
+    notes = []
+    for t in onset_times:
+        i = int(t * sr)
+        seg = y[i : i + window]
+        if len(seg) < window // 2 or np.abs(seg).max() < 1e-4:
+            continue
+        mag = np.abs(np.fft.rfft(seg, n=window))
+        total = mag.sum() or 1.0
+        low_ratio = float(mag[freqs < 150].sum() / total)
+        high_ratio = float(mag[freqs > 5000].sum() / total)
+        # a coincident hat adds ~0.4 high-band ratio, so only near-pure HF is a hat
+        if low_ratio > 0.25:
+            pitch = GM_KICK
+        elif high_ratio > 0.7:
+            pitch = GM_HAT
+        else:
+            pitch = GM_SNARE
+        velocity = int(np.clip(np.abs(seg).max() / peak * 127, 20, 127))
+        notes.append(
+            {
+                "pitch": pitch,
+                "start": round(float(t), 4),
+                "end": round(float(t) + 0.1, 4),
+                "velocity": velocity,
+            }
+        )
+    return notes
+
+
+def transcribe_stem(stem_name: str, audio_path: str | Path) -> dict:
+    """Return {"notes": [...], "is_drum": bool}. Never raises on empty/unpitched audio."""
+    is_drum = stem_name == "drums"
+    try:
+        notes = transcribe_drums(audio_path) if is_drum else transcribe_pitched(audio_path, stem_name)
+    except Exception:
+        notes = []
+    return {"notes": notes, "is_drum": is_drum}