ferraus

A command-line audio workstation for scripts and AI agents. One cross-platform binary covers conversion and editing, effects, restoration, noise reduction, stem separation, pitch correction, MIDI, notation in both directions, CLAP/VST3 instrument hosting, and mastering.

• New here? Start with Getting started, then pick a tutorial: clean a podcast, tune a vocal, split a song into stems, turn a hum into an instrument part, make a score, perform a sheet-music file, master a track, or host a plugin. Each one says what to listen for at every step.
• Building an agent? Read the agent guide, MCP setup, and the cookbook: clean, tune, and master a vocal, stems for a remix, hum to an instrument, sheet music to a performance, batch podcast cleanup, pipeline files. Runnable versions of these recipes (shell scripts, pipeline files, an MCP client, and a Claude agent loop) are in the repository's examples folder.
• Coming from FFmpeg? The FFmpeg equivalents table translates common commands.
• Looking up a command? Every command has a reference page under Command reference, and ferraus docs <command> prints the same page offline. Background on units, loudness, pan laws, stems, notation, sound folders, and sidecars is under Concepts.
• Something wrong? See Troubleshooting and the error catalog.

Command pages are generated from the same definitions as the binary, and every command-line example on them is checked against the CLI in CI. The tutorials and cookbook were written by running every command shown against ferraus 0.1.0; their outputs are trimmed copies of what it printed.

Getting started

Install

From source (any platform with Rust). Install a Rust toolchain from https://rustup.rs, then:

cargo install ferraus

The Cargo package that builds the ferraus binary is named ferraus (its directory in the repository is crates/ferraus-cli; see docs/decisions/0005-binary-package-name.md). From a clone of the repository, cargo install --path crates/ferraus-cli does the same. Either way the binary goes to ~/.cargo/bin, which rustup puts on your PATH.

Release installers. Releases are built and attested by the repository's GitHub Actions workflows and published on the releases page. Release builds exist for:

