ssmall256/mlx-audio-separator

MLX Audio Separator

Separate music into vocals, drums, bass, guitar, piano, and other instruments on your Apple Silicon Mac. This repository contains seven ready-to-use safetensors models for mlx-audio-separator, with MLX inference, matching configurations, and individual validation reports. No PyTorch or ONNX runtime is required to use these weights.

Download one model or the full collection. All weights are hosted here, organized by model ID.

Models

Model	Output stems	Precision	Size
BS-RoFormer-SW	Bass, drums, other, vocals, guitar, piano	float32	666.5 MiB
Mel-RoFormer InstV7n	Instrumental, vocals	float32	870.6 MiB
UVR-MDX-NET Inst HQ3	Instrumental, vocals	float32	63.8 MiB
HTDemucs	Drums, bass, other, vocals	float32	160.2 MiB
HTDemucs_FT	Drums, bass, other, vocals	float32	640.9 MiB
HTDemucs_6s	Drums, bass, other, vocals, guitar, piano	float32	104.6 MiB
ZFTurbo Mel-RoFormer Vocals v1	Vocals, instrumental	float16	64.3 MiB

BS-RoFormer-SW separates six instruments in one model. HTDemucs produces four stems; HTDemucs_FT uses four specialist models, and HTDemucs_6s adds guitar and piano. For vocal and instrumental separation, choose InstV7n, Inst HQ3, or ZFTurbo Vocals v1.

All models produce stereo audio at 44.1 kHz. The complete collection is 2.51 GiB. Download sizes include weights and configurations; runtime memory use is higher and varies by model. Weight precision describes the stored tensors, not the precision of every inference operation.

Quick start

Requires an Apple Silicon Mac running macOS 26+, native Python 3.10+, and mlx-audio-separator 0.1.21 or later.

Release availability: automatic downloads require the upcoming 0.1.21 package release. The model files are available now through direct downloads. The CLI and Python examples below apply once 0.1.21 is released; PyPI 0.1.20 does not include this catalog integration.

Install mlx-audio-separator and choose a model:

python -m pip install "mlx-audio-separator>=0.1.21"
mlx-audio-separator song.m4a -m bs-roformer-sw --output_dir stems

The first use downloads the selected model automatically. The package verifies its weights and configuration against bundled SHA-256 hashes, caches them, and separates your audio. Later runs reuse the cache and work offline. You do not need to download or convert a checkpoint yourself.

The CLI writes FLAC by default; add --output_format WAV for WAV files.

Python

from mlx_audio_separator import Separator

separator = Separator(output_dir="stems", output_format="WAV")
separator.load_model("bs-roformer-sw")
output_files = separator.separate("song.m4a")

Reuse the separator for additional files. Each of the seven model cards lists its short catalog ID and existing package name; both select the same safetensors. For example, BS-Roformer-SW.ckpt remains an alias for bs-roformer-sw, and htdemucs_ft.yaml remains an alias for htdemucs_ft. The .ckpt, .onnx, and .yaml aliases are model names, not the formats downloaded for these entries. Choose a model explicitly: the package's historical default is a different BS-RoFormer checkpoint.

Cache and offline use

Automatic downloads go to ~/.cache/mlx-audio-separator/models/<model-id>/. Use --model_file_dir /path/to/models in the CLI, or model_file_dir="/path/to/models" in Python, to choose another model directory. AUDIO_SEPARATOR_MODEL_DIR can select an existing directory for both interfaces and takes precedence over those options.

Set HF_HUB_OFFLINE=1 or MLX_AUDIO_SEPARATOR_NO_DOWNLOAD=1 to prohibit downloads. A complete, verified cache works without network access. A missing or damaged file produces a clear error in offline mode; with downloads enabled, the package fetches the required replacement. Failed transfers do not overwrite existing files.

To free space, remove an unused model's folder. The next use restores the required files. The package also reuses matching files from older model caches where possible.

Direct downloads

You can also download weights and configurations directly from this repository's Files and versions tab, or use the Hugging Face client. This is useful for manual setup or preparing an offline machine.

python -m pip install huggingface_hub

