homebridge-plugin-utils
Version:
Opinionated utilities to provide common capabilities and create rich configuration webUI experiences for Homebridge plugins.
273 lines (272 loc) • 10.7 kB
TypeScript
/**
* FFmpeg process management for HomeKit Secure Video (HKSV) events and fMP4 livestreaming.
*
* This module defines classes for orchestrating FFmpeg processes that produce fMP4 segments suitable for HomeKit Secure Video and realtime livestreaming scenarios. It
* handles process lifecycle, segment buffering, initialization segment detection, and streaming event generation, abstracting away the complexity of interacting directly
* with FFmpeg for these workflows.
*
* Key features:
*
* - 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.
* - Designed for Homebridge plugin authors or advanced users who need robust, platform-aware FFmpeg session control for HomeKit and related integrations.
*
* @module
*/
import { type CameraRecordingConfiguration } from "homebridge";
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).
*/
export interface FMp4BaseOptions {
audioStream: number;
codec: string;
enableAudio: boolean;
hardwareDecoding: boolean;
hardwareTranscoding: boolean;
videoStream: number;
}
/**
* Options for configuring an fMP4 recording or livestream 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 recording or livestream session.
*
* @property url - Source URL for livestream (RTSP) remuxing to fMP4.
*/
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
*
* ```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;
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 - Configuration for the fMP4 session (fps, type, url, etc.).
* @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);
/**
* 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 fMp4Options - fMP4 recording options.
* @param isVerbose - If `true`, enables more verbose logging for debugging purposes. Defaults to `false`.
*/
constructor(options: FfmpegOptions, recordingConfig: CameraRecordingConfiguration, fMp4Options?: Partial<FMp4RecordingOptions>, isVerbose?: boolean);
}
/**
* 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 livestreamOptions - livestream segmenting options.
* @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);
/**
* 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 {};