WAIT — Stale — last commit 1y ago

• 10 active contributors
• Distributed ownership (top contributor 40% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago
• ⚠ Scorecard: marked unmaintained (0/10)

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests + OpenSSF Scorecard}

Spleeter is Deezer's open-source source separation library that uses TensorFlow to decompose audio tracks into isolated stems (vocals, drums, bass, piano, other). It provides pre-trained models for 2-stem (vocals/accompaniment), 4-stem, and 5-stem separation, achieving 100x faster-than-real-time performance on GPUs and competitive results on the MUSDB dataset. Monorepo with core library in spleeter/ subdirectory: spleeter/audio/ handles audio I/O and spectrograms (adapter.py, convertor.py, ffmpeg.py), spleeter/dataset.py manages training data, and the model configuration lives in configs/ (2stems, 4stems, 5stems JSON configs). CLI entry point is spleeter/main.py. Dockerfiles for different CUDA versions and conda packages provide deployment flexibility.

Music producers, audio engineers, and machine learning researchers who need to programmatically isolate instrument tracks from mixed audio—either via CLI commands or by embedding the Python library into their own pipelines. Contributors are typically ML engineers familiar with TensorFlow and audio processing.

Production-ready and actively maintained. The codebase has PyPI releases (2.1.0+ with breaking changes documented in CHANGELOG.md), multi-platform CI/CD workflows (test.yml, conda.yml, docker.yml, pypi.yml in .github/workflows/), Docker multi-version support (CUDA 9.2, 10-0, 10-1), and is published on conda-forge and Docker Hub. However, the 2.1.0 release introduced breaking changes, so users upgrading should read the changelog carefully.

Low-to-moderate risk: codebase is stable and Deezer-backed, but depends on TensorFlow (a heavy, fast-moving dependency) and requires careful GPU/CPU configuration. Breaking changes were introduced in v2.1.0 (new CLI option naming, dropped dedicated GPU package), so downstream users upgrading may experience friction. No visible open-source governance docs (CODEOWNERS exists but is not populated in the provided file structure), raising questions about long-term maintenance if Deezer's priorities shift.

Library is in maintenance mode with focus on stability and compatibility. Recent work includes CI/CD pipeline maturation (.github/workflows/ shows active testing, conda, and Docker build automation), and v2.1.0 addressed breaking changes around CLI naming and GPU package consolidation. The interactive notebook spleeter.ipynb suggests educational use is encouraged.

Clone and install:

git clone https://github.com/deezer/spleeter.git
cd spleeter
pip install -e .

Or use conda:

conda install -c deezer-research spleeter

Quick test with provided audio:

spleeter separate -i audio_example.mp3 -o output

Daily commands: CLI usage (from README snippet):

spleeter separate -i audio_example.mp3 -o output

For Python API, see spleeter.ipynb for Jupyter examples. Train models using configs/musdb_train.csv and dataset.py, or use pre-trained models (automatic download).

• spleeter/separator.py — Core API entry point for audio separation—all source separation workflows start here.
• spleeter/model/provider/__init__.py — Model provider abstraction that manages pretrained model loading and caching from GitHub.
• spleeter/audio/adapter.py — Audio I/O abstraction layer handling multiple backend formats (FFmpeg, librosa, etc.).
• spleeter/model/functions/unet.py — U-Net neural network architecture implementation—the core ML model for source separation.
• spleeter/utils/configuration.py — Configuration loading and validation system that drives model selection and training parameters.
• spleeter/__main__.py — CLI entry point providing command-line interface for separation, training, and evaluation.
• spleeter/audio/spectrogram.py — Audio feature extraction (spectrograms) that converts raw audio into model-readable tensors.

Add a new audio backend (e.g., WaveFile instead of FFmpeg)

1. Create a new adapter class inheriting from AudioAdapter in spleeter/audio/adapter.py (spleeter/audio/adapter.py)
2. Implement load() and save() methods using your library (spleeter/audio/my_adapter.py)
3. Update Separator.__init__() to accept backend parameter and instantiate your adapter (spleeter/separator.py)
4. Add test case in tests/test_separator.py verifying audio round-trip (tests/test_separator.py)

Add a new model architecture (e.g., Transformer-based)

1. Create new architecture file (e.g., spleeter/model/functions/transformer.py) with TensorFlow/PyTorch model (spleeter/model/functions/transformer.py)
2. Add configuration JSON in configs/6stems/ defining layer sizes, training params, and architecture name (configs/6stems/base_config.json)
3. Register metadata in spleeter/resources/6stems.json with model checksum and download URL (spleeter/resources/6stems.json)
4. Update spleeter/model/provider/github.py to handle new architecture type in load_model() (spleeter/model/provider/github.py)
5. Add training script in tests/test_train.py to validate model convergence (tests/test_train.py)

