homebridge-plugin-utils 1.15.2 → 1.16.0

package/dist/ffmpeg/codecs.js

@@ -0,0 +1,374 @@
+/* Copyright(C) 2023-2025, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * ffmpeg/codecs.ts: Probe FFmpeg capabilities and codecs.
+ */
+/**
+ * Probe FFmpeg capabilities and codecs on the host system.
+ *
+ * Utilities for dynamically probing FFmpeg capabilities on the host system, including codec and hardware acceleration support.
+ *
+ * This module provides classes and interfaces to detect which FFmpeg encoders, decoders, and hardware acceleration methods are available, as well as host platform
+ * detection (such as macOS or Raspberry Pi specifics) that directly impact transcoding or livestreaming use cases. It enables advanced plugin development by allowing
+ * dynamic adaptation to the host's video processing features, helping ensure compatibility and optimal performance when working with camera-related Homebridge plugins
+ * that leverage FFmpeg.
+ *
+ * Key features include:
+ *
+ * - Querying the FFmpeg version, available codecs, and hardware acceleration methods.
+ * - Detecting host hardware platform details that are relevant to transcoding in FFmpeg.
+ * - Checking for the presence of specific encoders/decoders and validating hardware acceleration support.
+ *
+ * This module is intended for use by plugin developers or advanced users who need to introspect and adapt to system-level FFmpeg capabilities programmatically.
+ *
+ * @module
+ */
+import { EOL, cpus } from "node:os";
+import { env, platform } from "node:process";
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import util from "node:util";
+/**
+ * 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 class FfmpegCodecs {
+    /**
+     * The path or command name to invoke FFmpeg.
+     */
+    ffmpegExec;
+    _ffmpegVersion;
+    _gpuMem;
+    _hostSystem;
+    log;
+    ffmpegCodecs;
+    ffmpegHwAccels;
+    /**
+     * Indicates whether verbose logging is enabled for FFmpeg probing.
+     */
+    verbose;
+    /**
+     * Creates an instance of `FfmpegCodecs`.
+     *
+     * @param options - Options used to configure FFmpeg probing.
+     */
+    constructor(options) {
+        this._gpuMem = 0;
+        this._ffmpegVersion = "";
+        this._hostSystem = "";
+        this.ffmpegExec = options.ffmpegExec ?? "ffmpeg";
+        this.ffmpegCodecs = {};
+        this.ffmpegHwAccels = {};
+        this.log = options.log;
+        this.verbose ??= options.verbose ?? false;
+        // Detect our host system type.
+        this.probeHwOs();
+    }
+    /**
+     * 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.");
+     * }
+     * ```
+     */
+    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;
+    }
+    /**
+     * 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, decoder) {
+        // Normalize our lookups.
+        codec = codec.toLowerCase();
+        decoder = decoder.toLowerCase();
+        return this.ffmpegCodecs[codec]?.decoders.some(x => x === decoder);
+    }
+    /**
+     * 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, encoder) {
+        // Normalize our lookups.
+        codec = codec.toLowerCase();
+        encoder = encoder.toLowerCase();
+        return this.ffmpegCodecs[codec]?.encoders.some(x => x === encoder);
+    }
+    /**
+     * 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) {
+        return this.ffmpegHwAccels[accel.toLowerCase()] ? true : false;
+    }
+    /**
+     * 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;
+    }
+    /**
+     * Returns the detected FFmpeg version string, or "unknown" if detection failed.
+     */
+    get ffmpegVersion() {
+        return this._ffmpegVersion;
+    }
+    /**
+     * 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;
+    }
+    // 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);
+        });
+    }
+    // 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;
+                }
+                // We've found a hardware acceleration method, let's add it.
+                this.ffmpegHwAccels[accel.toLowerCase()] = true;
+            }
+        }))) {
+            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 Object.keys(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))) {
+                delete this.ffmpegHwAccels[accel];
+                if (this.verbose) {
+                    this.log.error("Hardware-accelerated decoding and encoding using %s will be unavailable: unable to successfully validate capabilities.", accel);
+                }
+            }
+        }
+        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 it's supported decoders.
+            const decodersRegex = /\S+\s+(\S+).+\(decoders: (.*?)\s*\)/;
+            // A regular expression to parse out the codec and it's 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: [], encoders: [] };
+                    this.ffmpegCodecs[decodersMatch[1]].decoders = decodersMatch[2].split(" ").map(x => x.toLowerCase());
+                }
+                // If we found decoders, add them to our list of supported decoders for this format.
+                if (encodersMatch) {
+                    if (!this.ffmpegCodecs[encodersMatch[1]]) {
+                        this.ffmpegCodecs[encodersMatch[1]] = { decoders: [], encoders: [] };
+                    }
+                    this.ffmpegCodecs[encodersMatch[1]].encoders = encodersMatch[2].split(" ").map(x => x.toLowerCase());
+                }
+            }
+        });
+    }
+    // Identify what hardware and operating system environment we're actually running on.
+    probeHwOs() {
+        // Start off with a generic identifier.
+        this._hostSystem = "generic";
+        // 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." + (cpus()[0].model.includes("Apple") ? "Apple" : "Intel");
+                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";
+                    }
+                }
+                catch (error) {
+                    // We aren't especially concerned with errors here, given we're just trying to ascertain the system information through hints.
+                }
+                break;
+            default:
+                // We aren't trying to solve for every system type.
+                break;
+        }
+    }
+    // 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);
+            // We matched what we're looking for.
+            if (gpuMatch) {
+                // Parse the result and retrieve our allocated GPU memory.
+                this._gpuMem = parseInt(gpuMatch[1]);
+                // Something went wrong.
+                if (isNaN(this._gpuMem)) {
+                    this._gpuMem = 0;
+                }
+            }
+        });
+    }
+    // Utility to probe the capabilities of FFmpeg and the host platform.
+    async probeCmd(command, commandLineArgs, processOutput, quietRunErrors = false) {
+        try {
+            // Promisify exec to allow us to wait for it asynchronously.
+            const execAsync = util.promisify(execFile);
+            // Check for the codecs in our video processor.
+            const { stdout } = await execAsync(command, commandLineArgs);
+            processOutput(stdout);
+            return true;
+        }
+        catch (error) {
+            // It's really a SystemError, but Node hides that type from us for esoteric reasons.
+            if (error instanceof 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, error.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);
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=codecs.js.map

package/dist/ffmpeg/codecs.js.map

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

package/dist/ffmpeg/exec.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Executes arbitrary FFmpeg commands and returns the results.
+ *
+ * This module exposes the `FfmpegExec` class, which extends the core process handling of FFmpeg to support running custom command-line operations. It enables developers
+ * to run FFmpeg commands from Node.js, capture both standard output and error streams, handle process exit codes, and optionally supply input via stdin.
+ *
+ * Intended for plugin developers and advanced users, this module is ideal for scenarios where you need direct control over FFmpeg execution—such as probing media,
+ * transcoding, or automation tasks—while still benefiting from structured result handling and robust error logging.
+ *
+ * Key features:
+ *
+ * - Execute any FFmpeg command with custom arguments.
+ * - Capture stdout, stderr, and exit codes as structured results.
+ * - Optional stdin data injection.
+ * - Configurable error logging.
+ *
+ * @module
+ */
+import type { FfmpegOptions } from "./options.js";
+import { FfmpegProcess } from "./process.js";
+import type { Nullable } from "../util.js";
+/**
+ * Describes the result of executing an FFmpeg process.
+ *
+ * @property exitCode        - The process exit code, or `null` if not available.
+ * @property stderr          - The standard error output as a Buffer.
+ * @property stdout          - The standard output as a Buffer.
+ *
+ * @category FFmpeg
+ */
+export type ProcessResult = {
+    exitCode: Nullable<number>;
+    stderr: Buffer;
+    stdout: Buffer;
+};
+/**
+ * Executes arbitrary FFmpeg commands and returns the results.
+ *
+ * This class extends `FfmpegProcess` to provide a simple interface for running FFmpeg with custom command-line arguments, capturing both standard output and standard
+ * error, and returning process results in a structured format. Intended for plugin authors and advanced users who need to programmatically execute FFmpeg commands and
+ * capture their results.
+ *
+ * @example
+ *
+ * ```ts
+ * const exec = new FfmpegExec(options, ["-version"]);
+ * const result = await exec.exec();
+ *
+ * if(result && result.exitCode === 0) {
+ *
+ *   console.log(result.stdout.toString());
+ * }
+ * ```
+ *
+ * @see FfmpegProcess
+ * @see {@link https://ffmpeg.org/documentation.html | FFmpeg Documentation}
+ *
+ * @category FFmpeg
+ */
+export declare class FfmpegExec extends FfmpegProcess {
+    private isLoggingErrors;
+    /**
+     * Creates a new instance of `FfmpegExec`.
+     *
+     * @param options          - The options used to configure FFmpeg execution.
+     * @param commandLineArgs  - Optional. Command-line arguments to pass to the FFmpeg process.
+     * @param logErrors        - Optional. If `true`, errors will be logged; otherwise, they will be suppressed. Defaults to `true`.
+     *
+     * @example
+     *
+     * ```ts
+     * const exec = new FfmpegExec(options, ["-i", "input.mp4", "-f", "null", "-"]);
+     * ```
+     */
+    constructor(options: FfmpegOptions, commandLineArgs?: string[], logErrors?: boolean);
+    /**
+     * Runs the FFmpeg process and returns the result, including exit code, stdout, and stderr.
+     *
+     * If `stdinData` is provided, it will be written to the process's standard input before execution. Returns `null` if the process fails to start.
+     *
+     * @param stdinData        - Optional. Data to write to FFmpeg's standard input.
+     *
+     * @returns A promise that resolves to a `ProcessResult` object containing the exit code, stdout, and stderr, or `null` if the process could not be started.
+     *
+     * @example
+     *
+     * ```ts
+     * const exec = new FfmpegExec(options, ["-i", "input.wav", "output.mp3"]);
+     * const result = await exec.exec();
+     *
+     * if(result) {
+     *
+     *   console.log("Exit code:", result.exitCode);
+     *   console.log("FFmpeg output:", result.stdout.toString());
+     * }
+     * ```
+     */
+    exec(stdinData?: Buffer): Promise<Nullable<ProcessResult>>;
+    /**
+     * Logs errors encountered during FFmpeg execution.
+     *
+     * If error logging is disabled, this method will do nothing. Otherwise, it calls the parent implementation for standard logging behavior.
+     *
+     * @param exitCode         - The exit code returned by the FFmpeg process.
+     * @param signal           - The signal used to terminate the process, if any.
+     */
+    protected logFfmpegError(exitCode: number, signal: NodeJS.Signals): void;
+}