• macOS 13.4 or newer, on Apple silicon and on Intel.
• Linux on x86-64 and ARM64, in two flavors. The glibc build needs glibc 2.38 or newer (Ubuntu 24.04+, Debian 13+, Fedora 39+). The musl build is fully static: it runs on Alpine and other musl systems and on Linux distributions too old for the glibc build, with nothing to install. The shell installer chooses it by itself on those systems. The static build cannot load audio plugins (CLAP, VST3); use the glibc build for plugin hosting.
• Windows 10 and 11 on x86-64 and ARM64, with the Microsoft Visual C++ Redistributable, which most Windows machines already have (https://aka.ms/vs/17/release/vc_redist.x64.exe, or https://aka.ms/vs/17/release/vc_redist.arm64.exe on ARM).

macOS and Linux:

curl -fsSL https://github.com/djynnius/ferraus/releases/latest/download/ferraus-installer.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://github.com/djynnius/ferraus/releases/latest/download/ferraus-installer.ps1 | iex"

The installers put ferraus in ~/.ferraus/bin (set FERRAUS_INSTALL_DIR to change it) and never ask for administrator rights. Open a new terminal afterwards.

Package managers, which also keep ferraus up to date:

• Homebrew (macOS, Linux): brew install djynnius/tap/ferraus

• Debian 13+ and Ubuntu 24.04+ (signed apt repository):

  sudo mkdir -p /etc/apt/keyrings
  sudo curl -fsSLo /etc/apt/keyrings/ferraus-archive-keyring.asc https://djynnius.github.io/packages/ferraus-archive-keyring.asc
  sudo curl -fsSLo /etc/apt/sources.list.d/ferraus.sources https://djynnius.github.io/packages/apt/ferraus.sources
  sudo apt update && sudo apt install ferraus
  

• Fedora 39+ and RHEL (signed dnf repository):

  sudo curl -fsSLo /etc/yum.repos.d/ferraus.repo https://djynnius.github.io/packages/rpm/ferraus.repo
  sudo dnf install ferraus
  

• Windows (scoop): scoop bucket add djynnius https://github.com/djynnius/scoop-bucket, then scoop install djynnius/ferraus. winget follows once Microsoft has reviewed the package.

• The .deb, .rpm, and Windows MSI files are also on the releases page.

Docker (Linux x86-64 and ARM64; the current folder is /work, models persist in the ferraus-data volume):

docker run --rm -v "$PWD:/work" -v ferraus-data:/data ghcr.io/djynnius/ferraus separate song.wav -y

The ghcr.io/djynnius/ferraus:latest-cuda image (x86-64) runs models on an NVIDIA GPU with docker run --gpus all ....

Check the installation

ferraus doctor

{
  "ferraus_version": "0.1.0",
  "platform": {"os": "macos", "arch": "aarch64"},
  "paths": {
    "config": "/Users/me/Library/Application Support/ferraus/config.toml",
    "cache": "/Users/me/Library/Caches/ferraus",
    "data": "/Users/me/Library/Application Support/ferraus/data",
    "models": "/Users/me/Library/Caches/ferraus/models",
    "sounds": "/Users/me/Library/Application Support/ferraus/data/sounds"
  },
  "ffmpeg": {"found": true, "path": "/opt/homebrew/bin/ffmpeg", "source": "path", ...},
  "models": {"cache_bytes": 0},
  "compute": {"providers": ["coreml", "cpu"], "active": "coreml", ...},
  "plughost": {"clap_host": ".../ferraus-plughost"},
  "engraver": {"helper": null, "lilypond": null},
  "suggestions": []
}

doctor reports the version, where config, models, and sounds live, whether FFmpeg was found (needed only for a few formats, see Troubleshooting), the compute devices for neural models, the plugin host, and the score engraver. suggestions lists runnable fixes for anything missing.

Your first five commands

ferraus info song.mp3                          # what is in this file?
ferraus convert song.mp3 -o song.flac          # lossless copy
ferraus normalize song.flac --lufs -14 -o song.loud.flac
ferraus trim song.flac --range 0:30..1:00 -o chorus.flac
ferraus fx chorus.flac -o chorus.fx.wav --fx "fade:in=1s,out=2s" --fx "reverb:mix=20%"

What the first two print:

{"path": "song.mp3", "container": "mp3", "codec": "mp3", "duration_s": 84.8, "duration": "1:24.800",
 "sample_rate": 48000, "channels": 2, "channel_layout": "stereo", "bit_depth": null,
 "bitrate_kbps": 129.0, "lossless": false, "tags": {}, "art": {"present": false, "pictures": []}}

song.flac

{"input": "song.mp3", "output": "song.flac", "format": "flac", "bit_depth": 16, "sample_rate": 48000,
 "channels": 2, "duration_s": 84.8, "frames": 4070400, ...}

Each command prints the output path, then its result. Each output also gets a <output>.ferraus.json file beside it, recording exactly what was done (provenance sidecars). Without -o the output goes beside the input as <input>.<command>.<ext> (song.normalize.flac). Existing files are never overwritten unless you pass --overwrite.

Useful on every command:

• --json: one machine-readable result object on stdout, nothing else.
• --dry-run: resolve everything and show the plan without processing.
• ferraus docs <command>: the full reference page, offline. ferraus <command> --help is the short version.

Where to go next: a tutorial for your task, or the agent guide if you are building with an AI model.

Commands that use models

Stem separation, speech denoising, the neural pitch trackers, chord transcription, and sheet music recognition use neural-network models that are not in the package. ferraus never downloads one unless you allow it, once, with -y:

ferraus separate song.mp3 --tier fast -y

or pull models ahead of time (ferraus models pull separate/htdemucs) and work offline with --offline. ferraus models list shows every model with its size, license, and which tiers use it. Some models are not yet downloadable in this release; see Stems and separation tiers.

Where files live

On Linux the XDG_CONFIG_HOME, XDG_CACHE_HOME, and XDG_DATA_HOME variables are honoured. FERRAUS_HOME=<dir> moves all three (to <dir>/config, <dir>/cache, and <dir>/data), which is handy for a sandbox or a test; FERRAUS_CONFIG points at another config file.

Uninstall

• Release installer: ferraus self-uninstall -y (--purge also removes models, sounds, and config).
• cargo install: cargo uninstall ferraus.
• Package managers: brew uninstall ferraus, sudo apt remove ferraus, sudo dnf remove ferraus, scoop uninstall ferraus, winget uninstall djynnius.ferraus.

Models, sounds, and config stay in the folders above until you delete them (or use --purge).

Glossary

Troubleshooting and FAQ

Each entry says what you see, why it happens, and the exact command that fixes it. Add --json to any command to get the same information as structured data, including an error.hint that is a runnable command.

Installation

ferraus: command not found after the URL installer. The installer puts the binary in ~/.ferraus/bin and adds it to your shell profile. Open a new terminal, or run export PATH="$HOME/.ferraus/bin:$PATH". On Windows, open a new PowerShell window; the installer adds the folder to your user PATH.

ferraus: command not found after cargo install ferraus. Cargo installs to ~/.cargo/bin (%USERPROFILE%\.cargo\bin on Windows). rustup adds it to PATH; if you installed Rust another way, add it yourself. Note the package name: cargo install ferraus, not ferraus-cli.

Windows says the publisher is unknown. Release binaries and the MSI are Authenticode signed by the GitHub Actions release workflow. Builds made with cargo install are not signed; that warning is expected for them.

Check what is installed. ferraus doctor prints the version, config/cache/data paths, FFmpeg status, cached models, and the active compute device.

Models and offline use

Exit code 5: model not cached. ferraus downloads a model only when you allow it: add -y to the command (or set models.auto_download = true in the config), or run the command in the hint, for example ferraus models pull separate/htdemucs, then re-run. ferraus models list shows every model, its size and license, and which tiers use it.

Exit code 6 with model_unverified. The model's registry entry has no recorded SHA-256 (or, for some entries, no download at all), so ferraus refuses to fetch it. In this release that affects the balanced, quality, and max separation tiers, 6-stem separation, the full-size CREPE model, and the homr sheet-music transformer (the builtin score read engine does not need it); see Stems and separation tiers. separate with the default --tier auto uses the best verified tier (fast today). You can override the check for an entry that does have a download with the variable shown in the hint (FERRAUS_ALLOW_UNVERIFIED=1), at your own risk.

Exit code 6: download or verification failed. Downloads resume; run the command again. A second checksum mismatch means a mirror is serving a corrupted file; report it.

Working with no network. Pull the models you need while online, then pass --offline (or set FERRAUS_OFFLINE=1): any attempt to use the network becomes an error instead of a download.

GPU setup

Inference runs on the CPU. The base package is CPU-only. ferraus accelerate install downloads the execution-provider libraries for your platform (CUDA on Linux/Windows with an NVIDIA GPU; CoreML is built in on macOS; DirectML on Windows). ferraus doctor shows the active provider; --device cpu|cuda|coreml|directml forces one per run. GPU results match CPU results within 1e-3 RMS.

Formats and FFmpeg

Exit code 4: unsupported format. Native decoding covers WAV, AIFF, FLAC, MP3, AAC/M4A, ALAC, Vorbis, Opus, and the audio track of MP4/MKV/WebM/MOV. Encoding AAC/ALAC (.m4a), exotic containers, and writing video need the FFmpeg bridge: ferraus doctor --install-ffmpeg installs a pinned static build into the ferraus cache, or set ffmpeg.path in the config.

MP3 encoding is unavailable. MP3 encoding loads the system LAME library at run time. Install it (brew install lame, apt install libmp3lame0) or install the FFmpeg bridge.

Plugins and sounds

plugin not found (exit code 7). Run ferraus plugin scan (add --paths <dir> for non-standard locations) and check ferraus plugin list. Folders passed with --sound-path or FERRAUS_SOUND_PATH are scanned too.

A plugin crashed. Plugins run in a separate ferraus-plughost process, so ferraus keeps running; the error names the plugin and its path. Try another preset or report it to the plugin vendor.

An instrument name is ambiguous. The error lists the candidates with a runnable hint for each. Pin one with ferraus sounds alias piano=<id>.

Output files

output_exists (exit code 2). ferraus never overwrites a file unless you pass --overwrite (or --in-place, which keeps <input>.bak).

The command returned instantly with reused_output. An identical output from the same command, parameters, inputs, and ferraus version already exists, so the existing file was returned. Pass --force --overwrite to recompute (--force alone stops at the existing file).

A batch fails with unsupported_format on .ferraus.json files. A glob such as "takes/*" also matches the sidecars ferraus wrote. Name the extension: "takes/*.wav".

Clipping after a chain of separate commands. Each command writes an integer file (the input's bit depth), so a stage that adds gain (leveler, enhance-voice, eq boosts) can push peaks past 0 dBFS and clip in the file it writes. analyze stats shows full_scale_samples. Run the stages in one ferraus fx pass (floating point inside) with normalize or limit last, or write intermediates as 32-bit float with --bit-depth 32.

engraver_missing when writing PDF, PNG, or SVG scores. Engraving needs the ferraus-engrave helper (in the release packages; from source cargo build -p ferraus-engrave --release, then put it beside ferraus or set FERRAUS_ENGRAVE) or LilyPond. MusicXML, ABC, LilyPond, MEI, and sol-fa outputs need nothing.

Sheet music recognition

pdf_renderer_missing (exit code 4). PDFs are rasterized with pdftoppm (poppler) or mutool (MuPDF); install one (brew install poppler, apt install poppler-utils), or export the pages as PNG and pass those. On macOS without either, sips reads only the first page.

no staves were recognized. The page needs staff lines at least about 8 px apart after scanning; scan at 300 dpi, crop away dark borders, and straighten the page. Photos taken at an angle, handwritten music, and very faint copies are best-effort.

Wrong notes or durations. Run score read page.png -o out.musicxml --review: measures whose durations do not add up are in failing_measures, uncertain ones in review.low_confidence with the reason. Fix them with --fix edits.json or score from-json. To see what the recognizer saw, set FERRAUS_OMR_DEBUG=<dir>: it writes the network's maps and the boxes of every symbol it read as PNGs (FERRAUS_OMR_TRACE=1 prints its decisions).

Slow. Recognition takes roughly 15–60 s per page on a laptop CPU (two networks over overlapping tiles); blank areas are skipped. --device cuda uses a GPU when one is set up.

Slow runs

• Separation is the slowest command: the fast tier runs at about half real time on a laptop CPU. Run it with --async and ferraus jobs wait, or install a GPU provider.
• --threads N caps CPU use; --deterministic fixes the thread count and may be slower.
• ferraus bench reports real-time factors on your machine.

Quality expectations per feature

Reporting a bug

Attach the output's sidecar (<output>.ferraus.json) and the output of ferraus doctor: the sidecar records the exact command, resolved parameters, model hashes, ferraus version, and host. ferraus verify <sidecar> checks that the files still match. Open an issue at https://github.com/djynnius/ferraus/issues.

Agent guide

The whole command surface, one line per command. The same text is printed by ferraus describe --agent.

analyze chords: Chord sequence with times and confidence (best-effort)
analyze clipping: Count and locate clipped runs [--threshold --min-run]
analyze key: Key and scale with confidence [--method]
analyze loudness: EBU R128 loudness: integrated, short-term, momentary, range, true peak [--timeline]
analyze pitch: Pitch curve as JSON or CSV [--tracker --hop --range]
analyze problems: Diagnose clipping, DC, clicks, hum, hiss, phase, silence, and more [--min-severity]
analyze silence: List silent regions with start, end, and floor level [--threshold --min]
analyze similarity <audio>x2: Spectral, cepstral, and loudness similarity between two files
analyze spectrum: Long-term average spectrum in fractional-octave bands or FFT bins [--resolution]
analyze stats: Per-channel peak, true peak, RMS, DC, crest factor, dynamic range [--histogram]
analyze stereo: Stereo image: correlation, width per band, mono compatibility
analyze tempo: Tempo, beat times, downbeats, and time signature [--range]
compare <audio>x2: Null test: align b to a and report RMS and peak difference and SI-SDR [--max-offset --no-align]
info <file>: Probe a file: container, codec, duration, rate, channels, bit depth, bitrate, tags, art [--loudness --spectrum]
spectrogram: Export a spectrogram as a PNG image or JSON matrix [--fft --hop --mel]
tags <file>: Read and write metadata tags and cover art [--set --remove --art]
waveform: Export a waveform image (PNG, SVG) or JSON peaks [--width --height --peaks-per-second]
channels: Mix down, up-mix, extract, swap, or mid/side-convert channels [--to --extract --swap]
concat <audio...>: Join files end to end, optionally with crossfades or gaps [--crossfade --crossfade-curve --gap]
convert: Decode and re-encode between formats [--vbr --dither]
cut: Remove one or more time ranges and join the rest [--range --crossfade]
envelope: Keyframed automation of gain, pan, or pitch [--points --curve --target]
fade: Fade in and/or out [--in --out --curve]
gain: Apply a fixed gain, overall or per channel [--by]
generate noise: Generate white, pink, or brown noise [--color --dur --amplitude]
generate silence: Generate digital silence [--dur]
generate tone: Generate a test tone or sweep [--freq --dur --shape]
invert-phase: Invert polarity [--channel]
mix <audio...>: Sum several files with per-input gain, pan, and offset [--gains --pans --offsets]
normalize: Set loudness (LUFS), peak, or RMS level to a target [--lufs --peak --rms]
resample: Change the sample rate with a high-quality sinc resampler [--to --quality]
reverse: Play the audio backwards
silence detect: Find silent regions and report their start, end, and level [--threshold --min --markers]
silence pad: Add silence to the start and/or end [--start --end]
silence trim: Remove leading and trailing silence, optionally long pauses too [--edges --all --threshold]
speed: Change speed and pitch together (varispeed) [--factor]
split: Split a file into parts at times, at silences, or into equal chunks [--at --every --on-silence]
trim: Keep one time range of the input [--range --pad --pad-start]
clip: Soft or hard clipper [--ceiling --mode --knee]
compress: Compress dynamic range (feed-forward, soft knee) [--threshold --ratio --attack]
deess: Reduce sibilance [--center --bandwidth --threshold]
dynamics: Transfer-curve dynamics: compressor, expander, and gate from one curve [--curve --spline --attack]
expand: Downward expander [--threshold --ratio --attack]
gate: Noise gate with hysteresis and hold [--threshold --attack --hold]
limit: True-peak brickwall limiter [--ceiling --release --lookahead]
multiband: Multiband compressor [--crossovers --bands --threshold]
transient: Shape attack and sustain [--attack --sustain]
band-split: Split audio into frequency bands that sum back to the input [--crossovers]
bitcrush: Bit-depth and sample-rate reduction [--bits --rate]
chorus: Chorus (or chorus/flanger blend) [--rate --depth --voices]
distort: Distortion from drawn transfer curves [--curve-pos --curve-neg --smooth]
eq: Parametric EQ (cascaded biquads or linear phase) [--band --linear-phase]
fft-filter: Filter by a drawn magnitude curve [--curve --fft]
filter: Scientific filters: Butterworth, Chebyshev, Bessel, elliptic [--design --type --freq]
flanger: Flanger [--rate --depth --feedback]
graphic-eq: Linear-phase graphic equalizer (10, 20, or 30 bands) [--bands --gains --accuracy]
guitar: Guitar amp chain: compressor, tone filter, distortion, cabinet [--amp --cab --filter]
highpass: High-pass filter [--freq --order --q]
lowpass: Low-pass filter [--freq --order --q]
match-eq: Match the long-term spectrum of a reference [--reference --amount --smoothing]
notch: Narrow notch filter, optionally with harmonics [--freq --q --depth]
phaser: Phaser [--stages --rate --depth]
saturate: Saturation (tape, tube, soft, hard) [--drive --type --tone]
tilt: Tilt EQ: one-knob brighter or darker [--pivot --gain]
tremolo: Tremolo (amplitude modulation) [--rate --depth --shape]
vibrato: Vibrato (pitch modulation) [--rate --depth]
vocoder: Vocoder: make a carrier speak or sing with the input's voice [--carrier --note --follow]
delay: Feedback delay (echo), tempo-synced [--time --feedback --mix]
doppler: Doppler pitch and level trajectory of a moving source [--path --velocity --distance]
echo: Multi-tap echo with per-repeat filtering [--taps --time --feedback]
reverb: Add reverb (plate, room, hall, chamber, or an impulse response) [--type --size --decay]
center: Extract or remove centre-panned material (vocals, dialogue) [--mode --pan --phase-tolerance]
dc-remove: Remove DC offset [--freq]
declick: Remove clicks, pops, and crackle [--sensitivity --complexity --max-width]
declip: Repair clipped peaks by autoregressive interpolation [--threshold --max-gap --headroom]
dehiss: Reduce broadband hiss [--floor --reduction --range]
dehum: Remove mains hum (50/60 Hz) and its harmonics [--freq --harmonics --q]
dereverb: Reduce room reverberation [--rt60 --amount --late]
enhance: Essential-Sound-style one-knob chain for dialogue, music, SFX, or ambience [--loudness --repair --clarity]
enhance-voice: Vocal enhancer: rumble filter, de-plosive, de-ess, compression, presence [--mode]
leveler: Slow speech volume leveler [--target --amount --range]
phase-align: Align the timing of channels (azimuth and mic-placement correction) [--mode --shift --window]
remove-sound: Learn an unwanted sound and subtract it everywhere [--learn --model --save-model]
repair: Spectral repair of a time-frequency region from its neighbours [--range --freq --method]
autopan: Cyclic automatic panning [--rate --depth --shape]
channels mix: Channel mixer: per-output weights and phase invert [--out --invert]
pan: Place a source in the stereo field (static or keyframed) [--position --law --mode]
widen: Stereo widener (mid/side) with mono bass [--amount --mono-below --center-pan]
denoise: Remove steady background noise (hiss, hum, fan, room tone) or run a speech denoiser [--profile --noise-range --auto]
denoise profile: Learn a noise profile (.noiseprof) from a noise-only region [--range --auto --from]
denoise profile merge <file...>: Combine noise profiles from several takes into one [--method]
separate: Split a mix into stems (vocals, drums, bass, other, ...) [--stems --tier --only]
pitch: Shift pitch, keep duration [--semitones --cents --formant]
pitch-bend: Pitch envelope: tape-style varispeed or duration-preserving bend [--points --curve --preserve-duration]
stretch: Change duration, keep pitch [--factor --to --bpm]
tune: Pitch correction (auto-tune) to a key, scale or written melody [--key --scale --strength]
hum: Turn a hummed idea into an instrument part [--to --grid --strength]
midi from-json <file>: Write a MIDI file from JSON [--ppq]
midi groove extract <midi>: Capture a groove from a reference part [--grid]
midi info <midi>: Summarize a MIDI file
midi legato <midi>: Extend notes to the next onset [--gap]
midi merge <midi...>: Combine MIDI files [--mode]
midi quantize <midi>: Snap notes to a grid [--grid --strength --swing]
midi split-tracks <midi>: One file per track or channel [--by]
midi tempo <midi>: Set or scale the tempo [--set --scale]
midi to-json <midi>: Convert MIDI to editable JSON [--compact]
midi transpose <midi>: Shift note pitches [--semitones --include-drums]
midi trim <midi>: Keep a time range [--range --shift]
midi velocity <midi>: Scale, compress, or set velocities [--scale --compress --set]
render <midi>: Render MIDI to audio with an instrument [--instrument --map --swap]
transcribe: Turn singing, humming, or an instrument into MIDI [--mode --tracker --min-note]
score <file>: Notation from a recording or a MIDI file [--layout --chords --solfa]
score check <file>: Validate a score: measure durations, voices, unsupported constructs [--strict]
score convert <file...>: Convert between notation formats [--pretty --solfa]
score from-json <file>: Score JSON back to notation [--pretty]
score perform <file>: One shot: read, play, render [--tempo --repeats --dynamics]
score play <file>: Notation to a MIDI performance [--tempo --repeats --dynamics]
score read <file>: Optical music recognition: sheet music to MusicXML [--pages --dpi --engine]
score to-json <file>: Score as the agent-facing JSON model [--pretty]
fx: Apply a chain of effects in order in one pass [--fx]
pipeline explain <file>: Print the resolved plan with every default filled in [--set]
pipeline run <file>: Run a pipeline file (YAML or JSON) with stage caching [--set --no-cache]
pipeline validate <file>: Check a pipeline file without running it [--set]
presets list [effect]: List built-in and user presets
presets save [name]: Save parameter values as a user preset [--set]
presets show [name]: Show a preset's values, e.g. compress/tighten
plugin info [name]: Show a plugin's parameters, presets, ports, latency, and MIDI support
plugin list: List cached plugins [--instruments --effects --format]
plugin presets list [name]: List a plugin's presets
plugin run: Run an effect plugin over audio [--plugin --param --preset]
plugin scan: Find CLAP and VST3 plugins and cache their metadata [--paths --format --rescan]
plugin state load [name]: Load a saved state into a plugin and show the resulting parameters [--state]
plugin state save [name]: Save a plugin's native state as base64 JSON [--param --preset --state]
sounds alias [assignment]: Set what an instrument name resolves to [--remove]
sounds info [id]: Show a registry entry's license, size, and downloads
sounds install [id]: Download, verify, and install a sound [--from --name]
sounds list: List installed sounds, or what a folder contains [--path --category]
sounds remove [id]: Remove an installed sound
sounds scan [dir]: Index a folder of sounds [--watch --interval]
sounds search [query]: Search the sounds registry [--type --license]
sounds update: Fetch the latest signed sounds registry
master: Automatic master of a finished mix to a delivery target [--target --lufs --true-peak]
master analyze: The measurement report an agent decides from [--target --lufs --true-peak]
master deliver: Write the deliverable set [--formats --tags --isrc]
master plan: The exact chain master would apply, every parameter resolved, editable [--target --lufs --true-peak]
master verify: Pass or fail against a delivery spec [--target --lufs --true-peak]
ffmpeg [args]: Run the managed FFmpeg with any arguments (pass-through)
ffprobe [args]: Run the managed ffprobe with any arguments (pass-through)
media extract-audio <file>: Pull an audio track out of a video or multi-track file [--track --copy]
media info <file>: Container and stream details as JSON (ffprobe -show_format -show_streams)
media remux <file>: Change the container without re-encoding (ffmpeg -c copy)
media replace-audio <file>x2: Write a copy of a video with a new audio track [--codec --keep-original --shortest]
media streams <file>: List every stream in a container: video, audio, subtitle, data
accelerate install: Install GPU execution-provider libraries for ONNX Runtime [--provider --accept-eula]
accelerate status: Show available execution providers and installed GPU libraries
models info [name]: Spec, license, source, benchmarks, and cache state of a model
models list: List registry models: version, task, size, license, cached, and which tiers use them [--task --cached]
models path [name]: Print the cached file path of a model
models prune: Remove cached models no tier uses, stale partial downloads, and enforce the cache budget
models pull [name]: Download models with resume and SHA-256 verification [--all-for --tier --accept-license]
models registry update: Refresh the signed registry manifest, or pin a snapshot [--pin --unpin --url]
models rm [name]: Remove a cached model
models verify [name]: Re-hash the model cache
describe: Compact catalog of every command for agents [--agent --format]
jobs cancel [id]: Cancel a running background job
jobs list: List background jobs started with --async
jobs logs [id]: Progress and log output of a background job
jobs result [id]: The JSON result envelope of a finished job
jobs status [id]: Status of a background job
jobs wait [id]: Block until a background job finishes, then return its result [--poll]
mcp serve: Run an MCP server exposing every command as a tool [--http --allow]
replay <file>: Re-run the command recorded in a sidecar
schema [command]: List commands, or print the JSON Schema of one command's arguments and result
verify <file>: Check that a sidecar's inputs and outputs still match their hashes
bench: Measure real-time factors of every effect on this machine [--only --duration --save]
completions [shell]: Print a shell completion script
doctor: Report what is installed: version, paths, FFmpeg, models, devices, plugins [--install-ffmpeg --install-audiveris]
licenses: Print every third-party license and attribution
self-uninstall: Remove everything the URL installer placed [--purge]
self-update: Update ferraus to the latest release (opt-in, never automatic) [--version]
docs [command]: Full reference page for a command, offline
docs build-site: Generate the mdBook docs site source from the command definitions [--out --guides --check]
man: Print a man page (roff) for ferraus

Error catalog

Every error carries a stable code, a message, an exit_code, and when a fix exists, a hint that is a runnable command.

Clean a podcast

This walkthrough takes a raw spoken-word recording with mains hum and background hiss to a clean episode at podcast loudness. Every command was run against ferraus 0.1.0 on a test recording; the outputs shown are trimmed copies of what it printed.

You need: ferraus, a recording (episode.wav here; any format ferraus reads works), and headphones. No models or downloads are needed for steps 1 to 6.

Making a test file. If you want to follow along without your own recording, this builds one: speech (macOS say; any voice recording works), pink hiss, and 60 Hz hum.

say -o speech.aiff "Welcome back to the show. Today we are talking about home recording."
ferraus convert speech.aiff -o voice.wav --sample-rate 48000
ferraus silence pad voice.wav --start 1.5s -o voice-pad.wav       # room tone before the first word
ferraus generate noise --color pink --dur 13.5s --amplitude -48dB --sample-rate 48000 -o hiss.wav
ferraus generate tone --freq 60Hz --dur 13.5s --amplitude -36dB --sample-rate 48000 -o hum.wav
ferraus mix voice-pad.wav hiss.wav hum.wav -o episode.wav

1. Listen, then ask ferraus what is wrong

Play the first ten seconds. Listen for: a low buzz under everything (hum), a steady "shhh" in the pauses (hiss), and level jumps between sentences.

ferraus analyze problems episode.wav

{
  "clean": false,
  "counts": {"high": 0, "medium": 2, "low": 1},
  "problems": [
    {"problem": "hum", "severity": "medium",
     "details": "60 Hz hum (harmonics [1]) at -23.1 dB relative to the signal",
     "suggested_fix": "dehum:freq=60Hz"},
    {"problem": "hiss", "severity": "medium",
     "details": "high-frequency noise floor of -57.7 dBFS (6–16 kHz) in quiet passages",
     "suggested_fix": "dehiss"},
    {"problem": "sibilance", "severity": "low",
     "details": "6% of loud frames are dominated by 5-10 kHz energy (peak -16.5 dBFS)",
     "suggested_fix": "deess"}
  ]
}

Every suggested_fix is an fx stage you can paste into a chain. Also note the starting loudness so you can compare later:

ferraus analyze loudness episode.wav

{"integrated_lufs": -16.4262, "loudness_range_lu": 1.7741, "true_peak_dbtp": -1.8811, ...}

2. Remove the hum

ferraus dehum episode.wav -o 1-dehum.wav --json

{"ok": true, "command": "dehum", "params": {"freq": "60.001Hz", "harmonics": "8", "depth": "-40dB", ...},
 "metrics": {"freq_hz": 60.001, "hum_reduction_db": 16.7}, ...}

ferraus found the mains frequency itself (60.001 Hz; in Europe and most of Africa and Asia it will find 50 Hz). Listen for: the buzz is gone in the pauses, and the voice has not lost its body. If a deep voice sounds thin, reduce the number of notched harmonics: --harmonics 4. To hear exactly what was removed, add --residual hum-only.wav.

3. Remove the hiss

Noise reduction works best when ferraus learns what the noise sounds like from a stretch that contains only noise. Most recordings have a second or two of room tone before the first word; --auto finds the quietest steady second for you.

ferraus denoise profile 1-dehum.wav --auto -o room.noiseprof --json

{"ok": true, "command": "denoise profile",
 "params": {"noise_region": {"range": "0.331s..1.323s", "level_db": -73.1, "method": "auto"}, ...},
 "result": {"profile": "room.noiseprof", "fft_size": 2048, "mean_level_db": -81.2, ...}}

Check that noise_region really is a pause (play that range). If it landed on a word, give the region yourself: --range 0s..1.2s. Then apply the profile and keep what was removed:

ferraus denoise 1-dehum.wav --profile room.noiseprof -o 2-denoised.wav --residual 2-removed.wav --json

{"ok": true, "command": "denoise",
 "metrics": {"mean_gain_db": -7.1, "input_rms_dbfs": -17.4, "output_rms_dbfs": -17.4, "removed_rms_dbfs": -53.3}, ...}

Listen for: the pauses are quiet, and there is no "underwater" or chirping sound on the voice (that sound is called musical noise). Then play 2-removed.wav: it should be hiss only. If you can hear words in it, the reduction is too strong; lower it with --reduction 8dB or raise --artifact-control 70%. If hiss remains, raise --reduction 18dB.

For a recording with no clean pause, or a changing background (traffic, a fan that speeds up), use a speech model instead of a profile:

ferraus denoise episode.wav --mode ml --model rnnoise -o clean.wav    # built in, no download
ferraus denoise episode.wav --mode ml -y -o clean.wav                  # DeepFilterNet 3, 8 MB download once

4. Polish the voice

enhance-voice is a preset chain for speech: a rumble filter, a de-plosive for p and b pops, a de-esser, gentle compression, and a presence lift. Pick male, female, or music.

ferraus enhance-voice 2-denoised.wav --mode female -o 3-voice.wav --json

{"metrics": {"stages": [
  {"op": "highpass", "args": {"freq_hz": 100.0, "order": 4}},
  {"op": "de-plosive", "args": {"below_hz": 150, "ducked_ms": 0.0}},
  {"op": "deess", "args": {"center": "7kHz", "threshold": "-24dB"}},
  {"op": "compress", "args": {"threshold": "-20dB", "ratio": "3:1", "attack": "5ms", "release": "80ms"}},
  {"op": "eq", "args": {"band": ["peak:250Hz:-1dB:q=1", "peak:4kHz:+2dB:q=1", "highshelf:12kHz:+2dB"]}}]}}

Listen for: clearer consonants, softer "s" sounds, and no boom on plosives. If it sounds too processed, blend it back: --mix 60%.

5. Even out the level, then set the loudness

Process the last steps in one fx pass. Each separate command writes an integer WAV file, and a stage that adds gain (the leveler does) can push peaks past full scale and clip in the file it writes. Inside one fx run the audio stays in floating point until the final normalize, whose limiter catches the peaks.

ferraus fx 3-voice.wav -o episode.clean.wav --fx leveler --fx "normalize:lufs=-16" --json

leveler raises quiet sentences and lowers loud ones slowly, like a careful engineer riding a fader. normalize --lufs -16 sets the integrated loudness to -16 LUFS (the usual target for stereo podcasts; the podcast spec for mono is -19 LUFS, see Loudness standards) and limits true peaks to -1 dBTP.

Listen for: every sentence at a similar level, with no pumping (the background swelling in the pauses). If the pauses get noisy, the leveler is boosting room tone: raise its noise gate, --fx "leveler:gate=-50dB".

6. Check the result

ferraus analyze problems episode.clean.wav
ferraus analyze loudness episode.clean.wav

{"clean": true, "counts": {"high": 0, "medium": 0, "low": 2}, ...}
{"integrated_lufs": -16.0249, "loudness_range_lu": 1.1295, "true_peak_dbtp": -1.0191, ...}

The whole thing in one command

Once you know the settings that suit your room, run every stage in one pass (the fx stage names and keys are the command names and flags):

ferraus fx episode.wav -o episode.clean.wav \
  --fx dehum --fx "denoise:auto" --fx leveler --fx "enhance-voice:mode=female" --fx "normalize:lufs=-16"

To trim long pauses as well, add ferraus silence trim episode.clean.wav --all --threshold -50dB --max-gap 700ms -o tight.wav. Choose the threshold from ferraus silence detect: it should sit a few dB above the floor level that command reports for the pauses.

For a whole folder of episodes, see the batch podcast cleanup recipe.

Reference

analyze problems · dehum · denoise profile · denoise · enhance-voice · leveler · normalize · fx · silence trim

Host a plugin

ferraus runs CLAP and VST3 plugins (effects and instruments) offline, so you can use the plugins you already own in scripts and agent workflows. Each plugin runs in a separate ferraus-plughost process: a plugin that crashes or hangs cannot take ferraus down with it. This walkthrough uses CLAP. Outputs are trimmed copies of what ferraus 0.1.0 printed with the small test plugins from the ferraus repository (crates/ferraus-test-plugin: a gain, a delay, and a sine instrument); with your own plugins only the names change.

You need: a CLAP plugin (free ones include Surge XT, Dexed, Vital, and the Airwindows Consolidated set) installed in a standard folder, or a .clap bundle in any folder.

1. Find your plugins

ferraus plugin scan

The scan looks in the standard folders for your system (on macOS ~/Library/Audio/Plug-Ins/CLAP, /Library/Audio/Plug-Ins/CLAP, and the same for VST3; on Linux ~/.clap and /usr/lib/clap; on Windows %COMMONPROGRAMFILES%\CLAP and %LOCALAPPDATA%\Programs\Common\CLAP; plus every folder in CLAP_PATH), probes each bundle in a separate process, and caches the result, so later scans only look at new or changed bundles. Plugins somewhere else:

ferraus plugin scan --paths ~/plugins --json

{"ok": true, "command": "plugin scan", "metrics": {"plugins": 5, "bundles": 1, "probed": 1},
 "result": {"plugins": [
   {"name": "Ferraus Test Gain", "id": "ferraus.test.gain", "vendor": "ferraus", "format": "clap", "kind": "audio-effect", ...},
   {"name": "Ferraus Test Sine", "id": "ferraus.test.sine", "format": "clap", "kind": "instrument", "category": "synth", ...},
   ...], "errors": []}}

A plugin that fails to load is listed under errors with its path; the scan goes on.

ferraus plugin list                 # everything cached
ferraus plugin list --instruments   # only instruments

2. Look inside one

ferraus plugin info "Ferraus Test Gain"

{"plugin": {"name": "Ferraus Test Gain", "id": "ferraus.test.gain", "format": "clap", ...},
 "params": [{"id": 0, "name": "gain", "min": -60.0, "max": 24.0, "default": 0.0, "default_text": "0.00 dB", "unit": "dB", ...}],
 "presets": [{"name": "Quiet", "load_key": "quiet"}, {"name": "Loud", "load_key": "loud"}],
 "audio_inputs": [{"name": "in", "channels": 2, "main": true}], ...}

params are the names you set with --param; presets are the names --preset loads.

3. Process audio through an effect

ferraus plugin run voice.wav --plugin "Ferraus Test Gain" --param "gain=-6dB" -o voice.gain.wav --json

{"ok": true, "command": "plugin run",
 "outputs": [{"path": "voice.gain.wav", "duration_s": 11.298, "sample_rate": 48000, "channels": 2}],
 "metrics": {"latency_samples": 0, "tail_s": 0.0},
 "result": {"params": [{"id": 0, "name": "gain", "value": -6.0, "text": "-6.00 dB"}], "preset": null, ...}}

• --param takes the display units the plugin shows (-6dB, 2.5kHz, 30%), or a normalized value (norm:0.3). Repeat it for more parameters.
• --preset Quiet loads a preset first, then applies any --param values.
• --tail 3s keeps processing after the input ends so reverbs and delays ring out.
• --mix 30% blends the processed signal with the dry input.
• The plugin's latency is compensated, so the output lines up with the input sample for sample. The output has the plugin's channel count: this stereo test plugin turned a mono file into a stereo one (add --channels 1 to get mono back).

Listen for: the effect you asked for and nothing else: no clicks at the start (latency compensation) and no cut-off tails (raise --tail).

The sidecar (voice.gain.wav.ferraus.json) stores the plugin, its parameters, and its state, so ferraus replay voice.gain.wav.ferraus.json --overwrite repeats the run. To save a configured state yourself:

ferraus plugin state save "Ferraus Test Gain" --param "gain=-3dB" -o gain.state.json
ferraus plugin run voice.wav --plugin "Ferraus Test Gain" --state gain.state.json -o voice.state.wav

4. Play MIDI through an instrument plugin

ferraus render melody.mid --instrument 'plugin:"Ferraus Test Sine"' -o melody.plugin.wav --json

{"ok": true, "command": "render",
 "params": {"instrument": {"given": "plugin:\"Ferraus Test Sine\"", "source": {"type": "plugin", "name": "Ferraus Test Sine"}, "via": "explicit"}},
 "metrics": {"duration_s": 11.57, "notes": 16, "peak_dbfs": -8.08}}

Use the plugin:"Name" form for plugin instruments (the quotes go inside the argument, so wrap the whole thing in single quotes in your shell). hum --to and score perform --instrument take the same form.

5. Plugins and sounds outside the standard folders: --sound-path

Point ferraus at a folder of plugins, SoundFonts (.sf2), SFZ libraries, and impulse responses for one run with --sound-path (repeatable), for every run with the FERRAUS_SOUND_PATH environment variable, or permanently with [sounds] paths in the config:

ferraus sounds list --path ~/my-sounds       # what ferraus finds in the folder
ferraus sounds scan ~/my-sounds              # index it (fast lookups later)
ferraus plugin run in.wav --sound-path ~/my-sounds --plugin "My Reverb" -o out.wav
ferraus render song.mid --sound-path ~/my-sounds --instrument strings -o song.wav

6. Install free instruments: sounds install

The sounds registry lists free instruments with their licenses and pinned checksums:

ferraus sounds search piano
ferraus sounds info gm-basic
ferraus sounds install gm-basic -y

{"ok": true, "command": "sounds install",
 "result": {"id": "gm-basic", "license": {"spdx": "LicenseRef-GeneralUser-GS-2.0", ...},
            "installed": {"name": "GM Basic (GeneralUser GS)", "type": "sf2", "paths": [".../data/sounds/gm-basic"]}}}

The license is printed before anything is installed; downloads need -y. After installing gm-basic, every General MIDI name plays from it instead of the built-in synth:

ferraus render melody.mid --instrument Flute -o melody.flute.wav

{"params": {"instrument": {"given": "Flute", "source": {"type": "sf2", "path": ".../GeneralUser-GS.sf2", "preset": {"bank": 0, "program": 73}},
                           "via": "gm", "program": 73, "program_name": "Flute"}}}

Vendors that require their own installer (Vital, for example) cannot be downloaded by ferraus; download them yourself and register the file: ferraus sounds install vital --from ~/Downloads/VitalInstaller.zip. ferraus never runs installers or asks for administrator rights.

Short names for instruments you use often: ferraus sounds alias piano=salamander-grand-piano.

When something goes wrong

{"ok": false, "error": {"code": "plugin_not_found",
  "message": "no plugin named 'Nonexistent Synth' was found (searched the scan cache and --sound-path folders)",
  "hint": "ferraus plugin scan --paths <folder-with-plugins>", "exit_code": 7}}

Exit code 7 covers a plugin that was not found, crashed, or stopped responding (the host is stopped after --watchdog, 60 s by default). See Troubleshooting.

Reference

plugin scan · plugin list · plugin info · plugin run · plugin state save · render · sounds install · Sound folders

Turn a hum into an instrument part

Hum, sing, or whistle a melody into your phone, and ferraus turns it into a MIDI part played by a real instrument sound. This walkthrough shows the one-step command, then the steps underneath it so you can fix wrong notes. Outputs are trimmed copies of what ferraus 0.1.0 printed.

You need: a recording of one melody line (idea.wav): humming, "la la la", whistling, or a single instrument. Record somewhere quiet, close to the microphone, one note at a time. No downloads are needed.

Making a test file. Without a recording, render a melody with a soft lead sound and roll off its brightness so it behaves roughly like a hum (melody.mid is any one-line MIDI melody; see Make a score for how to write one from JSON):

ferraus render melody.mid --instrument builtin:lead --tail 0.5s -o lead.wav
ferraus fx lead.wav -o idea.wav --fx "lowpass:freq=900Hz" --fx "tremolo:rate=5.5,depth=15%" --channels 1

1. One step: hum to piano

ferraus hum idea.wav --to piano -o idea-piano.wav --json

{"ok": true, "command": "hum",
 "outputs": [{"path": "idea-piano.mid", "role": "midi"}, {"path": "idea-piano.wav", "duration_s": 11.77}],
 "params": {"bpm": "99.84 (audio)", "grid": "1/16", "strength": "80%", "key": "A minor (confidence 0.91; snapped)", "to": "piano", ...},
 "metrics": {"notes": 11, "tempo_confidence": 1.0, "mean_note_confidence": 0.995},
 "result": {"mode": "mono", "engine": "pyin", "bpm": 99.84, "key": "A minor", "pitch_range": ["A4", "E5"],
            "midi": "idea-piano.mid", "audio": "idea-piano.wav", "instrument": "piano", ...}}

ferraus tracked the pitch, found the tempo (99.84 BPM; the melody was played at 100) and the key, split the line into notes, nudged them 80% of the way onto a sixteenth-note grid, and played them with a piano. It also wrote the MIDI part, idea-piano.mid, so you can edit or re-voice it.

Listen for: the right notes in the right order, and the rhythm of your hum (not a machine-straight version of it, unless you asked for that).

2. Missing notes? Split repeated notes

Our test melody has 16 notes but ferraus found 11. The missing ones are repeated notes: when you hum the same pitch twice without a clear break, it sounds like one long note. --onset-sensitivity controls how readily a note is split on a small dip in level or pitch:

ferraus transcribe idea.wav -o idea.mid                            # 11 notes (default 50%)
ferraus transcribe idea.wav --onset-sensitivity 90% -o idea90.mid  # 13 notes
ferraus transcribe idea.wav --onset-sensitivity 100% -o idea100.mid

The note lists, from each .notes.json file:

50%:  E5 D5 C5 D5 E5 C5 B4 A4 B4 C5 A4
90%:  E5 D5 C5 D5 E5 E5 C5 B4 A4 B4 C5 A4 A4
100%: E5 D5 C5 D5 E5 E5 E5 C5 C5 B4 A4 B4 C5 C5 A4 A4    (all 16)

hum takes the same flag: ferraus hum idea.wav --to piano --onset-sensitivity 100% -o idea-piano.wav. Going the other way, if a wobbly hum is split into extra short notes, lower the sensitivity or raise --min-note 120ms. Humming each note on "da" or "ta" instead of "mm" gives the clearest onsets of all.

3. Check every note

transcribe writes a JSON list beside the MIDI file with a confidence for every note:

ferraus transcribe idea.wav -o idea.mid --json

{"ok": true, "command": "transcribe",
 "outputs": [{"path": "idea.mid"}, {"path": "idea.notes.json", "role": "notes"}],
 "result": {"mode": "mono", "notes": 11, "bpm": 99.84, "key": "A minor", "key_confidence": 0.91,
            "key_snapped": true, "notes_snapped": 0, "pitch_range": ["A4", "E5"], "mean_confidence": 0.995, ...}}

{"start_s": 0.01, "end_s": 0.6197, "pitch": 76, "name": "E5", "velocity": 92, "confidence": 0.993, ...}

Notes with low confidence are the ones to listen to. Out-of-key notes are moved to the nearest note of the key when the key confidence is above 0.6 (--key-snap off keeps them).

4. Choose the instrument, tempo, and feel

ferraus hum idea.wav --to strings --grid 1/8 --strength 100% --bpm 100 -o idea-strings.wav
ferraus hum bass-idea.wav --to "Acoustic Bass" --bpm 92 -o bass.wav

• --to takes any instrument name render understands: piano, strings, a General MIDI name such as "Acoustic Bass" or "Flute", gm:48, an installed sound, or a plugin (plugin:"Surge XT"). With no sounds installed, a built-in synth plays it; install the free General MIDI sound bank for much better instruments: ferraus sounds install gm-basic -y (31 MB).
• --grid 1/8 --strength 100% snaps fully to eighth notes (tight and mechanical); --grid off keeps your timing exactly.
• --bpm fixes the tempo instead of detecting it, so the part lines up with a song at that tempo.
• --octave auto (the default) moves the part into the instrument's comfortable range, so a hummed bass line plays in the bass register.

5. Re-voice the MIDI without re-humming

ferraus render idea-piano.mid --instrument "Acoustic Bass" -o idea-bass.wav
ferraus midi transpose idea-piano.mid --semitones -12 -o idea-low.mid
ferraus midi quantize idea-piano.mid --grid 1/8 --strength 100% -o idea-tight.mid

Any DAW can open the .mid files too.

Reference

hum · transcribe · render · midi quantize · midi transpose · sounds install

Make a score from a song or a MIDI file

ferraus score writes readable sheet music: a lead sheet with chord symbols, a grand staff for piano, a drum score, or tonic sol-fa. MusicXML is the main output; MuseScore, Finale, Sibelius, Dorico, and most notation apps open it. This walkthrough starts from MIDI (the reliable path), then goes from a recording. Outputs are trimmed copies of what ferraus 0.1.0 printed.

You need: a MIDI file, or a recording plus the separation model (see Split a song into stems). PDF, SVG, and PNG pages also need an engraver (step 4).

1. A melody to a lead sheet

Making a test file. A MIDI file can be written from a few lines of JSON:

cat > melody.json <<'EOF'
{"tempo_map": [{"beat": 0, "bpm": 100}],
 "tracks": [{"notes": [
   {"beat": 0, "duration_beats": 1, "name": "E5", "velocity": 100},
   {"beat": 1, "duration_beats": 1, "name": "D5", "velocity": 100},
   {"beat": 2, "duration_beats": 1, "name": "C5", "velocity": 100},
   {"beat": 3, "duration_beats": 1, "name": "D5", "velocity": 100}]}]}
EOF
ferraus midi from-json melody.json -o melody.mid

The examples below used a 16-note version of this melody.

ferraus score melody.mid -o melody.musicxml --title "Little Tune" --svg melody.svg --abc melody.abc --solfa-txt melody.solfa.txt --json

{"ok": true, "command": "score",
 "outputs": [{"path": "melody.musicxml", "role": "musicxml"}, {"path": "melody.abc", "role": "abc"},
             {"path": "melody.solfa.txt", "role": "solfa"}, {"path": "melody.svg", "role": "svg"}],
 "params": {"engraver": "native", "key": "A minor", "time": "4/4", "quantize": "1/16", ...},
 "result": {"measures": 4, "check": {"ok": true, "errors": 0, "warnings": 0}, "low_confidence": [],
            "notation": {"key": "A minor", "key_source": "estimated", "key_confidence": 1.0, "tempo_bpm": 100.0,
                         "parts": [{"id": "P1", "name": "Piano", "layout": "lead-sheet", "notes": 16}]}}}

The ABC and sol-fa outputs are plain text:

X:1
T:Little Tune
M:4/4
L:1/8
Q:1/4=100
K:Am
e2 d2 c2 d2 | e2 e2 e2 c2 | c2 B2 A2 B2 | c2 c2 A2 A2 |]

Little Tune
Key: Doh is C (A minor, lah is A)
Time: 4/4
Tempo: 100 bpm

|m :r :d :r |m :m :m :d |d :t, :l, :t, |d :d :l, :l, ||

Check: open melody.musicxml in a notation app (or melody.svg in a browser) and play it back. The key was estimated from the notes (key_source); this melody sits equally well in C major and its relative minor, A minor, and ferraus chose A minor. If you know the key, give it: --key C. Notes are snapped to --quantize 1/16 (use 1/8 for simpler rhythms, 1/32 for fast passages).

Sol-fa only, with no staff (--solfa only), or fixed do (--solfa fixed):

ferraus score melody.mid --solfa only -o melody-solfa.txt

Transpose for another instrument or singer, with guitar chord diagrams:

ferraus score melody.mid --chords diagrams --transpose 3 -o lead.musicxml

2. A full arrangement

A multi-track MIDI file becomes one part per track: the drum channel (10) gets a drum score, wide-range parts get a grand staff, and the rest get lead sheets (in the bass clef when low).

ferraus score song.mid -o song.musicxml --midi song.score.mid --json

{"result": {"parts": [{"id": "P1", "name": "lead", "staves": 1}, {"id": "P2", "name": "piano", "staves": 2},
                      {"id": "P3", "name": "bass", "staves": 1}, {"id": "P4", "name": "drums", "staves": 1, "percussion": true}],
            "measures": 8, "check": {"ok": true, "errors": 0, "warnings": 0},
            "notation": {"key": "C major", "key_confidence": 0.9, "time": "4/4", "tempo_bpm": 100.0,
                         "chords": ["C", "Am", "F", "G", "Gadd9", "C", "Am", "F", "G"]}}}

--midi song.score.mid also writes the MIDI performance of the notation, so you can hear exactly what was notated. Validate any score file with:

ferraus score check song.musicxml

{"ok": true, "errors": 0, "warnings": 0, "parts": 4, "measures": 8, "notes": 184, "issues": [], "failing_measures": []}

Force a layout when the automatic choice is wrong: --layout grand --split C4 for piano with a fixed hand split, --layout drums, --layout bass, --layout lead-sheet.

3. From a recording

The one-command route

ferraus score take.wav --parts vocals,bass,drums -o take.musicxml --midi take.mid -y

This runs analyze tempo, analyze key, analyze chords, separate, transcribe per stem, and a native drum transcription, then notates. --dry-run shows that plan. It separates with the default tier (balanced in this release: four fine-tuned Demucs models, about 660 MB on the first run; see Stems and separation tiers). Measured with the quality tier (the Mel-Band RoFormer for the vocals) on a 7-second excerpt of a MUSDB18 test song, it took 52 s on a laptop CPU and peaked at 3.2 GB of memory:

{"parts": [{"id": "P1", "name": "Vocals"}, {"id": "P2", "name": "Bass"}, {"id": "P3", "name": "Drums", "percussion": true}],
 "measures": 6, "check": {"ok": true, "errors": 0, "warnings": 0},
 "audio": {"stems": [{"role": "vocals", "notes": 20, "mode": "mono"}, {"role": "bass", "notes": 16, "mode": "mono"},
                     {"role": "drums", "notes": 67, "method": "native onset drum transcription"}]}}

A stem with nothing pitched in it (a part the song does not have) is reported with a no_notes warning and left out of the score.

The step-by-step route (faster, pitched parts)

Do the same steps yourself with the fast tier, which needs one 166 MB model. Measure the tempo first and pass it to every transcription, so all the parts share one tempo map:

ferraus analyze tempo song.wav                       # "bpm": 100.0, "confidence": 1.0
ferraus separate song.wav --tier fast -y
ferraus transcribe song.bass.wav --mode mono --program 33 --bpm 100 -o bass.mid
ferraus transcribe song.other.wav --mode poly --bpm 100 -y -o other.mid      # chords: Basic Pitch model, 230 kB
ferraus midi merge other.mid bass.mid -o parts.mid
ferraus score parts.mid --title "From audio" -o parts.musicxml

{"notation": {"key": "C major", "time": "4/4", "tempo_bpm": 100.0, "measures": 9,
              "parts": [{"id": "P1", "layout": "grand", "notes": 159}, {"id": "P2", "layout": "lead-sheet", "notes": 33}],
              "chords": ["C", "Am", "F", "G", "C", "Am", "F", "Bm7b5/F", "G"]}}

Check: the bass line (one note at a time) transcribes very accurately (33 notes for 32 played). Polyphonic parts (--mode poly, chords) are best-effort: the mean note confidence was 0.52, and the chord list has one wrong chord (Bm7b5/F where the song plays F). Open the score, play it back against the recording, and fix what you hear. Drum audio is not transcribed on this route; analyze chords song.wav gives chord symbols with times if you only need a chord chart.

4. PDF, SVG, and PNG pages

MusicXML, ABC, LilyPond (--ly), MEI (--mei), and sol-fa are written natively. --svg falls back to a minimal built-in renderer. Proper engraving (--pdf, --png, and good SVG) needs the ferraus-engrave helper (shipped in the release packages; from source: cargo build -p ferraus-engrave --release) or LilyPond. Without either, ferraus says so:

{"ok": false, "error": {"code": "engraver_missing",
  "message": "no engraver found: neither the ferraus-engrave helper (Verovio) nor LilyPond is available; SVG, PDF, and PNG output need one", ...}}

ferraus doctor reports which engraver it found ("engraver": {"helper": ..., "lilypond": ...}).

Reference

score · score check · score convert · transcribe · midi merge · analyze chords · Notation and solfa

Master a track

Mastering takes a finished stereo mix and prepares it for release: balanced tone, controlled dynamics, a safe stereo image, and the right loudness for where it will be played, without clipping. ferraus master does all of it in one command, and every stage is an ordinary ferraus command you can inspect, edit, and re-run. Outputs are trimmed copies of what ferraus 0.1.0 printed for a 21-second test mix.

You need: a stereo mix (mix.wav) with some headroom (peaks below about -3 dBFS, no limiter on the mix bus). No downloads are needed.

1. Measure the mix

ferraus master analyze mix.wav --json

{"ok": true, "command": "master analyze",
 "metrics": {"integrated_lufs": -19.61, "true_peak_dbtp": -4.94, "looks_mastered": false},
 "result": {"loudness": {"integrated_lufs": -19.61, "loudness_range_lu": 0.84, "true_peak_dbtp": -4.94, "crest_factor_db": 17.02, "plr_db": 14.67},
            "tonal_balance": {"against": "genre curve: acoustic", "rms_deviation_db": 3.23,
                              "largest_deviations": [{"center_hz": 10000.0, "delta_db": 8.2, "direction": "too much"},
                                                     {"center_hz": 800.0, "delta_db": -7.0, "direction": "too little"}, ...]}, ...}}

This is the report the automatic master decides from: how loud the mix is, how much peak room it has, and how its tone compares with a typical curve for the genre (guessed here as "acoustic"; set it with --genre pop|hiphop|edm|rock|acoustic|classical|jazz|podcast).

Listen for the same things before you start: harsh or dull top end, boomy or thin bass, and whether the loud parts already sound squashed.

2. Master it

ferraus master mix.wav -o master.wav --report report.json --ab --json

{"ok": true, "command": "master",
 "outputs": [{"path": "master.wav"}, {"path": "master.ab-before.wav", "role": "ab-before"},
             {"path": "master.ab-after.wav", "role": "ab-after"}, {"path": "report.json", "role": "report"}],
 "params": {"target": "streaming", "genre": "acoustic", "intensity": "medium", "warmth": "15%", "width": "100%", ...},
 "metrics": {"integrated_lufs": -14.0, "true_peak_dbtp": -1.02, "limiter_gain_reduction_db": 0.3,
             "target_reached": true, "verify_pass": true, "ab_loudness_difference_lu": 0.0}}

The default target is streaming: -14 LUFS integrated, true peak at or below -1 dBTP, which is where Spotify, YouTube, Tidal, and Amazon normalize playback. The master also trimmed the 2-second silent tail of the test mix (--trim-silence -70dB; off keeps it).

Listen to the A/B pair, not the master against the mix. master.ab-before.wav and master.ab-after.wav are matched in loudness (here within 0.0 LU), so you hear what mastering changed rather than "louder sounds better". Listen for: a clearer, more even tone; bass that is solid but not boomy; no pumping (the level dipping on every kick); no harshness on loud cymbals or vocals.

3. Check it against the delivery spec

ferraus master verify master.wav --target streaming

{"pass": true, "target": {"name": "streaming", "lufs": -14.0, "true_peak_dbtp": -1.0}, "tolerance_lu": 0.5,
 "checks": [
   {"check": "loudness", "status": "pass", "value": -14.0, "limit": "-14 LUFS ± 0.5 LU"},
   {"check": "true_peak", "status": "pass", "value": -1.02, "limit": "<= -1 dBTP (4x oversampled)"},
   {"check": "clipping", "status": "pass", "value": 0},
   {"check": "dc_offset", "status": "pass", "value": 0.00011},
   {"check": "out_of_phase_bass", "status": "pass", "value": 1.0},
   {"check": "correlation", "status": "pass", "value": 1.0}, ...]}

A failing file exits with code 9 and a runnable fix for each failed check. The unmastered mix, for example:

ferraus master verify mix.wav --target streaming --json

{"ok": false, "metrics": {"pass": false, "failed_checks": ["loudness"],
  "checks": [{"check": "loudness", "status": "fail", "value": -19.61,
              "details": "integrated loudness -19.61 LUFS is -5.61 LU from the -14 LUFS target",
              "fix": "normalize:lufs=-14LUFS"}, ...]},
 "error": {"code": "verification_failed", "exit_code": 9, ...}}

4. Change what the master does

Plan without writing audio, edit the plan, then run the edited plan:

ferraus master plan mix.wav --target apple --intensity light -o plan-apple.json

{"version": 1,
 "target": {"name": "apple", "lufs": -16.0, "true_peak_dbtp": -1.0},
 "intensity": {"name": "light", "limiter_max_gain_reduction_db": 2.0},
 "stages": [
   {"stage": "preflight", "op": "dc-remove", "args": {"freq": "5Hz"}, "why": "remove DC offset (5 Hz high-pass)"},
   {"stage": "preflight", "op": "silence trim", "args": {"threshold": "-70dB", "keep": "10ms"}, ...},
   {"stage": "corrective_eq", "op": "eq", "args": {"band": ["peak:25Hz:+3dB:q=4.32", ...], "linear_phase": "true"},
    "why": "match-eq toward the acoustic genre curve at 50% (1/3-octave bands, at most 4 dB per band; ...)"},
   {"stage": "corrective_eq", "op": "highpass", "args": {"freq": "20Hz", "order": "4"}, ...},
   {"stage": "dynamics", "op": "multiband", "args": {"crossovers": "120Hz,2kHz,10kHz", "ratio": "1.5:1", ...}, ...},
   {"stage": "dynamics", "op": "compress", "args": {"threshold": "-22dB", "ratio": "1.5:1", ...}, ...},
   ...]}

Every stage is a ferraus command with its arguments, and why explains the choice. Change a value (say, the compressor threshold), delete a stage you do not want, then:

ferraus master mix.wav --plan plan-apple.json -o master-apple.wav
ferraus master verify master-apple.wav --target apple

Common adjustments without editing a plan:

Targets: streaming (-14 LUFS), apple (-16), youtube (-14), club (-8, -0.3 dBTP), cd (-10, 16-bit 44.1 kHz), broadcast (-23, EBU R128; --standard atsc for -24 LKFS), podcast (-16 stereo, -19 mono), or custom with --lufs and --true-peak. See Loudness standards.

5. Write the release files

ferraus master deliver master.wav --tags title=Demo,artist=Ferraus --loudness-sheet -o release/demo.wav

release/demo.wav24.wav   release/demo.wav16.wav   release/demo.mp3
release/demo.loudness.json   release/demo.loudness.csv

format,path,sample_rate,channels,bit_depth,bitrate,duration_s,integrated_lufs,loudness_range_lu,short_term_max_lufs,true_peak_dbtp,sample_peak_dbfs,plr_db,measured
wav24,release/demo.wav24.wav,48000,2,24,,19.597,-14.0,0.25,-13.74,-1.02,-1.11,12.98,decoded deliverable
wav16,release/demo.wav16.wav,44100,2,16,,19.597,-14.02,0.26,-13.76,-1.05,-1.32,12.97,decoded deliverable
mp3,release/demo.mp3,44100,2,,320000,19.597,-14.04,0.26,-13.78,-0.85,-0.85,13.2,decoded deliverable

Every deliverable is decoded and measured again. Note the MP3's true peak (-0.85 dBTP): lossy encoding adds small overshoots, so check the sheet before you upload. Add flac and aac with --formats wav24,flac,aac (AAC needs FFmpeg), and an ISRC with --isrc.

Reference

master · master analyze · master plan · master verify · master deliver · normalize

Perform a sheet-music file

ferraus score perform reads written music and plays it: it turns the notation into a MIDI performance (repeats unrolled, dynamics and articulations applied) and renders that with an instrument. This walkthrough uses ABC and MusicXML files. Outputs are trimmed copies of what ferraus 0.1.0 printed.

You need: a notation file: MusicXML (.musicxml, .xml, .mxl), ABC (.abc), MEI, LilyPond (.ly), MIDI, or ferraus score JSON. Most notation apps export MusicXML, and thousands of folk tunes are published as ABC.

Printed sheet music (a PDF or a page image) works too: score perform reads it with optical music recognition first. Section 5 shows that path and what to check.

1. Write or get a score

Save this as tune.abc (the first lines of Beethoven's Ode to Joy):

X:1
T:Ode to Joy (excerpt)
C:Beethoven
M:4/4
L:1/4
Q:1/4=96
K:D
!mf! F F G A | A G F E | D D E F | F3/2 E/ E2 |
F F G A | A G F E | D D E F | !p! E3/2 D/ D2 |]

Check that ferraus reads it the way you meant:

ferraus score check tune.abc

{"ok": true, "errors": 0, "warnings": 0, "parts": 1, "measures": 8, "notes": 30, "issues": [], "failing_measures": []}

check finds measures whose durations do not add up, voices that overlap, and constructs ferraus cannot play, with the measure number for each.

2. Perform it

ferraus score perform tune.abc --instrument piano -o tune.wav --json

{"ok": true, "command": "score perform",
 "outputs": [{"path": "tune.musicxml", "role": "musicxml"}, {"path": "tune.mid", "role": "midi"},
             {"path": "tune.wav", "role": "audio", "duration_s": 22.0}],
 "params": {"tempo": "auto", "repeats": "on", "dynamics": "on", "articulation": "on", "humanize": "0%", ...},
 "result": {"engine": "none (abc input)",
            "performance": {"duration_s": 20.0, "notes": 30, "measures_played": 8, "order": [1, 2, 3, 4, 5, 6, 7, 8], "tempo_bpm": 96.0},
            "render": {"instrument": "builtin:piano", ...}}}

Beside the audio you get the MusicXML and the MIDI performance, so you can open either in another program. order lists the measures in the order they were played, which is where you check that repeats and first/second endings were followed.

Listen for: the tempo marking (96 here; --tempo 120 overrides it), the !mf! to !p! dynamic change in the last line, and the dotted rhythm in bars 4 and 8.

3. Shape the performance

ferraus score perform tune.abc --tempo 120 --swing 50% --humanize 30% --seed 7 --instrument strings -o tune-strings.wav

• --humanize 30% adds small random timing and velocity changes (seeded, so the same seed gives the same performance).
• --swing 50% delays the off-beat eighths halfway to a triplet feel.
• --instrument-map "P1=piano,P2=strings" chooses an instrument per part in a multi-part score.
• --repeats off, --dynamics off, and --articulation off switch each interpretation step off.
• --click on adds a metronome track.

For better instruments than the built-in synth, install the General MIDI sound bank once (31 MB) and use General MIDI names:

ferraus sounds install gm-basic -y
ferraus score perform melody.musicxml --instrument "Acoustic Grand Piano" -o melody.wav

4. Just the MIDI, or another format

ferraus score play tune.abc -o tune-perf.mid --click on      # the performance as MIDI, no audio
ferraus score convert tune.abc -o tune.musicxml              # ABC to MusicXML
ferraus score to-json tune.abc -o tune.score.json            # the editable JSON model

The JSON model is what an agent edits: change a note's pitch or duration, then ferraus score from-json tune.score.json -o fixed.musicxml and perform it again. Small corrections can also be applied as an edit list with ferraus score read tune.musicxml --fix edits.json -o fixed.musicxml.

5. From printed sheet music

score read and score perform accept a PDF or a page image (PNG, JPEG, TIFF, ...) and read it with the built-in recognizer: oemer's two segmentation networks (MIT license, about 110 MB, downloaded once) find staff lines, noteheads, stems, rests, clefs, and accidentals, and ferraus rebuilds the measures from them. Allow the download with -y the first time (or run ferraus models pull omr/oemer omr/oemer-seg):

ferraus score perform minuet.pdf --instrument piano -o minuet.wav -y --json

{"ok": true, "command": "score perform",
 "outputs": [{"path": "minuet.musicxml", "role": "musicxml"}, {"path": "minuet.mid", "role": "midi"},
             {"path": "minuet.wav", "role": "audio", "duration_s": 26.0}],
 "models": [{"name": "omr/oemer", ...}, {"name": "omr/oemer-seg", ...}],
 "result": {"engine": "builtin",
            "performance": {"duration_s": 24.0, "notes": 73, "measures_played": 16, ...}}}

Reading takes 15–60 seconds per page on a laptop CPU. PDFs are turned into images with pdftoppm (poppler) or mutool when one is installed; on macOS without them, sips reads the first page only. --pages 2-3 picks pages and --dpi the resolution.

Check before you listen. Recognition is not perfect, so read first and look at the review:

ferraus score read minuet.pdf -o minuet.musicxml --review

The result says whether the score passes score check (check_ok), lists measures whose durations do not add up (failing_measures), and gives every measure a confidence with the reason when it is low (for example dot added to fill the measure or uncertain notehead). Fix what is wrong with an edit list (--fix edits.json, see the cookbook) or in a notation app, then perform the corrected MusicXML.

What it reads: clean printed (engraved) music: treble, bass, and C clefs; key and time signatures; notes from whole to 32nd with beams, flags, and dots; chords; rests; sharps, flats, and naturals; one or more staves per system, including piano grand staves. On the project's engraved test set (23 pieces, 975 notes, read both as PNG and as PDF) every pitch and duration came out right; scans and other engravers' fonts will do worse, which is why the review matters.

What it does not read: lyrics and other text, tuplets, grace notes, ties, slurs, dynamics, articulations, repeats and endings, and two voices on one staff (they come out as chords). Handwritten music and phone photos of pages are best-effort. For those, the optional Audiveris bridge (ferraus doctor --install-audiveris, then --engine audiveris) is often better.

Reference

score perform · score play · score check · score read · score convert · score to-json · render

Split a song into stems

Stem separation splits a finished mix into its parts: vocals, drums, bass, and everything else ("other"). Use it to make a karaoke or instrumental version, pull a vocal for a remix, practise along with the drums muted, or clean up one part. Outputs below are trimmed copies of what ferraus 0.1.0 printed for a 21-second test song.

You need: a song (song.wav; MP3, FLAC, and M4A work too), about 170 MB of disk space for the model, and a network connection the first time.

Which tier to use

Separation uses neural-network models from the ferraus model registry, and every tier has a verified download. The default tier, auto, picks quality (a Mel-Band RoFormer for the vocals plus fine-tuned Demucs for drums, bass, and other: about 960 MB of models, about 7 minutes for a 4-minute song on a laptop CPU), which gives the cleanest vocals. --tier balanced (four fine-tuned Demucs models, about 660 MB, about 3 minutes) is the middle ground. The commands below use --tier fast (Demucs v4 htdemucs, 166 MB, MIT license, under a minute for a 4-minute song) to keep the first run quick. See Stems and separation tiers for all tiers and their measured quality.

1. See what would happen

ferraus separate song.wav --tier fast --dry-run --json

{"ok": true, "command": "separate", "dry_run": true,
 "result": {"plan": [{"model": "separate/htdemucs@v4-onnx.2026-05-21", "weight": 1.0, "cached": false}],
            "outputs": [{"stem": "vocals", "path": "song.vocals.wav"}, {"stem": "drums", "path": "song.drums.wav"},
                        {"stem": "bass", "path": "song.bass.wav"}, {"stem": "other", "path": "song.other.wav"}]}}

Without -y ferraus never downloads anything; it stops with exit code 5 and prints the exact command that fetches the model:

{"ok": false, "error": {"code": "model_not_cached",
  "message": "model is not cached and downloads are disabled: separate/htdemucs@v4-onnx.2026-05-21",
  "hint": "ferraus models pull separate/htdemucs@v4-onnx.2026-05-21", "exit_code": 5}}

2. Separate

ferraus separate song.wav --tier fast -y --json

warning: downloading separate/htdemucs@v4-onnx.2026-05-21 (165.6 MB, license MIT)

{"ok": true, "command": "separate",
 "outputs": [{"path": "song.vocals.wav", "role": "vocals"}, {"path": "song.drums.wav", "role": "drums"},
             {"path": "song.bass.wav", "role": "bass"}, {"path": "song.other.wav", "role": "other"}],
 "models": [{"name": "separate/htdemucs", "version": "v4-onnx.2026-05-21", "sha256": "d05c269d..."}],
 "metrics": {"quality_vocals": 0.018, "quality_drums": 0.901, "quality_bass": 0.516, "quality_other": 0.869},
 "result": {"sum_to_mix": {"applied": true, "target": "other", "residual_peak_db": -15.3, "clipped": 0}, ...}}

The model is cached after the first run (ferraus models list --cached), and later runs work offline. On an Apple-silicon laptop a 21-second song takes about 5 seconds on the CPU.

Listen to each stem:

• vocals: the voice alone. Expect some cymbal "wash" and reverb tails from other parts (bleed); a little is normal.
• drums: kick, snare, and cymbals. Listen for vocal "s" sounds leaking in.
• bass: should be solid in the low end; very low synth parts sometimes land in other.
• other: everything else (guitars, keys, pads, synth leads).

The quality_* numbers are the model's own confidence per stem (0 to 1). Our test song is a synthesized instrumental, so quality_vocals is 0.018: there is no voice, and the lead synth went to other. A low score on a stem you know is present means that stem needs a careful listen.

3. The stems add back to the song

With --sum-to-mix on (the default) whatever the model missed goes into other, so the four files add back to the original exactly. You can check that:

ferraus mix song.vocals.wav song.drums.wav song.bass.wav song.other.wav -o sum.wav
ferraus compare song.wav sum.wav

{"rms_diff_db": -240.0, "si_sdr_db": 200.0, "identical": true, "verdict": "identical"}

4. Common variations

ferraus separate song.wav --tier fast --stems 2 --outdir two         # vocals + instrumental
ferraus separate song.wav --tier fast --instrumental --outdir karaoke # one file with the vocals removed
ferraus separate song.wav --tier fast --only drums,bass --outdir rhythm
ferraus separate song.wav --tier fast --stems 6 --outdir six         # adds guitar and piano
ferraus separate song.wav --tier fast --drum-split --outdir kit      # drums → kick, snare, toms, cymbals

two/song.vocals.wav  two/song.instrumental.wav
karaoke/song.instrumental.wav
rhythm/song.drums.wav  rhythm/song.bass.wav
six/song.vocals.wav  six/song.drums.wav  six/song.bass.wav  six/song.guitar.wav  six/song.piano.wav  six/song.other.wav
kit/song.vocals.wav ... kit/song.kick.wav  kit/song.snare.wav  kit/song.cymbals.wav  kit/song.toms.wav

--stems 2 --tier quality runs only the RoFormer vocal model, so a clean karaoke track costs about two thirds of a full quality run. --drum-split downloads the DrumSep model (335 MB) on first use; it has no separate hi-hat output (hi-hats land in cymbals), and --dry-run lists the extra outputs before anything runs.

--outdir keeps each run's files apart; without it, a second run stops with output_exists instead of overwriting (pass --overwrite to replace).

5. Long songs, agents, and batches

Separation is the slowest command in ferraus. Memory does not grow with the song: models run one at a time over the song window by window, the song is decoded and the stems are written block by block, and an hour-long input spills its intermediate signals to temporary files (removed afterwards) so it stays under 4 GB (measured on a laptop: 1.5 GB for fast, 2.8 GB for quality). A larger --max-memory keeps everything in memory, which on a laptop CPU is no faster. Run long jobs in the background and collect the result later:

ferraus separate song.wav --tier fast --outdir stems --async --json

{"ok": true, "job_id": "1792400395782-593d"}

ferraus jobs status 1792400395782-593d   # state, percent
ferraus jobs wait 1792400395782-593d     # blocks, then prints the separate result

What next

• Make a remix from the stems: Stems for a remix.
• Transcribe a stem to MIDI (ferraus transcribe song.bass.wav -o bass.mid), or notate it: Make a score.
• Tune the vocal stem: Tune a vocal.

Reference

separate · models list · models pull · compare · jobs wait

Tune a vocal

Pitch correction moves each sung note toward the nearest note of a key (or toward a written melody) while keeping the singer's tone. This walkthrough goes from "find out what key it is" to a natural correction, then the deliberate robotic effect. Outputs are trimmed copies of what ferraus 0.1.0 printed on a test take.

You need: a dry, solo vocal (vocal.wav): one voice, no backing track, little reverb. Pitch tracking follows one note at a time, so a vocal with music underneath gives poor results; split it out first with Split a song into stems.

Making a test take. macOS can sing: say -v Cellos -o sung.aiff "la la la la la la". Convert it and push it out of tune by 35 cents so there is something to correct:

ferraus convert sung.aiff -o sung48.wav --sample-rate 48000
ferraus pitch sung48.wav --cents 35 -o vocal.wav

1. Listen and look at the pitch

Listen for: notes that sound sour against where the song sits, especially long held notes and the ends of phrases. Then look at what the pitch tracker hears:

ferraus analyze pitch vocal.wav -o curve.csv --json

{"ok": true, "command": "analyze pitch",
 "metrics": {"voiced_fraction": 0.9908, "notes": 12},
 "result": {"summary": {"tracker": "pyin", "voiced_fraction": 0.9908, "median_hz": 104.8854, "median_note": "G#2", ...},
            "notes": [{"start_s": 0.01, "end_s": 0.35, "midi": 39.2647, "note": "D#2", ...}, ...]}}

curve.csv has one row per 10 ms (time_s,freq_hz,midi,confidence,voiced,rms) and opens in any spreadsheet. A midi value of 39.26 means the note is 26 cents sharp of D#2.

2. Find the key

ferraus analyze key vocal.wav --method notes

warning: key confidence 0.32 is below 0.6; 'Bb minor' is only a best guess

{"key": "Bb minor", "confidence": 0.315, "alternatives": [{"key": "Bb major", ...}, {"key": "A major", ...}],
 "method": "notes", "reliable": false}

--method notes works from the sung notes, which suits a solo vocal; the default (chroma) suits a full mix. A short phrase rarely contains enough notes to pin down a key, which is what this warning says. If you know the song's key, always pass it; if you have the full mix, run ferraus analyze key song.wav on the mix instead.

3. Correct it

With no options, tune detects the key and corrects every note fully. When the key confidence is below 0.6 it falls back to the chromatic scale (every semitone is a valid target) and tells you, so nothing is pulled to a wrong key:

ferraus tune vocal.wav --notes-out notes.json -o vocal.tuned.wav --json

warning: key detection confidence 0.32 is below 0.6 (best guess Bb minor); correcting to the chromatic scale. Pass --key to choose the key

{"ok": true, "command": "tune",
 "params": {"key": "Bb minor (detected, confidence 0.32; not used)", "scale": "chromatic", "strength": "100%", "retune_speed": "25ms", ...},
 "metrics": {"notes": 12, "corrected_notes": 12, "mean_abs_deviation_cents": 21.49, "max_abs_deviation_cents": 27.02, "resynthesis": "td_psola"}}

notes.json lists every note with what was heard and where it was moved:

{"start_s": 0.01, "end_s": 0.35, "note": "D#2", "detected_hz": 78.98, "target_note": "D#2", "deviation_cents": -26.47, "confidence": 0.67}

Listen for: held notes now sit in tune, and the voice still sounds like the same person. Listen hard at note changes: a "warble" or a step in the middle of a slide means the correction is too fast for this singer.

When you know the key, give it, and back the correction off so the performance keeps some life:

ferraus tune vocal.wav --key C --scale major --strength 80% --retune-speed 60ms -o vocal.gentle.wav

• --strength 80% moves each note 80% of the way to its target.
• --retune-speed 60ms glides into the correction instead of snapping (0 ms snaps).
• Vibrato is left alone by default (--vibrato-preserve on), so a wobble on a long note is not flattened.
• --humanize 20% adds a few cents of slow random drift if a fully corrected take sounds sterile; it is seeded by --seed, so the result is reproducible.

4. Tune to a written melody

If you have the melody as MIDI (from a songwriter's demo, or from ferraus transcribe of a guide vocal), tune each note to the written note rather than the nearest note of a scale:

ferraus tune vocal.wav --target melody.mid --tolerance 100cents --notes-out notes.json -o vocal.tuned.wav

Notes more than --tolerance away from the written note are left alone and reported, so an intentional blue note or ad-lib is not dragged somewhere it was never meant to go.

5. The hard-tune effect

ferraus tune vocal.wav --effect hard --key C -o vocal.robot.wav

--effect hard sets an instant retune, full strength, and no humanize: the stepped, "robotic" sound used as a deliberate effect in pop and hip-hop. Listen for: clean jumps between notes with no glide.

Noisy or breathy takes

The built-in tracker (pYIN) is good on clean takes. On breathy, quiet, or noisy takes a neural tracker can follow the pitch better. They download once with -y:

ferraus tune vocal.wav --tracker crepe -y --key C -o vocal.crepe.wav      # CREPE tiny, 2 MB
ferraus tune vocal.wav --tracker swiftf0 -y --key C -o vocal.swift.wav    # SwiftF0, 135 kB

Compare metrics.notes and the notes.json reports between trackers: on our synthetic test take CREPE split the line into 24 notes where pYIN found 12, so more notes is not always better. Pick the one whose notes match what you hear.

Reference

tune · analyze pitch · analyze key · pitch · transcribe

Batch podcast cleanup

Clean and level a whole folder of episodes in one call. Every command takes several inputs or a glob, processes each file the same way, and returns one envelope with a result per file. Run with ferraus 0.1.0; JSON is trimmed.

episodes/ep01.wav   episodes/ep02.wav   episodes/ep03.flac

1. Measure them all

ferraus analyze loudness "episodes/*.wav" "episodes/*.flac" --json

{"ok": true, "command": "analyze loudness",
 "inputs": [{"path": "episodes/ep01.wav", ...}, {"path": "episodes/ep02.wav", ...}, {"path": "episodes/ep03.flac", ...}],
 "result": [
   {"input": "episodes/ep01.wav", "metrics": {"integrated_lufs": -16.4262, "loudness_range_lu": 1.7741, "true_peak_dbtp": -1.8811, ...}, "result": {...}},
   {"input": "episodes/ep02.wav", "metrics": {"integrated_lufs": -22.4262, ...}, "result": {...}},
   {"input": "episodes/ep03.flac", ...}]}

Quote globs so ferraus expands them (the same on every shell, including PowerShell). Name the extensions: a bare "episodes/*" also matches the .ferraus.json sidecars that ferraus writes beside its outputs. Each of those becomes a failed item with unsupported_format, and because one item failed, the envelope's top-level ok is false and the exit code is 4, even though every audio file succeeded. In a batch, result[] has one entry per input; failed entries carry "ok": false and an error object, so check each entry.

2. Clean, level, and normalize in one pass per file

ferraus fx "episodes/*.wav" "episodes/*.flac" --fx dehum --fx "denoise:auto" --fx leveler \
  --fx "enhance-voice:mode=female" --fx "normalize:lufs=-16" --outdir clean --json

{"ok": true, "command": "fx",
 "outputs": [{"path": "clean/ep01.fx.wav"}, {"path": "clean/ep02.fx.wav"}, {"path": "clean/ep03.fx.flac"}],
 "result": [{"input": "episodes/ep01.wav", "metrics": {"freq_hz": 60.001, "hum_reduction_db": 16.7, "noise_floor_db": -81.2, ...}}, ...]}

• --outdir clean is required for a batch unless -o is a template. Outputs keep the input name plus the command (ep01.fx.wav) and the input's format.
• Use an -o template for other names: -o 'clean/{name}.wav' ({name} is the input file's stem, {index} its position in the batch, {ext} its extension).
• denoise:auto learns the noise of each file separately, and params.noise_region per item says where. Check that each landed on a pause.

If you only need the loudness step (the "normalize every episode to -16 LUFS" job):

ferraus normalize "episodes/*.wav" --lufs -16 --outdir loud --json

--dry-run shows the output names first:

{"ok": true, "command": "normalize", "dry_run": true,
 "outputs": [{"path": "loud/ep01.normalize.wav"}, {"path": "loud/ep02.normalize.wav"}],
 "params": {"lufs": "-16", "ceiling": "-1dBTP", "true_peak_limit": "on", ...}}

3. Verify against the podcast spec

ferraus master verify "clean/*.wav" "clean/*.flac" --target podcast --json

{"ok": false, "result": [
  {"input": "clean/ep01.fx.wav", "ok": false, "error": {"code": "verification_failed",
   "message": "clean/ep01.fx.wav fails the podcast spec: loudness: integrated loudness -16.00 LUFS is +3.00 LU from the -19 LUFS target",
   "hint": "ferraus master clean/ep01.fx.wav --target podcast -o fixed.wav", "exit_code": 9}}, ...]}

These episodes are mono, and the podcast spec is -16 LUFS for stereo but -19 LUFS for mono (a mono file plays from both speakers, which sounds about 3 dB louder). Either normalize mono episodes to -19 (--fx "normalize:lufs=-19") or make them stereo (--channels 2 on the fx run) and keep -16.

4. Encode for publishing

ferraus convert "clean/*.wav" --format mp3 --bitrate 128k --outdir mp3 --json

mp3/ep01.fx.convert.mp3   mp3/ep02.fx.convert.mp3

5. Long batches

Run the batch in the background and collect it later:

ferraus fx "episodes/*.wav" --fx dehum --fx "normalize:lufs=-16" --outdir clean --async --json   # {"ok": true, "job_id": "..."}
ferraus jobs wait <job_id> --json

Re-running the same command skips files whose output already exists with a matching sidecar (warning reused_output, "result": {"reused": true}), so an interrupted batch can simply be started again. To recompute anyway, pass --force --overwrite (--force alone stops at the existing file with output_exists).

Clean, tune, and master a vocal

An agent recipe: take a raw vocal take and a backing track to a mastered song, deciding each step from the JSON the previous step returned. Every command below was run with ferraus 0.1.0; JSON is trimmed to the fields an agent reads. Add --json to every call and read ok, error.hint, warnings, and metrics.

Inputs: take.wav (dry mono vocal), beat.wav (instrumental).

1. Diagnose

ferraus analyze problems take.wav --json

{"ok": true, "command": "analyze problems",
 "metrics": {"high": 0, "medium": 0, "low": 0, "clean": true},
 "result": {"clean": true, "counts": {"high": 0, "medium": 0, "low": 0},
            "problems": [{"problem": "hum", "severity": "medium", "details": "...", "suggested_fix": "dehum:freq=60Hz"}]}}

Decide: build the cleanup chain from result.problems[].suggested_fix (each is an fx stage string). If clean is true and problems is empty, skip cleanup: do not denoise a take that has no noise. On a clean, digitally silent take denoise --auto learns "noise" from silence and still turned the level down by about 6 dB in our test (output_rms_dbfs -26.3 vs input_rms_dbfs -20.1), so only run it when the report names hiss or noise.

ferraus fx take.wav -o take.clean.wav --fx "dehum:freq=60Hz" --fx "denoise:auto" --fx "highpass:freq=80Hz" --json

Read back params.noise_region (where the noise was learned; it must be a pause) and metrics.removed_rms_dbfs (should be far below input_rms_dbfs).

2. Find the key and tune

Prefer the key of the full song, measured on the beat (polyphonic material gives a reliable chroma estimate):

ferraus analyze key beat.wav --json

{"ok": true, "command": "analyze key",
 "metrics": {"confidence": 0.595},
 "warnings": [{"code": "low_key_confidence", "message": "key confidence 0.59 is below 0.6; 'C major' is only a best guess"}],
 "result": {"key": "C major", "tonic": "C", "mode": "major", "confidence": 0.595, "correlation": 0.823,
            "alternatives": [{"key": "G major", "correlation": 0.774}, {"key": "A minor", ...}]}}

Decide: if result.confidence is at least 0.6, pass result.tonic and result.mode. Here it is 0.595 with a low_key_confidence warning, and the runners-up are the neighbouring key (G major) and the relative minor (A minor), which share most notes with C major. An agent should ask the user, or check with ferraus analyze chords beat.wav (this song's chords are C, Am, F, G: C major). Without --key, tune falls back to the chromatic scale by itself and warns with the same code.

ferraus tune take.clean.wav --key C --scale major --strength 85% --retune-speed 30ms --notes-out notes.json -o take.tuned.wav --json

{"ok": true, "command": "tune",
 "params": {"key": "C", "scale": "major", "strength": "85%", "retune_speed": "30ms", ...},
 "metrics": {"notes": 14, "corrected_notes": 14, "mean_abs_deviation_cents": 49.44, "max_abs_deviation_cents": 83.77, "resynthesis": "td_psola"}}

Check: a mean_abs_deviation_cents near 50 means notes sit between two scale notes and may be pulled to the wrong one; open notes.json and look at deviation_cents and confidence per note. Notes with large deviation and low confidence are tracking errors: lower --strength, try --tracker crepe -y, or tune to a written melody with --target melody.mid.

3. Vocal effects

ferraus presets list compress --json        # vocal, drums, bus, master, tighten
ferraus fx take.tuned.wav -o take.fx.wav --fx "compress:preset=vocal" --fx deess --fx "reverb:type=plate,mix=18%" --json

4. Mix with the beat

ferraus mix take.fx.wav beat.wav --gains 0dB,-6dB -o song.mix.wav --json

{"ok": true, "command": "mix",
 "result": {"duration_s": 21.2, "channels": 2, "sample_rate": 48000,
            "inputs": [{"path": "take.fx.wav", "gain_db": 0.0, "pan": null, "offset_s": 0.0},
                       {"path": "beat.wav", "gain_db": -6.0, "pan": null, "offset_s": 0.0}]}}

Use --offsets 0s,2b (with --bpm) to start the vocal later, and --pans to place parts.

5. Master and verify

ferraus master song.mix.wav --target streaming -o song.master.wav --report report.json --json

{"ok": true, "command": "master",
 "metrics": {"integrated_lufs": -14.01, "true_peak_dbtp": -1.05, "limiter_gain_reduction_db": 1.68,
             "target_reached": true, "verify_pass": true}}

stderr may show warning: the result peaks at +0.55 dBFS and will clip in fixed-point formats from inner stages; those stages run in floating point, and the final file is what true_peak_dbtp and verify_pass describe.

Decide: if target_reached is false, the warnings array says why (for example, the limiter bound of --intensity), with the flag that fixes it. Confirm independently:

ferraus master verify song.master.wav --target streaming --json

Exit code 0 and "ok": true mean every check passed; exit code 9 lists failed_checks, each with a fix string.

The same job as one file

The whole recipe is also a pipeline file, which caches every stage so re-running after a change recomputes only what changed. Over MCP, the server's clean-and-tune-vocal prompt walks a model through these steps (MCP setup).

FFmpeg equivalents

Every ferraus command on this page was run against ferraus 0.1.0.

ferraus does common audio jobs natively, so an agent or person who already knows FFmpeg can translate directly. Anything not listed here still works through the pass-through: ferraus ffmpeg -- <the same ffmpeg arguments> (the exact command line is recorded in the JSON envelope and sidecar). ferraus ffmpeg -- -h prints FFmpeg's own help.

Global flags map the same way everywhere: -ar → --sample-rate, -ac → --channels, -b:a → --bitrate, -sample_fmt s16 → --bit-depth 16, -y → --overwrite, -f wav - (stdout) → -o -.

Conversion and encoding

Inspecting

Editing

Channels

Filters

Video containers

Getting FFmpeg

The bridge looks for FERRAUS_FFMPEG (or ffmpeg.path in the config), then the managed build in the ferraus cache, then ffmpeg on PATH. ferraus doctor --install-ffmpeg downloads a pinned, SHA-256-verified static build (LGPL builds on Linux and Windows; the macOS build is GPL) and shows its license; ferraus doctor reports which binary is in use.

Hum to an instrument

An agent recipe: turn a hummed idea into a rendered instrument part, check the notes, and fix them without asking the user to hum again. Run with ferraus 0.1.0; JSON is trimmed. The plain-language version is the tutorial.

1. Transcribe and inspect

Transcribe first instead of calling hum directly: the note list is what you check.

ferraus transcribe idea.wav -o idea.mid --json

{"ok": true, "command": "transcribe",
 "outputs": [{"path": "idea.mid"}, {"path": "idea.notes.json", "role": "notes"}],
 "params": {"bpm": "99.84 (audio)", "key": "A minor (confidence 0.91; snapped)", "mode": "mono", ...},
 "metrics": {"notes": 11, "tempo_confidence": 1.0, "mean_note_confidence": 0.995, "polyphonic_fraction": 0.022},
 "result": {"mode": "mono", "engine": "pyin", "notes": 11, "bpm": 99.84, "key": "A minor", "key_confidence": 0.91,
            "key_snapped": true, "notes_snapped": 0, "pitch_range": ["A4", "E5"],
            "polyphony": {"monophonic": true, ...}, "output": "idea.mid", "notes_output": "idea.notes.json"}}

idea.notes.json:

{"ferraus_notes": 1, "source": "idea.wav", "mode": "mono", "bpm": 99.84, "key": "A minor",
 "notes": [{"start_s": 0.01, "end_s": 0.6197, "duration_s": 0.6097, "start_beats": 0.0167,
            "pitch": 76, "name": "E5", "velocity": 92, "confidence": 0.993, ...}, ...]}

Checks an agent can make:

• result.polyphony.monophonic false: the recording has chords or background music; use --mode poly or separate the voice first.
• Fewer notes than the user expects, with long duration_s: repeated notes merged. Re-run with --onset-sensitivity 100% (in our test: 11 notes at 50%, 13 at 90%, all 16 at 100%).
• Many very short notes: a wobbly hum split into fragments. Lower --onset-sensitivity or raise --min-note 120ms.
• Low confidence on a note: ask the user about that note, or drop it.

2. Render

ferraus hum idea.wav --to piano --onset-sensitivity 100% -o idea-piano.wav --json

{"ok": true, "command": "hum",
 "outputs": [{"path": "idea-piano.mid", "role": "midi"}, {"path": "idea-piano.wav", "duration_s": 11.77}],
 "result": {"notes": 16, "bpm": 99.84, "key": "A minor", "quantize_grid": "1/16", "quantize_strength": 0.8,
            "render": {"instrument": "builtin:piano", "plan": [{"source": {"type": "built_in", "name": "piano"}, "notes": 16}]}}}

result.render.instrument says what actually played the part. builtin:* means no sound bank is installed; ferraus sounds install gm-basic -y (31 MB, free license) makes every General MIDI name play a sampled instrument.

3. Edit the MIDI, not the audio

To fix notes, convert the MIDI to JSON, edit it, and convert it back:

ferraus midi to-json idea-piano.mid -o idea.json
# edit tracks[0].notes[i].pitch / name / beat / duration_beats
ferraus midi from-json idea.json -o idea-fixed.mid
ferraus render idea-fixed.mid --instrument strings -o idea-strings.wav

Minimal JSON is enough for from-json; positions can be beat (wins), tick, or time_s:

{"tempo_map": [{"beat": 0, "bpm": 100}],
 "tracks": [{"notes": [{"beat": 0, "duration_beats": 1, "name": "C4", "velocity": 100}]}]}

Other one-step edits: midi transpose --semitones -12, midi quantize --grid 1/8 --strength 100%, midi velocity --set 90, midi legato, midi tempo --set 92.

Over MCP, the hum-to-instrument prompt guides a model through the same steps.

MCP setup and a tool call

ferraus mcp serve exposes every command as a Model Context Protocol tool, so an AI client (Claude Code, Claude Desktop, Cursor, or any MCP client) can edit audio without a shell. This page sets it up and shows a complete session as it ran against ferraus 0.1.0. Background: MCP concepts.

Set it up

Claude Code:

claude mcp add ferraus -- ferraus mcp serve --allow ~/music

Any client that reads an mcpServers config (Claude Desktop's claude_desktop_config.json, Cursor's mcp.json, ...):

{"mcpServers": {"ferraus": {"command": "ferraus", "args": ["mcp", "serve", "--allow", "/Users/me/music"]}}}

--allow is the sandbox: every input and output must be inside an allowed directory (repeat the flag for more; the default is the current directory). Use an absolute path in JSON configs, since ~ is not expanded there.

A session

The server speaks JSON-RPC 2.0 over stdio, one message per line. This is the exchange a client performs, trimmed:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"docs-test","version":"0"}}}

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18",
 "capabilities":{"tools":{"listChanged":false},"resources":{"subscribe":false,"listChanged":false},"prompts":{"listChanged":false},"logging":{}},
 "serverInfo":{"name":"ferraus","title":"ferraus audio toolkit","version":"0.1.0"},
 "instructions":"ferraus edits, repairs, separates, tunes, transcribes, and masters audio. Every tool returns the ferraus JSON envelope ..."}}

