skills/docs/media/audio/audio-cli

@suaveplan/audio-cli - Server-tier audio command-line tool: chainable pipeline grammar, batch glob processing, analysis JSON reports, codec conversion, info, play, record. Thin shell over @suaveplan/audio-core + audio-codecs + audio-engine-server.

Server-tier audio command-line tool. Thin shell over @suaveplan/audio-core, @suaveplan/audio-codecs, and @suaveplan/audio-engine-server: every audio transform delegates to the universal layer; the CLI itself owns argument parsing, the pipeline grammar, command dispatch, exit-code mapping, and SIGINT handling.

Documentation tree

• bin — This module is the bin shebang entry for the suaveplan-audio command. It is the only file in the package with side…
  • bin — This module is the bin shebang entry for the suaveplan-audio command. It is the only file in the package with side…
• cli — AudioCLI is the application-class wrapper for the audio command-line tool. It owns the default codec registry, the…
  • cli — AudioCLI is the application-class wrapper for the audio command-line tool. It owns the default codec registry, the…
• analyze — runAnalyze is the analysis pipeline entry. It loads an input file through the FileSourceAdapter, runs the requested…
• batch — runBatch is the bulk-processing entry point. It expands a glob pattern or a comma-separated list of explicit paths in…
• convert — runConvert is a deliberately thin wrapper around runProcess. It validates the small ConvertOptions surface (`form…
• info — runInfo produces a one-shot metadata + statistics report for a file: sample rate, channel count, duration, total samp…
• play — runPlay plays a file through an injected SpeakerAdapter. The CLI package intentionally carries no platform audio bi…
• process — runProcess is the engine of the audio process and bare-op invocations. It loads the input file via `FileSourceAdapt…
• record — runRecord captures audio from an injected MicrophoneAdapter for a fixed duration and saves the resulting `AudioDocu…
• error-codes — This module is the structured error and exit-code boundary for @suaveplan/audio-cli. It defines the six AUDIO_CLI.*…
  • error-codes — This module is the structured error and exit-code boundary for @suaveplan/audio-cli. It defines the six AUDIO_CLI.*…
• pipeline — This module turns a CLI user's free-form pipeline expression into a typed [opName, params] chain that the rest of the…
  • parser — This module turns a CLI user's free-form pipeline expression into a typed [opName, params] chain that the rest of the…

Install

bun add @suaveplan/audio-cli

The suaveplan-audio bin is installed alongside the package.

CLI

suaveplan-audio --version
suaveplan-audio --help

# Process: load → ops → save
suaveplan-audio process input.wav output.flac --pipeline "trim 30s | normalize -16lufs"

# Batch: glob + shared pipeline
suaveplan-audio batch --input "tracks/*.mp3" --output processed/ --pipeline "normalize" --workers 4

# Analyze: produce a JSON report
suaveplan-audio analyze input.mp3 --bpm --key --lufs --output report.json

# Format conversion (no ops)
suaveplan-audio convert input.wav output.flac

# Print metadata + computeStats
suaveplan-audio info input.mp3

# Headless play (uses an injected SpeakerAdapter)
suaveplan-audio play input.wav

# Record silence (default mic) for N seconds
suaveplan-audio record out.wav --duration 60

Programmatic API

import { AudioCLI } from "@suaveplan/audio-cli";

const cli = new AudioCLI();
await cli.process("input.wav", "output.flac", { pipeline: "trim 30s | normalize" });
const report = await cli.analyze("input.mp3", { bpm: true, key: true, lufs: true });

Subpath exports for tree-shaken consumption:

• @suaveplan/audio-cli/cli — the AudioCLI class.
• @suaveplan/audio-cli/pipeline/parser — parsePipeline / validatePipeline.
• @suaveplan/audio-cli/error-codes — AUDIO_CLI_CODES, AudioCliError, EXIT_CODES, exitCodeFor.
• @suaveplan/audio-cli/commands/<command> — each runX entry.

Exit codes

Stable mapping from AUDIO_CLI.* codes onto Unix exit codes:

Code	Exit
AUDIO_CLI.INVALID_ARGS	2
AUDIO_CLI.UNKNOWN_OP	2
AUDIO_CLI.INPUT_NOT_FOUND	3
AUDIO_CLI.BAD_OUTPUT	4
AUDIO_CLI.PIPELINE_FAILED	5
AUDIO_CLI.ABORTED	130

0 is reserved for success. Any uncaught non-AudioCliError exits 1.

Quality

• Server-tier, Node.js >=22.
• 100/100/100/100 coverage on every implementation file.
• Zero mocks — tests drive the real CLI against real mkdtemp temp files and the real @suaveplan/audio-engine-server adapters.