Cross-platform CLI wrapper for VST3/AU audio plugins. Control commercial audio software like iZotope RX from the command line.
Built for AI agents and automated audio pipelines — the root-level --json flag gives machine-readable output for every subcommand.
# requires uv (https://docs.astral.sh/uv/)
git clone https://github.com/unohee/audioman.git
cd audioman
uv sync
# Install as global CLI tool
uv tool install -e .
audioman --help-
audioman scansearches the platform's standard VST3 directories; add others with--paths. Linux/Windows VST3 bundles have noContents/Info.plist, so the plugin name is taken from the bundle directory name (de-artifact.vst3→de-artifact) and vendor/version fromContents/Resources/moduleinfo.jsonwhen present. -
On some x86_64 CPUs (observed: AVX2 without AVX-512) the pedalboard cp313 Linux wheel crashes with
SIGILLon import. Python 3.12 works, so pin it when installing:uv sync --python 3.12 uv tool install --python 3.12 --force -e .
# Scan system for available plugins
audioman scan
# List registered plugins
audioman list
# Show plugin parameters
audioman info denoise
# Process a single file
audioman process input.wav --plugin denoise --param noise_reduction_db=15 -o output.wav
# Multi-pass adaptive denoising (RX Spectral De-noise)
audioman process input.wav -p denoise \
--param adaptive_learning=true \
--param noise_reduction_db=12 \
--passes 2 -o denoised.wav
# Chain multiple plugins
audioman chain input.wav --steps "dehum:notch_frequency=60,declick,denoise" -o cleaned.wav
# Batch process a directory
audioman process ./input_dir/ -p dereverb -o ./output_dir/ --suffix _dry
audioman process ./input_dir/ -p dereverb -o ./output_dir/ -r # recursiveThe subcommands mirror audioman --help:
| Command | Description |
|---|---|
scan |
Scan system for VST3/AU plugins |
list |
List registered plugins |
info <plugin> |
Plugin details + parameter list |
process <input> |
Process audio with a single plugin |
chain <input> |
Process audio through multiple plugins sequentially |
preset |
Preset management (save/load/list/delete) |
dump [plugin] |
Dump plugin parameter state to JSON/JSONL (always machine-readable; --json is implied) |
analyze <input> |
Audio analysis (RMS, spectral entropy, silence detection, etc.) |
fx <input> |
Built-in DSP effects (fade, trim, cut, splice, normalize, gate, gain) |
visualize <input> |
Vamp plugin or built-in analysis -> Sonic Visualiser SVL file |
doctor -p <plugin> |
Plugin analysis — frequency response, THD, dynamics, waveshaper, performance |
eq-profile -p <plugin> |
EQ plugin profiling — frequency response, phase, group delay, nonlinearity |
bounce |
Bounce multiple tracks into a single stereo file |
commit <input> |
Commit plugin chain to audio with auto delay compensation |
mixdown |
Mix tracks with master chain processing |
edl |
Non-destructive edit workflow (EDL) |
master |
Mastering delivery workflow (prep / qc / verify) |
fader-test <input> |
Open a multitrack mixer GUI to set per-track gain balance (export as ground truth JSON) |
fader-compare <gt> |
Compare automix recommendations against a fader-test ground truth |
vo {analyze,process} |
Voiceover workflow (VAD + denoise + per-utterance LUFS leveling) |
screen <input> |
Screen audio for aesthetic issues such as clicks, hum, breaths, sibilance, and noise |
obs {probe,dry-run} |
OBS multitrack video auto-diagnosis (dry-run) — track topology + voice/music classification + treatment plan |
observe <input> |
Observe audio faults across categories (signal, spectral, plugin, container) |
changelog |
Show audioman changelog (LLM-friendly, parses CHANGELOG.md) |
schemas {list,show} |
Show audioman JSONSchemas (machine-readable contract for --json output) |
stream {bench,triage,compare,play} |
Reproduce DAW real-time block processing — benchmark & triage plugin clicks/dropouts |
Global flags (--json, --plain, --verbose, --version) are defined at the root, so they must be placed before the subcommand (see JSON Output).
audioman reproduces and automatically diagnoses the clicks you hear in a real DAW (Ableton, etc.). A DAW processes audio in fixed blocks (128/256/512 samples) via callbacks and keeps plugin internal state continuous across blocks — stream reproduces that environment and exposes what differs from an offline bounce.
# Real-time CPU load per block size (RT factor, xrun, concurrent track estimate)
audioman stream bench mix.wav -p reverb --blocks 64,128,256,512,1024
# Click/discontinuity triage — block-boundary aligned = streaming bug, unaligned = source click
audioman --json stream triage mix.wav -p denoise --block-size 512
# Simulate a misbehaving host (reset on every block) — forces clicks
audioman stream triage mix.wav -p denoise --reset-per-block
# Block-size-dependent bug: null test whether output differs per block size
audioman stream compare mix.wav -p delay --blocks 128,256,512
# Play through a real audio device + count PortAudio underflows (real xruns)
audioman stream play mix.wav -p reverb --block-size 256
# Test without VST3: use pedalboard built-in effects via the builtin: prefix
audioman stream triage sine -p builtin:reverb --reset-per-blockaudioman --json analyze mix.wav --texture --segment-sec 2Spectral shape (centroid, rolloff, bandwidth, flatness, contrast, flux, HF ratio, approximate sharpness), dynamics (RMS, crest factor, onset density) and stereo image (width, L/R correlation) for the whole file and each segment, with an ERB-band level profile. Every descriptor carries a repeat floor: the amount it moves when the analysis grid is shifted by half a hop. Differences below the floor are noise of the measurement, not of the audio.
audioman's job toward an agent is to hand over evidence about how audio sounds that it can trust and afford to read, not verdicts on taste:
- Digest first. Every analysis payload starts with a short plain-English
digest. - Bounded output.
--detail summary|standard|fullkeeps JSON under 4 KiB / 32 KiB; everything moved out is in a file referenced by path. - Floors. Every measurement in
report(report.v2) says how precise it is; texture descriptors carry a repeat floor, anddiffonly calls a change significant beyond twice the combined floor. - Gates. PASS/WARN/FAIL with thresholds and reasons; a check that did not run is FAIL.
- Words, carefully.
diffproposes terms such as darker, noisier, wider, pitch-corrected — experimental, each with the evidence behind it and a confidence, and only when the change also clears a provisional perceptual minimum (smaller ones are listed underbelow_perceptual_minimum). - Pitch.
pitch,pitch_spread,pitch_deviationandvoiced_fractioncome from a YIN f0 track. They assume one f0 (a voice, a solo instrument) and are null on material without one; a chord can report the subharmonic its notes share.
scripts/texture_qa.py --assert checks this end to end: 34 synthetic before/after
pairs with known processing go through the MCP diff tool; currently 94.1% of them
get the right terms (and controls get none) in at most ~950 tokens per answer. Until
listening tests calibrate the vocabulary, this is a regression guard, not a calibration.
claude mcp add audioman -- audioman mcp # Claude Codeor, in any MCP client configuration:
{"mcpServers": {"audioman": {"command": "audioman", "args": ["mcp"]}}}Tools: analyze, describe, diff, uat_compare. Each returns a digest, a file
reference to the complete JSON result, and a summary bounded by detail
(summary <= 4 KiB by default).
audioman on PATH must be a build that has the mcp command (audioman mcp --help);
reinstall an older tool install with uv tool install --force . from a checkout.
Claude Code passes the structuredContent object (whose digest key is the digest)
to the model rather than the text content; other clients may show the text digest.
audioman --json diff before.wav after.wav --png diff.pngB is aligned to A, both are described, and every descriptor, segment and band change is reported with its floor. Only changes beyond twice the combined floor are marked significant; identical files report "no significant change".
# Real-time take vs offline render vs source (+ bypass take, render time)
audioman --json uat compare --source dry.wav --offline bounce.wav --realtime take.wav \
--bypassed bypass.wav --render-seconds 3.2
# Load, process and stay finite/audible at several rates
audioman --json uat smoke --plugin "My Plugin" --rates 44100,48000,96000
# Measured vs reported latency
audioman --json uat pdc --plugin "My Plugin"
audioman --json uat pdc --reference dry.wav --processed wet.wav --reported 1024Each prints a report.v2 block and exits 1 on a FAIL verdict, so it can gate CI directly.
Any file argument can be a directory for batch mode:
# Process all files in a directory
audioman process ./recordings/ -p denoise -o ./cleaned/
# Recursive (include subdirectories)
audioman process ./recordings/ -p denoise -o ./cleaned/ -r
# Same directory with suffix
audioman process ./recordings/ -p dereverb --param output_reverb_only=true \
-o ./recordings/ --suffix _deverbDump default parameters or full catalog as JSONL:
# Single plugin state
audioman dump denoise
# With parameter overrides
audioman dump dehum --param notch_frequency=50
# Dump ALL plugins as JSONL
audioman dump --all -o all_plugins.jsonl
# Filter by keyword
audioman dump --all --filter "rx 10" -o rx10_defaults.jsonlanalyze, observe, screen, master qc and doctor add a report object
(audioman schemas show report.v2) with the same shape for every command:
measurements with a floor (the smallest meaningful difference), gates
(PASS/WARN/FAIL; a required gate that did not run is FAIL with reason missing)
and a verdict derived from the gates.
analyze, observe, screen and master qc shape their --json output for a context window:
| Level | Printed size | What stays inline |
|---|---|---|
summary |
<= 4 KiB | scalars, arrays up to 8 values, top 5 findings/events |
standard (default) |
<= 32 KiB | arrays up to 64 values, top 50 findings/events |
full |
unbounded | everything |
Anything moved out of line is written to a JSON spill file (--spill-dir, default <cache dir>/spill) and replaced by {"$ref": "/abs/path.json", "length": N, "min": ..., "max": ..., "mean": ...}. Every payload also starts with a digest string summarising the full measurement.
--json, --plain, --verbose, and --version are root-level global flags. They are parsed by the top-level parser, so they must appear before the subcommand. Placing them after the subcommand fails with error: unrecognized arguments:
# Correct — global flags first
audioman --json info denoise
audioman --json process input.wav -p denoise -o out.wav
# Wrong — rejected by argparse
audioman info denoise --json # error: unrecognized arguments: --json
# Batch mode outputs JSONL (one JSON object per line)
audioman --json process ./dir/ -p denoise -o ./out/dump is the one exception to the "flag is required" rule: it is always machine-readable (JSON for a single plugin, JSONL for --all), so --json is implied and accepted only for uniformity. Every other command needs the root-level flag to switch output modes.
# Save current parameters as a preset
audioman preset save my_denoise --plugin denoise \
--param noise_reduction_db=20 --param adaptive_learning=true
# List presets
audioman preset list
# Use a preset when dumping plugin state
audioman dump denoise --preset my_denoise
# Dump plugin state and save as preset in one step
audioman dump denoise --param noise_reduction_db=25 --save-preset aggressive_denoise# Full analysis (RMS, spectral centroid, silence detection)
audioman analyze input.wav
# With ASCII waveform visualization
audioman analyze input.wav -w
# Frame-level metrics (global --json goes before the subcommand)
audioman --json analyze input.wav --frames# Normalize to -1dB peak
audioman fx input.wav normalize -o output.wav
# Noise gate
audioman fx input.wav gate --threshold -40 -o output.wav
# Trim silence from start and end
audioman fx input.wav trim-silence -o output.wav
# Fade in/out
audioman fx input.wav fade-in --duration 0.5 -o output.wavExport analysis data as .svl files that Sonic Visualiser can open directly.
# Built-in spectrogram → SVL
audioman visualize input.wav -b spectrogram -o spec.svl
# Built-in spectral centroid → SVL
audioman visualize input.wav -b spectral-centroid -o centroid.svl
# Vamp plugin analysis → SVL (requires vamp package + plugins)
audioman visualize input.wav -p vamp-example-plugins:powerspectrum -o power.svl
audioman visualize input.wav -p qm-vamp-plugins:qm-chromagram -o chroma.svl
# List installed Vamp plugins
audioman visualize input.wav --list-plugins
# Open in Sonic Visualiser after generation
audioman visualize input.wav -b spectrogram --openBuilt-in analysis types: spectrogram, spectral-centroid, spectral-entropy, rms, peak, zcr
Automatically diagnoses the audio streams of OBS Studio videos, identifies which tracks are voice/music/fullmix, and produces a treatment plan (dry-run).
# Track topology only, quickly (multitrack/single/duplicated/silent)
audioman obs probe /Volumes/T7/OBS/
# 60-second analysis + diagnosis + treatment plan JSON (no actual processing)
audioman obs dry-run /Volumes/T7/OBS/ --seconds 60 --out-dir reports/Each active track is classified as voice / music / fullmix / silent, and a treatment matching the hum / clipping / DC offset / clicks / phase check results (dehum, declip, voice-de-noise, leveling, stem_separate, etc.) is chosen. Identical signal groups are mirrored automatically and receive the same treatment.
For detailed usage, classification rules, the JSON report structure, and follow-up processing guidance, see docs/obs-workflow.md.
PluginDoctor-style measurements for any VST3/AU plugin:
# Full analysis (frequency response, THD, dynamics, waveshaper, performance)
audioman doctor -p denoise
# Single mode
audioman doctor -p saturn-2 --mode thd --frequency 1000 --level -6
# Waveshaper v2 (multi-level measurement)
audioman doctor -p decapitator --mode waveshaper --ws-levels 7 --ws-points 256
# A/B comparison
audioman doctor -p saturn-2 --compare vsm-3
# CLAP embedding profiling
audioman doctor -p vsm-3 --clap --clap-sweep drive=0,25,50,75,100 \
--clap-output vsm3_embeddings.npyModes: linear, thd, imd, sweep, dynamics, attack-release, waveshaper, performance, all
pip install vamp
brew install vamp-plugin-sdk
mkdir -p ~/Library/Audio/Plug-Ins/Vamp
cp /opt/homebrew/lib/vamp/vamp-example-plugins.* ~/Library/Audio/Plug-Ins/Vamp/
# macOS requires .dylib extension
cp ~/Library/Audio/Plug-Ins/Vamp/vamp-example-plugins.so \
~/Library/Audio/Plug-Ins/Vamp/vamp-example-plugins.dylibFor QM Vamp Plugins (chromagram, tempo tracking, onset detection), download from vamp-plugins.org.
Tested with iZotope RX 10 (15 VST3 plugins, all parameters accessible):
| Plugin | Short Name | Aliases | Params |
|---|---|---|---|
| Spectral De-noise | spectral-de-noise |
denoise |
27 |
| Voice De-noise | voice-de-noise |
voice-denoise |
14 |
| Guitar De-noise | guitar-de-noise |
guitar-denoise |
13 |
| De-click | de-click |
declick |
6 |
| De-clip | de-clip |
declip |
10 |
| De-crackle | de-crackle |
decrackle |
5 |
| De-ess | de-ess |
deess |
9 |
| De-hum | de-hum |
dehum |
33 |
| De-plosive | de-plosive |
deplosive |
4 |
| De-reverb | de-reverb |
dereverb |
10 |
| Breath Control | breath-control |
- | 4 |
| Mouth De-click | mouth-de-click |
mouth-declick |
4 |
| Repair Assistant | repair-assistant |
repair |
15 |
Any VST3 or AU plugin installed on the system can be used — not limited to iZotope.
- macOS (primary, VST3 + AU)
- Python 3.12+
- uv
- VST3/AU plugins installed on the system
- pedalboard — Spotify's plugin hosting engine
- numpy — DSP, FFT, spectral analysis
- vamp — Vamp plugin host (optional, for
visualizecommand) - argparse — CLI
- rich — terminal output
- pydantic-settings — configuration
- soundfile — audio I/O
MIT