`cli` — `AudioCLI` class

(no submodules)

Purpose

AudioCLI is the application-class wrapper for the audio command-line tool. It owns the default codec registry, the default op registry, the FileSourceAdapter / FileSinkAdapter pair from @suaveplan/audio-engine-server, the stdout/stderr streams, the OTel instrumentation, and the argv dispatch logic. Both the bin entry and programmatic consumers construct an instance of this class and call its public methods, so the test surface and the binary exercise the same code path.

The class deliberately holds only wiring: every audio transform is delegated to the seven runX command modules, the pipeline parser, and the underlying @suaveplan/audio-* packages.

Features

Default CodecRegistry populated with the 10 built-in codecs.
Default OpRegistry.createWithDefaults() plus user-supplied overrides.
Injectable FileSourceAdapter / FileSinkAdapter for tests without patching node:fs.
OTel span (audio_cli.<command>), command counter, duration histogram, files-processed counter, all tagged with { command, outcome }.
dispatch(argv) returns a numeric exit code, never throws — failures are formatted onto stderr and mapped through the EXIT_CODES table.
helpText() lists every subcommand and global flag for --help rendering.
detectCodecForOutput(path, registry) exposed for tests and the convert command: extension → codec name, throws AUDIO_CLI.BAD_OUTPUT on miss.

Usage: Basic

import { AudioCLI } from "@suaveplan/audio-cli/cli";

const cli = new AudioCLI();
await cli.process("input.wav", "output.flac");

Usage: Advanced

import { AudioCLI } from "@suaveplan/audio-cli/cli";
import { CodecRegistry, WavCodec } from "@suaveplan/audio-codecs";

const wavOnly = new CodecRegistry({ codecs: [WavCodec] });
const cli = new AudioCLI({ registry: wavOnly, version: "1.2.3" });
const exit = await cli.dispatch(["--version"]);   // prints "1.2.3", returns 0

API Reference

AudioCLI(options?: AudioCliOptions) — constructor.
AudioCliOptions — { registry, ops, source, sink, stdout, stderr, version }.
cli.process / batch / analyze / convert / info / play / record — typed promises, each delegating to its runX module.
cli.dispatch(argv) — exit-code-returning dispatcher.
cli.helpText() — rendered help string.
createDefaultCodecRegistry() — top-level helper used by the default constructor path.
detectCodecForOutput(path, registry) — extension → codec-name lookup.

Implementation Notes

The OTel wrapper records the start time at the top of every command, records the outcome attribute in finally, and lets the AudioCliError propagate. #reportAndExit is the single point that converts a thrown value into a numeric exit code; it writes a single human-readable diagnostic line to stderr (code: message) so the binary composes cleanly inside shell pipelines. The dispatch switch is deliberately flat — every subcommand owns its argument-parsing helper, validates inputs with a Zod schema, and either returns 0 or throws an AudioCliError.

3.1 KiB Raw Blame History

cli — AudioCLI class