Add a new CLI command (e.g., spleeter evaluate)

1. Add command handler function and argument group in spleeter/options.py (spleeter/options.py)
2. Implement evaluation logic (e.g., in new spleeter/evaluate.py module) using SDR/SIR metrics (spleeter/evaluate.py)
3. Wire command dispatch in spleeter/__main__.py to call your evaluation function (spleeter/__main__.py)
4. Add test case in tests/test_command.py verifying CLI invocation (tests/test_command.py)

Support a new sample rate (e.g., 48kHz variant)

1. Create config configs/2stems/48khz_config.json with adjusted STFT parameters (configs/2stems/48khz_config.json)
2. Add model metadata to spleeter/resources/2stems-48kHz.json with checkpoint URL (spleeter/resources/2stems-48kHz.json)
3. Update spleeter/audio/convertor.py to handle sample rate resampling in the pipeline (spleeter/audio/convertor.py)
4. Test with tests/test_separator.py using 48kHz audio example (tests/test_separator.py)

• TensorFlow/Keras — Production-ready DL framework with GPU support for real-time or batch audio separation inference
• FFmpeg — Robust, multi-format audio codec support without licensing restrictions; decouples Spleeter from audio format specifics
• NumPy/SciPy — Standard audio DSP stack for STFT, windowing, and fast tensor operations
• GitHub Releases API — Decentralized model distribution; versioning and release management without dedicated model server

• Pretrained models downloaded at runtime rather than bundled

  • Why: Model weights are large (~100MB–1GB per config); bundling increases package size prohibitively
  • Consequence: First inference requires network access and download (~1–5s); subsequent runs use local cache

• U-Net + BLSTM over Transformer for base architecture

  • Why: Proven performance on speech/music separation; lower computational footprint than Transformers; release predates Transformer dominance
  • Consequence: Transformers may outperform on certain datasets but require more memory and training data; architecture extensible

• Fixed sample rates (16kHz, 44.1kHz) with separate model configs per rate

  • Why: Simplifies training pipeline; avoids resampling artifacts; aligns with standard audio processing conventions
  • Consequence: User must pre-resample non-standard rates (e.g., 48kHz → 44.1kHz) or train custom model; slight added user friction

• CLI-first design with Separator class as secondary API

  • Why: Deezer's primary use-case is batch processing; CLI is more accessible to non-Python users
  • Consequence: Programmatic API less ergonomic than dedicated Python packages; requires wrapping in small scripts

• Does not provide real-time streaming separation (batch processing only)
• Does not include music metadata tagging or downstream music analysis
• Does not handle authentication or user accounts
• Does not support Windows subsystem for Linux (WSL) officially, though community workarounds exist
• Does not provide GPU memory optimization for mobile/edge devices

1. Audio backend dependency: FFmpeg must be installed on the system (spleeter/audio/ffmpeg.py). CLI won't work without it; no graceful fallback in file list. 2. TensorFlow version pinning: poetry.lock will enforce specific TensorFlow version; GPU vs CPU builds can conflict if not carefully managed (v2.1.0 dropped dedicated GPU package, now unified). 3. Model download on first use: Pre-trained models auto-download from network on first separation call—no offline mode visible. Slow on first run, can fail silently with network issues. 4. MUSDB dataset not included: configs/musdb_train.csv and musdb_validation.csv reference external MUSDB data; training requires separate download and setup. 5. Audio sample rates and channel count: spectrogram.py likely expects specific audio properties; mismatched sample rates between model training and input can cause silent failures.

• Source Separation (Music Information Retrieval) — Spleeter's primary goal; understanding the signal processing and ML techniques (e.g., U-Net, time-frequency masking) that enable decomposing mixed audio into isolated instruments is essential to use and improve the library
• Short-Time Fourier Transform (STFT) and Spectrogram — The spectrogram.py module converts waveforms to time-frequency representation (magnitude and phase); understanding STFT is critical to debug audio preprocessing, modify window sizes, or handle edge cases
• U-Net Architecture — The pre-trained models likely use U-Net (encoder-decoder with skip connections) for spectrogram-to-mask regression; understanding this architecture helps when reading configs and training custom models
• Time-Frequency Masking — Spleeter separates stems by predicting multiplicative or ideal ratio masks applied to the input spectrogram; this is the core technique behind why configs/ specify mask thresholds and normalization
• Audio Codec and Container Formats (WAV, MP3, FLAC) — spleeter/audio/adapter.py and ffmpeg.py handle multiple audio formats; understanding codec differences (lossy vs. lossless, bit depth, sample rate) is essential for debugging format conversion and ensuring output quality
• TensorFlow SavedModel Format — Pre-trained models are likely stored as TensorFlow SavedModels; understanding how to load, inspect, and serve these models is necessary for deployment and custom model integration
• Conda and Python Packaging Ecosystems — Spleeter is distributed via pip (pyproject.toml), conda (conda/spleeter/meta.yaml), and Docker; understanding dependency resolution, virtual environments, and cross-platform builds is critical for installation troubleshooting and contribution

