homebridge-plugin-utils 1.33.0 → 1.34.0

package/dist/ffmpeg/record.d.ts

@@ -10,7 +10,7 @@
  * - Automated setup and management of FFmpeg processes for HKSV event recording and livestreaming (with support for audio and video).
  * - Parsing and generation of fMP4 boxes/segments for HomeKit, including initialization and media segments.
  * - Async generator APIs for efficient, event-driven segment handling.
- * - Flexible error handling and timeouts for HomeKit’s strict realtime requirements.
+ * - Flexible error handling and timeouts for HomeKit's strict realtime requirements.
  * - Designed for Homebridge plugin authors or advanced users who need robust, platform-aware FFmpeg session control for HomeKit and related integrations.
  *
  * @module
@@ -20,21 +20,27 @@ import { type Nullable, type PartialWithId } from "../util.js";
 import type { FfmpegOptions } from "./options.js";
 import { FfmpegProcess } from "./process.js";
 /**
- * Base options for configuring an fMP4 recording or livestream session. These options aren't used directly but are inherited and used by it's descendents.
- *
- * @property audioStream          - Audio stream input to use, if the input contains multiple audio streams. Defaults to `0` (the first audio stream).
- * @property codec                - The codec for the input video stream. Valid values are `av1`, `h264`, and `hevc`. Defaults to `h264`.
- * @property enableAudio          - Indicates whether to enable audio or not.
- * @property hardwareDecoding     - Enable hardware-accelerated video decoding if available. Defaults to what was specified in `ffmpegOptions`.
- * @property hardwareTranscoding  - Enable hardware-accelerated video transcoding if available. Defaults to what was specified in `ffmpegOptions`.
- * @property videoStream          - Video stream input to use, if the input contains multiple video streams. Defaults to `0` (the first video stream).
+ * Base options shared by both fMP4 recording and livestream sessions.
+ *
+ * @property audioFilters        - Audio filters for FFmpeg to process. These are passed as an array of filters.
+ * @property audioStream         - Audio stream input to use, if the input contains multiple audio streams. Defaults to `0` (the first audio stream).
+ * @property codec               - The codec for the input video stream. Valid values are `av1`, `h264`, and `hevc`. Defaults to `h264`.
+ * @property enableAudio         - Indicates whether to enable audio or not.
+ * @property hardwareDecoding    - Enable hardware-accelerated video decoding if available. Defaults to what was specified in `ffmpegOptions`.
+ * @property hardwareTranscoding - Enable hardware-accelerated video transcoding if available. Defaults to what was specified in `ffmpegOptions`.
+ * @property transcodeAudio      - Transcode audio to AAC. This can be set to false if the audio stream is already in AAC. Defaults to `true`.
+ * @property videoFilters        - Video filters for FFmpeg to process. These are passed as an array of filters.
+ * @property videoStream         - Video stream input to use, if the input contains multiple video streams. Defaults to `0` (the first video stream).
  */
 export interface FMp4BaseOptions {
+    audioFilters: string[];
     audioStream: number;
     codec: string;
     enableAudio: boolean;
     hardwareDecoding: boolean;
     hardwareTranscoding: boolean;
+    transcodeAudio: boolean;
+    videoFilters: string[];
     videoStream: number;
 }
 /**
@@ -61,7 +67,7 @@ export interface FMp4BaseOptions {
  *   url: "http://doorbird-ip/bha-api/audio.cgi"
  * };
  *
- * // Self-describing RTSP audio stream — only URL is needed.
+ * // Self-describing RTSP audio stream - only URL is needed.
  * const rtspAudioInput: FMp4AudioInputConfig = {
  *
  *   url: "rtsp://camera-ip/audio"
@@ -79,22 +85,16 @@ export interface FMp4AudioInputConfig {
     url: string;
 }
 /**
- * Options for configuring an fMP4 recording or livestream session.
+ * Options for configuring an fMP4 HKSV recording session.
  *
- * @property audioFilters    - Audio filters for FFmpeg to process. These are passed as an array of filters.
  * @property fps             - The video frames per second for the session.
  * @property probesize       - Number of bytes to analyze for stream information.
  * @property timeshift       - Timeshift offset for event-based recording (in milliseconds).
- * @property transcodeAudio  - Transcode audio to AAC. This can be set to false if the audio stream is already in AAC. Defaults to `true`.
- * @property videoFilters    - Video filters for FFmpeg to process. These are passed as an array of filters.
  */
 export interface FMp4RecordingOptions extends FMp4BaseOptions {
-    audioFilters: string[];
     fps: number;
     probesize: number;
     timeshift: number;
-    transcodeAudio: boolean;
-    videoFilters: string[];
 }
 /**
  * Options for configuring an fMP4 livestream session.
@@ -112,94 +112,48 @@ export interface FMp4LivestreamOptions extends FMp4BaseOptions {
     url: string;
 }
 /**
- * FFmpeg process controller for HomeKit Secure Video (HKSV) and fMP4 livestreaming and recording.
- *
- * This class manages the lifecycle and parsing of an FFmpeg process to support HKSV and livestreaming in fMP4 format. It handles initialization segments, media segment
- * parsing, buffering, and HomeKit segment generation, and emits events for segment and initialization.
- *
- * @example
+ * Abstract base class for fMP4 FFmpeg processes. Owns the shared command line skeleton (preamble, video mapping, movflags, audio encoding, output format) and the fMP4
+ * box-parsing loop. Subclasses provide mode-specific pieces (input args, encoder selection, box handling) via protected hook methods, following the template method
+ * pattern.
  *
- * ```ts
- * // Create a new recording process for an HKSV event.
- * const process = new FfmpegRecordingProcess(ffmpegOptions, recordingConfig, 30, true, 5000000, 0);
- *
- * // Start the process.
- * process.start();
- *
- * // Iterate over generated segments.
- * for await(const segment of process.segmentGenerator()) {
- *
- *   // Send segment to HomeKit, etc.
- * }
- *
- * // Stop when finished.
- * process.stop();
- * ```
- *
- * @see FfmpegOptions
+ * @see FfmpegRecordingProcess
+ * @see FfmpegLivestreamProcess
  * @see FfmpegProcess
  * @see {@link https://ffmpeg.org/ffmpeg.html | FFmpeg Documentation}
  */
