---

name: training description: "Train and validate custom Spleeter source-separation models with safe data and config helpers." metadata: disco-role: operating disable-model-invocation: true license: MIT

Spleeter Training

Use this sub-skill when the task is about custom Spleeter model training: spleeter train, training CSVs, custom stems, model_dir checkpoints, DatasetBuilder, get_training_dataset, get_validation_dataset, config validation, cache directories, or TensorFlow estimator training behavior.

Do not use this sub-skill for pretrained separation or MUSDB metrics:

• Pretrained model separation, Separator, output stems, codecs, and filename templates: separation.
• MUSDB evaluation, spleeter evaluate, musdb/museval, and SDR/SAR/SIR/ISR reports: evaluation.

Fast route

1. Confirm runtime prerequisites in installation and runtime: Python >=3.8,<3.12, Spleeter 2.4.2, TensorFlow 2.12.1, and system ffmpeg/ffprobe. GPU is optional acceleration only; CPU training is supported but slow for real datasets.
2. For the training command and Typer option spellings, see root CLI reference and the workflow recipe in training-workflow.md.
3. Build or validate the data/config contract before starting TensorFlow:
   • Create a tiny local fixture: scripts/create_training_fixture.py.
   • Validate a Spleeter-style config and CSVs: scripts/validate_training_config.py.
   • Schema and compatibility rules: data-format-and-config.md.
4. For programmatic dataset construction or estimator adaptation, use api-reference.md.
5. For failures, first check training troubleshooting, then cross-cutting package issues in root troubleshooting.

Command shape

The supported training CLI shape is:

python -m spleeter train \
  --data DATA_ROOT \
  --params_filename CONFIG.json \
  --adapter spleeter.audio.ffmpeg.FFMPEGProcessAudioAdapter \
  --verbose

Short aliases are --data/-d, --params_filename/-p, and --adapter/-a. CONFIG.json must describe the dataset CSVs, STFT dimensions, source instruments, caches, checkpoint settings, and model function. CSV audio paths are relative to --data DATA_ROOT.

Evidence basis

This sub-skill distills the training surfaces evidenced by spleeter/__main__.py, spleeter/dataset.py, spleeter/model/__init__.py, spleeter/model/functions/unet.py, spleeter/utils/configuration.py, spleeter/utils/tensor.py, spleeter/resources/*.json, configs/musdb_config.json, configs/musdb_train.csv, configs/musdb_validation.csv, tests/test_train.py, and pyproject.toml.