@synapse-sdk/media 0.0.0-stage → 0.3.0

package/dist/encoder.d.ts

@@ -0,0 +1,74 @@
+import { type MediaFrame } from "@synapse-sdk/core";
+export interface H264EncoderOptions {
+    width: number;
+    height: number;
+    /** Frames per second the source will deliver (rate control and level selection); default 30. */
+    fps?: number;
+    /** Target bits per second; default `width × height × fps × 0.15` (about 260 kbps at 320×180@30). */
+    bitrate?: number;
+    /** Codec string; default Baseline (`avc1.4200XX`) with the level chosen from width × height × fps × bitrate (H.264 Table A-1). */
+    codec?: string;
+    /** Default `"no-preference"`. */
+    hardwareAcceleration?: HardwareAcceleration;
+    /** Default `"realtime"`. */
+    latencyMode?: LatencyMode;
+    /** Default `"constant"` (CBR, the dylithium encoder option block). */
+    bitrateMode?: VideoEncoderBitrateMode;
+    /** Force a key frame every N encoded frames; 0 (default) = only the first frame, `forceIdr()` and the IDR service. */
+    keyframeInterval?: number;
+    /** Captured frames are dropped, not queued, while the encoder holds this many (default 2): drop captured, never encoded. */
+    maxQueue?: number;
+    onError?: (e: unknown) => void;
+    onLog?: (msg: string) => void;
+}
+export interface H264EncoderStats {
+    /** Access units produced. */
+    encoded: number;
+    keyframes: number;
+    /** Captured frames dropped because the encoder was behind (`maxQueue`). */
+    dropped: number;
+    /** `encode()` throws and encoder `error` callbacks. */
+    errors: number;
+    /** Encoder queue depth right now. */
+    queue: number;
+    /** Bits per second in force. */
+    bitrate: number;
+    /** Smoothed `encode()`-to-chunk time, ms. */
+    encodeMs: number;
+    /** Encoded bytes produced. */
+    bytes: number;
+    codec: string;
+}
+/** Receives encoded access units (`stages.encodedUs` stamped, `stages.sentUs` 0 until the publisher writes). */
+export type MediaSink = (frame: MediaFrame) => void;
+/** Lowest H.264 level (level_idc) whose Table A-1 limits cover the picture rate, frame size and Baseline bitrate. */
+export declare function h264LevelIdc(width: number, height: number, fps: number, bitrateBps: number): number;
+export declare class H264Encoder {
+    #private;
+    private readonly opts;
+    readonly cfg: VideoEncoderConfig;
+    constructor(opts: H264EncoderOptions);
+    /** Whether WebCodecs can encode this configuration here (Annex-B, realtime). */
+    static isSupported(opts: Pick<H264EncoderOptions, "width" | "height" | "fps" | "bitrate" | "codec" | "hardwareAcceleration">): Promise<boolean>;
+    /** Adds a consumer of encoded access units; returns a detach function. */
+    attachSink(sink: MediaSink): () => void;
+    /**
+     * Encodes one picture: a `VideoFrame` (camera, `MediaStreamTrackProcessor`) or any
+     * `CanvasImageSource` (a canvas, video element, image bitmap). `tUs` is the capture time in the
+     * node clock (default `nowUs()` now) and rides through `VideoFrame.timestamp` to the chunk, so
+     * the published `t_us` is the capture stamp. The caller keeps ownership of a `VideoFrame` source
+     * (close it afterwards). Returns `false` when the frame was dropped (encoder behind, or closed).
+     */
+    encode(source: VideoFrame | CanvasImageSource, opts?: {
+        tUs?: number;
+        keyFrame?: boolean;
+    }): boolean;
+    /** The next encoded frame is an IDR (the `<topic>/idr` service calls this). */
+    forceIdr(): void;
+    /** Changes the target bitrate (reconfigures; the next frame is an IDR so the new rate starts clean). */
+    setBitrate(bps: number): void;
+    /** Waits for every queued frame to come out. */
+    flush(): Promise<void>;
+    stats(): H264EncoderStats;
+    close(): void;
+}

package/dist/encoder.js

