homebridge-plugin-utils 1.15.2 → 1.16.0

package/dist/ffmpeg/record.d.ts

@@ -0,0 +1,230 @@
+import { type Nullable } from "../util.js";
+import type { CameraRecordingConfiguration } from "homebridge";
+import type { FfmpegOptions } from "./options.js";
+import { FfmpegProcess } from "./process.js";
+/**
+ * Options for configuring an fMP4 recording or livestream session.
+ *
+ * @property fps        - The video frames per second for the session.
+ * @property livestream - Indicates if this is a livestream session (`true`) or a recording (`false`).
+ * @property probesize  - Number of bytes to analyze for stream information.
+ * @property timeshift  - Timeshift offset for event-based recording (in milliseconds).
+ * @property url        - Source URL for livestreaming (RTSP).
+ */
+interface Fmp4OptionsConfig {
+    fps: number;
+    livestream: boolean;
+    probesize: number;
+    timeshift: number;
+    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
+ *
+ * ```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 FfmpegProcess
+ * @see {@link https://ffmpeg.org/ffmpeg.html | FFmpeg Documentation}
+ */
+declare class FfmpegFmp4Process extends FfmpegProcess {
+    private hasInitSegment;
+    private _initSegment;
+    private isLivestream;
+    private isLoggingErrors;
+    isTimedOut: boolean;
+    private recordingBuffer;
+    private recordingConfig;
+    segmentLength?: number;
+    /**
+     * Constructs a new fMP4 FFmpeg process for HKSV event recording or livestreaming.
+     *
+     * @param ffmpegOptions     - FFmpeg configuration options.
+     * @param recordingConfig   - HomeKit recording configuration for the session.
+     * @param isAudioActive     - If `true`, enables audio stream processing.
+     * @param fmp4Options       - Partial configuration for the fMP4 session (fps, url, etc.).
+     *
+     * @example
+     *
+     * ```ts
+     * const process = new FfmpegFmp4Process(ffmpegOptions, recordingConfig, true, { fps: 30 });
+     * ```
+     */
+    constructor(ffmpegOptions: FfmpegOptions, recordingConfig: CameraRecordingConfiguration, isAudioActive: boolean, fmp4Options?: Partial<Fmp4OptionsConfig>);
+    /**
+     * 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.
+     */
+    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.
+     */
+    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.
+     *
+     * @param logErrors - If `true`, logs FFmpeg errors. Defaults to the internal process logging state.
+     *
+     * @example
+     *
+     * ```ts
+     * process.stop();
+     * ```
+     */
+    stop(logErrors?: boolean): void;
+    /**
+     * Logs errors from FFmpeg process execution, handling known benign HKSV stream errors gracefully.
+     *
+     * @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>;
+}
+/**
+ * Manages a HomeKit Secure Video recording FFmpeg process.
+ *
+ * @example
+ *
+ * ```ts
+ * const process = new FfmpegRecordingProcess(ffmpegOptions, recordingConfig, 30, true, 5000000, 0);
+ * process.start();
+ * ```
+ *
+ * @see FfmpegFmp4Process
+ *
+ * @category FFmpeg
+ */
+export declare class FfmpegRecordingProcess extends FfmpegFmp4Process {
+    /**
+     * Constructs a new FFmpeg recording process for HKSV events.
+     *
+     * @param options          - FFmpeg configuration options.
+     * @param recordingConfig  - HomeKit recording configuration for the session.
+     * @param fps              - Video frames per second.
+     * @param isAudioActive    - If `true`, enables audio stream processing.
+     * @param probesize        - Stream analysis size, in bytes.
+     * @param timeshift        - Timeshift offset for event-based recording, in milliseconds.
+     */
+    constructor(options: FfmpegOptions, recordingConfig: CameraRecordingConfiguration, fps: number, isAudioActive: boolean, probesize: number, timeshift: number);
+}
+/**
+ * Manages a HomeKit livestream FFmpeg process for generating fMP4 segments.
+ *
+ * @example
+ *
+ * ```ts
+ * const process = new FfmpegLivestreamProcess(ffmpegOptions, recordingConfig, url, 30, true);
+ * process.start();
+ *
+ * const initSegment = await process.getInitSegment();
+ * ```
+ *
+ * @see FfmpegFmp4Process
+ *
+ * @category FFmpeg
+ */
+export declare class FfmpegLivestreamProcess extends FfmpegFmp4Process {
+    /**
+     * Constructs a new FFmpeg livestream process.
+     *
+     * @param options          - FFmpeg configuration options.
+     * @param recordingConfig  - HomeKit recording configuration for the session.
+     * @param url              - Source RTSP or livestream URL.
+     * @param fps              - Video frames per second.
+     * @param isAudioActive    - If `true`, enables audio stream processing.
+     */
+    constructor(options: FfmpegOptions, recordingConfig: CameraRecordingConfiguration, url: string, fps: number, isAudioActive: boolean);
+    /**
+     * Gets the fMP4 initialization segment generated by FFmpeg for the livestream.
+     *
+     * @returns A promise resolving to the initialization segment as a Buffer.
+     *
+     * @example
+     *
+     * ```ts
+     * const initSegment = await process.getInitSegment();
+     * ```
+     */
+    getInitSegment(): Promise<Buffer>;
+}
+export {};