@synapse-sdk/media 0.3.0 → 0.3.3

package/dist/camera.d.ts

@@ -1,12 +1,11 @@
-import type { H264Encoder } from "./encoder.ts";
 /** `MediaStreamTrackProcessor` is available (Chrome 94+). */
 export declare function trackProcessorSupported(): boolean;
 /** The `VideoFrame`s of a video track as a `ReadableStream` (`maxBufferSize` 1: the newest frame wins, older ones are dropped by the browser). */
 export declare function trackFrames(track: MediaStreamTrack): ReadableStream<VideoFrame>;
 /**
- * Pumps a camera track into the encoder until the track ends or `signal` aborts. Resolves with
- * the number of frames offered to the encoder (dropped ones included; see `encoder.stats()`).
+ * Pumps a camera track into `publish` (a video publisher's) until the track ends or `signal`
+ * aborts; each frame is closed after the call. Resolves with the number of frames handed over.
  */
-export declare function pumpTrack(track: MediaStreamTrack, encoder: H264Encoder, opts?: {
+export declare function pumpTrack(track: MediaStreamTrack, publish: (frame: VideoFrame, tUs: number) => void, opts?: {
     signal?: AbortSignal;
 }): Promise<number>;

package/dist/camera.js

@@ -1,7 +1,7 @@
-// Camera frames into the encoder: `MediaStreamTrackProcessor` (Chrome-only, not in TypeScript's
-// DOM lib, so it is reached through `globalThis`) turns a `MediaStreamTrack` into a stream of
-// `VideoFrame`s. Each frame is encoded with `tUs = nowUs()` at dequeue (stamp at capture, as
-// dylithium did) and closed right after.
+// Camera frames into a video publisher: `MediaStreamTrackProcessor` (Chrome-only, not in
+// TypeScript's DOM lib, so it is reached through `globalThis`) turns a `MediaStreamTrack` into a
+// stream of `VideoFrame`s. Each frame is published with `tUs = nowUs()` at dequeue (stamp at
+// capture, as dylithium did) and closed right after.
 import { SynapseError, nowUs } from "@synapse-sdk/core";
 /** `MediaStreamTrackProcessor` is available (Chrome 94+). */
 export function trackProcessorSupported() { return typeof globalThis.MediaStreamTrackProcessor === "function"; }
@@ -13,12 +13,14 @@ export function trackFrames(track) {
     return new Ctor({ track, maxBufferSize: 1 }).readable;
 }
 /**
- * Pumps a camera track into the encoder until the track ends or `signal` aborts. Resolves with
- * the number of frames offered to the encoder (dropped ones included; see `encoder.stats()`).
+ * Pumps a camera track into `publish` (a video publisher's) until the track ends or `signal`
+ * aborts; each frame is closed after the call. Resolves with the number of frames handed over.
  */
-export async function pumpTrack(track, encoder, opts = {}) {
+export async function pumpTrack(track, publish, opts = {}) {
     const reader = trackFrames(track).getReader();
     const onAbort = () => { void reader.cancel(); };
+    if (opts.signal?.aborted)
+        onAbort();
     opts.signal?.addEventListener("abort", onAbort, { once: true });
     let n = 0;
     try {
@@ -27,7 +29,7 @@ export async function pumpTrack(track, encoder, opts = {}) {
             if (done || !value)
                 break;
             try {
-                encoder.encode(value, { tUs: nowUs() });
+                publish(value, nowUs());
                 n++;
             }
             finally {

package/dist/canvas.d.ts

@@ -1,4 +1,3 @@
-import type { VideoSink } from "./decoder.ts";
 export interface CanvasSinkOptions {
     /** Coalesce to the display refresh (drops superseded pictures). Default false: draw immediately. */
     vsync?: boolean;
@@ -12,8 +11,8 @@ export interface CanvasSink {
     readonly dropped: number;
     detach(): void;
 }
-/** Anything with a decoder-style `attachSink` (an `H264Decoder`, or a `VideoSubscriber` through its decoder). */
+/** Anything with a decoder-style `attachSink` that hands over pictures the sink then owns (an `H264Decoder`). */
 export interface VideoSource {
-    attachSink(sink: VideoSink): () => void;
+    attachSink(sink: (vf: VideoFrame) => void): () => void;
 }
 export declare function attachCanvas(source: VideoSource, canvas: HTMLCanvasElement, opts?: CanvasSinkOptions): CanvasSink;

package/dist/decoder.d.ts

@@ -16,7 +16,7 @@ export interface H264DecoderOptions {
     hardwareAcceleration?: HardwareAcceleration;
     /** Sync policy overrides; the defaults are the shared 10/150/60 (`SYNC_DEFAULT`) with `startAtRecovery: false` (see the constructor). */
     sync?: Partial<SyncConfig>;
-    /** The decoder has produced nothing for `stuckFrames` chunks: ask the publisher for an IDR (`VideoSubscriber` wires this to the `<topic>/idr` service). */
+    /** The decoder has produced nothing for `stuckFrames` chunks: ask the publisher for an IDR (`videoSubscriber` wires this to the `<topic>/idr` service). */
     onRequestIdr?: () => void;
     /** Diagnostics (configure, sync, reset, error lines). */
     onLog?: (msg: string) => void;
@@ -41,7 +41,7 @@ export declare class H264Decoder {
     private readonly opts;
     /** The shared sync policy (read `sync.state`, `sync.stats`). */
     readonly sync: DecoderSync;
-    /** Stuck signal; set by the options or later by the owner (`VideoSubscriber` does). */
+    /** Stuck signal; set by the options or later by the owner (`videoSubscriber` does). */
     onRequestIdr: (() => void) | undefined;
     /** Observer of every decoded picture (stats, latency), called before the sink. */
     onOutput: ((meta: DecodedFrameMeta) => void) | undefined;

package/dist/decoder.js

@@ -9,14 +9,14 @@
 // → drop the decoder and wait for the next start point. Frames are handed to one sink as they
 // decode; the sink owns them and must `close()` them (`attachCanvas` does).
 import { nowUs } from "@synapse-sdk/core";
-import { codecStringFromSps } from "./annexb.js";
+import { codecStringFromSps } from "@synapse-sdk/core";
 import { DecoderSync } from "./sync.js";
 import { DEFAULT_H264_CODEC, requireWebCodecs } from "./webcodecs.js";
 export class H264Decoder {
     opts;
     /** The shared sync policy (read `sync.state`, `sync.stats`). */
     sync;
-    /** Stuck signal; set by the options or later by the owner (`VideoSubscriber` does). */
+    /** Stuck signal; set by the options or later by the owner (`videoSubscriber` does). */
     onRequestIdr;
     /** Observer of every decoded picture (stats, latency), called before the sink. */
     onOutput;
@@ -36,7 +36,7 @@ export class H264Decoder {
         requireWebCodecs("H264Decoder");
         // Chromium's VideoDecoder checks that a `key` chunk carries an IDR (Annex-B without `description`):
         // a recovery-point start throws "A key frame is required after configure()", so WebCodecs waits for
-        // an IDR (the owner asks for one through `onRequestIdr`; `VideoSubscriber` does so while waiting).
+        // an IDR (the owner asks for one through `onRequestIdr`; the sync policy raises it while waiting too).
         this.sync = new DecoderSync({ startAtRecovery: false, ...opts.sync });
         this.onRequestIdr = opts.onRequestIdr;
     }

package/dist/encoder.js

@@ -1,15 +1,14 @@
 // 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
+// what a `video/h264` topic 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`
+// frame, on `forceIdr()` (the `<topic>/idr` service `videoPublisher` serves) 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 { auParamSets, auSyncPoints, nowUs } from "@synapse-sdk/core";
 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) {
@@ -136,10 +135,9 @@ export class H264Encoder {
     #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 };
+        // Flags from the bitstream like every Synapse publisher; R27 §4: a key chunk is an IDR (the bitstream says so too).
+        const { idr, recovery } = auSyncPoints(data);
+        const f = { data, tUs: chunk.timestamp, key: idr || chunk.type === "key", config: auParamSets(data) !== undefined, recovery, stages: { encodedUs: nowUs(), sentUs: 0 } };
         const started = this.#inflight.get(chunk.timestamp);
         if (started !== undefined) {
             this.#inflight.delete(chunk.timestamp);

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export * from "./annexb.ts";
+export { AuSplitter, NAL_TYPE, SEI_RECOVERY_POINT, auParamSets, auSyncPoints, codecStringFromSps, concatBytes, findSps, findStartCode, hasVcl, isKeyframe, isVclType, nalIsVcl, nalPayload, nalType, nalUnits, nalWithStartCode, rbspUnescape, seiHasRecoveryPoint, seiPayloadTypes, splitAccessUnits, type Nal, } from "@synapse-sdk/core";
 export * from "./reinsert.ts";
 export * from "./sync.ts";
 export * from "./webcodecs.ts";
@@ -6,6 +6,6 @@ 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 { trackFrames, trackProcessorSupported } from "./camera.ts";
+export type { MediaFrame, Stages } from "@synapse-sdk/core";
 export { isStartPoint, mediaFlags, mediaFrameFromHeader, mediaHeader, stagesOf } from "@synapse-sdk/core";

package/dist/index.js

@@ -1,10 +1,10 @@
-// @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).
+// @synapse-sdk/media: H.264 video over Synapse in the browser.
+// - `videoPublisher(node, topic)` / `videoSubscriber(node, topic)`: pictures in, pictures out.
+// - `H264Encoder` / `H264Decoder`: WebCodecs, for a two-step path of your own (constructors throw `not_supported` without WebCodecs).
 // - `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 Annex-B walkers (flags from the bitstream), `attachCanvas`, camera helpers.
 // The React hook lives in `@synapse-sdk/media/react`.
-export * from "./annexb.js";
+export { AuSplitter, NAL_TYPE, SEI_RECOVERY_POINT, auParamSets, auSyncPoints, codecStringFromSps, concatBytes, findSps, findStartCode, hasVcl, isKeyframe, isVclType, nalIsVcl, nalPayload, nalType, nalUnits, nalWithStartCode, rbspUnescape, seiHasRecoveryPoint, seiPayloadTypes, splitAccessUnits, } from "@synapse-sdk/core";
 export * from "./reinsert.js";
 export * from "./sync.js";
 export * from "./webcodecs.js";
@@ -12,5 +12,5 @@ export * from "./decoder.js";
 export * from "./canvas.js";
 export * from "./encoder.js";
 export * from "./video.js";
-export * from "./camera.js";
+export { trackFrames, trackProcessorSupported } from "./camera.js";
 export { isStartPoint, mediaFlags, mediaFrameFromHeader, mediaHeader, stagesOf } from "@synapse-sdk/core";

package/dist/react.d.ts

@@ -1,24 +1,15 @@
 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 {
+export interface UseVideoOptions extends 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. */
+/** Decodes a video 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

@@ -1,48 +1,52 @@
-// `@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`.
+// `@synapse-sdk/media/react`: `useVideo(topic)` — a canvas ref callback for a video topic, on
+// `videoSubscriber`. The per-frame path (decoder → canvas) never touches React. 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. */
+import { videoSubscriber } from "./video.js";
+/** Decodes a video 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);
+        if (!canvas || !node || topic === "skip")
             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);
+            // The canvas sink owns each picture handed to it (draws, then closes it).
+            let sink;
+            const drawn = attachCanvas({ attachSink: s => { sink = s; return () => { if (sink === s)
+                    sink = undefined; }; } }, canvas, { vsync: o.vsync, resize: o.resize });
+            let video;
+            try {
+                video = videoSubscriber(node, topic);
+            }
+            catch (e) {
+                drawn.detach();
+                throw e;
+            }
+            void (async () => { for await (const vf of video) {
+                if (sink)
+                    sink(vf);
+                else
+                    vf.close();
+            } })();
             setError(undefined);
-            const timer = statsHz > 0 ? setInterval(() => setStats(sub.stats()), 1000 / statsHz) : undefined;
-            return () => { if (timer)
-                clearInterval(timer); sub.close(); sink.detach(); decoder.close(); };
+            return () => { video.close(); drawn.detach(); };
         }
         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 };
+    }, [node, canvas, topicName]);
+    return { ref, error };
 }

package/dist/reinsert.js

@@ -1,4 +1,4 @@
-import { auParamSets, concatBytes } from "./annexb.js";
+import { auParamSets, concatBytes } from "@synapse-sdk/core";
 /** Remembers the most recent SPS+PPS (with start codes) and re-inserts them where a decoder needs them. */
 export class ParamSetCache {
     #paramSets;

package/dist/sync.js

@@ -10,6 +10,8 @@ export class DecoderSync {
     #startedAtRecovery = false;
     #syncChunk = false;
     #fedSinceOutput = 0;
+    /** Frames since the last IDR request (or since the output or start): the stuck rule. */
+    #fedSinceRequest = 0;
     constructor(cfg = {}) { this.cfg = { ...SYNC_DEFAULT, ...cfg }; }
     get state() { return this.#state; }
     get paramSets() { return this.cache.paramSets; }
@@ -36,18 +38,29 @@ export class DecoderSync {
                 this.stats.startsAtRecovery++;
             }
             else {
+                // still waiting: after a stuck window of dropped frames, ask for an IDR
                 this.stats.dropped++;
-                return { feed: undefined, keyChunk: false, started: false, signal: undefined };
+                this.#fedSinceOutput++;
+                this.#fedSinceRequest++;
+                let signal;
+                if (this.#fedSinceRequest >= this.cfg.stuckFrames) {
+                    this.#fedSinceRequest = 0;
+                    this.stats.idrRequests++;
+                    signal = "request_idr";
+                }
+                return { feed: undefined, keyChunk: false, started: false, signal };
             }
             this.#state = "primed";
             this.#syncChunk = true;
             this.#fedSinceOutput = 0;
+            this.#fedSinceRequest = 0;
             this.stats.starts++;
             started = true;
         }
         const keyChunk = frame.key || this.#syncChunk;
         this.#syncChunk = false;
         this.#fedSinceOutput++;
+        this.#fedSinceRequest++;
         this.stats.fed++;
         return { feed: data, keyChunk, started, signal: this.#checkStuck() };
     }
@@ -57,9 +70,9 @@ export class DecoderSync {
             this.#reset();
             return "reset";
         }
-        if (this.#fedSinceOutput >= tolerated) {
-            // Give the IDR a full window before asking again.
-            this.#fedSinceOutput = 0;
+        if (this.#fedSinceRequest >= tolerated) {
+            // Give the IDR a full window before asking again (the wedged count runs on).
+            this.#fedSinceRequest = 0;
             this.#startedAtRecovery = false;
             this.stats.idrRequests++;
             return "request_idr";
@@ -69,6 +82,7 @@ export class DecoderSync {
     /** The decoder produced a frame. */
     onOutput() {
         this.#fedSinceOutput = 0;
+        this.#fedSinceRequest = 0;
         this.#startedAtRecovery = false;
         this.stats.output++;
         if (this.#state === "primed")
@@ -81,6 +95,7 @@ export class DecoderSync {
         this.#syncChunk = false;
         this.#startedAtRecovery = false;
         this.#fedSinceOutput = 0;
+        this.#fedSinceRequest = 0;
         this.stats.resets++;
     }
 }

package/dist/video.d.ts

@@ -1,124 +1,47 @@
-import { type MediaFrame, type MediaLayout, type TopicContract, type TopicRef } from "@synapse-sdk/core";
-import type { Envelope, Publisher, Registration, Subscription, Synapse } from "@synapse-sdk/client";
-import type { H264Decoder } from "./decoder.ts";
-import type { H264Encoder } from "./encoder.ts";
-import type { SyncState } from "./sync.ts";
-export declare const H264 = "video/h264";
-export interface H264TopicOptions {
-    /** RaptorQ repair percentage; default 30 (`repairPct: 0` = source symbols only). */
-    repairPct?: number;
-    /** FEC give-up budget, ms; default 50 (video). */
-    deadlineMs?: number;
-    /** One MoQ group per frame with the relay caching the latest, instead of datagrams (a poster-frame topic, not live video). */
-    retain?: boolean;
-}
-/** A raw topic for H.264 access units: `contentType: "video/h264"`, `layout: {codec: "h264", stream: "annexb", ...}`, datagrams with FEC. */
-export declare function h264Topic(name: string, layout?: Omit<MediaLayout, "codec" | "stream">, opts?: H264TopicOptions): TopicContract<Uint8Array, Uint8Array>;
-/** The IDR-on-demand service a video publisher serves (decision 4): `<topic>/idr`, no arguments, `{ ok: true }`. */
-export declare function idrServiceName(topic: string): string;
-export interface VideoPublisherOptions {
-    /** Serve `<topic>/idr` → `encoder.forceIdr()`; default true. */
-    idrService?: boolean;
-}
-export interface VideoPublisherStats {
-    /** Access units handed to `publishMedia`. */
-    sent: number;
-    /** `<topic>/idr` calls served. */
-    idrCalls: number;
-    /** Frames the SPS/PPS re-insertion policy touched (WebCodecs streams: none, key chunks carry them). */
-    reinserted: number;
+import { type TopicRef } from "@synapse-sdk/core";
+import type { Envelope, Synapse } from "@synapse-sdk/client";
+import { H264Encoder, type H264EncoderOptions } from "./encoder.ts";
+/** `videoPublisher` settings: the `H264Encoder` knobs a caller may want, all with defaults. */
+export type VideoPublisherOptions = Pick<H264EncoderOptions, "fps" | "bitrate" | "hardwareAcceleration">;
+/** Pictures in, `video/h264` out (`videoPublisher`). */
+export interface VideoPublisher {
+    /**
+     * Encodes and publishes `frame`, stamped `tUs` (the capture time, if you have one; default now).
+     * Synchronous; the encoder drops a picture rather than queue behind (see `encoder.stats()`). The
+     * first picture opens the encoder at its size. The frame stays yours to close.
+     */
+    publish(frame: VideoFrame, tUs?: number): void;
+    /** Publishes a camera track's frames until it ends or `signal` aborts (Chrome's `MediaStreamTrackProcessor`); resolves with the frames handed over. */
+    pumpTrack(track: MediaStreamTrack, opts?: {
+        signal?: AbortSignal;
+    }): Promise<number>;
+    /** Ends the topic, the `<topic>/idr` service and the encoder. */
+    close(): void;
+    /** The encoder, once the first picture made it. */
+    readonly encoder: H264Encoder | undefined;
 }
 /**
- * Encoder output → `publisher.publishMedia()`: `t_us` = capture (the `VideoFrame.timestamp`),
- * `STAGES` = encoder stamp + `sentUs` 0 (the publisher stamps it at the write, WP §4.1), SPS/PPS
- * re-insertion at recovery points, plus the `<topic>/idr` service that forces the next frame to be
- * an IDR. `VideoPublisher.open()` resolves once the runtime admitted the topic (and the service).
+ * A video publisher on `topic` (a name, or a `video/h264` topic: datagrams with FEC unless the
+ * contract says otherwise). Resolves once the topic and its `<topic>/idr` service are admitted.
  */
-export declare class VideoPublisher {
-    #private;
-    readonly node: Synapse;
-    readonly topic: TopicContract<Uint8Array, Uint8Array>;
-    readonly publisher: Publisher<Uint8Array>;
-    readonly registration: Registration | undefined;
-    readonly encoder: H264Encoder;
-    private constructor();
-    static open(node: Synapse, topic: TopicRef<Uint8Array, Uint8Array>, encoder: H264Encoder, opts?: VideoPublisherOptions): Promise<VideoPublisher>;
-    stats(): VideoPublisherStats;
-    /** Stops publishing (the encoder stays yours to close). */
+export declare function videoPublisher(node: Synapse, topic: TopicRef<Uint8Array, Uint8Array>, opts?: VideoPublisherOptions): Promise<VideoPublisher>;
+/** Decoded pictures of a `video/h264` topic (`videoSubscriber`): `for await` them (you close each), or get them through `onFrame`. */
+export interface VideoSubscriber extends AsyncIterable<VideoFrame> {
+    /** Stops the subscription and the decoder; pictures not yet read are closed. */
     close(): void;
 }
 export interface VideoSubscriberOptions {
-    /** Call `<topic>/idr` when the decoder is stuck and while it waits for a start point; default true. */
-    requestIdr?: boolean;
-    /** Minimum spacing between IDR requests, ms; default 1000. */
-    idrMinIntervalMs?: number;
-    /** Subscription priority 0..7; default 2. */
-    priority?: number;
-}
-/**
- * Latency split over the last stats window (averages, ms). Undefined when the stamps needed are
- * not there. `e2eMs` and `netMs` cross the publisher's clock and ours: exact when it shares our time
- * domain, otherwise through the broker's clock (`node.toLocalUs`, SDK §4.4) and reported with
- * `epsMs`, the error bound; undefined while the publisher's domain has no offset yet (no judgment).
- */
-export interface VideoLatency {
-    /** Capture → decoded picture, `± epsMs`. */
-    e2eMs: number | undefined;
-    /** Capture → encoder output (`STAGES.encoded_us`; one clock). */
-    encMs: number | undefined;
-    /** Encoder output → transport write (`STAGES.sent_us`; one clock). */
-    sendMs: number | undefined;
-    /** Transport write → our receive, `± epsMs`. */
-    netMs: number | undefined;
-    /** `decode()` → output. */
-    decodeMs: number | undefined;
-    /** Error bound on `e2eMs`/`netMs` from the clock conversion: 0 in our own domain, the two estimates' bounds added across domains, undefined when the clocks are not comparable (then both are undefined too). */
-    epsMs: number | undefined;
-}
-export interface VideoStats {
-    /** Decoded pictures per second over the window. */
-    fps: number;
-    /** Received bit rate over the window. */
-    kbps: number;
-    /** Totals since the subscriber was created. */
-    received: number;
-    decoded: number;
-    /** Frames not decoded: dropped while waiting for a start point, plus frames superseded before they were read. */
-    dropped: number;
-    superseded: number;
-    resets: number;
-    idrRequests: number;
-    /** Decoder queue depth right now. */
-    queue: number;
-    width: number;
-    height: number;
-    state: SyncState;
-    latency: VideoLatency;
-}
-/** A received envelope on a raw media topic as a `MediaFrame` (the header's flags and `STAGES`). */
-export declare function mediaFrameOf(env: Envelope<Uint8Array>): MediaFrame;
-/**
- * A raw subscription feeding an `H264Decoder`. Every envelope becomes a `MediaFrame` and goes to
- * `decoder.push()`; the decoder's stuck signal and the waiting state (a late joiner on an IDR-only
- * stream sees nothing until an IDR comes) both call the publisher's `<topic>/idr` service, at most
- * once per `idrMinIntervalMs`. Stats: fps, totals, and the latency split from `t_us` and `STAGES`.
- */
-export declare class VideoSubscriber {
-    #private;
-    readonly node: Synapse;
-    readonly decoder: H264Decoder;
-    private readonly opts;
-    readonly topic: TopicContract<Uint8Array, Uint8Array>;
-    readonly sub: Subscription<Uint8Array>;
-    constructor(node: Synapse, topic: TopicRef<Uint8Array, Uint8Array>, decoder: H264Decoder, opts?: VideoSubscriberOptions);
-    /** Window averages since the previous call plus totals; resets the window. */
-    stats(): VideoStats;
-    /** IDR calls that failed (no publisher serving `<topic>/idr`, or timed out). */
-    get idrFailed(): number;
     /**
-     * Stops the subscription and gives the decoder back its previous callbacks (the decoder stays
-     * yours to close). Close subscribers sharing one decoder newest first: a subscriber whose
-     * callbacks another one wrapped since cannot take them back, so the newer one still calls them.
+     * Each decoded picture with the envelope of the access unit it came from (`tUs` = capture time,
+     * `key`, `dom`, publisher). The picture is closed when the callback returns; `clone()` it to keep
+     * it. With `onFrame` the subscriber yields nothing.
      */
-    close(): void;
+    onFrame?: (frame: VideoFrame, meta: Envelope<Uint8Array>) => void;
 }
+/**
+ * Decoded pictures of the video topic `topic` (by name; the established descriptor says what it
+ * carries). Every frame is fed to the decoder in order and every picture it gives is delivered.
+ * Frames before a start point are dropped by the decoder's policy, which asks the publisher for an
+ * IDR when stuck or waiting. Throws `not_supported` where WebCodecs is missing.
+ */
+export declare function videoSubscriber(node: Synapse, topic: TopicRef<Uint8Array, Uint8Array>, opts?: VideoSubscriberOptions): VideoSubscriber;