homebridge-plugin-utils 1.35.0 → 2.1.0

package/dist/ffmpeg/mp4-parser.d.ts

@@ -0,0 +1,94 @@
+/**
+ * ISO BMFF box type code for the `ftyp` (file type) box, encoded as a 32-bit big-endian integer. Useful for branching on {@link Mp4Box.type} without re-encoding
+ * the 4-character ASCII tag on every comparison.
+ *
+ * @category FFmpeg
+ */
+export declare const BOX_TYPE_FTYP = 1718909296;
+/**
+ * ISO BMFF box type code for the `mdat` (media data) box. The mdat box carries the sample payload for the preceding `moof` in an fMP4 fragment and is the end-of-segment
+ * marker that {@link ffmpeg/mp4-assembler!Mp4SegmentAssembler | Mp4SegmentAssembler} watches for.
+ *
+ * @category FFmpeg
+ */
+export declare const BOX_TYPE_MDAT = 1835295092;
+/**
+ * ISO BMFF box type code for the `moof` (movie fragment) box. Marks the start of a new fMP4 media fragment; the first `moof` in a stream also marks the end of the
+ * initialization segment.
+ *
+ * @category FFmpeg
+ */
+export declare const BOX_TYPE_MOOF = 1836019558;
+/**
+ * ISO BMFF box type code for the `moov` (movie) box. Part of the initialization segment that precedes the first `moof` in an fMP4 stream.
+ *
+ * @category FFmpeg
+ */
+export declare const BOX_TYPE_MOOV = 1836019574;
+/**
+ * A complete parsed ISO BMFF box emitted by {@link Mp4BoxParser}.
+ *
+ * @property bytes   - The complete box bytes, including the 8-byte header. The buffer is typically a zero-copy subarray view over the feed chunk; consumers that need
+ *                     to hold it past the iteration loop should copy with `Buffer.from()` if the upstream chunk lifetime is suspect.
+ * @property type    - The box type encoded as a 32-bit big-endian integer. Compare against the `BOX_TYPE_*` constants exported from this module; numeric comparison
+ *                     avoids the per-box string allocation that an ASCII tag comparison would incur.
+ *
+ * @category FFmpeg
+ */
+export interface Mp4Box {
+    bytes: Buffer;
+    type: number;
+}
+/**
+ * Pure stateful parser that converts a stream of ISO BMFF byte chunks into discrete {@link Mp4Box} records.
+ *
+ * Feed each chunk from the byte source through {@link Mp4BoxParser.consume} and iterate the returned values for every complete box now available. The parser carries
+ * only the bytes of an incomplete trailing box across calls; chunk boundaries in the middle of a box are handled transparently. A single chunk may produce zero, one, or
+ * many boxes depending on how the stream falls on chunk boundaries.
+ *
+ * The class is intentionally signal-free and event-free. It performs one job, synchronously, and leaves resource lifecycle and async consumption to the composing
+ * caller - typically {@link ffmpeg/mp4-assembler!Mp4SegmentAssembler | Mp4SegmentAssembler} for fMP4 streams driven by an FFmpeg process.
+ *
+ * @remarks **Trust boundary.** The parser does not bound the size field it reads from the wire. A source that claims a multi-gigabyte box size would cause the parser
+ * to accumulate incoming chunks into its internal pending buffer until the declared box completes. This is safe for trusted sources like FFmpeg stdout, where the
+ * size field reflects the actual payload. Callers feeding untrusted byte streams (e.g., user-uploaded media, network input from arbitrary peers) should impose their
+ * own bound - either by truncating chunks that would exceed a budget, or by wrapping the parser in a guard that rejects implausibly large declared sizes before
+ * feeding the chunk.
+ *
+ * @example
+ *
+ * ```ts
+ * import { BOX_TYPE_MDAT, Mp4BoxParser } from "homebridge-plugin-utils";
+ *
+ * const parser = new Mp4BoxParser();
+ *
+ * for(const box of parser.consume(chunk)) {
+ *
+ *   if(box.type === BOX_TYPE_MDAT) {
+ *
+ *     // We have just received a complete mdat box.
+ *   }
+ * }
+ * ```
+ *
+ * @see Mp4SegmentAssembler
+ *
+ * @category FFmpeg
+ */
+export declare class Mp4BoxParser {
+    #private;
+    /**
+     * Feed the parser a new byte chunk and yield every complete box now available.
+     *
+     * The iterable is single-pass: consume it with a `for...of` loop (or spread into an array) before the next call to `consume`. Emitted `bytes` are typically
+     * zero-copy subarray views over the input chunk; copy with `Buffer.from()` if you intend to hold a box past the upstream chunk's lifetime.
+     *
+     * Chunk boundaries in the middle of a box are handled internally: the incomplete trailing bytes are stashed and prepended to the next call's input.
+     *
+     * @param chunk - A contiguous slice of box-stream bytes from the source.
+     *
+     * @returns An iterable of every box contained in (or completed by) this chunk, in stream order.
+     */
+    consume(chunk: Buffer): Iterable<Mp4Box>;
+}
+//# sourceMappingURL=mp4-parser.d.ts.map

package/dist/ffmpeg/mp4-parser.js

@@ -0,0 +1,130 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * ffmpeg/mp4-parser.ts: Pure byte-to-record parser for ISO BMFF (fMP4) box streams.
+ */
+/**
+ * Pure stateful byte-to-record parser for ISO BMFF (fMP4) box streams.
+ *
+ * This module ships the streaming counterpart to the static predicates in {@link ffmpeg/fmp4! | fmp4}. The predicates (`findBox`, `isKeyframe`, `hasAudioTrack`,
+ * `splitMoofMdat`) answer one-shot questions about a complete Buffer. {@link Mp4BoxParser} solves a different problem: incrementally consuming an unbounded byte stream
+ * (typically FFmpeg stdout producing fMP4 fragments) and emitting each complete box as it becomes available.
+ *
+ * The parser is intentionally signal-free, event-free, and allocation-light. It carries only the bytes of an incomplete trailing box across calls and hands out
+ * zero-copy `subarray` views whenever possible. Resource lifetime, async consumption, and cancellation are not this class's job - those belong to the composing
+ * caller (see {@link ffmpeg/mp4-assembler!Mp4SegmentAssembler | Mp4SegmentAssembler}).
+ *
+ * @module
+ */
+import { BOX_HEADER_SIZE } from "./fmp4.js";
+/**
+ * ISO BMFF box type code for the `ftyp` (file type) box, encoded as a 32-bit big-endian integer. Useful for branching on {@link Mp4Box.type} without re-encoding
+ * the 4-character ASCII tag on every comparison.
+ *
+ * @category FFmpeg
+ */
+export const BOX_TYPE_FTYP = 0x66747970;
+/**
+ * ISO BMFF box type code for the `mdat` (media data) box. The mdat box carries the sample payload for the preceding `moof` in an fMP4 fragment and is the end-of-segment
+ * marker that {@link ffmpeg/mp4-assembler!Mp4SegmentAssembler | Mp4SegmentAssembler} watches for.
+ *
+ * @category FFmpeg
+ */
+export const BOX_TYPE_MDAT = 0x6D646174;
+/**
+ * ISO BMFF box type code for the `moof` (movie fragment) box. Marks the start of a new fMP4 media fragment; the first `moof` in a stream also marks the end of the
+ * initialization segment.
+ *
+ * @category FFmpeg
+ */
+export const BOX_TYPE_MOOF = 0x6D6F6F66;
+/**
+ * ISO BMFF box type code for the `moov` (movie) box. Part of the initialization segment that precedes the first `moof` in an fMP4 stream.
+ *
+ * @category FFmpeg
+ */
+export const BOX_TYPE_MOOV = 0x6D6F6F76;
+// Reusable empty buffer sentinel for the parser's pending-bytes state. Avoids repeated zero-byte allocations at the start of every parse cycle where no residual bytes
+// carried over from the previous chunk.
+const EMPTY_BUFFER = Buffer.alloc(0);
+/**
+ * Pure stateful parser that converts a stream of ISO BMFF byte chunks into discrete {@link Mp4Box} records.
+ *
+ * Feed each chunk from the byte source through {@link Mp4BoxParser.consume} and iterate the returned values for every complete box now available. The parser carries
+ * only the bytes of an incomplete trailing box across calls; chunk boundaries in the middle of a box are handled transparently. A single chunk may produce zero, one, or
+ * many boxes depending on how the stream falls on chunk boundaries.
+ *
+ * The class is intentionally signal-free and event-free. It performs one job, synchronously, and leaves resource lifecycle and async consumption to the composing
+ * caller - typically {@link ffmpeg/mp4-assembler!Mp4SegmentAssembler | Mp4SegmentAssembler} for fMP4 streams driven by an FFmpeg process.
+ *
+ * @remarks **Trust boundary.** The parser does not bound the size field it reads from the wire. A source that claims a multi-gigabyte box size would cause the parser
+ * to accumulate incoming chunks into its internal pending buffer until the declared box completes. This is safe for trusted sources like FFmpeg stdout, where the
+ * size field reflects the actual payload. Callers feeding untrusted byte streams (e.g., user-uploaded media, network input from arbitrary peers) should impose their
+ * own bound - either by truncating chunks that would exceed a budget, or by wrapping the parser in a guard that rejects implausibly large declared sizes before
+ * feeding the chunk.
+ *
+ * @example
+ *
+ * ```ts
+ * import { BOX_TYPE_MDAT, Mp4BoxParser } from "homebridge-plugin-utils";
+ *
+ * const parser = new Mp4BoxParser();
+ *
+ * for(const box of parser.consume(chunk)) {
+ *
+ *   if(box.type === BOX_TYPE_MDAT) {
+ *
+ *     // We have just received a complete mdat box.
+ *   }
+ * }
+ * ```
+ *
+ * @see Mp4SegmentAssembler
+ *
+ * @category FFmpeg
+ */
+export class Mp4BoxParser {
+    // Residual bytes from the previous call that did not complete a box. Prepended to the next chunk so a box split across two chunks is reassembled transparently. A
+    // zero-length sentinel is used when nothing is pending to avoid per-call allocation.
+    #pending = EMPTY_BUFFER;
+    /**
+     * Feed the parser a new byte chunk and yield every complete box now available.
+     *
+     * The iterable is single-pass: consume it with a `for...of` loop (or spread into an array) before the next call to `consume`. Emitted `bytes` are typically
+     * zero-copy subarray views over the input chunk; copy with `Buffer.from()` if you intend to hold a box past the upstream chunk's lifetime.
+     *
+     * Chunk boundaries in the middle of a box are handled internally: the incomplete trailing bytes are stashed and prepended to the next call's input.
+     *
+     * @param chunk - A contiguous slice of box-stream bytes from the source.
+     *
+     * @returns An iterable of every box contained in (or completed by) this chunk, in stream order.
+     */
+    *consume(chunk) {
+        // Prepend any pending partial box from the previous call. Buffer.concat is only paid when there is actually residual state; the common "chunk carries whole boxes
+        // and nothing is pending" path stays zero-allocation.
+        const buffer = (this.#pending.length > 0) ? Buffer.concat([this.#pending, chunk]) : chunk;
+        let offset = 0;
+        // Walk boxes by reading each header: 4 bytes size (big-endian) + 4 bytes type. The 32-bit type code is surfaced directly so consumers can compare against the
+        // exported BOX_TYPE_* constants without re-encoding a 4-character ASCII tag on every box.
+        while ((offset + BOX_HEADER_SIZE) <= buffer.length) {
+            const size = buffer.readUInt32BE(offset);
+            // Size must be at least the header size. Smaller values indicate corruption, a misaligned feed, or an unsupported extended-size box (size === 1 signals a 64-bit
+            // size field that we do not handle). Either way, the parser cannot make further progress - reset pending state so we do not busy-loop on the same bad byte on
+            // every subsequent chunk.
+            if (size < BOX_HEADER_SIZE) {
+                this.#pending = EMPTY_BUFFER;
+                return;
+            }
+            // Not enough bytes for a complete box yet. Stash the remainder - including the header - for the next call.
+            if ((offset + size) > buffer.length) {
+                break;
+            }
+            const type = buffer.readUInt32BE(offset + 4);
+            const bytes = buffer.subarray(offset, offset + size);
+            offset += size;
+            yield { bytes, type };
+        }
+        // Carry the trailing incomplete box (header + partial payload, or just the unconsumed tail) into the next call.
+        this.#pending = (offset === buffer.length) ? EMPTY_BUFFER : buffer.subarray(offset);
+    }
+}
+//# sourceMappingURL=mp4-parser.js.map

package/dist/ffmpeg/mp4-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mp4-parser.js","sourceRoot":"","sources":["../../src/ffmpeg/mp4-parser.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC;AAExC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC;AAExC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC;AAExC;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC;AAExC,uKAAuK;AACvK,wCAAwC;AACxC,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAkBrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,OAAO,YAAY;IAEvB,kKAAkK;IAClK,qFAAqF;IACrF,QAAQ,GAAW,YAAY,CAAC;IAEhC;;;;;;;;;;;OAWG;IACI,CAAC,OAAO,CAAC,KAAa;QAE3B,kKAAkK;QAClK,sDAAsD;QACtD,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QAC5F,IAAI,MAAM,GAAG,CAAC,CAAC;QAEf,8JAA8J;QAC9J,0FAA0F;QAC1F,OAAM,CAAC,MAAM,GAAG,eAAe,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAElD,MAAM,IAAI,GAAG,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YAEzC,iKAAiK;YACjK,8JAA8J;YAC9J,0BAA0B;YAC1B,IAAG,IAAI,GAAG,eAAe,EAAE,CAAC;gBAE1B,IAAI,CAAC,QAAQ,GAAG,YAAY,CAAC;gBAE7B,OAAO;YACT,CAAC;YAED,2GAA2G;YAC3G,IAAG,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;gBAEnC,MAAM;YACR,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;YAErD,MAAM,IAAI,IAAI,CAAC;YAEf,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACxB,CAAC;QAED,gHAAgH;QAChH,IAAI,CAAC,QAAQ,GAAG,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACtF,CAAC;CACF"}

package/dist/ffmpeg/options.d.ts

@@ -17,9 +17,22 @@
  *
  * @module
  */
-import { AudioRecordingCodecType, H264Level, H264Profile, type Logging } from "homebridge";
-import type { FfmpegCodecs } from "./codecs.js";
-import type { HomebridgePluginLogging } from "../util.js";
+import type { H264Level as H264LevelEnum, H264Profile as H264ProfileEnum } from "homebridge";
+import { AudioRecordingCodecType } from "./hap-enums.ts";
+import type { FfmpegCodecs } from "./codecs.ts";
+import type { Logger } from "../util.ts";
+declare const H264Level: {
+    readonly LEVEL3_1: H264LevelEnum.LEVEL3_1;
+    readonly LEVEL3_2: H264LevelEnum.LEVEL3_2;
+    readonly LEVEL4_0: H264LevelEnum.LEVEL4_0;
+};
+declare const H264Profile: {
+    readonly BASELINE: H264ProfileEnum.BASELINE;
+    readonly HIGH: H264ProfileEnum.HIGH;
+    readonly MAIN: H264ProfileEnum.MAIN;
+};
+type H264Level = H264LevelEnum;
+type H264Profile = H264ProfileEnum;
 /**
  * Configuration options for `FfmpegOptions`, defining transcoding, decoding, logging, and hardware acceleration settings.
  *
@@ -66,15 +79,17 @@ export interface FfmpegOptionsConfig {
     debug?: boolean;
     hardwareDecoding: boolean;
     hardwareTranscoding: boolean;
-    log: HomebridgePluginLogging | Logging;
+    log: Logger;
     name: () => string;
 }
 /**
- * Options used for configuring video encoding in FFmpeg operations.
+ * Options used for configuring audio encoding in FFmpeg operations.
  *
- * These options control output bitrate, framerate, resolution, H.264 profile and level, input framerate, and smart quality optimizations.
+ * The single field selects the AAC profile that drives encoder-specific arg emission in {@link FfmpegOptions.audioEncoder} - AAC-ELD (the HomeKit Secure Video event-
+ * recording default, lower bitrate, low-latency) versus AAC-LC (higher-quality livestream variant). The chosen profile maps to `aac_at` mode switches on macOS and to
+ * `libfdk_aac` flags elsewhere.
  *
- * @property codec               - Optional. Audio codec to encode (`AudioRecordingCodecType.AAC_ELD` or `AudioRecordingCodecType.AAC_LC`). Defaults to
+ * @property codec               - Optional. AAC profile to encode (`AudioRecordingCodecType.AAC_ELD` or `AudioRecordingCodecType.AAC_LC`). Defaults to
  *                                 `AudioRecordingCodecType.AAC_ELD`.
  *
  * @example
@@ -104,14 +119,21 @@ export interface AudioEncoderOptions {
  *
  * @property bitrate             - Target video bitrate, in kilobits per second.
  * @property fps                 - Target output frames per second.
- * @property hardwareDecoding    - Optional. If `true`, encoder options will account for hardware decoding (primarily for Intel QSV scenarios). Defaults to `true`.
+ * @property hardwareDecoding    - Optional. If `true`, the emitted encoder args assume the input stream has already been hardware-decoded (the GPU holds the frames).
+ *                                 Used by the transfer-filter logic to decide between `hwupload`, `hwdownload`, or neither. Defaults to the resolved
+ *                                 `FfmpegOptionsConfig.hardwareDecoding` value on the owning `FfmpegOptions` instance.
+ * @property hardwareTranscoding - Optional. If `true`, the emitted args select a hardware-accelerated encoder (`h264_videotoolbox` / `h264_qsv` / `h264_v4l2m2m`) and
+ *                                 the matching filter pipeline. If `false`, the args fall back to the libx264 software encoder. Defaults to the resolved
+ *                                 `FfmpegOptionsConfig.hardwareTranscoding` value on the owning `FfmpegOptions` instance.
  * @property height              - Output video height, in pixels.
  * @property idrInterval         - Interval (in seconds) between keyframes (IDR frames).
  * @property inputFps            - Input (source) frames per second.
  * @property level               - H.264 profile level for output.
  * @property profile             - H.264 profile for output.
- * @property smartQuality        - Optional and applicable only when not using hardware acceleration. If `true`, enables smart quality and variable bitrate optimizations.
- *                                 Defaults to `true`.
+ * @property smartQuality        - Optional. Enables variable-bitrate quality-constrained encoding on encoders that support it - libx264 (`-crf 20`), Apple Silicon
+ *                                 VideoToolbox (`-q:v 90`), and Intel QSV (`-global_quality 20`). Intel VideoToolbox and v4l2m2m have no quality-constraint mode and
+ *                                 always emit a fixed `-b:v` regardless. In all cases, `smartQuality` also adds `HOMEKIT_STREAMING_HEADROOM` to `-maxrate`, giving the
+ *                                 encoder a narrow band of variation above the target bitrate. Defaults to `true`.
  * @property width               - Output video width, in pixels.
  *
  * @example
@@ -155,6 +177,15 @@ export interface VideoEncoderOptions {
     smartQuality?: boolean;
     width: number;
 }
+/**
+ * Every hardware-transcode context this module distinguishes, each with a source-pixel ceiling that can differ on a given host. Live streaming and HKSV recording
+ * both transcode, but a host may admit one context to its hardware encoder and not the other (today: Raspberry Pi runs live transcoding on h264_v4l2m2m but falls
+ * HKSV recording back to libx264). Consumed by `maxSourcePixels` and the `recordEncoder` software-fallback so both derive the same per-context hardware-capability
+ * answer from one predicate.
+ *
+ * @category FFmpeg
+ */
+export type EncoderContext = "record" | "stream";
 /**
  * Provides Homebridge FFmpeg transcoding, decoding, and encoding options, selecting codecs, pixel formats, and hardware acceleration for the host system.
  *
@@ -194,27 +225,13 @@ export interface VideoEncoderOptions {
  * @category FFmpeg
  */
 export declare class FfmpegOptions {
+    #private;
     /**
-     * FFmpeg codec and hardware capabilities for the current host.
-     *
-     */
-    readonly codecSupport: FfmpegCodecs;
-    /**
-     * The configuration options used to initialize this instance.
+     * The configuration options used to initialize this instance. This is the single stored state on `FfmpegOptions`: every other public field on this class is either
+     * a getter that forwards to `this.config`, or a fixed constant independent of it (`audioDecoder`), so external callers have exactly one canonical path to each
+     * config-backed value and internal code never has to keep a parallel field in sync with `config` at construction time.
      */
     readonly config: FfmpegOptionsConfig;
-    /**
-     * Indicates if debug logging is enabled.
-     */
-    readonly debug: boolean;
-    /**
-     * Logging interface for output and errors.
-     */
-    readonly log: HomebridgePluginLogging | Logging;
-    /**
-     * Function returning the name for this options instance to be used for logging.
-     */
-    readonly name: () => string;
     /**
      * Creates an instance of Homebridge FFmpeg encoding and decoding options.
      *
@@ -228,50 +245,18 @@ export declare class FfmpegOptions {
      */
     constructor(options: FfmpegOptionsConfig);
     /**
-     * Determines and configures hardware-accelerated video decoding and transcoding for the host system.
-     *
-     * This internal method checks for the availability of hardware codecs and accelerators based on the host platform and updates
-     * FFmpeg options to use the best available hardware or falls back to software processing when necessary.
-     * It logs warnings or errors if required codecs or hardware acceleration are unavailable.
-     *
-     * This method is called automatically by the `FfmpegOptions` constructor and is not intended to be called directly.
-     *
-     * @returns `true` if hardware-accelerated transcoding is enabled after configuration, otherwise `false`.
-     *
-     * @example
-     *
-     * ```ts
-     * // This method is invoked by the FfmpegOptions constructor:
-     * const ffmpegOpts = new FfmpegOptions(optionsConfig);
-     *
-     * // Hardware acceleration configuration occurs automatically.
-     * // Developers typically do not need to call configureHwAccel() directly.
-     * ```
-     *
-     * @see FfmpegCodecs
-     * @see FfmpegOptions
+     * Indicates if debug logging is enabled. Normalizes `undefined` to `false` so callers always see a definite boolean regardless of whether the config object set
+     * the field explicitly.
      */
-    private configureHwAccel;
+    get debug(): boolean;
     /**
-     * Determines the required hardware transfer filters based on the decoding and encoding configuration.
-     *
-     * This method manages the transition between software and hardware processing contexts. When video data needs to move between the CPU and GPU for processing, we
-     * provide the appropriate FFmpeg filters to handle that transfer efficiently.
-     *
-     * @param options - Video encoder options including hardware decoding and transcoding state.
-     * @returns Array of filter strings for hardware upload or download operations.
+     * Logging interface for output and errors.
      */
-    private getHardwareTransferFilters;
+    get log(): Logger;
     /**
-     * Gets hardware device initialization options for encoders that need them.
-     *
-     * When we're using hardware encoding without hardware decoding, we need to initialize the hardware device context explicitly. This method provides the
-     * platform-specific initialization arguments required by FFmpeg.
-     *
-     * @param options - Video encoder options.
-     * @returns Array of FFmpeg arguments for hardware device initialization.
+     * Function returning the name for this options instance to be used for logging.
      */
-    private getHardwareDeviceInit;
+    get name(): () => string;
     /**
      * Returns the audio encoder arguments to use when transcoding.
      *
@@ -294,7 +279,8 @@ export declare class FfmpegOptions {
     /**
      * Returns the video decoder arguments to use for decoding video.
      *
-     * @param codec            - Optional. Codec to decode (`"av1"`, `"h264"` (default), or `"hevc"`).
+     * @param codec            - Optional. Codec to decode (`"av1"`, `"h264"` (default), or `"hevc"`; `"h265"` is accepted as an
+     *                           alias for `"hevc"`, and codec matching is case-insensitive).
      * @returns Array of FFmpeg command-line arguments for video decoding or an empty array if the codec isn't supported.
      *
      * @example
@@ -318,43 +304,6 @@ export declare class FfmpegOptions {
      * @returns The crop filter string for FFmpeg.
      */
     get cropFilter(): string;
-    /**
-     * Generate the appropriate scale filter for the current platform. This method returns platform-specific scale filters to leverage hardware acceleration capabilities
-     * where available.
-     */
-    private getScaleFilter;
-    /**
-     * Generates the default set of FFmpeg video encoder arguments for software transcoding using libx264.
-     *
-     * This method builds command-line options for the FFmpeg libx264 encoder based on the provided encoder options, including bitrate, H.264 profile and level, pixel
-     * format, frame rate, buffer size, and optional smart quality settings. It is used internally when hardware-accelerated transcoding is not enabled or supported.
-     *
-     * @param options            - The encoder options to use for generating FFmpeg arguments.
-     *
-     * @returns An array of FFmpeg command-line arguments for software video encoding.
-     *
-     * @example
-     *
-     * ```ts
-     * const encoderOptions: VideoEncoderOptions = {
-     *
-     *   bitrate: 2000,
-     *   fps: 30,
-     *   height: 720,
-     *   idrInterval: 2,
-     *   inputFps: 30,
-     *   level: H264Level.LEVEL3_1,
-     *   profile: H264Profile.MAIN,
-     *   smartQuality: true,
-     *   width: 1280
-     * };
-     *
-     * const args = ffmpegOpts['defaultVideoEncoderOptions'](encoderOptions);
-     * ```
-     *
-     * @see VideoEncoderOptions
-     */
-    private defaultVideoEncoderOptions;
     /**
      * Returns the video encoder options to use for HomeKit Secure Video (HKSV) event recording.
      *
@@ -376,51 +325,15 @@ export declare class FfmpegOptions {
      */
     streamEncoder(options: VideoEncoderOptions): string[];
     /**
-     * Returns the maximum pixel count supported by a specific hardware encoder on the host system, or `Infinity` if not limited.
-     *
-     * @returns Maximum supported pixel count.
-     */
-    get hostSystemMaxPixels(): number;
-    /**
-     * Converts a HomeKit H.264 level enum value to the corresponding FFmpeg string or numeric representation.
-     *
-     * This helper is used to translate between HomeKit's `H264Level` enum and the string or numeric format expected by FFmpeg's `-level:v` argument.
-     *
-     * @param level        - The H.264 level to translate.
-     * @param numeric      - Optional. If `true`, returns the numeric representation (e.g., "31"). If `false` or omitted, returns the standard string format (e.g., "3.1").
-     *
-     * @returns The FFmpeg-compatible H.264 level string or numeric value.
-     *
-     * @example
-     *
-     * ```ts
-     * ffmpegOpts['getH264Level'](H264Level.LEVEL3_1);      // "3.1"
-     *
-     * ffmpegOpts['getH264Level'](H264Level.LEVEL4_0, true); // "40"
-     * ```
-     *
-     * @see H264Level
-     */
-    private getH264Level;
-    /**
-     * Converts a HomeKit H.264 profile enum value to the corresponding FFmpeg string or numeric representation.
-     *
-     * This helper is used to translate between HomeKit's `H264Profile` enum and the string or numeric format expected by FFmpeg's `-profile:v` argument.
-     *
-     * @param profile - The H.264 profile to translate.
-     * @param numeric - Optional. If `true`, returns the numeric representation (e.g., "100"). If `false` or omitted, returns the standard string format (e.g., "high").
+     * Returns the maximum source pixel count the host's hardware transcode pipeline can ingest for the given encoding context, or `Infinity` when unconstrained.
      *
-     * @returns The FFmpeg-compatible H.264 profile string or numeric value.
-     *
-     * @example
-     *
-     * ```ts
-     * ffmpegOpts['getH264Profile'](H264Profile.HIGH);      // "high"
-     *
-     * ffmpegOpts['getH264Profile'](H264Profile.BASELINE, true); // "66"
-     * ```
+     * Only Raspberry Pi's GPU imposes a real limit; every other host is unconstrained. A context is capped only when it actually runs on that hardware path - so today live
+     * streaming on a Pi returns the RPi ceiling while recording on a Pi returns `Infinity` (it software-encodes). Consumers apply this value blindly; the "why" lives here.
      *
-     * @see H264Profile
+     * @param context - The encoding context whose ceiling is requested.
+     * @returns Maximum supported source pixel count for `context`.
      */
-    private getH264Profile;
+    maxSourcePixels(context: EncoderContext): number;
 }
+export {};
+//# sourceMappingURL=options.d.ts.map