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

Documentation tree

binary — This module owns ffmpeg-binary discovery for @suaveplan/audio-codec-ffmpeg-native. It implements a fixed four-step pr…
- binary — This module owns ffmpeg-binary discovery for @suaveplan/audio-codec-ffmpeg-native. It implements a fixed four-step pr…
codec — FfmpegNativeCodec is the server-tier concrete AudioCodec implementation that backs `@suaveplan/audio-codec-ffmpeg-n…
- codec — FfmpegNativeCodec is the server-tier concrete AudioCodec implementation that backs `@suaveplan/audio-codec-ffmpeg-n…
- pcm — PCM helper module for @suaveplan/audio-codec-ffmpeg-native. The ffmpeg subprocess speaks f32le (planar-interleaved…
error-codes — This module owns the stable, namespaced error-code registry for @suaveplan/audio-codec-ffmpeg-native. Every operation…
- error-codes — This module owns the stable, namespaced error-code registry for @suaveplan/audio-codec-ffmpeg-native. Every operation…
register — register(registry, options?) is the one-line entry point applications use to wire `@suaveplan/audio-codec-ffmpeg-nati…
- register — register(registry, options?) is the one-line entry point applications use to wire `@suaveplan/audio-codec-ffmpeg-nati…
runner — This module is the single place in @suaveplan/audio-codec-ffmpeg-native that imports node:child_process. It owns sp…
- runner — This module is the single place in @suaveplan/audio-codec-ffmpeg-native that imports node:child_process. It owns sp…
stream-decoder — createStreamingDecoder returns a FfmpegStreamingDecoder — the @suaveplan/audio-codecs StreamingDecoder plus an…
stream-encoder — createStreamingEncoder returns a FfmpegStreamingEncoder — the @suaveplan/audio-codecs StreamingEncoder plus an…

Install

bun add @suaveplan/audio-codec-ffmpeg-native @suaveplan/audio-codecs
# Optional bundled static binary:
bun add @ffmpeg-installer/ffmpeg

Quickstart

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

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.

4.4 KiB Raw Blame History