homebridge-plugin-utils 1.15.3 → 1.17.0

package/dist/ffmpeg/stream.d.ts

@@ -0,0 +1,143 @@
+/**
+ * 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 the return stream (used except for two-way audio).
+     * @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;
+}

package/dist/ffmpeg/stream.js

@@ -0,0 +1,186 @@
+/* Copyright(C) 2017-2025, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * ffmpeg/stream.ts: Provide FFmpeg process control to support HomeKit livestreaming.
+ */
+import { FfmpegProcess } from "./process.js";
+import { createSocket } from "node:dgram";
+/**
+ * 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 class FfmpegStreamingProcess extends FfmpegProcess {
+    /*
+     * The streaming delegate instance responsible for handling stream events and errors.
+     */
+    delegate;
+    /**
+     * The unique session identifier for this streaming process.
+     */
+    sessionId;
+    /**
+     * The timeout reference used to monitor UDP stream health.
+     */
+    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 the return stream (used except for two-way audio).
+     * @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, sessionId, ffmpegOptions, commandLineArgs, returnPort, callback) {
+        // Initialize our parent.
+        super(ffmpegOptions);
+        this.delegate = delegate;
+        this.delegate.adjustProbeSize ??= () => { };
+        this.delegate.ffmpegErrorCheck ??= () => undefined;
+        this.delegate.stopStream ??= () => { };
+        this.sessionId = sessionId;
+        // Create the return port for FFmpeg, if requested to do so. The only time we don't do this is when we're standing up
+        // a two-way audio stream - in that case, the audio work is done through RtpSplitter and not here.
+        if (returnPort) {
+            this.createSocket(returnPort);
+        }
+        // Start it up, with appropriate error handling.
+        this.start(commandLineArgs, callback, (errorMessage) => {
+            // Stop the stream.
+            this.delegate.stopStream?.(this.sessionId);
+            // Let homebridge know what happened and stop the stream if we've already started.
+            if (!this.isStarted && this.callback) {
+                this.callback(new Error(errorMessage));
+                this.callback = null;
+                return;
+            }
+            // Tell Homebridge to forcibly stop the streaming session.
+            this.delegate.controller.forceStopStreamingSession(this.sessionId);
+            this.delegate.stopStream?.(this.sessionId);
+        });
+    }
+    /**
+     * 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.
+     */
+    createSocket(portInfo) {
+        let errorListener;
+        let messageListener;
+        const socket = createSocket(portInfo.addressVersion === "ipv6" ? "udp6" : "udp4");
+        // Cleanup after ourselves when the socket closes.
+        socket.once("close", () => {
+            if (this.streamTimeout) {
+                clearTimeout(this.streamTimeout);
+            }
+            socket.off("error", errorListener);
+            socket.off("message", messageListener);
+        });
+        // Handle potential network errors.
+        socket.on("error", errorListener = (error) => {
+            this.log.error("Socket error: %s.", error.name);
+            void this.delegate.stopStream?.(this.sessionId);
+        });
+        // Manage our video streams in case we haven't received a stop request, but we're in fact dead zombies.
+        socket.on("message", messageListener = () => {
+            // Clear our last canary.
+            if (this.streamTimeout) {
+                clearTimeout(this.streamTimeout);
+            }
+            // Set our new canary.
+            this.streamTimeout = setTimeout(() => {
+                this.log.debug("Video stream appears to be inactive for 5 seconds. Stopping stream.");
+                this.delegate.controller.forceStopStreamingSession(this.sessionId);
+                void this.delegate.stopStream?.(this.sessionId);
+            }, 5000);
+        });
+        // Bind to the port we're opening.
+        socket.bind(portInfo.port, (portInfo.addressVersion === "ipv6") ? "::1" : "127.0.0.1");
+    }
+    /**
+     * 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() {
+        return this.process;
+    }
+    /**
+     * 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.
+     */
+    logFfmpegError(exitCode, signal) {
+        // We want to process known streaming-related errors due to the performance and latency tweaks we've made to the FFmpeg command line. In some cases we may inform the
+        // user and take no action, in others, we tune our own internal parameters.
+        // Process any specific errors our caller is interested in.
+        const errTest = this.delegate.ffmpegErrorCheck?.(this.stderrLog);
+        if (errTest) {
+            this.log.error(errTest);
+            return;
+        }
+        // Test for probesize errors.
+        const probesizeRegex = new RegExp("not enough frames to estimate rate; consider increasing probesize");
+        if (this.stderrLog.some(logEntry => probesizeRegex.test(logEntry))) {
+            // Let the streaming delegate know to adjust it's parameters for the next run and inform the user.
+            this.delegate.adjustProbeSize?.();
+            return;
+        }
+        // Otherwise, revert to our default logging in our parent.
+        super.logFfmpegError(exitCode, signal);
+    }
+}
+//# sourceMappingURL=stream.js.map

