| --- |
| license: other |
| pipeline_tag: audio-to-audio |
| library_name: unblend |
| tags: |
| - audio |
| - music |
| - source-separation |
| - music-source-separation |
| - demucs |
| - roformer |
| - onnx |
| - onnxruntime |
| - webgpu |
| --- |
| |
| # unblend model artifacts |
|
|
| Model weights and browser-ready ONNX graphs for |
| [unblend](https://github.com/Ryan5453/unblend), an audio source-separation |
| library for Python and the browser. |
|
|
| These artifacts support music stem separation at 44.1 kHz using HTDemucs, |
| BS-RoFormer, and Mel-Band RoFormer architectures. |
|
|
| ## Models |
|
|
| | Model | Output stems | Python | Browser | Weight terms | |
| |---|---|---:|---:|---| |
| | `htdemucs` | drums, bass, other, vocals | Yes | Yes | No explicit license grant identified for the released weights | |
| | `htdemucs_ft` | four-stem specialist ensemble | Yes | No | No explicit license grant identified for the released weights | |
| | `htdemucs_6s` | drums, bass, other, vocals, guitar, piano | Yes | Yes | No explicit license grant identified for the released weights | |
| | `bs_roformer_sw` | bass, drums, other, vocals, guitar, piano | Yes | Yes | CC-BY-NC-SA-4.0 | |
| | `melband_roformer_kim` | vocals, other | Yes | Yes | CC-BY-NC-SA-4.0 | |
|
|
| ## Artifact formats |
|
|
| ### Safetensors |
|
|
| The `.safetensors` files are pickle-free Python checkpoint weights consumed by |
| the `unblend` model repository. Their exact sizes and SHA-256 values are |
| registered in [`unblend/metadata.json`](https://github.com/Ryan5453/unblend/blob/main/unblend/metadata.json). |
|
|
| The HTDemucs releases distributed by Meta stored their checkpoint state in |
| FP16. The corresponding Safetensors preserve that released precision. |
| HTDemucs inference may still run with FP32 parameters and computation depending |
| on the selected device and `dtype`. |
|
|
| The RoFormer Safetensors contain FP32 weights. |
|
|
| ### ONNX |
|
|
| Each browser-supported model has two ONNX variants: |
|
|
| - `*_fp32.onnx` — weights stored as FP32. |
| - `*_fp16.onnx` — eligible weights stored as FP16 and cast back to FP32 before |
| use. Inputs, outputs, activations, and computation remain FP32. |
|
|
| The FP16 ONNX variants reduce download size; they are not true FP16-compute |
| graphs. This avoids the audible numerical degradation observed with native |
| FP16 accumulation in ONNX Runtime Web/WASM. |
|
|
| The exact ONNX sizes and SHA-256 values are registered in |
| [`web/demucs/src/model-artifacts.ts`](https://github.com/Ryan5453/unblend/blob/main/web/demucs/src/model-artifacts.ts). |
| All model URLs used by the package are pinned to immutable Hugging Face |
| revisions. |
|
|
| ## Usage and API documentation |
|
|
| The GitHub documentation is the maintained source for installation, usage, and |
| API details: |
|
|
| - [Project README and Python quick start](https://github.com/Ryan5453/unblend/blob/main/readme.md) |
| - [Python API reference](https://github.com/Ryan5453/unblend/blob/main/api.md) |
| - [ONNX export and runtime notes](https://github.com/Ryan5453/unblend/blob/main/onnx.md) |
| - [Browser/npm package API](https://github.com/Ryan5453/unblend/blob/main/web/demucs/README.md) |
|
|
| ## Integrity verification |
|
|
| Repository maintainers can stream every published ONNX artifact and verify its |
| size and SHA-256 without retaining an additional full model copy in memory: |
|
|
| ```bash |
| cd web |
| npm run verify:model-artifacts -w unblend |
| ``` |
|
|
| Python downloads are independently verified against the exact sizes and |
| SHA-256 values in `unblend/metadata.json` before model construction. |
|
|
| ## Licensing |
|
|
| The `unblend` source code is MIT-licensed. This does not relicense the model |
| weights. |
|
|
| ### HTDemucs |
|
|
| HTDemucs was developed by Alexandre Défossez and Meta. The released model |
| weights were trained using MUSDB18-HQ and additional proprietary training |
| material. No explicit license grant for the released HTDemucs weights has been |
| identified, so users should not assume that the code's MIT license applies to |
| those weights. |
|
|
| ### RoFormer |
|
|
| The BS-RoFormer and Mel-Band RoFormer weights are labeled |
| CC-BY-NC-SA-4.0 in their release metadata. They are non-commercial and require |
| attribution and share-alike treatment. |
|
|
| - BS-RoFormer-SW: model by jarredou; checkpoint provenance includes the |
| enerjazzer mirror. |
| - Mel-Band RoFormer: vocals model by Kimberley Jensen. |
|
|
| Users are responsible for ensuring that their use complies with the applicable |
| weight terms and the rights associated with their input audio. |
|
|
| ## Limitations |
|
|
| - Source separation is imperfect and may introduce bleed, artifacts, or missing |
| content. |
| - Model behavior depends on the source material and selected architecture. |
| - RoFormer weights are non-commercial. |
| - Browser inference requires substantial memory and can be slow on unsupported |
| or low-memory devices. |
| - The ONNX FP16 variants reduce transfer size but do not guarantee lower runtime |
| memory consumption, because ONNX Runtime may materialize FP32 constants when |
| creating a session. |
|
|
| ## Attribution |
|
|
| - [Demucs](https://github.com/facebookresearch/demucs) — Alexandre Défossez / |
| Meta |
| - BS-RoFormer-SW — jarredou |
| - Mel-Band RoFormer — Kimberley Jensen |
| - Integration, safe artifact loading, ONNX export, and browser runtime — |
| [unblend](https://github.com/Ryan5453/unblend) |
|
|
