homebridge-plugin-utils 1.35.0 → 2.1.0

package/dist/ffmpeg/record.js

@@ -1,35 +1,66 @@
 /* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
  *
- * ffmpeg/record.ts: Provide FFmpeg process control to support livestreaming and HomeKit Secure Video.
+ * ffmpeg/record.ts: FFmpeg process control for fMP4 recording and livestreaming, composing Mp4SegmentAssembler for the shared pipeline.
  */
+/**
+ * fMP4 FFmpeg processes for HomeKit Secure Video (HKSV) events and livestreaming.
+ *
+ * This module defines an abstract base {@link FfmpegFMp4Process} and its concrete fMP4-mode specializations,
+ * {@link FfmpegRecordingProcess} for HKSV event recording (stdin pipe input, transcoded output) and
+ * {@link FfmpegLivestreamProcess} for fMP4 livestreaming (RTSP input, codec copy). The base exists **solely to centralize
+ * composition wiring** - it owns the internal {@link Mp4SegmentAssembler}, delegates `getInitSegment` / `segments` to it,
+ * and propagates assembler teardown reasons up to the process. It contains no pipeline logic and no command-line assembly;
+ * the byte-to-segment pipeline lives in the assembler so this base stays composition-only.
+ *
+ * Both concrete subclasses:
+ *
+ * - Spawn FFmpeg on construction and expose the inherited `signal`, `ready`, `exited`, `stdin`, `stderr`, `stderrLog`,
+ *   `abort()`, and `[Symbol.asyncDispose]`.
+ * - Narrow the inherited public `stdout` to `never`, because the assembler owns the stream and a concurrent external reader
+ *   would race.
+ * - Build their FFmpeg arg vector via the pure helper `buildFMp4CommandLine`, which takes fully-resolved options plus
+ *   mode-specific hook values and returns the vector. Neither subclass calls `super()` until the arg vector is finalized,
+ *   so the constructor-before-super contract is respected.
+ *
+ * The command-line hook values that differ per mode:
+ *
+ * | Hook                     | Recording                                  | Livestream                              |
+ * |--------------------------|--------------------------------------------|-----------------------------------------|
+ * | `inputArgs`              | `-i pipe:0` + probesize + `-ss`            | `-i <url>` + `-rtsp_transport tcp`      |
+ * | `separateAudioInputArgs` | `[]`                                       | Separate audio URL when configured      |
+ * | `audioInputIndex`        | `0`                                        | `0` or `1` (if separate audio)          |
+ * | `audioTarget`            | `recordingConfig.audioCodec` (transcoding) | `init.audio` when provided              |
+ * | `videoEncoderArgs`       | `options.recordEncoder(...)`               | `-codec:v copy`                         |
+ * | `postFilterArgs`         | `[]`                                       | `-frag_duration <segmentLength * 1000>` |
+ * | `metadataLabel`          | `"HKSV Event"`                             | `"Livestream Buffer"`                   |
+ *
+ * The shared pipeline primitive ({@link Mp4SegmentAssembler}) also means this module avoids template-method coupling between
+ * the base and the concrete subclasses: no abstract hook methods, no mode-specific state on the base. The base is pure lifecycle
+ * composition; the subclasses are pure args builders plus (for recording) a known-error message substitution.
+ *
+ * @module
+ */
+import { AudioRecordingCodecType, AudioRecordingSamplerate } from "./hap-enums.js";
 import { HKSV_IDR_INTERVAL, HKSV_TIMEOUT } from "./settings.js";
-import { runWithTimeout } from "../util.js";
-import { BOX_HEADER_SIZE } from "./fmp4.js";
+import { isHbpuAbortReason, onAbort } from "../util.js";
 import { FfmpegProcess } from "./process.js";
-import { once } from "node:events";
-// Utility to map HKSV audio recording codec types to their AAC Object Type identifiers. We also use satisfies here to ensure we account for any future changes that
-// would require updating this mapping.
+import { Mp4SegmentAssembler } from "./mp4-assembler.js";
+// Translation tables for the hap-nodejs enum values that shape the FFmpeg audio encoder args. `as const satisfies` pins the map shape to exhaustively cover every enum
+// member at compile time - a new enum value added upstream would require updating the maps or the build breaks.
 const translateAudioRecordingCodecType = {
-    [1 /* AudioRecordingCodecType.AAC_ELD */]: "38",
-    [0 /* AudioRecordingCodecType.AAC_LC */]: "1"
+    [AudioRecordingCodecType.AAC_ELD]: "38",
+    [AudioRecordingCodecType.AAC_LC]: "1"
 };
-// Utility to map audio sample rates to strings. We also use satisfies here to ensure we account for any future changes that would require updating this mapping.
 const translateAudioSampleRate = {
-    [0 /* AudioRecordingSamplerate.KHZ_8 */]: "8",
-    [1 /* AudioRecordingSamplerate.KHZ_16 */]: "16",
-    [2 /* AudioRecordingSamplerate.KHZ_24 */]: "24",
-    [3 /* AudioRecordingSamplerate.KHZ_32 */]: "32",
-    [4 /* AudioRecordingSamplerate.KHZ_44_1 */]: "44.1",
-    [5 /* AudioRecordingSamplerate.KHZ_48 */]: "48"
+    [AudioRecordingSamplerate.KHZ_8]: "8",
+    [AudioRecordingSamplerate.KHZ_16]: "16",
+    [AudioRecordingSamplerate.KHZ_24]: "24",
+    [AudioRecordingSamplerate.KHZ_32]: "32",
+    [AudioRecordingSamplerate.KHZ_44_1]: "44.1",
+    [AudioRecordingSamplerate.KHZ_48]: "48"
 };