tools/list returns 175 tools: one per command (ferraus_<command>, spaces become underscores) plus ferraus_job_start, ferraus_job_status, ferraus_job_result, and ferraus_job_cancel. Each tool's inputSchema is the command's argument schema (ferraus schema <command>):

{"name": "ferraus_fx", "title": "ferraus fx",
 "description": "Apply a chain of effects in order in one pass\n\n...\n\nCLI equivalent: ferraus fx take.wav -o clean.wav --fx \"denoise:auto\" ...",
 "inputSchema": {"type": "object", "required": ["inputs"], "additionalProperties": false,
                 "properties": {"inputs": {"type": "array", "items": {"type": "string"}, "minItems": 1, ...},
                                "output": {"type": "string", ...}, "fx": {...}, ...}}}

A tool call: arguments use the flag names with _ for -, inputs go in inputs, the output path in output.

{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"ferraus_normalize",
 "arguments":{"inputs":["episodes/ep02.wav"],"lufs":"-16","output":"ep02.mcp.wav"}}}

{"jsonrpc":"2.0","id":4,"result":{
 "content":[{"type":"text","text":"{\"ok\":true,\"command\":\"normalize\", ...}"}],
 "structuredContent":{"ok":true,"command":"normalize",
   "inputs":[{"path":"/Users/me/music/episodes/ep02.wav","duration_s":13.5,"sample_rate":48000,"channels":1}],
   "outputs":[{"path":"/Users/me/music/ep02.mcp.wav","duration_s":13.5}],
   "params":{"lufs":"-16","ceiling":"-1dBTP","true_peak_limit":"on","mode":"lufs","target_lufs":-16.0, ...},
   "metrics":{"before":{"integrated_lufs":-22.43,"true_peak_dbtp":-7.88},"gain_db":6.43,
              "after":{"integrated_lufs":-16.0,"true_peak_dbtp":-1.45}}}}}

