@camstack/types 1.2.42 → 1.2.44

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

@@ -420,6 +420,7 @@ export declare const EgressTranscodeRequestSchema: z.ZodObject<{
         h264_mp4toannexb: "h264_mp4toannexb";
         hevc_mp4toannexb: "hevc_mp4toannexb";
     }>>;
+    publishLocally: z.ZodOptional<z.ZodBoolean>;
     pixelFormat: z.ZodOptional<z.ZodEnum<{
         yuv420p: "yuv420p";
         nv12: "nv12";
@@ -450,6 +451,7 @@ export declare const EgressTranscodeSchema: z.ZodObject<{
     transcoded: z.ZodBoolean;
     encoder: z.ZodString;
     decodeHwAccel: z.ZodNullable<z.ZodString>;
+    camStreamId: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export type EgressTranscode = z.infer<typeof EgressTranscodeSchema>;
 export declare const streamBrokerCapability: {
@@ -687,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
@@ -955,6 +959,7 @@ export declare const streamBrokerCapability: {
                 h264_mp4toannexb: "h264_mp4toannexb";
                 hevc_mp4toannexb: "hevc_mp4toannexb";
             }>>;
+            publishLocally: z.ZodOptional<z.ZodBoolean>;
             pixelFormat: z.ZodOptional<z.ZodEnum<{
                 yuv420p: "yuv420p";
                 nv12: "nv12";
@@ -983,6 +988,7 @@ export declare const streamBrokerCapability: {
             transcoded: z.ZodBoolean;
             encoder: z.ZodString;
             decodeHwAccel: z.ZodNullable<z.ZodString>;
+            camStreamId: z.ZodNullable<z.ZodString>;
         }, z.core.$strip>, "mutation">;
         /** Drop one reference. The child dies when the last holder releases. */
         readonly releaseEgressTranscode: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
@@ -1147,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/capabilities/stream-params.cap.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { type InferNativeProvider } from './capability-definition.js';
 import { DeviceType } from '../device/device-type.js';
+import { type InferNativeProvider } from './capability-definition.js';
 /** One of the camera's stream profiles. */
 export declare const StreamProfileSchema: z.ZodEnum<{
     sub: "sub";
@@ -183,7 +183,13 @@ export declare const StreamParamsOptionsSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 /** A partial change to one profile — every field optional; a provider
- *  ignores fields it doesn't support. */
+ *  ignores fields it doesn't support.
+ *
+ *  There is deliberately NO `audio` here. It existed until 2026-08-07,
+ *  reachable from no form and honoured by exactly one provider, while the
+ *  camera's microphone is a whole-device fact. It now has one writer,
+ *  `privacyMask.setAudioEnabled`, which writes every profile — see
+ *  `privacy-mask.cap.ts`. */
 export declare const StreamProfilePatchSchema: z.ZodObject<{
     width: z.ZodOptional<z.ZodNumber>;
     height: z.ZodOptional<z.ZodNumber>;
@@ -203,7 +209,6 @@ export declare const StreamProfilePatchSchema: z.ZodObject<{
         main: "main";
     }>>;
     gop: z.ZodOptional<z.ZodNumber>;
-    audio: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type StreamParamsStatus = z.infer<typeof StreamParamsStatusSchema>;
 export type StreamParamsOptions = z.infer<typeof StreamParamsOptionsSchema>;
@@ -316,7 +321,6 @@ export declare const streamParamsCapability: {
                     main: "main";
                 }>>;
                 gop: z.ZodOptional<z.ZodNumber>;
-                audio: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>;
         }, z.core.$strip>, z.ZodVoid, "mutation">;
         /**

package/dist/device/device-profile.d.ts

@@ -120,10 +120,18 @@ export interface DeviceProfile {
      */
     readonly defaults: DeviceProfileDefaults;
     /**
-     * Generic settings overrides (snapshot interval, pre-buffer flag,
-     * etc.). Same sticky semantics as defaults — applied on first read,
-     * operator override wins. Keys are dot-paths interpreted by the
-     * per-driver / per-addon config schema.
+     * Generic settings overrides, keyed by dot-path, intended to be
+     * interpreted by the per-driver / per-addon config schema.
+     *
+     * **Nothing reads this today.** It is a declared extension point with no
+     * consumer anywhere in the workspace, so any entry placed here is inert. It
+     * shipped populated — `snapshot.minRefreshIntervalSec: 3600` and
+     * `streamBroker.preBufferEnabled: false` on the battery profile — which read
+     * as live policy and were not: both behaviours are really enforced off
+     * `DeviceFeature.BatteryOperated` directly, by `BATTERY_DEFAULT_MAX_AGE_S`
+     * in `snapshot.addon.ts` and by `getEffectivePreBufferSec` in
+     * `stream-broker-manager.ts`. Emptied 2026-08-07; keep it empty until a
+     * reader exists, or an entry here is just documentation that lies.
      */
     readonly settings: Readonly<Record<string, unknown>>;
 }

package/dist/device/system-mirror.d.ts

@@ -62,6 +62,17 @@ export interface SystemMirrorApi extends SliceHandleApi {
                 addonId?: string;
             }): Promise<ReadonlyArray<DeviceInfo>>;
         };
+        /**
+         * Single-device metadata read. Required — `refreshDeviceMetadata`
+         * runs once per `device.registered` / `device.updated` event, and a
+         * full-catalog fetch there is what melts the hub during a
+         * deploy/restart storm (see `refreshDeviceMetadata`).
+         */
+        readonly getDevice: {
+            query(input: {
+                deviceId: number;
+            }): Promise<DeviceInfo | null>;
+        };
     };
     readonly deviceState: SliceHandleApi['deviceState'] & {
         readonly getAllSnapshots: {

package/dist/ffmpeg/encode-defaults.d.ts

@@ -56,6 +56,24 @@ export declare const WEBRTC_EGRESS_PROFILE: EncodeProfile;
  * audio plane (out-of-band), so this is `passthrough` exactly like the browser
  * — see the ADR for why the previous in-band Opus was encoded and discarded.
  */
+/**
+ * Alexa's egress asks for OPUS, and that is a change with a history.
+ *
+ * The previous profile encoded Opus IN-BAND into an MPEG-TS, where it was
+ * discarded: Opus is `stream_type 0x06` and the broker's demuxer maps only
+ * `0x0f` (aac), `0x03`/`0x04` (mp2) and `0x81` (ac3). Every frame it produced
+ * died at the demuxer, so the encode was replaced with `passthrough` — correct,
+ * because paying libopus for nothing is worse than silence.
+ *
+ * But `passthrough` means the egress emits NO audio at all, and Alexa's audio
+ * does not arrive by magic: it rides the published stream, which is what the
+ * WebRTC session dials. So the Echo had video and silence either way.
+ *
+ * Opus here now reaches the egress AUDIO SIDECAR — a separate RTP leg the
+ * restreamer grafts onto its SDP — which never touches the MPEG-TS demuxer that
+ * killed the in-band attempt. Same codec, different plane, and this one the
+ * consumer can actually negotiate.
+ */
 export declare const ALEXA_EGRESS_PROFILE: EncodeProfile;
 /** VBV window for a consumer whose budget is enforced per second (HomeKit). */
 export declare const RATE_CONTROL_TIGHT: FfmpegRateControl;

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

@@ -21,7 +21,7 @@
  * `-i`; everything that configures an OUTPUT comes after. `__tests__/
  * ffmpeg-invocation.spec.ts` asserts INDEXES, never membership.
  */
-import type { EncodeProfile, AudioEncode } from '../encode-profile.js';
+import type { AudioEncode, EncodeProfile } from '../encode-profile.js';
 /** Everything that configures the ffmpeg INPUT. Emitted strictly before `-i`. */
 export interface FfmpegInputPlan {
     /** An RTSP url, a `pipe:0` stdin feed, or a file path. */
@@ -34,6 +34,25 @@ export interface FfmpegInputPlan {
     readonly rtspTransport?: 'tcp' | 'udp' | null;
     /** `-fflags` values, e.g. `['+discardcorrupt']`, `['+genpts']`. */
     readonly fflags?: readonly string[];
+    /**
+     * `-analyzeduration` (microseconds) and `-probesize` (bytes): how long ffmpeg
+     * inspects the input before it emits ANYTHING.
+     *
+     * Unset means ffmpeg's defaults — 5 s and 5 MB — and on a live egress pull
+     * that is a five-second stall before the first packet, paid by whoever is
+     * staring at the player. Measured on the live hub: a HomeKit session on a
+     * 9 fps slot took 9 s from `stream started` to the first packet out of
+     * ffmpeg and 12.2 s to the first key frame. The SLOWER the slot, the longer
+     * the wait, because the default budget is wall-clock over an input that
+     * delivers few frames per second — which is why the 25 fps slot looked fine
+     * and the 9 fps one looked broken.
+     *
+     * Safe to shrink on RTSP specifically: the SDP already declares the codec,
+     * so there is nothing for the probe to discover. Leave unset for inputs that
+     * genuinely need discovery (a file of unknown provenance, a raw pipe).
+     */
+    readonly analyzeDurationUs?: number;
+    readonly probeSizeBytes?: number;
     /** Caller-supplied input options (an `EncodeProfile.inputArgs`, probe flags). */
     readonly extraArgs?: readonly string[];
 }
@@ -82,6 +101,21 @@ export interface FfmpegVideoEncodePlan {
     readonly pixelFormat?: string;
     readonly fps?: number;
     readonly gopFrames?: number;
+    /**
+     * `-force_key_frames expr:gte(t,n_forced*<sec>)` — an IDR every `<sec>`
+     * seconds of OUTPUT time, regardless of what the source does.
+     *
+     * Only a fragmented-MP4 consumer needs this today, and it needs it for a
+     * structural reason rather than a quality one: an fMP4 fragment written with
+     * `frag_keyframe` is cut at a key frame, so the key-frame cadence IS the
+     * fragment cadence. `-g` bounds the GOP the encoder would choose anyway;
+     * this pins the boundary to a wall-clock grid the muxer can meet.
+     *
+     * Structurally absent from {@link FfmpegVideoCopyPlan}: a copy has no
+     * encoder to instruct, and ffmpeg accepts the flag there, warns, and ignores
+     * it — the silent-no-op shape this file exists to prevent.
+     */
+    readonly forceKeyFramesSeconds?: number;
     readonly bf?: number;
     readonly bitrateKbps?: number;
     readonly rateControl?: FfmpegRateControl;
@@ -136,13 +170,48 @@ export interface FfmpegRtpOutput {
     /** Path ffmpeg writes this output's SDP to (`-sdp_file`). */
     readonly sdpFile?: string;
 }
+/**
+ * A fragmented-MP4 bytestream on stdout: `ftyp`+`moov` once, then a
+ * `moof`+`mdat` per fragment. The shape HomeKit Secure Video's recording
+ * delegate consumes, and the shape a CamStack clip source can consume from the
+ * same child (D67's primitive, one fragmenter, two consumers).
+ *
+ * ## Why `frag_keyframe` + `min_frag_duration`, and NOT `frag_duration`
+ *
+ * HKSV requires every media fragment to START on a sync sample. `frag_keyframe`
+ * cuts a fragment at each key frame, which satisfies that by construction.
+ * `-frag_duration` cuts at a wall-clock boundary *whether or not* a key frame
+ * has arrived, so a source whose IDR is late produces a fragment that opens on
+ * a delta frame — accepted by the muxer, rejected by the consumer, and
+ * invisible in an argv test. `-min_frag_duration` is the safe half of the pair:
+ * it only ever DELAYS a cut, so the boundary stays a key frame and a source
+ * with a 1 s GOP does not emit four fragments where one was negotiated.
+ *
+ * The consequence, stated because it decides what the caller must do: the
+ * fragment length is the key-frame cadence, so a caller that wants ~N-second
+ * fragments must also pin {@link FfmpegVideoEncodePlan.forceKeyFramesSeconds}.
+ * On a `copy` plan it cannot, and the fragment length is then whatever the
+ * SOURCE's GOP makes it — `fragmentMs` becomes a floor, not a target.
+ */
+export interface FfmpegFmp4Sink {
+    readonly kind: 'stdout';
+    readonly container: 'mp4';
+    /**
+     * The negotiated fragment length in milliseconds. Emitted as
+     * `-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;
+}
 export type FfmpegSink = {
     readonly kind: 'rtsp-listen';
     readonly url: string;
 } | {
     readonly kind: 'stdout';
     readonly container: 'h264' | 'hevc' | 'mpegts';
-}
+} | FfmpegFmp4Sink
 /**
  * Two independent mapped RTP outputs. Generic ffmpeg RTP vocabulary — the
  * SRTP encryption, the port allocation and the payload-type numbers stay
@@ -235,6 +304,37 @@ export interface EncodeProfileInvocationInput {
     readonly logLevel?: 'error' | 'warning' | 'info';
     readonly threadCount?: number;
     readonly audioSidecar?: FfmpegAudioSidecar | null;
+    /**
+     * How the encoder is bounded. `EncodeProfile` carries a bitrate but not the
+     * WINDOW it is enforced over, and the window is the difference between a
+     * HomeKit stream that fits its per-second budget and one that overshoots on
+     * every key frame. Absent ⇒ the relaxed two-second default a browser wants.
+     *
+     * The three overlays below are on the INVOCATION rather than on
+     * `EncodeProfile` on purpose: they are consumer-protocol facts
+     * (`acquireEgressTranscode` exposes each as its own named request field),
+     * while `EncodeProfile` is the operator-facing shape a derived-stream editor
+     * writes. Folding them into the profile would put ffmpeg detail in front of
+     * an operator who has no way to judge it.
+     */
+    readonly rateControl?: FfmpegRateControl;
+    /** `-bsf:v` — `dump_extra` for a consumer that negotiates its own SDP. */
+    readonly bitstreamFilter?: string;
+    /** `-pix_fmt`. */
+    readonly pixelFormat?: string;
+    /**
+     * `-force_key_frames` on a fixed grid — see
+     * {@link FfmpegVideoEncodePlan.forceKeyFramesSeconds}. An overlay like the
+     * three above rather than an `EncodeProfile` field: it is a CONSUMER-protocol
+     * fact (an fMP4 fragment length the consumer negotiated), not something an
+     * operator authoring a derived stream can judge.
+     *
+     * Applies only to the encode branch. On a smart COPY there is no encoder to
+     * instruct, and the caller — not this adapter — has to decide whether a
+     * source-dictated GOP is acceptable, because only the caller knows what it
+     * promised its consumer.
+     */
+    readonly forceKeyFramesSeconds?: number;
 }
 /**
  * Adapt an `EncodeProfile` (the operator/consumer-facing shape) into an