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

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

import type { HomebridgePluginLogging } from "../util.js";
import type { Logging } from "homebridge";
/**
 * Options for configuring FFmpeg probing.
 *
 * @category FFmpeg
 */
export interface FOptions {
    /**
     * The path or command used to execute FFmpeg.
     */
    ffmpegExec: string;
    /**
     * Logging interface for output and errors.
     */
    log: HomebridgePluginLogging | Logging;
    /**
     * Enables or disables verbose logging output.
     */
    verbose: boolean;
}
/**
 * Probe FFmpeg capabilities and codecs on the host system.
 *
 * This class provides methods to check available FFmpeg decoders, encoders, and hardware acceleration methods, as well as to determine system-specific resources such as
 * GPU memory (on Raspberry Pi). Intended for plugin authors or advanced users needing to assess FFmpeg capabilities dynamically.
 *
 * @example
 *
 * ```ts
 * const codecs = new FfmpegCodecs({
 *
 *   ffmpegExec: "ffmpeg",
 *   log: console,
 *   verbose: true
 * });
 *
 * // Probe system and FFmpeg capabilities.
 * const ready = await codecs.probe();
 *
 * if(ready) {
 *
 *   console.log("Available FFmpeg version:", codecs.ffmpegVersion);
 *
 *   if(codecs.hasDecoder("h264", "h264_v4l2m2m")) {
 *
 *     console.log("Hardware H.264 decoder is available.");
 *   }
 * }
 * ```
 *
 * @category FFmpeg
 */
export declare class FfmpegCodecs {
    /**
     * The path or command name to invoke FFmpeg.
     */
    readonly ffmpegExec: string;
    private _ffmpegVersion;
    private _gpuMem;
    private _hostSystem;
    private _intelGeneration;
    private readonly log;
    private readonly ffmpegCodecs;
    private readonly ffmpegHwAccels;
    /**
     * Indicates whether verbose logging is enabled for FFmpeg probing.
     */
    readonly verbose: boolean;
    /**
     * Creates an instance of `FfmpegCodecs`.
     *
     * @param options - Options used to configure FFmpeg probing.
     */
    constructor(options: FOptions);
    /**
     * Probes the host system and FFmpeg executable for capabilities, version, codecs, and hardware acceleration support.
     *
     * Returns `true` if probing succeeded, otherwise `false`.
     *
     * @returns A promise that resolves to `true` if probing is successful, or `false` on failure.
     *
     * @example
     *
     * ```ts
     *
     * const ready = await codecs.probe();
     *
     * if(!ready) {
     *
     *   console.log("FFmpeg probing failed.");
     * }
     * ```
     */
    probe(): Promise<boolean>;
    /**
     * Checks whether a specific decoder is available for a given codec.
     *
     * @param codec - The codec name, e.g., "h264".
     * @param decoder - The decoder name to check for, e.g., "h264_qsv".
     *
     * @returns `true` if the decoder is available for the codec, `false` otherwise.
     *
     * @example
     *
     * ```ts
     *
     * if(codecs.hasDecoder("h264", "h264_qsv")) {
     *
     *   // Use hardware decoding.
     * }
     * ```
     */
    hasDecoder(codec: string, decoder: string): boolean;
    /**
     * Checks whether a specific encoder is available for a given codec.
     *
     * @param codec - The codec name, e.g., "h264".
     * @param encoder - The encoder name to check for, e.g., "h264_videotoolbox".
     *
     * @returns `true` if the encoder is available for the codec, `false` otherwise.
     *
     * @example
     *
     * ```ts
     *
     * if(codecs.hasEncoder("h264", "h264_videotoolbox")) {
     *
     *   // Use hardware encoding.
     * }
     * ```
     */
    hasEncoder(codec: string, encoder: string): boolean;
    /**
     * Checks whether a given hardware acceleration method is available and validated on the host.
     *
     * @param accel - The hardware acceleration method name, e.g., "videotoolbox".
     *
     * @returns `true` if the hardware acceleration method is available, `false` otherwise.
     *
     * @example
     *
     * ```ts
     * if(codecs.hasHwAccel("videotoolbox")) {
     *
     *   // Hardware acceleration is supported.
     * }
     * ```
     */
    hasHwAccel(accel: string): boolean;
    /**
     * Returns the amount of GPU memory available on the host system, in megabytes.
     *
     * @remarks Always returns `0` on non-Raspberry Pi systems.
     */
    get gpuMem(): number;
    /**
     * Returns the detected FFmpeg version string, or "unknown" if detection failed.
     */
    get ffmpegVersion(): string;
    /**
     * Returns the host system type we are running on as one of "generic", "macOS.Apple", "macOS.Intel", or "raspbian".
     *
     * @remarks We are only trying to detect host capabilities to the extent they impact which FFmpeg options we are going to use.
     */
    get hostSystem(): string;
    /**
     * Returns the Intel CPU generation, if we're on Linux and have an Intel processor.
     *
     * @returns Returns the CPU generation or 0 if it can't be detected or an invalid platform.
     */
    get intelGeneration(): number;
    private probeFfmpegVersion;
    private probeFfmpegHwAccel;
    private probeFfmpegCodecs;
    private probeHwOs;
    private probeRpiGpuMem;
    private probeCmd;
}