@@ -0,0 +1,173 @@
+// WebCodecs H.264 encoder for a live stream (R27 §4; dylithium had no browser encoder).
+//
+// `avc: { format: "annexb" }` puts SPS/PPS in-band on every key chunk, so the bytes are exactly
+// what `MediaFrame.data` carries (no avcC, no repackaging) and the flags are read off the
+// bitstream like every other Synapse publisher. `latencyMode: "realtime"`, `bitrateMode:
+// "constant"`, `hardwareAcceleration: "no-preference"` (Chrome picks; software OpenH264 in
+// headless Chromium). WebCodecs has no GOP and no intra-refresh: keyframes happen on the first
+// frame, on `forceIdr()` (the `<topic>/idr` service) and optionally every `keyframeInterval`
+// frames; a receiver's policy for a browser publisher is therefore IDR-only, which is fine.
+// Captured frames are dropped when the encoder queue is behind, encoded ones never (lessons register).
+import { nowUs } from "@synapse-sdk/core";
+import { mediaFrameFromAnnexb } from "./annexb.js";
+import { requireWebCodecs } from "./webcodecs.js";
+/** Lowest H.264 level (level_idc) whose Table A-1 limits cover the picture rate, frame size and Baseline bitrate. */
+export function h264LevelIdc(width, height, fps, bitrateBps) {
+    const mbs = Math.ceil(width / 16) * Math.ceil(height / 16);
+    const mbps = mbs * fps;
+    const kbps = bitrateBps / 1000;
+    // [level_idc, MaxMBPS, MaxFS, MaxBR (kbit/s, Baseline/Main)]
+    const table = [
+        [0x0a, 1485, 99, 64], [0x0b, 3000, 396, 192], [0x0c, 6000, 396, 384], [0x0d, 11880, 396, 768], [0x14, 11880, 396, 2000],
+        [0x15, 19800, 792, 4000], [0x16, 20250, 1620, 4000], [0x1e, 40500, 1620, 10000], [0x1f, 108000, 3600, 14000], [0x20, 216000, 5120, 20000],
+        [0x28, 245760, 8192, 20000], [0x29, 245760, 8192, 50000], [0x2a, 522240, 8704, 50000], [0x32, 589824, 22080, 135000], [0x33, 983040, 36864, 240000], [0x34, 2073600, 36864, 240000],
+    ];
+    for (const [idc, maxMbps, maxFs, maxBr] of table)
+        if (mbps <= maxMbps && mbs <= maxFs && kbps <= maxBr)
+            return idc;
+    return 0x34;
+}
+export class H264Encoder {
+    opts;
+    cfg;
+    #enc;
+    #sinks = new Set();
+    #forceKey = true;
+    #sinceKey = 0;
+    #inflight = new Map();
+    #encodeMs = 0;
+    #stats = { encoded: 0, keyframes: 0, dropped: 0, errors: 0, bytes: 0 };
+    #closed = false;
+    constructor(opts) {
+        this.opts = opts;
+        requireWebCodecs("H264Encoder");
+        const fps = opts.fps ?? 30;
+        const bitrate = opts.bitrate ?? Math.round(opts.width * opts.height * fps * 0.15);
+        const codec = opts.codec ?? `avc1.4200${h264LevelIdc(opts.width, opts.height, fps, bitrate).toString(16).padStart(2, "0")}`;
+        this.cfg = {
+            codec, width: opts.width, height: opts.height, framerate: fps, bitrate,
+            bitrateMode: opts.bitrateMode ?? "constant", latencyMode: opts.latencyMode ?? "realtime", hardwareAcceleration: opts.hardwareAcceleration ?? "no-preference",
+            avc: { format: "annexb" },
+        };
+        this.#enc = new VideoEncoder({ output: (chunk, meta) => this.#onChunk(chunk, meta), error: e => { this.#stats.errors++; this.#log(`encoder error: ${e.message}`); this.opts.onError?.(e); } });
+        this.#enc.configure(this.cfg);
+        this.#log(`encoder configured: ${codec} ${opts.width}x${opts.height}@${fps} ${bitrate} bps`);
+    }
+    /** Whether WebCodecs can encode this configuration here (Annex-B, realtime). */
+    static async isSupported(opts) {
+        if (typeof VideoEncoder !== "function")
+            return false;
+        const fps = opts.fps ?? 30;
+        const bitrate = opts.bitrate ?? Math.round(opts.width * opts.height * fps * 0.15);
+        const codec = opts.codec ?? `avc1.4200${h264LevelIdc(opts.width, opts.height, fps, bitrate).toString(16).padStart(2, "0")}`;
+        try {
+            const r = await VideoEncoder.isConfigSupported({ codec, width: opts.width, height: opts.height, framerate: fps, bitrate, latencyMode: "realtime", hardwareAcceleration: opts.hardwareAcceleration ?? "no-preference", avc: { format: "annexb" } });
+            return r.supported === true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Adds a consumer of encoded access units; returns a detach function. */
+    attachSink(sink) { this.#sinks.add(sink); return () => { this.#sinks.delete(sink); }; }
+    /**
+     * Encodes one picture: a `VideoFrame` (camera, `MediaStreamTrackProcessor`) or any
+     * `CanvasImageSource` (a canvas, video element, image bitmap). `tUs` is the capture time in the
+     * node clock (default `nowUs()` now) and rides through `VideoFrame.timestamp` to the chunk, so
+     * the published `t_us` is the capture stamp. The caller keeps ownership of a `VideoFrame` source
+     * (close it afterwards). Returns `false` when the frame was dropped (encoder behind, or closed).
+     */
+    encode(source, opts = {}) {
+        if (this.#closed)
+            return false;
+        if (this.#enc.encodeQueueSize >= (this.opts.maxQueue ?? 2)) {
+            this.#stats.dropped++;
+            return false;
+        }
+        const tUs = Math.round(opts.tUs ?? nowUs());
+        const interval = this.opts.keyframeInterval ?? 0;
+        const key = this.#forceKey || opts.keyFrame === true || (interval > 0 && this.#sinceKey >= interval);
+        let vf;
+        try {
+            vf = new VideoFrame(source, { timestamp: tUs });
+        }
+        catch (e) {
+            this.#stats.errors++;
+            this.opts.onError?.(e);
+            return false;
+        }
+        try {
+            this.#enc.encode(vf, { keyFrame: key });
+        }
+        catch (e) {
+            this.#stats.errors++;
+            this.#log(`encode() threw: ${e instanceof Error ? e.message : String(e)}`);
+            this.opts.onError?.(e);
+            return false;
+        }
+        finally {
+            vf.close();
+        }
+        this.#inflight.set(tUs, performance.now());
+        this.#forceKey = false;
+        this.#sinceKey = key ? 1 : this.#sinceKey + 1;
+        return true;
+    }
+    /** The next encoded frame is an IDR (the `<topic>/idr` service calls this). */
+    forceIdr() { this.#forceKey = true; }
+    /** Changes the target bitrate (reconfigures; the next frame is an IDR so the new rate starts clean). */
+    setBitrate(bps) {
+        if (this.#closed || bps <= 0)
+            return;
+        this.cfg.bitrate = Math.round(bps);
+        try {
+            this.#enc.configure(this.cfg);
+            this.#forceKey = true;
+            this.#log(`bitrate → ${Math.round(bps)} bps`);
+        }
+        catch (e) {
+            this.#stats.errors++;
+            this.opts.onError?.(e);
+        }
+    }
+    /** Waits for every queued frame to come out. */
+    async flush() { if (!this.#closed && this.#enc.state === "configured")
+        await this.#enc.flush(); }
+    #onChunk(chunk, _meta) {
+        const data = new Uint8Array(chunk.byteLength);
+        chunk.copyTo(data);
+        const f = mediaFrameFromAnnexb(data, chunk.timestamp);
+        if (chunk.type === "key")
+            f.key = true; // R27 §4: a key chunk is an IDR (the bitstream says so too)
+        f.stages = { encodedUs: nowUs(), sentUs: 0 };
+        const started = this.#inflight.get(chunk.timestamp);
+        if (started !== undefined) {
+            this.#inflight.delete(chunk.timestamp);
+            const ms = performance.now() - started;
+            this.#encodeMs = this.#encodeMs === 0 ? ms : this.#encodeMs * 0.9 + ms * 0.1;
+        }
+        this.#stats.encoded++;
+        if (f.key) {
+            this.#stats.keyframes++;
+            this.#sinceKey = Math.min(this.#sinceKey, 1);
+        }
+        this.#stats.bytes += data.length;
+        for (const s of this.#sinks)
+            s(f);
+    }
+    stats() {
+        return { ...this.#stats, queue: this.#closed ? 0 : this.#enc.encodeQueueSize, bitrate: this.cfg.bitrate ?? 0, encodeMs: this.#encodeMs, codec: this.cfg.codec };
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        try {
+            this.#enc.close();
+        }
+        catch { /* already closed */ }
+        this.#sinks.clear();
+        this.#inflight.clear();
+    }
+    #log(msg) { this.opts.onLog?.(msg); }
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./annexb.ts";
+export * from "./reinsert.ts";
+export * from "./sync.ts";
+export * from "./webcodecs.ts";
+export * from "./decoder.ts";
+export * from "./canvas.ts";
+export * from "./encoder.ts";
+export * from "./video.ts";
+export * from "./camera.ts";
+export type { MediaFrame, MediaLayout, Stages } from "@synapse-sdk/core";
+export { isStartPoint, mediaFlags, mediaFrameFromHeader, mediaHeader, stagesOf } from "@synapse-sdk/core";

package/dist/index.js

@@ -0,0 +1,16 @@
+// @synapse-sdk/media: H.264 over Synapse in the browser (stage plan J1/J2).
+// - `annexb`: the Annex-B walkers shared with `crates/synapse-media` (flags from the bitstream).
+// - `ParamSetCache` / `DecoderSync`: the publisher re-insertion and decoder sync policies, identical in every SDK.
+// - `H264Decoder` / `H264Encoder`: WebCodecs (browser only; constructors throw `not_supported` elsewhere).
+// - `attachCanvas`, `VideoPublisher`, `VideoSubscriber`, `h264Topic`, camera helpers.
+// The React hook lives in `@synapse-sdk/media/react`.
+export * from "./annexb.js";
+export * from "./reinsert.js";
+export * from "./sync.js";
+export * from "./webcodecs.js";
+export * from "./decoder.js";
+export * from "./canvas.js";
+export * from "./encoder.js";
+export * from "./video.js";
+export * from "./camera.js";
+export { isStartPoint, mediaFlags, mediaFrameFromHeader, mediaHeader, stagesOf } from "@synapse-sdk/core";

package/dist/react.d.ts

@@ -0,0 +1,24 @@
+import type { Synapse, TopicRef } from "@synapse-sdk/client";
+import { type SynapseError } from "@synapse-sdk/core";
+import { type CanvasSinkOptions } from "./canvas.ts";
+import { type H264DecoderOptions } from "./decoder.ts";
+import { VideoSubscriber, type VideoStats, type VideoSubscriberOptions } from "./video.ts";
+export interface UseVideoOptions extends VideoSubscriberOptions, CanvasSinkOptions {
+    /** The node to use instead of the one from `<SynapseProvider>`. */
+    node?: Synapse;
+    decoder?: H264DecoderOptions;
+    /** Stats re-render rate; default 2 Hz; 0 disables. */
+    statsHz?: number;
+}
+export interface UseVideoResult {
+    /** Put this on the `<canvas>`: `<canvas ref={ref} />`. */
+    ref: (el: HTMLCanvasElement | null) => void;
+    /** Last stats snapshot, undefined until the first tick. */
+    stats: VideoStats | undefined;
+    /** `not_supported` when WebCodecs is missing, or whatever failed while setting up. */
+    error: SynapseError | undefined;
+    /** The live subscriber (undefined while there is no canvas or the topic is `"skip"`). */
+    subscriber: VideoSubscriber | undefined;
+}
+/** Decodes an H.264 topic into a canvas. `topic` may be `"skip"` to render nothing without subscribing. */
+export declare function useVideo(topic: TopicRef<Uint8Array, Uint8Array> | "skip", opts?: UseVideoOptions): UseVideoResult;

package/dist/react.js

@@ -0,0 +1,48 @@
+// `@synapse-sdk/media/react`: `useVideo(topic)` — a canvas ref callback plus live stats. The
+// per-frame path (decoder → canvas) never touches React; only the stats snapshot re-renders, at
+// `statsHz` (default 2). Needs a `<SynapseProvider>` (from `@synapse-sdk/react`) or `opts.node`.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { toSynapseError } from "@synapse-sdk/core";
+import { useSynapseOptional } from "@synapse-sdk/react";
+import { attachCanvas } from "./canvas.js";
+import { H264Decoder } from "./decoder.js";
+import { VideoSubscriber } from "./video.js";
+/** Decodes an H.264 topic into a canvas. `topic` may be `"skip"` to render nothing without subscribing. */
+export function useVideo(topic, opts = {}) {
+    const ctxNode = useSynapseOptional();
+    const node = opts.node ?? ctxNode;
+    const [canvas, setCanvas] = useState(null);
+    const [stats, setStats] = useState(undefined);
+    const [error, setError] = useState(undefined);
+    const [subscriber, setSubscriber] = useState(undefined);
+    const optsRef = useRef(opts);
+    optsRef.current = opts;
+    const ref = useCallback((el) => setCanvas(el), []);
+    const topicName = topic === "skip" ? undefined : typeof topic === "string" ? topic : topic.name;
+    const statsHz = opts.statsHz ?? 2;
+    useEffect(() => {
+        if (!canvas || !node || topic === "skip") {
+            setSubscriber(undefined);
+            setStats(undefined);
+            return;
+        }
+        const o = optsRef.current;
+        let decoder, sub;
+        try {
+            decoder = new H264Decoder(o.decoder);
+            const sink = attachCanvas(decoder, canvas, { vsync: o.vsync, resize: o.resize });
+            sub = new VideoSubscriber(node, topic, decoder, o);
+            setSubscriber(sub);
+            setError(undefined);
+            const timer = statsHz > 0 ? setInterval(() => setStats(sub.stats()), 1000 / statsHz) : undefined;
+            return () => { if (timer)
+                clearInterval(timer); sub.close(); sink.detach(); decoder.close(); };
+        }
+        catch (e) {
+            setError(toSynapseError(e, "not_supported", "sdk"));
+            return;
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [node, canvas, topicName, statsHz]);
+    return { ref, stats, error, subscriber };
+}

package/dist/reinsert.d.ts

@@ -0,0 +1,24 @@
+import type { MediaFrame } from "@synapse-sdk/core";
+/** Remembers the most recent SPS+PPS (with start codes) and re-inserts them where a decoder needs them. */
+export declare class ParamSetCache {
+    #private;
+    /** Frames the publisher policy re-inserted into (diagnostics). */
+    reinserted: number;
+    /** The cached SPS+PPS bytes, if any were seen. */
+    get paramSets(): Uint8Array | undefined;
+    get isPrimed(): boolean;
+    /** Looks at an AU: caches its parameter sets when it carries some. Returns `true` if it did. */
+    observe(au: Uint8Array): boolean;
+    /**
+     * Publisher policy on an outgoing frame: cache parameter sets when present; when absent on a
+     * recovery point (or when `force`), prepend the cached ones and set `config`. Frames that need
+     * nothing pass through unchanged (no copy).
+     */
+    prepare(frame: MediaFrame, force?: boolean): MediaFrame;
+    /**
+     * Receiver side: the AU with parameter sets in front when it lacks them and the cache has some
+     * (`undefined` if neither is available, i.e. the AU cannot start a decoder on its own). Caches
+     * the AU's own parameter sets first, so the newest ones always win.
+     */
+    prime(au: Uint8Array): Uint8Array | undefined;
+}

package/dist/reinsert.js

@@ -0,0 +1,41 @@
+import { auParamSets, concatBytes } from "./annexb.js";
+/** Remembers the most recent SPS+PPS (with start codes) and re-inserts them where a decoder needs them. */
+export class ParamSetCache {
+    #paramSets;
+    /** Frames the publisher policy re-inserted into (diagnostics). */
+    reinserted = 0;
+    /** The cached SPS+PPS bytes, if any were seen. */
+    get paramSets() { return this.#paramSets; }
+    get isPrimed() { return this.#paramSets !== undefined; }
+    /** Looks at an AU: caches its parameter sets when it carries some. Returns `true` if it did. */
+    observe(au) {
+        const ps = auParamSets(au);
+        if (!ps)
+            return false;
+        this.#paramSets = ps;
+        return true;
+    }
+    /**
+     * Publisher policy on an outgoing frame: cache parameter sets when present; when absent on a
+     * recovery point (or when `force`), prepend the cached ones and set `config`. Frames that need
+     * nothing pass through unchanged (no copy).
+     */
+    prepare(frame, force = false) {
+        if (this.observe(frame.data))
+            return frame.config ? frame : { ...frame, config: true };
+        if (!(frame.recovery || force) || !this.#paramSets)
+            return frame;
+        this.reinserted++;
+        return { ...frame, data: concatBytes([this.#paramSets, frame.data]), config: true };
+    }
+    /**
+     * Receiver side: the AU with parameter sets in front when it lacks them and the cache has some
+     * (`undefined` if neither is available, i.e. the AU cannot start a decoder on its own). Caches
+     * the AU's own parameter sets first, so the newest ones always win.
+     */
+    prime(au) {
+        if (this.observe(au))
+            return au;
+        return this.#paramSets ? concatBytes([this.#paramSets, au]) : undefined;
+    }
+}

package/dist/sync.d.ts

@@ -0,0 +1,60 @@
+import type { MediaFrame } from "@synapse-sdk/core";
+import { ParamSetCache } from "./reinsert.ts";
+export interface SyncConfig {
+    /** Frames fed without output before an IDR is requested (about a third of a second at 30 fps). */
+    stuckFrames: number;
+    /** Frames fed without output before the decoder is dropped outright. */
+    wedgedFrames: number;
+    /** Silence tolerated after a start at a recovery point (a refresh period plus slack). */
+    recoverySilenceFrames: number;
+    /**
+     * A recovery point with parameter sets is a start point (default true, the Rust/libav rule).
+     * `false` for decoders that can only start on an IDR: WebCodecs in Chromium verifies that a
+     * chunk labelled `key` carries an IDR and rejects the recovery-point start (`H264Decoder` sets this).
+     */
+    startAtRecovery: boolean;
+}
+/** `synapse_media::SyncConfig::default()`. */
+export declare const SYNC_DEFAULT: Readonly<SyncConfig>;
+/** `waiting`: no start point yet, frames are dropped. `primed`: started, nothing decoded yet. `streaming`: output seen since the start. */
+export type SyncState = "waiting" | "primed" | "streaming";
+/** What the owner should do about the decoder after a frame: ask the publisher for an IDR, or drop the decoder (the machine is back in `waiting`). */
+export type SyncSignal = "request_idr" | "reset";
+/** The verdict on one pushed frame. */
+export interface SyncDecision {
+    /** Bytes to hand to the decoder (parameter sets prepended when needed), or `undefined` = dropped. */
+    feed: Uint8Array | undefined;
+    /** Label the chunk `key` for the decoder (an IDR, or the first chunk after a start). */
+    keyChunk: boolean;
+    /** The decoder was just (re)started with this frame: (re)configure it first. */
+    started: boolean;
+    signal: SyncSignal | undefined;
+}
+export interface SyncStats {
+    frames: number;
+    dropped: number;
+    fed: number;
+    output: number;
+    starts: number;
+    startsAtRecovery: number;
+    resets: number;
+    idrRequests: number;
+}
+export declare class DecoderSync {
+    #private;
+    readonly cfg: SyncConfig;
+    readonly stats: SyncStats;
+    /** The SPS/PPS cache (primed from every AU that carries them, even while waiting). */
+    readonly cache: ParamSetCache;
+    constructor(cfg?: Partial<SyncConfig>);
+    get state(): SyncState;
+    get paramSets(): Uint8Array | undefined;
+    /** Frames fed since the decoder last produced output. */
+    get fedSinceOutput(): number;
+    /** A received media frame. Decides whether to feed it and how to label it, and raises the stuck/wedged signals. */
+    push(frame: MediaFrame): SyncDecision;
+    /** The decoder produced a frame. */
+    onOutput(): void;
+    /** The decoder reported an error: drop it and wait for the next start point. */
+    onError(): void;
+}

package/dist/sync.js

@@ -0,0 +1,86 @@
+import { ParamSetCache } from "./reinsert.js";
+/** `synapse_media::SyncConfig::default()`. */
+export const SYNC_DEFAULT = { stuckFrames: 10, wedgedFrames: 150, recoverySilenceFrames: 60, startAtRecovery: true };
+export class DecoderSync {
+    cfg;
+    stats = { frames: 0, dropped: 0, fed: 0, output: 0, starts: 0, startsAtRecovery: 0, resets: 0, idrRequests: 0 };
+    /** The SPS/PPS cache (primed from every AU that carries them, even while waiting). */
+    cache = new ParamSetCache();
+    #state = "waiting";
+    #startedAtRecovery = false;
+    #syncChunk = false;
+    #fedSinceOutput = 0;
+    constructor(cfg = {}) { this.cfg = { ...SYNC_DEFAULT, ...cfg }; }
+    get state() { return this.#state; }
+    get paramSets() { return this.cache.paramSets; }
+    /** Frames fed since the decoder last produced output. */
+    get fedSinceOutput() { return this.#fedSinceOutput; }
+    /** A received media frame. Decides whether to feed it and how to label it, and raises the stuck/wedged signals. */
+    push(frame) {
+        this.stats.frames++;
+        let started = false;
+        // Parameter sets are cached from every frame, synced or not (the cache primes later starts).
+        const inBand = this.cache.observe(frame.data);
+        let data = frame.data;
+        if (this.#state === "waiting") {
+            if (frame.key) {
+                this.#startedAtRecovery = false;
+            }
+            else if (this.cfg.startAtRecovery && frame.recovery && (inBand || this.cache.isPrimed)) {
+                if (!inBand) {
+                    const primed = this.cache.prime(frame.data);
+                    if (primed)
+                        data = primed;
+                }
+                this.#startedAtRecovery = true;
+                this.stats.startsAtRecovery++;
+            }
+            else {
+                this.stats.dropped++;
+                return { feed: undefined, keyChunk: false, started: false, signal: undefined };
+            }
+            this.#state = "primed";
+            this.#syncChunk = true;
+            this.#fedSinceOutput = 0;
+            this.stats.starts++;
+            started = true;
+        }
+        const keyChunk = frame.key || this.#syncChunk;
+        this.#syncChunk = false;
+        this.#fedSinceOutput++;
+        this.stats.fed++;
+        return { feed: data, keyChunk, started, signal: this.#checkStuck() };
+    }
+    #checkStuck() {
+        const tolerated = this.#startedAtRecovery ? this.cfg.recoverySilenceFrames : this.cfg.stuckFrames;
+        if (this.#fedSinceOutput >= this.cfg.wedgedFrames) {
+            this.#reset();
+            return "reset";
+        }
+        if (this.#fedSinceOutput >= tolerated) {
+            // Give the IDR a full window before asking again.
+            this.#fedSinceOutput = 0;
+            this.#startedAtRecovery = false;
+            this.stats.idrRequests++;
+            return "request_idr";
+        }
+        return undefined;
+    }
+    /** The decoder produced a frame. */
+    onOutput() {
+        this.#fedSinceOutput = 0;
+        this.#startedAtRecovery = false;
+        this.stats.output++;
+        if (this.#state === "primed")
+            this.#state = "streaming";
+    }
+    /** The decoder reported an error: drop it and wait for the next start point. */
+    onError() { this.#reset(); }
+    #reset() {
+        this.#state = "waiting";
+        this.#syncChunk = false;
+        this.#startedAtRecovery = false;
+        this.#fedSinceOutput = 0;
+        this.stats.resets++;
+    }
+}