MelBand-RoFormer-Infer

Production-ready, inference-only toolkit for Mel-Band RoFormer audio source separation

MelBand-RoFormer-Infer provides a clean, lightweight API for running music source separation inference using Mel-Band RoFormer models with automatic checkpoint management.

Why This Exists

Mel-Band RoFormer is a strong architecture for music source separation, introduced by Lu, Wang, Kong, and Hung (2023) alongside their Band-Split RoPE Transformer (BS-RoFormer) work. The reference implementation, lucidrains/BS-RoFormer, provides the model architecture only -- no checkpoint management, no CLI, no packaging for downstream use. Trained checkpoints -- including the widely-used vocal separation model trained by Kimberley Jensen -- are typically distributed through python-audio-separator (which pulls in the full Ultimate Vocal Remover GUI stack) or through individual community members' personal Hugging Face accounts -- hosts that can and do vanish or get renamed without warning (see the jarredou account deletion and the broader 2026-07 registry audit in CHANGELOG.md: 57 of the 99 registry entries are currently known fully usable; the older legacy audit also records dead or partially dead third-party entries).

MelBand-RoFormer-Infer reprovides the architecture as a clean, pip-installable, inference-only package: no training code, no GUI dependency, a versioned model registry that can be repointed at a new host by editing one JSON file (no code change), and sha256-verified auto-download so a corrupted or tampered checkpoint is never silently loaded.

Acknowledgments

This project builds upon the excellent work of several open-source projects:

Mel-Band-Roformer-Vocal-Model by Kimberley Jensen -- original model training and the recommended default vocal-separation checkpoint
BS-RoFormer by Phil Wang (lucidrains) -- PyTorch implementation of the Mel-Band / Band-Split RoPE Transformer architecture
python-audio-separator by Andrew Beveridge (nomadkaraoke) -- the models.json registry this package's model list was bulk-imported from, plus pre-trained checkpoints and configurations for many registry entries
Original Research -- Wei-Tsung Lu, Ju-Chiang Wang, Qiuqiang Kong, and Yun-Ning Hung for the Band-Split RoPE Transformer paper (see Citation below)

Citation

If you use MelBand-RoFormer-Infer in your research, please cite the original paper:

@inproceedings{lu2024music,
    title     = {Music Source Separation with Band-Split RoPE Transformer},
    author    = {Lu, Wei-Tsung and Wang, Ju-Chiang and Kong, Qiuqiang and Hung, Yun-Ning},
    booktitle = {ICASSP 2024 - 2024 IEEE International Conference on Acoustics, Speech and Signal Processing (ICASSP)},
    pages     = {481--485},
    year      = {2024},
    publisher = {IEEE},
    doi       = {10.1109/ICASSP48485.2024.10446843}
}

Also available as a preprint: arXiv:2309.02612.

Features

Inference Only: Lightweight package focused on production inference
Auto-Download: the default model is fetched on first use and sha256-verified against recorded checksums
Model Registry: 99 catalogued models -- vocals, instrumentals, karaoke, denoise, dereverb, and more (see the availability note below)
CLI Tools: melband-roformer-infer and melband-roformer-download commands
Python API: Clean programmatic interface

Scope

In scope: inference (forward pass) with the Mel-Band RoFormer architecture; a 115-model registry (src/mel_band_roformer/data/melband_models.json) spanning vocals, instrumental, karaoke, denoise, dereverb, crowd, general, and aspiration checkpoints; automatic, manual, and configurable-directory checkpoint management with sha256 verification; a standalone download CLI.

Out of scope, forever:

Training or fine-tuning code -- this package only ever runs a forward pass.
The Ultimate Vocal Remover GUI itself, or any GUI.
Bundling or committing checkpoint bytes to this repository's git history (see What This Project Will NEVER Bundle).

Install

# Using pip
pip install melband-roformer-infer

# Using UV (recommended)
uv pip install melband-roformer-infer

Backends and devices

Two independent choices:

Argument	Values	Meaning
`backend`	`torch` (default), `mlx`, `auto`	which framework computes
`device`	`None`, `auto`, `cpu`, `cuda`, `cuda:N`, `mps`	where Torch computes

from mel_band_roformer import MelBandRoformerSession

with MelBandRoformerSession(device="mps") as session:  # Apple GPU, Torch
    session.infer("songs/", store_dir="stems/")

melband-roformer-infer --input_folder songs --device mps
melband-roformer-infer --input_folder songs --backend auto

backend defaults to torch, so nothing changes unless you ask. auto picks an accelerated backend only when one is genuinely installed and falls back to Torch otherwise. Requesting a backend that cannot run here raises immediately -- before any checkpoint is downloaded -- rather than quietly using a different one. backend="mlx" owns its own Apple Silicon execution and accepts only device of auto/mps (or none), refusing anything else rather than ignoring it.

