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: Automatic checkpoint downloads with integrity verification
• 70+ Pre-trained Models: Vocals, instrumentals, karaoke, denoise, dereverb, and more
• CLI Tools: melband-roformer-infer and melband-roformer-download commands
• Python API: Clean programmatic interface
• Model Registry: Easy model discovery with search and category filtering

Try it in Colab

No installation needed! Try the demo directly in Google Colab:

Quick Start

Installation

# Using pip
pip install melband-roformer-infer

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

Download Models

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

# Download the recommended model (MelBand Roformer Kim)
melband-roformer-download --model melband-roformer-kim-vocals

# Download by category
melband-roformer-download --category karaoke --output-dir ./models

# Download all models
melband-roformer-download --all --output-dir ./models

CLI Inference

# Using the recommended MelBand Roformer Kim model
melband-roformer-infer \
  --config_path models/melband-roformer-kim-vocals/config_vocals_mel_band_roformer.yaml \
  --model_path models/melband-roformer-kim-vocals/MelBandRoformer.ckpt \
  --input_folder ./songs \
  --store_dir ./outputs

Every WAV inside input_folder produces *_vocals.wav and *_instrumental.wav stems.

Python API

from pathlib import Path
from ml_collections import ConfigDict
import torch
import yaml
from mel_band_roformer import MODEL_REGISTRY, DEFAULT_MODEL, get_model_from_config

# Use the default recommended model (MelBand Roformer Kim)
entry = MODEL_REGISTRY.get(DEFAULT_MODEL)

# Load config and model
config = ConfigDict(yaml.safe_load(open(f"models/{entry.slug}/{entry.config}")))
model = get_model_from_config("mel_band_roformer", config)
model.load_state_dict(torch.load(f"models/{entry.slug}/{entry.checkpoint}", 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

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

Note on download availability: 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). That audit repointed 43 dead entries to a live mirror, but ~10 of the 89 registry models are still fully dead (both checkpoint and config unreachable) and could not be matched to a live source yet -- see CHANGELOG.md for the full breakdown. Run python tools/check_weights_liveness.py (needs network access) to 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