homebridge-plugin-utils 1.33.0 → 1.35.0

package/dist/ffmpeg/record.js

@@ -4,11 +4,11 @@
  */
 import { HKSV_IDR_INTERVAL, HKSV_TIMEOUT } from "./settings.js";
 import { runWithTimeout } from "../util.js";
+import { BOX_HEADER_SIZE } from "./fmp4.js";
 import { FfmpegProcess } from "./process.js";
-import events from "node:events";
 import { once } from "node:events";
-// Utility to map HKSV audio recording profiles to FFmpeg profile strings. We also use satisfies here to ensure we account for any future changes that would require
-// updating this mapping.
+// 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.
 const translateAudioRecordingCodecType = {
     [1 /* AudioRecordingCodecType.AAC_ELD */]: "38",
     [0 /* AudioRecordingCodecType.AAC_LC */]: "1"
@@ -22,80 +22,77 @@ const translateAudioSampleRate = {
     [4 /* AudioRecordingSamplerate.KHZ_44_1 */]: "44.1",
     [5 /* 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.
+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)",
+    "(Could not write header for output file #0)",
+    "(Error closing file: Broken pipe)",
+    "(Error splitting the input into NAL units\\.)",
+    "(Invalid data found when processing input)",
+    "(moov atom not found)"
+].join("|"));
 /**
- * FFmpeg process controller for HomeKit Secure Video (HKSV) and fMP4 livestreaming and recording.
+ * 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.
  *
- * This class manages the lifecycle and parsing of an FFmpeg process to support HKSV and livestreaming in fMP4 format. It handles initialization segments, media segment
- * parsing, buffering, and HomeKit segment generation, and emits events for segment and initialization.
- *
- * @example
- *
- * ```ts
- * // Create a new recording process for an HKSV event.
- * const process = new FfmpegRecordingProcess(ffmpegOptions, recordingConfig, 30, true, 5000000, 0);
- *
- * // Start the process.
- * process.start();
- *
- * // Iterate over generated segments.
- * for await(const segment of process.segmentGenerator()) {
- *
- *   // Send segment to HomeKit, etc.
- * }
- *
- * // Stop when finished.
- * process.stop();
- * ```
- *
- * @see FfmpegOptions
+ * @see FfmpegRecordingProcess
+ * @see FfmpegLivestreamProcess
  * @see FfmpegProcess
  * @see {@link https://ffmpeg.org/ffmpeg.html | FFmpeg Documentation}
  */
 class FfmpegFMp4Process extends FfmpegProcess {
-    hasInitSegment;
-    _initSegment;
-    isLivestream;
     isLoggingErrors;
-    isTimedOut;
-    recordingBuffer;
-    segmentLength;
+    // 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 for HKSV event recording or livestreaming.
+     * 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 isAudioActive     - If `true`, enables audio stream processing.
-     * @param fMp4Options       - Configuration for the fMP4 session (fps, type, url, audio input, etc.).
+     * @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`.
-     *
-     * @example
-     *
-     * ```ts
-     * const process = new FfmpegFMp4Process(ffmpegOptions, recordingConfig, true, { fps: 30 });
-     * ```
      */
     constructor(ffmpegOptions, recordingConfig, fMp4Options = {}, isVerbose = false) {
         // Initialize our parent.
         super(ffmpegOptions);
         // We want to log errors when they occur.
         this.isLoggingErrors = true;
-        // Initialize our recording buffer.
-        this.hasInitSegment = false;
-        this._initSegment = Buffer.alloc(0);
-        this.recordingBuffer = [];
-        // Initialize our state.
-        this.isLivestream = !!fMp4Options.url;
-        this.isTimedOut = false;
-        fMp4Options.audioStream ??= 0;
-        fMp4Options.audioFilters ??= [];
-        fMp4Options.codec ??= "h264";
-        fMp4Options.enableAudio ??= true;
-        fMp4Options.fps ??= 30;
-        fMp4Options.hardwareDecoding ??= this.options.codecSupport.ffmpegVersion.startsWith("8.") ? this.options.config.hardwareDecoding : false;
-        fMp4Options.hardwareTranscoding ??= this.options.config.hardwareTranscoding;
-        fMp4Options.transcodeAudio ??= true;
-        fMp4Options.videoFilters ??= [];
-        fMp4Options.videoStream ??= 0;
+        // 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;
+    }
+    // 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.
@@ -108,100 +105,53 @@ class FfmpegFMp4Process extends FfmpegProcess {
             "-nostats",
             "-fflags", "+discardcorrupt",
             "-err_detect", "ignore_err",
-            ...this.options.videoDecoder(fMp4Options.codec),
-            "-max_delay", "500000"
+            ...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()
         ];
-        // Track which FFmpeg input index contains the audio stream. By default, audio and video share the same input (index 0). When a separate audio input is provided
-        // for livestreaming, the audio input becomes index 1.
-        let audioInputIndex = 0;
-        if (this.isLivestream && fMp4Options.url) {
-            // -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.
-            this.commandLineArgs.push("-avioflags", "direct", "-rtsp_transport", "tcp", "-i", fMp4Options.url);
-        }
-        else {
-            // -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.
-            this.commandLineArgs.push("-flags", "low_delay", "-probesize", (fMp4Options.probesize ?? 5000000).toString(), "-f", "mp4", "-i", "pipe:0", "-ss", (fMp4Options.timeshift ?? 0).toString() + "ms");
-        }
-        // If a separate audio input has been configured for livestreaming, add it as a second FFmpeg input. This enables support for devices like DoorBird where video and
-        // audio are served from different endpoints.
-        if (this.isLivestream && fMp4Options.enableAudio && fMp4Options.audioInput) {
-            // Normalize the audio input configuration. A plain string is treated as a URL shorthand.
-            const audioInput = (typeof fMp4Options.audioInput === "string") ?
-                { url: fMp4Options.audioInput } :
-                fMp4Options.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) {
-                this.commandLineArgs.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))) {
-                this.commandLineArgs.push("-rtsp_transport", "tcp");
-            }
-            // -i url                          Audio input URL.
-            this.commandLineArgs.push("-i", audioInput.url);
-            // Audio is now on the second input (index 1) instead of the primary input (index 0).
-            audioInputIndex = 1;
-        }
         // Configure our recording options for the video stream:
         //
         // -map 0:v:X                    Selects the video track from the input.
-        this.commandLineArgs.push("-map", "0:v:" + fMp4Options.videoStream.toString(), ...(this.isLivestream ? ["-codec:v", "copy"] : this.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: fMp4Options.fps,
-            level: recordingConfig.videoCodec.parameters.level,
-            profile: recordingConfig.videoCodec.parameters.profile,
-            width: recordingConfig.videoCodec.resolution[0]
-        })));
+        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 (fMp4Options.videoFilters.length) {
-            this.commandLineArgs.push("-filter:v", fMp4Options.videoFilters.join(", "));
-        }
-        // If we're livestreaming, emit fragments at one-second intervals.
-        if (this.isLivestream) {
-            // -frag_duration number       Length of each fMP4 fragment, in microseconds.
-            this.commandLineArgs.push("-frag_duration", "1000000");
+        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.isLivestream ? "Livestream Buffer" : "HKSV Event"));
-        if (fMp4Options.enableAudio) {
+        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", audioInputIndex.toString() + ":a:" + fMp4Options.audioStream.toString() + "?");
+            this.commandLineArgs.push("-map", this.audioInputIndex().toString() + ":a:" + this.fMp4Options.audioStream.toString() + "?");
             // Configure our audio filters, if we have them.
-            if (fMp4Options.audioFilters.length) {
-                this.commandLineArgs.push("-filter:a", fMp4Options.audioFilters.join(", "));
-                // Audio filters require transcoding. If the user's decided to filter, we enforce this requirement even if they wanted to copy the audio stream.
-                fMp4Options.transcodeAudio = true;
+            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 (fMp4Options.transcodeAudio) {
+            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: recordingConfig.audioCodec.type }), "-profile:a", translateAudioRecordingCodecType[recordingConfig.audioCodec.type], "-ar", translateAudioSampleRate[recordingConfig.audioCodec.samplerate] + "k", "-ac", (recordingConfig.audioCodec.audioChannels ?? 1).toString());
+                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:
@@ -216,51 +166,54 @@ class FfmpegFMp4Process extends FfmpegProcess {
         // pipe:1                        Output the stream to standard output.
         this.commandLineArgs.push("-f", "mp4", "pipe:1");
         // Additional logging, but only if we're debugging.
-        if (isVerbose || this.isVerbose) {
+        if (this._isVerbose || this.isVerbose) {
             this.commandLineArgs.unshift("-loglevel", "level+verbose");
         }
     }
     /**
-     * Prepares and configures the FFmpeg process for reading and parsing output fMP4 data.
-     *
-     * This method is called internally by the process lifecycle and is not typically invoked directly by consumers.
+     * 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 = Buffer.alloc(0);
-        let bufferRemaining = Buffer.alloc(0);
+        let header = EMPTY_BUFFER;
+        let bufferRemaining = EMPTY_BUFFER;
         let dataLength = 0;
-        let type = "";
-        // Process FFmpeg output and parse out the fMP4 stream it's generating for HomeKit Secure Video.
+        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 = Buffer.alloc(0);
+                bufferRemaining = EMPTY_BUFFER;
             }
             let offset = 0;
-            // FFmpeg is outputting an fMP4 stream that's suitable for HomeKit Secure Video. However, we can't just pass this stream directly back to HomeKit since we're using
-            // a generator-based API to send packets back to HKSV. 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.
+            // 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;
-                // 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.
                 // 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, 8);
+                    header = buffer.subarray(0, BOX_HEADER_SIZE);
                     // Now we retrieve the length of the box.
                     dataLength = header.readUInt32BE(0);
-                    // Get the type of the box. This is always a string and has a funky history to it that makes for an interesting read!
-                    type = header.subarray(4).toString();
+                    // 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(8, dataLength);
+                    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 = 8;
+                    dataLength -= offset = BOX_HEADER_SIZE;
                 }
                 else {
                     // Grab the data from our buffer.
@@ -272,33 +225,11 @@ class FfmpegFMp4Process extends FfmpegProcess {
                     bufferRemaining = data;
                     break;
                 }
-                // If we're creating a livestream to be consumed by the timeshift buffer, we need to track the initialization segment, and emit segments.
-                if (this.isLivestream) {
-                    // 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.
-                        if (type === "moof") {
-                            this.hasInitSegment = true;
-                            this.emit("initsegment");
-                        }
-                        else {
-                            this._initSegment = Buffer.concat([this._initSegment, header, data]);
-                        }
-                    }
-                    if (this.hasInitSegment) {
-                        // We only emit segments once we have the initialization segment.
-                        this.emit("segment", Buffer.concat([header, data]));
-                    }
-                }
-                else {
-                    // Add it to our queue to be eventually pushed out through our generator function.
-                    this.recordingBuffer.push({ data: data, header: header, length: dataLength, type: type });
-                    this.emit("mp4box");
-                }
+                // 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.
-                data = Buffer.alloc(0);
-                header = Buffer.alloc(0);
-                type = "";
+                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;
@@ -315,59 +246,16 @@ class FfmpegFMp4Process extends FfmpegProcess {
         });
     }
     /**
-     * Retrieves the fMP4 initialization segment generated by FFmpeg.
-     *
-     * Waits until the initialization segment is available, then returns it.
-     *
-     * @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 seen and then try again.
-        await events.once(this, "initsegment");
-        return this.getInitSegment();
-    }
-    /**
-     * Stops the FFmpeg process and performs cleanup, including emitting termination events for segment generators.
-     *
-     * This is called as part of the process shutdown sequence.
+     * 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();
-        // Ensure that we clear out of our segment generator by guaranteeing an exit path.
-        this.isEnded = true;
-        this.emit("mp4box");
+        // Signal that the process has ended.
+        this._isEnded = true;
         this.emit("close");
     }
-    /**
-     * Starts the FFmpeg process, adjusting segment length for livestreams if set.
-     *
-     * @example
-     *
-     * ```ts
-     * process.start();
-     * ```
-     */
-    start() {
-        if (this.isLivestream && (this.segmentLength !== undefined)) {
-            const fragIndex = this.commandLineArgs.indexOf("-frag_duration");
-            if (fragIndex !== -1) {
-                this.commandLineArgs[fragIndex + 1] = (this.segmentLength * 1000).toString();
-            }
-        }
-        // Start the FFmpeg session.
-        super.start();
-    }
     /**
      * Stops the FFmpeg process and logs errors if specified.
      *
@@ -399,24 +287,118 @@ class FfmpegFMp4Process extends FfmpegProcess {
         if (!this.isLoggingErrors) {
             return;
         }
-        // Known HKSV-related errors due to occasional inconsistencies that are occasionally produced by the input stream and FFmpeg's own occasional quirkiness.
-        const ffmpegKnownHksvError = new RegExp([
-            "(Cannot determine format of input stream 0:0 after EOF)",
-            "(Could not write header \\(incorrect codec parameters \\?\\): Broken pipe)",
-            "(Could not write header for output file #0)",
-            "(Error closing file: Broken pipe)",
-            "(Error splitting the input into NAL units\\.)",
-            "(Invalid data found when processing input)",
-            "(moov atom not found)"
-        ].join("|"));
         // See if we know about this error.
-        if (this.stderrLog.some(x => ffmpegKnownHksvError.test(x))) {
+        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.");
             return;
         }
         // Otherwise, revert to our default logging in our parent.
         super.logFfmpegError(exitCode, signal);
     }
+}
+/**
+ * Manages a HomeKit Secure Video recording FFmpeg process.
+ *
+ * @example
+ *
+ * ```ts
+ * const process = new FfmpegRecordingProcess(ffmpegOptions, recordingConfig, 30, true, 5000000, 0);
+ * process.start();
+ * ```
+ *
+ * @see FfmpegFMp4Process
+ *
+ * @category FFmpeg
+ */
+export class FfmpegRecordingProcess extends FfmpegFMp4Process {
+    /**
+     * Indicates whether the recording has timed out waiting for FFmpeg output.
+     */
+    isTimedOut;
+    fps;
+    probesize;
+    recordingBuffer;
+    timeshift;
+    /**
+     * Constructs a new FFmpeg recording process for HKSV events.
+     *
+     * @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`.
+     */
+    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");
+    }
+    /**
+     * Stops the FFmpeg process and performs cleanup, ensuring the segment generator can exit.
+     */
+    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();
+    }
     /**
      * Asynchronously generates complete segments from FFmpeg output, formatted for HomeKit Secure Video.
      *
@@ -437,8 +419,8 @@ class FfmpegFMp4Process extends FfmpegProcess {
         let segment = [];
         // Loop forever, generating either FTYP/MOOV box pairs or MOOF/MDAT box pairs for HomeKit Secure Video.
         for (;;) {
-            // FFmpeg has finished it's output - we're done.
-            if (this.isEnded) {
+            // 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.
@@ -466,60 +448,12 @@ class FfmpegFMp4Process extends FfmpegProcess {
             //   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 === "moov") || (box.type === "mdat")) {
+            if ((box.type === BOX_TYPE_MOOV) || (box.type === BOX_TYPE_MDAT)) {
                 yield Buffer.concat(segment);
                 segment = [];
             }
         }
     }
-    /**
-     * 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
-     *
-     * ```ts
-     * const init = process.initSegment;
-     * if(init) {
-     *
-     *   // Use the initialization segment.
-     * }
-     * ```
-     */
-    get initSegment() {
-        if (!this.hasInitSegment) {
-            return null;
-        }
-        return this._initSegment;
-    }
-}
-/**
- * Manages a HomeKit Secure Video recording FFmpeg process.
- *
- * @example
- *
- * ```ts
- * const process = new FfmpegRecordingProcess(ffmpegOptions, recordingConfig, 30, true, 5000000, 0);
- * process.start();
- * ```
- *
- * @see FfmpegFMp4Process
- *
- * @category FFmpeg
- */
-export class FfmpegRecordingProcess extends FfmpegFMp4Process {
-    /**
-     * Constructs a new FFmpeg recording process for HKSV events.
-     *
-     * @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`.
-     */
-    constructor(options, recordingConfig, fMp4Options = {}, isVerbose = false) {
-        super(options, recordingConfig, fMp4Options, isVerbose);
-    }
 }
 /**
  * Manages a HomeKit livestream FFmpeg process for generating fMP4 segments.
@@ -538,6 +472,16 @@ export class FfmpegRecordingProcess extends FfmpegFMp4Process {
  * @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;
     /**
      * Constructs a new FFmpeg livestream process.
      *
@@ -548,6 +492,113 @@ export class FfmpegLivestreamProcess extends FfmpegFMp4Process {
      */
     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]));
+        }
+    }
+    /**
+     * 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();
+            }
+        }
+        // Start the FFmpeg session.
+        super.start();
     }
     /**
      * Gets the fMP4 initialization segment generated by FFmpeg for the livestream.
@@ -561,7 +612,34 @@ export class FfmpegLivestreamProcess extends FfmpegFMp4Process {
      * ```
      */
     async getInitSegment() {
-        return super.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;
+    }
+    /**
+     * 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
+     *
+     * ```ts
+     * const init = process.initSegment;
+     * if(init) {
+     *
+     *   // Use the initialization segment.
+     * }
+     * ```
+     */
+    get initSegment() {
+        if (!this.hasInitSegment) {
+            return null;
+        }
+        return this._initSegment;
     }
 }
 //# sourceMappingURL=record.js.map