node-av-light 0.0.0-stage → 7.1.0-beta.1

package/dist/api/utilities/audio-sample.js

@@ -0,0 +1,112 @@
+import { bindings } from '../../lib/binding.js';
+import { FFmpegError } from '../../lib/error.js';
+/**
+ * Audio sample buffer utilities.
+ *
+ * Provides static methods for allocating and managing audio sample buffers.
+ * These utilities handle the memory layout for various sample formats,
+ * including planar formats where each channel has its own buffer.
+ *
+ * @example
+ * ```typescript
+ * import { AudioSampleUtils } from 'node-av';
+ * import { AV_SAMPLE_FMT_FLTP, AV_SAMPLE_FMT_S16 } from 'node-av/constants';
+ *
+ * // Allocate audio buffers for stereo float planar
+ * const audio = AudioSampleUtils.alloc(2, 1024, AV_SAMPLE_FMT_FLTP, 0);
+ * console.log(`Allocated ${audio.size} bytes`);
+ * console.log(`${audio.data.length} buffers (one per channel)`);
+ *
+ * // Get buffer size for packed format
+ * const size = AudioSampleUtils.getBufferSize(2, 1024, AV_SAMPLE_FMT_S16, 0);
+ * console.log(`S16 stereo needs ${size.size} bytes`);
+ * ```
+ */
+export class AudioSampleUtils {
+    // Private constructor to prevent instantiation
+    constructor() { }
+    /**
+     * Allocate audio sample buffers.
+     *
+     * Allocates buffers for audio samples. For planar formats, allocates
+     * separate buffers for each channel. For packed formats, allocates
+     * a single interleaved buffer.
+     * Direct mapping to av_samples_alloc()
+     *
+     * @param nbChannels - Number of audio channels
+     *
+     * @param nbSamples - Number of samples per channel
+     *
+     * @param sampleFmt - Audio sample format
+     *
+     * @param align - Buffer alignment (0 for default)
+     *
+     * @returns Allocation result with buffers and size information
+     *
+     * @throws {FFmpegError} On allocation failure
+     *
+     * @example
+     * ```typescript
+     * import { AudioSampleUtils } from 'node-av';
+     * import { AV_SAMPLE_FMT_FLTP, AV_SAMPLE_FMT_S16 } from 'node-av/constants';
+     *
+     * // Allocate for planar format (separate buffer per channel)
+     * const planar = AudioSampleUtils.alloc(2, 1024, AV_SAMPLE_FMT_FLTP, 0);
+     * console.log(`Planar: ${planar.data.length} buffers`); // 2 buffers
+     *
+     * // Allocate for packed format (single interleaved buffer)
+     * const packed = AudioSampleUtils.alloc(2, 1024, AV_SAMPLE_FMT_S16, 0);
+     * console.log(`Packed: ${packed.data.length} buffer`);  // 1 buffer
+     * ```
+     */
+    static alloc(nbChannels, nbSamples, sampleFmt, align) {
+        const result = bindings.avSamplesAlloc(nbChannels, nbSamples, sampleFmt, align);
+        if (typeof result === 'number') {
+            FFmpegError.throwIfError(result, 'Failed to allocate audio samples');
+        }
+        return result;
+    }
+    /**
+     * Get required buffer size for audio samples.
+     *
+     * Calculates the buffer size needed to store audio samples with the
+     * given parameters. Does not allocate any memory.
+     * Direct mapping to av_samples_get_buffer_size()
+     *
+     * @param nbChannels - Number of audio channels
+     *
+     * @param nbSamples - Number of samples per channel
+     *
+     * @param sampleFmt - Audio sample format
+     *
+     * @param align - Buffer alignment (0 for default)
+     *
+     * @returns Buffer size and line size information
+     *
+     * @throws {FFmpegError} On invalid parameters
+     *
+     * @example
+     * ```typescript
+     * import { AudioSampleUtils } from 'node-av';
+     * import { AV_SAMPLE_FMT_FLT, AV_SAMPLE_FMT_S16P } from 'node-av/constants';
+     *
+     * // Calculate size for packed float (32-bit) stereo
+     * const floatSize = AudioSampleUtils.getBufferSize(2, 1024, AV_SAMPLE_FMT_FLT, 0);
+     * console.log(`Float stereo: ${floatSize.size} bytes total`);
+     * console.log(`Line size: ${floatSize.linesize} bytes`);
+     *
+     * // Calculate size for planar 16-bit stereo
+     * const planarSize = AudioSampleUtils.getBufferSize(2, 1024, AV_SAMPLE_FMT_S16P, 0);
+     * console.log(`S16 planar: ${planarSize.size} bytes total`);
+     * console.log(`Per channel: ${planarSize.linesize} bytes`);
+     * ```
+     */
+    static getBufferSize(nbChannels, nbSamples, sampleFmt, align) {
+        const result = bindings.avSamplesGetBufferSize(nbChannels, nbSamples, sampleFmt, align);
+        if (typeof result === 'number') {
+            FFmpegError.throwIfError(result, 'Failed to get audio buffer size');
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=audio-sample.js.map

package/dist/api/utilities/audio-sample.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-sample.js","sourceRoot":"","sources":["../../../src/api/utilities/audio-sample.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA0BjD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,gBAAgB;IAC3B,+CAA+C;IAC/C,gBAAuB,CAAC;IAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,MAAM,CAAC,KAAK,CAAC,UAAkB,EAAE,SAAiB,EAAE,SAAyB,EAAE,KAAa;QAC1F,MAAM,MAAM,GAAG,QAAQ,CAAC,cAAc,CAAC,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;QAChF,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC/B,WAAW,CAAC,YAAY,CAAC,MAAM,EAAE,kCAAkC,CAAC,CAAC;QACvE,CAAC;QACD,OAAO,MAA+B,CAAC;IACzC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,MAAM,CAAC,aAAa,CAAC,UAAkB,EAAE,SAAiB,EAAE,SAAyB,EAAE,KAAa;QAClG,MAAM,MAAM,GAAG,QAAQ,CAAC,sBAAsB,CAAC,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;QACxF,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC/B,WAAW,CAAC,YAAY,CAAC,MAAM,EAAE,iCAAiC,CAAC,CAAC;QACtE,CAAC;QACD,OAAO,MAA+B,CAAC;IACzC,CAAC;CACF"}

package/dist/api/utilities/audio-transcode.d.ts

@@ -0,0 +1,20 @@
+import { Decoder } from '../decoder.js';
+import type { Stream } from '../../lib/stream.js';
+import type { DecoderOptions } from '../decoder.js';
+/**
+ * Open the audio decoder of a transcode.
+ *
+ * Opus is decoded with libopus when the build has it. FFmpeg's own Opus decoder
+ * loses sync on in-band FEC (LBRR) frames and turns the rest of the packet into
+ * loud noise without reporting an error. Cameras that send SILK with FEC, such as
+ * Ring, crackle through it.
+ *
+ * @param stream - The audio stream
+ *
+ * @param options - Decoder options
+ *
+ * @returns The decoder
+ *
+ * @internal
+ */
+export declare function openAudioDecoder(stream: Stream, options: DecoderOptions): Promise<Decoder>;

package/dist/api/utilities/audio-transcode.js

@@ -0,0 +1,27 @@
+import { AV_CODEC_ID_OPUS } from '../../constants/constants.js';
+import { FF_DECODER_LIBOPUS } from '../../constants/decoders.js';
+import { Codec } from '../../lib/codec.js';
+import { Decoder } from '../decoder.js';
+/**
+ * Open the audio decoder of a transcode.
+ *
+ * Opus is decoded with libopus when the build has it. FFmpeg's own Opus decoder
+ * loses sync on in-band FEC (LBRR) frames and turns the rest of the packet into
+ * loud noise without reporting an error. Cameras that send SILK with FEC, such as
+ * Ring, crackle through it.
+ *
+ * @param stream - The audio stream
+ *
+ * @param options - Decoder options
+ *
+ * @returns The decoder
+ *
+ * @internal
+ */
+export async function openAudioDecoder(stream, options) {
+    if (stream.codecpar.codecId === AV_CODEC_ID_OPUS && Codec.findDecoderByName(FF_DECODER_LIBOPUS)) {
+        return await Decoder.create(stream, FF_DECODER_LIBOPUS, options);
+    }
+    return await Decoder.create(stream, options);
+}
+//# sourceMappingURL=audio-transcode.js.map

package/dist/api/utilities/audio-transcode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-transcode.js","sourceRoot":"","sources":["../../../src/api/utilities/audio-transcode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAKxC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAc,EAAE,OAAuB;IAC5E,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,KAAK,gBAAgB,IAAI,KAAK,CAAC,iBAAiB,CAAC,kBAAkB,CAAC,EAAE,CAAC;QAChG,OAAO,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,EAAE,OAAO,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC/C,CAAC"}

package/dist/api/utilities/channel-layout.d.ts

@@ -0,0 +1,76 @@
+import type { ChannelLayout } from '../../lib/types.js';
+/**
+ * Audio channel layout utilities.
+ *
+ * Provides static methods for describing and working with audio channel layouts.
+ * Channel layouts define the arrangement and meaning of audio channels in
+ * multi-channel audio.
+ *
+ * @example
+ * ```typescript
+ * import { ChannelLayoutUtils } from 'node-av';
+ * import { AV_CHANNEL_ORDER_NATIVE } from 'node-av/constants';
+ *
+ * // Describe a stereo layout
+ * const stereo: ChannelLayout = {
+ *   order: AV_CHANNEL_ORDER_NATIVE,
+ *   nb_channels: 2,
+ *   u: { mask: 0x3n } // FL | FR
+ * };
+ *
+ * const description = ChannelLayoutUtils.describe(stereo);
+ * console.log(description); // "stereo"
+ *
+ * // Describe a 5.1 layout
+ * const surround: ChannelLayout = {
+ *   order: AV_CHANNEL_ORDER_NATIVE,
+ *   nb_channels: 6,
+ *   u: { mask: 0x3Fn } // FL | FR | FC | LFE | BL | BR
+ * };
+ *
+ * console.log(ChannelLayoutUtils.describe(surround)); // "5.1"
+ * ```
+ */
+export declare class ChannelLayoutUtils {
+    private constructor();
+    /**
+     * Get string description of channel layout.
+     *
+     * Returns a human-readable string describing the channel layout.
+     * Direct mapping to av_channel_layout_describe()
+     *
+     * @param channelLayout - Channel layout to describe
+     *
+     * @returns String description, or null on error
+     *
+     * @example
+     * ```typescript
+     * import { ChannelLayoutUtils } from 'node-av';
+     * import { AV_CHANNEL_ORDER_NATIVE, AV_CHANNEL_ORDER_CUSTOM } from 'node-av/constants';
+     *
+     * // Standard layouts
+     * const mono: ChannelLayout = {
+     *   order: AV_CHANNEL_ORDER_NATIVE,
+     *   nb_channels: 1,
+     *   u: { mask: 0x4n } // FC
+     * };
+     * console.log(ChannelLayoutUtils.describe(mono)); // "mono"
+     *
+     * const stereo: ChannelLayout = {
+     *   order: AV_CHANNEL_ORDER_NATIVE,
+     *   nb_channels: 2,
+     *   u: { mask: 0x3n } // FL | FR
+     * };
+     * console.log(ChannelLayoutUtils.describe(stereo)); // "stereo"
+     *
+     * // Custom layout
+     * const custom: ChannelLayout = {
+     *   order: AV_CHANNEL_ORDER_CUSTOM,
+     *   nb_channels: 3,
+     *   u: { map: null }
+     * };
+     * console.log(ChannelLayoutUtils.describe(custom)); // "3 channels"
+     * ```
+     */
+    static describe(channelLayout: Partial<ChannelLayout>): string | null;
+}

package/dist/api/utilities/channel-layout.js

@@ -0,0 +1,80 @@
+import { bindings } from '../../lib/binding.js';
+/**
+ * Audio channel layout utilities.
+ *
+ * Provides static methods for describing and working with audio channel layouts.
+ * Channel layouts define the arrangement and meaning of audio channels in
+ * multi-channel audio.
+ *
+ * @example
+ * ```typescript
+ * import { ChannelLayoutUtils } from 'node-av';
+ * import { AV_CHANNEL_ORDER_NATIVE } from 'node-av/constants';
+ *
+ * // Describe a stereo layout
+ * const stereo: ChannelLayout = {
+ *   order: AV_CHANNEL_ORDER_NATIVE,
+ *   nb_channels: 2,
+ *   u: { mask: 0x3n } // FL | FR
+ * };
+ *
+ * const description = ChannelLayoutUtils.describe(stereo);
+ * console.log(description); // "stereo"
+ *
+ * // Describe a 5.1 layout
+ * const surround: ChannelLayout = {
+ *   order: AV_CHANNEL_ORDER_NATIVE,
+ *   nb_channels: 6,
+ *   u: { mask: 0x3Fn } // FL | FR | FC | LFE | BL | BR
+ * };
+ *
+ * console.log(ChannelLayoutUtils.describe(surround)); // "5.1"
+ * ```
+ */
+export class ChannelLayoutUtils {
+    // Private constructor to prevent instantiation
+    constructor() { }
+    /**
+     * Get string description of channel layout.
+     *
+     * Returns a human-readable string describing the channel layout.
+     * Direct mapping to av_channel_layout_describe()
+     *
+     * @param channelLayout - Channel layout to describe
+     *
+     * @returns String description, or null on error
+     *
+     * @example
+     * ```typescript
+     * import { ChannelLayoutUtils } from 'node-av';
+     * import { AV_CHANNEL_ORDER_NATIVE, AV_CHANNEL_ORDER_CUSTOM } from 'node-av/constants';
+     *
+     * // Standard layouts
+     * const mono: ChannelLayout = {
+     *   order: AV_CHANNEL_ORDER_NATIVE,
+     *   nb_channels: 1,
+     *   u: { mask: 0x4n } // FC
+     * };
+     * console.log(ChannelLayoutUtils.describe(mono)); // "mono"
+     *
+     * const stereo: ChannelLayout = {
+     *   order: AV_CHANNEL_ORDER_NATIVE,
+     *   nb_channels: 2,
+     *   u: { mask: 0x3n } // FL | FR
+     * };
+     * console.log(ChannelLayoutUtils.describe(stereo)); // "stereo"
+     *
+     * // Custom layout
+     * const custom: ChannelLayout = {
+     *   order: AV_CHANNEL_ORDER_CUSTOM,
+     *   nb_channels: 3,
+     *   u: { map: null }
+     * };
+     * console.log(ChannelLayoutUtils.describe(custom)); // "3 channels"
+     * ```
+     */
+    static describe(channelLayout) {
+        return bindings.avChannelLayoutDescribe(channelLayout);
+    }
+}
+//# sourceMappingURL=channel-layout.js.map

package/dist/api/utilities/channel-layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-layout.js","sourceRoot":"","sources":["../../../src/api/utilities/channel-layout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAIhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,OAAO,kBAAkB;IAC7B,+CAA+C;IAC/C,gBAAuB,CAAC;IAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACH,MAAM,CAAC,QAAQ,CAAC,aAAqC;QACnD,OAAO,QAAQ,CAAC,uBAAuB,CAAC,aAAa,CAAC,CAAC;IACzD,CAAC;CACF"}

package/dist/api/utilities/codec-format.d.ts

@@ -0,0 +1,87 @@
+import type { AVPixelFormat, AVSampleFormat } from '../../constants/index.js';
+import type { ChannelLayout } from '../../lib/types.js';
+/**
+ * Pick a codec-supported sample rate, keeping the input rate when accepted and
+ * otherwise choosing the numerically nearest supported one.
+ *
+ * @param rate - Input sample rate in Hz
+ *
+ * @param supported - Codec's supported sample rates, or null when unrestricted
+ *
+ * @returns A sample rate the codec accepts
+ *
+ * @example
+ * ```typescript
+ * pickSupportedRate(48000, [44100, 48000]); // 48000 (kept)
+ * pickSupportedRate(96000, [44100, 48000]); // 48000 (nearest supported)
+ * pickSupportedRate(48000, null);           // 48000 (codec unrestricted)
+ * ```
+ */
+export declare function pickSupportedRate(rate: number, supported: number[] | null): number;
+/**
+ * Pick a codec-supported sample format, keeping the input when accepted.
+ *
+ * When the input format is unsupported, prefers the lowest-precision supported
+ * format that still meets the input's bit depth (so converting incurs no silent
+ * precision loss); if none reach it, takes the highest-precision one available.
+ * Ties break toward matching planar/packed layout. This improves on FFmpeg CLI's
+ * naive "first supported format" fallback without any downside.
+ *
+ * @param fmt - Input sample format
+ *
+ * @param supported - Codec's supported sample formats, or null when unrestricted
+ *
+ * @returns A sample format the codec accepts
+ *
+ * @example
+ * ```typescript
+ * import { AV_SAMPLE_FMT_S32, AV_SAMPLE_FMT_S16, AV_SAMPLE_FMT_FLTP } from 'node-av/constants';
+ *
+ * // s32 input: prefer fltp (preserves bit depth) over the lossy s16 a naive pick would take
+ * pickSupportedSampleFormat(AV_SAMPLE_FMT_S32, [AV_SAMPLE_FMT_S16, AV_SAMPLE_FMT_FLTP]); // fltp
+ * ```
+ */
+export declare function pickSupportedSampleFormat(fmt: AVSampleFormat, supported: AVSampleFormat[] | null): AVSampleFormat;
+/**
+ * Pick a codec-supported channel layout.
+ *
+ * Keeps the input layout when the codec accepts its channel count, otherwise picks
+ * the supported layout with the nearest channel count (rather than blindly the
+ * first), minimizing how much up/down-mixing the resampler must perform.
+ *
+ * @param layout - Input channel layout
+ *
+ * @param supported - Codec's supported channel layouts, or null when unrestricted
+ *
+ * @returns A channel layout the codec accepts
+ *
+ * @example
+ * ```typescript
+ * import { avChannelLayoutDefault } from 'node-av';
+ *
+ * // 7.1 (8ch) input into a codec supporting stereo + 5.1 -> nearest count is 5.1 (6ch)
+ * const picked = pickSupportedLayout(avChannelLayoutDefault(8), [avChannelLayoutDefault(2), avChannelLayoutDefault(6)]);
+ * console.log(picked.nbChannels); // 6
+ * ```
+ */
+export declare function pickSupportedLayout(layout: ChannelLayout, supported: ChannelLayout[] | null): ChannelLayout;
+/**
+ * Pick a codec-supported pixel format, keeping the input when accepted and
+ * otherwise the least-loss supported format (via `avcodec_find_best_pix_fmt_of_list`,
+ * which weighs color depth, chroma subsampling, and alpha).
+ *
+ * @param fmt - Input pixel format
+ *
+ * @param supported - Codec's supported pixel formats, or null when unrestricted
+ *
+ * @returns A pixel format the codec accepts
+ *
+ * @example
+ * ```typescript
+ * import { AV_PIX_FMT_RGB24, AV_PIX_FMT_YUV420P, AV_PIX_FMT_YUV444P } from 'node-av/constants';
+ *
+ * // rgb24 into a codec's formats -> yuv444p (least chroma loss, not the first entry)
+ * pickSupportedPixelFormat(AV_PIX_FMT_RGB24, [AV_PIX_FMT_YUV420P, AV_PIX_FMT_YUV444P]); // yuv444p
+ * ```
+ */
+export declare function pickSupportedPixelFormat(fmt: AVPixelFormat, supported: AVPixelFormat[] | null): AVPixelFormat;

package/dist/api/utilities/codec-format.js

@@ -0,0 +1,117 @@
+import { avcodecFindBestPixFmtOfList, avGetBytesPerSample, avSampleFmtIsPlanar } from '../../lib/utilities.js';
+/**
+ * Pick a codec-supported sample rate, keeping the input rate when accepted and
+ * otherwise choosing the numerically nearest supported one.
+ *
+ * @param rate - Input sample rate in Hz
+ *
+ * @param supported - Codec's supported sample rates, or null when unrestricted
+ *
+ * @returns A sample rate the codec accepts
+ *
+ * @example
+ * ```typescript
+ * pickSupportedRate(48000, [44100, 48000]); // 48000 (kept)
+ * pickSupportedRate(96000, [44100, 48000]); // 48000 (nearest supported)
+ * pickSupportedRate(48000, null);           // 48000 (codec unrestricted)
+ * ```
+ */
+export function pickSupportedRate(rate, supported) {
+    if (!supported || supported.length === 0 || supported.includes(rate)) {
+        return rate;
+    }
+    return supported.reduce((best, r) => (Math.abs(r - rate) < Math.abs(best - rate) ? r : best), supported[0]);
+}
+/**
+ * Pick a codec-supported sample format, keeping the input when accepted.
+ *
+ * When the input format is unsupported, prefers the lowest-precision supported
+ * format that still meets the input's bit depth (so converting incurs no silent
+ * precision loss); if none reach it, takes the highest-precision one available.
+ * Ties break toward matching planar/packed layout. This improves on FFmpeg CLI's
+ * naive "first supported format" fallback without any downside.
+ *
+ * @param fmt - Input sample format
+ *
+ * @param supported - Codec's supported sample formats, or null when unrestricted
+ *
+ * @returns A sample format the codec accepts
+ *
+ * @example
+ * ```typescript
+ * import { AV_SAMPLE_FMT_S32, AV_SAMPLE_FMT_S16, AV_SAMPLE_FMT_FLTP } from 'node-av/constants';
+ *
+ * // s32 input: prefer fltp (preserves bit depth) over the lossy s16 a naive pick would take
+ * pickSupportedSampleFormat(AV_SAMPLE_FMT_S32, [AV_SAMPLE_FMT_S16, AV_SAMPLE_FMT_FLTP]); // fltp
+ * ```
+ */
+export function pickSupportedSampleFormat(fmt, supported) {
+    if (!supported || supported.length === 0 || supported.includes(fmt)) {
+        return fmt;
+    }
+    const inBytes = avGetBytesPerSample(fmt);
+    const inPlanar = avSampleFmtIsPlanar(fmt);
+    // Reaching the input's bit depth dominates the score; among those the smallest
+    // excess wins (and among formats that fall short, the highest depth). The planar
+    // match is a final tie-break.
+    const score = (cand) => {
+        const bytes = avGetBytesPerSample(cand);
+        const planar = avSampleFmtIsPlanar(cand) === inPlanar ? 1 : 0;
+        return (bytes >= inBytes ? 1_000_000 - (bytes - inBytes) * 1000 : bytes * 1000) + planar;
+    };
+    return supported.reduce((best, cand) => (score(cand) > score(best) ? cand : best), supported[0]);
+}
+/**
+ * Pick a codec-supported channel layout.
+ *
+ * Keeps the input layout when the codec accepts its channel count, otherwise picks
+ * the supported layout with the nearest channel count (rather than blindly the
+ * first), minimizing how much up/down-mixing the resampler must perform.
+ *
+ * @param layout - Input channel layout
+ *
+ * @param supported - Codec's supported channel layouts, or null when unrestricted
+ *
+ * @returns A channel layout the codec accepts
+ *
+ * @example
+ * ```typescript
+ * import { avChannelLayoutDefault } from 'node-av';
+ *
+ * // 7.1 (8ch) input into a codec supporting stereo + 5.1 -> nearest count is 5.1 (6ch)
+ * const picked = pickSupportedLayout(avChannelLayoutDefault(8), [avChannelLayoutDefault(2), avChannelLayoutDefault(6)]);
+ * console.log(picked.nbChannels); // 6
+ * ```
+ */
+export function pickSupportedLayout(layout, supported) {
+    if (!supported || supported.length === 0 || supported.some((l) => l.nbChannels === layout.nbChannels)) {
+        return layout;
+    }
+    return supported.reduce((best, l) => (Math.abs(l.nbChannels - layout.nbChannels) < Math.abs(best.nbChannels - layout.nbChannels) ? l : best), supported[0]);
+}
+/**
+ * Pick a codec-supported pixel format, keeping the input when accepted and
+ * otherwise the least-loss supported format (via `avcodec_find_best_pix_fmt_of_list`,
+ * which weighs color depth, chroma subsampling, and alpha).
+ *
+ * @param fmt - Input pixel format
+ *
+ * @param supported - Codec's supported pixel formats, or null when unrestricted
+ *
+ * @returns A pixel format the codec accepts
+ *
+ * @example
+ * ```typescript
+ * import { AV_PIX_FMT_RGB24, AV_PIX_FMT_YUV420P, AV_PIX_FMT_YUV444P } from 'node-av/constants';
+ *
+ * // rgb24 into a codec's formats -> yuv444p (least chroma loss, not the first entry)
+ * pickSupportedPixelFormat(AV_PIX_FMT_RGB24, [AV_PIX_FMT_YUV420P, AV_PIX_FMT_YUV444P]); // yuv444p
+ * ```
+ */
+export function pickSupportedPixelFormat(fmt, supported) {
+    if (!supported || supported.length === 0 || supported.includes(fmt)) {
+        return fmt;
+    }
+    return avcodecFindBestPixFmtOfList(supported, fmt);
+}
+//# sourceMappingURL=codec-format.js.map

package/dist/api/utilities/codec-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec-format.js","sourceRoot":"","sources":["../../../src/api/utilities/codec-format.ts"],"names":[],"mappings":"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"}

package/dist/api/utilities/context-options.d.ts

@@ -0,0 +1,25 @@
+type IfEquals<X, Y, A, B> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? A : B;
+type WritableKeys<T> = {
+    [P in keyof T]-?: IfEquals<{
+        [Q in P]: T[P];
+    }, {
+        -readonly [Q in P]: T[P];
+    }, P, never>;
+}[keyof T];
+export type ContextOptions<T> = Partial<{
+    [K in WritableKeys<T> as K extends string ? (T[K] extends (...args: never[]) => unknown ? never : K) : never]: T[K];
+}>;
+/**
+ * Apply a {@link ContextOptions} bag onto a native context wrapper.
+ *
+ * Assigns each provided (defined) field via the wrapper's setter. No-ops when
+ * `options` is undefined.
+ *
+ * @param target - The native context wrapper to mutate
+ *
+ * @param options - The field/value bag to apply
+ *
+ * @internal
+ */
+export declare function applyContextOptions<T extends object>(target: T, options: ContextOptions<T> | undefined): void;
+export {};

package/dist/api/utilities/context-options.js

@@ -0,0 +1,23 @@
+/**
+ * Apply a {@link ContextOptions} bag onto a native context wrapper.
+ *
+ * Assigns each provided (defined) field via the wrapper's setter. No-ops when
+ * `options` is undefined.
+ *
+ * @param target - The native context wrapper to mutate
+ *
+ * @param options - The field/value bag to apply
+ *
+ * @internal
+ */
+export function applyContextOptions(target, options) {
+    if (!options) {
+        return;
+    }
+    for (const [key, value] of Object.entries(options)) {
+        if (value !== undefined) {
+            target[key] = value;
+        }
+    }
+}
+//# sourceMappingURL=context-options.js.map

package/dist/api/utilities/context-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-options.js","sourceRoot":"","sources":["../../../src/api/utilities/context-options.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAmB,MAAS,EAAE,OAAsC;IACrG,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO;IACT,CAAC;IAED,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACvB,MAAkC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACnD,CAAC;IACH,CAAC;AACH,CAAC"}