@camstack/types 1.2.43 → 1.2.45

package/dist/capabilities/pipeline-orchestrator.cap.d.ts

@@ -449,6 +449,7 @@ declare const CameraStatusSchema: z.ZodObject<{
         notifications: "notifications";
         "object-detection": "object-detection";
         "device-audio": "device-audio";
+        "broker-audio": "broker-audio";
     }>>>;
     fetchedAt: z.ZodNumber;
 }, z.core.$strip>;
@@ -1099,6 +1100,7 @@ export declare const pipelineOrchestratorCapability: {
                     notifications: "notifications";
                     "object-detection": "object-detection";
                     "device-audio": "device-audio";
+                    "broker-audio": "broker-audio";
                 }>;
                 label: z.ZodString;
                 costWhenOff: z.ZodString;
@@ -1124,6 +1126,8 @@ export declare const pipelineOrchestratorCapability: {
                 }, z.core.$strip>, z.ZodObject<{
                     kind: z.ZodLiteral<"camera-mask">;
                     capName: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"broker-audio-mute">;
                 }, z.core.$strip>], "kind">;
             }, z.core.$strip>>>;
             fetchedAt: z.ZodNumber;
@@ -1151,6 +1155,7 @@ export declare const pipelineOrchestratorCapability: {
                 notifications: "notifications";
                 "object-detection": "object-detection";
                 "device-audio": "device-audio";
+                "broker-audio": "broker-audio";
             }>;
             enabled: z.ZodBoolean;
         }, z.core.$strip>, z.ZodObject<{
@@ -1164,6 +1169,7 @@ export declare const pipelineOrchestratorCapability: {
                     notifications: "notifications";
                     "object-detection": "object-detection";
                     "device-audio": "device-audio";
+                    "broker-audio": "broker-audio";
                 }>;
                 label: z.ZodString;
                 costWhenOff: z.ZodString;
@@ -1189,6 +1195,8 @@ export declare const pipelineOrchestratorCapability: {
                 }, z.core.$strip>, z.ZodObject<{
                     kind: z.ZodLiteral<"camera-mask">;
                     capName: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"broker-audio-mute">;
                 }, z.core.$strip>], "kind">;
             }, z.core.$strip>>>;
             fetchedAt: z.ZodNumber;
@@ -1310,6 +1318,7 @@ export declare const pipelineOrchestratorCapability: {
                 notifications: "notifications";
                 "object-detection": "object-detection";
                 "device-audio": "device-audio";
+                "broker-audio": "broker-audio";
             }>>>;
             fetchedAt: z.ZodNumber;
         }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
@@ -1429,6 +1438,7 @@ export declare const pipelineOrchestratorCapability: {
                 notifications: "notifications";
                 "object-detection": "object-detection";
                 "device-audio": "device-audio";
+                "broker-audio": "broker-audio";
             }>>>;
             fetchedAt: z.ZodNumber;
         }, z.core.$strip>>>, import("./capability-definition.js").CapabilityMethodKind>;

package/dist/capabilities/pipeline-runner.cap.d.ts

@@ -55,6 +55,8 @@ declare const DetailResultSchema: z.ZodObject<{
     }, z.core.$strip>>;
     embedding: z.ZodOptional<z.ZodString>;
     label: z.ZodOptional<z.ZodString>;
+    labelTier: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+    labelModelId: z.ZodOptional<z.ZodString>;
     alignedCropJpeg: z.ZodOptional<z.ZodString>;
     nativeFaceShortSidePx: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
@@ -623,6 +625,8 @@ export declare const pipelineRunnerCapability: {
                 }, z.core.$strip>>;
                 embedding: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelTier: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+                labelModelId: z.ZodOptional<z.ZodString>;
                 alignedCropJpeg: z.ZodOptional<z.ZodString>;
                 nativeFaceShortSidePx: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
@@ -699,6 +703,8 @@ export declare const pipelineRunnerCapability: {
                 }, z.core.$strip>>;
                 embedding: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelTier: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+                labelModelId: z.ZodOptional<z.ZodString>;
                 alignedCropJpeg: z.ZodOptional<z.ZodString>;
                 nativeFaceShortSidePx: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;

package/dist/capabilities/schemas/streaming-shared.d.ts