-// ISO BMFF box type constants encoded as 32-bit integers for comparison without string allocation in the box-parsing hot path.
-const BOX_TYPE_MDAT = 0x6D646174;
-const BOX_TYPE_MOOF = 0x6D6F6F66;
-const BOX_TYPE_MOOV = 0x6D6F6F76;
-// Reusable empty buffer sentinel for the box-parsing loop. Avoids repeated zero-byte allocations on every box reset.
-const EMPTY_BUFFER = Buffer.alloc(0);
-// Known HKSV-related errors due to occasional inconsistencies produced by the input stream and FFmpeg's own occasional quirkiness. Compiled once at module scope
-// rather than on every error event.
+// Known HKSV-related errors due to occasional inconsistencies produced by the input stream and FFmpeg's own occasional quirkiness. Compiled once at module scope rather
+// than on every teardown event.
 const FFMPEG_KNOWN_HKSV_ERROR = new RegExp([
     "(Cannot determine format of input stream 0:0 after EOF)",
     "(Could not write header \\(incorrect codec parameters \\?\\): Broken pipe)",
@@ -39,607 +70,429 @@ const FFMPEG_KNOWN_HKSV_ERROR = new RegExp([
     "(Invalid data found when processing input)",
     "(moov atom not found)"
 ].join("|"));
-/**
- * Abstract base class for fMP4 FFmpeg processes. Owns the shared command line skeleton (preamble, video mapping, movflags, audio encoding, output format) and the fMP4
- * box-parsing loop. Subclasses provide mode-specific pieces (input args, encoder selection, box handling) via protected hook methods, following the template method
- * pattern.
- *
- * @see FfmpegRecordingProcess
- * @see FfmpegLivestreamProcess
- * @see FfmpegProcess
- * @see {@link https://ffmpeg.org/ffmpeg.html | FFmpeg Documentation}
- */
-class FfmpegFMp4Process extends FfmpegProcess {
-    isLoggingErrors;
-    // The HomeKit recording configuration and resolved base options are stored as protected fields so subclass hook methods can reference them without needing their own
-    // copies of the shared state.
-    fMp4Options;
-    recordingConfig;
-    /**
-     * Constructs a new fMP4 FFmpeg process. Stores shared state and applies defaults to the base options. The command line is not assembled here...subclasses call
-     * `buildCommandLine()` after their own initialization to trigger the template method assembly.
-     *
-     * @param ffmpegOptions     - FFmpeg configuration options.
-     * @param recordingConfig   - HomeKit recording configuration for the session.
-     * @param fMp4Options       - Partial base options with defaults applied for any unset fields.
-     * @param isVerbose         - If `true`, enables more verbose logging for debugging purposes. Defaults to `false`.
-     */
-    constructor(ffmpegOptions, recordingConfig, fMp4Options = {}, isVerbose = false) {
-        // Initialize our parent.
-        super(ffmpegOptions);
-        // We want to log errors when they occur.
-        this.isLoggingErrors = true;
-        // Store the recording configuration for use by subclass hook methods.
-        this.recordingConfig = recordingConfig;
-        // Apply defaults to the base options and store them. Subclasses store their own mode-specific options separately.
-        this.fMp4Options = {
-            audioFilters: fMp4Options.audioFilters ?? [],
-            audioStream: fMp4Options.audioStream ?? 0,
-            codec: fMp4Options.codec ?? "h264",
-            enableAudio: fMp4Options.enableAudio ?? true,
-            hardwareDecoding: fMp4Options.hardwareDecoding ?? (this.options.codecSupport.ffmpegVersion.startsWith("8.") ? this.options.config.hardwareDecoding : false),
-            hardwareTranscoding: fMp4Options.hardwareTranscoding ?? this.options.config.hardwareTranscoding,
-            transcodeAudio: fMp4Options.transcodeAudio ?? true,
-            videoFilters: fMp4Options.videoFilters ?? [],
-            videoStream: fMp4Options.videoStream ?? 0
-        };
-        // Store the verbose flag for use during command line assembly. We don't build the command line here...subclasses call buildCommandLine() after initializing their
-        // own state, which avoids the virtual-call-from-constructor problem.
-        this._isVerbose = isVerbose;
+// URL prefixes whose presence in a separate-audio-input URL means we should explicitly request TCP transport, matching the behavior of the primary video input for RTSP
+// sources. Module-scope constant - shape never changes, allocated once.
+const RTSP_TRANSPORT_PATTERNS = ["rtsp://", "rtsps://"];
+// Apply defaults to a partial base options object. Hardware decoding defaults vary with FFmpeg version (only the 8.x line supports it stably); hardware transcoding
+// follows the caller's resolved config.
+function resolveBaseOptions(options, partial) {
+    return {
+        audioFilters: partial.audioFilters ?? [],
+        audioStream: partial.audioStream ?? 0,
+        codec: partial.codec ?? "h264",
+        enableAudio: partial.enableAudio ?? true,
+        hardwareDecoding: partial.hardwareDecoding ?? (options.config.codecSupport.ffmpegAtLeast(8) ? options.config.hardwareDecoding : false),
+        hardwareTranscoding: partial.hardwareTranscoding ?? options.config.hardwareTranscoding,
+        transcodeAudio: partial.transcodeAudio ?? true,
+        videoFilters: partial.videoFilters ?? [],
+        videoStream: partial.videoStream ?? 0
+    };
+}
+// Assemble the FFmpeg command line for any fMP4 subclass. The builder consumes pre-resolved hook values supplied by the caller; subclass constructors resolve their
+// hooks inline against their own init and FfmpegOptions, then invoke this function once to produce the final arg vector.
+function buildFMp4CommandLine(input) {
+    const { audioInputIndex, audioTarget, fMp4Options, inputArgs, metadataLabel, options, postFilterArgs, separateAudioInputArgs, verbose, videoEncoderArgs } = input;
+    // Configure our video parameters for our input:
+    //
+    // -hide_banner                  Suppress printing the startup banner in FFmpeg.
+    // -nostats                      Suppress printing progress reports while encoding in FFmpeg.
+    // -fflags flags                 Set the format flags to discard any corrupt packets rather than exit.
+    // -err_detect ignore_err        Ignore decoding errors and continue rather than exit.
+    // -max_delay 500000             Set an upper limit on how much time FFmpeg can take in demuxing packets, in microseconds.
+    const args = [
+        "-hide_banner",
+        "-nostats",
+        "-fflags", "+discardcorrupt",
+        "-err_detect", "ignore_err",
+        ...options.videoDecoder(fMp4Options.codec),
+        "-max_delay", "500000",
+        // Mode-specific input arguments (RTSP input for livestream, stdin pipe for recording).
+        ...inputArgs,
+        // Mode-specific separate audio input arguments (livestream with a separate audio endpoint, empty for recording).
+        ...separateAudioInputArgs,
+        // Select the video track and apply mode-specific encoder arguments.
+        "-map", "0:v:" + fMp4Options.videoStream.toString(),
+        ...videoEncoderArgs
+    ];
+    // Configure our video filters, if we have them.
+    if (fMp4Options.videoFilters.length) {
+        args.push("-filter:v", fMp4Options.videoFilters.join(", "));
     }
-    // Per-instance verbose flag, distinct from the inherited isVerbose which reflects the global codecSupport.verbose setting. We keep both so either a global debug
-    // setting or a per-session opt-in can enable verbose FFmpeg logging...the check in buildCommandLine() ORs them together.
-    _isVerbose;
-    // Assembles the FFmpeg command line by calling hook methods in the standard order. The shared skeleton lives here; mode-specific pieces come from subclass overrides.
-    // Subclasses call this as the last step of their constructor, after their own state is fully initialized.
-    buildCommandLine() {
-        // Configure our video parameters for our input:
-        //
-        // -hide_banner                  Suppress printing the startup banner in FFmpeg.
-        // -nostats                      Suppress printing progress reports while encoding in FFmpeg.
-        // -fflags flags                 Set the format flags to discard any corrupt packets rather than exit.
-        // -err_detect ignore_err        Ignore decoding errors and continue rather than exit.
-        // -max_delay 500000             Set an upper limit on how much time FFmpeg can take in demuxing packets, in microseconds.
-        this.commandLineArgs = [
-            "-hide_banner",
-            "-nostats",
-            "-fflags", "+discardcorrupt",
-            "-err_detect", "ignore_err",
-            ...this.options.videoDecoder(this.fMp4Options.codec),
-            "-max_delay", "500000",
-            // Mode-specific input arguments (RTSP input for livestream, stdin pipe for recording).
-            ...this.inputArgs(),
-            // Mode-specific separate audio input arguments (livestream with a separate audio endpoint, empty for recording).
-            ...this.separateAudioInputArgs()
-        ];
-        // Configure our recording options for the video stream:
+    // Mode-specific post-filter arguments (frag_duration for livestream, empty for recording).
+    args.push(...postFilterArgs);
+    // -movflags flags               In the generated fMP4 stream: set the default-base-is-moof flag in the header, write an initial empty MOOV box, start a new fragment
+    //                               at each keyframe, skip creating a segment index (SIDX) box in fragments, and skip writing the final MOOV trailer since it is unneeded.
+    // -flush_packets 1              Ensure we flush our write buffer after each muxed packet.
+    // -reset_timestamps             Reset timestamps at the beginning of each segment.
+    // -metadata                     Set the metadata to the name of the camera to distinguish between FFmpeg sessions.
+    args.push("-movflags", "default_base_moof+empty_moov+frag_keyframe+skip_sidx+skip_trailer", "-flush_packets", "1", "-reset_timestamps", "1", "-metadata", "comment=" + options.name() + " " + metadataLabel);
+    // Assemble the audio encoding block. This is shared between both modes - the only mode-specific piece is which FFmpeg input index carries the audio stream.
+    if (fMp4Options.enableAudio) {
+        // Configure the audio portion of the command line:
         //
-        // -map 0:v:X                    Selects the video track from the input.
-        this.commandLineArgs.push("-map", "0:v:" + this.fMp4Options.videoStream.toString(), 
-        // Mode-specific video encoder arguments (copy for livestream, recordEncoder for recording).
-        ...this.videoEncoderArgs());
-        // Configure our video filters, if we have them.
-        if (this.fMp4Options.videoFilters.length) {
-            this.commandLineArgs.push("-filter:v", this.fMp4Options.videoFilters.join(", "));
-        }
-        // Mode-specific post-filter arguments (frag_duration for livestream, empty for recording).
-        this.commandLineArgs.push(...this.postFilterArgs());
-        // -movflags flags               In the generated fMP4 stream: set the default-base-is-moof flag in the header, write an initial empty MOOV box, start a new fragment
-        //                               at each keyframe, skip creating a segment index (SIDX) box in fragments, and skip writing the final MOOV trailer since it's unneeded.
-        // -flush_packets 1              Ensure we flush our write buffer after each muxed packet.
-        // -reset_timestamps             Reset timestamps at the beginning of each segment.
-        // -metadata                     Set the metadata to the name of the camera to distinguish between FFmpeg sessions.
-        this.commandLineArgs.push("-movflags", "default_base_moof+empty_moov+frag_keyframe+skip_sidx+skip_trailer", "-flush_packets", "1", "-reset_timestamps", "1", "-metadata", "comment=" + this.options.name() + " " + this.metadataLabel());
-        // Assemble the audio encoding block. This is shared between both modes...the only mode-specific piece is which FFmpeg input index carries the audio stream.
-        let transcodeAudio = this.fMp4Options.transcodeAudio;
-        if (this.fMp4Options.enableAudio) {
-            // Configure the audio portion of the command line. Options we use are:
-            //
-            // -map N:a:X?                 Selects the audio stream from input N, if it exists. The input index is 0 when audio and video share the same input, or 1 when a
-            //                             separate audio input has been configured.
-            this.commandLineArgs.push("-map", this.audioInputIndex().toString() + ":a:" + this.fMp4Options.audioStream.toString() + "?");
-            // Configure our audio filters, if we have them.
-            if (this.fMp4Options.audioFilters.length) {
-                this.commandLineArgs.push("-filter:a", this.fMp4Options.audioFilters.join(", "));
-                // Audio filters require transcoding. If the user has decided to filter, we enforce this requirement even if they wanted to copy the audio stream.
-                transcodeAudio = true;
-            }
-            if (transcodeAudio) {
-                // Configure the audio portion of the command line. Options we use are:
-                //
-                // -codec:a                    Encode using the codecs available to us on given platforms.
-                // -profile:a                  Specify either low-complexity AAC or enhanced low-delay AAC for HKSV events.
-                // -ar samplerate              Sample rate to use for this audio. This is specified by HKSV.
-                // -ac number                  Set the number of audio channels.
-                this.commandLineArgs.push(...this.options.audioEncoder({ codec: this.recordingConfig.audioCodec.type }), "-profile:a", translateAudioRecordingCodecType[this.recordingConfig.audioCodec.type], "-ar", translateAudioSampleRate[this.recordingConfig.audioCodec.samplerate] + "k", "-ac", (this.recordingConfig.audioCodec.audioChannels ?? 1).toString());
-            }
-            else {
-                // Configure the audio portion of the command line. Options we use are:
-                //
-                // -codec:a copy               Copy the audio stream, since it's already in AAC.
-                this.commandLineArgs.push("-codec:a", "copy");
+        // -map N:a:X?                 Selects the audio stream from input N, if it exists. The input index is 0 when audio and video share the same input, or 1 when a
+        //                             separate audio input has been configured.
+        args.push("-map", audioInputIndex.toString() + ":a:" + fMp4Options.audioStream.toString() + "?");
+        // A resolved audio target is the single signal to transcode: its presence means we encode to it, its absence means we copy the already-encoded audio through
+        // untouched. The target carries its own filters, so filtering-without-transcoding is unrepresentable here by construction rather than enforced by a runtime override.
+        if (audioTarget) {
+            // Audio filters ride inside the transcode request. When the target supplies them, we apply them ahead of the encoder.
+            if (audioTarget.filters?.length) {
+                args.push("-filter:a", audioTarget.filters.join(", "));
             }
+            // Configure the audio portion of the command line:
+            //
+            // -codec:a                    Encode using the codecs available to us on given platforms.
+            // -profile:a                  Specify either low-complexity AAC or enhanced low-delay AAC per the resolved audio target's codec.
+            // -ar samplerate              Sample rate to use for this audio, per the resolved audio target.
+            // -ac number                  Set the number of audio channels.
+            args.push(...options.audioEncoder({ codec: audioTarget.codec }), "-profile:a", translateAudioRecordingCodecType[audioTarget.codec], "-ar", translateAudioSampleRate[audioTarget.samplerate] + "k", "-ac", (audioTarget.channels ?? 1).toString());
         }
-        // Configure our video parameters for outputting our final stream:
-        //
-        // -f mp4                        Tell ffmpeg that it should create an MP4-encoded output stream.
-        // pipe:1                        Output the stream to standard output.
-        this.commandLineArgs.push("-f", "mp4", "pipe:1");
-        // Additional logging, but only if we're debugging.
-        if (this._isVerbose || this.isVerbose) {
-            this.commandLineArgs.unshift("-loglevel", "level+verbose");
+        else {
+            // -codec:a copy               Copy the audio stream through untouched when no transcode target is supplied.
+            args.push("-codec:a", "copy");
         }
     }
-    /**
-     * Prepares and configures the FFmpeg process for reading and parsing output fMP4 data. The box parsing loop is shared...each complete box is dispatched to the
-     * subclass via handleParsedBox().
-     */
-    configureProcess() {
-        let dataListener;
-        // Call our parent to get started.
-        super.configureProcess();
-        // Initialize our variables that we need to process incoming FFmpeg packets.
-        let header = EMPTY_BUFFER;
-        let bufferRemaining = EMPTY_BUFFER;
-        let dataLength = 0;
-        let type = 0;
-        // Process FFmpeg output and parse out the fMP4 stream it's generating. Here, we take on the task of parsing the fMP4 stream that's being generated and split it up
-        // into the MP4 boxes that HAP-NodeJS is ultimately expecting.
-        this.process?.stdout.on("data", dataListener = (buffer) => {
-            // If we have anything left from the last buffer we processed, prepend it to this buffer.
-            if (bufferRemaining.length > 0) {
-                buffer = Buffer.concat([bufferRemaining, buffer]);
-                bufferRemaining = EMPTY_BUFFER;
-            }
-            let offset = 0;
-            // The MP4 container format is well-documented and designed around the concept of boxes. A box (or atom as they used to be called) is at the center of an MP4
-            // container. It's composed of an 8-byte header, followed by the data payload it carries.
-            for (;;) {
-                let data;
-                // No existing header, let's start a new box.
-                if (!header.length) {
-                    // If there aren't enough bytes for a complete box header, save them for the next chunk.
-                    if (buffer.length < BOX_HEADER_SIZE) {
-                        bufferRemaining = buffer;
-                        break;
-                    }
-                    // Grab the header. The first four bytes represents the length of the entire box. Second four bytes represent the box type.
-                    header = buffer.subarray(0, BOX_HEADER_SIZE);
-                    // Now we retrieve the length of the box.
-                    dataLength = header.readUInt32BE(0);
-                    // Read the box type as a 32-bit integer to avoid per-box string allocation. Box types are 4-byte ASCII codes ("moof", "mdat", etc.) - a legacy of Apple's
-                    // original QuickTime "atoms" from 1991, carried forward when MPEG-4 Part 12 standardized the container as ISO BMFF and renamed atoms to "boxes."
-                    type = header.readUInt32BE(4);
-                    // Finally, we get the data portion of the box.
-                    data = buffer.subarray(BOX_HEADER_SIZE, dataLength);
-                    // Mark our data offset so we account for the length of the data header and subtract it from the overall length to capture just the data portion.
-                    dataLength -= offset = BOX_HEADER_SIZE;
-                }
-                else {
-                    // Grab the data from our buffer.
-                    data = buffer.subarray(0, dataLength);
-                    offset = 0;
-                }
-                // If we don't have enough data in this buffer, save what we have for the next buffer we see and append it there.
-                if (data.length < dataLength) {
-                    bufferRemaining = data;
-                    break;
-                }
-                // Dispatch the complete box to the subclass for mode-specific handling.
-                this.handleParsedBox(header, data, dataLength, type);
-                // Prepare to start a new box for the next buffer that we will be processing.
-                header = EMPTY_BUFFER;
-                type = 0;
-                // We've parsed an entire box, and there's no more data in this buffer to parse.
-                if (buffer.length === (offset + dataLength)) {
-                    dataLength = 0;
-                    break;
-                }
-                // If there's anything left in the buffer, move us to the new box and let's keep iterating.
-                buffer = buffer.subarray(offset + dataLength);
-                dataLength = 0;
-            }
-        });
-        // Make sure we cleanup our listeners when we're done.
-        this.process?.once("exit", () => {
-            this.process?.stdout.off("data", dataListener);
-        });
+    // Configure our video parameters for outputting our final stream:
+    //
+    // -f mp4                        Tell ffmpeg that it should create an MP4-encoded output stream.
+    // pipe:1                        Output the stream to standard output.
+    args.push("-f", "mp4", "pipe:1");
+    // Additional logging, but only if we're debugging.
+    if (verbose || options.config.codecSupport.verbose) {
+        args.unshift("-loglevel", "level+verbose");
     }
-    /**
-     * Stops the FFmpeg process and performs cleanup. Subclasses override this to emit mode-specific events before calling super, which handles the shared teardown and
-     * emits the "close" event.
-     */
-    stopProcess() {
-        // Call our parent to get started.
-        super.stopProcess();
-        // Signal that the process has ended.
-        this._isEnded = true;
-        this.emit("close");
+    return args;
+}
+// Build the separate-audio-input arg segment for livestream sessions and report whether a separate input was actually configured. Returns both results together as a
+// named pair because the input index in the subsequent audio mapping step depends on whether a separate input exists - the two results must stay consistent.
+function buildLivestreamAudioInputArgs(livestream, enableAudio) {
+    if (!enableAudio || !livestream.audioInput) {
+        return { args: [], hasSeparateInput: false };
     }
-    /**
-     * Stops the FFmpeg process and logs errors if specified.
-     *
-     * @param logErrors - If `true`, logs FFmpeg errors. Defaults to the internal process logging state.
-     *
-     * @example
-     *
-     * ```ts
-     * process.stop();
-     * ```
-     */
-    stop(logErrors = this.isLoggingErrors) {
-        const savedLogErrors = this.isLoggingErrors;
-        // Flag whether we should log abnormal exits (e.g. being killed) or not.
-        this.isLoggingErrors = logErrors;
-        // Call our parent to finish the job.
-        super.stop();
-        // Restore our previous logging state.
-        this.isLoggingErrors = savedLogErrors;
+    const args = [];
+    // Normalize the audio input configuration. A plain string is treated as a URL shorthand.
+    const audioInput = (typeof livestream.audioInput === "string") ? { url: livestream.audioInput } : livestream.audioInput;
+    // When a raw audio format is specified, we need to explicitly tell FFmpeg how to interpret the incoming stream since it cannot probe raw audio sources.
+    //
+    // -f format                       Specify the raw audio format (e.g., mulaw, alaw, s16le).
+    // -ar sampleRate                  Specify the audio sample rate in Hz.
+    // -ac channels                    Specify the number of audio channels.
+    if (audioInput.format) {
+        args.push("-f", audioInput.format, "-ar", (audioInput.sampleRate ?? 8000).toString(), "-ac", (audioInput.channels ?? 1).toString());
     }
-    /**
-     * Logs errors from FFmpeg process execution, handling known benign HKSV stream errors gracefully.
-     *
-     * @param exitCode - The exit code from the FFmpeg process.
-     * @param signal   - The signal (if any) used to terminate the process.
-     */
-    logFfmpegError(exitCode, signal) {
-        // If we're ignoring errors, we're done.
-        if (!this.isLoggingErrors) {
+    // For RTSP and RTSPS audio sources, we explicitly request TCP transport to match the behavior we use for the primary video input.
+    if (RTSP_TRANSPORT_PATTERNS.some((protocol) => audioInput.url.toLowerCase().startsWith(protocol))) {
+        args.push("-rtsp_transport", "tcp");
+    }
+    // -i url                          Audio input URL.
+    args.push("-i", audioInput.url);
+    return { args, hasSeparateInput: true };
+}
+// Compose the command line for a recording session. Extracted so the subclass constructor can compute its full arg vector ahead of the super() call.
+function buildRecordingCommandLine(options, init) {
+    const recording = init.recording ?? {};
+    const fMp4Options = resolveBaseOptions(options, recording);
+    const { recordingConfig } = init;
+    const fps = recording.fps ?? 30;
+    // Recording transcodes audio to the HKSV-selected codec whenever transcoding is requested or an audio filter forces it; otherwise the already-encoded audio is copied
+    // through untouched. The filters ride inside the target, so the filters-require-transcoding rule is expressed by the target's presence rather than a runtime override.
+    const audioTarget = (fMp4Options.transcodeAudio || (fMp4Options.audioFilters.length > 0)) ? {
+        channels: recordingConfig.audioCodec.audioChannels,
+        codec: recordingConfig.audioCodec.type,
+        filters: fMp4Options.audioFilters,
+        // homebridge types `audioCodec.samplerate` more loosely than our local enum, but HKSV only ever supplies a valid `AudioRecordingSamplerate` member, so the `as`
+        // narrows a known-good value into the exhaustive translation table.
+        samplerate: recordingConfig.audioCodec.samplerate
+    } : undefined;
+    // The default mirrors FFmpeg's own default probesize and is sufficient to discover the fMP4 stream's parameters before decoding begins.
+    const probesize = recording.probesize ?? 5_000_000;
+    const timeshift = recording.timeshift ?? 0;
+    // Recording input: read fMP4 data from standard input with low-delay optimizations and an optional timeshift for HKSV event alignment.
+    //
+    // -flags low_delay              Tell FFmpeg to optimize for low delay / realtime decoding.
+    // -probesize number             How many bytes should be analyzed for stream information.
+    // -f mp4                        Tell FFmpeg that it should expect an MP4-encoded input stream.
+    // -i pipe:0                     Use standard input to get video data.
+    // -ss                           Fast-forward to where HKSV is expecting us to be for a recording event.
+    const inputArgs = [
+        "-flags", "low_delay",
+        "-probesize", probesize.toString(),
+        "-f", "mp4",
+        "-i", "pipe:0",
+        "-ss", timeshift.toString() + "ms"
+    ];
+    // Recordings transcode video using the platform-appropriate encoder for HKSV.
+    const videoEncoderArgs = options.recordEncoder({
+        bitrate: recordingConfig.videoCodec.parameters.bitRate,
+        fps: recordingConfig.videoCodec.resolution[2],
+        hardwareDecoding: fMp4Options.hardwareDecoding,
+        hardwareTranscoding: fMp4Options.hardwareTranscoding,
+        height: recordingConfig.videoCodec.resolution[1],
+        idrInterval: HKSV_IDR_INTERVAL,
+        inputFps: fps,
+        level: recordingConfig.videoCodec.parameters.level,
+        profile: recordingConfig.videoCodec.parameters.profile,
+        width: recordingConfig.videoCodec.resolution[0]
+    });
+    return buildFMp4CommandLine({
+        audioInputIndex: 0,
+        audioTarget,
+        fMp4Options,
+        inputArgs,
+        metadataLabel: "HKSV Event",
+        options,
+        postFilterArgs: [],
+        separateAudioInputArgs: [],
+        verbose: init.verbose ?? false,
+        videoEncoderArgs
+    });
+}
+// Compose the command line for a livestream session. Extracted so the subclass constructor can compute its full arg vector ahead of the super() call.
+function buildLivestreamCommandLine(options, init) {
+    const fMp4Options = resolveBaseOptions(options, init.livestream);
+    const { audio, livestream } = init;
+    // Livestream input: connect to an RTSP source with direct I/O and TCP transport.
+    //
+    // -avioflags direct           Tell FFmpeg to minimize buffering to reduce latency for more realtime processing.
+    // -rtsp_transport tcp         Tell the RTSP stream handler that we're looking for a TCP connection.
+    // -i url                      RTSPS URL to get our input stream from.
+    const inputArgs = [
+        "-avioflags", "direct",
+        "-rtsp_transport", "tcp",
+        "-i", livestream.url
+    ];
+    // If a separate audio input has been configured, build the FFmpeg input arguments for it. The returned `hasSeparateInput` flag drives the subsequent audio-mapping
+    // step so the primary/secondary input index selection stays consistent with the configured inputs.
+    const separateAudio = buildLivestreamAudioInputArgs(livestream, fMp4Options.enableAudio);
+    // Livestreams remux the video stream directly without transcoding.
+    const videoEncoderArgs = ["-codec:v", "copy"];
+    // Livestreams emit fMP4 fragments at the configured cadence. `segmentLength` is expressed in milliseconds; FFmpeg wants microseconds. Default to one second when the
+    // caller does not specify an override, since one-second fragments match HomeKit's expected fMP4 fragment cadence for livestreaming consumers.
+    const segmentLengthMs = init.segmentLength ?? 1000;
+    const postFilterArgs = ["-frag_duration", (segmentLengthMs * 1000).toString()];
+    return buildFMp4CommandLine({
+        audioInputIndex: separateAudio.hasSeparateInput ? 1 : 0,
+        audioTarget: audio,
+        fMp4Options,
+        inputArgs,
+        metadataLabel: "Livestream Buffer",
+        options,
+        postFilterArgs,
+        separateAudioInputArgs: separateAudio.args,
+        verbose: init.verbose ?? false,
+        videoEncoderArgs
+    });
+}
+// Propagate assembler aborts up to the process when the assembler ends its life for a reason the process's own exit handler cannot recover. The assembler dispatches
+// on a two-way branch: the named reason `"closed"` (source ended naturally) defers to the process's own exit path, while every other reason - `"timeout"`
+// (inter-segment watchdog), `"failed"` (source stream error), or any reason supplied to an external `abort()` call - propagates so the FFmpeg child is actively torn
+// down via the process's kill path. `"closed"` must NOT propagate because the child's own `"exit"` event follows shortly and the base class computes the correct
+// reason from the actual exit code - propagating `"closed"` here would race with and pre-empt that, converting a nonzero-exit `"failed"` into a `"closed"` and losing
+// the error signal. `onAbort` provides one-shot semantics AND covers the pre-aborted-signal edge case where a parent-aborted assembler would otherwise miss the bridge
+// entirely.
+function bridgeAssemblerToProcess(process, assembler) {
+    onAbort(assembler.signal, () => {
+        if (process.aborted) {
             return;
         }
-        // See if we know about this error.
-        if (this.stderrLog.some(x => FFMPEG_KNOWN_HKSV_ERROR.test(x))) {
-            this.log.error("FFmpeg ended unexpectedly due to issues processing the media stream. This error can be safely ignored - it will occur occasionally.");
+        const reason = assembler.signal.reason;
+        // Natural source-end defers to the process's own exit path.
+        if (isHbpuAbortReason(reason, "closed")) {
             return;
         }
-        // Otherwise, revert to our default logging in our parent.
-        super.logFfmpegError(exitCode, signal);
-    }
+        process.abort(reason);
+    });
 }
 /**
- * Manages a HomeKit Secure Video recording FFmpeg process.
+ * Abstract base for FFmpeg processes that produce fragmented MP4 segments on their stdout. Owns the composition wiring between the process's stdout and an internal
+ * {@link Mp4SegmentAssembler}, plus the bridge that propagates assembler teardown to the process when the assembler aborts for reasons the process's own exit handler
+ * cannot discover on its own (watchdog timeout, source stream error).
  *
- * @example
+ * This base deliberately contains **no pipeline logic** and **no command-line assembly**. The byte-to-segment pipeline lives in {@link Mp4SegmentAssembler}, and each
+ * concrete subclass builds its own FFmpeg arg vector. The base exists solely to consolidate the composition shape - internal assembler field, the delegating public
+ * methods, and the bridge registration - that would otherwise duplicate across every fMP4 subclass. The constructor takes only `segmentTimeout` as a mode-specific knob
+ * and holds no mode-specific state, so the base avoids template-method coupling with its subclasses.
  *
- * ```ts
- * const process = new FfmpegRecordingProcess(ffmpegOptions, recordingConfig, 30, true, 5000000, 0);
- * process.start();
- * ```
+ * Subclasses must call `super(options, init, segmentTimeout?)` from their constructor, having already folded their subclass-specific init into a base-compatible
+ * {@link FfmpegProcessInit} (typically by spreading their own init and setting `args` to their built command line).
  *
- * @see FfmpegFMp4Process
+ * @see Mp4SegmentAssembler
+ * @see FfmpegProcess
  *
  * @category FFmpeg
  */
-export class FfmpegRecordingProcess extends FfmpegFMp4Process {
-    /**
-     * Indicates whether the recording has timed out waiting for FFmpeg output.
-     */
-    isTimedOut;
-    fps;
-    probesize;
-    recordingBuffer;
-    timeshift;
+export class FfmpegFMp4Process extends FfmpegProcess {
+    #assembler;
     /**
-     * Constructs a new FFmpeg recording process for HKSV events.
+     * Construct and spawn a new fMP4 segment-producing process.
      *
-     * @param options          - FFmpeg configuration options.
-     * @param recordingConfig  - HomeKit recording configuration for the session.
-     * @param fMp4Options      - fMP4 recording options.
-     * @param isVerbose        - If `true`, enables more verbose logging for debugging purposes. Defaults to `false`.
+     * @param options         - Shared {@link FfmpegOptions} configuration (codec support, logger, debug flag, name).
+     * @param init            - Base-class init (FfmpegProcessInit) plus the finalized `args` built by the subclass.
+     * @param segmentTimeout  - Optional inter-segment watchdog in milliseconds. When set, the assembler aborts with
+     *                          `HbpuAbortError("timeout")` if no media segment arrives within the window, and the bridge
+     *                          propagates the timeout up to the process. Omit for subclasses that tolerate quiet periods
+     *                          (e.g., livestreams).
      */
-    constructor(options, recordingConfig, fMp4Options = {}, isVerbose = false) {
-        super(options, recordingConfig, fMp4Options, isVerbose);
-        // Store recording-specific options.
-        this.fps = fMp4Options.fps ?? 30;
-        this.isTimedOut = false;
-        this.probesize = fMp4Options.probesize ?? 5000000;
-        this.recordingBuffer = [];
-        this.timeshift = fMp4Options.timeshift ?? 0;
-        // Assemble the FFmpeg command line now that all state is initialized.
-        this.buildCommandLine();
-    }
-    // Recording input: read fMP4 data from standard input with low-delay optimizations and an optional timeshift for HKSV event alignment.
-    //
-    // -flags low_delay              Tell FFmpeg to optimize for low delay / realtime decoding.
-    // -probesize number             How many bytes should be analyzed for stream information.
-    // -f mp4                        Tell FFmpeg that it should expect an MP4-encoded input stream.
-    // -i pipe:0                     Use standard input to get video data.
-    // -ss                           Fast forward to where HKSV is expecting us to be for a recording event.
-    inputArgs() {
-        return [
-            "-flags", "low_delay",
-            "-probesize", this.probesize.toString(),
-            "-f", "mp4",
-            "-i", "pipe:0",
-            "-ss", this.timeshift.toString() + "ms"
-        ];
-    }
-    // Recordings always read audio from the primary input...no separate audio source.
-    separateAudioInputArgs() {
-        return [];
-    }
-    // Audio is always on the primary input (index 0) for recordings.
-    audioInputIndex() {
-        return 0;
-    }
-    // Recordings transcode video using the platform-appropriate encoder for HKSV.
-    videoEncoderArgs() {
-        return this.options.recordEncoder({
-            bitrate: this.recordingConfig.videoCodec.parameters.bitRate,
-            fps: this.recordingConfig.videoCodec.resolution[2],
-            hardwareDecoding: this.fMp4Options.hardwareDecoding,
-            hardwareTranscoding: this.fMp4Options.hardwareTranscoding,
-            height: this.recordingConfig.videoCodec.resolution[1],
-            idrInterval: HKSV_IDR_INTERVAL,
-            inputFps: this.fps,
-            level: this.recordingConfig.videoCodec.parameters.level,
-            profile: this.recordingConfig.videoCodec.parameters.profile,
-            width: this.recordingConfig.videoCodec.resolution[0]
-        });
-    }
-    // Recordings have no post-filter arguments.
-    postFilterArgs() {
-        return [];
-    }
-    // Metadata label identifying this as an HKSV event recording.
-    metadataLabel() {
-        return "HKSV Event";
-    }
-    // Each parsed box is queued in the recording buffer for consumption by segmentGenerator().
-    handleParsedBox(header, data, dataLength, type) {
-        this.recordingBuffer.push({ data, header, length: dataLength, type });
-        this.emit("mp4box");
+    constructor(options, init, segmentTimeout) {
+        super(options, init);
+        this.#assembler = new Mp4SegmentAssembler(this._stdout, { segmentTimeout, signal: this.signal });
+        bridgeAssemblerToProcess(this, this.#assembler);
     }
     /**
-     * Stops the FFmpeg process and performs cleanup, ensuring the segment generator can exit.
+     * Resolve with the fMP4 initialization segment (typically `ftyp` + `moov`) once it appears on stdout. Rejects with `this.signal.reason` if the process aborts before
+     * the initialization segment completes.
+     *
+     * @returns A promise resolving to the initialization segment bytes.
      */
-    stopProcess() {
-        // Emit mp4box to unblock segmentGenerator() if it's waiting, then let the base class handle the rest.
-        this._isEnded = true;
-        this.emit("mp4box");
-        super.stopProcess();
+    async getInitSegment() {
+        return this.#assembler.initSegment;
     }
     /**
-     * Asynchronously generates complete segments from FFmpeg output, formatted for HomeKit Secure Video.
+     * Async generator yielding each completed media segment (concatenated `moof` + `mdat` pair) as a single Buffer. Terminates cleanly when the process or the caller's
+     * signal aborts, or when the underlying stdout ends.
      *
-     * This async generator yields fMP4 segments as Buffers, or ends on process termination or timeout.
+     * @param init - Optional init options. `signal` composes with the process's own signal; aborting it terminates only this generator call, not the process.
      *
-     * @yields A Buffer containing a complete MP4 segment suitable for HomeKit.
+     * @returns An async generator yielding media segment buffers in stream order.
+     */
+    segments(init = {}) {
+        return this.#assembler.segments(init);
+    }
+    /**
+     * The number of assembled media segments buffered in the internal assembler but not yet pulled through {@link FfmpegFMp4Process.segments} - the consumer's catch-up
+     * reserve when the FFmpeg source stalls. Delegates to {@link Mp4SegmentAssembler.bufferedSegments}.
      *
-     * @example
+     * @returns The buffered-segment depth.
+     */
+    get bufferedSegments() {
+        return this.#assembler.bufferedSegments;
+    }
+    /**
+     * Async generator yielding the whole segment stream as a kind-tagged sequence: one {@link Mp4Segment} of kind `"init"` carrying the initialization bytes, then one of
+     * kind `"media"` per completed media fragment. Delegates to {@link Mp4SegmentAssembler.stream}; it is a third view over the same pipeline as
+     * {@link FfmpegFMp4Process.getInitSegment} / {@link FfmpegFMp4Process.segments} and shares their single-consumer contract - use one view or the other, never both.
      *
-     * ```ts
-     * for await(const segment of process.segmentGenerator()) {
+     * @param init - Optional init options. `signal` composes with the process's own signal; aborting it terminates only this generator call, not the process.
      *
-     *   // Process each segment for HomeKit.
-     * }
-     * ```
+     * @returns An async generator yielding one `"init"` segment followed by `"media"` segments in stream order.
      */
-    async *segmentGenerator() {
-        let segment = [];
-        // Loop forever, generating either FTYP/MOOV box pairs or MOOF/MDAT box pairs for HomeKit Secure Video.
-        for (;;) {
-            // FFmpeg has finished its output - we're done.
-            if (this._isEnded) {
-                return;
-            }
-            // If the buffer is empty, wait for our FFmpeg process to produce more boxes.
-            if (!this.recordingBuffer.length) {
-                // Segments are output by FFmpeg according to our specified IDR interval. If we don't see a segment within the timeframe we need for HKSV's timing requirements,
-                // we flag it accordingly and return null back to the generator that's calling us.
-                // eslint-disable-next-line no-await-in-loop
-                await runWithTimeout(once(this, "mp4box"), HKSV_TIMEOUT);
-            }
-            // Grab the next fMP4 box from our buffer.
-            const box = this.recordingBuffer.shift();
-            // FFmpeg hasn't produced any output. Given the time-sensitive nature of HKSV that constrains us to no more than 5 seconds to provide the next segment, we're done.
-            if (!box) {
-                this.isTimedOut = true;
-                return;
-            }
-            // Queue up this fMP4 box to send back to HomeKit.
-            segment.push(box.header, box.data);
-            // What we want to send are two types of complete segments, made up of multiple MP4 boxes:
-            //
-            // - a complete MOOV box, usually with an accompanying FTYP box, that's sent at the very beginning of any valid fMP4 stream. HomeKit Secure Video looks for this
-            //   before anything else.
-            //
-            // - a complete MOOF/MDAT pair. MOOF describes the sample locations and their sizes and MDAT contains the actual audio and video data related to that segment. Think
-            //   of MOOF as the audio/video data "header", and MDAT as the "payload".
-            //
-            // Once we see these, we combine all the segments in our queue to send back to HomeKit.
-            if ((box.type === BOX_TYPE_MOOV) || (box.type === BOX_TYPE_MDAT)) {
-                yield Buffer.concat(segment);
-                segment = [];
-            }
-        }
+    stream(init = {}) {
+        return this.#assembler.stream(init);
     }
 }
 /**
- * Manages a HomeKit livestream FFmpeg process for generating fMP4 segments.
+ * FFmpeg process specialization for HomeKit Secure Video (HKSV) event recording. Builds its command line from the provided HKSV recording configuration and delegates
+ * segment production to {@link FfmpegFMp4Process}. Overrides `FfmpegProcess.logFailedTeardown` to substitute a friendly user-facing message when the stderr log
+ * matches one of the tolerated HKSV error patterns, suppressing the canonical ERROR dump for those known benign cases. Also overrides
+ * `FfmpegProcess.logTimeoutTeardown` to demote the benign inter-segment watchdog reap to debug - a recording ends exactly this way when its segment source quiets,
+ * so the base's WARN would be alarming.
  *
  * @example
  *
  * ```ts
- * const process = new FfmpegLivestreamProcess(ffmpegOptions, recordingConfig, url, 30, true);
- * process.start();
+ * await using proc = new FfmpegRecordingProcess(ffmpegOptions, {
+ *
+ *   recording: { fps: 30, probesize: 5_000_000, timeshift: 0 },
+ *   recordingConfig,
+ *   signal: delegate.abortController.signal
+ * });
  *
- * const initSegment = await process.getInitSegment();
+ * const init = await proc.getInitSegment();
+ *
+ * for await (const segment of proc.segments()) {
+ *
+ *   // Forward each media segment to HomeKit.
+ * }
  * ```
  *
  * @see FfmpegFMp4Process
+ * @see FfmpegProcess
  *
  * @category FFmpeg
  */
-export class FfmpegLivestreamProcess extends FfmpegFMp4Process {
-    /**
-     * Optional override for the fMP4 fragment duration, in milliseconds. When set, the `-frag_duration` argument is updated before starting the FFmpeg process.
-     */
-    segmentLength;
-    // Set to true during separateAudioInputArgs() when a separate audio input is configured, so that audioInputIndex() returns the correct FFmpeg input index.
-    _hasAudioInput;
-    _initSegment;
-    _initSegmentParts;
-    hasInitSegment;
-    livestreamOptions;
+export class FfmpegRecordingProcess extends FfmpegFMp4Process {
     /**
-     * Constructs a new FFmpeg livestream process.
+     * Construct and spawn a new HKSV recording process.
      *
-     * @param options            - FFmpeg configuration options.
-     * @param recordingConfig    - HomeKit recording configuration for the session.
-     * @param livestreamOptions  - livestream segmenting options.
-     * @param isVerbose          - If `true`, enables more verbose logging for debugging purposes. Defaults to `false`.
+     * @param options - Shared {@link FfmpegOptions} configuration (codec support, logger, debug flag, name).
+     * @param init    - Init options. See {@link FfmpegRecordingInit}.
      */
-    constructor(options, recordingConfig, livestreamOptions, isVerbose = false) {
-        super(options, recordingConfig, livestreamOptions, isVerbose);
-        // Store livestream-specific options.
-        this._hasAudioInput = false;
-        this._initSegment = Buffer.alloc(0);
-        this._initSegmentParts = [];
-        this.hasInitSegment = false;
-        this.livestreamOptions = livestreamOptions;
-        // Assemble the FFmpeg command line now that all state is initialized.
-        this.buildCommandLine();
-    }
-    // Livestream input: connect to an RTSP source with direct I/O and TCP transport.
-    //
-    // -avioflags direct           Tell FFmpeg to minimize buffering to reduce latency for more realtime processing.
-    // -rtsp_transport tcp         Tell the RTSP stream handler that we're looking for a TCP connection.
-    // -i url                      RTSPS URL to get our input stream from.
-    inputArgs() {
-        return [
-            "-avioflags", "direct",
-            "-rtsp_transport", "tcp",
-            "-i", this.livestreamOptions.url
-        ];
-    }
-    // If a separate audio input has been configured, build the FFmpeg input arguments for it. This enables support for devices like DoorBird where video and audio are
-    // served from different endpoints.
-    separateAudioInputArgs() {
-        if (!this.fMp4Options.enableAudio || !this.livestreamOptions.audioInput) {
-            return [];
-        }
-        const args = [];
-        // Normalize the audio input configuration. A plain string is treated as a URL shorthand.
-        const audioInput = (typeof this.livestreamOptions.audioInput === "string") ?
-            { url: this.livestreamOptions.audioInput } :
-            this.livestreamOptions.audioInput;
-        // When a raw audio format is specified, we need to explicitly tell FFmpeg how to interpret the incoming stream since it cannot probe raw audio sources.
-        //
-        // -f format                       Specify the raw audio format (e.g., mulaw, alaw, s16le).
-        // -ar sampleRate                  Specify the audio sample rate in Hz.
-        // -ac channels                    Specify the number of audio channels.
-        if (audioInput.format) {
-            args.push("-f", audioInput.format, "-ar", (audioInput.sampleRate ?? 8000).toString(), "-ac", (audioInput.channels ?? 1).toString());
-        }
-        // For RTSP and RTSPS audio sources, we explicitly request TCP transport to match the behavior we use for the primary video input.
-        if (["rtsp://", "rtsps://"].some((protocol) => audioInput.url.toLowerCase().startsWith(protocol))) {
-            args.push("-rtsp_transport", "tcp");
-        }
-        // -i url                          Audio input URL.
-        args.push("-i", audioInput.url);
-        // Track that we have a separate audio input so audioInputIndex() returns the correct value.
-        this._hasAudioInput = true;
-        return args;
-    }
-    // When a separate audio input is configured, audio is on the second FFmpeg input (index 1). Otherwise it shares the primary input (index 0).
-    audioInputIndex() {
-        return this._hasAudioInput ? 1 : 0;
-    }
-    // Livestreams remux the video stream directly without transcoding.
-    videoEncoderArgs() {
-        return ["-codec:v", "copy"];
-    }
-    // Livestreams emit fMP4 fragments at one-second intervals by default.
-    //
-    // -frag_duration number       Length of each fMP4 fragment, in microseconds.
-    postFilterArgs() {
-        return ["-frag_duration", "1000000"];
-    }
-    // Metadata label identifying this as a livestream buffer.
-    metadataLabel() {
-        return "Livestream Buffer";
-    }
-    // Livestream box handling: accumulate the initialization segment (everything before the first moof box), then emit each subsequent box as a segment event.
-    handleParsedBox(header, data, _dataLength, type) {
-        // If this is part of the initialization segment, store it for future use.
-        if (!this.hasInitSegment) {
-            // The initialization segment is everything before the first moof box. Once we've seen a moof box, we know we've captured it in full. We collect the parts into an
-            // array and concatenate once at the end to avoid creating intermediate buffers on every pre-moof box.
-            if (type === BOX_TYPE_MOOF) {
-                this._initSegment = Buffer.concat(this._initSegmentParts);
-                this._initSegmentParts = [];
-                this.hasInitSegment = true;
-                this.emit("initsegment");
-            }
-            else {
-                this._initSegmentParts.push(header, data);
-            }
-        }
-        if (this.hasInitSegment) {
-            // We only emit segments once we have the initialization segment.
-            this.emit("segment", Buffer.concat([header, data]));
-        }
+    constructor(options, init) {
+        super(options, { ...init, args: init.args ?? buildRecordingCommandLine(options, init) }, HKSV_TIMEOUT);
     }
-    /**
-     * Starts the FFmpeg process, adjusting the fragment duration if segmentLength has been set.
-     *
-     * @example
-     *
-     * ```ts
-     * process.start();
-     * ```
-     */
-    start() {
-        if (this.segmentLength !== undefined) {
-            const fragIndex = this.commandLineArgs.indexOf("-frag_duration");
-            if (fragIndex !== -1) {
-                this.commandLineArgs[fragIndex + 1] = (this.segmentLength * 1000).toString();
-            }
+    // Known-HKSV-error friendly message. When the abort reason is `"failed"`, inspect the accumulated stderr for any of the tolerated HKSV error patterns and substitute
+    // a single user-facing log line for the canonical ERROR dump. Non-matching failures fall through to the base's canonical ERROR dump via `super.logFailedTeardown`.
+    // Policy is driven entirely by `signal.reason` and the observed stderr, with no class state of our own.
+    logFailedTeardown(reason) {
+        if (this.stderrLog.some((line) => FFMPEG_KNOWN_HKSV_ERROR.test(line))) {
+            this.log.error("%s: FFmpeg ended unexpectedly due to issues processing the media stream. This error can be safely ignored - it will occur occasionally.", this.options.name());
+            return;
         }
-        // Start the FFmpeg session.
-        super.start();
+        super.logFailedTeardown(reason);
     }
-    /**
-     * Gets the fMP4 initialization segment generated by FFmpeg for the livestream.
-     *
-     * @returns A promise resolving to the initialization segment as a Buffer.
-     *
-     * @example
-     *
-     * ```ts
-     * const initSegment = await process.getInitSegment();
-     * ```
-     */
-    async getInitSegment() {
-        // If we have the initialization segment, return it.
-        if (this.hasInitSegment) {
-            return this._initSegment;
-        }
-        // Wait until the initialization segment is available.
-        await once(this, "initsegment");
-        return this._initSegment;
+    // FfmpegRecordingProcess is the only fMP4 process that arms an inter-segment watchdog - it alone passes HKSV_TIMEOUT to super, while the sibling
+    // FfmpegLivestreamProcess passes no segmentTimeout, so that watchdog never fires there. The watchdog firing is benign by default - it is simply how an HKSV recording
+    // ends when its segment source quiets. The watchdog is output-only (it re-arms on completed output segments and never sees stdin), so the library cannot tell a starved
+    // source (a benign wire stall) from a fed-but-stuck FFmpeg (a real local hang); it reports the reap quietly at debug and leaves the severity verdict to the consumer,
+    // which alone holds the input-feed and reachability context. The base class warns here because a stall on a general (streaming) process genuinely is a problem.
+    logTimeoutTeardown(_reason) {
+        this.log.debug("%s: the recording's inter-segment watchdog window elapsed with no new segment.", this.options.name());
     }
+}
+/**
+ * The production {@link RecordingProcessFactory}: builds the concrete FFmpeg-backed recording process. A consumer holds this typed as the abstraction; a test substitutes
+ * a fake factory. `create` is exactly the {@link FfmpegRecordingProcess} constructor call, so wiring construction through this seam is behavior-neutral.
+ *
+ * @see RecordingProcessFactory
+ *
+ * @category FFmpeg
+ */
+export const recordingProcessFactory = {
+    create: (options, init) => new FfmpegRecordingProcess(options, init)
+};
+/**
+ * FFmpeg process specialization for fMP4 livestreaming from an RTSP source. Builds its command line from the provided livestream source and delegates segment production
+ * to {@link FfmpegFMp4Process}.
+ *
+ * Used by HBUP as an alternative HKSV segment source when pulling directly from an RTSP URL (bypasses the Protect livestream API for debug and diagnostic scenarios).
+ * Matches the polymorphic `{ getInitSegment(): Promise<Buffer>; segments(): AsyncGenerator<Buffer> }` interface HBUP uses across the native Protect livestream and this
+ * class. Unlike recording, livestream does not enforce an inter-segment watchdog timeout: a live camera feed legitimately quiets down during low-motion periods and does
+ * not carry HKSV's 5-second hard timing contract. Callers that need a liveness cap can compose their own timeout via the process's `signal`.
+ *
+ * @example
+ *
+ * ```ts
+ * await using proc = new FfmpegLivestreamProcess(ffmpegOptions, {
+ *
+ *   audio: { codec: AudioRecordingCodecType.AAC_LC, samplerate: AudioRecordingSamplerate.KHZ_16 },
+ *   livestream: { url: "rtsp://camera/stream" },
+ *   segmentLength: 1000,
+ *   signal: session.controller.signal
+ * });
+ *
+ * const init = await proc.getInitSegment();
+ *
+ * for await (const segment of proc.segments()) {
+ *
+ *   // Forward each media segment to the downstream consumer.
+ * }
+ * ```
+ *
+ * @see FfmpegFMp4Process
+ * @see FfmpegProcess
+ *
+ * @category FFmpeg
+ */
+export class FfmpegLivestreamProcess extends FfmpegFMp4Process {
     /**
-     * Returns the initialization segment as a Buffer, or null if not yet available.
-     *
-     * @returns The initialization segment Buffer, or `null` if not yet generated.
-     *
-     * @example
+     * Construct and spawn a new fMP4 livestream process.
      *
-     * ```ts
-     * const init = process.initSegment;
-     * if(init) {
-     *
-     *   // Use the initialization segment.
-     * }
-     * ```
+     * @param options - Shared {@link FfmpegOptions} configuration (codec support, logger, debug flag, name).
+     * @param init    - Init options. See {@link FfmpegLivestreamInit}.
      */
-    get initSegment() {
-        if (!this.hasInitSegment) {
-            return null;
-        }
-        return this._initSegment;
+    constructor(options, init) {
+        super(options, { ...init, args: init.args ?? buildLivestreamCommandLine(options, init) });
     }
 }
 //# sourceMappingURL=record.js.map