82 lines
4.4 KiB
Markdown
82 lines
4.4 KiB
Markdown
# @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.
|
|
|