@mediabunny/server 1.45.0

package/dist/mediabunny-server.d.ts

@@ -0,0 +1,105 @@
+import { AudioSample } from 'mediabunny';
+import { AudioSampleResource } from 'mediabunny';
+import { MaybePromise } from 'mediabunny';
+import * as NodeAv from 'node-av';
+import { SetRequired } from 'mediabunny';
+import { VideoDataPlane } from 'mediabunny';
+import { VideoSample } from 'mediabunny';
+import { VideoSampleColorSpace } from 'mediabunny';
+import { VideoSampleInit } from 'mediabunny';
+import { VideoSamplePixelFormat } from 'mediabunny';
+import { VideoSampleResource } from 'mediabunny';
+
+/**
+ * A custom `AudioSampleResource` backed by NodeAV's
+ * [`Frame`](https://seydx.github.io/node-av/api/lib/classes/Frame.html), which in turn is backed by FFmpeg's
+ * [`AVFrame`](https://ffmpeg.org/doxygen/2.7/structAVFrame.html). You can use this resource to create `AudioSample`
+ * instances that are directly backed by FFmpeg's `AVFrame` without data having to be copied.
+ *
+ * When passed, the `Frame` is now owned by resource, meaning it takes care of closing the frame later. If you want to
+ * keep a copy for your own use, clone the frame first.
+ *
+ * @group \@mediabunny/server
+ * @public
+ */
+export declare class AvFrameAudioSampleResource extends AudioSampleResource {
+    /**
+     * The NodeAV [`Frame`](https://seydx.github.io/node-av/api/lib/classes/Frame.html) instance backing this resource.
+     * Access throws if the resource has already been closed.
+     */
+    get frame(): NodeAv.Frame;
+    constructor(frame: NodeAv.Frame);
+    getFormat(): AudioSampleFormat;
+    getSampleRate(): number;
+    getNumberOfChannels(): number;
+    getNumberOfFrames(): number;
+    getTimestamp(): number;
+    close(): void;
+    getDataPlane(planeIndex: number): Uint8Array;
+}
+
+/**
+ * A custom `VideoSampleResource` backed by NodeAV's
+ * [`Frame`](https://seydx.github.io/node-av/api/lib/classes/Frame.html), which in turn is backed by FFmpeg's
+ * [`AVFrame`](https://ffmpeg.org/doxygen/2.7/structAVFrame.html). You can use this resource to create `VideoSample`
+ * instances that are directly backed by FFmpeg's `AVFrame` without data having to be copied. Since `AVFrame`s can
+ * themselves be backed by data on the GPU, this enables zero-copy hardware-accelerated decode and encode paths.
+ *
+ * When using Electron, you can directly create `Frame` instances without the data having to leave the GPU. For more,
+ * see [NodeAV's docs](https://seydx.github.io/node-av/api/lib/classes/Frame.html).
+ *
+ * When passed, the `Frame` is now owned by resource, meaning it takes care of closing the frame later. If you want to
+ * keep a copy for your own use, clone the frame first.
+ *
+ * @group \@mediabunny/server
+ * @public
+ */
+export declare class AvFrameVideoSampleResource extends VideoSampleResource {
+    /**
+     * The NodeAV [`Frame`](https://seydx.github.io/node-av/api/lib/classes/Frame.html) instance backing this resource.
+     * Access throws if the resource has already been closed.
+     */
+    get frame(): NodeAv.Frame;
+    constructor(frame: NodeAv.Frame);
+    getFormat(): VideoSamplePixelFormat | null;
+    getCodedWidth(): number;
+    getCodedHeight(): number;
+    getSquarePixelWidth(): number;
+    getSquarePixelHeight(): number;
+    getColorSpace(): VideoSampleColorSpace;
+    close(): void;
+    getDataPlanes(): MaybePromise<VideoDataPlane[]>;
+    toRgbSample(init: SetRequired<VideoSampleInit, 'timestamp'>, colorSpace: PredefinedColorSpace): Promise<VideoSample>;
+}
+
+/**
+ * Registers video and audio decoders and encoders for all codecs, using FFmpeg's libavcodec under the hood.
+ * Additionally, a custom `VideoSample` transformer based on libavfilter is registered to enable resizing, rotation and
+ * cropping of video frames.
+ *
+ * Make sure to call this function before interacting with Mediabunny.
+ *
+ * The decoders and encoders will automatically detect hardware acceleration support for each codec and platform and
+ * make use of it if applicable.
+ *
+ * @group \@mediabunny/server
+ * @public
+ */
+export declare const registerMediabunnyServer: () => void;
+
+/**
+ * Copies a `VideoSample` or `AudioSample` into the given NodeAV
+ * [`Frame`](https://seydx.github.io/node-av/api/lib/classes/Frame.html), setting up the frame's format, media type,
+ * timing and data. When the sample is already backed by an `AVFrame` (via `AvFrameVideoSampleResource` or
+ * `AvFrameAudioSampleResource`), the frame is ref'd instead of copied for zero-copy reuse.
+ *
+ * For video samples, the frame's time base is always set to 1/1000000 (microsecond accuracy). For audio samples, the
+ * frame's time base is always set to 1/sampleRate.
+ *
+ * @group \@mediabunny/server
+ * @public
+ */
+export declare const toAvFrame: (sample: VideoSample | AudioSample, frame: NodeAv.Frame) => Promise<void>;
+
+export { }
+export as namespace MediabunnyServer;

