node-av 6.2.0-beta.9 → 7.0.0-beta.1

package/dist/api/utilities/packet-age-watchdog.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Bounds how long an fMP4 muxer may hold a packet before emitting it in a fragment.
+ *
+ * Remembers when each packet reached the muxer, per output stream and in order, and
+ * forgets packets as the fragments carrying them are written. When the oldest pending
+ * packet of any stream is older than the limit, the next packet write fails with a
+ * descriptive error. The age does not depend on packet timestamps, so it also bounds
+ * retention caused by missing, constant or runaway timestamps. It counts the time
+ * while packets arrive: a pause of the whole input counts at most 2 s, so a source
+ * that goes quiet and resumes is not mistaken for a stalled muxer.
+ *
+ * @example
+ * ```typescript
+ * const watchdog = new PacketAgeWatchdog(60, (index) => `stream ${index}`);
+ * const output = await Muxer.open(
+ *   {
+ *     write: (chunk) => {
+ *       watchdog.consumeChunk(chunk);
+ *       return chunk.length;
+ *     },
+ *   },
+ *   { format: 'mp4', options: { movflags: '+frag_keyframe+empty_moov' } },
+ * );
+ * output.setPacketObserver(watchdog);
+ * ```
+ *
+ * @see {@link Muxer.setPacketObserver} For registering it with a muxer
+ *
+ * @internal
+ */
+export declare class PacketAgeWatchdog {
+    private readonly limitMs;
+    private readonly limitSeconds;
+    private readonly describeStream;
+    private queues;
+    private clock;
+    private lastArrival;
+    private header;
+    private headerFill;
+    private skipRemaining;
+    private partialBox;
+    private partialFill;
+    private blind;
+    /**
+     * @param limitSeconds - Maximum age of a pending packet in seconds (> 0)
+     *
+     * @param describeStream - Label for an output stream in the error message (e.g. its media type)
+     *
+     * @internal
+     */
+    constructor(limitSeconds: number, describeStream: (streamIndex: number) => string);
+    /**
+     * Number of packets of a stream that have not been emitted in a fragment yet.
+     *
+     * @param streamIndex - Output stream index
+     *
+     * @returns Pending packet count
+     *
+     * @internal
+     */
+    pendingPackets(streamIndex: number): number;
+    /**
+     * Age of the oldest pending packet of a stream, as the next packet would see it.
+     *
+     * @param streamIndex - Output stream index
+     *
+     * @param now - Current time in ms (performance.now() clock)
+     *
+     * @returns Age in ms of input time, or 0 when nothing is pending
+     *
+     * @internal
+     */
+    pendingAge(streamIndex: number, now?: number): number;
+    /**
+     * Record a packet the muxer accepted.
+     *
+     * Checks every stream first, so a stream that is held back is caught by the
+     * packets of the streams that still flow.
+     *
+     * @param streamIndex - Output stream index
+     *
+     * @throws {Error} If a pending packet of any stream is older than the limit
+     *
+     * @internal
+     */
+    onPacket(streamIndex: number): void;
+    /**
+     * Forget a packet of a stream that the muxer accepted but dropped.
+     *
+     * @param streamIndex - Output stream index
+     *
+     * @internal
+     */
+    onPacketRejected(streamIndex: number): void;
+    /**
+     * Stop judging packet ages for the rest of the session.
+     *
+     * For a caller that frames the output itself and lost the box boundaries:
+     * emitted samples can no longer be counted, and pending packets would
+     * otherwise look stalled. Drops what it has recorded and records nothing
+     * more, so a blind session holds no state.
+     *
+     * @internal
+     */
+    onFramingLost(): void;
+    /**
+     * Account for one complete top-level box of the muxer output.
+     *
+     * Only `moof` (fragment samples) and `moov` (samples of a first fragment
+     * written without `empty_moov`) matter; other boxes are ignored.
+     *
+     * @param box - The whole box including its header
+     *
+     * @internal
+     */
+    consumeBox(box: Buffer): void;
+    /**
+     * Account for a raw chunk of the muxer output.
+     *
+     * Frames top-level boxes across chunk boundaries without buffering media
+     * data: only `moof`/`moov` boxes are collected, everything else is skipped.
+     * If the framing breaks (a size the muxer never writes), the watchdog stops
+     * judging ages for the rest of the session instead of guessing.
+     *
+     * @param chunk - Output chunk in stream order
+     *
+     * @internal
+     */
+    consumeChunk(chunk: Buffer): void;
+    /**
+     * Drain the samples of every track fragment in a moof.
+     *
+     * @param buf - Buffer holding the moof
+     *
+     * @param start - Offset of the moof payload
+     *
+     * @param end - End offset of the moof
+     *
+     * @internal
+     */
+    private drainFragment;
+    /**
+     * Drain the samples of one traf: its tfhd names the track, each trun counts samples.
+     *
+     * movenc writes several truns per traf when the sample data is not contiguous.
+     *
+     * @param buf - Buffer holding the traf
+     *
+     * @param start - Offset of the traf payload
+     *
+     * @param end - End offset of the traf
+     *
+     * @internal
+     */
+    private drainTrackFragment;
+    /**
+     * Drain samples a moov carries in its sample tables.
+     *
+     * With `empty_moov` the tables are empty. Without it movenc writes the first
+     * fragment's samples into the moov instead of a moof.
+     *
+     * @param buf - Buffer holding the moov
+     *
+     * @param start - Offset of the moov payload
+     *
+     * @param end - End offset of the moov
+     *
+     * @internal
+     */
+    private drainInitSegment;
+    /**
+     * Remove emitted samples from the queue of the stream behind a track.
+     *
+     * movenc numbers the tracks of the muxer's streams stream index + 1; tracks
+     * it adds itself (chapters, timecode) have no queue and are ignored.
+     *
+     * @param trackId - mp4 track_ID
+     *
+     * @param samples - Number of emitted samples
+     *
+     * @internal
+     */
+    private drain;
+    /**
+     * Build the error for a stream whose oldest pending packet is too old.
+     *
+     * @param streamIndex - Output stream index
+     *
+     * @param ageMs - Age of its oldest pending packet in ms
+     *
+     * @param pending - Number of its pending packets
+     *
+     * @returns Error describing the stalled stream
+     *
+     * @internal
+     */
+    private violation;
+}