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

<!-- begin:auto-docs -->
## Documentation tree

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

## Install

```sh
bun add @suaveplan/audio-cli
```

The `suaveplan-audio` bin is installed alongside the package.

## CLI

```sh
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

```ts
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.