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