ferraus

ferraus

A command-line audio workstation for scripts and AI agents.

One cross-platform binary that edits, repairs, separates, tunes, transcribes, notates, and masters audio. Every command returns JSON and records how each file was made, so scripts and agents can chain it without a GUI and reproduce any result. (The *au* is for audio.)

ferraus separate song.mp3                         # vocals, drums, bass, other

ferraus denoise take.wav --auto -o clean.wav # learn the noise, remove it ferraus tune vocal.wav --key auto -o tuned.wav # pitch-correct to the detected key ferraus hum idea.wav --to piano -o idea.piano.wav # humming → MIDI → a real instrument ferraus mix balance stems/*.wav --genre pop # faders that put stems on a genre balance ferraus master mix.wav --target streaming # release-ready master at -14 LUFS

• Editing and conversion: convert, trim, cut, split, concat, resample, normalize (EBU R128), channels, silence, tags, waveform and spectrogram export; audio from MP4/MKV/WebM/MOV.
• Effects: fades, compressor, limiter, gate, de-esser, multiband, EQ, reverb (plate, FDN, convolution), delay, chorus/flanger/phaser, saturation, vocoder, panning and automation.
• Restoration matching Adobe Audition's effects: declip, dehum, declick, dehiss, spectral repair, phase alignment, leveler, scientific filters, and more.
• Noise reduction from a noise profile, adaptive, or model-based (DeepFilterNet, RNNoise).
• Stem separation in tiers from Demucs to RoFormer ensembles.
• Pitch and time: auto-tune, pitch shift with formant preservation, time stretch.
• MIDI and notation: quantize, groove, hum-to-MIDI, rendering through SoundFonts, SFZ, or CLAP/VST3 instruments; scores (lead sheet, grand staff, drums, solfa) from audio or MIDI, and sheet-music PDFs performed as audio.
• Mixing: stem balance to genre templates, level-aware masking analysis with the EQ cut that fixes it, sidechain ducking, a vocal rider that holds the vocal against the music word by word, dynamic resonance control, song structure (sections, repeats, roles), patching a bad note from a clean repeat, a pass/fail gate before mastering, and whole sessions as cached pipeline files whose stages report their own measurements.
• Mastering: one command, or an analyze → plan → verify loop an agent can drive.

For AI agents

Every command takes --json and returns a stable, versioned envelope; ferraus schema prints its JSON Schema; every output gets a provenance sidecar ( .ferraus.json) that ferraus replay reproduces. ferraus is also an MCP server:

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

ferraus describe --agent prints the whole command surface in under 4,000 tokens. See AGENTS.md.

Install the skills

The ferraus skill teaches an agent when and how to use ferraus (the --json contract, dry runs, model downloads). The companion skills carry an engineer's working method for whole jobs: every decision taken from a measurement, every result checked against a numeric gate, and the session delivered as an editable pipeline file plus a report. They are what let an agent mix and master a producer's stems unsupervised.

Install them with one of:

The skills drive the ferraus command, so install the CLI first (see Install).

One prompt that sets everything up

To set up an agent, paste this into it:

Install the ferraus CLI and its skill, then use ferraus for any audio, music, or sheet-music task.

1. Install the CLI if ferraus --version fails. Use one method: macOS or Linux with Homebrew: brew install djynnius/tap/ferraus; otherwise on macOS or Linux: curl -fsSL https://github.com/djynnius/ferraus/releases/latest/download/ferraus-installer.sh | sh; on Windows (PowerShell): powershell -ExecutionPolicy ByPass -c "irm https://github.com/djynnius/ferraus/releases/latest/download/ferraus-installer.ps1 | iex". Then run ferraus doctor --json and confirm "ok": true.
2. Install the skills. In Claude Code: claude plugin marketplace add djynnius/ferraus, then claude plugin install ferraus@ferraus. In another agent: npx skills add djynnius/ferraus and select all the ferraus skills and your agent. Use one method. You can read the skills directly at https://github.com/djynnius/ferraus/tree/main/skills (the main one, raw: https://raw.githubusercontent.com/djynnius/ferraus/main/skills/ferraus/SKILL.md).
3. Optional, if you support MCP: register ferraus mcp serve --allow as an MCP server (Claude Code: claude mcp add ferraus -- ferraus mcp serve --allow ~/Music).
4. Before the first task, run ferraus describe --agent for the command catalog and read https://raw.githubusercontent.com/djynnius/ferraus/main/AGENTS.md for the contract: add --json to every call, plan with --dry-run, never pass --overwrite unless asked, and only download models (-y) when the user agrees.

Examples

examples/ has runnable shell scripts, pipeline files, an MCP client, and a Claude agent loop. They work on test audio that ferraus generates, and CI runs all of them.

Install

apt repository (signed; updates arrive with apt upgrade):

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

Update: ferraus update --check says whether a newer release is out and how to get it; ferraus update installs it when the release installer put ferraus there, and otherwise prints the Homebrew, apt, dnf, scoop, or cargo command.

Builds: macOS 13.4+ on Apple silicon and Intel; Linux on x86-64 and ARM64, both with glibc 2.38+ (Ubuntu 24.04+, Debian 13+, Fedora 39+) and as a fully static musl build for Alpine and older distributions (the shell installer picks it when glibc is too old; it cannot load CLAP or VST3 plugins); Windows on x86-64 and ARM64 (needs the Microsoft Visual C++ Redistributable, present on most machines). Release artifacts are built and attested only by this repository's GitHub Actions workflows. Model weights are not in the package; they download on first use (with -y or models.auto_download = true) and are verified by SHA-256.

Run ferraus doctor after installing.

Documentation

• ferraus docs — the full reference page for any command, offline.
• The docs site: https://djynnius.github.io/ferraus (and llms.txt for models).
• Product requirements.md), architecture decisions, contributor guide.

License

Apache-2.0 OR MIT, at your option. The score engraving helper (ferraus-engrave) is LGPL-3.0 because it links Verovio; it runs as a separate process.