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.

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: 89 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

Quick Start

Installation

# Using pip
pip install melband-roformer-infer

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

CLI Inference

# 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"))

Model Weights

Where weights live

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

1. Explicit argument: --models_dir (inference CLI), --output-dir (download CLI), or ensure_model_assets(..., models_dir=...) (API)
2. The MELBAND_ROFORMER_MODELS_PATH environment variable
3. 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 (71 assets covering every URL that was live in the 2026-07-12 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):

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

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

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

Note on download availability (re-audited 2026-07-12): 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, 37 of the 89 registry models are fully usable (checkpoint and config both live -- all of these carry recorded sha256 checksums); 36 checkpoints are dead, and 10 models are fully dead (both checkpoint and config unreachable). 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())

Development Installation

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

# Install with UV
uv sync

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

Acknowledgments

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

• Mel-Band-Roformer-Vocal-Model by Kimberley Jensen - Original model and training
• BS-RoFormer by Phil Wang (lucidrains) - PyTorch implementation of the RoFormer architecture
• python-audio-separator by Andrew Beveridge (nomadkaraoke) - Pre-trained checkpoints and model configurations
• Original Research - Wei-Tsung Lu, Ju-Chiang Wang, Qiuqiang Kong, and Yun-Ning Hung for the Band-Split RoPE Transformer paper

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

Citation

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

@inproceedings{Lu2023MusicSS,
    title   = {Music Source Separation with Band-Split RoPE Transformer},
    author  = {Wei-Tsung Lu and Ju-Chiang Wang and Qiuqiang Kong and Yun-Ning Hung},
    year    = {2023},
    url     = {https://api.semanticscholar.org/CorpusID:261556702}
}

Support

For issues and questions:

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