README.md

metadata

title: StemFlipper
emoji: 🎛️
colorFrom: purple
colorTo: blue
sdk: gradio
sdk_version: 6.19.0
app_file: app.py
python_version: 3.10.13
pinned: false
license: mit
short_description: Song → stems → MIDI → editable instruments → DAW bundle

🎛️ 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.

Try it: live web app · Hugging Face Space · parameter dataset

The web app in web/ is a static, build-step-free page that calls the Space's API via @gradio/client; it is served from GitHub Pages. What the bundle contains:

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

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).