@@ -317,6 +317,8 @@ export declare const BrokerStatsSchema: z.ZodObject<{
         channels: z.ZodNumber;
         supported: z.ZodBoolean;
     }, z.core.$strip>>>;
+    audioMuted: z.ZodOptional<z.ZodBoolean>;
+    audioMutedDropped: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 /**
  * Exporter-facing "profile restream" entry. Returned by

package/dist/capabilities/server-management.cap.d.ts

@@ -50,8 +50,8 @@ declare const ServerBootModeSchema: z.ZodEnum<{
  */
 declare const ServerUpdateStateSchema: z.ZodEnum<{
     idle: "idle";
-    checking: "checking";
     staging: "staging";
+    checking: "checking";
     "pending-restart": "pending-restart";
     "awaiting-confirmation": "awaiting-confirmation";
 }>;
@@ -123,8 +123,8 @@ declare const ServerPackageStatusSchema: z.ZodObject<{
     }>;
     updateState: z.ZodEnum<{
         idle: "idle";
-        checking: "checking";
         staging: "staging";
+        checking: "checking";
         "pending-restart": "pending-restart";
         "awaiting-confirmation": "awaiting-confirmation";
     }>;
@@ -189,8 +189,8 @@ export declare const serverManagementCapability: {
             }>;
             updateState: z.ZodEnum<{
                 idle: "idle";
-                checking: "checking";
                 staging: "staging";
+                checking: "checking";
                 "pending-restart": "pending-restart";
                 "awaiting-confirmation": "awaiting-confirmation";
             }>;

package/dist/capabilities/stream-broker.cap.d.ts

@@ -689,6 +689,8 @@ export declare const streamBrokerCapability: {
                 channels: z.ZodNumber;
                 supported: z.ZodBoolean;
             }, z.core.$strip>>>;