structuredContent is the same envelope --json prints on the command line; content[0].text carries it as text for clients that do not read structured content. Relative paths resolve against the first --allow directory. When a call names no output, results go to ferraus-out/ inside it.

List values can be JSON arrays: {"inputs": ["vox.wav", "beat.wav"], "gains": ["0dB", "-6dB"]} is the same as --gains 0dB,-6dB.

A path outside the sandbox is refused, and the error is a normal envelope with "isError": true:

{"jsonrpc":"2.0","id":5,"result":{"isError":true,"structuredContent":{"ok":false,"command":"gain",
 "error":{"code":"path_not_allowed","message":"/etc/hosts is outside the allowed directories",
          "hint":"allowed: /Users/me/music","exit_code":2}}, ...}}

Long jobs

Separation, mastering, and batches can take minutes. Start them as jobs:

{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"ferraus_job_start",
 "arguments":{"tool":"ferraus_separate","arguments":{"inputs":["song.wav"],"tier":"fast"}}}}

The result's structuredContent is {"job_id": "job-1", "state": "running"}; poll ferraus_job_status with {"job_id": "job-1"}, then fetch ferraus_job_result, or stop it with ferraus_job_cancel. Jobs live as long as the server process. Calls that carry an MCP progress token also receive notifications/progress.

