Metadata-Version: 2.4
Name: voxsplit
Version: 0.1.0
Summary: Local-first AI stem separation with a modern web UI
Author: Michael Borck
License: MIT License
        
        Copyright (c) 2026 Michael Borck
        
        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.
        
Project-URL: Homepage, https://voxsplit.borck.dev
Project-URL: Repository, https://github.com/michael-borck/voxsplit
Project-URL: Issues, https://github.com/michael-borck/voxsplit/issues
Keywords: audio,stems,source-separation,vocal-remover,karaoke,demucs,roformer,music
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn[standard]>=0.30
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: audio-separator[cpu]>=0.30
Requires-Dist: audioread>=3.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Dynamic: license-file

# VoxSplit

**[voxsplit.borck.dev](https://voxsplit.borck.dev)** — hear real separation output, then self-host.

Local-first AI stem separation with a modern web UI. Drop in a song, get back
vocals, instrumental, or full 4-stem splits — everything runs on your own
machine, no accounts, no uploads to the cloud.

VoxSplit is a greenfield web app built on proven open-source separation
engines. It is inspired by [Ultimate Vocal Remover GUI](https://github.com/Anjok07/ultimatevocalremovergui)
and stands on the shoulders of that project and its model authors.

## Status

Working proof of concept: upload → separate with per-job progress → play/download
stems. Models auto-use the best available accelerator: CUDA on Linux/NVIDIA,
MPS on Apple Silicon (torch-based models), CPU everywhere.

## Models

Weights are fetched on demand (first use of each model) into `data/models/`
from the community model repos maintained by the UVR and python-audio-separator
projects. No manual downloads needed.

| Model | Family | Stems | Notes |
|---|---|---|---|
| Mel-Band RoFormer (aufr33/viperx) | RoFormer | 2 | SOTA karaoke quality |
| Mel-Band RoFormer (becruily) | RoFormer | 2 | SOTA karaoke alt |
| Mel-Band RoFormer (KimberleyJSN) | RoFormer | 2 | SOTA vocals |
| UVR-MDX-NET-Inst HQ 3 | MDX-Net | 2 | Fast, high quality |
| Kim Vocal 2 | MDX-Net | 2 | Vocals, male-leaning |
| UVR MDXNET Kara 2 | MDX-Net | 2 | Karaoke-optimized |
| htdemucs_4s | Demucs | 4 | Vocals/drums/bass/other |

Accelerator notes: RoFormer and Demucs run on CUDA/MPS automatically. MDX-Net
runs via onnxruntime — CPU on macOS, CUDA on Linux with `audio-separator[gpu]`.

## Quickstart

Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/) (or plain `pip` —
see note below).

```bash
git clone https://github.com/michael-borck/voxsplit
cd voxsplit
uv venv
source .venv/bin/activate
uv pip install -e .
voxsplit
```

Without uv: `python3 -m venv .venv && source .venv/bin/activate && pip install -e .`

Open http://127.0.0.1:8399, drop a `.wav`/`.mp3`/`.flac`, pick a model, hit
**Split**. The first run downloads the selected model (~60 MB) to `data/models/`.

## Architecture

```
browser (vanilla JS) ──► FastAPI (backend/main.py)
                            ├── jobs.py     thread-safe job store, 1-worker queue
                            ├── engine.py   python-audio-separator wrapper (lazy import)
                            └── data/       uploads, outputs, model weights
```

- **REST API**: `POST /api/jobs` (upload + model), `GET /api/jobs/{id}` (status),
  `GET /api/jobs/{id}/files/{name}` (stream stem), `DELETE /api/jobs/{id}`.
- **Engines**: models run via `python-audio-separator`, which supports UVR's
  MDX-Net/VR models, Demucs, and Mel-Band RoFormers.

## Credits

This project exists because of the people who built the models and the
original app:

- **Anjok07 & aufr33** — [Ultimate Vocal Remover GUI](https://github.com/Anjok07/ultimatevocalremovergui),
  the project that made high-quality local stem separation accessible.
- **nomadkaraoke** — [python-audio-separator](https://github.com/nomadkaraoke/python-audio-separator),
  the maintained headless engine VoxSplit wraps.
- **ZFTurbo** — MDX23C weights and [Music-Source-Separation-Training](https://github.com/ZFTurbo/Music-Source-Separation-Training).
- **Kuielab & Woosung Choi** — original MDX-Net AI code.
- **tsurumeso** — original VR architecture code.
- **Alexandre Défossez & Meta (Demucs)** — Demucs AI code.
- **Bas Curtiz** — original UVR logo/icon design.

## Deployment (NVIDIA)

On a Linux box with NVIDIA GPUs and Docker + nvidia-container-toolkit:

```bash
cd deploy
docker compose up -d --build
```

Then browse to `http://<box-ip>:8399`. Model weights persist in `deploy/data/`.

## Roadmap

- [x] Per-job progress reporting (tqdm hooks on torch models)
- [x] Mel-Band RoFormer models (current SOTA)
- [x] Apple Silicon MPS acceleration (automatic for torch models)
- [ ] Ensemble mode + post-processing (from UVR's playbook)
- [ ] Optional Tauri desktop wrapper

## License

MIT — see [LICENSE](LICENSE).