package/dist/ffmpeg/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/ffmpeg/stream.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export * from "./featureoptions.js";
 export * from "./mqttclient.js";
-export * from "./rtp.js";
 export * from "./service.js";
 export * from "./util.js";
+export * from "./ffmpeg/index.js";

package/dist/index.js

@@ -4,7 +4,7 @@
  */
 export * from "./featureoptions.js";
 export * from "./mqttclient.js";
-export * from "./rtp.js";
 export * from "./service.js";
 export * from "./util.js";
+export * from "./ffmpeg/index.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC"}

package/dist/mqttclient.d.ts

@@ -1,4 +1,42 @@
-import { HomebridgePluginLogging } from "./util.js";
+/**
+ * MQTT connectivity and topic management for Homebridge plugins.
+ *
+ * @module
+ */
+import type { HomebridgePluginLogging } from "./util.js";
+/**
+ * MQTT connectivity and topic management class for Homebridge plugins.
+ *
+ * This class manages connection, publishing, subscription, and message handling for an MQTT broker, and provides convenience methods for Homebridge accessories to
+ * interact with MQTT topics using a standard topic prefix.
+ *
+ * @example
+ *
+ * ```ts
+ * const mqtt = new MqttClient("mqtt://localhost:1883", "homebridge", log);
+ *
+ * // Publish a message to a topic.
+ * mqtt.publish("device1", "status", "on");
+ *
+ * // Subscribe to a topic.
+ * mqtt.subscribe("device1", "status", (msg) => {
+ *
+ *   console.log(msg.toString());
+ * });
+ *
+ * // Subscribe to a 'get' topic and automatically publish a value in response.
+ * mqtt.subscribeGet("device1", "temperature", "Temperature", () => "21.5");
+ *
+ * // Subscribe to a 'set' topic and handle value changes.
+ * mqtt.subscribeSet("device1", "switch", "Switch", (value) => {
+ *
+ *   console.log("Switch set to", value);
+ * });
+ *
+ * // Unsubscribe from a topic.
+ * mqtt.unsubscribe("device1", "status");
+ * ```
+ */
 export declare class MqttClient {
     private brokerUrl;
     private isConnected;
@@ -7,12 +45,134 @@ export declare class MqttClient {
     private mqtt;
     private subscriptions;
     private topicPrefix;
+    /**
+     * Creates a new MQTT client for connecting to a broker and managing topics with a given prefix.
+     *
+     * @param brokerUrl          - The MQTT broker URL (e.g., "mqtt://localhost:1883").
+     * @param topicPrefix        - Prefix to use for all MQTT topics (e.g., "homebridge").
+     * @param log                - Logger for debug and info messages.
+     * @param reconnectInterval  - Optional. Interval (in seconds) to wait between reconnection attempts. Defaults to 60 seconds.
+     *
+     * @example
+     *
+     * ```ts
+     * const mqtt = new MqttClient("mqtt://localhost", "homebridge", log);
+     * ```
+     *
+     * @remarks URL must conform to formats supported by {@link https://github.com/mqttjs/MQTT.js | MQTT.js}.
+     */
     constructor(brokerUrl: string, topicPrefix: string, log: HomebridgePluginLogging, reconnectInterval?: number);
+    /**
+     * Initializes and connects the MQTT client to the broker, setting up event handlers for connection, messages, and errors.
+     *
+     * Catches invalid broker URLs and logs errors. Handles all major MQTT client events internally.
+     */
     private configure;
+    /**
+     * Publishes a message to a topic for a specific device.
+     *
+     * Expands the topic using the topic prefix and device ID, then publishes the provided message string.
+     *
+     * @param id      - The device or accessory identifier.
+     * @param topic   - The topic name to publish to.
+     * @param message - The message payload to publish.
+     *
+     * @example
+     *
+     * ```ts
+     * mqtt.publish("device1", "status", "on");
+     * ```
+     */
     publish(id: string, topic: string, message: string): void;
+    /**
+     * Subscribes to a topic for a specific device and registers a handler for incoming messages.
+     *
+     * The topic is expanded using the prefix and device ID, and the callback will be called for each message received.
+     *
+     * @param id       - The device or accessory identifier.
+     * @param topic    - The topic name to subscribe to.
+     * @param callback - Handler function called with the message buffer.
+     *
+     * @example
+     *
+     * ```ts
+     * mqtt.subscribe("device1", "status", (msg) => {
+     *
+     *   console.log(msg.toString());
+     * });
+     * ```
+     */
     subscribe(id: string, topic: string, callback: (cbBuffer: Buffer) => void): void;
+    /**
+     * Subscribes to a '<topic>/get' topic and publishes a value in response to "true" messages.
+     *
+     * When a message "true" is received on the '<topic>/get' topic, this method will publish the result of `getValue()` on the main topic. The log will record each status
+     * publication event.
+     *
+     * @param id       - The device or accessory identifier.
+     * @param topic    - The topic name to use.
+     * @param type     - A human-readable label for log messages (e.g., "Temperature").
+     * @param getValue - Function to get the value to publish as a string.
+     * @param log      - Optional logger for status output. Defaults to the class logger.
+     *
+     * @example
+     *
+     * ```ts
+     * mqtt.subscribeGet("device1", "temperature", "Temperature", () => "21.5");
+     * ```
+     */
     subscribeGet(id: string, topic: string, type: string, getValue: () => string, log?: HomebridgePluginLogging): void;
+    /**
+     * Subscribes to a '<topic>/set' topic and calls a setter when a message is received.
+     *
+     * The `setValue` function is called with both a normalized value and the raw string. Handles both synchronous and promise-based setters. Logs when set messages are
+     * received and when errors occur.
+     *
+     * @param id        - The device or accessory identifier.
+     * @param topic     - The topic name to use.
+     * @param type      - A human-readable label for log messages (e.g., "Switch").
+     * @param setValue  - Function to call when a value is set. Can be synchronous or return a Promise.
+     * @param log       - Optional logger for status output. Defaults to the class logger.
+     *
+     * @example
+     *
+     * ```ts
+     * mqtt.subscribeSet("device1", "switch", "Switch", (value) => {
+     *
+     *   console.log("Switch set to", value);
+     * });
+     * ```
+     */
     subscribeSet(id: string, topic: string, type: string, setValue: (value: string, rawValue: string) => Promise<void> | void, log?: HomebridgePluginLogging): void;
+    /**
+     * Unsubscribes from a topic for a specific device, removing its message handler.
+     *
+     * @param id    - The device or accessory identifier.
+     * @param topic - The topic name to unsubscribe from.
+     *
+     * @example
+     *
+     * ```ts
+     * mqtt.unsubscribe("device1", "status");
+     * ```
+     */
     unsubscribe(id: string, topic: string): void;
+    /**
+     * Expands a topic string into a fully-formed topic path including the prefix and device ID.
+     *
+     * Returns `null` if the device ID is missing or empty.
+     *
+     * @param id    - The device or accessory identifier.
+     * @param topic - The topic name to expand.
+     *
+     * @returns The expanded topic string, or `null` if the ID is missing.
+     *
+     * @example
+     *
+     * ```ts
+     * const topic = mqtt['expandTopic']("device1", "status");
+     * // topic = "homebridge/device1/status"
+     * ```
+     */
     private expandTopic;
 }