Resources and prompts

resources/list returns ferraus://catalog, ferraus://presets, ferraus://models, ferraus://plugins, and ferraus://sounds; the templates ferraus://docs/{command}, ferraus://schema/{command}, ferraus://presets/{effect}, and ferraus://jobs/{id} read one item. prompts/list returns clean-and-tune-vocal, extract-stems-for-remix, hum-to-instrument, and master-song, which walk a model through the recipes in this cookbook.

HTTP instead of stdio

ferraus mcp serve --http 127.0.0.1:8765 --allow ~/music

Clients POST JSON-RPC to http://127.0.0.1:8765/mcp. Requests with a browser Origin other than localhost are refused.

Pipeline files

A pipeline file describes a whole job (inputs, stages, outputs) in one YAML or JSON document. ferraus pipeline run executes it, caches every stage by content hash, and on a re-run recomputes only the stages whose inputs or arguments changed. It is the reproducible form of a multi-step recipe, and the easiest way for an agent to hand a person a job they can re-run. Run with ferraus 0.1.0; JSON is trimmed.

The file

# job.yaml: clean a vocal take, tune it, put it over a beat, and master the bounce
version: 1
inputs:
  vocal: vocal.wav
  beat: beat.wav
stages:
  - id: clean
    op: denoise
    in: vocal
    args: { auto: true, reduction: 12dB }
  - id: tuned
    op: tune
    in: clean
    args: { key: C, scale: major, strength: 85%, retune_speed: 30ms }
  - id: vox_fx
    op: fx
    in: tuned
    args:
      chain:
        - { op: compress, preset: vocal }
        - { op: deess }
        - { op: reverb, type: plate, mix: 18% }
  - id: mix
    op: mix
    in: [vox_fx, beat]
    args: { gains: [0dB, -6dB] }
  - id: master
    op: fx
    in: mix
    args:
      chain:
        - { op: normalize, lufs: -14 }
        - { op: limit, ceiling: -1dBTP }
outputs:
  - { from: master, path: out/song.wav, bit_depth: 24 }
  - { from: tuned, path: out/vocal_tuned.wav }

Rules:

• op is any command name (denoise, tune, separate, midi quantize, ...) and args keys are its flags with _ instead of - (retune_speed for --retune-speed). A flag without a value is true (auto: true).
• in names an input or an earlier stage's id. A stage with several outputs (separate) is addressed as id.role, for example stems.vocals.
• A list value (gains: [0dB, -6dB]) is the same as the comma list on the command line (--gains 0dB,-6dB).
• fx stages take chain, a list of {op, ...args}.
• outputs[] choose which stage results are written. The format follows the extension, and each output can set bit_depth, sample_rate, and bitrate (other keys are ignored in this release; convert channels in a stage, for example {op: channels, to: mono}).

Validate and explain

ferraus pipeline validate job.yaml

{"valid": true, "order": ["clean", "tuned", "vox_fx", "mix", "master"],
 "stages": [{"id": "clean", "op": "denoise", "in": ["vocal"],
             "args": {"auto": "true", "reduction": "12dB", "mode": "profile", "sensitivity": "6", ...}}, ...],
 "outputs": [{"from": "master", "path": "out/song.wav", "bit_depth": 24}, {"from": "tuned", "path": "out/vocal_tuned.wav"}]}

pipeline explain job.yaml prints the same plan with every default filled in. Both catch unknown ops, unknown or invalid arguments, unknown references, and cycles before anything runs. pipeline run job.yaml --dry-run --json returns the same plan plus the output paths it would write, and refuses outputs that already exist unless --overwrite is given.

Run

ferraus pipeline run job.yaml --json

{"ok": true, "command": "pipeline run",
 "outputs": [{"path": "out/song.wav", "role": "master", "duration_s": 21.2}, {"path": "out/vocal_tuned.wav", "role": "tuned"}],
 "result": {"pipeline": "job.yaml", "plan": [
   {"id": "clean", "op": "denoise", "cached": false, "timing_ms": 99, "key": "21a95ab8...",
    "result": {"mode": "profile", "noise_region": {"range": "0.085s..1.077s", "method": "auto"}}},
   {"id": "tuned", "op": "tune", "cached": false, "result": {"key": "C major", "scale": "C major"}},
   {"id": "mix", "op": "mix", "args": {"gains": "0dB,-6dB", ...},
    "result": {"inputs": [{"gain_db": 0.0}, {"path": "beat.wav", "gain_db": -6.0}]}}, ...]}}

out/job.ferraus.json records the resolved plan and timings, and each output gets its own sidecar.

Change one thing and re-run

--set overrides any field without editing the file (stages are addressed by id):

ferraus pipeline run job.yaml --set stages.tuned.args.strength=100% --overwrite --json

Only tuned and the stages after it run again; clean reports "cached": true (and a stage whose arguments match an earlier run, even an interrupted one, is reused too). Other overrides: --set inputs.vocal=take2.wav, --set outputs.0.path=out/song_v2.wav, or a whole replacement chain as JSON (--set 'stages.master.args.chain=[{"op":"normalize","lufs":-16}]'). --no-cache recomputes everything.

Outputs are never overwritten without --overwrite, so the second run above needs it. Give it, or change every output path: outputs are written in order, and a run that stops at an existing file has already written the outputs listed before it.

Sheet music to a performance

An agent recipe: take a notation file, validate it, fix problems in the score model, and render a performance. Run with ferraus 0.1.0; JSON is trimmed. The plain-language version is the tutorial.

Printed scores (PDF or page images) go through score read first; the steps below then apply to its MusicXML. Recognition needs the two oemer models (MIT, about 110 MB; pass -y or run ferraus models pull omr/oemer omr/oemer-seg once), and PDFs need pdftoppm or mutool on PATH (macOS sips reads the first page only).

0. Recognize a printed score

ferraus score read minuet.pdf -o minuet.musicxml --review --json -y

{"ok": true, "command": "score read",
 "models": [{"name": "omr/oemer", "version": "checkpoints-2021-11-25", "sha256": "37512e85..."},
            {"name": "omr/oemer-seg", "version": "checkpoints-2021-11-25", "sha256": "ed2e1a86..."}],
 "warnings": [],
 "result": {"engine": "builtin", "parts": 1, "measures": 16, "check_ok": true, "failing_measures": [],
            "recognition": {"pages": [1], "rasterizer": "pdftoppm", "staff_space_px": [13.8], "issues": []},
            "review": {"ok": true, "notes": 77,
                       "issues": [{"severity": "warning", "code": "unsupported", "message": "lyrics and text are not read"}, ...,
                                  {"severity": "info", "code": "low_confidence", "part": "P1", "measure": 10,
                                   "message": "confidence 0.50: duration doubled to fill the measure"}],
                       "low_confidence": [{"part": "P1", "measure": 10, "confidence": 0.5,
                                           "reasons": ["duration doubled to fill the measure"]}]}}}

Decide:

• check_ok: false with failing_measures: those measures' durations do not add up. Look at them with score to-json and fix them (step 2).
• review.low_confidence: measures the reader was unsure about, with the reason. duration doubled / halved / dot added to fill the measure means a duration was corrected so the measure adds up; check that note against the page. uncertain notehead means the network was unsure; check the pitch.
• recognition.issues (also in warnings as omr_issue): page-level doubts, such as a time signature that was inferred from the measures instead of read.
• The unsupported warnings are always present for the builtin engine: lyrics, tuplets, grace notes, ties, slurs, dynamics, articulations, repeats, and a second voice on a staff are not read. A score that relies on them needs fixing by hand (or --engine audiveris).

1. Validate

ferraus score check tune.abc --json

{"ok": true, "command": "score check",
 "result": {"ok": true, "errors": 0, "warnings": 0, "parts": 1, "measures": 8, "notes": 30,
            "issues": [], "failing_measures": []}}

Decide: if failing_measures is not empty, each issue names the measure, voice, and what is wrong (for example, a measure whose durations do not add up to the time signature). Fix those before performing; --strict turns warnings into a failing exit code.

2. Read and edit the score model

ferraus score to-json tune.abc -o tune.score.json

{"version": 1, "title": "Ode to Joy (excerpt)", "composer": "Beethoven", "divisions": 2,
 "parts": [{"id": "P1", "name": "Voice 1", "program": 0,
   "staves": [{"number": 1, "measures": [{"number": 1, "key": {"fifths": 2, "mode": "major"},
     "time": {"beats": 4, "beat_type": 4}, "clef": {"sign": "G", "line": 2}, "tempo": [{"offset": 0, "bpm": 96.0}],
     "voices": [{"number": 1, "events": [
       {"duration": 2, "notes": [{"pitch": {"step": "F", "alter": 1, "octave": 4}, "midi": 66}], "dynamic": "mf"}, ...]}]}]}]}]}

duration is in divisions per quarter note (here 2, so 2 = a quarter note). Edit pitches, durations, dynamics, or the tempo, then write it back:

ferraus score from-json tune.score.json -o tune.fixed.musicxml

For a few targeted corrections, an edit list is shorter than the whole model:

ferraus score read tune.musicxml --fix edits.json -o tune.fixed.musicxml --review

where edits.json is [{"measure": 4, "voice": 1, "note": 1, "set": {"pitch": "F#4"}}].

3. Perform

ferraus score perform tune.abc --instrument piano -o tune.wav --json

{"ok": true, "command": "score perform",
 "outputs": [{"path": "tune.musicxml", "role": "musicxml"}, {"path": "tune.mid", "role": "midi"},
             {"path": "tune.wav", "role": "audio", "duration_s": 22.0}],
 "result": {"engine": "none (abc input)",
            "performance": {"duration_s": 20.0, "notes": 30, "measures_played": 8, "order": [1, 2, 3, 4, 5, 6, 7, 8], "tempo_bpm": 96.0, "tracks": 1},
            "render": {"instrument": "builtin:piano", ...}}}

Checks: performance.order is the measure sequence after unrolling repeats and endings; compare it with the form you expect. performance.tempo_bpm is the tempo used (--tempo overrides the score). render.instrument shows what played it.

Variations: --instrument-map "P1=piano,P2=strings" per part, --humanize 30% --seed 7 for a less mechanical but reproducible take, --swing 50%, --click on for a metronome track, ferraus score play for the MIDI alone.

Stems for a remix

An agent recipe: split a song into stems, move them to a new tempo and key, process each stem, mix a remix, cut loops, and master it loud for a DJ set. Run with ferraus 0.1.0 on a 21-second, 100 BPM test song; JSON is trimmed.

1. Separate

ferraus separate song.wav --tier fast -y --json

{"ok": true, "command": "separate",
 "outputs": [{"path": "song.vocals.wav", "role": "vocals"}, {"path": "song.drums.wav", "role": "drums"},
             {"path": "song.bass.wav", "role": "bass"}, {"path": "song.other.wav", "role": "other"}],
 "metrics": {"quality_vocals": 0.018, "quality_drums": 0.901, "quality_bass": 0.516, "quality_other": 0.869},
 "result": {"stems": [{"stem": "vocals", "path": "song.vocals.wav", "quality": {"score": 0.018, "method": "mask_confidence", "calibrated": false}}, ...],
            "sum_to_mix": {"applied": true, "target": "other", "residual_peak_db": -15.3}}}

Decide: read result.stems[].quality.score; skip or flag stems that score low (this test song has no vocals, hence 0.018). This recipe uses --tier fast for speed; the default --tier auto picks quality (RoFormer vocals, about 9× slower; see Stems and separation tiers), worth it when the vocal is the hook of the remix, and --tier balanced sits in between (about 4× slower). For a long song, add --async and poll ferraus jobs wait <job_id> --json; memory stays bounded however long the song is. Need the kit apart for a flip? Add --drum-split for kick, snare, toms, and cymbals stems.