The MLX backend

Native Apple Silicon execution through MLX. Install it with the extra, which is never part of the core install:

pip install "melband-roformer-infer[mlx]"

MelBandRoformerSession(backend="mlx").load()

Verified against the Torch path on the default checkpoint (Kim Vocals), end to end through the public session API on real WAV files: 8.4e-08 maximum absolute error on clean signal, 1.8e-07 on a track with a genuinely silent tail, and 4.9e-09 on a near-silent tail. The silent-tail case is the one that matters -- MLX's rfft kernel is not exactly zero on an all-zero frame, which without a workaround corrupts an entire chunk (see CLAUDE.md for the mechanism); measured with the workaround disabled, the same silent-tail case degrades to 4.5e-02, roughly 250,000x worse. It reads the same sha256-verified checkpoint and config as the Torch path -- there is no second catalog and no separate converted-weight cache.

This package's 21-model config/checkpoints.toml registry declares no mask-estimator variations (unlike this package's fork sibling bs-roformer-infer, whose registry has four), so every registry checkpoint runs under MLX today; a checkpoint requiring a head this backend does not build would refuse cleanly by name rather than construct silently as the wrong architecture.

It refuses, rather than gets wrong, a config whose chunk_size is not a multiple of its STFT hop -- an alignment the chunked path silently assumes.

MPS and MLX both need an arm64 Python interpreter. Under Rosetta/x86_64 they report as unavailable rather than failing loudly -- an x86_64 interpreter makes torch.backends.mps.is_available() return False, and MLX ships no macOS x86_64 wheel at all, so it cannot even be installed there. Either way, an accelerated path just looks absent rather than misconfigured. This is easy to hit without noticing: an x86_64 uv resolves x86_64 interpreters, so uv sync can silently produce an environment where the accelerated paths structurally cannot exist. Check with python -c "import platform; print(platform.machine())" -- it must print arm64.

Quick Start

# First run auto-downloads the recommended MelBand Roformer Kim model (~913 MB,
# sha256-verified) into ~/.cache/melband-roformer-infer/ -- no separate download step needed
melband-roformer-infer --input_folder ./songs --store_dir ./outputs

Every WAV inside input_folder produces *_vocals.wav and *_instrumental.wav stems. Explicit --config_path/--model_path arguments still work and skip auto-resolution entirely; --model <slug> picks a different registry model to auto-resolve.

Python API

from ml_collections import ConfigDict
import torch
import yaml
from mel_band_roformer import DEFAULT_MODEL, ensure_model_assets, get_model_from_config

# Resolves local copies, or downloads (sha256-verified) on first use
ckpt_path, config_path = ensure_model_assets(DEFAULT_MODEL)

config = ConfigDict(yaml.safe_load(open(config_path)))
model = get_model_from_config("mel_band_roformer", config)
model.load_state_dict(torch.load(ckpt_path, map_location="cpu"))

Recommended Model

MelBand Roformer Kim (melband-roformer-kim-vocals) by Kimberley Jensen is the recommended default model for vocal separation. It provides excellent quality and is the foundation for many fine-tuned variants.

from mel_band_roformer import DEFAULT_MODEL
print(DEFAULT_MODEL)  # "melband-roformer-kim-vocals"

Available Models

