BS-RoFormer-Infer

Production-ready, inference-only toolkit for Band-Split RoPE Transformer audio source separation

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

Features

• Inference Only: Lightweight package focused on production inference
• Auto-Download: Automatic checkpoint downloads with integrity verification
• 10+ Pre-trained Models: Vocals, instrumentals, dereverb, and multi-stem separation
• CLI Tools: bs-roformer-infer and bs-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 bs-roformer-infer

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

Download Models

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

# Download the recommended model (BS-RoFormer-SW)
bs-roformer-download --model roformer-model-bs-roformer-sw-by-jarredou

# Download by category
bs-roformer-download --category vocals --output-dir ./models

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

CLI Inference

# Using the recommended BS-RoFormer-SW model
bs-roformer-infer \
  --config_path models/roformer-model-bs-roformer-sw-by-jarredou/BS-Rofo-SW-Fixed.yaml \
  --model_path models/roformer-model-bs-roformer-sw-by-jarredou/BS-Rofo-SW-Fixed.ckpt \
  --input_folder ./songs \
  --store_dir ./outputs

Every WAV inside input_folder produces separated stems (vocals, drums, bass, guitar, piano, other) plus *_instrumental.wav.

Python API

from pathlib import Path
from ml_collections import ConfigDict
import torch
import yaml
from bs_roformer import MODEL_REGISTRY, DEFAULT_MODEL, get_model_from_config
from bs_roformer.inference import SafeLoaderWithTuple

# Use the default recommended model (BS-RoFormer-SW)
entry = MODEL_REGISTRY.get(DEFAULT_MODEL)

# Load config and model
with open(f"models/{entry.slug}/{entry.config}") as f:
    config = ConfigDict(yaml.load(f, Loader=SafeLoaderWithTuple))
model = get_model_from_config("bs_roformer", config)
model.load_state_dict(torch.load(f"models/{entry.slug}/{entry.checkpoint}", map_location="cpu"))

Recommended Model

BS-RoFormer-SW (roformer-model-bs-roformer-sw-by-jarredou) by jarredou is the recommended default model for audio source separation. It supports 6-stem separation (vocals, drums, bass, guitar, piano, other) and provides excellent quality for production workflows.

from bs_roformer import DEFAULT_MODEL
print(DEFAULT_MODEL)  # "roformer-model-bs-roformer-sw-by-jarredou"

Available Models

Categories: multi-stem, vocals, instrumental, dereverb

Registry Helpers

from bs_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("unwa")
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/bs-roformer-infer.git
cd bs-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:

• BS-RoFormer by Phil Wang (lucidrains) - Clean PyTorch implementation of the Band-Split RoPE Transformer 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

Citation

If you use BS-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/bs-roformer-infer/issues