2. Measure tempo and key

ferraus analyze tempo song.drums.wav --json      # result.bpm: 100.0, result.confidence: 1.0
ferraus analyze key song.other.wav --json        # result.key: "C major", result.confidence: 0.623

Tempo is most reliable on the drum stem and key on the harmonic stem ("other" or "piano").

3. New tempo and key

ferraus stretch song.drums.wav --bpm 100 --to-bpm 110 -o remix/drums110.wav --json
ferraus stretch song.bass.wav --bpm 100 --to-bpm 110 -o remix/bass110.wav
ferraus stretch song.other.wav --bpm 100 --to-bpm 110 -o remix/other110.wav
ferraus pitch remix/bass110.wav --semitones 2 -o remix/bass110-up2.wav
ferraus pitch remix/other110.wav --semitones 2 -o remix/other110-up2.wav

{"ok": true, "command": "stretch", "metrics": {"factor": 0.9091, "engine": "hybrid", "transients": 64, "anchored_transients": 64}}

stretch keeps pitch and pitch keeps duration. Do not pitch-shift the drums: they have no key, and shifting them changes their character. anchored_transients equal to transients means every drum hit stayed sharp.

4. Process each stem

ferraus fx remix/drums110.wav --fx "saturate:type=tape,drive=6dB" --fx "highpass:freq=40Hz" -o remix/drums-fx.wav
ferraus fx remix/other110-up2.wav --fx chorus --fx "delay:time=1/8D,feedback=35%,mix=25%" --bpm 110 -o remix/other-fx.wav

Beat-based values (1/8D, a dotted eighth) need --bpm with the new tempo.

5. Mix

ferraus mix remix/drums-fx.wav remix/bass110-up2.wav remix/other-fx.wav --gains 0dB,-2dB,-4dB --pans 0,0,+20 -o remix/remix.wav --json

{"ok": true, "command": "mix", "metrics": {"peak_db": -9.27, "duration_s": 19.27}}

6. Cut loops

ferraus split remix/remix.wav --every 4b --bpm 110 -o 'remix/loops/loop{stem}.wav' --json

{"ok": true, "command": "split",
 "outputs": [{"path": "remix/loops/loop001.wav", "role": "001", "duration_s": 2.179},
             {"path": "remix/loops/loop002.wav", "role": "002", "duration_s": 2.183}, ...]}

In an output template, {stem} is each part's role (001, 002, ...) and {index} is the position of the input in a batch, so use {stem} to number the parts of one file. Without -o, --outdir loops names them remix.001.wav, remix.002.wav, .... Split points snap to the nearest zero crossing within 5 ms (--snap off for exact samples), which is why the loops are a few samples apart in length.

7. Master for a DJ set

ferraus master remix/remix.wav --target club --genre edm -o remix/remix.master.wav --json

{"ok": true, "command": "master",
 "metrics": {"integrated_lufs": -13.15, "true_peak_dbtp": -0.32, "limiter_gain_reduction_db": 4.0,
             "target_reached": false, "verify_pass": false},
 "warnings": [{"code": "target_not_reached", "message": "landed at -13.2 LUFS, 5.2 LU short of the -8.0 LUFS target: --intensity medium allows at most 4 dB of limiter gain reduction and reaching the target needs more. Use --intensity heavy, or accept the quieter master"},
              {"code": "verify_failed", "message": "master verify failed: loudness: integrated loudness -13.15 LUFS is -5.15 LU from the -8 LUFS target"}]}

Decide: target_reached: false with a target_not_reached warning that names the fix. Either re-run with --intensity heavy (more limiting, less punch) or accept -13 LUFS. ferraus never limits harder than the intensity allows on its own.

Global options

Every command accepts these. Command-specific options are listed on each command's page.

Exit codes

JSON results and provenance sidecars

The result envelope

With --json, every command prints exactly one JSON object on stdout:

{
  "ok": true,
  "command": "separate",
  "ferraus_version": "0.1.0",
  "schema_version": 1,
  "inputs": [{"path": "song.wav", "duration_s": 21.2, "sample_rate": 48000, "channels": 2}],
  "outputs": [{"path": "song.vocals.wav", "role": "vocals", "duration_s": 21.2, "sample_rate": 48000, "channels": 2}],
  "params": {"stems": "4", "tier": "fast", "overlap": "25%", "sum_to_mix": "on", "execution_provider": "cpu"},
  "models": [{"name": "separate/htdemucs", "version": "v4-onnx.2026-05-21", "sha256": "d05c269d..."}],
  "metrics": {"quality_vocals": 0.018, "quality_drums": 0.901},
  "warnings": [],
  "result": {"stems": [...], "tier": "fast"},
  "timing_ms": 11065
}

params holds every parameter after defaults and presets, plus values resolved at run time (a detected key, the noise region chosen by --auto). Errors use the same envelope with "ok": false and an error object: code (stable snake_case), message, hint (a runnable command when one exists), and exit_code.

With several inputs (a list or a glob), result is an array with one entry per input: {"input": "...", "metrics": {...}, "result": {...}}, or {"input": "...", "ok": false, "error": {...}} for an input that failed. If any input failed, the top-level ok is false and the exit code is that input's, so check every entry.

In examples throughout these docs, ... marks fields left out for brevity.

ferraus schema <command> prints the JSON Schema (draft 2020-12) of a command's arguments and of its result. schema_version increments only on breaking changes.

Progress events

--progress json writes NDJSON to stderr:

{"event":"progress","stage":"separate","percent":0.0,"eta_s":null}
{"event":"stage_start","stage":"separate/htdemucs@v4-onnx.2026-05-21","index":1,"of":1}
{"event":"progress","stage":"separate","percent":45.0,"eta_s":9}
{"event":"output","path":"prog/song.vocals.wav","role":"vocals"}
{"event":"warning","code":"low_key_confidence","message":"..."}

Sidecars

Each output gets <output>.ferraus.json recording the command, argv, resolved parameters, input and output SHA-256 hashes, models with hashes, plugins and their state, host, whether the run was deterministic, and timing. The sidecar of ferraus transcribe idea.wav -o idea.mid:

{
  "ferraus_version": "0.1.0",
  "schema_version": 1,
  "command": "transcribe",
  "argv": ["transcribe", "idea.wav", "-o", "idea.mid", "--json"],
  "params": {"bpm": "99.84 (audio)", "mode": "mono", "tracker": "pyin", "key": "A minor (confidence 0.91; snapped)", "...": "..."},
  "inputs": [{"path": "idea.wav", "sha256": "932ac21f...", "duration_s": 10.07}],
  "outputs": [{"path": "idea.mid", "sha256": "1a746192..."},
              {"path": "idea.notes.json", "sha256": "0c5d9a3e...", "role": "notes"}],
  "models": [],
  "plugins": [],
  "host": {"os": "macos", "arch": "aarch64", "device": "auto", "threads": 10},
  "deterministic": true,
  "warnings": [],
  "timing_ms": 89
}

Values resolved at run time (the detected tempo and key above) are recorded, so a replay uses the same values even if detection would change. --no-sidecar skips the file.

• ferraus replay <sidecar> re-runs the recorded command with the recorded parameters. Deterministic commands reproduce the output bit-exactly on the same machine.

• ferraus verify <sidecar> checks that inputs and outputs still match their hashes:

  {"verified": true, "files": [
    {"kind": "input", "path": "episodes/ep01.wav", "expected": "2cae956e...", "actual": "2cae956e...", "match": true},
    {"kind": "output", "path": "clean/ep01.wav", "expected": "cd52fcf3...", "actual": "cd52fcf3...", "match": true}]}
  

• If an output exists and its sidecar matches the command, parameters, inputs, and version, ferraus returns the existing result instantly (warning reused_output, "result": {"reused": true}). To recompute, pass --force --overwrite. replay also needs --overwrite (or -o to a new path) when the recorded output still exists.

• Attach the sidecar when you report a bug: it is everything needed to reproduce the run.

Loudness standards

ferraus measures loudness with ITU-R BS.1770-4 / EBU R128: K-weighted, gated integrated loudness in LUFS (loudness units relative to full scale), short-term (3 s) and momentary (400 ms) loudness, loudness range (LRA, in LU), and true peak in dBTP (measured after 4x oversampling, so it catches peaks between samples).

• ferraus analyze loudness song.wav reports every measure; --timeline adds curves.
• ferraus normalize song.wav --lufs -14 reaches a target within 0.3 LU and never exceeds the true-peak ceiling (a lookahead limiter catches overshoot).
• ferraus master mix.wav --target streaming does tonal balance, dynamics, stereo, and loudness.

Louder is not better on streaming services: they turn loud masters down, so excessive limiting only costs dynamics.

Using ferraus from AI agents (MCP)

ferraus runs as a Model Context Protocol server. Every command is a tool named ferraus_<command> (spaces and hyphens become underscores: ferraus_denoise_profile, ferraus_enhance_voice), with the same argument schema as ferraus schema <command> and the JSON envelope as its result (in structuredContent, and as text in content). ferraus 0.1.0 lists 175 tools. A complete session is in the MCP setup and tool-call recipe.

Claude Code

claude mcp add ferraus -- ferraus mcp serve --allow ~/music

Other clients (stdio)

{"mcpServers": {"ferraus": {"command": "ferraus", "args": ["mcp", "serve", "--allow", "/Users/me/music"]}}}

HTTP

ferraus mcp serve --http 127.0.0.1:8765 --allow ~/music

Clients POST JSON-RPC to http://127.0.0.1:8765/mcp. Requests with a browser Origin other than localhost are refused.

Sandbox

Every read and write must be inside an --allow directory (default: the current directory). Relative paths are resolved against the first allowed directory, and when a tool call names no output, results go to ferraus-out/ there.

Tool arguments

{"inputs": ["takes/vocal.wav"], "key": "auto", "strength": "85%", "output": "vocal.tuned.wav"}

Global options allowed inside arguments: overwrite, dry_run, force, bpm, sample_rate, bit_depth, channels, bitrate, format, outdir, seed, deterministic.

Long jobs

ferraus_job_start {"tool": "ferraus_separate", "arguments": {...}} returns a job_id; poll ferraus_job_status, fetch ferraus_job_result, or ferraus_job_cancel. Calls that carry a progress token also receive notifications/progress.

Resources and prompts

Resources: ferraus://catalog, ferraus://presets, ferraus://models, ferraus://plugins, ferraus://sounds, and templates ferraus://presets/{effect}, ferraus://jobs/{id}, ferraus://docs/{command}, ferraus://schema/{command}.

Prompts: clean-and-tune-vocal, extract-stems-for-remix, hum-to-instrument, master-song.

Notation and solfa

ferraus score turns audio or MIDI into notation and ferraus score read / score perform go the other way. MusicXML is the hub format. Readable inputs: MusicXML (.musicxml, .xml, .mxl), MEI, ABC, LilyPond, MIDI, and the ferraus score JSON; outputs add SVG, PDF, and PNG pages (through the ferraus-engrave helper or LilyPond) and sol-fa text or Markdown. Printed music (PDF, PNG, JPEG) goes through optical music recognition (score read): oemer's segmentation networks (MIT, downloaded once) and ferraus's own reconstruction read clean printed scores; see Perform a sheet-music file for what is and is not read.

• Lead sheet: melody on a treble staff, chord symbols above, lyrics below.

• Grand staff: treble and bass clefs for piano, with a hand split (--split auto or a note such as C4).

• Drum score: percussion clef with the standard drum map (kick in the bottom space, snare in the third space, hi-hat and cymbals as x noteheads above the staff).

• Solfa: tonic sol-fa with movable do (d r m f s l t), octave marks, and Curwen rhythm punctuation; --solfa on prints syllables under the staff, --solfa only writes sol-fa text and no staff, --solfa fixed uses fixed do (do = C). A minor key is written with its relative major's doh, so the tonic is l (lah). From ferraus score melody.mid --solfa only:

  Key: Doh is C (A minor, lah is A)
  Time: 4/4
  Tempo: 100 bpm
  
  |m :r :d :r |m :m :m :d |d :t, :l, :t, |d :d :l, :l, ||
  

  : separates beats, | bars, and a comma after a syllable (t,) puts it an octave below.

• Chord symbols: C, Am7, G/B (slash chords carry the bass); --chords diagrams adds guitar fretboard diagrams.

Every note carries a confidence and every measure an aggregate; low-confidence measures are listed with the reason so you (or an agent) know which bars to check.

Walkthroughs: Make a score and Perform a sheet-music file.

Pan laws and stereo placement

When a mono source moves between speakers, its perceived loudness changes unless the gains follow a pan law. ferraus uses constant power by default.

Positions run from -100 (hard left) through 0 (center) to +100 (hard right); left, center, right, L30, R60 also work.

• pan --mode pan places a mono (or mono-summed) source. --mode balance scales the channels of a stereo source instead, keeping its image.
• Movement: pan --points 0s=-100,4s=0,8s=100 --curve spline or --from -100 --to 100 --over 0s..end.
• Cyclic movement: autopan --rate 1/2 (beats) or --rate 0.5Hz.
• While mixing: mix vox.wav gtr.wav keys.wav --gains 0dB,-3dB,-6dB --pans 0,-40,+40.
• widen --amount 130% --mono-below 120Hz widens the image but keeps the bass mono.

Sound folders and instrument switching

Instruments come from four places:

• the sounds registry: free instruments ferraus downloads, verifies, and installs (ferraus sounds search piano, ferraus sounds install gm-basic -y);
• folders you point at with --sound-path <dir> (repeatable), the FERRAUS_SOUND_PATH environment variable, or [sounds] paths in the config: SoundFonts (.sf2), SFZ libraries, impulse responses, and plugins;
• the standard CLAP and VST3 plugin folders (ferraus plugin scan);
• the built-in preview synth, which needs no files, so rendering always works.

ferraus sounds list shows what is installed and found; ferraus sounds list --path <dir> shows what one folder contains; ferraus sounds scan <dir> indexes a large folder once so later lookups are fast.

How a name is resolved

render --instrument, render --map, hum --to, and score perform --instrument resolve a name in this order:

1. an alias (ferraus sounds alias piano=salamander-grand-piano);
2. an installed or --sound-path SoundFont or SFZ library whose name or category matches (strings finds Strings.sf2);
3. a General MIDI program name or number ("String Ensemble 1", Flute, gm:48, or a family such as ensemble), played by the gm-basic SoundFont when it is installed, otherwise by the built-in synth;
4. an explicit source: sf2:<path>[@bank:program], sfz:<path>, builtin:<timbre> (piano, strings, organ, lead, bass, pad, bell, brass, guitar), or plugin:"Name".

Plugin instruments are always named with plugin:"Name" (for example --instrument 'plugin:"Surge XT"'): in this release a plugin's plain name is not matched in step 2, even though sounds list shows scanned plugins.

An ambiguous name lists the candidates with a runnable hint for each; an unknown one fails with exit code 2 and the hint ferraus sounds list.

ferraus render part.mid --instrument strings -o part.strings.wav
ferraus render song.mid --map "1=piano,2=strings,10=drums" -o song.wav
ferraus render song.mid --swap piano=strings -o song.wav
ferraus render part.mid --sound-path ~/my-sounds --instrument strings -o part.wav
ferraus hum idea.wav --to ensemble -o idea.wav

The resolved instrument (file, program, plugin id, preset) is recorded in the JSON result and the sidecar, so a render is reproducible even if aliases or folders change later:

{"instrument": {"given": "Flute", "via": "gm", "program": 73, "program_name": "Flute",
                "source": {"type": "sf2", "path": ".../sounds/gm-basic/GeneralUser-GS.sf2", "preset": {"bank": 0, "program": 73}}}}

See Host a plugin for plugins and sounds install.

Stems and separation tiers

ferraus separate splits a mix into stems: 2 (vocals, instrumental), 4 (vocals, drums, bass, other), or 6 (adds guitar and piano). The models are neural networks from the ferraus model registry, run through ONNX Runtime on the CPU or a GPU.

Tiers

A tier is a named recipe of registry models. This table is what ferraus separate --dry-run plans and ferraus models list --task separate reports:

Every model in every tier has a recorded SHA-256 and a pinned download URL, so all four tiers work. The RoFormer's training data is not disclosed by its author (its weights are MIT); ferraus models list shows each entry's license note.

• --stems 6 uses htdemucs-6s in every tier (136 MB, MIT). Guitar and piano are best-effort quality.
• --stems 2 runs only the models that produce vocals; the instrumental is the mix minus the vocals (exactly, with --sum-to-mix on).
• --model <name or .onnx file> pins one model instead of a tier; --ensemble a,b --weights 0.6,0.4 builds your own ensemble from registry models.
• Several registry entries (bs-roformer-viperx-1297, bs-roformer-sw, scnet-xl, mdx-kim-vocal-2, mdx-kara-2) are listed with the flag no_clear_license and belong to no tier; --model with --accept-license uses one explicitly.

The default tier is auto: the best tier whose models are all verified and that the registry does not hold back (a tier's auto_skip field), tried in the order quality → balanced → fast. With this release's registry auto means quality, and the result records "tier": "quality (auto)". A registry whose better tiers lack verified models falls back to balanced or fast and says so in a tier_fallback warning (ADR 0007).

Quality

Separation quality is measured as SDR (signal-to-distortion ratio, in dB; higher is better). Published Multisong results put fine-tuned Demucs v4 at about 8.4 dB on vocals and Kimberley Jensen's Mel-Band RoFormer at about 11 dB. On the first 12 MUSDB18 test excerpts (the 7-second CC BY 4.0 set; the RoFormer's training data is unknown, so it may have heard them) ferraus measured the median SI-SDR per stem, in dB:

SI-SDR is scale-invariant SDR against the true stems; MUSDB18's published SDR figures use a different metric (BSSEval), so compare tiers with each other rather than with papers. The quality tier beats balanced on vocals by 2.9 dB here; max adds about 0.2 dB on vocals and up to 0.4 dB elsewhere for about 5 times the work.

The fast tier is good enough for practice tracks, karaoke, and remix sketches; expect some bleed (cymbals in the vocal, reverb tails in the wrong stem). quality gives clearly cleaner vocals; drums, bass, and other come from the same fine-tuned Demucs models as balanced.

Each stem's JSON result carries a quality estimate between 0 and 1 (mask confidence for a single model, agreement between models for an ensemble). It is not calibrated to SDR, but a low value flags a stem to check by ear. A stem that is absent from the mix (no vocals in an instrumental) scores near 0.

Speed and memory

Measured on an M1 Pro laptop's CPU (10 cores) with a 4-minute song, at the default --max-memory 2GB (details and method in docs/dev/PERFORMANCE.md):

Separation runs the models one at a time and streams each over the song window by window; the input is decoded straight into that stream and every stem is encoded block by block, so memory does not grow with the song: a 60-minute input stays under 4 GB in every tier (measured: fast 1.5 GB, balanced 1.6 GB, quality 2.8 GB). Long inputs spill their intermediate signals to temporary files (removed afterwards, also on error or cancel). When a model's own working memory exceeds --max-memory, ferraus loads it in a leaner mode (on a laptop CPU it is as fast as the full one); result.memory reports the plan (spilled, lean_sessions, fits). The quality tier's RoFormer needs about 2.8 GB on its own, so that tier goes over a 2 GB budget and says so with "fits": false. A supported GPU (ferraus accelerate install, see Troubleshooting) helps most for quality and max.

Options that matter

• --sum-to-mix on (default) assigns whatever the models missed to other, so the stems add back to the original exactly: ferraus mix of the four stems against the input gives "verdict": "identical" in ferraus compare.
• --only vocals,drums writes only those stems; --instrumental writes one file without the vocals.
• --drum-split splits the drum stem into kick, snare, toms, and cymbals with DrumSep (a hybrid Demucs fine-tune, MIT; hi-hats land in cymbals). --extended guitar,piano takes guitar and piano out of other with htdemucs-6s. Each cascade output carries a quality flag, and --dry-run lists the cascade stages with their models and outputs.
• --vocal-split splits the vocal stem into song.lead.wav and song.backing.wav. No lead/backing model has a clear license, so the default is built in (separate/melody-mask, nothing to download): it tracks the lead's pitch, keeps the energy on the lead's harmonics, sends other voices' harmonics to the backing, weights stereo input toward the centre, and makes backing = vocals − lead, so the two add back to the vocal stem. It is best effort ("method": "melody_mask"): it cannot pull apart a harmony in unison or at the octave, it takes a backing part that sings alone for the lead, and it warns when the pitch track is unreliable (vocal_split_pitch_unreliable) or the stem has little backing (vocal_split_little_backing). On synthetic test mixes it improved the lead by about 1 dB SI-SDR on mono input and 3–4 dB on stereo input with panned backing. --vocal-split-tracker crepe|swiftf0 uses a model pitch tracker instead of pYIN. --cascade-models vocal-split=<model> runs a separation model instead: an ONNX file of your own, or the UVR karaoke model separate/mdx-kara-2 (no license stated for its weights; never used by default; it needs --accept-license once and warns on every use).
• --overlap 25% and --segment auto control the processing windows; --shifts 2 adds test-time augmentation (slower, slightly cleaner).
• Models download on first use with -y, or pull them first: ferraus models pull --all-for separate --tier quality. ferraus models list --cached shows what is on disk.

See the tutorial and the remix recipe.

Units and parsing

Every value on the command line, in fx strings, in pipeline files, and in MCP arguments is parsed by the same unit parser, so 1.5s, -6dB, C4, and 1/8T mean the same thing everywhere.

Time

Ranges use ..: --range 0s..2s, --range 1:00..end, --range ..30s (from the start), --range -10s..end (the last ten seconds). In a beat range, give the tempo once with --bpm 120 --range 0b..4b; an @120 suffix applies only to the end it is written on.

Gain

-6dB, +3dB, -6 (dB), 0.5x (a linear factor), -14LUFS (integrated loudness, for normalize and mastering targets), -1dBTP (true peak, measured with 4x oversampling).

Frequency and pitch

120Hz, 2.5kHz, note names C4 (middle C, 261.63 Hz), A#3, Bb2, MIDI numbers midi:60. Pitch offsets: 20cents, +200cents, 2st (semitones).

Ratios and percentages

4:1 or 4. 80% or the fraction 0.8; 130% is 1.3. A bare number is a fraction, so 80 means 8000%, not 80%: always write the %.