• facebook/demucs — Competing source separation library using convolutional neural networks; users often choose between Spleeter and Demucs based on speed vs. quality tradeoffs
• sigsep/musdb — Upstream dataset repository (MUSDB) referenced in configs/musdb_train.csv and configs/musdb_validation.csv; required for training and benchmarking Spleeter models
• mirdata/mirdata — Music information retrieval dataset toolkit; provides unified interface to MUSDB and other datasets commonly used with Spleeter for training and evaluation
• tensorflow/tensorflow — Core deep learning framework that Spleeter is built on; understanding TensorFlow's audio processing and model serving is essential for extending Spleeter

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for audio adapter and converter modules

The spleeter/audio/ directory contains critical audio processing modules (adapter.py, convertor.py, ffmpeg.py, spectrogram.py) but there's no visible test directory structure for these components. Given that audio I/O is fundamental to the library's functionality, adding tests would catch regressions in audio format handling, FFmpeg integration, and spectrogram computation across different input types and edge cases.

• [ ] Create tests/audio/ directory structure mirroring spleeter/audio/
• [ ] Add unit tests for spleeter/audio/adapter.py covering different audio formats and sample rates
• [ ] Add tests for spleeter/audio/convertor.py testing audio conversion between formats
• [ ] Add tests for spleeter/audio/ffmpeg.py covering FFmpeg command construction and execution
• [ ] Add tests for spleeter/audio/spectrogram.py validating spectrogram generation
• [ ] Integrate test suite into .github/workflows/test.yml CI pipeline

Add model provider tests and documentation for GitHub model fetching

The spleeter/model/provider/github.py module handles downloading pretrained models from GitHub releases, which is critical infrastructure. There are no visible tests for this component, and the resource JSON files (spleeter/resources/*.json) reference models but lack documentation on the provider mechanism. This PR would improve reliability of model downloads and add clarity for users/contributors.

• [ ] Add tests/model/provider/ directory with github.py test suite
• [ ] Create unit tests for GitHub release API interaction in spleeter/model/provider/github.py
• [ ] Add tests for model caching and validation logic
• [ ] Document the model provider architecture in README.md with a 'Model Configuration' section
• [ ] Add docstrings to spleeter/model/provider/init.py explaining how to add new providers
• [ ] Create example configuration showing how resource JSONs map to model providers

Refactor and test spleeter/options.py with dedicated argument parsing tests

The spleeter/options.py module handles CLI argument parsing, but there's no visible test coverage for command-line argument validation, default values, or error handling. With multiple configuration files (configs/*/base_config.json), configurations, and command-line invocations, comprehensive option testing would prevent CLI breaking changes and improve user experience.

• [ ] Create tests/test_options.py with parametrized tests for all CLI arguments
• [ ] Add tests validating stem configuration selection (2stems, 4stems, 5stems)
• [ ] Add tests for audio input/output path handling and validation
• [ ] Add tests for bitrate, sample rate, and codec option combinations
• [ ] Add tests for MuSDB configuration path resolution (configs/musdb_config.json)
• [ ] Document all CLI options in README.md with examples for each configuration type

• Add unit tests for spleeter/audio/convertor.py: The file exists but no tests are visible in the file list. Writing tests for audio format conversion (WAV, MP3, FLAC) would catch regressions and help new contributors understand the pipeline.
• Document model architecture in README or docs/: The configs/ directory shows model names (2stems, 4stems, 5stems) but the actual TensorFlow model definition files are not in the provided file structure. Adding a detailed architecture diagram or docstring explaining how stems are separated would help users and contributors understand the core ML logic.
• Add integration test for the full CLI workflow: spleeter/main.py is the entry point but no end-to-end test covering 'separate -i audio.mp3 -o output' with validation of output stems is visible. This would catch CLI regressions across Python versions and OS platforms (Docker workflows suggest multi-platform testing is needed).

