From WAV to Features: How to Run Sonic Annotator — Step-by-Step
Overview
Sonic Annotator is a command-line tool for batch extracting audio features from files using Vamp plugins. This guide shows a practical, minimal workflow: install, pick plugins, run extraction, and inspect results. Assumes Linux/macOS (Windows steps noted where different).
1) Install Sonic Annotator
- Linux (Debian/Ubuntu):
- sudo apt update && sudo apt install sonic-annotator
- macOS (Homebrew):
- brew install sonic-annotator
- Windows:
- Use prebuilt binaries from the Sonic Annotator project or install via Cygwin/MSYS with package build; alternatively run in WSL.
2) Install Vamp plugins you need
- Common plugins:
- QM-vamp-plugins (tonal, chroma)
- vamp-libxtract
- Linux:
- sudo apt install vamp-plugin-host qm-vamp-plugins vamp-plugin-sdk
- macOS (Homebrew):
- brew install qm-vamp-plugins vamp-plugin-libxtract
- Confirm plugin availability:
- sonic-annotator -l
3) Choose the plugin and output format
- Plugins have plugin:feature IDs shown by sonic-annotator -l.
- Output formats:
- CSV (–csv) — good for spreadsheets, machine processing
- RDF (–rdf) — semantic annotations
- JSON (–json) — structured programmatic use
- Common choice for features: CSV or JSON.
4) Basic command examples
- Extract a single feature to CSV:
- sonic-annotator -d vamp:qm-vamp-plugins:specparam:spec -w csv input.wav -o output.csv
- Extract multiple features:
- sonic-annotator -d “vamp:qm-vamp-plugins:melbands:melbands,vamp:qm-vamp-plugins:chroma:chroma” -w csv input.wav -o features.csv
- Process a folder (recursive):
- sonic-annotator -r -d vamp:qm-vamp-plugins:melbands:melbands -w csv /path/to/audio -o /path/to/output
- Use JSON:
- sonic-annotator -d vamp:qm-vamp-plugins:tonal:tonal -w json track.wav -o tonal.json
5) Common useful flags
- -r : recurse directories
- -t : show plugin parameters and types
- –raw : include raw frames (if supported)
- –csv-stdout / –json-stdout : print to stdout for piping
- –tempo-method / plugin-specific params: append parameter settings after plugin ID (consult -t)
6) Inspecting and cleaning outputs
- CSV columns typically: file, start, duration, label, value
- Use Python (pandas) or R to load and aggregate per-frame features:
- pandas.read_csv(‘features.csv’) then groupby file or time window
- Normalize or aggregate (mean, median, rms) over time windows to get fixed-size feature vectors.
7) Batch workflow example (practical)
- Install sonic-annotator and qm-vamp-plugins.
- List plugins: sonic-annotator -l > plugins.txt
- Choose features (e.g., melbands, chroma).
- Run recursively: sonic-annotator -r -d “vamp:qm-vamp-plugins:melbands:melbands,vamp:qm-vamp-plugins:chroma:chroma” -w csv /dataset/audio -o /dataset/features
- Postprocess: use a script to compute per-file summaries and save as ARFF/CSV for ML.
8) Troubleshooting
- Plugin missing: check plugin ID with -l and ensure plugin package installed.
- Permission errors on Windows: run as admin or use WSL.
- Large outputs: use JSON streaming or split by file; adjust frame size via plugin parameters.
9) Tips
- Start with -l to explore available features.
- Run on a single file to tune plugin parameters before batch processing.
- Keep outputs organized mirroring input folder structure.
- Use –csv-stdout to pipe directly into processing scripts for speed.
If you want, I can:
- generate the exact sonic-annotator command for a specific feature set and OS,
- provide a short Python script to aggregate CSV outputs into per-file feature vectors.