mdxnet-infer

Inference-only MDX23C TFC-TDF drum source separation.

Overview

mdxnet-infer separates drum audio into individual component stems using the MDX23C TFC-TDF architecture. It ships one community-trained DrumSep model (6-stem), trained by aufr33 and jarredou. Model weights are downloaded automatically on first use, sha256-verified against org-recorded digests (see Weights provenance below).

Features

• 6-stem separation: kick, snare, toms, hi-hat, ride, crash (with optional cymbal merging)
• High-level separate() function and MDX23CInference class API
• Time-Frequency Convolution with Time-Distributed Fully-connected (TFC-TDF) blocks
• 44.1 kHz stereo output

Acknowledgments

mdxnet-infer is built on the MDX23C TFC-TDF architecture and the DrumSep model weights by aufr33 and jarredou.

• TFC-TDF v3 architecture originates from kuielab/sdx23 (KUIELab's entry to the Sound Demixing Challenge 2023, MIT licensed).
• Music-Source-Separation-Training by Roman Solovyev (ZFTurbo) — the training/inference framework this package's model.py is a verbatim-ported, inference-only subset of (models/mdx23c_tfc_tdf_v3.py, MIT licensed). See Citation for the associated benchmark paper.
• DrumSep model weights by aufr33 and jarredou — see Weights provenance below; these are separate community-trained checkpoints, not part of the ZFTurbo/KUIELab code release, and their license terms are not formally documented by the original authors.

Weights provenance

• 6-stem model (drumsep-6stem): aufr33-jarredou_DrumSep_model_mdx23c_ep_141_sdr_10.8059.ckpt, originally from the "aufr33-jarredou MDX23C DrumSep v0.1" release on github.com/jarredou/models.

• Original hosting is gone; re-hosted under org control. As of the 2026-07 campaign, the github.com/jarredou/models account/repository no longer exists — the original release assets are unreachable. openmirlab located the checkpoint and its config on two independent third-party Hugging Face mirrors, confirmed the two mirrors were byte-identical (matching sha256 digests), and re-published both files as an openmirlab-controlled GitHub Release so mdxnet-infer no longer depends on a third-party account staying online (org constitution art.4: weights hosting must be under org control or a verified mirror, never a single third-party account).

• Download URLs and checksums (auto-downloaded by the package; see Manual download for the manual recipe):

  File	URL	sha256
  aufr33-jarredou_DrumSep_model_mdx23c_ep_141_sdr_10.8059.ckpt	https://github.com/openmirlab/mdxnet-infer/releases/download/weights-drumsep-v1/aufr33-jarredou_DrumSep_model_mdx23c_ep_141_sdr_10.8059.ckpt	d2a4aa53eb584d21eead358a4e66d1882ad182911be018f052b5da73be9096d0
  aufr33-jarredou_DrumSep_model_mdx23c_ep_141_sdr_10.8059.yaml	https://github.com/openmirlab/mdxnet-infer/releases/download/weights-drumsep-v1/aufr33-jarredou_DrumSep_model_mdx23c_ep_141_sdr_10.8059.yaml	17d1649a227f841165bdb4c11a42082898192a1ea3ceab7e7e0b9293d6589dd6

  Every download (fresh or cached) is checked against these digests; a mismatch raises ChecksumMismatchError and deletes the bad file rather than silently loading it.

• 5-stem model (drumsep-5stem) is lost upstream — no longer available. It was also hosted only on github.com/jarredou/models (the "DrumSep" release, drumsep_5stems_mdx23c_jarredou.ckpt), which is gone. Unlike the 6-stem model, no intact original-quality mirror could be found anywhere on the web during this campaign — the only surviving copy is a derived OpenVINO conversion (Intel/drumsep_mdx23c_jarredou_openvino), which is not usable as a drop-in PyTorch checkpoint. drumsep-5stem has therefore been removed from KNOWN_MODELS (no auto-download path); the architecture config (MDX23CConfig.drumsep_5stem()) remains available for anyone who already has their own copy of the checkpoint. It may return to KNOWN_MODELS if a verified original-format mirror surfaces.

• License is not formally documented by aufr33/jarredou. No LICENSE file or explicit terms accompanied the original GitHub Release or the linked Colab notebooks. Third-party re-uploads disagree: a Hugging Face mirror of the same checkpoint (Politrees/UVR_resources) is tagged license:mit (uploader-asserted, not from the original authors), while the derived OpenVINO conversion (Intel/drumsep_mdx23c_jarredou_openvino) is tagged license:cc-by-nc-sa-4.0. Until the original authors confirm terms, treat these weights as non-commercial-safe only — do not assume MIT for the weights even though the code around them is MIT. openmirlab is a non-commercial project, so this is usable here, but downstream users with commercial intent should not assume the same.

Weights folder: default location and override

Downloaded weight files are cached in a directory resolved in this order:

1. The cache_dir argument to separate() / MDX23CInference.download_model() / MDX23CInference.from_pretrained(), or the CLI's --cache-dir flag.
2. The MDXNET_INFER_CACHE_DIR environment variable.
3. The default: ~/.cache/mdxnet-infer/.

# Override via env var
export MDXNET_INFER_CACHE_DIR=/path/to/weights
mdxnet-infer drums.wav -o output/

# Override via CLI flag
mdxnet-infer drums.wav -o output/ --cache-dir /path/to/weights

# Override via API argument
from mdxnet_infer import MDX23CInference
engine = MDX23CInference.from_pretrained("drumsep-6stem", cache_dir="/path/to/weights")

Manual download and offline use

For offline/air-gapped machines, download the two files from the table above yourself (e.g. with curl or a browser) and place them directly in the weights folder (default ~/.cache/mdxnet-infer/, or your MDXNET_INFER_CACHE_DIR/--cache-dir override) — no subdirectory needed, filenames must match exactly:

mkdir -p ~/.cache/mdxnet-infer
curl -L -o ~/.cache/mdxnet-infer/aufr33-jarredou_DrumSep_model_mdx23c_ep_141_sdr_10.8059.ckpt \
  https://github.com/openmirlab/mdxnet-infer/releases/download/weights-drumsep-v1/aufr33-jarredou_DrumSep_model_mdx23c_ep_141_sdr_10.8059.ckpt
curl -L -o ~/.cache/mdxnet-infer/aufr33-jarredou_DrumSep_model_mdx23c_ep_141_sdr_10.8059.yaml \
  https://github.com/openmirlab/mdxnet-infer/releases/download/weights-drumsep-v1/aufr33-jarredou_DrumSep_model_mdx23c_ep_141_sdr_10.8059.yaml

Verify the sha256 digests match the table above before use:

sha256sum ~/.cache/mdxnet-infer/aufr33-jarredou_DrumSep_model_mdx23c_ep_141_sdr_10.8059.*

Once both files are in place, mdxnet-infer/separate()/from_pretrained() will find and use them without attempting a download.

Quick Start

from mdxnet_infer import separate

# Separate a drum file (downloads model automatically)
output_paths = separate("drums.wav", output_dir="output/", model_name="drumsep-6stem")

Installation

With UV (Recommended)

uv add mdxnet-infer

With pip

pip install mdxnet-infer

Usage

CLI

# 6-stem separation (kick, snare, toms, hh, ride, crash)
mdxnet-infer drums.wav -o output/ --model drumsep-6stem

# Combine ride+crash into a single cymbals stem
mdxnet-infer drums.wav -o output/ --model drumsep-6stem --combine-cymbals

# Run on a specific device
mdxnet-infer drums.wav -o output/ --device cuda

# Use a custom weights folder (see Weights provenance below)
mdxnet-infer drums.wav -o output/ --cache-dir /path/to/weights

Python API

from mdxnet_infer import separate, MDX23CInference

# High-level convenience function
output_paths = separate("drums.wav", output_dir="output/", model_name="drumsep-6stem")

# Lower-level API with more control
engine = MDX23CInference.from_pretrained("drumsep-6stem", device="cuda")
import librosa
audio, sr = librosa.load("drums.wav", sr=None, mono=False)
stems = engine.separate(audio.T, sample_rate=sr)
# stems -> {"kick": array, "snare": array, "toms": array, "hh": array, "ride": array, "crash": array}

Supported Models

Citation

@misc{solovyev2023benchmarks,
      title={Benchmarks and leaderboards for sound demixing tasks},
      author={Roman Solovyev and Alexander Stempkovskiy and Tatiana Habruseva},
      year={2023},
      eprint={2305.07489},
      archivePrefix={arXiv},
      primaryClass={cs.SD}
}

(Citation as used by the upstream Music-Source-Separation-Training repository this architecture is ported from.)

License

• Code: MIT License. See LICENSE for details. src/mdxnet_infer/model.py is a verbatim-ported, inference-only subset of ZFTurbo's MIT-licensed Music-Source-Separation-Training, itself based on KUIELab's MIT-licensed TFC-TDF v3 architecture — both original copyrights are preserved in LICENSE.
• Weights: not covered by the above. See Weights provenance — the aufr33/jarredou DrumSep checkpoints have no formally documented license; treat as non-commercial-safe only until clarified.

Support

For bugs and feature requests, please open an issue on GitHub.