+            audioMuted: z.ZodOptional<z.ZodBoolean>;
+            audioMutedDropped: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
         /**
          * Force a one-shot probe of a single source stream: transiently dial the
@@ -1151,6 +1153,36 @@ export declare const streamBrokerCapability: {
         readonly isRtspEnabled: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             brokerId: z.ZodString;
         }, z.core.$strip>, z.ZodBoolean, import("./capability-definition.js").CapabilityMethodKind>;
+        /**
+         * ── Per-device audio-plane policy (D83) ───────────────────────────
+         *
+         * The BROKER-side mute: while `muted`, this node distributes none of
+         * the device's audio, on any plane it serves — live (WebRTC / encoded
+         * subscribers) AND recording (the RTSP restreamer the recorder pulls,
+         * which additionally serves the video-only SDP so the recorder's ffmpeg
+         * never declares an audio stream it will not receive).
+         *
+         * Keyed by `deviceId`, not `brokerId`: every one of a camera's streams
+         * carries the same microphone, and a per-stream answer would let main
+         * and sub disagree about whether the camera is silent.
+         *
+         * The state lives in the broker's existing `DeviceOverride` blob — no
+         * new store — and the mute is applied to a fresh broker at creation, so
+         * a restart, a re-dial or a catalog republish never un-mutes a camera.
+         */
+        readonly getDeviceAudioMute: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            muted: z.ZodBoolean;
+            appliedBrokers: z.ZodNumber;
+        }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
+        readonly setDeviceAudioMute: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            muted: z.ZodBoolean;
+        }, z.core.$strip>, z.ZodObject<{
+            muted: z.ZodBoolean;
+            appliedBrokers: z.ZodNumber;
+        }, z.core.$strip>, "mutation">;
     };
     readonly events: {
         readonly onCamStreamDemand: import("./capability-definition.js").CapabilityEventSchema<z.ZodObject<{

package/dist/ffmpeg/fmp4-box-splitter.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Fmp4BoxSplitter — cut an ffmpeg fragmented-MP4 byte stream into the units a
+ * consumer of fragments actually needs: ONE initialisation segment
+ * (`ftyp`+`moov`) followed by one unit per `moof`+`mdat` pair.
+ *
+ * This is the shape HomeKit Secure Video's `CameraRecordingDelegate` yields
+ * (`RecordingPacket` #0 is the initialisation, the rest are media fragments),
+ * and it is the same shape a CamStack clip source wants — which is the point.
+ * One fragmenter, two consumers ([roadmap 4b](../../../../../docs/roadmap.md)).
+ * The splitter therefore knows about NEITHER of them: it emits units, and
+ * {@link import('./fmp4-fragment-plane.js').Fmp4FragmentPlane} decides who gets
+ * them.
+ *
+ * ## Pure, streaming, bounded
+ *
+ * No I/O, no timers, no ffmpeg. `push` takes whatever bytes arrived and returns
+ * whatever units completed — a caller may hand it one byte at a time or a
+ * megabyte, and the units are identical either way (asserted). Memory is
+ * bounded by {@link Fmp4SplitterOptions.maxUnitBytes}: the splitter holds at
+ * most one in-progress unit plus a partial box, and a stream that exceeds the
+ * bound FAULTS rather than growing, because the alternative on a live 24/7
+ * source is the broker's heap.
+ *
+ * ## The box rules, from ISO/IEC 14496-12
+ *
+ * A box header is `size:uint32` + `type:4 chars`. `size == 1` means the real
+ * size is a `uint64` in the next 8 bytes; `size == 0` means "to end of file".
+ * A size-0 box is a FAULT here and not a special case: it cannot be cut into
+ * fragments at all, and pretending otherwise would produce one enormous unit
+ * whose bytes never arrive.
+ *
+ * ## What it does NOT do
+ *
+ * It never inspects `tfdt`/`trun` and never computes a fragment's duration. The
+ * fragment length is decided upstream by the muxer (`-min_frag_duration` plus a
+ * key-frame grid, see `@camstack/types` `ffmpeg/invocation.ts`), and a duration
+ * parsed here would be a SECOND opinion about the same fact — the failure mode
+ * D67 exists to prevent. A consumer that must verify conformance measures the
+ * arrival cadence, which is the thing it actually cares about.
+ */
+/** `init` is the `ftyp`+`moov` head; `fragment` is one `moof`+`mdat` pair. */
+export type Fmp4UnitKind = 'init' | 'fragment';
+export interface Fmp4Unit {
+    readonly kind: Fmp4UnitKind;
+    /** A standalone copy — the splitter never hands out a view into its buffer. */
+    readonly data: Uint8Array;
+    /** `0` for the initialisation segment, then `1, 2, 3…` per fragment. */
+    readonly sequence: number;
+}
+export interface Fmp4SplitterOptions {
+    /**
+     * The most bytes one unit may reach before the stream is declared unusable.
+     * A 4-second 1080p fragment is a few hundred KB; the default leaves three
+     * orders of magnitude of headroom and still bounds a source that is not
+     * really fMP4 (a plain MP4 with a trailing `moov`, say, whose single `mdat`
+     * is the entire recording).
+     */
+    readonly maxUnitBytes?: number;
+}
+export declare class Fmp4BoxSplitter {
+    private readonly maxUnitBytes;
+    /** Bytes of the CURRENT unit plus any partial box after it. */
+    private buffer;
+    /** Where the current unit starts inside {@link buffer}. */
+    private unitStart;
+    /** Where the box scanner has reached inside {@link buffer}. */
+    private cursor;
+    private state;
+    private nextSequence;
+    private faultReason;
+    private readonly interstitial;
+    constructor(options?: Fmp4SplitterOptions);
+    /**
+     * Non-null once the stream cannot be split. The splitter emits nothing
+     * further, so a caller polls this to kill the child rather than watching a
+     * silent stall — a fragmenter that quietly stops producing looks exactly like
+     * a camera with no motion.
+     */
+    get fault(): string | null;
+    /** Bytes currently held. The memory bound, observable rather than asserted. */
+    get pendingBytes(): number;
+    /**
+     * Top-level box types seen BETWEEN fragments and discarded — `mfra`, `free`,
+     * a stray `sidx`. Reported rather than dropped in silence: they are legal and
+     * useless to a fragment consumer, but a type nobody expected showing up here
+     * is the first symptom of a muxer that is not writing what we think it is.
+     */
+    get discardedInterstitialTypes(): readonly string[];
+    /**
+     * Feed bytes; get back whatever units completed. Returns `[]` once faulted.
+     */
+    push(chunk: Uint8Array): readonly Fmp4Unit[];
+    private append;
+    /** Consume every COMPLETE top-level box now in the buffer. */
+    private drainBoxes;
+    /**
+     * Apply one box to the state machine. Returns a unit when this box CLOSED
+     * one, `null` otherwise.
+     */
+    private consumeBox;
+    /**
+     * Parse the header at {@link cursor}, or `null` when too few bytes have
+     * arrived to know. Faults on a size the splitter cannot honour.
+     */
+    private readHeader;
+    private emit;
+    /**
+     * Drop everything already emitted or discarded. Without this the buffer is
+     * the whole stream and the process dies in hours, not minutes.
+     */
+    private compact;
+    private fail;
+}

package/dist/ffmpeg/fmp4-fragment-child.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Fmp4FragmentChild — one ffmpeg writing a fragmented MP4 to stdout, split into
+ * units and fanned out on a {@link Fmp4FragmentPlane}.
+ *
+ * ## Why this lives in the PRIMITIVE and not in the broker
+ *
+ * It was written as the stream-broker's third egress transport, on the premise
+ * ([D80](../../../../docs/decisions/adr-0080.md)) that its consumers would be
+ * in-process with the broker and could hold a live plane object. **They are
+ * not.** `addon-export-hap` — the HKSV recording delegate, the first real
+ * consumer — is a `hub-only` addon in its OWN runner ([D2](../../../../docs/decisions/adr-0002.md)),
+ * and a plane cannot cross a process boundary. The choice was a second copy of
+ * the splitter in the exporter, or one copy here beside the sink that produces
+ * the bytes. The sink, the splitter, the plane and this child are one primitive
+ * ([D84](../../../../docs/decisions/adr-0084.md)); `EgressTranscodeManager`
+ * keeps only what is broker business — sharing key, refcount, release grace.
+ *
+ * It is deliberately the same shape as `TranscodeEgress` (the dial transport)
+ * and `createPushChild` (the push one), because the three failures that cost
+ * sessions on those paths are the same three here:
+ *
+ *  - **It resolves on the first UNIT, never on the first byte.** A child whose
+ *    bytes do not parse as fMP4 is a child that will never produce a fragment,
+ *    and resolving on bytes hands the caller a handle nothing feeds.
+ *  - **It retries once in SOFTWARE.** `-hwaccel vaapi` fails to create a device
+ *    inside the stream-broker runner on the live hub (`code=244`), and the push
+ *    transport was dark for exactly as long as it lacked this retry.
+ *  - **A child that dies AFTER going live says so.** Silence reads as "it is
+ *    running"; the plane must be ended so a consumer's generator completes
+ *    rather than hanging on a producer that no longer exists.
+ *
+ * Two consumers: `EgressTranscodeManager.acquireFragments` (the broker, for a
+ * future CamStack clip source — roadmap 4b half 2) and `HksvFragmentSource` in
+ * `addon-export-hap`. It stays unreachable from `acquireEgressTranscode`'s
+ * request schema on purpose (see `egressTransportFromRequest`): a plane is a
+ * live object, so an off-node caller could not use one anyway.
+ */
+import type { spawn as nodeSpawn } from 'node:child_process';
+import type { IScopedLogger } from '../interfaces/logging.js';
+import type { FfmpegInvocation } from './invocation.js';
+import type { Fmp4FragmentPlane } from './fmp4-fragment-plane.js';
+export interface Fmp4FragmentChildDeps {
+    readonly logger: IScopedLogger;
+    readonly ffmpegBinaryPath: string;
+    readonly spawnFn: typeof nodeSpawn;
+    /** How long the child may produce no UNIT before it is declared dead. */
+    readonly firstUnitTimeoutMs?: number;
+    /** The child exited, or its output stopped parsing, AFTER it went live. */
+    readonly onChildExit?: (error: Error) => void;
+}
+export interface Fmp4FragmentChildArgs {
+    readonly sourceId: string;
+    /** Every line about this child is grouped per camera, without exception. */
+    readonly deviceId: number;
+    /** The negotiated fragment length — argv only; the splitter never reads it. */
+    readonly fragmentMs: number;
+    /** The invocation minus the sink, which this child owns. */
+    readonly invocation: Omit<FfmpegInvocation, 'sink' | 'audioSidecar'>;
+    /** Where the units go. Owned by the caller, ended by this child. */
+    readonly plane: Fmp4FragmentPlane;
+}
+export declare class Fmp4FragmentChild {
+    private readonly deps;
+    private readonly args;
+    private child;
+    private splitter;
+    private stopped;
+    private unitsOut;
+    private activeHwAccel;
+    constructor(deps: Fmp4FragmentChildDeps, args: Fmp4FragmentChildArgs);
+    /** Spawn, and resolve once the INIT segment has been cut out of stdout. */
+    start(): Promise<void>;
+    /** The backend the child ACTUALLY ran with — `null` for software. */
+    activeDecodeHwAccel(): string | null;
+    /** Kill ffmpeg and end the plane. Idempotent. */
+    stop(): Promise<void>;
+    private spawnAttempt;
+    /**
+     * The byte stream stopped being splittable. Not recoverable — the splitter
+     * cannot resynchronise mid-box — so the child is a corpse and every consumer
+     * has to be told, loudly, with the reason.
+     */
+    private onFault;
+    private killChild;
+}

package/dist/ffmpeg/fmp4-fragment-plane.d.ts

@@ -0,0 +1,142 @@
+import type { IScopedLogger } from '../interfaces/logging.js';
+import type { Fmp4Unit, Fmp4UnitKind } from './fmp4-box-splitter.js';
+/** One unit as a subscriber receives it. */
+export interface Fmp4Packet {
+    readonly kind: Fmp4UnitKind;
+    readonly data: Uint8Array;
+    /** The producer's sequence number. NOT contiguous per subscriber — a
+     *  subscriber that attached late starts at the retained init's own number. */
+    readonly sequence: number;
+    /** The final packet this subscriber will receive. Exactly one, or none. */
+    readonly isLast: boolean;
+}
+/** Why a subscription stopped. */
+export type Fmp4CloseReason = 
+/** The producer ended: the child exited, or the consumer released it. */
+'ended'
+/** The subscriber did not drain fast enough; its stream would have a hole. */
+ | 'slow-consumer'
+/** The subscriber closed it. */
+ | 'released';
+export interface Fmp4Subscription {
+    readonly id: string;
+    readonly tag: string;
+    /** Packets delivered so far — the premise the `isLast` contract rests on. */
+    readonly delivered: number;
+    /** Non-null once no further packets will arrive. */
+    readonly closedReason: Fmp4CloseReason | null;
+    /**
+     * The packet stream, with real backpressure: the generator suspends until a
+     * packet is queued, so a consumer that awaits each packet paces itself.
+     * The bounded queue only exists for the case where it does NOT.
+     */
+    packets(): AsyncGenerator<Fmp4Packet>;
+    /** Stop receiving. Idempotent. */
+    release(): void;
+}
+export interface Fmp4SubscriberInfo {
+    readonly tag: string;
+    readonly subscribedAt: number;
+    readonly delivered: number;
+    readonly closedReason: Fmp4CloseReason | null;
+}
+export interface Fmp4SubscribeInput {
+    /** Short caller identity for diagnostics — `hksv/615`, `clips/615`. */
+    readonly tag: string;
+    /**
+     * Fragments a subscriber may fall behind by before it is closed. Four is two
+     * negotiated fragment lengths of slack on a 4 s cadence — enough to ride out
+     * a GC pause, far short of the memory a real stall would take.
+     *
+     * A prebuffer replay is added ON TOP of this, never counted against it.
+     */
+    readonly queueCapacity?: number;
+    /**
+     * Replay the retained prebuffer before live fragments. Off by default: a
+     * clip consumer that joins an ongoing recording wants what happens NEXT, and
+     * handing it seconds of the past would silently shift its clip's start.
+     */
+    readonly withPrebuffer?: boolean;
+}
+/** How much past the plane keeps for a {@link Fmp4SubscribeInput.withPrebuffer}. */
+export interface Fmp4PrebufferOptions {
+    /**
+     * How far back the ring reaches, by fragment ARRIVAL time. HKSV's minimum
+     * prebuffer is 4000 ms and the fragment cadence is the source GOP on a copy
+     * branch (measured: 8 s on this fleet), so a window shorter than two
+     * cadences can hold nothing at all at the moment it is asked for.
+     */
+    readonly windowMs: number;
+    /**
+     * The hard ceiling. Non-negotiable, because the window alone does not bound
+     * RAM: same 8 s, 255 KB at 720p and 6.35 MB at 4K on the same cameras.
+     */
+    readonly maxBytes: number;
+}
+/** What the ring is holding right now — diagnostics, and a delegate's gate. */
+export interface Fmp4PrebufferStats {
+    readonly fragments: number;
+    readonly bytes: number;
+    /** Age of the OLDEST retained fragment. `0` when the ring is empty. */
+    readonly spanMs: number;
+}
+export declare class Fmp4FragmentPlane {
+    private readonly logger?;
+    private readonly prebuffer?;
+    /** Injectable clock — the ring's window is the one thing here that is
+     *  wall-clock dependent, and a test that sleeps 8 real seconds is a test
+     *  nobody runs. */
+    private readonly now;
+    private readonly subscriptions;
+    /** The last init unit seen, handed to every later subscriber. */
+    private retainedInit;
+    private ended;
+    /** Oldest first. Empty unless {@link Fmp4PrebufferOptions} was supplied. */
+    private readonly ring;
+    private ringBytes;
+    constructor(logger?: IScopedLogger | undefined, prebuffer?: Fmp4PrebufferOptions | undefined, 
+    /** Injectable clock — the ring's window is the one thing here that is
+     *  wall-clock dependent, and a test that sleeps 8 real seconds is a test
+     *  nobody runs. */
+    now?: () => number);
+    get subscriberCount(): number;
+    /** True once {@link end} has been called — no further units are accepted. */
+    get isEnded(): boolean;
+    /** What the prebuffer ring holds right now. All zeroes when disabled. */
+    prebufferStats(): Fmp4PrebufferStats;
+    subscribe(input: Fmp4SubscribeInput): Fmp4Subscription;
+    /**
+     * Fan one splitter unit out. An `init` REPLACES the retained one — ffmpeg
+     * emits exactly one per child, and a second means the child was respawned, in
+     * which case the old one describes a stream that no longer exists.
+     */
+    publish(unit: Fmp4Unit): void;
+    /**
+     * The producer stopped. Every subscriber drains what it holds; its final
+     * packet carries `isLast`, and its generator then completes.
+     */
+    end(reason?: string): void;
+    listSubscribers(): readonly Fmp4SubscriberInfo[];
+    /** End and forget everything. Idempotent. */
+    dispose(): void;
+    /**
+     * Add one fragment to the ring and evict from the front until BOTH bounds
+     * hold. Eviction is oldest-first, which is the one place in this file where
+     * dropping is correct: the ring is context, not stream — nobody is mid-decode
+     * on it, and a subscriber only ever receives a contiguous tail of it.
+     */
+    private retain;
+    /**
+     * The ring as a subscriber should receive it — window applied AT SUBSCRIBE
+     * time, not only at publish time. A camera that went quiet keeps its last
+     * fragment in the ring indefinitely (see the never-evict-the-newest rule),
+     * and replaying a 40-second-old fragment as "prebuffer" would put stale video
+     * at the head of a clip iOS presents as the moment of the event.
+     */
+    private trimmedRing;
+    private enqueue;
+    private closeSubscription;
+    private wake;
+    private facade;
+    private iterate;
+}

package/dist/ffmpeg/invocation.d.ts

@@ -198,8 +198,10 @@ export interface FfmpegFmp4Sink {
     readonly container: 'mp4';
     /**
      * The negotiated fragment length in milliseconds. Emitted as
-     * `-min_frag_duration` (microseconds): no fragment is cut before this much
-     * media has accumulated, and the cut itself still lands on a key frame.
+     * `-min_frag_duration` (microseconds) at {@link FMP4_MIN_FRAG_MARGIN} of this
+     * value — read that constant before changing anything here, the margin is
+     * what stops a camera whose GOP equals `fragmentMs` emitting fragments at
+     * twice the requested length.
      */
     readonly fragmentMs: number;
 }