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