128 lines
4.8 KiB
Markdown
128 lines
4.8 KiB
Markdown
# OpenSpec Change: enterprise-audio-cli
|
|
|
|
- **Change ID**: enterprise-audio-cli
|
|
- **Package**: `@suaveplan/audio-cli`
|
|
- **Category**: server
|
|
- **Target path**: `packages/media/audio/audio-cli`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-05-14
|
|
- **Design**: `./design.md`
|
|
- **Spec delta**: `./specs/audio-cli/spec.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/audio-cli` on the genesis branch from scratch at enterprise quality. Command-line audio processing tool for the genesis monorepo. Built on `@suaveplan/cli` for argument parsing and `@suaveplan/audio-engine-server` for file I/O. All processing is universal — the CLI is just a shell around the same `AudioDocument` + `PlanEngine` + `ProcessPipeline` that runs in browsers.
|
|
|
|
Inspired by `audiojs/audio`'s CLI: chainable operations, batch processing, and Unix pipe support.
|
|
|
|
---
|
|
|
|
## Current-state audit (genesis)
|
|
|
|
The package does not exist on genesis yet — this is a fresh build. No prior source, no test results, no coverage data.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/audio-core` (`workspace:^`) | `AudioDocument`, `OpRegistry`, `PlanEngine`, `ProcessPipeline` |
|
|
| `@suaveplan/audio-codecs` (`workspace:^`) | `CodecRegistry`, `encodeTo`, `decodeSource` |
|
|
| `@suaveplan/audio-engine-server` (`workspace:^`) | `FileSourceAdapter`, `FileSinkAdapter` |
|
|
| `@suaveplan/audio-fx-plugin-base` (`workspace:^`) | FX plugins for pipeline processing |
|
|
| `@suaveplan/audio-analysis-*` (`workspace:^`) | Analysis ops for `analyze` command |
|
|
| `@suaveplan/cli` (`workspace:^`) | CLI framework, argument parsing, command registry |
|
|
| `@suaveplan/queue` (`workspace:^`) | Batch job distribution |
|
|
| `@suaveplan/streams` (`workspace:^`) | Pipe support |
|
|
| `@suaveplan/error` (`workspace:^`) | `AudioError` base class; `AUDIO_CLI.*` codes |
|
|
| `@suaveplan/types` (`workspace:^`) | `LoggerLike` |
|
|
|
|
Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata` (all `catalog:testing`).
|
|
|
|
---
|
|
|
|
## Public API
|
|
|
|
### CLI commands
|
|
|
|
```ts
|
|
// process <input> <output> --pipeline "trim 30s | normalize | fade 0.5s 1s"
|
|
// batch --input "./tracks/*.mp3" --pipeline "..." --output "./processed/"
|
|
// analyze input.mp3 --bpm --key --lufs --output report.json
|
|
// convert input.wav output.flac
|
|
// info input.mp3
|
|
// play input.wav
|
|
// record output.wav --duration 60s
|
|
```
|
|
|
|
### Programmatic API
|
|
|
|
```ts
|
|
import { AudioCLI } from '@suaveplan/audio-cli'
|
|
|
|
const cli = new AudioCLI()
|
|
await cli.process('input.wav', 'output.flac', { pipeline: [['trim', { start: 30 }], ['normalize', { lufs: -16 }]] })
|
|
const report = await cli.analyze('input.mp3', ['bpm', 'key', 'lufs'])
|
|
```
|
|
|
|
---
|
|
|
|
## New additions for genesis
|
|
|
|
1. **Chainable pipeline syntax** — Unix-pipe-like string parsing for operation chains.
|
|
2. **Batch with glob + queue** — `batch` command supports glob patterns and `@suaveplan/queue` for distributed processing.
|
|
3. **Pipe support** — read from stdin, write to stdout for Unix pipeline integration.
|
|
4. **Analysis JSON output** — structured reports for CI integration.
|
|
5. **Progress bars** — per-file and overall progress for batch operations.
|
|
6. **OTel instrumentation** — spans per command, counters for files processed.
|
|
7. **Property-based tests** — random pipeline chains → deterministic output for same seed.
|
|
8. **Benchmark suite** — batch process 100 files, analyze 100 files.
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
packages/media/audio/audio-cli/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
error-codes.ts
|
|
cli.ts
|
|
cli.md
|
|
commands/
|
|
process.ts, process.md, process.test.ts
|
|
batch.ts, batch.md, batch.test.ts
|
|
analyze.ts, analyze.md, analyze.test.ts
|
|
convert.ts, convert.md, convert.test.ts
|
|
info.ts, info.md, info.test.ts
|
|
play.ts, play.md, play.test.ts
|
|
record.ts, record.md, record.test.ts
|
|
index.ts
|
|
pipeline/
|
|
parser.ts, parser.md, parser.test.ts
|
|
index.ts
|
|
__benchmarks__/
|
|
cli.bench.ts
|
|
tests/
|
|
integration.test.ts
|
|
property.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
**Breaking changes**: none — fresh build, package does not yet exist on genesis.
|
|
|
|
**Prerequisites**: `@suaveplan/audio-core`, `@suaveplan/audio-codecs`, `@suaveplan/audio-engine-server`, `@suaveplan/audio-fx-plugin-base`, `@suaveplan/audio-analysis-*`, `@suaveplan/cli`, `@suaveplan/queue`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/opentelemetry` published to Verdaccio.
|
|
|
|
### Affected dependents
|
|
|
|
No dependents (verified by `bunx turbo ls --filter=...@suaveplan/audio-cli`) — this is a terminal application package. The `audio` CLI sits at the top of the `@suaveplan/audio-*` dependency graph; nothing imports it. Downstream *consumers* are external (DevOps pipelines, server-side media processing, CI audio validation), not workspace packages, so there is no dependent surface to test or migrate.
|