BS-RoFormer-Infer

Current installation: pip install "bs-roformer-infer @ git+https://github.com/openmirlab/bs-roformer-infer.git" OpenMIRLab no longer publishes new versions to PyPI. Any existing PyPI releases are historical snapshots.

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.

Devices

from bs_roformer import BSRoformerSession

with BSRoformerSession(device="cuda") as session:
    session.infer("songs/", store_dir="stems/")

bs-roformer-infer --input_folder songs --device cuda

device accepts None (legacy default), auto, cpu, cuda, or cuda:N. Legacy None and explicit auto select CUDA when available, otherwise CPU. An explicitly requested accelerator that is unavailable raises rather than being silently downgraded.

This package is Torch/CUDA/CPU only. Apple Silicon (MPS) and MLX support were removed before release (org decision 2026-09-14, out of scope for openmirlab); device="mps" raises a clear ValueError naming why.

Lifecycle

BSRoformerSession.release() permits a later reload, while close() is terminal. Loading and cache_info() use the same checkpoint resolver; its package-owned config/checkpoints.toml remains the authoritative URL/integrity metadata. Legacy JSON files remain only as transition compatibility fixtures and are not read by production registry/download resolution.

---

Why This Exists

BS-RoFormer (Band-Split RoPE Transformer) is a strong architecture for music source separation, introduced by Lu, Wang, Kong, and Hung (2023). The reference implementation, lucidrains/BS-RoFormer, provides the model architecture only -- no checkpoint management, no CLI, no packaging for downstream use. Trained checkpoints 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/Google Drive accounts -- hosts that can and do vanish without warning. This project's own history includes exactly that: the original jarredou Hugging Face account behind the default BS-RoFormer-SW checkpoint was deleted (discovered 2026-06), and 9 of the other 10 registry models' fallback URLs (the dead upstream TRvlvr/model_repo GitHub repo) were found 404ing in a 2026-07-12 audit.

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

• 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
• Politrees/UVR_resources on Hugging Face -- current mirror host for 9 of the 10 registry checkpoints, after the original TRvlvr source went dead (see Model Weights)
• anvuew/dereverb_bs_roformer on Hugging Face -- author-hosted config for the De-Reverb model
• enerjazzer/BS-ROFO-SW-Fixed on Hugging Face -- current host for the default BS-RoFormer-SW checkpoint, after the original jarredou account was deleted

Citation

If you use BS-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
• 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

Scope

In scope: inference (forward pass) with the BS-RoFormer architecture; a 34-entry registry spanning multi-stem, 53-stem mega, four-stem, vocals, karaoke, instrumental, and de-reverb 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 "bs-roformer-infer @ git+https://github.com/openmirlab/bs-roformer-infer.git"

# Using UV (recommended)
uv pip install "bs-roformer-infer @ git+https://github.com/openmirlab/bs-roformer-infer.git"

Quick Start

# First run auto-downloads the recommended BS-RoFormer-SW model (~700 MB,
# sha256-verified) into ~/.cache/bs-roformer-infer/ -- no separate download step needed
bs-roformer-infer --input_folder ./songs --store_dir ./outputs

Every WAV inside input_folder produces separated stems (vocals, drums, bass, guitar, piano, other) plus *_instrumental.wav. Explicit --config_path/--model_path arguments still work and skip auto-resolution entirely.

---

Python API

from ml_collections import ConfigDict
import torch
import yaml
from bs_roformer import DEFAULT_MODEL, ensure_model_assets, get_model_from_config
from bs_roformer.inference import SafeLoaderWithTuple

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

with open(config_path) as f:
    config = ConfigDict(yaml.load(f, Loader=SafeLoaderWithTuple))
model = get_model_from_config("bs_roformer", config)
model.load_state_dict(torch.load(ckpt_path, map_location="cpu"))

Recommended Model

BS-RoFormer-SW (roformer-model-bs-roformer-sw-by-jarredou) is the recommended default model for audio source separation. It supports 6-stem separation (vocals, drums, bass, guitar, piano, other). The slug preserves the historical jarredou release name; we have not verified who trained the weights. The current checkpoint mirror labels their license unknown, and the ONNX export's model card says the rehoster did not train them and has no trainer provenance. The architecture and conversion code licenses do not establish a license for these pretrained weights. Do not treat this package's MIT code license as a grant for commercial use of this checkpoint.

