Open-Unmix

1.3.0 · active · verified Sat Apr 11

Open-Unmix is a PyTorch-based music source separation toolkit that provides pre-trained models and a flexible framework for separating audio into its constituent parts (vocals, drums, bass, other). The current version is 1.3.0, and the library is actively maintained with regular updates addressing bug fixes, performance improvements, and new model releases.

Warnings

breaking Starting from v1.2.1, the `umxl` model became the new default for inference (both CLI and Python API), potentially changing results compared to previous versions that defaulted to `umxhq`. Additionally, the training argument `--model` was renamed to `--checkpoint`.
Fix: To use the previous default, explicitly specify `model_name='umxhq'` when calling separation functions or using the CLI. Update training scripts to use the `--checkpoint` argument instead of `--model`.
breaking Support for `torchaudio <0.7.0` was dropped in Open-Unmix v1.1.1. Using older versions of `torchaudio` will result in compatibility errors.
Fix: Ensure your `torchaudio` installation is version 0.7.0 or newer. Upgrade using `pip install --upgrade torchaudio`.
gotcha The `umxl` model, introduced in v1.2.0 and made default in v1.2.1, is only licensed for non-commercial applications. Users must comply with its specific license terms.
Fix: Review the license terms associated with the `umxl` model. For commercial applications, consider using the `umxhq` model or other alternatives, explicitly specifying them during separation.
gotcha Python 3.6 support was removed in v1.3.0. The library now requires Python 3.9 or newer.
Fix: Upgrade your Python environment to version 3.9 or higher to use Open-Unmix v1.3.0 and later.
gotcha Fixes for broken Zenodo URLs were implemented in v1.3.0. Users of older versions might encounter issues when trying to download pre-trained models, as the URLs could be invalid or change.
Fix: For reliable model downloads, it is recommended to use Open-Unmix v1.3.0 or later. If using older versions and encountering download issues, manually verify the Zenodo model URLs or upgrade.

Install

pip install openunmix Install latest version

Imports

separate_audio

from openunmix.separate import separate_audio

Quickstart

This quickstart demonstrates how to use the `separate_audio` function to perform music source separation. It simulates loading a stereo audio signal and outputs a dictionary of separated stems, each as a PyTorch tensor. The `umxl` model is used by default for inference from version 1.2.1 onwards.

import torch
import numpy as np
from openunmix.separate import separate_audio

# Simulate stereo audio data (e.g., 10 seconds at 44.1 kHz)
sr = 44100
duration = 10  # seconds
num_frames = sr * duration

# Create a dummy audio tensor: (channels, samples)
# In a real scenario, load an audio file using torchaudio.load() or similar.
audio_data_np = np.random.randn(2, num_frames).astype(np.float32)
audio_tensor = torch.from_numpy(audio_data_np)

# Separate the audio into stems
# By default, 'umxl' model is used from v1.2.1 onwards
estimates = separate_audio(audio_tensor, rate=sr)

# 'estimates' is a dictionary with keys like 'vocals', 'drums', 'bass', 'other'
# Each value is a torch.Tensor representing the separated stem.
print("Separated stems and their shapes:")
for stem_name, stem_tensor in estimates.items():
    print(f"  {stem_name}: {stem_tensor.shape}")

# Example: access vocals
vocals = estimates['vocals']
# print(f"Vocals stem shape: {vocals.shape}")

view raw JSON →