homebridge-plugin-utils/dist/ffmpeg/process.d.ts

Opinionated utilities to provide common capabilities and create rich configuration webUI experiences for Homebridge plugins.

/**
 * FFmpeg process management and capability introspection.
 *
 * This module defines the `FfmpegProcess` class, which abstracts the spawning, monitoring, and logging of FFmpeg subprocesses. It manages process state, handles
 * command-line argument composition, processes standard streams (stdin, stdout, stderr), and robustly reports process errors and exit conditions.
 *
 * Designed for use in Homebridge plugins, this module enables safe and flexible execution of FFmpeg commands, making it easier to integrate video/audio processing
 * pipelines with realtime control and diagnostics.
 *
 * Key features:
 *
 * - Comprehensive FFmpeg subprocess management (start, monitor, stop, cleanup).
 * - Streamlined error handling and logging, with pluggable loggers.
 * - Access to process I/O streams for data injection and consumption.
 * - Flexible callback and event-based architecture for streaming scenarios.
 *
 * Intended for developers needing direct, reliable control over FFmpeg process lifecycles with detailed runtime insights, especially in plugin or media automation
 * contexts.
 *
 * @module
 */
import { type ChildProcessWithoutNullStreams } from "node:child_process";
import type { HomebridgePluginLogging, Nullable } from "../util.js";
import type { Readable, Writable } from "node:stream";
import { EventEmitter } from "node:events";
import type { FfmpegOptions } from "./options.js";
import type { StreamRequestCallback } from "homebridge";
/**
 * Base class providing FFmpeg process management and capability introspection.
 *
 * This class encapsulates spawning, managing, and logging of FFmpeg processes, as well as handling process I/O and errors. It is designed as a reusable foundation for
 * advanced FFmpeg process control in Homebridge plugins or similar environments. Originally inspired by the Homebridge and homebridge-camera-ffmpeg source code.
 *
 * @example
 *
 * ```ts
 * // Create and start an FFmpeg process.
 * const process = new FfmpegProcess(options, ["-i", "input.mp4", "-f", "null", "-"]);
 * process.start();
 *
 * // Access process streams if needed.
 * const stdin = process.stdin;
 * const stdout = process.stdout;
 * const stderr = process.stderr;
 *
 * // Stop the FFmpeg process when done.
 * process.stop();
 * ```
 *
 * @see {@link https://ffmpeg.org/documentation.html | FFmpeg Documentation}
 *
 * @see {@link https://nodejs.org/api/child_process.html | Node.js child_process}
 *
 * @see FfmpegOptions
 *
 * @category FFmpeg
 */
export declare class FfmpegProcess extends EventEmitter {
    /**
     * Indicates if an error has occurred during FFmpeg process execution.
     */
    hasError: boolean;
    /**
     * Indicates whether the FFmpeg process has ended.
     */
    isEnded: boolean;
    /**
     * Indicates whether the FFmpeg process has started.
     */
    isStarted: boolean;
    /**
     * Optional callback to be called when the FFmpeg process is ready for streaming.
     */
    protected callback: Nullable<StreamRequestCallback>;
    /**
     * The command line arguments for invoking FFmpeg.
     */
    protected commandLineArgs: string[];
    /**
     * Enables verbose logging for FFmpeg process output.
     */
    protected isVerbose: boolean;
    /**
     * Logger instance for output and error reporting.
     */
    protected readonly log: HomebridgePluginLogging;
    /**
     * FFmpeg process configuration options.
     */
    protected readonly options: FfmpegOptions;
    /**
     * The underlying Node.js ChildProcess instance for the FFmpeg process.
     */
    process: Nullable<ChildProcessWithoutNullStreams>;
    /**
     * Accumulated log lines from standard error for error reporting and debugging.
     */
    protected stderrLog: string[];
    private ffmpegTimeout?;
    private isLogging;
    private stderrBuffer;
    constructor(options: FfmpegOptions, commandLineArgs?: string[], callback?: StreamRequestCallback);
    private prepareProcess;
    /**
     * Starts the FFmpeg process with the provided command line and callback.
     *
     * @param commandLineArgs  - Optional. Arguments for FFmpeg command line.
     * @param callback         - Optional. Callback invoked when streaming is ready.
     * @param errorHandler     - Optional. Function called if FFmpeg fails to start or terminates with error.
     *
     * @example
     *
     * ```ts
     * process.start(["-i", "input.mp4", "-f", "null", "-"]);
     * ```
     */
    start(commandLineArgs?: string[], callback?: StreamRequestCallback, errorHandler?: (errorMessage: string) => Promise<void> | void): void;
    protected configureProcess(errorHandler?: (errorMessage: string) => Promise<void> | void): void;
    protected stopProcess(): void;
    /**
     * Stops the FFmpeg process and performs necessary cleanup.
     *
     * @example
     *
     * ```ts
     * process.stop();
     * ```
     */
    stop(): void;
    /**
     * Logs an error message for FFmpeg process termination.
     *
     * @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;
    /**
     * Returns the writable standard input stream for the FFmpeg process, if available.
     *
     * @returns The standard input stream, or `null` if not available.
     */
    get stdin(): Nullable<Writable>;
    /**
     * Returns the readable standard output stream for the FFmpeg process, if available.
     *
     * @returns The standard output stream, or `null` if not available.
     */
    get stdout(): Nullable<Readable>;
    /**
     * Returns the readable standard error stream for the FFmpeg process, if available.
     *
     * @returns The standard error stream, or `null` if not available.
     */
    get stderr(): Nullable<Readable>;
}