The real-weight regression in tests/test_original_default_golden.py compares the complete six-stem FP32 and CUDA-autocast output with pristine lucidrains/BS-RoFormer@93a07dd, using the SHA-256-pinned default checkpoint and config. A separate 13.4-second fixture verifies all seven public-session WAV outputs, including the derived instrumental stem, across the default chunk boundary. This second fixture records this package's existing session pipeline; upstream provides the model architecture, not that wrapper. Run pytest -m realweights with the official assets cached and the recorded Torch/CUDA profile to execute the real model tests. Hosted CPU CI validates fixture metadata; no checkpoint bytes are committed.

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

Available Models

Categories: multi-stem, mega-stem, four-stem, vocals, karaoke, instrumental, dereverb

The MVSep Mega entry exposes 53 raw stems from one BS-RoFormer checkpoint. It is useful for broad stem discovery, but it is much larger than the default model and the upstream release notes warn that individual stems may be weaker than specialized models.

HyperACE v1/v2, FNO, and Large-Inst checkpoints use model variations: the RoFormer trunk is the same, but the mask estimator head is different. Siamese and Value Residual checkpoints use distinct trunk variations. Registry-selected models load these variations automatically. The FNO variation is a bundled minimal FNO1d inference implementation, so installing this package does not pull in the full neuraloperator research framework. The Large-Inst variation adds four alternating time/frequency Transformer pairs before the mask MLP.

As of the 2026-07-12 re-audit, all registry entries have a live download URL (see the availability note in What This Project Will NEVER Bundle).

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())

---

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/bs_roformer/config/checkpoints.toml, and cached locally -- a mismatch deletes the file and retries instead of silently keeping a corrupt checkpoint.

Where weights live

Downloads default to ~/.cache/bs-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 BS_ROFORMER_MODELS_PATH environment variable
3. The default ~/.cache/bs-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 bs-roformer-infer runs without --model_path/--config_path, the requested registry model (default: BS-RoFormer-SW) is looked up in the directories above and downloaded on first use. Downloads are verified against the sha256 checksums recorded in src/bs_roformer/config/checkpoints.toml; a mismatch deletes the file and retries instead of keeping a corrupt checkpoint.

Manual download (offline / air-gapped)

The recommended BS-RoFormer-SW model needs one file (its config ships inside the package):

Place it at ~/.cache/bs-roformer-infer/roformer-model-bs-roformer-sw-by-jarredou/BS-Rofo-SW-Fixed.ckpt (or the equivalent path under your BS_ROFORMER_MODELS_PATH), and inference will pick it up without network access.

Additional registry assets (see CHANGELOG for full provenance) download from these mirrors:

The Chorus/Male-Female-aufr33 config (config_chorus_male_female_bs_roformer.yaml) and the three Revive checkpoints' shared config (config_bs_roformer_vocals_revive_unwa.yaml) are also fetched from Politrees/UVR_resources — see config/checkpoints.toml for the exact URLs and hashes.

Download CLI (manual path)

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

# Download the recommended model into the cache dir
bs-roformer-download --model roformer-model-bs-roformer-sw-by-jarredou

# Download into a custom directory
bs-roformer-download --model roformer-model-bs-roformer-sw-by-jarredou --output-dir ./models

Note on download availability (re-audited 2026-07-23): all registry models now have live download sources. The 9 that fell back to the dead upstream TRvlvr repository were re-hosted to Politrees/UVR_resources (with the De-Reverb config sourced from the author's anvuew/dereverb_bs_roformer repo instead — see CHANGELOG for why). Run python tools/check_weights_liveness.py (needs network) to re-check.

---

Development

# Clone repository
git clone https://github.com/openmirlab/bs-roformer-infer.git
cd bs-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 -- the latter need real hardware and real checkpoints)
uv run ruff check .    # lint

---

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

---

Support

For issues and questions:

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

---

Explicit lifecycle API

For applications that need controlled model lifetime, use BSRoformerSession:

from bs_roformer import BSRoformerSession
with BSRoformerSession() as session:
    session.infer("input_folder", store_dir="outputs")

load() downloads and verifies weights, infer() requires a ready session, release() frees memory while retaining the disk cache, and cache_info() reports the selected checkpoint. Existing CLI and downloader entry points remain available and lazy. Checkpoint URLs and SHA-256 metadata live in the package-owned config/checkpoints.toml and can be overridden with explicit paths or metadata.

OpenMIRLab inference contract

This package is inference-only. The public clean facade exposes an explicit lifecycle session (load, ready-only infer, release, close, status, cache_info, and context-manager support) while retaining the legacy one-shot API for compatibility. Checkpoint URLs and integrity metadata are package-owned in config/checkpoints.toml; callers may provide a generic checkpoint override without changing package code.