Metadata-Version: 2.4
Name: melband-roformer-infer
Version: 0.1.4
Summary: Inference-only Mel-Band Roformer vocal separation toolkit
Project-URL: Homepage, https://github.com/openmirlab/melband-roformer-infer
Project-URL: Documentation, https://github.com/openmirlab/melband-roformer-infer#readme
Project-URL: Repository, https://github.com/openmirlab/melband-roformer-infer
Project-URL: Issues, https://github.com/openmirlab/melband-roformer-infer/issues
Author-email: OpenMIRLab <bernie40916@gmail.com>
License: MIT License
        
        Copyright (c) 2025 OpenMIRLab
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: audio,inference,pytorch,roformer,source-separation,vocals
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: beartype>=0.14
Requires-Dist: einops>=0.6.1
Requires-Dist: librosa>=0.9
Requires-Dist: ml-collections>=0.1.1
Requires-Dist: numpy>=1.23
Requires-Dist: packaging>=14.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31
Requires-Dist: rotary-embedding-torch>=0.3.5
Requires-Dist: soundfile>=0.12
Requires-Dist: torch>=2.0
Requires-Dist: tqdm>=4.64
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# 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.

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-red.svg)](https://pytorch.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/melband-roformer-infer)](https://pypi.org/project/melband-roformer-infer/)

---

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

```bash
# Using pip
pip install melband-roformer-infer

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

### CLI Inference

```bash
# 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

```python
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):

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

```bash
# 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.

```python
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 |
| `roformer-model-melband-roformer-vocals-by-becruily` | vocals | Vocals by becruily |
| `roformer-model-melband-roformer-instrumental-by-gabox` | instrumental | Instrumental by Gabox |
| `roformer-model-melband-roformer-karaoke-by-becruily` | karaoke | Karaoke 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 |
| ... | ... | See `--list-models` for 89 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

```python
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

```bash
# 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](https://huggingface.co/KimberleyJSN/melbandroformer)** by Kimberley Jensen - Original model and training
- **[BS-RoFormer](https://github.com/lucidrains/BS-RoFormer)** by Phil Wang (lucidrains) - PyTorch implementation of the RoFormer architecture
- **[python-audio-separator](https://github.com/nomadkaraoke/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](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:

```bibtex
@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](https://github.com/openmirlab/melband-roformer-infer/issues)

---