package/dist/ffmpeg/exec.js

@@ -0,0 +1,122 @@
+/* Copyright(C) 2017-2025, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * ffmpeg/exec.ts: Execute arbitrary FFmpeg commands and return the results.
+ */
+import { FfmpegProcess } from "./process.js";
+/**
+ * Executes arbitrary FFmpeg commands and returns the results.
+ *
+ * This class extends `FfmpegProcess` to provide a simple interface for running FFmpeg with custom command-line arguments, capturing both standard output and standard
+ * error, and returning process results in a structured format. Intended for plugin authors and advanced users who need to programmatically execute FFmpeg commands and
+ * capture their results.
+ *
+ * @example
+ *
+ * ```ts
+ * const exec = new FfmpegExec(options, ["-version"]);
+ * const result = await exec.exec();
+ *
+ * if(result && result.exitCode === 0) {
+ *
+ *   console.log(result.stdout.toString());
+ * }
+ * ```
+ *
+ * @see FfmpegProcess
+ * @see {@link https://ffmpeg.org/documentation.html | FFmpeg Documentation}
+ *
+ * @category FFmpeg
+ */
+export class FfmpegExec extends FfmpegProcess {
+    isLoggingErrors;
+    /**
+     * Creates a new instance of `FfmpegExec`.
+     *
+     * @param options          - The options used to configure FFmpeg execution.
+     * @param commandLineArgs  - Optional. Command-line arguments to pass to the FFmpeg process.
+     * @param logErrors        - Optional. If `true`, errors will be logged; otherwise, they will be suppressed. Defaults to `true`.
+     *
+     * @example
+     *
+     * ```ts
+     * const exec = new FfmpegExec(options, ["-i", "input.mp4", "-f", "null", "-"]);
+     * ```
+     */
+    constructor(options, commandLineArgs, logErrors = true) {
+        // Initialize our parent.
+        super(options, commandLineArgs);
+        // We want to log errors when they occur.
+        this.isLoggingErrors = logErrors;
+    }
+    /**
+     * Runs the FFmpeg process and returns the result, including exit code, stdout, and stderr.
+     *
+     * If `stdinData` is provided, it will be written to the process's standard input before execution. Returns `null` if the process fails to start.
+     *
+     * @param stdinData        - Optional. Data to write to FFmpeg's standard input.
+     *
+     * @returns A promise that resolves to a `ProcessResult` object containing the exit code, stdout, and stderr, or `null` if the process could not be started.
+     *
+     * @example
+     *
+     * ```ts
+     * const exec = new FfmpegExec(options, ["-i", "input.wav", "output.mp3"]);
+     * const result = await exec.exec();
+     *
+     * if(result) {
+     *
+     *   console.log("Exit code:", result.exitCode);
+     *   console.log("FFmpeg output:", result.stdout.toString());
+     * }
+     * ```
+     */
+    async exec(stdinData) {
+        return new Promise((resolve) => {
+            this.start();
+            if (this.process === null) {
+                this.log.error("Unable to execute command.");
+                return null;
+            }
+            // Write data to stdin and close
+            if (stdinData) {
+                this.process.stdin.end(stdinData);
+            }
+            const stderr = [];
+            const stdout = [];
+            // Read standard output and standard error into buffers.
+            this.process.stderr.on("data", (chunk) => stderr.push(chunk));
+            this.process.stdout.on("data", (chunk) => stdout.push(chunk));
+            // We prepend this listener to ensure we can properly cleanup after ourselves.
+            this.process.prependOnceListener("exit", () => {
+                // Trigger our process cleanup activities.
+                this.stop();
+            });
+            // Return when process is done.
+            this.process.once("exit", (exitCode) => {
+                // Return the output and results.
+                resolve({
+                    exitCode,
+                    stderr: Buffer.concat(stderr),
+                    stdout: Buffer.concat(stdout)
+                });
+            });
+        });
+    }
+    /**
+     * Logs errors encountered during FFmpeg execution.
+     *
+     * If error logging is disabled, this method will do nothing. Otherwise, it calls the parent implementation for standard logging behavior.
+     *
+     * @param exitCode         - The exit code returned by the FFmpeg process.
+     * @param signal           - The signal used to terminate the process, if any.
+     */
+    logFfmpegError(exitCode, signal) {
+        // If we're ignoring errors, we're done.
+        if (!this.isLoggingErrors) {
+            return;
+        }
+        // Otherwise, revert to our default logging in our parent.
+        super.logFfmpegError(exitCode, signal);
+    }
+}
+//# sourceMappingURL=exec.js.map

