homebridge-plugin-utils 1.35.0 → 2.1.0

package/dist/ffmpeg/record.d.ts

@@ -1,36 +1,67 @@
 /**
- * FFmpeg process management for HomeKit Secure Video (HKSV) events and fMP4 livestreaming.
+ * fMP4 FFmpeg processes for HomeKit Secure Video (HKSV) events and livestreaming.
  *
- * This module defines classes for orchestrating FFmpeg processes that produce fMP4 segments suitable for HomeKit Secure Video and realtime livestreaming scenarios. It
- * handles process lifecycle, segment buffering, initialization segment detection, and streaming event generation, abstracting away the complexity of interacting directly
- * with FFmpeg for these workflows.
+ * 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.
  *
- * Key features:
+ * Both concrete subclasses:
  *
- * - Automated setup and management of FFmpeg processes for HKSV event recording and livestreaming (with support for audio and video).
- * - Parsing and generation of fMP4 boxes/segments for HomeKit, including initialization and media segments.
- * - Async generator APIs for efficient, event-driven segment handling.
- * - Flexible error handling and timeouts for HomeKit's strict realtime requirements.
- * - Designed for Homebridge plugin authors or advanced users who need robust, platform-aware FFmpeg session control for HomeKit and related integrations.
+ * - 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 { type CameraRecordingConfiguration } from "homebridge";
-import { type Nullable, type PartialWithId } from "../util.js";
-import type { FfmpegOptions } from "./options.js";
-import { FfmpegProcess } from "./process.js";
+import { AudioRecordingCodecType, AudioRecordingSamplerate } from "./hap-enums.ts";
+import type { HbpuAbortError, PartialWithId } from "../util.ts";
+import type { CameraRecordingConfiguration } from "homebridge";
+import type { FfmpegOptions } from "./options.ts";
+import { FfmpegProcess } from "./process.ts";
+import type { FfmpegProcessInit } from "./process.ts";
+import type { Mp4Segment } from "./mp4-assembler.ts";
+import type { Writable } from "node:stream";
 /**
  * Base options shared by both fMP4 recording and livestream sessions.
  *
- * @property audioFilters        - Audio filters for FFmpeg to process. These are passed as an array of filters.
+ * @property audioFilters        - Audio filters for FFmpeg to process. These are passed as an array of filters. Recording-only: the livestream builder ignores this
+ *                                 field, driving its audio-filter decision from the `audio` target instead.
  * @property audioStream         - Audio stream input to use, if the input contains multiple audio streams. Defaults to `0` (the first audio stream).
- * @property codec               - The codec for the input video stream. Valid values are `av1`, `h264`, and `hevc`. Defaults to `h264`.
+ * @property codec               - The codec for the input video stream. Valid values are `av1`, `h264`, and `hevc` (`h265` is accepted as an alias for `hevc`).
+ *                                 Defaults to `h264`.
  * @property enableAudio         - Indicates whether to enable audio or not.
- * @property hardwareDecoding    - Enable hardware-accelerated video decoding if available. Defaults to what was specified in `ffmpegOptions`.
+ * @property hardwareDecoding    - Enable hardware-accelerated video decoding if available. Defaults to what was specified in `ffmpegOptions` when FFmpeg is at least
+ *                                 8.x; on an older FFmpeg the default is always `false` regardless of what `ffmpegOptions` specifies.
  * @property hardwareTranscoding - Enable hardware-accelerated video transcoding if available. Defaults to what was specified in `ffmpegOptions`.
- * @property transcodeAudio      - Transcode audio to AAC. This can be set to false if the audio stream is already in AAC. Defaults to `true`.
+ * @property transcodeAudio      - Transcode audio to AAC. This can be set to false if the audio stream is already in AAC. Defaults to `true`. Recording-only: the
+ *                                 livestream builder ignores this field, driving its transcode decision from the `audio` target instead.
  * @property videoFilters        - Video filters for FFmpeg to process. These are passed as an array of filters.
  * @property videoStream         - Video stream input to use, if the input contains multiple video streams. Defaults to `0` (the first video stream).
+ *
+ * @category FFmpeg
  */
 export interface FMp4BaseOptions {
     audioFilters: string[];
@@ -56,24 +87,6 @@ export interface FMp4BaseOptions {
  * @property sampleRate  - Optional. Audio sample rate in Hz (e.g., `8000`). Used when `format` is set. Defaults to `8000`.
  * @property url         - The URL of the audio input source.
  *
- * @example
- *
- * ```ts
- * // Raw audio from a DoorBird audio.cgi endpoint.
- * const rawAudioInput: FMp4AudioInputConfig = {
- *
- *   format: "mulaw",
- *   sampleRate: 8000,
- *   url: "http://doorbird-ip/bha-api/audio.cgi"
- * };
- *
- * // Self-describing RTSP audio stream - only URL is needed.
- * const rtspAudioInput: FMp4AudioInputConfig = {
- *
- *   url: "rtsp://camera-ip/audio"
- * };
- * ```
- *
  * @see FMp4LivestreamOptions
  *
  * @category FFmpeg
@@ -84,12 +97,33 @@ export interface FMp4AudioInputConfig {
     sampleRate?: number;
     url: string;
 }
+/**
+ * The resolved audio-encode target for fMP4 production. Its presence on an fMP4 command line is the single signal to transcode the audio stream to this target; its
+ * absence means the already-encoded audio is copied through untouched. Any audio filters are carried inside the target because filtering requires transcoding - a filter
+ * without a transcode is unrepresentable by construction, so the filters-require-transcoding rule holds declaratively rather than through a runtime override.
+ *
+ * @property channels    - Optional. Number of output audio channels. Defaults to `1` when omitted.
+ * @property codec       - The AAC codec variant to encode to (low-complexity or enhanced low-delay).
+ * @property filters     - Optional. Audio filters applied ahead of the encoder. Supplying filters is what makes the transcode carry them; an empty or omitted list
+ *                         transcodes without filtering.
+ * @property samplerate  - The output audio sample rate.
+ *
+ * @category FFmpeg
+ */
+export interface FMp4AudioTarget {
+    channels?: number;
+    codec: AudioRecordingCodecType;
+    filters?: string[];
+    samplerate: AudioRecordingSamplerate;
+}
 /**
  * Options for configuring an fMP4 HKSV recording session.
  *
- * @property fps             - The video frames per second for the session.
- * @property probesize       - Number of bytes to analyze for stream information.
- * @property timeshift       - Timeshift offset for event-based recording (in milliseconds).
+ * @property fps             - The video frames per second for the session. Defaults to 30.
+ * @property probesize       - Number of bytes to analyze for stream information. Defaults to 5,000,000 bytes (mirrors FFmpeg's own default probesize).
+ * @property timeshift       - Timeshift offset for event-based recording (in milliseconds). Defaults to 0.
+ *
+ * @category FFmpeg
  */
 export interface FMp4RecordingOptions extends FMp4BaseOptions {
     fps: number;
@@ -112,208 +146,313 @@ export interface FMp4LivestreamOptions extends FMp4BaseOptions {
     url: string;
 }
 /**
- * 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.
+ * Construction-time options for {@link FfmpegRecordingProcess}.
  *
- * @see FfmpegRecordingProcess
- * @see FfmpegLivestreamProcess
+ * @property recording          - Optional. fMP4 recording options. Every field defaults when omitted; the interface surface matches {@link FMp4RecordingOptions} but with
+ *                                all fields optional.
+ * @property recordingConfig    - The HomeKit recording configuration (resolution, codec profile, audio codec, sample rate, channels) produced by the HKSV delegate.
+ * @property verbose            - Optional. When `true`, FFmpeg is invoked with verbose logging (`-loglevel level+verbose`) regardless of the global
+ *                                `codecSupport.verbose` flag. Defaults to `false`.
+ *
+ * @remarks Supplying `args` (inherited from {@link FfmpegProcessInit}) is an advanced escape hatch that replaces the auto-built command line entirely. When `args` is
+ * present, the mode-specific config fields (`recording`, `verbose`) do not participate in command-line assembly - they become no-ops. Typical callers omit `args` and
+ * let the class build the command line from the recording configuration.
+ *
+ * @see FfmpegProcessInit
+ * @see FMp4RecordingOptions
+ *
+ * @category FFmpeg
+ */
+export interface FfmpegRecordingInit extends FfmpegProcessInit {
+    recording?: Partial<FMp4RecordingOptions>;
+    recordingConfig: CameraRecordingConfiguration;
+    verbose?: boolean;
+}
+/**
+ * Construction-time options for {@link FfmpegLivestreamProcess}.
+ *
+ * @property audio              - Optional. The resolved audio-encode target. When provided, the audio stream is transcoded to it (with any filters it carries); when
+ *                                omitted, the already-encoded audio is copied through untouched. This is the livestream path's sole audio-filter source.
+ * @property livestream         - Livestream source configuration. `url` is required; other {@link FMp4BaseOptions} fields are optional and default when omitted.
+ * @property segmentLength      - Optional. fMP4 fragment duration in milliseconds, applied to `-frag_duration` at construction time. Defaults to 1000 ms (1 second).
+ * @property verbose            - Optional. When `true`, FFmpeg is invoked with verbose logging (`-loglevel level+verbose`) regardless of the global
+ *                                `codecSupport.verbose` flag. Defaults to `false`.
+ *
+ * @remarks Supplying `args` (inherited from {@link FfmpegProcessInit}) is an advanced escape hatch that replaces the auto-built command line entirely. When `args` is
+ * present, the mode-specific config fields (`audio`, `livestream`, `segmentLength`, `verbose`) do not participate in command-line assembly - they become no-ops. Typical
+ * callers omit `args` and let the class build the command line from `livestream` + `audio`.
+ *
+ * @see FfmpegProcessInit
+ * @see FMp4AudioTarget
+ * @see FMp4LivestreamOptions
+ *
+ * @category FFmpeg
+ */
+export interface FfmpegLivestreamInit extends FfmpegProcessInit {
+    audio?: FMp4AudioTarget;
+    livestream: PartialWithId<FMp4LivestreamOptions, "url">;
+    segmentLength?: number;
+    verbose?: boolean;
+}
+/**
+ * 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).
+ *
+ * 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.
+ *
+ * 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 Mp4SegmentAssembler
  * @see FfmpegProcess
- * @see {@link https://ffmpeg.org/ffmpeg.html | FFmpeg Documentation}
+ *
+ * @category FFmpeg
  */
-declare abstract class FfmpegFMp4Process extends FfmpegProcess {
-    private isLoggingErrors;
-    protected readonly fMp4Options: Required<FMp4BaseOptions>;
-    protected readonly recordingConfig: CameraRecordingConfiguration;
+export declare abstract class FfmpegFMp4Process extends FfmpegProcess {
+    #private;
     /**
-     * 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`.
+     * stdout is consumed internally by the assembler. The public type is narrowed to `never` so TypeScript callers cannot accidentally attach a concurrent reader.
      */
-    constructor(ffmpegOptions: FfmpegOptions, recordingConfig: CameraRecordingConfiguration, fMp4Options?: Partial<FMp4BaseOptions>, isVerbose?: boolean);
-    private _isVerbose;
-    protected buildCommandLine(): void;
-    protected abstract inputArgs(): string[];
-    protected abstract separateAudioInputArgs(): string[];
-    protected abstract audioInputIndex(): number;
-    protected abstract videoEncoderArgs(): string[];
-    protected abstract postFilterArgs(): string[];
-    protected abstract metadataLabel(): string;
-    protected abstract handleParsedBox(header: Buffer, data: Buffer, dataLength: number, type: number): void;
+    readonly stdout: never;
     /**
-     * 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().
+     * Construct and spawn a new fMP4 segment-producing process.
+     *
+     * @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).
      */
-    protected configureProcess(): void;
+    protected constructor(options: FfmpegOptions, init: FfmpegProcessInit, segmentTimeout?: number);
     /**
-     * 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.
+     * 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.
      */
-    protected stopProcess(): void;
+    getInitSegment(): Promise<Buffer>;
     /**
-     * Stops the FFmpeg process and logs errors if specified.
+     * 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.
      *
-     * @param logErrors - If `true`, logs FFmpeg errors. Defaults to the internal process logging state.
+     * @param init - Optional init options. `signal` composes with the process's own signal; aborting it terminates only this generator call, not the process.
      *
-     * @example
+     * @returns An async generator yielding media segment buffers in stream order.
+     */
+    segments(init?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<Buffer>;
+    /**
+     * 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}.
      *
-     * ```ts
-     * process.stop();
-     * ```
+     * @returns The buffered-segment depth.
      */
-    stop(logErrors?: boolean): void;
+    get bufferedSegments(): number;
     /**
-     * Logs errors from FFmpeg process execution, handling known benign HKSV stream errors gracefully.
+     * 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.
      *
-     * @param exitCode - The exit code from the FFmpeg process.
-     * @param signal   - The signal (if any) used to terminate the process.
+     * @param init - Optional init options. `signal` composes with the process's own signal; aborting it terminates only this generator call, not the process.
+     *
+     * @returns An async generator yielding one `"init"` segment followed by `"media"` segments in stream order.
      */
-    protected logFfmpegError(exitCode: Nullable<number>, signal: Nullable<NodeJS.Signals>): void;
+    stream(init?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<Mp4Segment>;
 }
 /**
- * Manages a HomeKit Secure Video recording FFmpeg process.
+ * The minimal surface a recording consumer reads off a recording process. This is the product half of the recording dependency-inversion seam: an HKSV recording
+ * delegate depends on this narrow interface rather than the concrete {@link FfmpegRecordingProcess}, so a test (or any alternative segment source) can substitute a
+ * fake without dragging FFmpeg into the consumer's dependency graph. The interface is type-only, so importing it costs a consumer nothing at runtime.
  *
- * @example
+ * Every member here is defined on {@link FfmpegFMp4Process} (`getInitSegment`, `segments`, `stream`, `bufferedSegments`) or inherited from {@link FfmpegProcess}
+ * (`abort`, `isTimedOut`, `signal`, `stderrLog`, `stdin`), so the real {@link FfmpegRecordingProcess} satisfies it by inheritance and carries only an `implements`
+ * annotation - zero runtime behavior change. This is deliberately the consumer's minimal surface, not the class's full surface: `ready`, `exited`, `stdout`,
+ * `aborted`, `hasError`, and `[Symbol.asyncDispose]` are NOT here because the recording consumer does not read them.
  *
- * ```ts
- * const process = new FfmpegRecordingProcess(ffmpegOptions, recordingConfig, 30, true, 5000000, 0);
- * process.start();
- * ```
- *
- * @see FfmpegFMp4Process
+ * @see FfmpegRecordingProcess
+ * @see RecordingProcessFactory
  *
  * @category FFmpeg
  */
-export declare class FfmpegRecordingProcess extends FfmpegFMp4Process {
+export interface RecordingProcess {
     /**
-     * Indicates whether the recording has timed out waiting for FFmpeg output.
+     * Abort the recording process and tear it down. Defaults to `HbpuAbortError("shutdown")` when no reason is supplied; explicit reasons pass through unchanged.
+     *
+     * @param reason - Optional abort reason. Typically an {@link HbpuAbortError}.
      */
-    isTimedOut: boolean;
-    private readonly fps;
-    private readonly probesize;
-    private recordingBuffer;
-    private readonly timeshift;
+    abort(reason?: unknown): void;
     /**
-     * Constructs a new FFmpeg recording process for HKSV events.
+     * The number of assembled media segments buffered but not yet pulled through {@link RecordingProcess.segments} - the consumer's catch-up reserve when the source
+     * stalls.
+     */
+    readonly bufferedSegments: number;
+    /**
+     * Resolve with the fMP4 initialization segment (typically `ftyp` + `moov`). Rejects with `signal.reason` if the process aborts before the initialization segment
+     * completes.
      *
-     * @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`.
+     * @returns A promise resolving to the initialization segment bytes.
      */
-    constructor(options: FfmpegOptions, recordingConfig: CameraRecordingConfiguration, fMp4Options?: Partial<FMp4RecordingOptions>, isVerbose?: boolean);
-    protected inputArgs(): string[];
-    protected separateAudioInputArgs(): string[];
-    protected audioInputIndex(): number;
-    protected videoEncoderArgs(): string[];
-    protected postFilterArgs(): string[];
-    protected metadataLabel(): string;
-    protected handleParsedBox(header: Buffer, data: Buffer, dataLength: number, type: number): void;
+    getInitSegment(): Promise<Buffer>;
     /**
-     * Stops the FFmpeg process and performs cleanup, ensuring the segment generator can exit.
+     * `true` when the abort reason indicates a timeout (the inter-segment watchdog fired or the platform `TimeoutError` was raised).
      */
-    protected stopProcess(): void;
+    readonly isTimedOut: boolean;
     /**
-     * Asynchronously generates complete segments from FFmpeg output, formatted for HomeKit Secure Video.
+     * Async generator yielding each completed media segment (a concatenated `moof` + `mdat` pair) as a single Buffer, in stream order. Terminates cleanly when the process
+     * or the caller's signal aborts, or when the underlying source 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?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<Buffer>;
+    /**
+     * The composed abort signal representing the recording process's lifetime. Aborts exactly once; the reason on `signal.reason` names the cause.
+     */
+    readonly signal: AbortSignal;
+    /**
+     * The accumulated stderr lines the process produced, preserved across teardown for post-mortem inspection. A readonly view: callers read, they do not mutate.
+     */
+    readonly stderrLog: readonly string[];
+    /**
+     * Writable standard input stream the recording bytes are fed into.
+     */
+    readonly stdin: Writable;
+    /**
+     * 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. A third view over the same pipeline as {@link RecordingProcess.getInitSegment} / {@link RecordingProcess.segments} that
+     * shares their single-consumer contract - a consumer uses this view or that pair, never both.
      *
-     * @example
+     * @param init - Optional init options. `signal` composes with the process's own signal; aborting it terminates only this generator call, not the process.
      *
-     * ```ts
-     * for await(const segment of process.segmentGenerator()) {
+     * @returns An async generator yielding one `"init"` segment followed by `"media"` segments in stream order.
+     */
+    stream(init?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<Mp4Segment>;
+}
+/**
+ * The creational half of the recording dependency-inversion seam: build a {@link RecordingProcess} from the shared options and the recording init. A consumer holds
+ * this factory typed as the abstraction and constructs through it, so a test can substitute a factory that returns a fake recording process. The production factory is
+ * {@link recordingProcessFactory}, whose `create` is exactly the {@link FfmpegRecordingProcess} constructor call - so routing construction through this seam is
+ * behavior-neutral, mirroring HBUP's `streamingDelegateFactory` precedent.
+ *
+ * @see recordingProcessFactory
+ * @see RecordingProcess
+ *
+ * @category FFmpeg
+ */
+export interface RecordingProcessFactory {
+    /**
+     * Construct a recording process for the supplied options and recording init.
      *
-     *   // Process each segment for HomeKit.
-     * }
-     * ```
+     * @param options - Shared {@link FfmpegOptions} configuration (codec support, logger, debug flag, name).
+     * @param init    - Recording init options. See {@link FfmpegRecordingInit}.
+     *
+     * @returns A new {@link RecordingProcess}.
      */
-    segmentGenerator(): AsyncGenerator<Buffer>;
+    create(options: FfmpegOptions, init: FfmpegRecordingInit): RecordingProcess;
 }
 /**
- * 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 init = await proc.getInitSegment();
+ *
+ * for await (const segment of proc.segments()) {
  *
- * const initSegment = await process.getInitSegment();
+ *   // Forward each media segment to HomeKit.
+ * }
  * ```
  *
  * @see FfmpegFMp4Process
+ * @see FfmpegProcess
  *
  * @category FFmpeg
  */
-export declare 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?: number;
-    private _hasAudioInput;
-    private _initSegment;
-    private _initSegmentParts;
-    private hasInitSegment;
-    private readonly livestreamOptions;
-    /**
-     * Constructs a new FFmpeg livestream 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`.
-     */
-    constructor(options: FfmpegOptions, recordingConfig: CameraRecordingConfiguration, livestreamOptions: PartialWithId<FMp4LivestreamOptions, "url">, isVerbose?: boolean);
-    protected inputArgs(): string[];
-    protected separateAudioInputArgs(): string[];
-    protected audioInputIndex(): number;
-    protected videoEncoderArgs(): string[];
-    protected postFilterArgs(): string[];
-    protected metadataLabel(): string;
-    protected handleParsedBox(header: Buffer, data: Buffer, _dataLength: number, type: number): void;
-    /**
-     * Starts the FFmpeg process, adjusting the fragment duration if segmentLength has been set.
-     *
-     * @example
-     *
-     * ```ts
-     * process.start();
-     * ```
-     */
-    start(): void;
+export declare class FfmpegRecordingProcess extends FfmpegFMp4Process implements RecordingProcess {
     /**
-     * Gets the fMP4 initialization segment generated by FFmpeg for the livestream.
-     *
-     * @returns A promise resolving to the initialization segment as a Buffer.
+     * Construct and spawn a new HKSV recording process.
      *
-     * @example
-     *
-     * ```ts
-     * const initSegment = await process.getInitSegment();
-     * ```
+     * @param options - Shared {@link FfmpegOptions} configuration (codec support, logger, debug flag, name).
+     * @param init    - Init options. See {@link FfmpegRecordingInit}.
      */
-    getInitSegment(): Promise<Buffer>;
+    constructor(options: FfmpegOptions, init: FfmpegRecordingInit);
+    protected logFailedTeardown(reason: HbpuAbortError): void;
+    protected logTimeoutTeardown(_reason: HbpuAbortError): void;
+}
+/**
+ * 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 declare const recordingProcessFactory: RecordingProcessFactory;
+/**
+ * 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 declare 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
-     *
-     * ```ts
-     * const init = process.initSegment;
-     * if(init) {
+     * Construct and spawn a new fMP4 livestream process.
      *
-     *   // 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(): Nullable<Buffer>;
+    constructor(options: FfmpegOptions, init: FfmpegLivestreamInit);
 }
-export {};
+//# sourceMappingURL=record.d.ts.map