Separate a target sound from a mixture using a natural-language query.
promptsep is a small, interpretable toolkit for language-queried audio
source separation (LASS). You describe what you want to keep — "a steady tone", "background hiss", "a low hum" — and it isolates that source from
the mixture. The core runs on NumPy alone, works fully offline, and every step
of the decision is inspectable rather than hidden inside learned weights.
import numpy as np
from promptsep import separate
mixture, sr = ... # your 16 kHz mono mixture as a NumPy array
tone = separate(mixture, "a clear steady tone", sample_rate=sr)
hiss = separate(mixture, "background static hiss", sample_rate=sr)Most LASS systems pair a large pretrained text/audio encoder (CLAP, BERT) with
a deep separation network. That is powerful but heavy: gigabytes of weights, a
GPU, and an opaque mask. promptsep takes the opposite stance:
- Offline-first. No model downloads, no network, no GPU.
pip installand go. - NumPy core. The only hard dependency is NumPy. PyTorch is optional and only enables an extra refinement backend.
- Interpretable. A query compiles into a small
AcousticProfile— texture weights (harmonic / percussive / noise) plus a log-frequency band. You can print it, tweak it, and see exactly why a bin was kept. - Reproducible. Deterministic given a query and a seed. Synthetic sources are built in, so the whole pipeline is testable without any dataset.
It will not beat a trained neural model on messy real-world audio — that is not the goal. It is a transparent, hackable baseline and a teaching tool.
pip install promptsep # NumPy core only
pip install "promptsep[torch]" # + optional PyTorch refinement backend# Separate and write <input>.a-steady-tone.wav next to the input
promptsep separate mixture.wav "a steady tone"
# Explicit output, NMF method, and a mask floor to soften artefacts
promptsep separate mixture.wav "background hiss" -o hiss.wav --method nmf --floor 0.1
# Inspect the acoustic profile a query compiles to
promptsep profile "a low steady hum"
# List the concepts and modifiers the lexicon understands
promptsep info- Query → profile. The query is tokenised and matched against a small
hand-written lexicon of sound concepts and modifiers,
producing an
AcousticProfile. - Mixture → spectrogram. A NumPy STFT (1024-point, 256 hop, Hann) with exact overlap-add reconstruction.
- Profile → mask. Median-filtering HPSS splits each bin into harmonic / percussive / noise energy; the profile weights those textures and gates them by its frequency band to form a soft mask.
- Mask → waveform. The mask is applied and inverted back to the time domain.
See docs/architecture.md for the full pipeline and docs/design-notes.md for the reasoning behind it.
MIT © Lu Wenjing. See LICENSE.