audionaut-cli

audionaut-cli [--json] [--quiet] verb project.audium [options]audionaut-cli --help | -haudionaut-cli --version

audionaut-cli is the console binary for Audionaut, a JUCE-based multitrack audio editor. It reads and writes `.audium` project packages without a GUI or audio device, so scripts, CI, and AI agents can create projects, import audio, edit the timeline, analyse, auto-edit, assemble arrangements, separate stems, and bounce mixes.Each invocation is one verb. The project argument may be the `.audium` package directory or the `Project.json` inside it. Positions and durations are musical by default (4/4, 24 clocks per beat, 96 clocks per bar). --unit selects `bars`, `beats`, `seconds`, or `clocks`; bars and beats are 1-based on the timeline, seconds and clocks start at 0. Option values accept `--opt value` or `--opt=value`.--json prints exactly one result envelope on stdout — `{"ok": true, "result": ...}` or `{"ok": false, "error": {"code": ..., "message": ...}}` — with logs on stderr. Exit codes: 0 success, 1 operation failed, 2 usage error, 3 feature unavailable in this build (for example `analyze` without Essentia).The desktop Audionaut binary accepts the same verbs headlessly and then quits. On Linux that binary is `audionaut` from the `.deb` or the AppImage. If the GUI already has the project open, a verb is handed to the live document as one undo step and `Project.json` is not written. Set AUDIONAUT_AGENT_ROUTING=0 to edit the file on disk instead. The MCP package `audionaut-mcp` (`npx -y audionaut-mcp`) exposes the same verbs to agents; it runs the installed app rather than this standalone CLI unless configured otherwise.

--json

One machine-readable envelope on stdout; logs on stderr.

Suppress log output.

List verbs and usage.

Print the CLI version string.

info project [--raw]

Print a summary (tempo, tracks, clips). --raw dumps the full persistence JSON.

Create a new empty `.audium` package (default: one stereo track).

Import audio files at the given position in seconds (default 0) and save.

Offline bounce. The output extension selects the format: `.wav` (8/16/24/32-bit), `.flac` (16/24-bit, up to 8 channels), `.aiff` (8/16/24-bit), `.ogg` (Vorbis, --bitrate 64–500, default 192), `.mp3` (LAME, --bitrate 96/128/160/192/256/320, mono or stereo, up to 48 kHz). --multi-mono writes one mono file per channel. --region bounces a single region dry, without clip gains or fades.

Run Essentia analysis and cache results next to the project for auto-edit, assemble, and the GUI. Default types include `sbic` and `beat_degara`. Exit 3 if Essentia is not in the build.

Segment a clip using cached analysis. Run analyze first.

Build an arrangement of the given duration from the project's regions.

Split the clip under that position on every track.

Name a region from a timeline range on every track whose clip fully contains it.

Rename and/or retrim a region (clamped to the source audio). Retrimming affects every clip that uses the region.

Remove a clip at a position, or every placement of a named region. --delete-region also drops the region unless other clips still use it.

Move exactly one matching clip. At least one of --to and --to-track is required.

Place an existing region on the timeline.

Delete regions no clip uses, plus empty resource groups. Audio files stay in the package.

Set clip gain (linear, or dB with --db) on every destination channel, or one channel with --channel.

Set fade ramps (0 clears) and curve exponents (0.1–4, 0.5 = equal power). Offsets are measured inward from the clip edges; a negative offset extends the ramp outside the clip.

Change playback speed. Ratio 2.0 is double speed (half duration); range 0.25–4.0. --mode stretch preserves pitch. --lock-tempo on ties the clip to project tempo.

Remove a track (channels, clips, and regions). Track ids below it shift up. Audio files stay in the package.

Remove channel C (0-based) from track N.

Split a clip into Drums/Bass/Other/Vocals tracks with Demucs (`htdemucs`). Needs model weights (downloaded by the app, or --model). --backend fake copies the clip into the Vocals stem for tests.

AUDIONAUT_DISABLE_ANALYTICS

When set to any non-empty value, skip CLI usage reporting even if the desktop app has granted analytics consent. Recommended for CI.

Set to `0` to edit the project file on disk even when the GUI has that project open. Default routing hands the verb to the live document, or fails rather than overwriting unsaved work if the host cannot be reached.

The standalone CLI is built from the test CMake project (`cmake --build … --target AudionautCli`); packaged Linux installs may ship only the GUI binary, which still runs the same verbs. `analyze` needs an Essentia-enabled build. `separate` needs Demucs weights and can take minutes on a full song. On macOS the sandboxed app CLI can only reach entitlement-covered locations such as `~/Music`; this standalone binary has no such limit. Leave `Autosave.json` and `Host.json` inside a project package alone. CLI analytics fire only after the app's opt-in consent (verb and exit code only).

Audionaut is written in C++ on the JUCE framework by Klaus Voltmer (Voltmer Systems). The code base went open source under GPLv3 (with a commercial licence option) on 15 August 2026. The headless CLI and MCP server (`audionaut-mcp`) expose the same edit verbs the timeline uses so agents can drive sessions.

sox(1), ffmpeg(1), lame(1), flac(1), audacity(1), ardour(1)

Source code · Homepage · Documentation