homebridge-plugin-utils 1.34.0 → 2.0.0

package/dist/ffmpeg/codecs.js

@@ -23,32 +23,190 @@
  * @module
  */
 import { EOL, cpus } from "node:os";
-import { execFile } from "node:child_process";
 import { env, platform } from "node:process";
+import { composeSignals } from "../util.js";
+import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { readFileSync } from "node:fs";
 // Promisified execFile, created once at module level rather than per-invocation.
 const execFileAsync = promisify(execFile);
+// Default watchdog timeout, in milliseconds, applied to every probe invocation so a slow or hung FFmpeg binary cannot stall the host plugin indefinitely. Thirty
+// seconds comfortably exceeds the realistic worst-case probe (the hardware-acceleration validation on slow Raspberry Pi hosts) while keeping a crashed binary from
+// parking a plugin forever.
+const PROBE_DEFAULT_TIMEOUT_MS = 30_000;
+// Codec-line regexes for `parseFfmpegCodecs`. Compiled once at module scope to match the convention used for `VALID_HOMEKIT_NAME`, `NON_PRINTABLE_CHARS`, and the other
+// hot-path patterns in this package - regex construction per call is wasted work, even on the cold probe path, when one regex serves every line of every probe.
+const FFMPEG_CODECS_DECODERS_REGEX = /\S+\s+(\S+).+\(decoders: (.*?)\s*\)/;
+const FFMPEG_CODECS_ENCODERS_REGEX = /\S+\s+(\S+).+\(encoders: (.*?)\s*\)/;
 /**
- * Probe FFmpeg capabilities and codecs on the host system.
+ * Parse the stdout of `ffmpeg -version` and return the version string. Returns `"unknown"` when the expected `"ffmpeg version X Copyright..."` line is not found -
+ * matching the behavior of the class-level probe, which records the literal `"unknown"` when it cannot identify the binary.
+ *
+ * Exposed as a module-scope helper (rather than remaining a closure inside the class) so the parse logic is unit-testable against fixture strings without spinning up
+ * the probe plumbing.
+ *
+ * @param stdout - Captured stdout from `ffmpeg -hide_banner -version`.
+ *
+ * @returns The version string, or `"unknown"` if the version line is absent.
+ *
+ * @category FFmpeg
+ */
+export function parseFfmpegVersion(stdout) {
+    const versionRegex = /^ffmpeg version (.*) Copyright.*$/m;
+    const versionMatch = versionRegex.exec(stdout);
+    return versionMatch ? (versionMatch[1] ?? "unknown") : "unknown";
+}
+/**
+ * Parse an FFmpeg version string into its numeric triple. Splits on `.` and `-` so real-world version strings parse correctly across release tarballs ("8.1.1"),
+ * distributor suffixes ("8.1.1-tessus"), distro packages ("4.4.2-0ubuntu0.22.04.1"), and git snapshots ("N-123456-gabcdef"). Any non-numeric segment yields `0` via the
+ * `|| 0` fallback, which gives a safe, conservative result: an unknown build parses as `{ major: 0, minor: 0, patch: 0 }` and fails every {@link ffmpegVersionAtLeast}
+ * check where the requested major is >= 1.
+ *
+ * @param version - An FFmpeg version string as produced by {@link parseFfmpegVersion} or by `FfmpegCodecs.ffmpegVersion`.
  *
- * 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.
+ * @returns The parsed numeric triple.
  *
  * @example
  *
  * ```ts
- * const codecs = new FfmpegCodecs({
+ * parseFfmpegVersionParts("8.1.1");            // { major: 8, minor: 1, patch: 1 }
+ * parseFfmpegVersionParts("8.1.1-tessus");     // { major: 8, minor: 1, patch: 1 }
+ * parseFfmpegVersionParts("N-123456-gabcdef"); // { major: 0, minor: 123456, patch: 0 }  - git snapshot, effectively "unknown"
+ * parseFfmpegVersionParts("unknown");          // { major: 0, minor: 0, patch: 0 }
+ * ```
+ *
+ * @category FFmpeg
+ */
+export function parseFfmpegVersionParts(version) {
+    const parts = version.split(/[.-]/);
+    return {
+        major: Number.parseInt(parts[0] ?? "", 10) || 0,
+        minor: Number.parseInt(parts[1] ?? "", 10) || 0,
+        patch: Number.parseInt(parts[2] ?? "", 10) || 0
+    };
+}
+/**
+ * Return `true` when `parts` represents an FFmpeg version at least as new as the requested major/minor/patch. Compares major, then minor, then patch - the canonical
+ * semver ordering. This is the single source of truth for version-gating comparisons across the library; both the `FfmpegCodecs.ffmpegAtLeast` instance method and the
+ * test-side fixtures delegate here so the boundary logic lives in one implementation.
+ *
+ * @param parts - A parsed version triple as produced by {@link parseFfmpegVersionParts}.
+ * @param major - The minimum major version to accept.
+ * @param minor - The minimum minor version, when major is equal. Defaults to `0`.
+ * @param patch - The minimum patch version, when major and minor are equal. Defaults to `0`.
+ *
+ * @returns `true` if `parts` is >= the requested version; `false` otherwise.
+ *
+ * @example
+ *
+ * ```ts
+ * const parts = parseFfmpegVersionParts("8.1.2");
+ *
+ * ffmpegVersionAtLeast(parts, 8);        // true - 8.1.2 >= 8.0.0
+ * ffmpegVersionAtLeast(parts, 8, 1, 3);  // false - 8.1.2 < 8.1.3
+ * ffmpegVersionAtLeast(parts, 9);        // false - 8.1.2 < 9.0.0
+ * ```
+ *
+ * @category FFmpeg
+ */
+export function ffmpegVersionAtLeast(parts, major, minor = 0, patch = 0) {
+    if (parts.major !== major) {
+        return parts.major > major;
+    }
+    if (parts.minor !== minor) {
+        return parts.minor > minor;
+    }
+    return parts.patch >= patch;
+}
+/**
+ * Parse the stdout of `ffmpeg -hwaccels` and return the list of hardware-acceleration method names in lowercase, in the order they appeared. Skips blank lines and
+ * the leading `"Hardware acceleration methods:"` banner.
+ *
+ * @param stdout - Captured stdout from `ffmpeg -hide_banner -hwaccels`.
+ *
+ * @returns Lowercased acceleration method names, one per entry.
+ *
+ * @category FFmpeg
+ */
+export function parseFfmpegHwAccels(stdout) {
+    const result = [];
+    for (const line of stdout.split(EOL)) {
+        if (!line.length) {
+            continue;
+        }
+        if (line === "Hardware acceleration methods:") {
+            continue;
+        }
+        result.push(line.toLowerCase());
+    }
+    return result;
+}
+/**
+ * Parse the stdout of `ffmpeg -codecs` into a format-keyed index of decoders and encoders. Both sets are lowercased for case-insensitive `hasDecoder` /
+ * `hasEncoder` lookups. Formats with only decoders or only encoders still produce a full entry (the opposite set is simply empty).
+ *
+ * @param stdout - Captured stdout from `ffmpeg -hide_banner -codecs`.
+ *
+ * @returns A record keyed by codec format, each entry carrying the decoders and encoders reported for that format.
  *
- *   ffmpegExec: "ffmpeg",
- *   log: console,
- *   verbose: true
- * });
+ * @category FFmpeg
+ */
+export function parseFfmpegCodecs(stdout) {
+    const result = {};
+    // Capture each codec's decoder and encoder lists separately because FFmpeg reports them in independent parenthesized segments on the same line. The regexes are
+    // hoisted to module scope above so they are compiled once rather than once per call.
+    for (const codecLine of stdout.split(EOL)) {
+        const decodersMatch = FFMPEG_CODECS_DECODERS_REGEX.exec(codecLine);
+        const encodersMatch = FFMPEG_CODECS_ENCODERS_REGEX.exec(codecLine);
+        if (decodersMatch) {
+            const [, format, decoders] = decodersMatch;
+            if ((format !== undefined) && (decoders !== undefined)) {
+                const entry = (result[format] ??= { decoders: new Set(), encoders: new Set() });
+                for (const decoder of decoders.split(" ")) {
+                    entry.decoders.add(decoder.toLowerCase());
+                }
+            }
+        }
+        if (encodersMatch) {
+            const [, format, encoders] = encodersMatch;
+            if ((format !== undefined) && (encoders !== undefined)) {
+                const entry = (result[format] ??= { decoders: new Set(), encoders: new Set() });
+                for (const encoder of encoders.split(" ")) {
+                    entry.encoders.add(encoder.toLowerCase());
+                }
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Parse the stdout of `vcgencmd get_mem gpu` into a megabyte value. Returns `0` when the expected `gpu=<N>M` shape is absent or the captured digits fail integer
+ * parsing - matching the class-level fallback.
+ *
+ * @param stdout - Captured stdout from `vcgencmd get_mem gpu`.
  *
- * // Probe system and FFmpeg capabilities.
- * const ready = await codecs.probe();
+ * @returns The reported GPU memory size in megabytes, or `0` when the value could not be read.
+ *
+ * @category FFmpeg
+ */
+export function parseRpiGpuMem(stdout) {
+    const gpuRegex = /^gpu=(.*)M\n$/;
+    const gpuMatch = gpuRegex.exec(stdout);
+    return Number.parseInt(gpuMatch?.[1] ?? "", 10) || 0;
+}
+/**
+ * Probe FFmpeg capabilities and codecs on the host system.
+ *
+ * Construct via the static factory {@link FfmpegCodecs.probe} to run the live probe pipeline, or via {@link FfmpegCodecs.fromState} to inject pre-assembled state
+ * (tests, cached capability data). Instances are immutable value objects - every getter and predicate reads from a frozen {@link FfmpegCodecsState} snapshot
+ * assembled at construction, so callers holding a reference know its state cannot shift underneath them.
+ *
+ * @example
+ *
+ * ```ts
+ * const codecs = await FfmpegCodecs.probe({ ffmpegExec: "ffmpeg", log: console, verbose: true });
  *
- * if(ready) {
+ * if(codecs) {
  *
  *   console.log("Available FFmpeg version:", codecs.ffmpegVersion);
  *
@@ -62,86 +220,159 @@ const execFileAsync = promisify(execFile);
  * @category FFmpeg
  */
 export class FfmpegCodecs {
+    #state;
+    // Private constructor - the only paths in are the static factories below. This makes "a live `FfmpegCodecs` has complete state" a type-level fact rather than a
+    // convention callers must remember to honor by running a separate async init step after construction.
+    constructor(state) {
+        this.#state = state;
+    }
     /**
-     * The path or command name to invoke FFmpeg.
+     * Async factory. Runs the full probe pipeline (host-system detection, optional Raspberry Pi GPU memory, FFmpeg version + codec inventory + hardware-accel inventory
+     * with per-accel capability validation) and returns a populated instance on success, or `null` when any required probe fails. Every inner probe runs under a
+     * watchdog timeout so a slow or hung FFmpeg binary cannot stall the caller indefinitely; the optional `init.signal` composes with that timeout so callers can cancel
+     * probing from outside (for example, during plugin shutdown).
+     *
+     * @param options - Options used to configure the probe (FFmpeg executable, logger, verbose flag).
+     * @param init    - Optional probe options. `signal` cancels in-flight probes; the per-call watchdog still applies.
+     *
+     * @returns A promise that resolves to a populated `FfmpegCodecs` instance, or `null` if probing failed.
+     *
+     * @example
+     *
+     * ```ts
+     * const codecs = await FfmpegCodecs.probe({ log: plugin.log }, { signal: shutdown.signal });
+     *
+     * if(!codecs) {
+     *
+     *   plugin.log.error("FFmpeg probing failed.");
+     * }
+     * ```
      */
-    ffmpegExec;
-    _ffmpegVersion;
-    _gpuMem;
-    _hostSystem;
-    _cpuGeneration;
-    log;
-    ffmpegCodecs;
-    ffmpegHwAccels;
+    static async probe(options, init = {}) {
+        const state = await probeFfmpegCapabilities(options, init.signal);
+        return state ? new FfmpegCodecs(state) : null;
+    }
     /**
-     * Indicates whether verbose logging is enabled for FFmpeg probing.
+     * Sync factory. Wraps a pre-assembled {@link FfmpegCodecsState} in a `FfmpegCodecs` instance without running any probes. Intended for tests that build a stand-in
+     * capability snapshot and for plugins that cache probe results across restarts and want to rehydrate the class without re-probing.
+     *
+     * @param state - Fully-assembled capability snapshot.
+     *
+     * @returns A populated `FfmpegCodecs` instance backed by the supplied state.
+     *
+     * @example
+     *
+     * ```ts
+     * const codecs = FfmpegCodecs.fromState({
+     *
+     *   codecs: {},
+     *   cpuGeneration: 0,
+     *   ffmpegExec: "ffmpeg",
+     *   ffmpegVersion: "8.0",
+     *   ffmpegVersionParts: parseFfmpegVersionParts("8.0"),
+     *   gpuMem: 0,
+     *   hostSystem: "macOS.Apple",
+     *   hwAccels: new Set([ "videotoolbox" ]),
+     *   verbose: false
+     * });
+     * ```
      */
-    verbose;
+    static fromState(state) {
+        return new FfmpegCodecs(state);
+    }
     /**
-     * Creates an instance of `FfmpegCodecs`.
+     * The path or command name used to invoke FFmpeg.
+     */
+    get ffmpegExec() {
+        return this.#state.ffmpegExec;
+    }
+    /**
+     * Indicates whether verbose logging is enabled for FFmpeg probing and downstream consumers.
+     */
+    get verbose() {
+        return this.#state.verbose;
+    }
+    /**
+     * Returns the amount of GPU memory available on the host system, in megabytes.
      *
-     * @param options - Options used to configure FFmpeg probing.
+     * @remarks Always returns `0` on non-Raspberry Pi systems.
+     */
+    get gpuMem() {
+        return this.#state.gpuMem;
+    }
+    /**
+     * Returns the detected FFmpeg version string. `"unknown"` when the probe ran but the `ffmpeg version X Copyright...` line was not found in stdout. Any other value
+     * is the literal version string reported by the binary and may carry suffixes (`"8.1.1-tessus"`, `"4.4.2-0ubuntu0.22.04.1"`, etc.). For version-comparison decisions,
+     * prefer {@link ffmpegAtLeast} over parsing this string directly.
      */
-    constructor(options) {
-        this.ffmpegExec = options.ffmpegExec ?? "ffmpeg";
-        this.ffmpegCodecs = {};
-        this.ffmpegHwAccels = new Set();
-        this.log = options.log;
-        this.verbose = options.verbose ?? false;
-        // Detect our host system type.
-        this.probeHwOs();
+    get ffmpegVersion() {
+        return this.#state.ffmpegVersion;
     }
     /**
-     * Probes the host system and FFmpeg executable for capabilities, version, codecs, and hardware acceleration support.
+     * Returns the detected FFmpeg major version as a number, or `0` when detection failed or the version string doesn't begin with an integer. Useful for display
+     * ("Running FFmpeg 8") and for callers that need the raw major number. Use {@link ffmpegAtLeast} for version-gating comparisons so all version logic flows through
+     * a single boundary-correct comparison primitive.
      *
-     * Returns `true` if probing succeeded, otherwise `false`.
+     * @returns The major version number (e.g., `6`, `7`, `8`, `10`), or `0` if the version is unknown or non-numeric.
+     */
+    get ffmpegMajorVersion() {
+        return this.#state.ffmpegVersionParts.major;
+    }
+    /**
+     * Return `true` when the detected FFmpeg build is at least the requested version. Compares major, then minor, then patch - the canonical semver ordering. This is
+     * the single source of truth for version-gating decisions across the library; callers prefer this over hand-rolled comparisons so the boundary logic (major-equal
+     * but minor-greater means "newer", etc.) lives in one place and stays consistent.
      *
-     * @returns A promise that resolves to `true` if probing is successful, or `false` on failure.
+     * @param major - The minimum major version to accept.
+     * @param minor - The minimum minor version, when major is equal. Defaults to `0`.
+     * @param patch - The minimum patch version, when major and minor are equal. Defaults to `0`.
+     *
+     * @returns `true` if the detected version is >= the requested version; `false` otherwise. Returns `false` for unknown or unparseable version strings (major = 0).
      *
      * @example
      *
      * ```ts
+     * if(codecs.ffmpegAtLeast(8)) {
      *
-     * const ready = await codecs.probe();
+     *   // FFmpeg 8.0.0 or later.
+     * }
      *
-     * if(!ready) {
+     * if(codecs.ffmpegAtLeast(8, 1)) {
      *
-     *   console.log("FFmpeg probing failed.");
+     *   // FFmpeg 8.1.0 or later.
      * }
      * ```
      */
-    async probe() {
-        // Let's conduct our system-specific capability probes.
-        switch (this.hostSystem) {
-            case "raspbian":
-                // If we're on a Raspberry Pi, let's verify that we have enough GPU memory for hardware-based decoding and encoding.
-                await this.probeRpiGpuMem();
-                break;
-            default:
-                break;
-        }
-        // Capture the version information of FFmpeg.
-        if (!(await this.probeFfmpegVersion())) {
-            return false;
-        }
-        // Ensure we've got a working video processor before we do anything else.
-        if (!(await this.probeFfmpegCodecs()) || !(await this.probeFfmpegHwAccel())) {
-            return false;
-        }
-        return true;
+    ffmpegAtLeast(major, minor = 0, patch = 0) {
+        return ffmpegVersionAtLeast(this.#state.ffmpegVersionParts, major, minor, patch);
+    }
+    /**
+     * 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() {
+        return this.#state.hostSystem;
+    }
+    /**
+     * Returns the CPU generation if we're on Linux and have an Intel processor or on macOS and have an Apple Silicon processor.
+     *
+     * @returns Returns the CPU generation or 0 if it can't be detected or an invalid platform.
+     */
+    get cpuGeneration() {
+        return this.#state.cpuGeneration;
     }
     /**
      * 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".
+     * @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.
@@ -149,24 +380,19 @@ export class FfmpegCodecs {
      * ```
      */
     hasDecoder(codec, decoder) {
-        // Normalize our lookups.
-        codec = codec.toLowerCase();
-        decoder = decoder.toLowerCase();
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-        return this.ffmpegCodecs[codec]?.decoders.has(decoder) ?? false;
+        return this.#state.codecs[codec.toLowerCase()]?.decoders.has(decoder.toLowerCase()) ?? false;
     }
     /**
      * 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".
+     * @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.
@@ -174,16 +400,13 @@ export class FfmpegCodecs {
      * ```
      */
     hasEncoder(codec, encoder) {
-        // Normalize our lookups.
-        codec = codec.toLowerCase();
-        encoder = encoder.toLowerCase();
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-        return this.ffmpegCodecs[codec]?.encoders.has(encoder) ?? false;
+        return this.#state.codecs[codec.toLowerCase()]?.encoders.has(encoder.toLowerCase()) ?? false;
     }
     /**
-     * Checks whether a given hardware acceleration method is available and validated on the host, as provided by the output of `ffmpeg -hwaccels`.
+     * Checks whether a given hardware acceleration method is available and validated on the host, as provided by the output of `ffmpeg -hwaccels` and the per-accel
+     * capability probe.
      *
-     * @param accel - The hardware acceleration method name, e.g., "videotoolbox".
+     * @param accel - The hardware acceleration method name, e.g., `"videotoolbox"`.
      *
      * @returns `true` if the hardware acceleration method is available, `false` otherwise.
      *
@@ -197,207 +420,204 @@ export class FfmpegCodecs {
      * ```
      */
     hasHwAccel(accel) {
-        return this.ffmpegHwAccels.has(accel.toLowerCase());
-    }
-    /**
-     * Returns the amount of GPU memory available on the host system, in megabytes.
-     *
-     * @remarks Always returns `0` on non-Raspberry Pi systems.
-     */
-    get gpuMem() {
-        return this._gpuMem ?? 0;
+        return this.#state.hwAccels.has(accel.toLowerCase());
     }
-    /**
-     * Returns the detected FFmpeg version string, or "unknown" if detection failed.
-     */
-    get ffmpegVersion() {
-        return this._ffmpegVersion ?? "";
+}
+// Probe pipeline. Module-scope functions rather than class methods because the probe assembles state BEFORE a `FfmpegCodecs` instance exists - putting the
+// orchestration inside the class would conflate "how do I populate state?" with "how do I hold and serve state?" The factory at `FfmpegCodecs.probe` glues the two
+// together.
+// Orchestrate the full probe pipeline. Returns a populated state snapshot on success, or `null` when any required probe fails.
+async function probeFfmpegCapabilities(options, signal) {
+    const ffmpegExec = options.ffmpegExec ?? "ffmpeg";
+    const verbose = options.verbose ?? false;
+    const { log } = options;
+    // Sync host-system / CPU-generation detection.
+    const { hostSystem, cpuGeneration } = probeHwOs();
+    // Raspberry Pi: probe GPU memory via vcgencmd. Non-fatal if the command fails (0 propagates; the configureHwAccel gate treats 0 as insufficient anyway).
+    let gpuMem = 0;
+    if (hostSystem === "raspbian") {
+        gpuMem = await probeRpiGpuMem(log, signal);
     }
-    /**
-     * 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() {
-        return this._hostSystem ?? "generic";
+    // FFmpeg version is the first required probe; failure here means the FFmpeg binary isn't usable.
+    const ffmpegVersion = await probeFfmpegVersion(ffmpegExec, log, signal);
+    if (ffmpegVersion === null) {
+        return null;
     }
-    /**
-     * Returns the CPU generation if we're on Linux and have an Intel processor or on macOS and have an Apple Silicon processor.
-     *
-     * @returns Returns the CPU generation or 0 if it can't be detected or an invalid platform.
-     */
-    get cpuGeneration() {
-        return this._cpuGeneration ?? 0;
+    log.info("Using FFmpeg version: %s.", ffmpegVersion);
+    // FFmpeg codec inventory.
+    const codecs = await probeFfmpegCodecs(ffmpegExec, log, signal);
+    if (codecs === null) {
+        return null;
     }
-    // Probe our video processor's version.
-    async probeFfmpegVersion() {
-        return this.probeCmd(this.ffmpegExec, ["-hide_banner", "-version"], (stdout) => {
-            // A regular expression to parse out the version.
-            const versionRegex = /^ffmpeg version (.*) Copyright.*$/m;
-            // Parse out the version string.
-            const versionMatch = versionRegex.exec(stdout);
-            // If we have a version string, let's save it. Otherwise, we're blind.
-            this._ffmpegVersion = versionMatch ? versionMatch[1] : "unknown";
-            this.log.info("Using FFmpeg version: %s.", this.ffmpegVersion);
-        });
+    // FFmpeg hwaccels inventory, with per-accel capability validation.
+    const hwAccels = await probeFfmpegHwAccels(ffmpegExec, verbose, log, signal);
+    if (hwAccels === null) {
+        return null;
     }
-    // Probe our video processor's hardware acceleration capabilities.
-    async probeFfmpegHwAccel() {
-        if (!(await this.probeCmd(this.ffmpegExec, ["-hide_banner", "-hwaccels"], (stdout) => {
-            // Iterate through each line, and a build a list of encoders.
-            for (const accel of stdout.split(EOL)) {
-                // Skip blank lines.
-                if (!accel.length) {
-                    continue;
-                }
-                // Skip the first line.
-                if (accel === "Hardware acceleration methods:") {
-                    continue;
+    return {
+        codecs,
+        cpuGeneration,
+        ffmpegExec,
+        ffmpegVersion,
+        ffmpegVersionParts: parseFfmpegVersionParts(ffmpegVersion),
+        gpuMem,
+        hostSystem,
+        hwAccels,
+        verbose
+    };
+}
+// Detect hardware / OS characteristics synchronously from Node built-ins. No subprocesses; cheap and deterministic.
+function probeHwOs() {
+    // Retrieve the CPU model string once to avoid repeated allocations from cpus(). A machine always has at least one CPU entry in practice; the empty-string fallback
+    // keeps the lookup total for `noUncheckedIndexedAccess` without changing behavior in any real environment.
+    const cpuModelString = cpus()[0]?.model ?? "";
+    let hostSystem = "generic";
+    let cpuGeneration = 0;
+    // Take a look at the platform we're on for an initial hint of what we are.
+    switch (platform) {
+        // The beloved macOS.
+        case "darwin":
+            hostSystem = "macOS." + (cpuModelString.includes("Apple") ? "Apple" : "Intel");
+            // Identify what generation of Apple Silicon we have.
+            if (cpuModelString.includes("Apple")) {
+                // Extract the CPU model.
+                const cpuModel = /Apple M(\d+) .*/i.exec(cpuModelString);
+                if (cpuModel?.[1]) {
+                    cpuGeneration = Number(cpuModel[1]);
                 }
-                // We've found a hardware acceleration method, let's add it.
-                this.ffmpegHwAccels.add(accel.toLowerCase());
             }
-        }))) {
-            return false;
-        }
-        // Let's test to ensure that just because we have a codec or capability available to us, it doesn't necessarily mean that the user has the hardware capabilities
-        // needed to use it, resulting in an FFmpeg error. We catch that here and prevent those capabilities from being exposed unless both software and hardware capabilities
-        // enable it. This simple test, generates a one-second video that is processed by the requested codec. If it fails, we discard the codec.
-        for (const accel of this.ffmpegHwAccels) {
-            // eslint-disable-next-line no-await-in-loop
-            if (!(await this.probeCmd(this.ffmpegExec, [
-                "-hide_banner", "-hwaccel", accel, "-v", "quiet", "-t", "1", "-f", "lavfi", "-i", "color=black:1920x1080", "-c:v", "libx264", "-f", "null", "-"
-            ], () => { }, true))) {
-                this.ffmpegHwAccels.delete(accel);
-                if (this.verbose) {
-                    this.log.error("Hardware-accelerated decoding and encoding using %s will be unavailable: unable to successfully validate capabilities.", accel);
+            break;
+        // The indomitable Linux.
+        case "linux":
+            // Check /sys/firmware for the Raspberry Pi 4 device-tree model string. Failure is non-fatal: we fall through to the generic-Linux path with no Pi-specific
+            // configuration.
+            try {
+                // As of the 4.9 kernel, Raspberry Pi prefers to be identified using this method and has deprecated cpuinfo.
+                const systemId = readFileSync("/sys/firmware/devicetree/base/model", { encoding: "utf8" });
+                // Is it a Pi 4?
+                if (/Raspberry Pi (Compute Module )?4/.test(systemId)) {
+                    hostSystem = "raspbian";
                 }
             }
-        }
-        return true;
-    }
-    // Probe our video processor's encoding and decoding capabilities.
-    async probeFfmpegCodecs() {
-        return this.probeCmd(this.ffmpegExec, ["-hide_banner", "-codecs"], (stdout) => {
-            // A regular expression to parse out the codec and its supported decoders.
-            const decodersRegex = /\S+\s+(\S+).+\(decoders: (.*?)\s*\)/;
-            // A regular expression to parse out the codec and its supported encoders.
-            const encodersRegex = /\S+\s+(\S+).+\(encoders: (.*?)\s*\)/;
-            // Iterate through each line, and a build a list of encoders.
-            for (const codecLine of stdout.split(EOL)) {
-                // Let's see if we have decoders.
-                const decodersMatch = decodersRegex.exec(codecLine);
-                // Let's see if we have encoders.
-                const encodersMatch = encodersRegex.exec(codecLine);
-                // If we found decoders, add them to our list of supported decoders for this format.
-                if (decodersMatch) {
-                    this.ffmpegCodecs[decodersMatch[1]] ??= { decoders: new Set(), encoders: new Set() };
-                    this.ffmpegCodecs[decodersMatch[1]].decoders = new Set(decodersMatch[2].split(" ").map(x => x.toLowerCase()));
-                }
-                // If we found encoders, add them to our list of supported encoders for this format.
-                if (encodersMatch) {
-                    this.ffmpegCodecs[encodersMatch[1]] ??= { decoders: new Set(), encoders: new Set() };
-                    this.ffmpegCodecs[encodersMatch[1]].encoders = new Set(encodersMatch[2].split(" ").map(x => x.toLowerCase()));
-                }
+            catch {
+                // We aren't especially concerned with errors here, given we're just trying to ascertain the system information through hints.
             }
-        });
-    }
-    // Identify what hardware and operating system environment we're actually running on.
-    probeHwOs() {
-        // Retrieve the CPU model string once to avoid repeated allocations from cpus().
-        const cpuModelString = cpus()[0].model;
-        // Take a look at the platform we're on for an initial hint of what we are.
-        switch (platform) {
-            // The beloved macOS.
-            case "darwin":
-                this._hostSystem = "macOS." + (cpuModelString.includes("Apple") ? "Apple" : "Intel");
-                // Identify what generation of Apple Silicon we have.
-                if (cpuModelString.includes("Apple")) {
-                    // Extract the CPU model.
-                    const cpuModel = /Apple M(\d+) .*/i.exec(cpuModelString);
-                    this._cpuGeneration = 0;
-                    if (cpuModel?.[1]) {
-                        this._cpuGeneration = Number(cpuModel[1]);
+            // Identify what generation of Intel CPU we have if we're on Intel.
+            if (cpuModelString.includes("Intel")) {
+                // Extract the CPU model.
+                const cpuModel = /Intel.*Core.*i\d+-(\d{3,5})/i.exec(cpuModelString);
+                if (cpuModel?.[1]) {
+                    // Grab the individual SKU as both a number and string.
+                    const skuStr = cpuModel[1];
+                    const skuNum = Number(skuStr);
+                    // Now deduce the CPU generation.
+                    if (skuNum < 1000) {
+                        // First generation CPUs are three digit SKUs.
+                        cpuGeneration = 1;
                     }
-                }
-                break;
-            // The indomitable Linux.
-            case "linux":
-                // Let's further see if we're a small, but scrappy, Raspberry Pi.
-                try {
-                    // As of the 4.9 kernel, Raspberry Pi prefers to be identified using this method and has deprecated cpuinfo.
-                    const systemId = readFileSync("/sys/firmware/devicetree/base/model", { encoding: "utf8" });
-                    // Is it a Pi 4?
-                    if (/Raspberry Pi (Compute Module )?4/.test(systemId)) {
-                        this._hostSystem = "raspbian";
+                    else if (skuStr.length > 4) {
+                        // For five-digit SKUs, the generation are the leading digits before the last three.
+                        cpuGeneration = Number(skuStr.slice(0, skuStr.length - 3));
                     }
-                }
-                catch (error) {
-                    // We aren't especially concerned with errors here, given we're just trying to ascertain the system information through hints.
-                }
-                // Identify what generation of Intel CPU we have if we're on Intel.
-                if (cpuModelString.includes("Intel")) {
-                    // Extract the CPU model.
-                    const cpuModel = /Intel.*Core.*i\d+-(\d{3,5})/i.exec(cpuModelString);
-                    this._cpuGeneration = 0;
-                    if (cpuModel?.[1]) {
-                        // Grab the individual SKU as both a number and string.
-                        const skuStr = cpuModel[1];
-                        const skuNum = Number(skuStr);
-                        // Now deduce the CPU generation.
-                        if (skuNum < 1000) {
-                            // First generation CPUs are three digit SKUs.
-                            this._cpuGeneration = 1;
-                        }
-                        else if (skuStr.length > 4) {
-                            // For five-digit SKUs, the generation are the leading digits before the last three.
-                            this._cpuGeneration = Number(skuStr.slice(0, skuStr.length - 3));
-                        }
-                        else {
-                            // Finally, for four-digit SKUs, the generation is the first digit.
-                            this._cpuGeneration = Number(skuStr.charAt(0));
-                        }
+                    else {
+                        // Finally, for four-digit SKUs, the generation is the first digit.
+                        cpuGeneration = Number(skuStr.charAt(0));
                     }
                 }
-                break;
-            default:
-                // We aren't trying to solve for every system type.
-                break;
+            }
+            break;
+        default:
+            // We aren't trying to solve for every system type.
+            break;
+    }
+    return { cpuGeneration, hostSystem };
+}
+// Probe the FFmpeg version string via `ffmpeg -hide_banner -version`. Returns the parsed version string, or `null` on probe failure.
+async function probeFfmpegVersion(ffmpegExec, log, signal) {
+    let version = null;
+    const ok = await probeCmd(ffmpegExec, ["-hide_banner", "-version"], (stdout) => {
+        version = parseFfmpegVersion(stdout);
+    }, { log, signal });
+    return ok ? version : null;
+}
+// Probe the FFmpeg codec inventory via `ffmpeg -hide_banner -codecs`. Returns a format-keyed index, or `null` on probe failure.
+async function probeFfmpegCodecs(ffmpegExec, log, signal) {
+    let parsed = null;
+    const ok = await probeCmd(ffmpegExec, ["-hide_banner", "-codecs"], (stdout) => {
+        parsed = parseFfmpegCodecs(stdout);
+    }, { log, signal });
+    return ok ? parsed : null;
+}
+// Probe the FFmpeg hardware-accelerator inventory via `ffmpeg -hide_banner -hwaccels`, then validate each advertised accel by running a one-second synthetic transcode
+// that initializes the hardware-acceleration context. The validation catches the case where a build advertises an accel the host hardware cannot actually use;
+// discarding those accelerators here means callers don't have to re-validate downstream.
+async function probeFfmpegHwAccels(ffmpegExec, verbose, log, signal) {
+    const hwAccels = new Set();
+    const ok = await probeCmd(ffmpegExec, ["-hide_banner", "-hwaccels"], (stdout) => {
+        for (const accel of parseFfmpegHwAccels(stdout)) {
+            hwAccels.add(accel);
         }
+    }, { log, signal });
+    if (!ok) {
+        return null;
     }
-    // Probe Raspberry Pi GPU capabilities.
-    async probeRpiGpuMem() {
-        return this.probeCmd("vcgencmd", ["get_mem", "gpu"], (stdout) => {
-            // A regular expression to parse out the configured GPU memory on the Raspberry Pi.
-            const gpuRegex = /^gpu=(.*)M\n$/;
-            // Let's see what we've got.
-            const gpuMatch = gpuRegex.exec(stdout);
-            // Parse the result and retrieve our allocated GPU memory.
-            this._gpuMem = Number.parseInt(gpuMatch?.[1] ?? "", 10) || 0;
-        });
+    // Capability validation per accel. Hardware / driver availability can diverge from FFmpeg's advertised build capabilities (e.g., `videotoolbox` is always present in
+    // macOS builds but unusable on Intel Macs running a pre-VT OS). A quick synthetic transcode against each accel tells us which ones actually work on this host.
+    for (const accel of hwAccels) {
+        // Validate one accel at a time rather than in parallel: each synthetic transcode initializes the same underlying hardware-acceleration context (GPU or codec
+        // engine), so concurrent probes would contend for that shared resource and risk a false negative - an accel reported as unusable because of contention with a
+        // sibling probe rather than a genuine host incapability. This is a one-time startup probe, not a throughput-sensitive workload, so serializing it here costs nothing
+        // that matters.
+        // eslint-disable-next-line no-await-in-loop
+        const accelOk = await probeCmd(ffmpegExec, [
+            "-hide_banner", "-hwaccel", accel, "-v", "quiet", "-t", "1", "-f", "lavfi", "-i", "color=black:1920x1080", "-c:v", "libx264", "-f", "null", "-"
+        ], () => { }, { log, quietRunErrors: true, signal });
+        if (!accelOk) {
+            hwAccels.delete(accel);
+            if (verbose) {
+                log.error("Hardware-accelerated decoding and encoding using %s will be unavailable: unable to successfully validate capabilities.", accel);
+            }
+        }
+    }
+    return hwAccels;
+}
+// Probe Raspberry Pi GPU memory via `vcgencmd get_mem gpu`. Returns the megabyte value, or `0` on probe failure (the caller's configureHwAccel gate treats `0` as
+// insufficient anyway, so the return-value distinction is cosmetic but keeps the null handling consistent with the other probes).
+async function probeRpiGpuMem(log, signal) {
+    let gpuMem = 0;
+    await probeCmd("vcgencmd", ["get_mem", "gpu"], (stdout) => {
+        gpuMem = parseRpiGpuMem(stdout);
+    }, { log, signal });
+    return gpuMem;
+}
+// Utility to run a probe subcommand under a composed signal (caller's signal + a per-probe watchdog timeout). The caller's processOutput handler receives the stdout on
+// success; a returned `true` indicates the command completed and the output was handed off. An ENOENT failure (the binary could not be found) always logs regardless of
+// `quietRunErrors`, since a missing binary is worth surfacing no matter the caller's intent; other failures log unless `quietRunErrors` is set - that flag exists for
+// the per-accel validation loop where failures are expected and logged at a higher level by the caller.
+async function probeCmd(command, commandLineArgs, processOutput, options) {
+    const { log, quietRunErrors = false, signal: callerSignal } = options;
+    // Always compose with a per-probe watchdog timeout so the worst-case outcome is bounded. When the caller also supplies a signal, `composeSignals` falls through to
+    // `AbortSignal.any()`; when no caller signal is supplied, the timeout alone governs (composeSignals returns it unwrapped).
+    const composed = composeSignals(callerSignal, AbortSignal.timeout(PROBE_DEFAULT_TIMEOUT_MS));
+    try {
+        const { stdout } = await execFileAsync(command, commandLineArgs, { signal: composed });
+        processOutput(stdout);
+        return true;
     }
-    // Utility to probe the capabilities of FFmpeg and the host platform.
-    async probeCmd(command, commandLineArgs, processOutput, quietRunErrors = false) {
-        try {
-            // Check for the codecs in our video processor.
-            const { stdout } = await execFileAsync(command, commandLineArgs);
-            processOutput(stdout);
-            return true;
+    catch (error) {
+        const execError = error;
+        if (execError.code === "ENOENT") {
+            log.error("Unable to find '%s' in path: '%s'.", command, env["PATH"]);
+            return false;
         }
-        catch (error) {
-            const execError = error;
-            if (execError.code === "ENOENT") {
-                this.log.error("Unable to find '%s' in path: '%s'.", command, env.PATH);
-            }
-            else if (quietRunErrors) {
-                return false;
-            }
-            else {
-                this.log.error("Error running %s: %s", command, execError.message);
-            }
-            this.log.error("Unable to probe the capabilities of your Homebridge host without access to '%s'. Ensure that it is available in your path and correctly working.", command);
+        else if (quietRunErrors) {
             return false;
         }
+        else {
+            log.error("Error running %s: %s.", command, execError.message.replace(/\.$/, ""));
+        }
+        log.error("Unable to probe the capabilities of your Homebridge host without access to '%s'. Ensure that it is available in your path and correctly working.", command);
+        return false;
     }
 }
 //# sourceMappingURL=codecs.js.map