Model	Category	Description
`melband-roformer-kim-vocals`	vocals	Recommended - Original MelBand Roformer by Kimberley Jensen
`melband-roformer-big-beta6`	vocals	Big Beta 6 by unwa
`melband-roformer-big-beta7`	vocals	Big Beta 7 by unwa
`roformer-model-melband-roformer-vocals-by-becruily`	vocals	Vocals by becruily
`roformer-model-melband-roformer-instrumental-by-becruily`	instrumental	Instrumental by becruily
`roformer-model-melband-roformer-kim-inst-v2-by-unwa`	instrumental	Inst V2 by unwa
`roformer-model-melband-roformer-deux-by-becruily`	instvoc	Vocals/Instrumental by becruily
`roformer-model-melband-roformer-kim-instvoc-duality-v1-by-unwa`	instvoc	InstVoc Duality V1 by Unwa
`roformer-model-melband-roformer-kim-instvoc-duality-v2-by-unwa`	instvoc	InstVoc Duality V2 by Unwa
`roformer-model-melband-roformer-instrumental-by-gabox`	instrumental	Instrumental by Gabox
`roformer-model-melband-roformer-karaoke-by-becruily`	karaoke	Karaoke by becruily
`roformer-model-melband-roformer-guitar-by-becruily`	guitar	Guitar by becruily
`melband-roformer-denoise-debleed-gabox`	denoise	Denoise Debleed by Gabox
`roformer-model-melband-roformer-de-reverb-by-anvuew`	dereverb	De-Reverb by anvuew
`roformer-model-melband-roformer-de-reverb-less-aggressive-by-anvuew`	dereverb	De-Reverb Less Aggressive by anvuew
`roformer-model-melband-roformer-de-reverb-mono-by-anvuew`	dereverb	De-Reverb Mono by anvuew
`roformer-model-melband-roformer-aspiration-by-sucial`	aspiration	Aspiration by Sucial
`roformer-model-melband-roformer-aspiration-less-aggressive-by-sucial`	aspiration	Aspiration Less Aggressive by Sucial
`roformer-model-melband-roformer-de-reverb-echo-by-sucial`	dereverb	De-Reverb-Echo by Sucial
`roformer-model-melband-roformer-de-reverb-echo-v2-by-sucial`	dereverb	De-Reverb-Echo V2 by Sucial
`roformer-model-melband-roformer-de-reverb-big-by-sucial`	dereverb	De-Reverb Big by Sucial
`roformer-model-melband-roformer-de-reverb-super-big-by-sucial`	dereverb	De-Reverb Super Big by Sucial
`roformer-model-melband-roformer-de-reverb-echo-fused-by-sucial`	dereverb	De-Reverb-Echo Fused by Sucial
`roformer-model-mel-roformer-viperx-1143`	vocals	Mel-RoFormer Viperx 1143
`pcunwa-melband-roformer-big-beta1` ... `pcunwa-melband-roformer-big-beta7`	vocals	Direct pcunwa Big beta variants
`pcunwa-melband-roformer-small-v1`	vocals	Direct pcunwa Small V1 checkpoint
`pcunwa-melband-roformer-inst-v1` ... `pcunwa-melband-roformer-inst-v1-plus-test`	instrumental	Direct pcunwa Instrumental V1 variants
`pcunwa-kimmel-ft` ... `pcunwa-kimmel-ft3-prev`	vocals	Direct pcunwa Kim fine-tuned variants
...	...	See `--list-models` for 99 models

Categories: vocals, instrumental, instvoc, karaoke, guitar, denoise, dereverb, crowd, general, aspiration

The package-owned TOML metadata contains all 20 direct pcunwa Mel-Band checkpoints, including InstVoc Duality V1/V2. The weight files remain runtime downloads; the pcunwa repositories currently do not declare an explicit weight license in their cards or repository files.

Note on download availability (re-audited 2026-07-23): this registry is bulk-imported from several third-party contributors' Hugging Face repos, some of which get renamed or taken down without notice (see CHANGELOG.md for the 2026-07 audit and the jarredou account deletion). As of the latest audit, 57 of the 99 registry models are known fully usable (checkpoint and config both live -- all of these carry recorded sha256 checksums). The older legacy audit also records dead or partially dead third-party entries; those remain in the registry for compatibility but are not declared as known-good checkpoint metadata. Run python tools/check_weights_liveness.py (needs network access) to re-check which models currently have a live download URL before relying on one in a pipeline; --model/--category downloads will print a clear error if a URL 404s rather than failing silently.

Registry Helpers

from mel_band_roformer import MODEL_REGISTRY

# List all categories
print(MODEL_REGISTRY.categories())

# List models by category
for model in MODEL_REGISTRY.list("vocals"):
    print(model.name, model.checkpoint)

# Search models
results = MODEL_REGISTRY.search("karaoke")
for m in results:
    print(m.slug)

# Pretty-print all models
print(MODEL_REGISTRY.as_table())

What This Project Will NEVER Bundle

Model weights are never bundled or committed to this repository. Every checkpoint is downloaded at runtime from its registry-recorded source, sha256-verified against src/mel_band_roformer/data/checksums.json, and cached locally -- a mismatch deletes the file and retries instead of silently keeping a corrupt checkpoint.

Where weights live

Downloads default to ~/.cache/melband-roformer-infer/<model-slug>/. The location is configurable, resolved in this order:

Explicit argument: --models_dir (inference CLI), --output-dir (download CLI), or ensure_model_assets(..., models_dir=...) (API)
The MELBAND_ROFORMER_MODELS_PATH environment variable
The default ~/.cache/melband-roformer-infer/

A relative ./models directory (the pre-0.1.4 default) is still searched as a read fallback, so existing downloads keep working without re-fetching.

Auto-download

