Initial Commit

packages/media/audio/audio-codec-ffmpeg-native/README.md

@@ -0,0 +1,81 @@
+# @suaveplan/audio-codec-ffmpeg-native - Server-tier ffmpeg-native AudioCodec plugin for @suaveplan/audio-codecs: spawns the system ffmpeg binary via fluent-ffmpeg, streams stdin/stdout for true chunked decode/encode of wav/mp3/ogg/opus/flac/aac/webm, bounded concurrency, AbortSignal cleanup with SIGTERM->SIGKILL escalation, and a one-line register(registry) helper.
+
+Server-tier `AudioCodec` plugin for `@suaveplan/audio-codecs` that shells out
+to the system `ffmpeg` binary via `fluent-ffmpeg` and streams audio through
+the subprocess' stdin/stdout. Spec ID: `enterprise-audio-codec-ffmpeg-native`.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [binary](./src/binary/binary.md) — This module owns ffmpeg-binary discovery for `@suaveplan/audio-codec-ffmpeg-native`. It implements a fixed four-step pr…
+  - [binary](./src/binary/binary.md) — This module owns ffmpeg-binary discovery for `@suaveplan/audio-codec-ffmpeg-native`. It implements a fixed four-step pr…
+- [codec](./src/codec/codec.md) — `FfmpegNativeCodec` is the server-tier concrete `AudioCodec` implementation that backs `@suaveplan/audio-codec-ffmpeg-n…
+  - [codec](./src/codec/codec.md) — `FfmpegNativeCodec` is the server-tier concrete `AudioCodec` implementation that backs `@suaveplan/audio-codec-ffmpeg-n…
+  - [pcm](./src/codec/pcm.md) — PCM helper module for `@suaveplan/audio-codec-ffmpeg-native`. The ffmpeg subprocess speaks `f32le` (planar-interleaved…
+- [error-codes](./src/error-codes/error-codes.md) — This module owns the stable, namespaced error-code registry for `@suaveplan/audio-codec-ffmpeg-native`. Every operation…
+  - [error-codes](./src/error-codes/error-codes.md) — This module owns the stable, namespaced error-code registry for `@suaveplan/audio-codec-ffmpeg-native`. Every operation…
+- [register](./src/register/register.md) — `register(registry, options?)` is the one-line entry point applications use to wire `@suaveplan/audio-codec-ffmpeg-nati…
+  - [register](./src/register/register.md) — `register(registry, options?)` is the one-line entry point applications use to wire `@suaveplan/audio-codec-ffmpeg-nati…
+- [runner](./src/runner/runner.md) — This module is the single place in `@suaveplan/audio-codec-ffmpeg-native` that imports `node:child_process`. It owns sp…
+  - [runner](./src/runner/runner.md) — This module is the single place in `@suaveplan/audio-codec-ffmpeg-native` that imports `node:child_process`. It owns sp…
+- [stream-decoder](./src/stream/stream-decoder.md) — `createStreamingDecoder` returns a `FfmpegStreamingDecoder` — the `@suaveplan/audio-codecs` `StreamingDecoder` plus an…
+- [stream-encoder](./src/stream/stream-encoder.md) — `createStreamingEncoder` returns a `FfmpegStreamingEncoder` — the `@suaveplan/audio-codecs` `StreamingEncoder` plus an…
+<!-- end:auto-docs -->
+
+## Install
+
+```bash
+bun add @suaveplan/audio-codec-ffmpeg-native @suaveplan/audio-codecs
+# Optional bundled static binary:
+bun add @ffmpeg-installer/ffmpeg
+```
+
+## Quickstart
+
+```ts
+import { CodecRegistry } from "@suaveplan/audio-codecs";
+import { register } from "@suaveplan/audio-codec-ffmpeg-native";
+
+const registry = new CodecRegistry();
+register(registry, { concurrencyLimit: 8, timeoutMs: 30_000 });
+
+const codec = registry.byName("ffmpeg-native");
+const decoded = await codec.decode(mp3Bytes);
+const encoded = await codec.encode(decoded.channelData, {
+    format: "flac",
+    sampleRate: decoded.sampleRate,
+});
+```
+
+## Streaming
+
+```ts
+import { FfmpegNativeCodec } from "@suaveplan/audio-codec-ffmpeg-native";
+
+const decoder = new FfmpegNativeCodec().createDecoder({ format: "ogg" });
+for (const chunk of oggChunks) decoder.write(chunk);
+const trailing = await decoder.flushAsync(); // additive Promise companion.
+decoder.close();
+```
+
+`flushAsync()` is an additive method on the streaming decoder/encoder that
+the spec asks for, layered over the synchronous base contract from
+`@suaveplan/audio-codecs`. See `src/stream/*.md` for details.
+
+## Engines
+
+Node.js 22+. Server-tier only — no browser support, no `worker_threads`
+plumbing.
+
+## Error codes
+
+Eight codes namespaced under `AUDIO_CODEC_FFMPEG_NATIVE.*`:
+`BINARY_MISSING`, `SPAWN_FAILED`, `DECODE_FAILED`, `ENCODE_FAILED`,
+`TIMEOUT`, `ABORTED`, `UNSUPPORTED_CODEC`, `INVALID_PCM`.
+
+## Status
+
+`0.1.0` — first-tier landing. Subpath exports cover every implementation
+module so consumers can tree-shake. See the package's OpenSpec change for
+the full specification.
+