Musical grid

1/16, 1/8T (triplet: two thirds of an eighth), 1/8D (dotted: one and a half eighths). Delay times also accept grids (--time 1/4), resolved against --bpm or the detected tempo.

Sizes and bitrates

2GB, 512MB; 192k, 320kbps.

When parsing fails

You get exit code 2 and a message naming the flag, the value, and what was expected:

error: --threshold: cannot parse gain 'loud': expected a number with dB, x, LUFS, or dBTP

ferraus info

Probe a file: container, codec, duration, rate, channels, bit depth, bitrate, tags, art

Synopsis

ferraus info <input> [options] [-o <output>]

What it does

Reads the container header (and, for video files, lists every stream) without decoding the audio. Add --loudness for an EBU R128 measurement (integrated loudness, loudness range, true peak) or --spectrum for 1/3-octave band averages; both decode the file in a streaming pass.

Examples

Container, codec, duration, sample rate, channels, bit depth, bitrate, tags

ferraus info song.flac

Integrated loudness, LRA, and true peak as JSON

ferraus info mix.wav --loudness --json

Audio track of a video file plus a 1/3-octave spectrum

ferraus info interview.mp4 --spectrum

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.

For models

• MCP tool: ferraus_info
• Schema: ferraus schema info
• Pipeline: { op: info, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "info", "defaults": {}}

ferraus tags

Read and write metadata tags and cover art

Synopsis

ferraus tags <input> [options] [-o <output>]

What it does

With no options, prints the file's tags and embedded pictures. --set key=value (repeatable), --remove key, --art cover.jpg, and --clear modify tags; writing needs --in-place (keeps <file>.bak) or -o for a tagged copy. Keys: title, artist, album, album_artist, date, year, genre, track, track_total, disc, disc_total, comment, composer, bpm, copyright, encoder, lyrics, label, publisher, isrc, conductor, lyricist, language, key, mood.

Examples

Show title, artist, album and embedded art

ferraus tags song.mp3

Edit tags in place (song.flac.bak is kept)

ferraus tags song.flac --set title="Blue Hour" --set artist=Nadia --in-place

Write a copy with cover art

ferraus tags song.m4a --art cover.jpg -o tagged.m4a

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.

For models

• MCP tool: ferraus_tags
• Schema: ferraus schema tags
• Pipeline: { op: tags, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "tags", "defaults": {}}

ferraus waveform

Export a waveform image (PNG, SVG) or JSON peaks

Synopsis

ferraus waveform <input> [options] [-o <output>]

What it does

Draws the waveform as a PNG or SVG image, or writes min/max peaks per time bucket and channel as JSON for web players and agents. The format follows the output extension (.png by default, .svg, .json). Images show the peak envelope with the RMS level drawn darker inside it.

Examples

1200x200 PNG thumbnail

ferraus waveform song.wav -o song.png

Peaks for a web player, 20 buckets per second

ferraus waveform episode.mp3 -o peaks.json --peaks-per-second 20

SVG with one lane per channel

ferraus waveform stereo.wav --split --width 800 --height 300 -o wave.svg

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.

For models

• MCP tool: ferraus_waveform
• Schema: ferraus schema waveform
• Pipeline: { op: waveform, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "waveform", "defaults": {"width": "1200", "height": "200", "peaks_per_second": "50", "color": "#1f6feb", "background": "transparent"}}

ferraus spectrogram

Export a spectrogram as a PNG image or JSON matrix

Synopsis

ferraus spectrogram <input> [options] [-o <output>]

What it does

Computes a short-time Fourier transform of the mono mix (Hann window) and writes it as a PNG (time left to right, low frequencies at the bottom) or as JSON (dB values per frame and bin, 0 dB = loudest point, floored at -db-range). --mel 128 groups the bins into 128 mel bands, which matches hearing and is what ML models expect; --mel 0 keeps linear FFT bins.

Examples

128-band mel spectrogram image

ferraus spectrogram song.wav -o song_spec.png

Linear-frequency matrix in JSON for analysis

ferraus spectrogram voice.wav --mel 0 --fft 4096 --hop 256 -o voice_spec.json

Fixed-size image with 60 dB range

ferraus spectrogram drums.wav --width 1200 --height 300 --db-range 60 -o drums.png

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.
• Gains need a unit when not in dB: 0.5x is a factor, -6 and -6dB are decibels.

For models

• MCP tool: ferraus_spectrogram
• Schema: ferraus schema spectrogram
• Pipeline: { op: spectrogram, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "spectrogram", "defaults": {"fft": "2048", "hop": "512", "mel": "128", "db_range": "80dB", "fmin": "0Hz", "width": "0", "height": "0"}}

ferraus analyze tempo

Tempo, beat times, downbeats, and time signature

Synopsis

ferraus analyze tempo <input> [options] [-o <output>]

What it does

Onset strength (spectral flux on a log-mel spectrogram) is autocorrelated and scored on a comb of metrical levels with a perceptual prior around 120 BPM; beats are placed by dynamic programming (Ellis 2007) and the tempo is refined through the beat times. Downbeats are reported only when the bar accent pattern is clear.

Examples

BPM, confidence, and beat times

ferraus analyze tempo song.wav --json

Search only fast tempi

ferraus analyze tempo dnb.wav --range 140..190

Keep a slow ballad from being read at double time

ferraus analyze tempo ballad.wav --range 50..100 --json

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.

For models

• MCP tool: ferraus_analyze_tempo
• Schema: ferraus schema analyze tempo
• Pipeline: { op: analyze tempo, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "analyze tempo", "defaults": {"range": "60..200"}}

ferraus analyze loudness

EBU R128 loudness: integrated, short-term, momentary, range, true peak

Synopsis

ferraus analyze loudness <input> [options] [-o <output>]

What it does

Integrated loudness with absolute (-70 LUFS) and relative (-10 LU) gates, maximum short-term (3 s) and momentary (400 ms) loudness, loudness range (EBU Tech 3342), 4x-oversampled true peak, and sample peak. --timeline adds the momentary and short-term curves, like a loudness meter or radar.

Examples

Integrated LUFS, LRA, and true peak

ferraus analyze loudness master.wav --json

Loudness curve every second

ferraus analyze loudness mix.wav --timeline --step 1s

Save the loudness report of a podcast episode for a delivery check

ferraus analyze loudness episode.mp3 --json > loudness.json

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.
• Beat-based times (4b, 1/4) need a tempo: pass --bpm or write 4b@120.

For models

• MCP tool: ferraus_analyze_loudness
• Schema: ferraus schema analyze loudness
• Pipeline: { op: analyze loudness, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "analyze loudness", "defaults": {"step": "100ms"}}

ferraus analyze silence

List silent regions with start, end, and floor level

Synopsis

ferraus analyze silence <input> [options] [-o <output>]

What it does

List silent regions with start, end, and floor level

Examples

Pauses longer than a second

ferraus analyze silence podcast.wav --threshold -50dB --min 1s

Silent regions with the defaults (-40 dB, at least 300 ms)

ferraus analyze silence take.wav --json

Short gaps in a quiet field recording

ferraus analyze silence field.wav --threshold -60dB --min 100ms --json

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.
• Beat-based times (4b, 1/4) need a tempo: pass --bpm or write 4b@120.
• Gains need a unit when not in dB: 0.5x is a factor, -6 and -6dB are decibels.

For models

• MCP tool: ferraus_analyze_silence
• Schema: ferraus schema analyze silence
• Pipeline: { op: analyze silence, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "analyze silence", "defaults": {"threshold": "-40dB", "min": "300ms"}}

ferraus analyze spectrum

Long-term average spectrum in fractional-octave bands or FFT bins

Synopsis

ferraus analyze spectrum <input> [options] [-o <output>]

What it does

Welch-averaged spectrum of all channels. Band levels are in dB relative to a full-scale sine (a 0 dBFS sine in a band reads 0 dB). Also reports the spectral centroid, 85% rolloff, flatness, and strongest frequency.

Examples

Third-octave levels from 20 Hz to 20 kHz

ferraus analyze spectrum mix.wav --json

Finer sixth-octave bands to find a resonance

ferraus analyze spectrum vocal.wav --resolution 1/6oct --json

Raw FFT bins, for example to locate a hum line exactly

ferraus analyze spectrum hum.wav --resolution bins --json

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.

For models

• MCP tool: ferraus_analyze_spectrum
• Schema: ferraus schema analyze spectrum
• Pipeline: { op: analyze spectrum, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "analyze spectrum", "defaults": {"resolution": "1/3oct"}}

ferraus analyze clipping

Count and locate clipped runs

Synopsis

ferraus analyze clipping <input> [options] [-o <output>]

What it does

A clipped run is at least --min-run consecutive samples at or above --threshold with the same polarity. Flat-topped runs below the threshold (audio clipped and then turned down) are reported with kind 'flat'.

Examples

Clipped runs with channel and time

ferraus analyze clipping take.wav --json

Count near-full-scale runs of two or more samples in a loud master

ferraus analyze clipping master.wav --threshold -0.1dB --min-run 2 --json

Report every sample at full scale, even single ones

ferraus analyze clipping old_transfer.wav --min-run 1

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.
• Gains need a unit when not in dB: 0.5x is a factor, -6 and -6dB are decibels.

For models

• MCP tool: ferraus_analyze_clipping
• Schema: ferraus schema analyze clipping
• Pipeline: { op: analyze clipping, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "analyze clipping", "defaults": {"threshold": "0dBFS", "min_run": "3"}}

ferraus analyze chords

Chord sequence with times and confidence (best-effort)

Quality tier: best-effort. Results are reported with a quality or confidence estimate.

Synopsis

ferraus analyze chords <input> [options] [-o <output>]

What it does

Peak-picked chroma matched against harmonic-aware templates for major, minor, 7, maj7, m7, dim, sus4, and sus2 chords, with a bass-note cue for slash chords and Viterbi smoothing. Best-effort: reliable on clear harmonic material, approximate on dense mixes.

Examples

Chord labels such as C, Am7, G/B with times

ferraus analyze chords song.wav --json

Fewer, steadier chord changes on a strummed part

ferraus analyze chords guitar.wav --change-penalty 1.5 --json

Drop chord segments shorter than half a second and save the result

ferraus analyze chords piano.wav --min-duration 500ms --json > chords.json

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.
• Beat-based times (4b, 1/4) need a tempo: pass --bpm or write 4b@120.
• Treating best-effort output as final: check the reported quality/confidence in --json.

For models

• MCP tool: ferraus_analyze_chords
• Schema: ferraus schema analyze chords
• Pipeline: { op: analyze chords, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "analyze chords", "defaults": {"change_penalty": "0.5", "min_duration": "250ms"}}

ferraus analyze similarity

Spectral, cepstral, and loudness similarity between two files

Synopsis

ferraus analyze similarity <inputs...> [options] [-o <output>]

What it does

For agents checking whether a processed take drifted from the original: cosine similarity of the log third-octave spectra, MFCC distance, and loudness difference combined into a 0..1 score.

Examples

Score near 1 means the character is unchanged

ferraus analyze similarity original.wav processed.wav --json

Check that mastering kept the character of the mix

ferraus analyze similarity mix.wav master.wav --json

Compare two takes of the same part

ferraus analyze similarity take1.wav take2.wav

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.

For models

• MCP tool: ferraus_analyze_similarity
• Schema: ferraus schema analyze similarity
• Pipeline: { op: analyze similarity, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "analyze similarity", "defaults": {}}

ferraus compare

Null test: align b to a and report RMS and peak difference and SI-SDR

Synopsis

ferraus compare <inputs...> [options] [-o <output>]

What it does

b is aligned to a by FFT cross-correlation (within --max-offset), resampled and channel-matched if needed, then compared sample by sample: RMS and peak of the difference, null depth, best-fit gain, SI-SDR of b against a, and loudness difference. The agent's regression test.

Examples

Confirm nothing was damaged

ferraus compare mix.wav master_v1.wav --json

Sample-for-sample null test of a format round trip

ferraus compare original.wav roundtrip.wav --no-align --json

Allow up to five seconds of offset when the files start at different times

ferraus compare stem_sum.wav mix.wav --max-offset 5s

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.
• Beat-based times (4b, 1/4) need a tempo: pass --bpm or write 4b@120.

For models

• MCP tool: ferraus_compare
• Schema: ferraus schema compare
• Pipeline: { op: compare, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "compare", "defaults": {"max_offset": "1s"}}

ferraus analyze problems

Diagnose clipping, DC, clicks, hum, hiss, phase, silence, and more

Synopsis

ferraus analyze problems <input> [options] [-o <output>]

What it does

Each problem has a severity (low, medium, high), details, and a suggested fix that is a runnable command or fx stage, e.g. 'dc-remove', 'declip', 'highpass:freq=30Hz', or 'silence trim --edges'.

Examples

Diagnostics with suggested fixes

ferraus analyze problems take.wav --json

Apply two suggested fixes

ferraus fx take.wav -o fixed.wav --fx dc-remove --fx "highpass:freq=30Hz"

Only the medium and high severity problems

ferraus analyze problems interview.wav --min-severity medium --json

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.

For models

• MCP tool: ferraus_analyze_problems
• Schema: ferraus schema analyze problems
• Pipeline: { op: analyze problems, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "analyze problems", "defaults": {"min_severity": "low"}}

ferraus analyze stats

Per-channel peak, true peak, RMS, DC, crest factor, dynamic range

Synopsis

ferraus analyze stats <input> [options] [-o <output>]

What it does

Per-channel peak, true peak, RMS, DC, crest factor, dynamic range

Examples

Amplitude statistics with histograms

ferraus analyze stats take.wav --histogram on --json

Peak, true peak, RMS, DC offset, and crest factor per channel

ferraus analyze stats mix.wav --json

Save the statistics of a master as JSON

ferraus analyze stats master.wav --json > stats.json

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.

For models

• MCP tool: ferraus_analyze_stats
• Schema: ferraus schema analyze stats
• Pipeline: { op: analyze stats, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "analyze stats", "defaults": {"histogram": "off"}}

ferraus analyze stereo

Stereo image: correlation, width per band, mono compatibility

Synopsis

ferraus analyze stereo <input> [options] [-o <output>]

What it does

L/R correlation broadband and below 120 Hz, mid/side balance, width and correlation per band, and a 0..1 mono-compatibility score.

Examples

Check the mix folds to mono

ferraus analyze stereo mix.wav --json

Correlation and width per band printed for a person

ferraus analyze stereo master.wav

Save the stereo report after widening to check mono compatibility

ferraus analyze stereo widened.wav --json > stereo.json

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.

For models

• MCP tool: ferraus_analyze_stereo
• Schema: ferraus schema analyze stereo
• Pipeline: { op: analyze stereo, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "analyze stereo", "defaults": {}}

ferraus analyze pitch

Pitch curve as JSON or CSV

Synopsis

ferraus analyze pitch <input> [options] [-o <output>]

What it does

Frame-by-frame fundamental frequency (Hz, 0 when unvoiced), voicing confidence, voiced flag and RMS, plus segmented notes and a summary. Prints JSON in the result by default; with -o file.csv writes CSV, with -o file.json writes the JSON there.

Examples

Pitch curve and notes as JSON

ferraus analyze pitch vocal.wav --json

Write a 5 ms pitch curve as CSV

ferraus analyze pitch hum.wav --hop 5ms --range 80Hz..800Hz -o curve.csv

Track a bass line with a low range and save the JSON

ferraus analyze pitch bass.wav --range E1..G3 -o bass_pitch.json

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.
• Beat-based times (4b, 1/4) need a tempo: pass --bpm or write 4b@120.

For models

• MCP tool: ferraus_analyze_pitch
• Schema: ferraus schema analyze pitch
• Pipeline: { op: analyze pitch, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "analyze pitch", "defaults": {"tracker": "pyin", "hop": "10ms", "range": "60Hz..1.2kHz"}}

ferraus analyze key

Key and scale with confidence

Synopsis

ferraus analyze key <input> [options] [-o <output>]

What it does

Estimates the key and mode by correlating a chroma profile (from an STFT with tuning estimation) with Krumhansl-Schmuckler major and minor profiles. Reports the confidence (normalised margin over the best key with a different scale), the top-3 alternatives, the tuning offset and the chroma. --method notes uses a duration-weighted histogram of the tracked notes instead, which suits monophonic vocals.

Examples

Key, mode, confidence and alternatives

ferraus analyze key song.wav --json

Key of a solo vocal from its notes

ferraus analyze key vocal.wav --method notes

Key of a loop from its chroma, saved as JSON

ferraus analyze key loop.wav --method chroma -o key.json

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.

For models

• MCP tool: ferraus_analyze_key
• Schema: ferraus schema analyze key
• Pipeline: { op: analyze key, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "analyze key", "defaults": {"method": "chroma"}}

ferraus convert

Decode and re-encode between formats

Synopsis

ferraus convert <input> [options] [-o <output>]

What it does

Converts between WAV, AIFF, FLAC, Ogg Vorbis, Opus, MP3, and (through the FFmpeg bridge) M4A/AAC/ALAC. The output format follows the -o extension or --format. Lossless WAV/FLAC round trips are bit-exact at the same bit depth. When no resampling is needed the conversion streams packet by packet, so multi-hour files convert in constant memory. Source tags are copied to the output.

Examples

Lossless WAV to FLAC (bit-exact)

ferraus convert song.wav -o song.flac

FLAC to MP3 at about 256 kbps VBR

ferraus convert take.flac -o take.mp3 --bitrate 256k

Downsample and dither a 24-bit master to CD format

ferraus convert master.wav -o master-16.wav --bit-depth 16 --sample-rate 44100

Mono Opus for speech

ferraus convert podcast.wav -o podcast.opus --bitrate 64k --channels 1

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.

For models

• MCP tool: ferraus_convert
• Schema: ferraus schema convert
• Pipeline: { op: convert, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "convert", "defaults": {"vbr": "on", "dither": "triangular"}}

ferraus trim

Keep one time range of the input

Synopsis

ferraus trim <input> [options] [-o <output>]

What it does

Keeps the part of the input between the two ends of --range and drops the rest. By default each cut point moves to the nearest zero crossing (within 5 ms) so the new edges start and stop cleanly without a click; use --snap off for exact sample positions. --pad adds silence around the result. Times accept seconds, mm:ss, samples, beats (with --bpm), and negative values counted from the end.

This command is also an fx stage and a pipeline op: ferraus fx in.wav -o out.wav --fx "trim:key=value".

Examples

Keep 0:30 to 1:15, with click-free edges

ferraus trim song.wav --range 0:30..1:15 -o chorus.wav

Drop the first 2.5 seconds and add a quarter second of silence at each end

ferraus trim take.wav --range 2.5s..end --pad 250ms -o take_clean.wav

Keep exactly four bars at 128 BPM, sample-accurate

ferraus trim loop.wav --range 0b..16b --bpm 128 --snap off -o loop4bars.wav

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.
• Beat-based times (4b, 1/4) need a tempo: pass --bpm or write 4b@120.

For models

• MCP tool: ferraus_trim
• Schema: ferraus schema trim
• Pipeline: { op: trim, args: { ... } } (flag names with _ instead of -)
• fx stage: yes

{"command": "trim", "defaults": {"snap": "zero", "snap_window": "5ms"}}

ferraus cut

Remove one or more time ranges and join the rest

Synopsis

ferraus cut <input> [options] [-o <output>]

What it does

Deletes each --range and joins what is left with a short equal-power crossfade so the joins are seamless. The result is exactly as long as the input minus the removed time. Overlapping ranges are merged.

This command is also an fx stage and a pipeline op: ferraus fx in.wav -o out.wav --fx "cut:key=value".

Examples

Remove two stumbles and splice the rest seamlessly

ferraus cut interview.wav --range 1:02..1:09 --range 3:40..3:44 -o interview_edit.wav

Remove the first bar (four beats) of a 120 BPM song

ferraus cut song.wav --range 0s..4b --bpm 120 -o song_nointro.wav

Drop the pre-roll chatter and everything after 58:30 in one pass

ferraus cut lecture.wav --range 0s..12s --range 58:30..end -o lecture_core.wav

Hard splice with no crossfade, for an edit that lands exactly on a drum hit

ferraus cut drums.wav --range 2.5s..3s --crossfade 0ms -o drums_cut.wav

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.
• Beat-based times (4b, 1/4) need a tempo: pass --bpm or write 4b@120.

For models

• MCP tool: ferraus_cut
• Schema: ferraus schema cut
• Pipeline: { op: cut, args: { ... } } (flag names with _ instead of -)
• fx stage: yes

{"command": "cut", "defaults": {"crossfade": "10ms", "crossfade_curve": "equal-power"}}

ferraus split

Split a file into parts at times, at silences, or into equal chunks

Synopsis

ferraus split <input> [options] [-o <output>]

What it does

Writes one file per part, named <input>.001.<ext>, <input>.002.<ext>, ... (or from an -o template using {stem} for the part number). Split points come from --at (repeatable), --every (equal chunks), and/or --on-silence (the middle of each silent gap); several sources are combined. Points snap to zero crossings so no part starts or ends with a click. Nothing is lost: the parts join back into the input exactly.

Examples

Cut a long recording into 10-minute files

ferraus split podcast.wav --every 10:00 --outdir parts/

Split a vinyl side into tracks at the gaps (track001.flac, track002.flac, ...)

ferraus split side_a.flac --on-silence --min-silence 2s -o 'track{stem}.flac'

Split at two times and report the parts as JSON

ferraus split song.wav --at 0:45 --at 2:10 --json

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.
• Beat-based times (4b, 1/4) need a tempo: pass --bpm or write 4b@120.
• Gains need a unit when not in dB: 0.5x is a factor, -6 and -6dB are decibels.

For models

• MCP tool: ferraus_split
• Schema: ferraus schema split
• Pipeline: { op: split, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "split", "defaults": {"silence_threshold": "-40dB", "min_silence": "500ms", "snap": "zero"}}

ferraus concat

Join files end to end, optionally with crossfades or gaps

Synopsis

ferraus concat <inputs...> [options] [-o <output>]

What it does

Joins the inputs in the order given. --crossfade overlaps the end of each file with the start of the next (each overlap shortens the result by the crossfade length); --gap inserts silence instead. With --match on (the default) every input is resampled and remixed to the first file's sample rate and channel count.

Examples

Join three files back to back