from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="ssmall256/mlx-audio-separator",
    local_dir="mlx-separator-models",
    allow_patterns=["models/bs-roformer-sw/*"],
)

Point the normal CLI at the downloaded models/ directory:

HF_HUB_OFFLINE=1 mlx-audio-separator song.m4a \
  -m bs-roformer-sw \
  --model_file_dir mlx-separator-models/models \
  --output_dir stems

Keep each model's files together under its model ID. Replace bs-roformer-sw in both examples to choose another model, or use models/* as the download pattern for all seven. The package verifies manually downloaded files using the same checks as automatic downloads.

For reproducible downloads, pass a specific commit with snapshot_download(revision=...). Use a package release whose bundled file hashes match that revision. See the Hugging Face download guide for more options.

Inference settings

RoFormer models use two overlapping windows by default: each chunk starts halfway through the preceding chunk. Demucs uses two shifts and 25% overlap. Shift offsets are random by default; set --demucs_seed 0 or demucs_params={"seed": 0} for repeatable selection. Inst HQ3 uses 25% overlap and a segment size of 256. The normal package options remain available to adjust these settings.

The catalog manifest records filenames, sizes, SHA-256 hashes, source checkpoints, and conversion details. Each model card includes file hashes, and SHA256SUMS covers the repository's distributed files.

Validation

Every model passed offline inference on a 14-second real-music excerpt in a fresh process, producing the expected full-length, finite stereo stems at 44.1 kHz. These checks ran with network access disabled and imports of PyTorch, ONNX, and ONNX Runtime blocked.

The BS-RoFormer-SW, InstV7n, and Inst HQ3 conversions produced bit-identical unquantized stems to their original checkpoints loaded through the same MLX implementations. The three Demucs models and ZFTurbo Vocals v1 preserve the bytes of their existing published safetensors, verified against pinned source revisions.

The normal package loader also passed first-use download and offline-cache checks for all seven models using a local HTTP mirror of these files. Both runs produced bit-identical unquantized stems, with conversion dependencies blocked. See the automatic-download report.

After publication, all seven models were downloaded anonymously from this Hugging Face repository into an empty cache through the package's normal download resolver. Every file matched its expected size and SHA-256, and a second pass reused the cache with downloads disabled. See the public-download verification. This checks public availability and artifact integrity; it does not repeat model inference.

These checks establish artifact integrity and conversion consistency. The 14-second check is not a full quality evaluation or a speed benchmark. See Validation details for per-model reports and earlier comparisons against python-audio-separator, the upstream project used for PyTorch references.

Licensing and credit

Model weights have individual licensing terms; there is no single license covering the entire collection. The MIT license in LICENSE-code applies to the catalog helper. See Third-Party Notices for checkpoint and conversion credits, upstream software attribution, and links to the included model-specific license texts.

Models	Weight license information
BS-RoFormer-SW	The source model card lists the license as unknown.
Mel-RoFormer InstV7n	No weight-specific redistribution license is recorded in the source metadata.
UVR-MDX-NET Inst HQ3	No weight-specific redistribution license is recorded in the source metadata.
HTDemucs, HTDemucs_FT, HTDemucs_6s	MIT, as declared by the pinned Demucs MLX source repository; license notices accompany the weights.
ZFTurbo Vocals v1	The source card declares MIT, with a caveat that the source license was added after the checkpoint release. Its notice is included unchanged.

An unknown weight license is not a grant of permission. Consult the individual model cards and original sources for the terms relevant to your use.

The fixed BS-RoFormer-SW checkpoint traces to jarredou's distribution, mirrored by enerjazzer; InstV7n to Gabox; Inst HQ3 to the UVR/TRvlvr model release; Demucs to Meta and the Demucs contributors; and ZFTurbo Vocals v1 to Roman Solovyev (ZFTurbo), with its existing MLX conversion from mlx-community. Architecture credit belongs to the BS-RoFormer, Mel-Band-RoFormer, Demucs, and MDX/UVR authors and contributors.

MLX separator development and catalog preparation are maintained by ssmall256. Report runtime issues or request additional models in the mlx-audio-separator issue tracker.