Asteroid

Asteroid is a PyTorch audio source-separation toolkit for researchers. Use this repo skill when a task mentions Asteroid models, separation, enhancement, recipes, metrics, datasets, DSP blocks, or model sharing.

Start here

Install the runtime from a clean environment, then read the sub-skill that matches the user intent.

From this skill directory, use the bundled scripts/install_runtime.py helper to bootstrap the public Asteroid runtime packages from the skill-local scripts/runtime_requirements.txt file without depending on the source checkout.

python scripts/install_runtime.py
python scripts/smoke_training.py --device cpu

If you want a tiny training sanity check after installation, run scripts/smoke_training.py.

If you only need a quick environment sanity check, read references/installation.md, references/package-overview.md, and references/runtime-entrypoints.md, then run the bundled scripts/inspect_versions.py helper.

Route by task family

Pretrained inference and separation

Read sub-skills/pretrained-inference/SKILL.md when the task is about:

• asteroid-infer
• BaseModel.from_pretrained
• separate(...), file_separate(...), numpy_separate(...), torch_separate(...)
• Torch Hub or Hugging Face model loading
• available_models() or show_available_models()
• long-file overlap-add inference with LambdaOverlapAdd

This sub-skill covers loading pretrained checkpoints from local files, Zenodo URLs, and hub IDs, then separating audio tensors or files.

Training recipes and evaluation

Read sub-skills/training-recipes/SKILL.md when the task is about:

• System, Trainer, optimizers, schedulers, or callbacks
• recipe run.sh, train.py, eval.py, local/ data prep scripts, and stage-based experiment flows
• datasets such as WhamDataset, LibriMix, Wsj0mixDataset, DNSDataset, MUSDB18Dataset, FUSSDataset, AVSpeechDataset, SmsWsjDataset, or KinectWsjMixDataset
• losses and metrics such as PITLossWrapper, SinkPITLossWrapper, MetricTracker, or get_metrics

This sub-skill is the right entry point for dataset-backed training, evaluation, and recipe debugging. For a checkout-free training sanity check, use the bundled scripts/smoke_training.py entry point.

Custom model building and core APIs

Read sub-skills/custom-models/SKILL.md when the task is about:

• asteroid.models constructors or custom subclasses of BaseModel
• filterbanks, encoders, decoders, or model registries
• mask blocks, recurrent blocks, normalization, complex-number helpers, or DSP modules
• shape, tracing, or serialization issues
• asteroid.utils parser helpers and other reusable building blocks

This sub-skill is the right place for new architectures, custom blocks, or low-level API inspection.

Model sharing and publishing

Read sub-skills/model-sharing/SKILL.md when the task is about:

• save_publishable(...) or upload_publishable(...)
• asteroid-upload or asteroid-register-sr
• Zenodo metadata, model cards, or publishable artifacts
• sample-rate fixes for legacy checkpoints

This sub-skill covers preparing release-ready model artifacts and the safe local smoke checks around them.

Common signals

Use the following as routing hints:

• infer, separate, pretrained, hub, checkpoint, model list, or long file → pretrained inference
• train, evaluate, recipe, dataset, loss, metric, scheduler, or optimizer → training recipes
• filterbank, mask network, complex, beamforming, JIT, trace, or custom model → custom model building
• publish, upload, Zenodo, model card, or register sample rate → model sharing

Public package surfaces worth remembering

• asteroid.models exposes the ready-to-use model families and sharing helpers.
• asteroid.data exposes dataset loaders for the supported speech, music, and audio-visual corpora.
• asteroid.losses exposes PIT, MixIT, SinkPIT, SDR/MSE/STOI/PMSQE, and other loss helpers.
• asteroid.metrics exposes separation metrics and the MetricTracker helper.
• asteroid.engine exposes the Lightning System wrapper plus optimizer and scheduler helpers.
• asteroid.dsp, asteroid.masknn, asteroid.complex_nn, and asteroid.utils provide the reusable building blocks that custom-model tasks usually need.
• scripts/install_runtime.py, scripts/smoke_training.py, and scripts/inspect_versions.py provide self-contained runtime bootstrap and smoke-test entry points from the skill output.

Read before editing or routing

• references/repo-provenance.md for the source snapshot.
• references/repo-routing-metadata.json for router placement.
• references/troubleshooting.md for cross-cutting failures.