StemSplit

Local-first audio stem separation (vocals/drums/bass/other) powered by Demucs, with a clean Next.js UI and a FastAPI backend.

Features

• 100% local processing (your audio stays on your machine)
• Demucs stem separation (htdemucs by default)
• Simple job history + stem downloads
• Experimental server-side mixdown (FFmpeg)

Requirements

• Python 3.10+ recommended
• Node.js 18+ recommended
• FFmpeg in your PATH
  • macOS: brew install ffmpeg

Quickstart (dev)

One command

./start.sh

This starts both backend and frontend. Use ./start.sh --install to force reinstall dependencies.

1) Backend

python3 -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
pip install -r backend/requirements-ml.txt
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

2) Frontend

cd frontend
npm ci
npm run dev

Open http://localhost:3000.

If your API is not on http://localhost:8000, set NEXT_PUBLIC_API_BASE_URL.

Environment

• BACKEND_PORT (default 8000)
• FRONTEND_PORT (default 3000)
• NEXT_PUBLIC_API_BASE_URL (defaults to http://localhost:8000)

Repo layout

• backend/: FastAPI API + Demucs runner
• frontend/: Next.js UI
• docs/: architecture + API notes

License

MIT — see LICENSE.

Contributing

PRs welcome — see CONTRIBUTING.md and CODE_OF_CONDUCT.md.