When melband-roformer-infer runs without --model_path/--config_path, the requested registry model (default: MelBand Roformer Kim) is looked up in the directories above and downloaded on first use. Downloads are verified against the sha256 checksums recorded in src/mel_band_roformer/data/checksums.json (94 assets covering every URL that was live in the latest 2026-07 audit); a mismatch deletes the file and retries instead of keeping a corrupt checkpoint. Assets without a recorded hash (only reachable via unaudited fallback URLs) print a warning and fall back to a basic size check.

Manual download (offline / air-gapped)

The recommended Kim model needs one file (its config ships inside the package):

File	URL	sha256
`MelBandRoformer.ckpt` (913,106,900 bytes)	https://huggingface.co/KimberleyJSN/melbandroformer/resolve/main/MelBandRoformer.ckpt	`87201f4d31afb5bc79993230fc49446918425574db48c01c405e44f365c7559e`

Place it at ~/.cache/melband-roformer-infer/melband-roformer-kim-vocals/MelBandRoformer.ckpt (or the equivalent path under your MELBAND_ROFORMER_MODELS_PATH), and inference will pick it up without network access. For any other model, the download URL is the overrides.json entry for its checkpoint (or the TRvlvr fallback) and the expected sha256 is in data/checksums.json.

Download CLI (manual path)

# List available models
melband-roformer-download --list-models

# Download the recommended model into the cache dir
melband-roformer-download --model melband-roformer-kim-vocals

# Download by category into a custom directory
melband-roformer-download --category karaoke --output-dir ./models

Development

# Clone repository
git clone https://github.com/openmirlab/melband-roformer-infer.git
cd melband-roformer-infer

# Install with UV
uv sync --extra dev

# Install with pip
pip install -e ".[dev]"

uv run pytest -q       # unit tests (network- and realweights-marked tests deselected by default)
uv run ruff check .    # lint

realweights-marked tests (tests/test_mlx_parity.py) need the [mlx] extra (uv sync --extra dev --extra mlx), an Apple Silicon Mac, and the default checkpoint already cached; run them explicitly with pytest -m realweights tests/test_mlx_parity.py -v.

License

MIT License - see LICENSE for details.

This project includes code and configurations adapted from:

BS-RoFormer (MIT) - Phil Wang
python-audio-separator (MIT) - Andrew Beveridge
Mel-Band-Roformer-Vocal-Model - Kimberley Jensen
mlx-audio-separator (MIT) - ssmall256, source of the vendored MLX MelBand-Roformer backend under src/mel_band_roformer/mlx/ (see that directory's file headers for revision and full license text)

Support

For issues and questions:

GitHub Issues: github.com/openmirlab/melband-roformer-infer/issues

Explicit lifecycle API

For applications that need controlled model lifetime, use MelBandRoformerSession:

from mel_band_roformer import MelBandRoformerSession
with MelBandRoformerSession() as session:
    manifest = session.infer("input_folder", store_dir="outputs")
    print(manifest[0]["output_id"], manifest[0]["output_path"])

load() is idempotent, infer() requires a ready session, and release() frees the resident model while allowing a later load() to rebuild it. close() is terminal and idempotent (and is called by the context manager). cache_info() is read-only: it resolves the same default or custom checkpoint path that load() would use without creating directories or downloading, and now also reports the resolved backend and device. Devices accept legacy automatic selection plus explicit cpu, cuda, cuda:N, and mps; unavailable explicit accelerators raise instead of silently falling back. backend (torch default, mlx, auto) selects the compute framework and is resolved before any checkpoint is downloaded or verified, so an unavailable backend fails fast -- see Backends and devices above. The packaged config/checkpoints.toml is the runtime source for its declared default model's URLs and SHA-256 metadata; legacy registry records remain a fallback for other community model variants. Existing CLI and downloader entry points remain lazy. The returned manifest is JSON-serializable and records each actual file write with input_path, track_id, output_id, and output_path.

Navigation Menu

Uh oh!

Repository files navigation

MelBand-RoFormer-Infer

Why This Exists

Acknowledgments

Citation

Features

Scope

Install

Backends and devices

The MLX backend

Quick Start

Python API

Recommended Model

Available Models

Registry Helpers

What This Project Will NEVER Bundle

Where weights live

Auto-download

Manual download (offline / air-gapped)

Download CLI (manual path)

Development

License

Support

Explicit lifecycle API

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
src/mel_band_roformer		src/mel_band_roformer
tests		tests
tools		tools
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

MelBand-RoFormer-Infer

Why This Exists

Acknowledgments

Citation

Features

Scope

Install

Backends and devices

The MLX backend

Quick Start

Python API

Recommended Model

Available Models

Registry Helpers

What This Project Will NEVER Bundle

Where weights live

Auto-download

Manual download (offline / air-gapped)

Download CLI (manual path)

Development

License

Support

Explicit lifecycle API

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages