homebridge-plugin-utils 1.35.0 → 2.0.0

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