-declare class FfmpegFMp4Process extends FfmpegProcess {
-    private hasInitSegment;
-    private _initSegment;
-    private isLivestream;
+declare abstract class FfmpegFMp4Process extends FfmpegProcess {
     private isLoggingErrors;
-    isTimedOut: boolean;
-    private recordingBuffer;
-    segmentLength?: number;
+    protected readonly fMp4Options: Required<FMp4BaseOptions>;
+    protected readonly recordingConfig: CameraRecordingConfiguration;
     /**
-     * Constructs a new fMP4 FFmpeg process for HKSV event recording or livestreaming.
+     * Constructs a new fMP4 FFmpeg process. Stores shared state and applies defaults to the base options. The command line is not assembled here...subclasses call
+     * `buildCommandLine()` after their own initialization to trigger the template method assembly.
      *
      * @param ffmpegOptions     - FFmpeg configuration options.
      * @param recordingConfig   - HomeKit recording configuration for the session.
-     * @param isAudioActive     - If `true`, enables audio stream processing.
-     * @param fMp4Options       - Configuration for the fMP4 session (fps, type, url, audio input, etc.).
+     * @param fMp4Options       - Partial base options with defaults applied for any unset fields.
      * @param isVerbose         - If `true`, enables more verbose logging for debugging purposes. Defaults to `false`.
-     *
-     * @example
-     *
-     * ```ts
-     * const process = new FfmpegFMp4Process(ffmpegOptions, recordingConfig, true, { fps: 30 });
-     * ```
      */
-    constructor(ffmpegOptions: FfmpegOptions, recordingConfig: CameraRecordingConfiguration, fMp4Options?: Partial<FMp4LivestreamOptions & FMp4RecordingOptions>, isVerbose?: boolean);
+    constructor(ffmpegOptions: FfmpegOptions, recordingConfig: CameraRecordingConfiguration, fMp4Options?: Partial<FMp4BaseOptions>, isVerbose?: boolean);
+    private _isVerbose;
+    protected buildCommandLine(): void;
+    protected abstract inputArgs(): string[];
+    protected abstract separateAudioInputArgs(): string[];
+    protected abstract audioInputIndex(): number;
+    protected abstract videoEncoderArgs(): string[];
+    protected abstract postFilterArgs(): string[];
+    protected abstract metadataLabel(): string;
+    protected abstract handleParsedBox(header: Buffer, data: Buffer, dataLength: number, type: string): void;
     /**
-     * Prepares and configures the FFmpeg process for reading and parsing output fMP4 data.
-     *
-     * This method is called internally by the process lifecycle and is not typically invoked directly by consumers.
+     * Prepares and configures the FFmpeg process for reading and parsing output fMP4 data. The box parsing loop is shared...each complete box is dispatched to the
+     * subclass via handleParsedBox().
      */
     protected configureProcess(): void;
     /**
-     * Retrieves the fMP4 initialization segment generated by FFmpeg.
-     *
-     * Waits until the initialization segment is available, then returns it.
-     *
-     * @returns A promise resolving to the initialization segment as a Buffer.
-     *
-     * @example
-     *
-     * ```ts
-     * const initSegment = await process.getInitSegment();
-     * ```
-     */
-    protected getInitSegment(): Promise<Buffer>;
-    /**
-     * Stops the FFmpeg process and performs cleanup, including emitting termination events for segment generators.
-     *
-     * This is called as part of the process shutdown sequence.
+     * Stops the FFmpeg process and performs cleanup. Subclasses override this to emit mode-specific events before calling super, which handles the shared teardown and
+     * emits the "close" event.
      */
     protected stopProcess(): void;
-    /**
-     * Starts the FFmpeg process, adjusting segment length for livestreams if set.
-     *
-     * @example
-     *
-     * ```ts
-     * process.start();
-     * ```
-     */
-    start(): void;
     /**
      * Stops the FFmpeg process and logs errors if specified.
      *
@@ -218,40 +172,7 @@ declare class FfmpegFMp4Process extends FfmpegProcess {
      * @param exitCode - The exit code from the FFmpeg process.
      * @param signal   - The signal (if any) used to terminate the process.
      */
-    protected logFfmpegError(exitCode: number, signal: NodeJS.Signals): void;
-    /**
-     * Asynchronously generates complete segments from FFmpeg output, formatted for HomeKit Secure Video.
-     *
-     * This async generator yields fMP4 segments as Buffers, or ends on process termination or timeout.
-     *
-     * @yields A Buffer containing a complete MP4 segment suitable for HomeKit.
-     *
-     * @example
-     *
-     * ```ts
-     * for await(const segment of process.segmentGenerator()) {
-     *
-     *   // Process each segment for HomeKit.
-     * }
-     * ```
-     */
-    segmentGenerator(): AsyncGenerator<Buffer>;
-    /**
-     * Returns the initialization segment as a Buffer, or null if not yet available.
-     *
-     * @returns The initialization segment Buffer, or `null` if not yet generated.
-     *
-     * @example
-     *
-     * ```ts
-     * const init = process.initSegment;
-     * if(init) {
-     *
-     *   // Use the initialization segment.
-     * }
-     * ```
-     */
-    get initSegment(): Nullable<Buffer>;
+    protected logFfmpegError(exitCode: Nullable<number>, signal: Nullable<NodeJS.Signals>): void;
 }
 /**
  * Manages a HomeKit Secure Video recording FFmpeg process.
@@ -268,6 +189,14 @@ declare class FfmpegFMp4Process extends FfmpegProcess {
  * @category FFmpeg
  */
 export declare class FfmpegRecordingProcess extends FfmpegFMp4Process {
+    /**
+     * Indicates whether the recording has timed out waiting for FFmpeg output.
+     */
+    isTimedOut: boolean;
+    private readonly fps;
+    private readonly probesize;
+    private recordingBuffer;
+    private readonly timeshift;
     /**
      * Constructs a new FFmpeg recording process for HKSV events.
      *
@@ -277,6 +206,34 @@ export declare class FfmpegRecordingProcess extends FfmpegFMp4Process {
      * @param isVerbose        - If `true`, enables more verbose logging for debugging purposes. Defaults to `false`.
      */
     constructor(options: FfmpegOptions, recordingConfig: CameraRecordingConfiguration, fMp4Options?: Partial<FMp4RecordingOptions>, isVerbose?: boolean);
+    protected inputArgs(): string[];
+    protected separateAudioInputArgs(): string[];
+    protected audioInputIndex(): number;
+    protected videoEncoderArgs(): string[];
+    protected postFilterArgs(): string[];
+    protected metadataLabel(): string;
+    protected handleParsedBox(header: Buffer, data: Buffer, dataLength: number, type: string): void;
+    /**
+     * Stops the FFmpeg process and performs cleanup, ensuring the segment generator can exit.
+     */
+    protected stopProcess(): void;
+    /**
+     * Asynchronously generates complete segments from FFmpeg output, formatted for HomeKit Secure Video.
+     *
+     * This async generator yields fMP4 segments as Buffers, or ends on process termination or timeout.
+     *
+     * @yields A Buffer containing a complete MP4 segment suitable for HomeKit.
+     *
+     * @example
+     *
+     * ```ts
+     * for await(const segment of process.segmentGenerator()) {
+     *
+     *   // Process each segment for HomeKit.
+     * }
+     * ```
+     */
+    segmentGenerator(): AsyncGenerator<Buffer>;
 }
 /**
  * Manages a HomeKit livestream FFmpeg process for generating fMP4 segments.
@@ -295,6 +252,15 @@ export declare class FfmpegRecordingProcess extends FfmpegFMp4Process {
  * @category FFmpeg
  */
 export declare class FfmpegLivestreamProcess extends FfmpegFMp4Process {
+    /**
+     * Optional override for the fMP4 fragment duration, in milliseconds. When set, the `-frag_duration` argument is updated before starting the FFmpeg process.
+     */
+    segmentLength?: number;
+    private _hasAudioInput;
+    private _initSegment;
+    private _initSegmentParts;
+    private hasInitSegment;
+    private readonly livestreamOptions;
     /**
      * Constructs a new FFmpeg livestream process.
      *
@@ -304,6 +270,23 @@ export declare class FfmpegLivestreamProcess extends FfmpegFMp4Process {
      * @param isVerbose          - If `true`, enables more verbose logging for debugging purposes. Defaults to `false`.
      */
     constructor(options: FfmpegOptions, recordingConfig: CameraRecordingConfiguration, livestreamOptions: PartialWithId<FMp4LivestreamOptions, "url">, isVerbose?: boolean);
+    protected inputArgs(): string[];
+    protected separateAudioInputArgs(): string[];
+    protected audioInputIndex(): number;
+    protected videoEncoderArgs(): string[];
+    protected postFilterArgs(): string[];
+    protected metadataLabel(): string;
+    protected handleParsedBox(header: Buffer, data: Buffer, _dataLength: number, type: string): void;
+    /**
+     * Starts the FFmpeg process, adjusting the fragment duration if segmentLength has been set.
+     *
+     * @example
+     *
+     * ```ts
+     * process.start();
+     * ```
+     */
+    start(): void;
     /**
      * Gets the fMP4 initialization segment generated by FFmpeg for the livestream.
      *
@@ -316,5 +299,21 @@ export declare class FfmpegLivestreamProcess extends FfmpegFMp4Process {
      * ```
      */
     getInitSegment(): Promise<Buffer>;
+    /**
+     * Returns the initialization segment as a Buffer, or null if not yet available.
+     *
+     * @returns The initialization segment Buffer, or `null` if not yet generated.
+     *
+     * @example
+     *
+     * ```ts
+     * const init = process.initSegment;
+     * if(init) {
+     *
+     *   // Use the initialization segment.
+     * }
+     * ```
+     */
+    get initSegment(): Nullable<Buffer>;
 }
 export {};