Initial Commit
This commit is contained in:
104
packages/media/audio/audio-cli/README.md
Normal file
104
packages/media/audio/audio-cli/README.md
Normal file
@@ -0,0 +1,104 @@
|
||||
# @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.
|
||||
|
||||
Reference in New Issue
Block a user