package/dist/ffmpeg/exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../src/ffmpeg/exec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAqBH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAmB7C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,UAAW,SAAQ,aAAa;IAEnC,eAAe,CAAU;IAEjC;;;;;;;;;;;;OAYG;IACH,YAAY,OAAsB,EAAE,eAA0B,EAAE,SAAS,GAAG,IAAI;QAE9E,yBAAyB;QACzB,KAAK,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;QAEhC,yCAAyC;QACzC,IAAI,CAAC,eAAe,GAAG,SAAS,CAAC;IACnC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACI,KAAK,CAAC,IAAI,CAAC,SAAkB;QAElC,OAAO,IAAI,OAAO,CAA0B,CAAC,OAAO,EAAE,EAAE;YAEtD,IAAI,CAAC,KAAK,EAAE,CAAC;YAEb,IAAG,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;gBAEzB,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;gBAE7C,OAAO,IAAI,CAAC;YACd,CAAC;YAED,gCAAgC;YAChC,IAAG,SAAS,EAAE,CAAC;gBAEb,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACpC,CAAC;YAED,MAAM,MAAM,GAAa,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAa,EAAE,CAAC;YAE5B,wDAAwD;YACxD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;YACtE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;YAEtE,8EAA8E;YAC9E,IAAI,CAAC,OAAO,CAAC,mBAAmB,CAAC,MAAM,EAAE,GAAG,EAAE;gBAE5C,0CAA0C;gBAC1C,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,CAAC,CAAC,CAAC;YAEH,+BAA+B;YAC/B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE;gBAErC,iCAAiC;gBACjC,OAAO,CAAC;oBAEN,QAAQ;oBACR,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;oBAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;iBAC9B,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACO,cAAc,CAAC,QAAgB,EAAE,MAAsB;QAE/D,wCAAwC;QACxC,IAAG,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;YAEzB,OAAO;QACT,CAAC;QAED,0DAA0D;QAC1D,KAAK,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACzC,CAAC;CAEF"}

package/dist/ffmpeg/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./codecs.js";
+export * from "./exec.js";
+export * from "./options.js";
+export * from "./process.js";
+export * from "./record.js";
+export * from "./rtp.js";
+export * from "./settings.js";
+export * from "./stream.js";

package/dist/ffmpeg/index.js

@@ -0,0 +1,13 @@
+/* Copyright(C) 2017-2025, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * ffmpeg/index.ts: FFmpeg classes.
+ */
+export * from "./codecs.js";
+export * from "./exec.js";
+export * from "./options.js";
+export * from "./process.js";
+export * from "./record.js";
+export * from "./rtp.js";
+export * from "./settings.js";
+export * from "./stream.js";
+//# sourceMappingURL=index.js.map

package/dist/ffmpeg/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ffmpeg/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}