@camstack/types 1.2.43 → 1.2.44

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;
 }