ferraus concat intro.wav body.wav outro.wav -o episode.wav

DJ-style 3-second equal-power crossfade; b.mp3 is converted to a.flac's format

ferraus concat a.flac b.mp3 --crossfade 3s -o mix.flac

Join every take with a second of silence between them

ferraus concat take*.wav --gap 1s -o all_takes.wav

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.
• Beat-based times (4b, 1/4) need a tempo: pass --bpm or write 4b@120.

For models

• MCP tool: ferraus_concat
• Schema: ferraus schema concat
• Pipeline: { op: concat, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "concat", "defaults": {"crossfade": "0ms", "crossfade_curve": "equal-power", "gap": "0ms", "match": "on"}}

ferraus gain

Apply a fixed gain, overall or per channel

Synopsis

ferraus gain <input> [options] [-o <output>]

What it does

Makes the audio louder or quieter by a fixed amount, in decibels (-6dB) or as a factor (0.5x). Give per-channel values as L=-3dB,R=0dB (or 1=..,2=.. for any channel number; unlisted channels are unchanged), like Audition's Amplify. Warns when the result clips.

This command is also an fx stage and a pipeline op: ferraus fx in.wav -o out.wav --fx "gain:key=value".

Examples

Turn the vocal down 6 dB

ferraus gain vocal.wav --by -6dB -o vocal_quiet.wav

Pull the left channel down 1.5 dB

ferraus gain mix.wav --by L=-1.5dB,R=0dB -o mix_balanced.wav

Double the amplitude inside an effects chain

ferraus fx in.wav -o out.wav --fx gain:by=2x --fx fade:out=3s

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.

For models

• MCP tool: ferraus_gain
• Schema: ferraus schema gain
• Pipeline: { op: gain, args: { ... } } (flag names with _ instead of -)
• fx stage: yes

{"command": "gain", "defaults": {"by": "0dB", "mix": "100%"}}

ferraus normalize

Set loudness (LUFS), peak, or RMS level to a target

Synopsis

ferraus normalize <input> [options] [-o <output>]

What it does

Measures the input and applies the gain that lands it on the target. The default mode is integrated loudness per EBU R128 (--lufs -14, the usual streaming level). --peak -1dBTP normalizes the true (inter-sample, 4x oversampled) peak and --peak -1dB the sample peak; --rms -20dB the average level. Give one mode only. For --lufs and --rms, if the gain pushes the true peak over --ceiling a transparent lookahead true-peak limiter holds it under the ceiling (--true-peak-limit off disables that). Several inputs are normalized one by one to the same target (Match Loudness). Before and after measurements are reported as metrics.

This command is also an fx stage and a pipeline op: ferraus fx in.wav -o out.wav --fx "normalize:key=value".

Examples

Integrated loudness to -14 LUFS, true peak at most -1 dBTP

ferraus normalize song.wav -o song_streaming.wav

Match a batch of tracks to -16 LUFS

ferraus normalize ep/*.wav --lufs -16 --outdir matched/

Sample peak to -0.1 dBFS

ferraus normalize sample.wav --peak -0.1dB -o sample_max.wav

Broadcast loudness with a -2 dBTP ceiling and a JSON report

ferraus normalize vo.wav --lufs -23 --ceiling -2dBTP --json

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.
• Beat-based times (4b, 1/4) need a tempo: pass --bpm or write 4b@120.
• Gains need a unit when not in dB: 0.5x is a factor, -6 and -6dB are decibels.

For models

• MCP tool: ferraus_normalize
• Schema: ferraus schema normalize
• Pipeline: { op: normalize, args: { ... } } (flag names with _ instead of -)
• fx stage: yes

{"command": "normalize", "defaults": {"lufs": "-14", "true_peak_limit": "on", "ceiling": "-1dBTP", "lookahead": "3ms", "release": "80ms", "mix": "100%"}}

ferraus resample

Change the sample rate with a high-quality sinc resampler

Synopsis

ferraus resample <input> [options] [-o <output>]

What it does

Converts to a new sample rate with a windowed-sinc (Kaiser) resampler that keeps the audible band intact and removes everything above the new Nyquist frequency. Rates accept 48000, 48k, or 44.1kHz.

This command is also an fx stage and a pipeline op: ferraus fx in.wav -o out.wav --fx "resample:key=value".

Examples

Convert to 48 kHz for video

ferraus resample voice.wav --to 48k -o voice48.wav

Down-convert a 96 kHz master for CD

ferraus resample master96.flac --to 44.1kHz -o master44.flac

Quickly convert a folder of takes to 44.1 kHz for a rough mix

ferraus resample takes/*.wav --to 44.1k --quality fast --outdir takes44/

Bring a 22.05 kHz file into a 48 kHz, 24-bit session (no new high frequencies are created)

ferraus resample old22k.wav --to 48000 --bit-depth 24 -o old48.wav

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.

For models

• MCP tool: ferraus_resample
• Schema: ferraus schema resample
• Pipeline: { op: resample, args: { ... } } (flag names with _ instead of -)
• fx stage: yes

{"command": "resample", "defaults": {"to": "48000", "quality": "high"}}

ferraus channels

Mix down, up-mix, extract, swap, or mid/side-convert channels

Synopsis

ferraus channels <input> [options] [-o <output>]

What it does

Does one channel operation per run. --to mono averages the channels; --to stereo copies a mono signal to both sides (and folds 5.1 down with the ITU coefficients). --extract keeps one channel as a mono file. --swap exchanges left and right. --mid-side encode turns L/R into mid (L+R)/2 and side (L-R)/2; decode reverses it exactly.

This command is also an fx stage and a pipeline op: ferraus fx in.wav -o out.wav --fx "channels:key=value".

Examples

Average left and right into one channel

ferraus channels stereo.wav --to mono -o mono.wav

Keep only the right channel (the guest's mic)

ferraus channels interview.wav --extract R -o guest.wav

Get mid in channel 1 and side in channel 2 for M/S processing

ferraus channels mix.wav --mid-side encode -o ms.wav

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.

For models

• MCP tool: ferraus_channels
• Schema: ferraus schema channels
• Pipeline: { op: channels, args: { ... } } (flag names with _ instead of -)
• fx stage: yes

{"command": "channels", "defaults": {}}

ferraus silence detect

Find silent regions and report their start, end, and level

Synopsis

ferraus silence detect <input> [options] [-o <output>]

What it does

Lists every stretch quieter than --threshold that lasts at least --min, with its start, end, duration, and average level. Nothing is changed. --markers also writes the regions as a marker file (CSV for editors and spreadsheets, or JSON) named <input>.silence-detect.csv unless -o says otherwise.

Examples

List pauses of 300 ms or more below -40 dBFS

ferraus silence detect interview.wav --json

Write long pauses to a CSV marker file

ferraus silence detect lecture.mp3 --threshold -50dB --min 2s --markers -o pauses.csv

Write pauses of a second or more to a JSON marker file next to the input

ferraus silence detect podcast.wav --min 1s --markers --markers-format json

Find even short, very quiet gaps, such as the breaths between words of a clean studio take

ferraus silence detect take.wav --threshold -60dB --min 100ms --json

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.
• Beat-based times (4b, 1/4) need a tempo: pass --bpm or write 4b@120.
• Gains need a unit when not in dB: 0.5x is a factor, -6 and -6dB are decibels.

For models

• MCP tool: ferraus_silence_detect
• Schema: ferraus schema silence detect
• Pipeline: { op: silence detect, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "silence detect", "defaults": {"threshold": "-40dB", "min": "300ms", "markers_format": "csv"}}

ferraus silence trim

Remove leading and trailing silence, optionally long pauses too

Synopsis

ferraus silence trim <input> [options] [-o <output>]

What it does

Removes silence below --threshold from the start and end, leaving --keep of it so the sound does not start abruptly (--edges, the default). With --all, pauses inside the audio longer than --min are also shortened to --max-gap, joined with a short crossfade (Audition's Delete Silence).

This command is also an fx stage and a pipeline op: ferraus fx in.wav -o out.wav --fx "silence trim:key=value".

Examples

Strip dead air from both ends, keeping 10 ms

ferraus silence trim take.wav -o take_trimmed.wav

Also shorten every pause longer than 1 s to 700 ms

ferraus silence trim podcast.wav --all --threshold -50dB --max-gap 700ms -o tight.wav

Cut a one-shot sample right at its first and last sound so it plays instantly

ferraus silence trim sample.wav --threshold -50dB --keep 0ms -o sample_tight.wav

Keep natural pauses but shorten any silence over 3 s down to 1 s

ferraus silence trim lecture.wav --all --min 3s --max-gap 1s -o lecture_tight.wav

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.
• Beat-based times (4b, 1/4) need a tempo: pass --bpm or write 4b@120.
• Gains need a unit when not in dB: 0.5x is a factor, -6 and -6dB are decibels.

For models

• MCP tool: ferraus_silence_trim
• Schema: ferraus schema silence trim
• Pipeline: { op: silence trim, args: { ... } } (flag names with _ instead of -)
• fx stage: yes

{"command": "silence trim", "defaults": {"threshold": "-60dB", "keep": "10ms", "min": "1s", "max_gap": "500ms"}}

ferraus silence pad

Add silence to the start and/or end

Synopsis

ferraus silence pad <input> [options] [-o <output>]

What it does

Inserts digital silence before and after the audio, e.g. to give a track lead-in time or meet a platform's spacing rules.

This command is also an fx stage and a pipeline op: ferraus fx in.wav -o out.wav --fx "silence pad:key=value".

Examples

One second of lead-in, two of tail

ferraus silence pad song.wav --start 1s --end 2s -o song_padded.wav

Add one bar of silence at 90 BPM for a reverb tail

ferraus silence pad loop.wav --end 4b --bpm 90 -o loop_tail.wav

Half a second of lead-in so players do not swallow the first word

ferraus silence pad episode.wav --start 500ms -o episode_lead.wav

Add two seconds of tail to every track of an album

ferraus silence pad tracks/*.wav --end 2s --outdir spaced/

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.
• Beat-based times (4b, 1/4) need a tempo: pass --bpm or write 4b@120.

For models

• MCP tool: ferraus_silence_pad
• Schema: ferraus schema silence pad
• Pipeline: { op: silence pad, args: { ... } } (flag names with _ instead of -)
• fx stage: yes

{"command": "silence pad", "defaults": {"start": "0s", "end": "0s"}}

ferraus mix

Sum several files with per-input gain, pan, and offset

Synopsis

ferraus mix <inputs...> [options] [-o <output>]

What it does

Adds the inputs together. --gains, --pans, and --offsets are comma lists with one value per input, in input order (missing values mean 0 dB, unpanned, and no offset). Pans run from -100 (hard left) to +100 (hard right) on a constant-power -3 dB law: a mono source panned to the centre sits 3 dB down on each side; a stereo source is balanced (its far side is turned down). Inputs are resampled to the first file's rate. The result lasts as long as the longest input including its offset. The sum is not normalized unless --normalize peak; a warning is raised if it clips.

Examples

Lay a vocal over a beat, beat 4 dB down

ferraus mix vocal.wav beat.wav --gains 0dB,-4dB -o demo.wav

Rough mix: vocal centred, guitar left, keys right

ferraus mix vox.wav gtr.wav keys.wav --gains 0dB,-3dB,-6dB --pans 0,-40,+40 -o rough.wav

Drop a sting in at 12.5 s and peak-normalize the sum

ferraus mix music.wav sting.wav --offsets 0s,12.5s --normalize peak -o promo.wav

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.
• Gains need a unit when not in dB: 0.5x is a factor, -6 and -6dB are decibels.

For models

• MCP tool: ferraus_mix
• Schema: ferraus schema mix
• Pipeline: { op: mix, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "mix", "defaults": {"normalize": "off", "ceiling": "-1dB"}}

ferraus fade

Fade in and/or out

Synopsis

ferraus fade <input> [options] [-o <output>]

What it does

Fades are computed in gain, not dB, so 'linear' is a straight amplitude ramp. 'log' changes the level evenly in dB (60 dB range), which matches the ear's loudness curve and is the recommended choice for musical fades; 'exp' is its mirror (fast start), 'scurve' eases in and out, and 'equal-power' (sine) suits crossfades. With --in 0s and --out 0s the input is returned unchanged.

This command is also an fx stage and a pipeline op: ferraus fx in.wav -o out.wav --fx "fade:key=value".

Examples

Musical fade in and out

ferraus fade song.wav --in 2s --out 4s --curve log -o faded.wav

Fade to silence one second before the end

ferraus fade take.wav --out 500ms --out-end -1s -o cut.wav

One-beat fade-in at 120 BPM

ferraus fade loop.wav --in 1b --bpm 120 -o loop_in.wav

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.
• Beat-based times (4b, 1/4) need a tempo: pass --bpm or write 4b@120.

For models

• MCP tool: ferraus_fade
• Schema: ferraus schema fade
• Pipeline: { op: fade, args: { ... } } (flag names with _ instead of -)
• fx stage: yes

{"command": "fade", "defaults": {"in": "0s", "out": "0s", "curve": "linear", "in_start": "start", "out_end": "end", "mix": "100%"}}

ferraus reverse

Play the audio backwards

Synopsis

ferraus reverse <input> [options] [-o <output>]

What it does

Reverses every channel. Combine with reverb for the classic reverse-reverb swell: reverse, reverb with --tail, reverse again.

This command is also an fx stage and a pipeline op: ferraus fx in.wav -o out.wav --fx "reverse:key=value".

Examples

Reverse a cymbal

ferraus reverse cymbal.wav -o swell.wav

Reverse-reverb pre-swell

ferraus fx vox.wav -o pre.wav --fx reverse --fx "reverb:mix=100%,tail=2s" --fx reverse

Blend the forward and backward signal for a ghostly texture

ferraus reverse speech.wav --mix 50% -o ghost.wav

Reverse every one-shot in a folder for a reversed sample pack

ferraus reverse samples/*.wav --outdir reversed/

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.

For models

• MCP tool: ferraus_reverse
• Schema: ferraus schema reverse
• Pipeline: { op: reverse, args: { ... } } (flag names with _ instead of -)
• fx stage: yes

{"command": "reverse", "defaults": {"mix": "100%"}}

ferraus speed

Change speed and pitch together (varispeed)

Synopsis

ferraus speed <input> [options] [-o <output>]

What it does

Tape-style speed change: --factor 2.0 plays twice as fast, an octave higher, in half the time. Uses windowed-sinc resampling with automatic anti-aliasing. To change only duration or only pitch, use stretch or pitch.

This command is also an fx stage and a pipeline op: ferraus fx in.wav -o out.wav --fx "speed:key=value".

Examples

Faster and higher

ferraus speed loop.wav --factor 1.5 -o fast.wav

Half speed, an octave down

ferraus speed vox.wav --factor 0.5 -o slow.wav

One semitone up and about 6% faster, like tape running fast

ferraus speed song.wav --factor 1.0595 -o song_up.wav

Fix a 45 rpm record that was digitised at 33 1/3 rpm

ferraus speed vinyl_rip.wav --factor 1.35 -o fixed.wav

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.

For models

• MCP tool: ferraus_speed
• Schema: ferraus schema speed
• Pipeline: { op: speed, args: { ... } } (flag names with _ instead of -)
• fx stage: yes

{"command": "speed", "defaults": {"factor": "1.0"}}

ferraus invert-phase

Invert polarity

Synopsis

ferraus invert-phase <input> [options] [-o <output>]

What it does

Multiplies the signal by -1 (all channels, or only --channel left/right). Fixes a mic wired out of polarity or tests phase cancellation.

This command is also an fx stage and a pipeline op: ferraus fx in.wav -o out.wav --fx "invert-phase:key=value".

Examples

Flip the polarity of a bottom-snare mic

ferraus invert-phase snare_bottom.wav -o flipped.wav

Invert only the right channel

ferraus invert-phase stereo.wav --channel right -o r_flipped.wav

Flip a second microphone that cancels the first, and print the JSON result

ferraus invert-phase mic2.wav --json -o mic2_flipped.wav

Invert one side of a stereo ambience for an out-of-phase, extra-wide effect (it cancels in mono)

ferraus invert-phase ambience.wav --channel left -o ambience_wide.wav

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.

For models

• MCP tool: ferraus_invert_phase
• Schema: ferraus schema invert-phase
• Pipeline: { op: invert-phase, args: { ... } } (flag names with _ instead of -)
• fx stage: yes

{"command": "invert-phase", "defaults": {"channel": "all", "mix": "100%"}}

ferraus envelope

Keyframed automation of gain, pan, or pitch

Synopsis

ferraus envelope <input> [options] [-o <output>]

What it does

Draws an automation curve through 'time=value' keyframes (times as 2s, 1:30, 4b, end, or -5s from the end) and applies it: gain in dB (interpolated in dB), pan from -100 (left) to 100 (right) or L30/R60/center (a mono input becomes stereo with a constant-power -3 dB law; a stereo input is balanced), or pitch in cents (duration-preserving granular shift; good for speech and monophonic lines, rougher on dense mixes). Values hold before the first and after the last keyframe; keyframes are hit sample-accurately.

This command is also an fx stage and a pipeline op: ferraus fx in.wav -o out.wav --fx "envelope:key=value".

Examples

A one-second fade in, then unity gain

ferraus envelope in.wav --points 0s=-60dB,1s=0dB,end=0dB -o faded-in.wav

Sweep a mono source from left to right

ferraus envelope mono.wav --target pan --points 0s=-100,4s=100 --curve spline -o sweep.wav

Bend up a semitone and back

ferraus envelope vox.wav --target pitch --points 0s=0,2s=+100cents,4s=0 -o bend.wav

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.

For models

• MCP tool: ferraus_envelope
• Schema: ferraus schema envelope
• Pipeline: { op: envelope, args: { ... } } (flag names with _ instead of -)
• fx stage: yes

{"command": "envelope", "defaults": {"points": "0s=0dB,2s=-6dB,end=-60dB", "curve": "linear", "target": "gain", "mix": "100%"}}

ferraus generate tone

Generate a test tone or sweep

Synopsis

ferraus generate tone [options]

What it does

Writes a sine, square, saw, or triangle tone (band-limited with polyBLEP, so square, saw, and triangle have no aliasing to speak of), optionally sweeping between two frequencies. The phase is accumulated in double precision, so the frequency is exact. The sample rate and channel count come from the global --sample-rate (default 48000) and --channels (default 1). Without -o the file is tone.wav in the current directory.

Examples

Five seconds of A440 at -3 dBFS

ferraus generate tone -o a440.wav

A ten-second logarithmic sweep at 96 kHz

ferraus generate tone --sweep 20Hz..20kHz --dur 10s --sample-rate 96000 -o sweep.wav

A band-limited saw at C3

ferraus generate tone --shape saw --freq C3 --dur 2s -o saw.wav

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Beat-based times (4b, 1/4) need a tempo: pass --bpm or write 4b@120.
• Gains need a unit when not in dB: 0.5x is a factor, -6 and -6dB are decibels.

For models

• MCP tool: ferraus_generate_tone
• Schema: ferraus schema generate tone
• Pipeline: { op: generate tone, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "generate tone", "defaults": {"freq": "440Hz", "dur": "5s", "shape": "sine", "sweep_curve": "log", "amplitude": "-3dB"}}

ferraus generate noise

Generate white, pink, or brown noise

Synopsis

ferraus generate noise [options]

What it does

Writes Gaussian noise: white (flat), pink (-3 dB per octave, Kellet filter), or brown (-6 dB per octave, leaky integrator), scaled to an exact RMS level. Each channel gets independent noise. --seed makes it reproducible. Without -o the file is noise.wav in the current directory.

Examples

Five seconds of pink noise at -18 dBFS RMS

ferraus generate noise --color pink -o pink.wav

Reproducible stereo brown noise

ferraus generate noise --color brown --dur 30s --channels 2 --seed 7 -o rumble.wav

A minute of quiet white noise, for example to test a noise gate or dehiss

ferraus generate noise --dur 60s --amplitude -30dB -o hiss.wav

Stereo pink noise at -20 dBFS RMS, the usual speaker-calibration signal

ferraus generate noise --color pink --dur 10s --amplitude -20dB --sample-rate 44100 --channels 2 -o calib.wav

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Beat-based times (4b, 1/4) need a tempo: pass --bpm or write 4b@120.
• Gains need a unit when not in dB: 0.5x is a factor, -6 and -6dB are decibels.

For models

• MCP tool: ferraus_generate_noise
• Schema: ferraus schema generate noise
• Pipeline: { op: generate noise, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "generate noise", "defaults": {"color": "white", "dur": "5s", "amplitude": "-18dB"}}

ferraus generate silence

Generate digital silence

Synopsis

ferraus generate silence [options]

What it does

Writes silence of the given duration (useful as padding or a fixture). Without -o the file is silence.wav in the current directory.

Examples

Two seconds of silence

ferraus generate silence -o gap.wav

Half a second of stereo silence

ferraus generate silence --dur 500ms --channels 2 -o gap.wav

Thirty seconds of silence as FLAC (the format follows the extension)

ferraus generate silence --dur 30s -o gap.flac

A minute of 16-bit, 44.1 kHz silence

ferraus generate silence --dur 1:00 --sample-rate 44100 --bit-depth 16 -o minute.wav

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Beat-based times (4b, 1/4) need a tempo: pass --bpm or write 4b@120.

For models

• MCP tool: ferraus_generate_silence
• Schema: ferraus schema generate silence
• Pipeline: { op: generate silence, args: { ... } } (flag names with _ instead of -)
• fx stage: no

{"command": "generate silence", "defaults": {"dur": "2s"}}

ferraus compress

Compress dynamic range (feed-forward, soft knee)

Synopsis

ferraus compress <input> [options] [-o <output>]

What it does

Feed-forward log-domain compressor with a soft knee, lookahead, RMS or peak detection, and a sidechain high-pass so bass does not pump the gain. 'auto' makeup adds back half the reduction a 0 dBFS signal would get. --mix below 100% gives parallel (New York) compression. Optional stages run around the compressor in this order: --highpass, compression, --character tube saturation, --deess, --lowpass; the 'tighten' preset (high-pass 60 Hz, 4:1, 5 ms / 60 ms, de-ess) uses them.

This command is also an fx stage and a pipeline op: ferraus fx in.wav -o out.wav --fx "compress:key=value".

Examples

Vocal preset