The Spleeter codebase has moderate security posture with several areas of concern. The primary risks are around external model downloads without verification, potential command injection in FFmpeg integration, and insecure deserialization of configuration files. The project lacks visible security hardening mechanisms such as input validation, resource limits, and cryptographic verification of downloaded artifacts. No hardcoded secrets were identified in the file structure. Recommended actions: implement checksum verification for model downloads, secure FFmpeg command construction, validate all input files and configuration, and add resource limits for audio processing operations. The codebase would benefit from security-focused code review and adding integration tests for malformed input handling.

• High · External Model Download from GitHub without Checksum Verification — spleeter/model/provider/github.py. The file 'spleeter/model/provider/github.py' likely downloads pretrained models from GitHub. Without cryptographic checksum verification (SHA-256/SHA-512), this creates a Man-in-the-Middle (MITM) attack vector where an attacker could serve malicious model files. Fix: Implement cryptographic verification of downloaded models using checksums or signatures. Store checksums securely in the codebase and verify them against downloaded files before loading.
• Medium · Potential Command Injection via FFmpeg Integration — spleeter/audio/ffmpeg.py, spleeter/audio/adapter.py. The audio processing pipeline uses FFmpeg (referenced in spleeter/audio/ffmpeg.py). If user input is passed unsanitized to FFmpeg command construction, this could lead to command injection vulnerabilities. Fix: Ensure all FFmpeg commands are constructed using argument arrays (subprocess.run with list args) rather than shell strings. Avoid subprocess.call() with shell=True. Validate and sanitize all user-provided file paths and parameters.
• Medium · Insecure Deserialization of Configuration Files — spleeter/utils/configuration.py, configs/ directory. Configuration files (configs/*.json) are loaded and parsed. If these use insecure deserialization methods or if configuration loading doesn't validate input structure, this could lead to arbitrary code execution or data manipulation. Fix: Use safe JSON parsing methods (json.load with strict mode). Validate configuration schema against a whitelist of expected keys and types. Do not use pickle or yaml.load() without Loader=yaml.SafeLoader.
• Medium · Missing Input Validation on Audio File Processing — spleeter/separator.py, spleeter/audio/adapter.py. The separator and audio adapter modules process user-supplied audio files. Without proper validation, this could lead to denial-of-service (DoS) through malformed files, excessive file sizes, or resource exhaustion attacks. Fix: Implement file size limits, timeout controls, and validation of audio file headers/formats before processing. Add resource limits (memory, CPU time) for audio processing operations.
• Low · Sensitive Information in Example Files — audio_example.mp3, audio_example_mono.mp3. The repository includes example audio files (audio_example.mp3, audio_example_mono.mp3) in the root directory. While not secrets, this increases the repository size and could potentially contain identifiable information. Fix: Consider storing large binary files in Git LFS or a separate artifact repository. Ensure example audio files do not contain sensitive or personally identifiable information.
• Low · Potential Logging of Sensitive Information — spleeter/utils/logging.py, spleeter/separator.py. The logging module (spleeter/utils/logging.py) may log file paths, configurations, or model parameters that could expose system information or configuration details. Fix: Implement secure logging practices: avoid logging full file paths, configuration secrets, or sensitive parameters. Use log redaction/masking for sensitive data. Set appropriate log levels for production use.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/deezer/spleeter shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live deezer/spleeter repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/deezer/spleeter.

What it runs against: a local clone of deezer/spleeter — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in deezer/spleeter | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 437 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of deezer/spleeter. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/deezer/spleeter.git
#   cd spleeter
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of deezer/spleeter and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "deezer/spleeter(\\.git)?\\b" \\
  && ok "origin remote is deezer/spleeter" \\
  || miss "origin remote is not deezer/spleeter (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "spleeter/separator.py" \\
  && ok "spleeter/separator.py" \\
  || miss "missing critical file: spleeter/separator.py"
test -f "spleeter/model/provider/__init__.py" \\
  && ok "spleeter/model/provider/__init__.py" \\
  || miss "missing critical file: spleeter/model/provider/__init__.py"
test -f "spleeter/audio/adapter.py" \\
  && ok "spleeter/audio/adapter.py" \\
  || miss "missing critical file: spleeter/audio/adapter.py"
test -f "spleeter/model/functions/unet.py" \\
  && ok "spleeter/model/functions/unet.py" \\
  || miss "missing critical file: spleeter/model/functions/unet.py"
test -f "spleeter/utils/configuration.py" \\
  && ok "spleeter/utils/configuration.py" \\
  || miss "missing critical file: spleeter/utils/configuration.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 437 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~407d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/deezer/spleeter"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.