@apocaliss92/nodelink-js 0.5.2 → 0.6.0

package/dist/index.d.cts

@@ -5284,6 +5284,88 @@ interface CompositeStreamPipOptions {
     teleRtspUrl?: string;
     /** ffmpeg `-rtsp_transport` value (default: tcp). */
     rtspTransport?: 'tcp' | 'udp';
+    /**
+     * Absolute path to the `ffmpeg` binary the compositor should `spawn()`.
+     *
+     * When unset, falls back to the bare string `"ffmpeg"`, which relies on
+     * the host's `PATH`. This works on standard Linux / macOS Node setups
+     * but fails silently on environments where the embedding process
+     * strips PATH or ships its own ffmpeg in a non-discoverable location:
+     *
+     *  - Scrypted on Windows (the Electron host launches plugins with a
+     *    minimal PATH; the bundled ffmpeg lives at a static absolute path
+     *    only `sdk.mediaManager.getFFmpegPath()` knows about).
+     *  - Scrypted on macOS App Store / sandboxed installs.
+     *  - Distroless / minimal Docker base images where ffmpeg is mounted
+     *    at a fixed path but not in PATH.
+     *
+     * Consumers in any of those environments should resolve the path
+     * themselves (e.g. via the Scrypted SDK) and pass it through here.
+     */
+    ffmpegPath?: string;
+    /**
+     * Output video encoder name (passed verbatim as `-c:v`). Default
+     * `libx264` — pure software. On a host with hardware-accelerated
+     * H.264 encoding, switching this is the single biggest perf win
+     * available (5-10x less CPU for the same output bitrate). Supported
+     * by ffmpeg in the wild:
+     *
+     *  - Intel/AMD QuickSync:  `h264_qsv`
+     *  - Intel/AMD VAAPI:      `h264_vaapi`
+     *  - NVIDIA NVENC:         `h264_nvenc`
+     *  - Apple VideoToolbox:   `h264_videotoolbox`
+     *  - Raspberry Pi / ARM:   `h264_v4l2m2m`
+     *
+     * Caveat: when not `libx264`, the libx264-specific knobs
+     * (`encoderPreset`, `crf`, `x264-params`) are silently dropped because
+     * each HW encoder has its own option vocabulary. Use
+     * {@link extraOutputArgs} to pass encoder-specific options
+     * (e.g. `["-q:v","23"]` for QSV, `["-preset","fast"]` for NVENC).
+     */
+    videoEncoder?: string;
+    /**
+     * libx264 preset (default `ultrafast`). Only consulted when
+     * {@link videoEncoder} is left at its default (libx264). Valid:
+     * `ultrafast | superfast | veryfast | faster | fast | medium | slow |
+     * slower | veryslow | placebo`. Slower = better compression / more CPU.
+     */
+    encoderPreset?: string;
+    /**
+     * CRF (constant rate factor) for libx264. Default 23 (visually
+     * lossless-ish). Range 0 (lossless, huge) — 51 (worst, tiny). Lower
+     * by 2 to roughly halve the bitrate at a given quality. Only consulted
+     * when {@link videoEncoder} is libx264.
+     */
+    crf?: number;
+    /**
+     * Output keyframe interval in seconds. Default 1 — important for
+     * mid-stream join latency (a new HLS / RTSP client only starts
+     * decoding from the next keyframe). Lower = faster join, larger
+     * stream; higher = better compression, slower join.
+     */
+    gopSeconds?: number;
+    /**
+     * Free-form ffmpeg arguments inserted at the START of the argv (after
+     * `-hide_banner -loglevel`). Use for hardware-accel decode hints that
+     * must appear before any `-i`:
+     *
+     *   extraGlobalArgs: ["-hwaccel","videotoolbox"]
+     *   extraGlobalArgs: ["-hwaccel","qsv","-qsv_device","/dev/dri/renderD128"]
+     *
+     * No validation — invalid args here WILL crash ffmpeg.
+     */
+    extraGlobalArgs?: readonly string[];
+    /**
+     * Free-form ffmpeg arguments inserted just BEFORE the `pipe:1` output.
+     * Use for encoder-specific options when {@link videoEncoder} is not
+     * `libx264`:
+     *
+     *   extraOutputArgs: ["-q:v","23"]                  // qsv/vaapi
+     *   extraOutputArgs: ["-preset","fast","-rc","cbr"] // nvenc
+     *
+     * No validation — invalid args here WILL crash ffmpeg.
+     */
+    extraOutputArgs?: readonly string[];
 }
 type CompositeStreamOptions = {
     api: ReolinkBaichuanApi;
@@ -5326,6 +5408,24 @@ type CompositeStreamOptions = {
     teleRtspUrl?: string;
     /** ffmpeg `-rtsp_transport` value (default: tcp). */
     rtspTransport?: 'tcp' | 'udp';
+    /**
+     * Absolute path to the `ffmpeg` binary the compositor should `spawn()`.
+     * Mirrors {@link CompositeStreamPipOptions.ffmpegPath} — see its docstring
+     * for the rationale. Defaults to `"ffmpeg"` (PATH lookup) when unset.
+     */
+    ffmpegPath?: string;
+    /** See {@link CompositeStreamPipOptions.videoEncoder}. */
+    videoEncoder?: string;
+    /** See {@link CompositeStreamPipOptions.encoderPreset}. */
+    encoderPreset?: string;
+    /** See {@link CompositeStreamPipOptions.crf}. */
+    crf?: number;
+    /** See {@link CompositeStreamPipOptions.gopSeconds}. */
+    gopSeconds?: number;
+    /** See {@link CompositeStreamPipOptions.extraGlobalArgs}. */
+    extraGlobalArgs?: readonly string[];
+    /** See {@link CompositeStreamPipOptions.extraOutputArgs}. */
+    extraOutputArgs?: readonly string[];
     /**
      * How long to wait for each input stream to produce frames before starting ffmpeg.
      * Battery cameras can take several seconds to wake and begin streaming.

package/dist/index.d.ts

@@ -4145,6 +4145,24 @@ export declare type CompositeStreamOptions = {
     teleRtspUrl?: string;
     /** ffmpeg `-rtsp_transport` value (default: tcp). */
     rtspTransport?: 'tcp' | 'udp';
+    /**
+     * Absolute path to the `ffmpeg` binary the compositor should `spawn()`.
+     * Mirrors {@link CompositeStreamPipOptions.ffmpegPath} — see its docstring
+     * for the rationale. Defaults to `"ffmpeg"` (PATH lookup) when unset.
+     */
+    ffmpegPath?: string;
+    /** See {@link CompositeStreamPipOptions.videoEncoder}. */
+    videoEncoder?: string;
+    /** See {@link CompositeStreamPipOptions.encoderPreset}. */
+    encoderPreset?: string;
+    /** See {@link CompositeStreamPipOptions.crf}. */
+    crf?: number;
+    /** See {@link CompositeStreamPipOptions.gopSeconds}. */
+    gopSeconds?: number;
+    /** See {@link CompositeStreamPipOptions.extraGlobalArgs}. */
+    extraGlobalArgs?: readonly string[];
+    /** See {@link CompositeStreamPipOptions.extraOutputArgs}. */
+    extraOutputArgs?: readonly string[];
     /**
      * How long to wait for each input stream to produce frames before starting ffmpeg.
      * Battery cameras can take several seconds to wake and begin streaming.
@@ -4192,6 +4210,88 @@ export declare interface CompositeStreamPipOptions {
     teleRtspUrl?: string;
     /** ffmpeg `-rtsp_transport` value (default: tcp). */
     rtspTransport?: 'tcp' | 'udp';
+    /**
+     * Absolute path to the `ffmpeg` binary the compositor should `spawn()`.
+     *
+     * When unset, falls back to the bare string `"ffmpeg"`, which relies on
+     * the host's `PATH`. This works on standard Linux / macOS Node setups
+     * but fails silently on environments where the embedding process
+     * strips PATH or ships its own ffmpeg in a non-discoverable location:
+     *
+     *  - Scrypted on Windows (the Electron host launches plugins with a
+     *    minimal PATH; the bundled ffmpeg lives at a static absolute path
+     *    only `sdk.mediaManager.getFFmpegPath()` knows about).
+     *  - Scrypted on macOS App Store / sandboxed installs.
+     *  - Distroless / minimal Docker base images where ffmpeg is mounted
+     *    at a fixed path but not in PATH.
+     *
+     * Consumers in any of those environments should resolve the path
+     * themselves (e.g. via the Scrypted SDK) and pass it through here.
+     */
+    ffmpegPath?: string;
+    /**
+     * Output video encoder name (passed verbatim as `-c:v`). Default
+     * `libx264` — pure software. On a host with hardware-accelerated
+     * H.264 encoding, switching this is the single biggest perf win
+     * available (5-10x less CPU for the same output bitrate). Supported
+     * by ffmpeg in the wild:
+     *
+     *  - Intel/AMD QuickSync:  `h264_qsv`
+     *  - Intel/AMD VAAPI:      `h264_vaapi`
+     *  - NVIDIA NVENC:         `h264_nvenc`
+     *  - Apple VideoToolbox:   `h264_videotoolbox`
+     *  - Raspberry Pi / ARM:   `h264_v4l2m2m`
+     *
+     * Caveat: when not `libx264`, the libx264-specific knobs
+     * (`encoderPreset`, `crf`, `x264-params`) are silently dropped because
+     * each HW encoder has its own option vocabulary. Use
+     * {@link extraOutputArgs} to pass encoder-specific options
+     * (e.g. `["-q:v","23"]` for QSV, `["-preset","fast"]` for NVENC).
+     */
+    videoEncoder?: string;
+    /**
+     * libx264 preset (default `ultrafast`). Only consulted when
+     * {@link videoEncoder} is left at its default (libx264). Valid:
+     * `ultrafast | superfast | veryfast | faster | fast | medium | slow |
+     * slower | veryslow | placebo`. Slower = better compression / more CPU.
+     */
+    encoderPreset?: string;
+    /**
+     * CRF (constant rate factor) for libx264. Default 23 (visually
+     * lossless-ish). Range 0 (lossless, huge) — 51 (worst, tiny). Lower
+     * by 2 to roughly halve the bitrate at a given quality. Only consulted
+     * when {@link videoEncoder} is libx264.
+     */
+    crf?: number;
+    /**
+     * Output keyframe interval in seconds. Default 1 — important for
+     * mid-stream join latency (a new HLS / RTSP client only starts
+     * decoding from the next keyframe). Lower = faster join, larger
+     * stream; higher = better compression, slower join.
+     */
+    gopSeconds?: number;
+    /**
+     * Free-form ffmpeg arguments inserted at the START of the argv (after
+     * `-hide_banner -loglevel`). Use for hardware-accel decode hints that
+     * must appear before any `-i`:
+     *
+     *   extraGlobalArgs: ["-hwaccel","videotoolbox"]
+     *   extraGlobalArgs: ["-hwaccel","qsv","-qsv_device","/dev/dri/renderD128"]
+     *
+     * No validation — invalid args here WILL crash ffmpeg.
+     */
+    extraGlobalArgs?: readonly string[];
+    /**
+     * Free-form ffmpeg arguments inserted just BEFORE the `pipe:1` output.
+     * Use for encoder-specific options when {@link videoEncoder} is not
+     * `libx264`:
+     *
+     *   extraOutputArgs: ["-q:v","23"]                  // qsv/vaapi
+     *   extraOutputArgs: ["-preset","fast","-rc","cbr"] // nvenc
+     *
+     * No validation — invalid args here WILL crash ffmpeg.
+     */
+    extraOutputArgs?: readonly string[];
 }
 
 /**

package/dist/index.js

@@ -2517,10 +2517,18 @@ var CompositeStream = class extends EventEmitter {
     }
   }
   async startFfmpegCompositionFromRtspUrls(mainWidth, mainHeight, pipWidth, pipHeight, position, widerRtspUrl, teleRtspUrl, rtspTransport) {
+    const videoEncoder = this.options.videoEncoder ?? "libx264";
+    const isX264 = videoEncoder === "libx264";
+    const encoderPreset = this.options.encoderPreset ?? "ultrafast";
+    const crf = this.options.crf ?? 23;
+    const gopSeconds = this.options.gopSeconds ?? 1;
+    const assumedFps = 30;
+    const gopFrames = Math.max(1, Math.round(gopSeconds * assumedFps));
     const ffmpegArgs = [
       "-hide_banner",
       "-loglevel",
       "error",
+      ...this.options.extraGlobalArgs ?? [],
       "-fflags",
       "+genpts",
       // Input 0: wider
@@ -2541,27 +2549,33 @@ var CompositeStream = class extends EventEmitter {
       // Output: always H.264 Annex-B
       "-an",
       "-c:v",
-      "libx264",
+      videoEncoder,
       "-g",
-      "30",
+      String(gopFrames),
       "-keyint_min",
-      "30",
+      String(gopFrames),
       "-sc_threshold",
       "0",
-      "-x264-params",
-      "aud=1:repeat-headers=1:keyint=30:min-keyint=30:scenecut=0",
-      "-preset",
-      "ultrafast",
-      "-tune",
-      "zerolatency",
-      "-crf",
-      "23",
+      ...isX264 ? [
+        "-x264-params",
+        `aud=1:repeat-headers=1:keyint=${gopFrames}:min-keyint=${gopFrames}:scenecut=0`,
+        "-preset",
+        encoderPreset,
+        "-tune",
+        "zerolatency",
+        "-crf",
+        String(crf)
+      ] : [],
+      ...this.options.extraOutputArgs ?? [],
       "-f",
       "h264",
       "pipe:1"
     ];
-    this.logger.log?.(`[CompositeStream] Starting ffmpeg (rtsp inputs): ${ffmpegArgs.join(" ")}`);
-    this.ffmpegProcess = spawn3("ffmpeg", ffmpegArgs, {
+    const ffmpegBin = this.options.ffmpegPath ?? "ffmpeg";
+    this.logger.log?.(
+      `[CompositeStream] Starting ffmpeg (rtsp inputs): bin=${ffmpegBin} args=${ffmpegArgs.join(" ")}`
+    );
+    this.ffmpegProcess = spawn3(ffmpegBin, ffmpegArgs, {
       stdio: ["ignore", "pipe", "pipe"]
     });
     this.ffmpegProcess.on("error", (error) => {
@@ -2628,10 +2642,18 @@ var CompositeStream = class extends EventEmitter {
       "-i",
       "pipe:3"
     ];
+    const videoEncoder = this.options.videoEncoder ?? "libx264";
+    const isX264 = videoEncoder === "libx264";
+    const encoderPreset = this.options.encoderPreset ?? "ultrafast";
+    const crf = this.options.crf ?? 23;
+    const gopSeconds = this.options.gopSeconds ?? 1;
+    const assumedFps = 30;
+    const gopFrames = Math.max(1, Math.round(gopSeconds * assumedFps));
     const ffmpegArgs = [
       "-hide_banner",
       "-loglevel",
       "error",
+      ...this.options.extraGlobalArgs ?? [],
       "-fflags",
       "+genpts",
       "-probesize",
@@ -2650,33 +2672,40 @@ var CompositeStream = class extends EventEmitter {
       "-map",
       "[out]",
       "-c:v",
-      "libx264",
-      // Re-encode for compatibility
-      // Make the stream easy to join mid-flight: frequent IDRs + in-band headers + AUD.
-      // Without this, a new client may wait many seconds for the next keyframe.
+      videoEncoder,
+      // Make the stream easy to join mid-flight: frequent IDRs + in-band
+      // headers + AUD. Without this, a new client may wait many seconds
+      // for the next keyframe.
       "-g",
-      "30",
+      String(gopFrames),
       "-keyint_min",
-      "30",
+      String(gopFrames),
       "-sc_threshold",
       "0",
-      "-x264-params",
-      "aud=1:repeat-headers=1:keyint=30:min-keyint=30:scenecut=0",
-      "-preset",
-      "ultrafast",
-      "-tune",
-      "zerolatency",
-      "-crf",
-      "23",
+      // libx264-specific knobs. We deliberately skip these for HW encoders
+      // — each one has its own option vocabulary (`-q:v`, `-rc`, etc.)
+      // and the user is expected to express them via extraOutputArgs.
+      ...isX264 ? [
+        "-x264-params",
+        `aud=1:repeat-headers=1:keyint=${gopFrames}:min-keyint=${gopFrames}:scenecut=0`,
+        "-preset",
+        encoderPreset,
+        "-tune",
+        "zerolatency",
+        "-crf",
+        String(crf)
+      ] : [],
+      ...this.options.extraOutputArgs ?? [],
       "-f",
       "h264",
       "pipe:1"
       // Output (stdout)
     ];
+    const ffmpegBin = this.options.ffmpegPath ?? "ffmpeg";
     this.logger.log?.(
-      `[CompositeStream] Starting ffmpeg: ${ffmpegArgs.join(" ")}`
+      `[CompositeStream] Starting ffmpeg: bin=${ffmpegBin} args=${ffmpegArgs.join(" ")}`
     );
-    this.ffmpegProcess = spawn3("ffmpeg", ffmpegArgs, {
+    this.ffmpegProcess = spawn3(ffmpegBin, ffmpegArgs, {
       stdio: ["pipe", "pipe", "pipe", "pipe"]
     });
     this.ffmpegProcess.on("error", (error) => {
@@ -3384,6 +3413,20 @@ async function createRfc4571TcpServerInternal(options) {
       ...forceH264 !== void 0 ? { forceH264 } : defaultForceH264 ? { forceH264: true } : {},
       ...compositeOptions?.assumeH264Inputs !== void 0 ? { assumeH264Inputs: compositeOptions.assumeH264Inputs } : {},
       ...compositeOptions?.disableTranscode !== void 0 ? { disableTranscode: compositeOptions.disableTranscode } : {},
+      // Propagate ffmpeg binary path — required when the embedder strips
+      // PATH (Scrypted on Windows, Electron sandboxes, distroless Docker)
+      // and the bundled ffmpeg is at a fixed absolute path only the
+      // embedder knows.
+      ...compositeOptions?.ffmpegPath ? { ffmpegPath: compositeOptions.ffmpegPath } : {},
+      // Encoder tuning knobs — see CompositeStreamPipOptions for the
+      // semantic contract on each one. Plumbed verbatim so the
+      // CompositeStream layer can apply defaults.
+      ...compositeOptions?.videoEncoder ? { videoEncoder: compositeOptions.videoEncoder } : {},
+      ...compositeOptions?.encoderPreset ? { encoderPreset: compositeOptions.encoderPreset } : {},
+      ...typeof compositeOptions?.crf === "number" ? { crf: compositeOptions.crf } : {},
+      ...typeof compositeOptions?.gopSeconds === "number" ? { gopSeconds: compositeOptions.gopSeconds } : {},
+      ...compositeOptions?.extraGlobalArgs ? { extraGlobalArgs: compositeOptions.extraGlobalArgs } : {},
+      ...compositeOptions?.extraOutputArgs ? { extraOutputArgs: compositeOptions.extraOutputArgs } : {},
       logger
     });
     isCompositeStream = true;