audioman

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 — every command supports --json output.

Install

# 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

Quick Start

# 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  # recursive

Commands

Command	Description
scan	Discover VST3/AU plugins on the system
list	List registered plugins with filters
info <plugin>	Show plugin parameters and ranges
process <input>	Process audio with a single plugin
chain <input>	Sequential multi-plugin processing
preset	Save/load/list/delete parameter presets
dump <plugin>	Dump plugin parameter state as JSON
analyze <input>	Audio analysis (RMS, spectral, silence detection)
fx <input>	Built-in DSP effects (normalize, gate, trim, fade)
visualize <input>	Export analysis to Sonic Visualiser SVL files
doctor -p <plugin>	Plugin analysis (freq response, THD, dynamics, waveshaper)
vo {analyze,process}	Voiceover workflow (VAD + RX denoise + utterance LUFS leveling)
obs {probe,dry-run}	OBS multitrack 영상 자동 진단 — track topology + voice/music classification + 처치 계획 (dry-run only)

Batch Processing

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 _deverb

Plugin Parameter Dump

Dump 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.jsonl

JSON Output

All commands support --json for machine-readable output:

audioman --json info denoise
audioman --json process input.wav -p denoise -o out.wav

# Batch mode outputs JSONL (one JSON object per line)
audioman --json process ./dir/ -p denoise -o ./out/

Presets

# 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 preset during processing
audioman process input.wav -p denoise --preset my_denoise -o out.wav

# Dump plugin state and save as preset in one step
audioman dump denoise --param noise_reduction_db=25 --save-preset aggressive_denoise

Audio Analysis

# Full analysis (RMS, spectral centroid, silence detection)
audioman analyze input.wav

# With ASCII waveform visualization
audioman analyze input.wav -w

# Frame-level metrics
audioman analyze input.wav --frames --json

Built-in DSP Effects

# 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.wav

Sonic Visualiser Integration

Export 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 --open

Built-in analysis types: spectrogram, spectral-centroid, spectral-entropy, rms, peak, zcr

OBS multitrack Diagnosis

OBS Studio 영상의 audio 스트림을 자동 진단해 어떤 트랙이 음성/음악/풀믹스인지 식별하고 처치 계획(dry-run)을 만든다.

# 트랙 토폴로지만 빠르게 (multitrack/single/duplicated/silent)
audioman obs probe /Volumes/T7/OBS/

# 60초 분석 + 진단 + 처치 계획 JSON 저장 (실제 처리 없음)
audioman obs dry-run /Volumes/T7/OBS/ --seconds 60 --out-dir reports/

각 활성 트랙은 voice / music / fullmix / silent로 분류되고, hum / clipping / DC offset / clicks / phase 검사 결과에 맞는 처치 (dehum, declip, voice-de-noise, leveling, stem_separate 등)가 정해진다. 같은 신호 그룹은 자동으로 미러링되어 동일 처치를 받는다.

자세한 사용법, 분류 규칙, JSON 리포트 구조, 후속 처리 가이드는 docs/obs-workflow.md 참조.

Plugin Analysis (Doctor)

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.npy

Modes: linear, thd, imd, sweep, dynamics, attack-release, waveshaper, performance, all

Vamp Plugin Setup (macOS)

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.dylib

For QM Vamp Plugins (chromagram, tempo tracking, onset detection), download from vamp-plugins.org.

Verified Plugins

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.

Internationalization (i18n)

CLI help text supports locale-based translation. Default is English; Korean is included.

# Force language via environment variable
AUDIOMAN_LANG=ko audioman --help   # Korean
AUDIOMAN_LANG=en audioman --help   # English

# Auto-detects from system locale (LC_ALL, LANG)
audioman --help

To add a new language, add a catalog dict to src/audioman/i18n.py.

Requirements

• macOS (primary, VST3 + AU)
• Python 3.12+
• uv
• VST3/AU plugins installed on the system

Stack

• pedalboard — Spotify's plugin hosting engine
• numpy — DSP, FFT, spectral analysis
• vamp — Vamp plugin host (optional, for visualize command)
• argparse — CLI
• rich — terminal output
• pydantic-settings — configuration
• soundfile — audio I/O

License

MIT