Metadata-Version: 2.4
Name: unblend
Version: 1.0.0
Summary: Audio source separation for music.
Author: Alexandre Défossez, Ryan Fahey
Author-email: Alexandre Défossez <defossez@fb.com>, Ryan Fahey <git@ryan.science>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: OS Independent
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: numpy>=2.0.0
Requires-Dist: torch>=2.13.0
Requires-Dist: torchaudio>=2.11.0
Requires-Dist: torchcodec>=0.15.0,<0.16
Requires-Dist: safetensors>=0.8.0
Requires-Dist: typer>=0.19.1,<0.26
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.8.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: filelock>=3.20.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: ruff ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: onnx>=1.22.0 ; extra == 'onnx'
Requires-Dist: onnxconverter-common>=1.16.0 ; extra == 'onnx'
Requires-Dist: onnxscript>=0.7.0 ; extra == 'onnx'
Requires-Python: >=3.10, <3.15
Project-URL: Homepage, https://github.com/Ryan5453/unblend
Project-URL: Repository, https://github.com/Ryan5453/unblend
Project-URL: Changelog, https://github.com/Ryan5453/unblend/blob/main/changelog.md
Provides-Extra: dev
Provides-Extra: onnx
Description-Content-Type: text/markdown

# <img src="https://raw.githubusercontent.com/Ryan5453/unblend/main/web/app/public/favicon.svg" width="30"> Unblend

Unblend is a music source separation inference library designed to be fast and easy to use. On CUDA it runs HTDemucs up to 10x faster than upstream Demucs at equal quality (on H200s against upstream on the PyTorch 2.1 it supports).
It implements one consistent API across four supported model architectures: HTDemucs, BS-RoFormer, Mel-Band RoFormer, and SCNet.

## Installation

### Prerequisites

- FFmpeg v4–v8 (not v9 yet)
- [`uv`](https://docs.astral.sh/uv/#installation)
- Optional: C/C++ compiler such as GCC, Clang, or MSVC - enables torch.compile support
- Optional: NVCC (NVIDIA CUDA Compiler) and [Ninja](https://ninja-build.org/) - enables custom CUDA kernels


### Install using uv

Create a virtual environment backed by a uv-managed Python:

```sh
$ uv python install 3.12
$ uv venv --managed-python --python 3.12
$ source .venv/bin/activate
```

Then install Unblend into that environment:

```sh
$ uv pip install unblend --torch-backend=auto
```

### Temporary Installation

With uv, you can use the `uvx` command to run Unblend without installing it permanently on your system.

```sh
$ uvx unblend separate audio_file.mp3
```

Note: `uvx` can't pick a PyTorch build for your GPU, so it gets PyPI's default wheel: GPUs only work on Apple Silicon, or on Linux with PyTorch's default CUDA version.


## CLI Usage

After installing Unblend:

```sh
$ unblend --help
$ unblend separate audio_file.mp3
$ unblend separate audio_file_1.mp3 audio_file_2.mp3 music_folder/
```

Stems are written to `separated/{model}/{track}/{stem}.wav` by default, at the model's sample rate (44.1 kHz stereo for every registered model) whatever the input's. Change it with `-o`, using the variables `{model}`, `{track}`, `{parent}` (the name of the track's folder), `{stem}`, `{ext}`, `{date}`, `{time}` and `{timestamp}`, and pick the container with `-f` (e.g. `-f flac`). Two tracks with the same name in different folders need `{parent}` in the template, or they would write to the same place (the CLI refuses rather than overwrite). Other common options:

- `-m MODEL` picks a model (see `unblend models list`); the default `auto` picks an HTDemucs model.
- `--isolate-stem vocals` writes just `vocals` and `no_vocals`.
- `--seed 0`, or `--shifts 0`, makes output reproducible run to run.
- `unblend tune` measures the fastest batch size and compile setting for your GPU.

## Models

| Model | Architecture | Stems | Weights license |
| --- | --- | --- | --- |
| `htdemucs` (default) | HTDemucs | drums, bass, other, vocals | unlicensed |
| `htdemucs_ft` | HTDemucs (4 fine-tuned models) | drums, bass, other, vocals | unlicensed |
| `htdemucs_6s` | HTDemucs | drums, bass, other, vocals, guitar, piano | unlicensed |
| `bs_roformer_sw` | BS-RoFormer | bass, drums, other, vocals, guitar, piano | unlicensed |
| `bs_roformer_anvuew` | BS-RoFormer | vocals, other | GPL-3.0 |
| `melband_roformer_kim` | Mel-Band RoFormer | vocals, other | MIT |
| `scnet_small` | SCNet | drums, bass, other, vocals | unlicensed |
| `scnet_xl_wide_v5` | SCNet | drums, bass, other, vocals | unlicensed |
| `roformer_vocals_ensemble` | ensemble | vocals, other | mixed |
| `htdemucs_scnet_ensemble` | ensemble | drums, bass, other, vocals | unlicensed |

## API Usage

Unblend has several programmatic interfaces:
- [ONNX export](https://github.com/Ryan5453/unblend/blob/main/onnx.md) 
- [Python API](https://github.com/Ryan5453/unblend/blob/main/api.md)
- [Browser API](https://github.com/Ryan5453/unblend/blob/main/web/unblend/README.md) 
- [Demucs Cog](https://github.com/Ryan5453/unblend/blob/main/cog.yaml) (hosted on [Replicate](https://replicate.com/ryan5453/demucs))