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

// 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

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

Chainable pipeline syntax — Unix-pipe-like string parsing for operation chains.
Batch with glob + queue — batch command supports glob patterns and @suaveplan/queue for distributed processing.
Pipe support — read from stdin, write to stdout for Unix pipeline integration.
Analysis JSON output — structured reports for CI integration.
Progress bars — per-file and overall progress for batch operations.
OTel instrumentation — spans per command, counters for files processed.
Property-based tests — random pipeline chains → deterministic output for same seed.
Benchmark suite — batch process 100 files, analyze 100 files.

File layout

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.

4.8 KiB Raw Permalink Blame History