homebridge-plugin-utils
Version:
Opinionated utilities to provide common capabilities and create rich configuration webUI experiences for Homebridge plugins.
144 lines (143 loc) • 6.21 kB
TypeScript
/**
* FFmpeg process management and socket handling to support HomeKit livestreaming sessions.
*
* This module defines the `FfmpegStreamingProcess` class and related interfaces for orchestrating and monitoring FFmpeg-powered video streams. It manages process
* lifecycle, handles UDP socket creation for video health monitoring, and enables integration with Homebridge streaming delegates for robust error handling, stream
* cleanup, and automatic tuning.
*
* Key features:
*
* - Automated start, monitoring, and termination of HomeKit-compatible FFmpeg video streams.
* - Integration with Homebridge’s CameraStreamingDelegate for custom error hooks and lifecycle control.
* - UDP socket creation and management for realtime video stream liveness detection.
* - Intelligent error handling, including automatic tuning for FFmpeg’s stream probing requirements.
* - Exposes access to the underlying FFmpeg child process for advanced scenarios.
*
* Designed for plugin developers and advanced users who require fine-grained control and diagnostics for HomeKit livestreaming, with seamless Homebridge integration.
*
* @module
*/
import type { CameraController, CameraStreamingDelegate, StreamRequestCallback } from "homebridge";
import type { ChildProcessWithoutNullStreams } from "child_process";
import type { FfmpegOptions } from "./options.js";
import { FfmpegProcess } from "./process.js";
import type { Nullable } from "../util.js";
/**
* Extension of the Homebridge CameraStreamingDelegate with additional streaming controls and error handling hooks.
*
* @property adjustProbeSize - Optional. Invoked to adjust probe size after stream startup errors.
* @property controller - The Homebridge CameraController instance managing the stream.
* @property ffmpegErrorCheck - Optional. Returns a user-friendly error message for specific FFmpeg errors, if detected.
* @property stopStream - Optional. Invoked to force stop a specific stream session by ID.
*
* @see CameraController
* @see CameraStreamingDelegate
*
* @category FFmpeg
*/
export interface HomebridgeStreamingDelegate extends CameraStreamingDelegate {
adjustProbeSize?: () => void;
controller: CameraController;
ffmpegErrorCheck?: (logEntry: string[]) => string | undefined;
stopStream?: (sessionId: string) => void;
}
/**
* Provides FFmpeg process management and socket handling to support HomeKit livestreaming sessions.
*
* This class extends `FfmpegProcess` to create, monitor, and terminate HomeKit-compatible video streams. Additionally, it invokes delegate hooks for error processing and
* stream lifecycle management.
*
* @example
*
* ```ts
* const streamingDelegate: HomebridgeStreamingDelegate = {
*
* controller,
* stopStream: (sessionId) => { ... } // End-of-session cleanup code.
* };
*
* const process = new FfmpegStreamingProcess(
*
* streamingDelegate,
* sessionId,
* ffmpegOptions,
* commandLineArgs,
* { addressVersion: "ipv4", port: 5000 }
* );
* ```
*
* @see HomebridgeStreamingDelegate
* @see FfmpegProcess
*
* @category FFmpeg
*/
export declare class FfmpegStreamingProcess extends FfmpegProcess {
private delegate;
/**
* The unique session identifier for this streaming process.
*/
private sessionId;
/**
* The timeout reference used to monitor UDP stream health.
*/
private streamTimeout?;
/**
* Constructs a new FFmpeg streaming process for a HomeKit session.
*
* Sets up required delegate hooks, creates UDP return sockets if needed, and starts the FFmpeg process. Automatically handles FFmpeg process errors and cleans up on
* failures.
*
* @param delegate - The Homebridge streaming delegate for this session.
* @param sessionId - The HomeKit session identifier for this stream.
* @param ffmpegOptions - The FFmpeg configuration options.
* @param commandLineArgs - FFmpeg command-line arguments.
* @param returnPort - Optional. UDP port info for talkback support (used for two-way audio in HomeKit for cameras that support it).
* @param callback - Optional. Callback invoked when the stream is ready or errors occur.
*
* @example
*
* ```ts
* const process = new FfmpegStreamingProcess(delegate, sessionId, ffmpegOptions, commandLineArgs, { addressVersion: "ipv6", port: 6000 });
* ```
*/
constructor(delegate: HomebridgeStreamingDelegate, sessionId: string, ffmpegOptions: FfmpegOptions, commandLineArgs: string[], returnPort?: {
addressVersion: string;
port: number;
}, callback?: StreamRequestCallback);
/**
* Creates and binds a UDP socket for monitoring the health of the outgoing video stream.
*
* Listens for UDP "message" events, sets and clears timeouts, and handles error/cleanup scenarios. If no messages are received within 5 seconds, forcibly stops the
* stream and informs the delegate.
*
* @param portInfo - Object containing the address version ("ipv4" or "ipv6") and port number.
*/
private createSocket;
/**
* Returns the underlying FFmpeg child process, or null if the process is not running.
*
* @returns The current FFmpeg process, or `null` if not running.
*
* @example
*
* ```ts
* const ffmpeg = process.ffmpegProcess;
*
* if(ffmpeg) {
*
* // Interact directly with the child process if necessary.
* }
* ```
*/
get ffmpegProcess(): Nullable<ChildProcessWithoutNullStreams>;
/**
* Handle and logs FFmpeg process errors.
*
* If a known error condition is detected by the delegate, logs the custom message and returns. For "not enough frames to estimate rate; consider increasing probesize"
* errors, invokes the delegate's `adjustProbeSize` hook for automatic tuning. Otherwise, falls back to the parent class's logging.
*
* @param exitCode - The exit code from FFmpeg.
* @param signal - The signal, if any, used to terminate the process.
*/
protected logFfmpegError(exitCode: number, signal: NodeJS.Signals): void;
}