package/dist/modules/src/audio-decoder.d.ts

@@ -0,0 +1,21 @@
+/*!
+ * Copyright (c) 2026-present, Vanilagy and contributors
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+import { AudioCodec, CustomAudioDecoder, EncodedPacket, type MaybePromise } from 'mediabunny';
+import * as NodeAv from 'node-av';
+export declare class NodeAvAudioDecoder extends CustomAudioDecoder {
+    frame: NodeAv.Frame;
+    packet: NodeAv.Packet;
+    codecContext: NodeAv.CodecContext;
+    static supports(codec: AudioCodec, config: AudioDecoderConfig): boolean;
+    init(): Promise<void>;
+    decode(packet: EncodedPacket): Promise<void>;
+    receiveFrame(ret: number): void;
+    flush(): Promise<void>;
+    close(): MaybePromise<void>;
+}
+//# sourceMappingURL=audio-decoder.d.ts.map

package/dist/modules/src/audio-decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-decoder.d.ts","sourceRoot":"","sources":["../../../src/audio-decoder.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAe,kBAAkB,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAC3G,OAAO,KAAK,MAAM,MAAM,SAAS,CAAC;AAKlC,qBAAa,kBAAmB,SAAQ,kBAAkB;IACzD,KAAK,EAAG,MAAM,CAAC,KAAK,CAAC;IACrB,MAAM,EAAG,MAAM,CAAC,MAAM,CAAC;IACvB,YAAY,EAAG,MAAM,CAAC,YAAY,CAAC;WAGnB,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO;IAU1E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgCrB,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBlD,YAAY,CAAC,GAAG,EAAE,MAAM;IAYlB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5B,KAAK,IAAI,YAAY,CAAC,IAAI,CAAC;CAK3B"}

package/dist/modules/src/audio-decoder.js

@@ -0,0 +1,132 @@
+"use strict";
+/*!
+ * Copyright (c) 2026-present, Vanilagy and contributors
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeAvAudioDecoder = void 0;
+const mediabunny_1 = require("mediabunny");
+const NodeAv = __importStar(require("node-av"));
+const misc_1 = require("./misc");
+const misc_2 = require("../../../src/misc");
+const audio_sample_1 = require("./audio-sample");
+class NodeAvAudioDecoder extends mediabunny_1.CustomAudioDecoder {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    static supports(codec, config) {
+        return codec === 'aac'
+            || codec === 'opus'
+            || codec === 'mp3'
+            || codec === 'vorbis'
+            || codec === 'flac'
+            || codec === 'ac3'
+            || codec === 'eac3';
+    }
+    async init() {
+        this.frame = new NodeAv.Frame();
+        this.frame.alloc();
+        this.packet = new NodeAv.Packet();
+        this.packet.alloc();
+        const codecId = misc_1.CODEC_TO_CODEC_ID[this.codec];
+        (0, misc_2.assert)(codecId !== undefined);
+        const codec = NodeAv.Codec.findDecoder(codecId);
+        if (codec === null) {
+            throw new Error(`Unable to obtain libav codec for '${this.codec}'.`);
+        }
+        const codecContext = new NodeAv.CodecContext();
+        codecContext.allocContext3(codec);
+        codecContext.sampleRate = this.config.sampleRate;
+        codecContext.channelLayout = (0, misc_1.getChannelLayout)(this.config.numberOfChannels);
+        codecContext.timeBase = new NodeAv.Rational(1, this.config.sampleRate);
+        codecContext.codecType = NodeAv.AVMEDIA_TYPE_AUDIO;
+        codecContext.codecId = codecId;
+        codecContext.extraData = this.config.description
+            ? Buffer.from((0, misc_2.toUint8Array)(this.config.description))
+            : null;
+        const ret = await codecContext.open2();
+        NodeAv.FFmpegError.throwIfError(ret, 'Open codec context');
+        this.codecContext = codecContext;
+    }
+    async decode(packet) {
+        this.packet.isKeyframe = packet.type === 'key';
+        this.packet.data = Buffer.from(packet.data);
+        this.packet.timeBase = { num: 1, den: this.config.sampleRate };
+        this.packet.pts = BigInt(Math.round(packet.timestamp * this.config.sampleRate));
+        this.packet.dts = NodeAv.AV_NOPTS_VALUE;
+        this.packet.duration = BigInt(Math.round(packet.duration * this.config.sampleRate));
+        const ret = await this.codecContext.sendPacket(this.packet);
+        NodeAv.FFmpegError.throwIfError(ret, 'Send packet');
+        while (true) {
+            const receiveRet = await this.codecContext.receiveFrame(this.frame);
+            if (receiveRet === NodeAv.AVERROR_EAGAIN || receiveRet === NodeAv.AVERROR_EOF) {
+                break;
+            }
+            this.receiveFrame(receiveRet);
+        }
+    }
+    receiveFrame(ret) {
+        NodeAv.FFmpegError.throwIfError(ret, 'Receive frame');
+        const clone = this.frame.clone();
+        if (!clone) {
+            throw new Error('Allocation failure during frame clone.');
+        }
+        clone.timeBase = new NodeAv.Rational(1, this.config.sampleRate);
+        this.onSample(new mediabunny_1.AudioSample(new audio_sample_1.AvFrameAudioSampleResource(clone)));
+    }
+    async flush() {
+        // Send null packet to signal flush
+        const ret = await this.codecContext.sendPacket(null);
+        NodeAv.FFmpegError.throwIfError(ret, 'Flush decoder');
+        // Keep receiving frames until no more are available
+        while (true) {
+            const receiveRet = await this.codecContext.receiveFrame(this.frame);
+            if (receiveRet === NodeAv.AVERROR_EAGAIN || receiveRet === NodeAv.AVERROR_EOF) {
+                // No more frames available
+                break;
+            }
+            this.receiveFrame(receiveRet);
+        }
+        this.codecContext.flushBuffers();
+    }
+    close() {
+        this.codecContext.freeContext();
+        this.frame.free();
+        this.packet.free();
+    }
+}
+exports.NodeAvAudioDecoder = NodeAvAudioDecoder;

package/dist/modules/src/audio-encoder.d.ts

@@ -0,0 +1,35 @@
+/*!
+ * Copyright (c) 2026-present, Vanilagy and contributors
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+import { AudioCodec, AudioSample, CustomAudioEncoder, type MaybePromise } from 'mediabunny';
+import * as NodeAv from 'node-av';
+import { AdtsHeaderTemplate } from '../../../shared/aac-misc';
+export declare class NodeAvAudioEncoder extends CustomAudioEncoder {
+    frame: NodeAv.Frame;
+    packet: NodeAv.Packet;
+    avCodec: NodeAv.Codec;
+    codecContext: NodeAv.CodecContext | null;
+    firstExpectedTimestamp: number | null;
+    outputTimestampOffset: number;
+    resampler: NodeAv.SoftwareResampleContext | null;
+    inputParametersKey: string | null;
+    resamplerInputSampleRate: number | null;
+    nextResamplerPts: bigint | null;
+    dstFrame: NodeAv.Frame | null;
+    packetEmitted: boolean;
+    adtsHeaderTemplate: AdtsHeaderTemplate | null;
+    static supports(codec: AudioCodec, config: AudioEncoderConfig): boolean;
+    init(): Promise<void>;
+    createCodecContext(): Promise<void>;
+    encode(audioSample: AudioSample): Promise<void>;
+    pullResampledFrames(): Promise<void>;
+    sendFrameAndReceivePackets(frame: NodeAv.Frame | null): Promise<void>;
+    receivePacket(ret: number): void;
+    flush(): Promise<void>;
+    close(): MaybePromise<void>;
+}
+//# sourceMappingURL=audio-encoder.d.ts.map

package/dist/modules/src/audio-encoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-encoder.d.ts","sourceRoot":"","sources":["../../../src/audio-encoder.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACN,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,KAAK,YAAY,EAGjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,MAAM,MAAM,SAAS,CAAC;AAIlC,OAAO,EACN,kBAAkB,EAGlB,MAAM,0BAA0B,CAAC;AAUlC,qBAAa,kBAAmB,SAAQ,kBAAkB;IACzD,KAAK,EAAG,MAAM,CAAC,KAAK,CAAC;IACrB,MAAM,EAAG,MAAM,CAAC,MAAM,CAAC;IACvB,OAAO,EAAG,MAAM,CAAC,KAAK,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC,YAAY,GAAG,IAAI,CAAQ;IAChD,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC7C,qBAAqB,SAAK;IAE1B,SAAS,EAAE,MAAM,CAAC,uBAAuB,GAAG,IAAI,CAAQ;IACxD,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAQ;IACzC,wBAAwB,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC/C,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAQ;IACvC,QAAQ,EAAE,MAAM,CAAC,KAAK,GAAG,IAAI,CAAQ;IACrC,aAAa,UAAS;IACtB,kBAAkB,EAAE,kBAAkB,GAAG,IAAI,CAAQ;WAErC,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO;IA2B1E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBrB,kBAAkB;IA+BlB,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IA6E/C,mBAAmB;IAuBnB,0BAA0B,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,GAAG,IAAI;IAgB3D,aAAa,CAAC,GAAG,EAAE,MAAM;IAsGnB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2C5B,KAAK,IAAI,YAAY,CAAC,IAAI,CAAC;CAO3B"}

package/dist/modules/src/audio-encoder.js

@@ -0,0 +1,329 @@
+"use strict";
+/*!
+ * Copyright (c) 2026-present, Vanilagy and contributors
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeAvAudioEncoder = void 0;
+const mediabunny_1 = require("mediabunny");
+const NodeAv = __importStar(require("node-av"));
+const misc_1 = require("./misc");
+const misc_2 = require("../../../src/misc");
+const audio_sample_1 = require("./audio-sample");
+const aac_misc_1 = require("../../../shared/aac-misc");
+const AAC_SAMPLE_RATES = [96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000, 7350];
+const OPUS_SAMPLE_RATES = [8000, 12000, 16000, 24000, 48000];
+const MP3_SAMPLE_RATES = [8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000];
+const AC3_SAMPLE_RATES = [32000, 44100, 48000];
+const FRAME_SIZE_FALLBACK = 1024; // Just 'cause
+class NodeAvAudioEncoder extends mediabunny_1.CustomAudioEncoder {
+    constructor() {
+        super(...arguments);
+        this.codecContext = null;
+        this.firstExpectedTimestamp = null;
+        this.outputTimestampOffset = 0;
+        this.resampler = null;
+        this.inputParametersKey = null;
+        this.resamplerInputSampleRate = null;
+        this.nextResamplerPts = null;
+        this.dstFrame = null;
+        this.packetEmitted = false;
+        this.adtsHeaderTemplate = null;
+    }
+    static supports(codec, config) {
+        const { numberOfChannels, sampleRate } = config;
+        return (codec === 'aac' && numberOfChannels >= 1 && numberOfChannels <= 48
+            && AAC_SAMPLE_RATES.includes(sampleRate)) || (codec === 'opus' && numberOfChannels >= 1 && numberOfChannels <= 255
+            && OPUS_SAMPLE_RATES.includes(sampleRate)) || (codec === 'mp3' && numberOfChannels >= 1 && numberOfChannels <= 2
+            && MP3_SAMPLE_RATES.includes(sampleRate)) || (codec === 'vorbis' && numberOfChannels >= 1 && numberOfChannels <= 255
+            && sampleRate <= 200000) || (codec === 'flac' && numberOfChannels >= 1 && numberOfChannels <= 8
+            && sampleRate <= 655350) || (codec === 'ac3' && numberOfChannels >= 1 && numberOfChannels <= 6
+            && AC3_SAMPLE_RATES.includes(sampleRate)) || (codec === 'eac3' && numberOfChannels >= 1 && numberOfChannels <= 16
+            && AC3_SAMPLE_RATES.includes(sampleRate));
+    }
+    async init() {
+        this.frame = new NodeAv.Frame();
+        this.frame.alloc();
+        this.packet = new NodeAv.Packet();
+        this.packet.alloc();
+        const codecId = misc_1.CODEC_TO_CODEC_ID[this.codec];
+        (0, misc_2.assert)(codecId !== undefined);
+        const codec = NodeAv.Codec.findEncoder(codecId);
+        if (!codec) {
+            throw new Error(`Unable to obtain libav codec for '${this.codec}'.`);
+        }
+        this.avCodec = codec;
+        await this.createCodecContext();
+    }
+    async createCodecContext() {
+        (0, misc_2.assert)(this.codecContext === null);
+        const codecContext = new NodeAv.CodecContext();
+        codecContext.allocContext3(this.avCodec);
+        let sampleFormat = NodeAv.AV_SAMPLE_FMT_FLTP;
+        if (this.avCodec.sampleFormats && !this.avCodec.sampleFormats.includes(NodeAv.AV_SAMPLE_FMT_FLTP)) {
+            // Use a format that's supported
+            sampleFormat = this.avCodec.sampleFormats[0];
+        }
+        codecContext.sampleRate = this.config.sampleRate;
+        codecContext.channelLayout = (0, misc_1.getChannelLayout)(this.config.numberOfChannels);
+        codecContext.codecType = NodeAv.AVMEDIA_TYPE_AUDIO;
+        codecContext.codecId = misc_1.CODEC_TO_CODEC_ID[this.codec];
+        codecContext.sampleFormat = sampleFormat;
+        codecContext.timeBase = new NodeAv.Rational(1, this.config.sampleRate);
+        codecContext.bitRate = BigInt(this.config.bitrate ?? mediabunny_1.QUALITY_MEDIUM._toAudioBitrate(this.codec) ?? 0);
+        if (this.config.bitrateMode === 'constant') {
+            codecContext.rcMinRate = codecContext.bitRate;
+            codecContext.rcMaxRate = codecContext.bitRate;
+        }
+        const ret = await codecContext.open2();
+        NodeAv.FFmpegError.throwIfError(ret, 'Open codec context');
+        this.codecContext = codecContext;
+    }
+    async encode(audioSample) {
+        if (this.codecContext === null) {
+            await this.createCodecContext();
+            (0, misc_2.assert)(this.codecContext);
+        }
+        this.firstExpectedTimestamp ??= audioSample.timestamp;
+        if (audioSample._data instanceof audio_sample_1.AvFrameAudioSampleResource) {
+            this.frame.ref(audioSample._data.frame);
+        }
+        else {
+            (0, audio_sample_1.copyAudioSampleToAvFrame)(audioSample, this.frame);
+        }
+        this.frame.pts = BigInt(Math.round(audioSample.timestamp * this.config.sampleRate));
+        this.frame.duration = BigInt(Math.round(audioSample.duration * this.config.sampleRate));
+        this.frame.timeBase = new NodeAv.Rational(1, this.config.sampleRate);
+        const key = `${this.frame.sampleRate}:${this.frame.channels}:${this.frame.format}`;
+        if (this.inputParametersKey !== null && this.inputParametersKey !== key) {
+            throw new Error('Input audio parameters changed. For this audio encoder, you cannot change the input audio'
+                + ' parameters over time.');
+        }
+        this.inputParametersKey = key;
+        // We need the resampler when:
+        // 1. Format conversion is needed (sample format, sample rate, or channel count differs)
+        // 2. The codec requires fixed frame sizes
+        const requiresResampler = this.codecContext.frameSize > 0
+            || this.codecContext.sampleFormat !== this.frame.format
+            || this.codecContext.sampleRate !== this.frame.sampleRate
+            || this.codecContext.channels !== this.frame.channels;
+        if (requiresResampler) {
+            if (!this.resampler) {
+                this.resampler = new NodeAv.SoftwareResampleContext();
+                this.resamplerInputSampleRate = this.frame.sampleRate;
+                const outLayout = (0, misc_1.getChannelLayout)(this.codecContext.channels);
+                const inLayout = (0, misc_1.getChannelLayout)(this.frame.channels);
+                const ret = this.resampler.allocSetOpts2(outLayout, this.codecContext.sampleFormat, this.codecContext.sampleRate, inLayout, this.frame.format, this.frame.sampleRate);
+                NodeAv.FFmpegError.throwIfError(ret, 'allocSetOpts2');
+                const ret2 = this.resampler.init();
+                NodeAv.FFmpegError.throwIfError(ret2, 'init');
+                this.dstFrame = new NodeAv.Frame();
+                this.dstFrame.alloc();
+                this.dstFrame.channelLayout = outLayout;
+                this.dstFrame.sampleRate = this.codecContext.sampleRate;
+                this.dstFrame.format = this.codecContext.sampleFormat;
+                this.dstFrame.nbSamples = this.codecContext.frameSize || FRAME_SIZE_FALLBACK;
+                this.dstFrame.duration = BigInt(this.dstFrame.nbSamples);
+                this.dstFrame.allocBuffer();
+                this.nextResamplerPts = this.frame.pts;
+            }
+            const inputBuffers = this.frame.data;
+            if (!inputBuffers) {
+                throw new DOMException('Frame has no data', 'EncodingError');
+            }
+            await this.resampler.convert(null, 0, inputBuffers, this.frame.nbSamples);
+            await this.pullResampledFrames();
+        }
+        else {
+            await this.sendFrameAndReceivePackets(this.frame);
+        }
+    }
+    async pullResampledFrames() {
+        (0, misc_2.assert)(this.codecContext);
+        (0, misc_2.assert)(this.resampler);
+        (0, misc_2.assert)(this.dstFrame);
+        (0, misc_2.assert)(this.nextResamplerPts !== null);
+        const frameSize = this.codecContext.frameSize || FRAME_SIZE_FALLBACK;
+        while (true) {
+            const available = this.resampler.getOutSamples(0);
+            if (available < frameSize) {
+                break;
+            }
+            await this.resampler.convert(this.dstFrame.data, frameSize, null, 0);
+            this.dstFrame.pts = this.nextResamplerPts;
+            await this.sendFrameAndReceivePackets(this.dstFrame);
+            this.nextResamplerPts += BigInt(frameSize);
+        }
+    }
+    async sendFrameAndReceivePackets(frame) {
+        (0, misc_2.assert)(this.codecContext);
+        const ret = await this.codecContext.sendFrame(frame);
+        NodeAv.FFmpegError.throwIfError(ret, 'Send frame');
+        while (true) {
+            const receiveRet = await this.codecContext.receivePacket(this.packet);
+            if (receiveRet === NodeAv.AVERROR_EAGAIN || receiveRet === NodeAv.AVERROR_EOF) {
+                break;
+            }
+            this.receivePacket(receiveRet);
+        }
+    }
+    receivePacket(ret) {
+        (0, misc_2.assert)(this.codecContext);
+        (0, misc_2.assert)(this.firstExpectedTimestamp !== null);
+        NodeAv.FFmpegError.throwIfError(ret, 'Receive packet');
+        if (!this.packet.data) {
+            return;
+        }
+        let timestamp = Number(this.packet.pts) / this.codecContext.sampleRate;
+        const duration = Number(this.packet.duration) / this.codecContext.sampleRate;
+        let data = this.packet.data;
+        let metadata;
+        if (this.packetEmitted) {
+            metadata = {};
+        }
+        else {
+            // To compensate for any negative timestamp things that FFmpeg might do. It does these for a reason, to
+            // indicate encoder delay, but the notion of this is not yet supported in Mediabunny. Yes, this technically
+            // introduces audio sync drift.
+            this.outputTimestampOffset = Math.max(this.firstExpectedTimestamp - timestamp, 0);
+            const codecString = this.config.codec;
+            let description = this.codecContext.extraData
+                ? (0, misc_2.toUint8Array)(this.codecContext.extraData)
+                : undefined;
+            if (this.codec === 'aac') {
+                if (!description) {
+                    throw new Error('Extradata expected for AAC.');
+                }
+                // eslint-disable-next-line @stylistic/max-len
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+                const isAdts = this.config.aac?.format === 'adts';
+                if (isAdts) {
+                    const parsedConfig = (0, aac_misc_1.parseAacAudioSpecificConfig)(description);
+                    this.adtsHeaderTemplate = (0, aac_misc_1.buildAdtsHeaderTemplate)(parsedConfig);
+                    description = undefined; // Not used with 'adts' format
+                }
+            }
+            else if (this.codec === 'opus') {
+                if (!description) {
+                    // Technically not required by the WebCodecs/Mediabunny Codec Registry, but we strive to be better
+                    throw new Error('Extradata expected for Opus.');
+                }
+            }
+            else if (this.codec === 'vorbis') {
+                if (!description) {
+                    throw new Error('Extradata expected for Vorbis.');
+                }
+            }
+            else if (this.codec === 'flac') {
+                if (!description) {
+                    throw new Error('Extradata expected for FLAC.');
+                }
+                // FFmpeg uses the STREAMINFO block as the extradata, but WebCodecs wants a different format:
+                // 1. The bytes 0x66 0x4C 0x61 0x43 ("fLaC" in ASCII)
+                // 2. A metadata block (called the STREAMINFO block) as described in section 7 of [FLAC]
+                // 3. Other optional metadata blocks (not included here, because, well, they're optional)
+                description = new Uint8Array([
+                    0x66, 0x4c, 0x61, 0x43, // 'fLaC'
+                    128, 0, 0, description.byteLength,
+                    ...description,
+                ]);
+            }
+            metadata = {
+                decoderConfig: {
+                    codec: codecString,
+                    sampleRate: this.codecContext.sampleRate,
+                    numberOfChannels: this.codecContext.channels,
+                    description,
+                },
+            };
+        }
+        if (this.adtsHeaderTemplate) {
+            const frameLength = data.byteLength + this.adtsHeaderTemplate.header.byteLength;
+            this.adtsHeaderTemplate.bitstream.pos = 30;
+            this.adtsHeaderTemplate.bitstream.writeBits(13, frameLength);
+            const final = new Uint8Array(this.adtsHeaderTemplate.header.byteLength + data.byteLength);
+            final.set(this.adtsHeaderTemplate.header, 0);
+            final.set(data, this.adtsHeaderTemplate.header.byteLength);
+            data = final;
+        }
+        timestamp += this.outputTimestampOffset;
+        const packet = new mediabunny_1.EncodedPacket(data, 'key', timestamp, duration);
+        this.packetEmitted = true;
+        this.onPacket(packet, metadata);
+    }
+    async flush() {
+        if (!this.codecContext) {
+            return;
+        }
+        outer: if (this.resampler) {
+            (0, misc_2.assert)(this.resamplerInputSampleRate !== null);
+            const currentOutSamples = this.resampler.getOutSamples(0);
+            if (currentOutSamples === 0) {
+                break outer; // Clean cut-off point
+            }
+            const frameSize = this.codecContext.frameSize || FRAME_SIZE_FALLBACK;
+            (0, misc_2.assert)(currentOutSamples < frameSize); // Because if it's more, it would've already been retrieved
+            const inputSamplesNeeded = Math.ceil(((frameSize - currentOutSamples) / this.codecContext.sampleRate) * this.resamplerInputSampleRate);
+            this.resampler.injectSilence(inputSamplesNeeded);
+            await this.pullResampledFrames();
+        }
+        await this.sendFrameAndReceivePackets(null);
+        this.codecContext.freeContext();
+        this.codecContext = null;
+        this.packetEmitted = false;
+        this.firstExpectedTimestamp = null;
+        this.outputTimestampOffset = 0;
+        this.adtsHeaderTemplate = null;
+        this.resampler?.free();
+        this.resampler = null;
+        this.inputParametersKey = null;
+        this.resamplerInputSampleRate = null;
+        this.nextResamplerPts = null;
+        this.dstFrame?.free();
+        this.dstFrame = null;
+    }
+    close() {
+        this.codecContext?.freeContext();
+        this.frame.free();
+        this.packet.free();
+        this.dstFrame?.free();
+        this.resampler?.free();
+    }
+}
+exports.NodeAvAudioEncoder = NodeAvAudioEncoder;

package/dist/modules/src/audio-sample.d.ts

@@ -0,0 +1,38 @@
+/*!
+ * Copyright (c) 2026-present, Vanilagy and contributors
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+import { AudioSample, AudioSampleResource } from 'mediabunny';
+import * as NodeAv from 'node-av';
+/**
+ * A custom `AudioSampleResource` backed by NodeAV's
+ * [`Frame`](https://seydx.github.io/node-av/api/lib/classes/Frame.html), which in turn is backed by FFmpeg's
+ * [`AVFrame`](https://ffmpeg.org/doxygen/2.7/structAVFrame.html). You can use this resource to create `AudioSample`
+ * instances that are directly backed by FFmpeg's `AVFrame` without data having to be copied.
+ *
+ * When passed, the `Frame` is now owned by resource, meaning it takes care of closing the frame later. If you want to
+ * keep a copy for your own use, clone the frame first.
+ *
+ * @group \@mediabunny/server
+ * @public
+ */
+export declare class AvFrameAudioSampleResource extends AudioSampleResource {
+    /**
+     * The NodeAV [`Frame`](https://seydx.github.io/node-av/api/lib/classes/Frame.html) instance backing this resource.
+     * Access throws if the resource has already been closed.
+     */
+    get frame(): NodeAv.Frame;
+    constructor(frame: NodeAv.Frame);
+    getFormat(): AudioSampleFormat;
+    getSampleRate(): number;
+    getNumberOfChannels(): number;
+    getNumberOfFrames(): number;
+    getTimestamp(): number;
+    close(): void;
+    getDataPlane(planeIndex: number): Uint8Array;
+}
+export declare const copyAudioSampleToAvFrame: (sample: AudioSample, frame: NodeAv.Frame) => void;
+//# sourceMappingURL=audio-sample.d.ts.map