@camstack/addon-pipeline 1.2.284 → 1.2.285

package/dist/stream-broker/index.mjs

@@ -1,10 +1,10 @@
 import { r as __toESM } from "../chunk-DnnnRqeS.mjs";
-import { $t as CAM_PROFILE_ORDER, B as cameraStreamsCapability, Bt as streamBrokerCapability, Cn as number, D as RATE_CONTROL_RELAXED, Dn as string, Dt as rankStreams, En as record, F as addonWidgetsSourceCapability, G as declareLogChannel, Gt as errMsg, Jt as buildFfmpegArgs$1, Kt as AUDIO_PRESETS, M as RingBuffer, Nt as resolveEgressDecodeHwAccel, O as RATE_CONTROL_TIGHT, On as union, Q as egressTransportFromRequest, Qt as BaseAddon, Sn as literal, U as createHwAccelCache, W as createLogChannelsProvider, Wt as webrtcSessionCapability, Xt as isSoftwareDecode, Yt as invocationFromEncodeProfile, Z as egressTranscodeSharingKey, Zt as BOOT_RECOVERY_BACKOFF_MS, _ as EncodeProfileSchema, _n as _enum, b as G711_SCALE_CORRECTION_DB, bn as discriminatedUnion, dn as makeSourceBrokerId, dt as logChannelsCapability, en as CamProfileSchema, fn as nodePin, i as BatteryStatusSchema, in as createEvent, kn as EventCategory, ln as isEvent, mn as parseProfileBrokerId, nn as DeviceType, pt as maskUrlCredentials, q as deriveBatteryPresence, sn as expandAudioChunkToF32le, tn as DeviceFeature, un as makeProfileBrokerId, ut as loadContributionCapability, vn as array, wn as object, yn as boolean, z as batteryCapability } from "../dist-CWJ_t5jq.mjs";
-import { i as NO_COST_CLAIM, n as Fmp4FragmentChild, o as probeFfmpegBinary, r as Fmp4FragmentPlane, t as ChildCostRegistry } from "../node-Cz6ByejK.mjs";
+import { $t as isSoftwareDecode, A as RATE_CONTROL_RELAXED, An as string, At as rankStreams, C as G711_SCALE_CORRECTION_DB, Cn as discriminatedUnion, Dn as object, En as number, F as RingBuffer, G as clipExportFailureOf, H as batteryCapability, It as resolveEgressDecodeHwAccel, J as declareLogChannel, Jt as errMsg, K as createHwAccelCache, Mn as EventCategory, Qt as invocationFromEncodeProfile, R as addonWidgetsSourceCapability, Sn as boolean, Tn as literal, U as cameraStreamsCapability, Ut as streamBrokerCapability, X as deriveBatteryPresence, Yt as AUDIO_PRESETS, Zt as buildFfmpegArgs$1, _n as parseProfileBrokerId, an as DeviceType, b as EncodeProfileSchema, bn as _enum, en as BOOT_RECOVERY_BACKOFF_MS, et as egressTranscodeSharingKey, fn as isEvent, gt as maskUrlCredentials, hn as nodePin, i as BatteryStatusSchema, in as DeviceFeature, j as RATE_CONTROL_TIGHT, jn as union, kn as record, mn as makeSourceBrokerId, mt as logChannelsCapability, nn as CAM_PROFILE_ORDER, pn as makeProfileBrokerId, pt as loadContributionCapability, q as createLogChannelsProvider, qt as webrtcSessionCapability, rn as CamProfileSchema, sn as createEvent, tn as BaseAddon, tt as egressTransportFromRequest, un as expandAudioChunkToF32le, xn as array } from "../dist-L6fspiMs.mjs";
+import { i as NO_COST_CLAIM, n as Fmp4FragmentChild, o as probeFfmpegBinary, r as Fmp4FragmentPlane, t as ChildCostRegistry } from "../node-BKSzm60G.mjs";
 import { a as parseRestreamPath, d as PREBUFFER_MAX_MS, f as capPreRollRequestMs, i as isLiveEdgeOnlyDial, m as resolvePrebuffer, n as NO_DECLARATION, p as prebufferRetentionMs, s as sdpVariantFor, u as withSentryIntent } from "../restream-intent-DyGmLAU9.mjs";
 import { n as profileForStreamId } from "../remote-restream-BeHi78PZ.mjs";
 import { n as RowMapStore, t as retireRootKeys } from "../retire-root-keys-DZvlso2l.mjs";
-import { i as require_mp4box_all, n as demuxSegmentPreferJs, r as runFfmpegOnce, t as demuxSegmentFullJs } from "../segment-demux-js-gLuKs5Mg.mjs";
+import { a as avccSampleToAnnexB, i as require_mp4box_all, n as demuxSegmentPreferJs, o as buildKeyframeAnnexB, r as runFfmpegOnce, s as parseNalLengthSize, t as demuxSegmentFullJs } from "../segment-demux-js-DIMPKsLl.mjs";
 import { createRequire } from "node:module";
 import * as os from "node:os";
 import { networkInterfaces, tmpdir } from "node:os";
@@ -24,6 +24,7 @@ import { createSocket } from "node:dgram";
 import { once } from "events";
 import { Socket } from "net";
 import { lookup } from "node:dns/promises";
+import { request } from "node:http";
 import { Worker } from "node:worker_threads";
 import { EventEmitter } from "node:events";
 //#region src/stream-broker/client-log-ingest.ts
@@ -26686,6 +26687,21 @@ var ServerMessageSchema = discriminatedUnion("t", [
 		t: literal("clipDuration"),
 		clipId: string().min(1),
 		durationMs: number().positive()
+	}),
+	object({
+		t: literal("clipAudio"),
+		clipId: string().min(1),
+		carried: boolean(),
+		codec: _enum(["opus", "pcmu"]).optional(),
+		/** Why there is no sound. Present iff `carried` is false. */
+		reason: _enum([
+			"not-negotiated",
+			"not-offered",
+			"no-audio-track",
+			"unsupported-codec",
+			"codec-mismatch",
+			"stream-failed"
+		]).optional()
 	})
 ]);
 function parseControlMessage(raw) {
@@ -27263,7 +27279,7 @@ var SEGMENT_TIMEOUT_MS = 8e3;
 * 2 ms, p95 202 ms, max 285 ms), so a segment that CAN yield audio still does.
 */
 var AUDIO_DEMUX_TIMEOUT_MS = 1500;
-var POSITION_INTERVAL_MS = 1e3;
+var POSITION_INTERVAL_MS$1 = 1e3;
 /** How often `recorded:play-census` fires while the advance loop is alive. */
 var PLAY_CENSUS_INTERVAL_TICKS = 5;
 /**
@@ -27285,7 +27301,7 @@ var PTS_REPAIR_LOG_MEMORY = 64;
 * PTS gap (or an empty/tail wait) still re-checks the abort guards promptly,
 * keeping seeks responsive without per-frame drift.
 */
-var WAIT_TICK_MS = 250;
+var WAIT_TICK_MS$1 = 250;
 /**
 * Output-clock gap stamped at every seek/scrub commit (markDiscontinuity on
 * both A/V clocks). Root cause of the "smeared frame on scrub": the aborted
@@ -27298,7 +27314,7 @@ var WAIT_TICK_MS = 250;
 * can't look contiguous with the new GOP, and the receiver resets timing
 * instead of merging the two feeds.
 */
-var SEEK_DISCONTINUITY_MS = 250;
+var SEEK_DISCONTINUITY_MS$1 = 250;
 /**
 * Coalescing window for feeder-scrub `scrubTo` (experimental). Pointer-move
 * targets arrive far faster than a segment demux completes; the feeder collapses
@@ -27884,8 +27900,8 @@ var RecordedFeeder = class {
 		try {
 			this.emitState("loading", "seek-start", token, dragId);
 			if (this.clockHasAdvanced) {
-				this.clock.markDiscontinuity(SEEK_DISCONTINUITY_MS);
-				this.audioClock.markDiscontinuity(SEEK_DISCONTINUITY_MS);
+				this.clock.markDiscontinuity(SEEK_DISCONTINUITY_MS$1);
+				this.audioClock.markDiscontinuity(SEEK_DISCONTINUITY_MS$1);
 			}
 			const locateStartedAt = performance.now();
 			let loc = await this.withTimeout(this.deps.locate({
@@ -28760,12 +28776,12 @@ var RecordedFeeder = class {
 				return;
 			}
 			for (const s of jumpTravel) {
-				if (this.clockHasAdvanced) this.clock.markDiscontinuity(SEEK_DISCONTINUITY_MS);
+				if (this.clockHasAdvanced) this.clock.markDiscontinuity(SEEK_DISCONTINUITY_MS$1);
 				this.deps.sink.pushAccessUnit(s.au.data, this.clock.stamp(s.au.ptsMs), s.au.codec);
 				this.clockHasAdvanced = true;
 				this.deps.onPosition(this.clampIntoSegment(s.seg, s.tMs));
 			}
-			if ((mode === "jump" || rewind) && this.clockHasAdvanced) this.clock.markDiscontinuity(SEEK_DISCONTINUITY_MS);
+			if ((mode === "jump" || rewind) && this.clockHasAdvanced) this.clock.markDiscontinuity(SEEK_DISCONTINUITY_MS$1);
 			else if (crossesFragment && this.clockHasAdvanced) this.clock.markSeek();
 			for (const au of aus) this.deps.sink.pushAccessUnit(au.data, this.clock.stamp(au.ptsMs), au.codec);
 			const pushedAtMs = performance.now();
@@ -29189,7 +29205,7 @@ var RecordedFeeder = class {
 			if (still === "deadline") break;
 			if (still !== null && still.seg.startMs !== lastFragStartMs && !fragmentCovers(still.seg, toMs) && !fragmentCovers(still.seg, fromMs)) {
 				lastFragStartMs = still.seg.startMs;
-				if (this.clockHasAdvanced) this.clock.markDiscontinuity(SEEK_DISCONTINUITY_MS);
+				if (this.clockHasAdvanced) this.clock.markDiscontinuity(SEEK_DISCONTINUITY_MS$1);
 				this.deps.sink.pushAccessUnit(still.au.data, this.clock.stamp(still.au.ptsMs), still.au.codec);
 				this.clockHasAdvanced = true;
 				this.deps.onPosition(this.clampIntoSegment(still.seg, tMs));
@@ -29636,7 +29652,7 @@ var RecordedFeeder = class {
 			if (this.disposed || gen !== this.advanceToken || this.rate === 0) return true;
 			const remaining = targetWall - performance.now();
 			if (remaining <= 0) return false;
-			const tick = Math.min(remaining, WAIT_TICK_MS);
+			const tick = Math.min(remaining, WAIT_TICK_MS$1);
 			await new Promise((resolve) => setTimeout(resolve, tick));
 		}
 	}
@@ -29761,7 +29777,7 @@ var RecordedFeeder = class {
 			if (this.rate <= 0) return;
 			this.positionTicks += 1;
 			if (this.positionTicks % PLAY_CENSUS_INTERVAL_TICKS === 0) this.emitPlayCensus("tick");
-		}, POSITION_INTERVAL_MS);
+		}, POSITION_INTERVAL_MS$1);
 	}
 	/** Tear down the ~1 Hz position interval so it stops reporting a stale cursor. */
 	stopPositionReports() {
@@ -30057,7 +30073,60 @@ var TimelineSession = class {
 		this.lastPositionMs = null;
 		const feeder = this.enterRecorded();
 		await feeder.seek(offsetMs);
-		await this.reportClipDuration(clipId, feeder);
+		await Promise.all([this.reportClipDuration(clipId, feeder), this.reportClipAudio(clipId, feeder)]);
+	}
+	/**
+	* Tell the viewer whether this clip has sound.
+	*
+	* Silence has three causes the operator cannot tell apart by listening —
+	* a camera with no microphone, a transport that carried no audio, and a
+	* session that negotiated none — so the viewer is told which. Every branch
+	* that sends nothing says so (D391): a feeder that cannot answer, an answer
+	* that rejected, and an answer that landed after the pointer had left the
+	* clip, which must not be pinned on whatever came next.
+	*/
+	async reportClipAudio(clipId, feeder) {
+		if (feeder.audio === void 0) {
+			this.deps.onLog?.("clip playback: audio not reported — this feeder cannot say", {
+				deviceId: this.deps.deviceId,
+				clipId
+			});
+			return;
+		}
+		let report;
+		try {
+			report = await feeder.audio();
+		} catch (err) {
+			this.deps.onLog?.("clip playback: audio not reported — the answer failed", {
+				deviceId: this.deps.deviceId,
+				clipId,
+				error: err instanceof Error ? err.message : String(err)
+			});
+			return;
+		}
+		if (this.clip?.clipId !== clipId) {
+			this.deps.onLog?.("clip playback: audio dropped — the pointer has left this clip", {
+				deviceId: this.deps.deviceId,
+				clipId,
+				carried: report.carried
+			});
+			return;
+		}
+		this.deps.onLog?.("clip playback: audio reported", {
+			deviceId: this.deps.deviceId,
+			clipId,
+			carried: report.carried,
+			codec: report.codec,
+			reason: report.reason,
+			detail: report.detail
+		});
+		this.deps.session.sendControl(serializeServerMessage({
+			t: "clipAudio",
+			clipId,
+			carried: report.carried,
+			...report.codec !== null ? { codec: report.codec } : {},
+			...report.reason !== null ? { reason: report.reason } : {}
+		}));
 	}
 	/**
 	* Tell the viewer how long the file on the pointer REALLY is.
@@ -30100,6 +30169,13 @@ var TimelineSession = class {
 			});
 			return;
 		}
+		if (durationMs === null) {
+			this.deps.onLog?.("clip playback: duration unknown — the source ended without a length", {
+				deviceId: this.deps.deviceId,
+				clipId
+			});
+			return;
+		}
 		if (!(durationMs > 0)) {
 			this.deps.onLog?.("clip playback: duration not reported — the measure is not positive", {
 				deviceId: this.deps.deviceId,
@@ -30298,7 +30374,7 @@ var LARGE_SIZE_HEADER_LENGTH = 16;
 * structurally impossible (a size that does not fit), which the caller turns
 * into `malformed` — never a throw, because these bytes come off a camera.
 */
-function childBoxes(bytes, start, end) {
+function childBoxes$1(bytes, start, end) {
 	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
 	const out = [];
 	let off = start;
@@ -30328,7 +30404,7 @@ function childBoxes(bytes, start, end) {
 	}
 	return out;
 }
-function findBox(boxes, type) {
+function findBox$1(boxes, type) {
 	for (const b of boxes) if (b.type === type) return b;
 	return null;
 }
@@ -30358,7 +30434,7 @@ function readSyncSampleNumbers(bytes, box) {
 	for (let i = 0; i < entries; i++) out.add(view.getUint32(base + 4 + i * 4));
 	return out;
 }
-function mediaTimescale(bytes, mdhd) {
+function mediaTimescale$1(bytes, mdhd) {
 	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
 	const version = bytes[mdhd.contentStart] ?? 0;
 	const at = mdhd.contentStart + 4 + (version === 1 ? 16 : 8);
@@ -30366,7 +30442,7 @@ function mediaTimescale(bytes, mdhd) {
 	const ts = view.getUint32(at);
 	return ts > 0 ? ts : null;
 }
-function handlerType(bytes, hdlr) {
+function handlerType$1(bytes, hdlr) {
 	const at = hdlr.contentStart + 8;
 	if (at + FOURCC_LENGTH > hdlr.end) return "";
 	let out = "";
@@ -30375,16 +30451,16 @@ function handlerType(bytes, hdlr) {
 }
 /** The video `trak` of a `moov`, or `null` when it has none. */
 function videoTrack(bytes, moov) {
-	const children = childBoxes(bytes, moov.contentStart, moov.end);
+	const children = childBoxes$1(bytes, moov.contentStart, moov.end);
 	if (!children) return null;
 	for (const trak of children) {
 		if (trak.type !== "trak") continue;
-		const trakKids = childBoxes(bytes, trak.contentStart, trak.end);
-		const mdia = trakKids ? findBox(trakKids, "mdia") : null;
+		const trakKids = childBoxes$1(bytes, trak.contentStart, trak.end);
+		const mdia = trakKids ? findBox$1(trakKids, "mdia") : null;
 		if (!mdia) continue;
-		const mdiaKids = childBoxes(bytes, mdia.contentStart, mdia.end);
-		const hdlr = mdiaKids ? findBox(mdiaKids, "hdlr") : null;
-		if (hdlr && handlerType(bytes, hdlr) === "vide") return mdia;
+		const mdiaKids = childBoxes$1(bytes, mdia.contentStart, mdia.end);
+		const hdlr = mdiaKids ? findBox$1(mdiaKids, "hdlr") : null;
+		if (hdlr && handlerType$1(bytes, hdlr) === "vide") return mdia;
 	}
 	return null;
 }
@@ -30393,12 +30469,12 @@ function videoTrack(bytes, moov) {
 * comes back as a named refusal so the caller can say WHY a clip will not play.
 */
 function indexClipMp4(bytes) {
-	const top = childBoxes(bytes, 0, bytes.length);
+	const top = childBoxes$1(bytes, 0, bytes.length);
 	if (!top) return {
 		kind: "refused",
 		reason: "malformed"
 	};
-	const moov = findBox(top, "moov");
+	const moov = findBox$1(top, "moov");
 	if (!moov) return {
 		kind: "refused",
 		reason: "no-moov"
@@ -30408,34 +30484,34 @@ function indexClipMp4(bytes) {
 		kind: "refused",
 		reason: "no-video-track"
 	};
-	const mdiaKids = childBoxes(bytes, mdia.contentStart, mdia.end);
+	const mdiaKids = childBoxes$1(bytes, mdia.contentStart, mdia.end);
 	if (!mdiaKids) return {
 		kind: "refused",
 		reason: "malformed"
 	};
-	const mdhd = findBox(mdiaKids, "mdhd");
-	const minf = findBox(mdiaKids, "minf");
+	const mdhd = findBox$1(mdiaKids, "mdhd");
+	const minf = findBox$1(mdiaKids, "minf");
 	if (!mdhd || !minf) return {
 		kind: "refused",
 		reason: "malformed"
 	};
-	const timescale = mediaTimescale(bytes, mdhd);
+	const timescale = mediaTimescale$1(bytes, mdhd);
 	if (timescale === null) return {
 		kind: "refused",
 		reason: "malformed"
 	};
-	const minfKids = childBoxes(bytes, minf.contentStart, minf.end);
-	const stbl = minfKids ? findBox(minfKids, "stbl") : null;
+	const minfKids = childBoxes$1(bytes, minf.contentStart, minf.end);
+	const stbl = minfKids ? findBox$1(minfKids, "stbl") : null;
 	if (!stbl) return {
 		kind: "refused",
 		reason: "no-samples"
 	};
-	const stblKids = childBoxes(bytes, stbl.contentStart, stbl.end);
+	const stblKids = childBoxes$1(bytes, stbl.contentStart, stbl.end);
 	if (!stblKids) return {
 		kind: "refused",
 		reason: "malformed"
 	};
-	const sttsBox = findBox(stblKids, "stts");
+	const sttsBox = findBox$1(stblKids, "stts");
 	if (!sttsBox) return {
 		kind: "refused",
 		reason: "no-samples"
@@ -30445,7 +30521,7 @@ function indexClipMp4(bytes) {
 		kind: "refused",
 		reason: "malformed"
 	};
-	const stssBox = findBox(stblKids, "stss");
+	const stssBox = findBox$1(stblKids, "stss");
 	const syncNumbers = stssBox === null ? null : readSyncSampleNumbers(bytes, stssBox);
 	if (stssBox !== null && syncNumbers === null) return {
 		kind: "refused",
@@ -30493,6 +30569,13 @@ var ClipSourceError = class extends Error {
 		this.name = "ClipSourceError";
 	}
 };
+/**
+* 64 MB. Above `VIDEOCLIPS_MAX_READ_BYTES` (50 MB) on purpose: the cap's own
+* bound refuses first and by name, and this one exists so a provider that ever
+* answers larger cannot pin a broker runner's heap. A `high` twin measured
+* 20–35 MB (D570 § 9.6).
+*/
+var CLIP_SOURCE_MAX_BYTES = 64 * 1024 * 1024;
 function createClipFileSource(deps) {
 	const maxBytes = deps.maxBytes ?? 67108864;
 	const { deviceId, clipId, provider, profile } = deps.handle;
@@ -30586,6 +30669,1817 @@ function createClipFileSource(deps) {
 	};
 }
 //#endregion
+//#region src/stream-broker/recorded/clip-path-choice.ts
+function chooseClipPath(input) {
+	if (input.streamDialWired) return {
+		path: "stream",
+		reason: "stream-serves-every-profile"
+	};
+	if (input.fileReadWired) return {
+		path: "file",
+		reason: "no-stream-dial-wired"
+	};
+	return {
+		path: "none",
+		reason: "nothing-wired"
+	};
+}
+/**
+* The feeder a `none` choice gets: every verb is a named refusal and the
+* first seek reports `error`, so a clip nothing can serve is never a frozen
+* frame with no line behind it (D391).
+*/
+function createRefusedClipFeeder(deps) {
+	const data = {
+		deviceId: deps.handle.deviceId,
+		clipId: deps.handle.clipId,
+		reason: deps.reason
+	};
+	let announced = false;
+	const refuse = (verb) => {
+		deps.onLog?.("clip playback: refused — no path can serve this clip", {
+			...data,
+			verb
+		});
+		if (announced) return;
+		announced = true;
+		deps.onState({
+			from: null,
+			to: "error",
+			reason: `refused:${deps.reason}`,
+			seekToken: 0
+		});
+	};
+	return {
+		seek: async () => refuse("seek"),
+		setRate: () => {},
+		stepFrame: () => refuse("stepFrame"),
+		beginScrub: () => refuse("beginScrub"),
+		scrubTo: () => {},
+		scrubAck: () => {},
+		durationMs: () => Promise.resolve(null),
+		dispose: () => {}
+	};
+}
+var PCMU_RATE_HZ = 8e3;
+function createPassthroughFramer() {
+	return {
+		push: (unit) => unit.data.byteLength === 0 ? [] : [{
+			data: unit.data,
+			ptsMs: unit.ptsMs,
+			durationMs: unit.durationMs
+		}],
+		carriedBytes: 0,
+		reanchors: 0
+	};
+}
+var PcmuFramer = class {
+	carry = new Uint8Array(0);
+	/** `ptsMs` of the first byte currently held in {@link carry}. */
+	anchorMs = null;
+	/** Bytes emitted plus carried since {@link anchorMs} — the exact clock. */
+	bytesSinceAnchor = 0;
+	reanchorCount = 0;
+	get carriedBytes() {
+		return this.carry.byteLength;
+	}
+	get reanchors() {
+		return this.reanchorCount;
+	}
+	push(unit) {
+		if (unit.data.byteLength === 0) return [];
+		const expectedMs = this.anchorMs === null ? null : this.anchorMs + this.bytesSinceAnchor * 1e3 / PCMU_RATE_HZ;
+		if (expectedMs === null || Math.abs(expectedMs - unit.ptsMs) > 20) {
+			if (expectedMs !== null) this.reanchorCount += 1;
+			this.carry = new Uint8Array(0);
+			this.anchorMs = unit.ptsMs;
+			this.bytesSinceAnchor = 0;
+		}
+		const anchorMs = this.anchorMs;
+		if (anchorMs === null) return [];
+		const joined = new Uint8Array(this.carry.byteLength + unit.data.byteLength);
+		joined.set(this.carry, 0);
+		joined.set(unit.data, this.carry.byteLength);
+		const out = [];
+		let at = 0;
+		while (at + 160 <= joined.byteLength) {
+			out.push({
+				data: joined.slice(at, at + 160),
+				ptsMs: anchorMs + this.bytesSinceAnchor * 1e3 / PCMU_RATE_HZ,
+				durationMs: 20
+			});
+			this.bytesSinceAnchor += 160;
+			at += 160;
+		}
+		this.carry = joined.slice(at);
+		return out;
+	}
+};
+/** The framer for a codec: a pass-through for Opus, a re-cut for µ-law. */
+function createClipAudioFramer(codec) {
+	return codec === "opus" ? createPassthroughFramer() : new PcmuFramer();
+}
+//#endregion
+//#region src/stream-broker/recorded/fmp4-stream-demux.ts
+/**
+* fmp4-stream-demux — an INCREMENTAL demux of a fragmented MP4 as it arrives.
+*
+* The clip STREAM (`/clip-stream/…`, D597) is an fMP4 written by ffmpeg with
+* `frag_keyframe+empty_moov+default_base_moof` while it is still reading the
+* camera: a `moov` with an EMPTY sample table, then one `moof`+`mdat` per
+* GOP, and no trailer until the end. Nothing in this directory can read that
+* shape as it flows — `clip-mp4-index.ts` wants `stbl` and refuses it
+* `no-samples` by design, `segment-demux-js.ts` (mp4box) wants a WHOLE
+* fragment in hand — so this module walks the boxes itself, byte by byte, and
+* emits every video sample the moment its bytes are in.
+*
+* ## What it emits and when
+*
+* {@link AccessUnit}s, in DECODE order, `ptsMs` anchored at 0 on the first
+* sample's composition time — the same contract `demuxSegmentFullJs` keeps,
+* so a streamed clip and a stored one push the same shape. A sample is
+* emitted as soon as ITS bytes have arrived, not when its `mdat` closes: a
+* GOP is a second or two of video, and a feeder that waited for the box would
+* hand the viewer that second late for nothing.
+*
+* Sync samples are fused with the parameter sets (`avcc-annexb.ts`), delta
+* samples are converted plain; the codec and the `avcC`/`hvcC` come from the
+* `moov`. ONE video track is followed, and — since D600 — ONE audio track
+* beside it; every other track's bytes in an `mdat` are skipped, never
+* emitted.
+*
+* ## The audio track, and the one clock both tracks are on
+*
+* A clip stream carries sound already transcoded to the session's codec
+* (D600): Opus, whose mp4 sample IS the RTP payload, or µ-law in a QuickTime
+* `ulaw` entry. Audio samples are handed to {@link Fmp4StreamDemuxOptions.onAudio}
+* as they land, interleaved with the video in FILE-OFFSET order — which is
+* the order the bytes arrive, and the only order a forward-only window can
+* drain in.
+*
+* **Both tracks are anchored on ONE origin**, the first sample of either to
+* be emitted, and every `ptsMs` is measured from it in exact integer
+* arithmetic over the two timescales. Anchoring each track on its own first
+* sample would zero out the offset BETWEEN them — which is the whole content
+* of lip sync — and would do it invisibly, in a way that only shows up as
+* drift on a long clip.
+*
+* An audio track whose sample entry is neither Opus nor µ-law is REPORTED
+* ({@link Fmp4StreamDemuxer.audio}) and not followed. It is never a refusal:
+* a codec this process cannot forward is a reason to play the clip silent,
+* never a reason to lose the video.
+*
+* ## What it refuses, by name
+*
+* A `moof` before any `moov` (`no-moov`), a `moov` with no video track
+* (`no-video-track`), a codec that is neither AVC nor HEVC
+* (`unsupported-codec`), and a box or a sample that cannot fit where it says
+* it is (`malformed`). Each is thrown ONCE as {@link Fmp4DemuxError}; the
+* demuxer is dead after it and says so on every further push. The bytes come
+* off a camera through two processes — a refusal here is a fact about the
+* stream, never a crash.
+*
+* ## Duration
+*
+* Unknown until the stream ENDS. `end()` answers the sum of the sample
+* durations, in ms, or `null` when no sample was ever emitted — never `0`
+* (D393). The caller learns the length when the camera has finished, which
+* is the truth about a forward-only source.
+*/
+var Fmp4DemuxError = class extends Error {
+	reason;
+	constructor(reason, message) {
+		super(message);
+		this.reason = reason;
+		this.name = "Fmp4DemuxError";
+	}
+};
+var BOX_HEADER = 8;
+var LARGE_BOX_HEADER = 16;
+var FULLBOX = 4;
+/** `sample_is_non_sync_sample`, ISO/IEC 14496-12 § 8.8.3.1. */
+var FLAG_NON_SYNC = 65536;
+var TFHD_BASE_DATA_OFFSET = 1;
+var TFHD_SAMPLE_DESC_INDEX = 2;
+var TFHD_DEFAULT_DURATION = 8;
+var TFHD_DEFAULT_SIZE = 16;
+var TFHD_DEFAULT_FLAGS = 32;
+var TFHD_DEFAULT_BASE_IS_MOOF = 131072;
+var TRUN_DATA_OFFSET = 1;
+var TRUN_FIRST_SAMPLE_FLAGS = 4;
+var TRUN_SAMPLE_DURATION = 256;
+var TRUN_SAMPLE_SIZE = 512;
+var TRUN_SAMPLE_FLAGS = 1024;
+var TRUN_SAMPLE_CTS = 2048;
+/** VisualSampleEntry fields between the sample-entry header and its children. */
+var VISUAL_SAMPLE_ENTRY_FIELDS = 78;
+/**
+* AudioSampleEntry fixed fields, ISO/IEC 14496-12 § 12.2.3: the 8-byte
+* `SampleEntry` (6 reserved + `data_reference_index`), then version, revision,
+* vendor, `channelcount`, `samplesize`, `compression_id`, `packet_size` and a
+* 16.16 `samplerate`.
+*/
+var AUDIO_SAMPLE_ENTRY_FIELDS = 28;
+var AUDIO_ENTRY_CHANNELS_AT = 16;
+var AUDIO_ENTRY_SAMPLE_RATE_AT = 24;
+/** `cts` in `timescale` ticks, as milliseconds from `origin`. Exact. */
+function ptsMsFrom(origin, cts, timescale) {
+	if (timescale === origin.timescale) return Math.round((cts - origin.ticks) * 1e3 / timescale);
+	const numerator = (cts * origin.timescale - origin.ticks * timescale) * 1e3;
+	return Math.round(numerator / (timescale * origin.timescale));
+}
+function fourcc(bytes, at) {
+	let out = "";
+	for (let i = 0; i < 4; i++) out += String.fromCharCode(bytes[at + i] ?? 0);
+	return out;
+}
+function u32(view, at) {
+	return view.getUint32(at);
+}
+function u64(view, at) {
+	return view.getUint32(at) * 4294967296 + view.getUint32(at + 4);
+}
+/** The direct children of `[start, end)`, or `null` when a size does not fit. */
+function childBoxes(bytes, start, end) {
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const out = [];
+	let off = start;
+	while (off + BOX_HEADER <= end) {
+		const declared = u32(view, off);
+		const type = fourcc(bytes, off + 4);
+		let size = declared;
+		let contentStart = off + BOX_HEADER;
+		if (declared === 1) {
+			if (off + LARGE_BOX_HEADER > end) return null;
+			size = u64(view, off + 8);
+			contentStart = off + LARGE_BOX_HEADER;
+		} else if (declared === 0) size = end - off;
+		if (size < contentStart - off) return null;
+		const boxEnd = off + size;
+		if (boxEnd > end) return null;
+		out.push({
+			type,
+			start: off,
+			end: boxEnd,
+			contentStart
+		});
+		off = boxEnd;
+	}
+	return out;
+}
+function findBox(boxes, type) {
+	if (boxes === null) return null;
+	for (const b of boxes) if (b.type === type) return b;
+	return null;
+}
+function handlerType(bytes, hdlr) {
+	const at = hdlr.contentStart + FULLBOX + 4;
+	return at + 4 <= hdlr.end ? fourcc(bytes, at) : "";
+}
+function trackId(bytes, tkhd) {
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const version = bytes[tkhd.contentStart] ?? 0;
+	const at = tkhd.contentStart + FULLBOX + (version === 1 ? 16 : 8);
+	return at + 4 <= tkhd.end ? u32(view, at) : null;
+}
+function mediaTimescale(bytes, mdhd) {
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const version = bytes[mdhd.contentStart] ?? 0;
+	const at = mdhd.contentStart + FULLBOX + (version === 1 ? 16 : 8);
+	if (at + 4 > mdhd.end) return null;
+	const ts = u32(view, at);
+	return ts > 0 ? ts : null;
+}
+/** The decoder config out of `stsd`, header stripped, with the codec it names. */
+function sampleDescription(bytes, stsd) {
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const countAt = stsd.contentStart + FULLBOX;
+	if (countAt + 4 > stsd.end) return null;
+	const count = u32(view, countAt);
+	const entries = childBoxes(bytes, countAt + 4, stsd.end);
+	if (entries === null || count === 0 || entries.length === 0) return null;
+	for (const entry of entries) {
+		const isAvc = entry.type === "avc1" || entry.type === "avc3";
+		const isHevc = entry.type === "hvc1" || entry.type === "hev1";
+		if (!isAvc && !isHevc) continue;
+		const config = findBox(childBoxes(bytes, entry.contentStart + VISUAL_SAMPLE_ENTRY_FIELDS, entry.end), isAvc ? "avcC" : "hvcC");
+		if (config === null) return null;
+		return {
+			codec: isAvc ? "H264" : "H265",
+			description: bytes.subarray(config.contentStart, config.end)
+		};
+	}
+	return "unsupported";
+}
+function audioSampleDescription(bytes, stsd) {
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const countAt = stsd.contentStart + FULLBOX;
+	if (countAt + 4 > stsd.end) return null;
+	const entry = childBoxes(bytes, countAt + 4, stsd.end)?.[0];
+	if (entry === void 0) return null;
+	if (entry.contentStart + AUDIO_SAMPLE_ENTRY_FIELDS > entry.end) return null;
+	const codec = entry.type === "Opus" ? "opus" : entry.type === "ulaw" ? "pcmu" : null;
+	if (codec === null) return { unsupported: entry.type };
+	return {
+		codec,
+		channels: view.getUint16(entry.contentStart + AUDIO_ENTRY_CHANNELS_AT),
+		sampleRateHz: view.getUint16(entry.contentStart + AUDIO_ENTRY_SAMPLE_RATE_AT)
+	};
+}
+function readTrex(bytes, moov, id) {
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const mvex = findBox(childBoxes(bytes, moov.contentStart, moov.end), "mvex");
+	const none = {
+		duration: null,
+		size: null,
+		flags: null
+	};
+	if (mvex === null) return none;
+	for (const trex of childBoxes(bytes, mvex.contentStart, mvex.end) ?? []) {
+		if (trex.type !== "trex" || trex.contentStart + FULLBOX + 20 > trex.end) continue;
+		const at = trex.contentStart + FULLBOX;
+		if (u32(view, at) !== id) continue;
+		return {
+			duration: u32(view, at + 8),
+			size: u32(view, at + 12),
+			flags: u32(view, at + 16)
+		};
+	}
+	return none;
+}
+/** The `trak`s of a `moov` whose handler is `want`, already unpacked. */
+function traksOfHandler(bytes, moov, want) {
+	const kids = childBoxes(bytes, moov.contentStart, moov.end);
+	if (kids === null) return "malformed";
+	const out = [];
+	for (const trak of kids) {
+		if (trak.type !== "trak") continue;
+		const trakKids = childBoxes(bytes, trak.contentStart, trak.end);
+		const mdia = findBox(trakKids, "mdia");
+		const tkhd = findBox(trakKids, "tkhd");
+		if (mdia === null || tkhd === null) continue;
+		const mdiaKids = childBoxes(bytes, mdia.contentStart, mdia.end);
+		const hdlr = findBox(mdiaKids, "hdlr");
+		if (hdlr === null || handlerType(bytes, hdlr) !== want) continue;
+		const id = trackId(bytes, tkhd);
+		const mdhd = findBox(mdiaKids, "mdhd");
+		const minf = findBox(mdiaKids, "minf");
+		if (id === null || mdhd === null || minf === null) return "malformed";
+		const timescale = mediaTimescale(bytes, mdhd);
+		const stbl = findBox(childBoxes(bytes, minf.contentStart, minf.end), "stbl");
+		const stsd = findBox(stbl ? childBoxes(bytes, stbl.contentStart, stbl.end) : null, "stsd");
+		if (timescale === null || stsd === null) return "malformed";
+		out.push({
+			id,
+			timescale,
+			stsd
+		});
+	}
+	return out;
+}
+/** The one video track of a `moov`, or the refusal that stands in for it. */
+function readVideoTrack(bytes, moov) {
+	const traks = traksOfHandler(bytes, moov, "vide");
+	if (traks === "malformed") return "malformed";
+	for (const trak of traks) {
+		const desc = sampleDescription(bytes, trak.stsd);
+		if (desc === null) return "malformed";
+		if (desc === "unsupported") return "unsupported-codec";
+		let nalLengthSize;
+		try {
+			nalLengthSize = parseNalLengthSize(desc.description, desc.codec === "H265");
+		} catch {
+			return "malformed";
+		}
+		return {
+			id: trak.id,
+			timescale: trak.timescale,
+			codec: desc.codec,
+			description: desc.description,
+			nalLengthSize,
+			trex: readTrex(bytes, moov, trak.id)
+		};
+	}
+	return "no-video-track";
+}
+/**
+* The one audio track of a `moov`, or what to REPORT instead of one.
+*
+* Never a refusal: sound this process cannot forward is a silent clip, and a
+* silent clip is a clip. The only thing that must not happen is silence
+* nobody can account for, which is what {@link Fmp4AudioState} is for.
+*/
+function readAudioTrack$1(bytes, moov) {
+	const traks = traksOfHandler(bytes, moov, "soun");
+	if (traks === "malformed") return { kind: "absent" };
+	for (const trak of traks) {
+		const desc = audioSampleDescription(bytes, trak.stsd);
+		if (desc === null) return {
+			kind: "unsupported",
+			sampleEntry: ""
+		};
+		if ("unsupported" in desc) return {
+			kind: "unsupported",
+			sampleEntry: desc.unsupported
+		};
+		return {
+			id: trak.id,
+			timescale: trak.timescale,
+			codec: desc.codec,
+			sampleRateHz: desc.sampleRateHz,
+			channels: desc.channels,
+			trex: readTrex(bytes, moov, trak.id)
+		};
+	}
+	return { kind: "absent" };
+}
+function readTfhd(view, tfhd) {
+	const flags = u32(view, tfhd.contentStart) & 16777215;
+	let at = tfhd.contentStart + FULLBOX;
+	if (at + 4 > tfhd.end) return null;
+	const id = u32(view, at);
+	at += 4;
+	let baseDataOffset = null;
+	if (flags & TFHD_BASE_DATA_OFFSET) {
+		if (at + 8 > tfhd.end) return null;
+		baseDataOffset = u64(view, at);
+		at += 8;
+	}
+	if (flags & TFHD_SAMPLE_DESC_INDEX) at += 4;
+	let duration = null;
+	let size = null;
+	let sampleFlags = null;
+	if (flags & TFHD_DEFAULT_DURATION) {
+		if (at + 4 > tfhd.end) return null;
+		duration = u32(view, at);
+		at += 4;
+	}
+	if (flags & TFHD_DEFAULT_SIZE) {
+		if (at + 4 > tfhd.end) return null;
+		size = u32(view, at);
+		at += 4;
+	}
+	if (flags & TFHD_DEFAULT_FLAGS) {
+		if (at + 4 > tfhd.end) return null;
+		sampleFlags = u32(view, at);
+	}
+	return {
+		trackId: id,
+		baseDataOffset,
+		defaultBaseIsMoof: (flags & TFHD_DEFAULT_BASE_IS_MOOF) !== 0,
+		defaults: {
+			duration,
+			size,
+			flags: sampleFlags
+		}
+	};
+}
+function readTfdt(view, bytes, tfdt) {
+	const version = bytes[tfdt.contentStart] ?? 0;
+	const at = tfdt.contentStart + FULLBOX;
+	if (version === 1) return at + 8 <= tfdt.end ? u64(view, at) : null;
+	return at + 4 <= tfdt.end ? u32(view, at) : null;
+}
+/** The samples one `trun` announces, or `null` when it does not fit. */
+function readTrun(args) {
+	const { view, trun, base, trex, traf } = args;
+	const version = view.getUint8(trun.contentStart);
+	const flags = u32(view, trun.contentStart) & 16777215;
+	let at = trun.contentStart + FULLBOX;
+	if (at + 4 > trun.end) return null;
+	const count = u32(view, at);
+	at += 4;
+	let dataOffset = 0;
+	if (flags & TRUN_DATA_OFFSET) {
+		if (at + 4 > trun.end) return null;
+		dataOffset = view.getInt32(at);
+		at += 4;
+	}
+	let firstSampleFlags = null;
+	if (flags & TRUN_FIRST_SAMPLE_FLAGS) {
+		if (at + 4 > trun.end) return null;
+		firstSampleFlags = u32(view, at);
+		at += 4;
+	}
+	const out = [];
+	let offset = base + dataOffset;
+	let dts = args.startDts;
+	for (let i = 0; i < count; i++) {
+		let duration = traf.defaults.duration ?? trex.duration;
+		let size = traf.defaults.size ?? trex.size;
+		let sampleFlags = traf.defaults.flags ?? trex.flags;
+		let ctsOffset = 0;
+		if (flags & TRUN_SAMPLE_DURATION) {
+			if (at + 4 > trun.end) return null;
+			duration = u32(view, at);
+			at += 4;
+		}
+		if (flags & TRUN_SAMPLE_SIZE) {
+			if (at + 4 > trun.end) return null;
+			size = u32(view, at);
+			at += 4;
+		}
+		if (flags & TRUN_SAMPLE_FLAGS) {
+			if (at + 4 > trun.end) return null;
+			sampleFlags = u32(view, at);
+			at += 4;
+		} else if (i === 0 && firstSampleFlags !== null) sampleFlags = firstSampleFlags;
+		if (flags & TRUN_SAMPLE_CTS) {
+			if (at + 4 > trun.end) return null;
+			ctsOffset = version === 0 ? u32(view, at) : view.getInt32(at);
+			at += 4;
+		}
+		if (duration === null || size === null) return null;
+		const sync = sampleFlags === null ? i === 0 : (sampleFlags & FLAG_NON_SYNC) === 0;
+		out.push({
+			offset,
+			size,
+			dts,
+			cts: dts + ctsOffset,
+			duration,
+			sync
+		});
+		offset += size;
+		dts += duration;
+	}
+	return out;
+}
+/**
+* Every sample a `moof` announces for the followed tracks, in FILE-OFFSET
+* order, or `null`.
+*
+* Offset order, not decode order across tracks: the window is forward-only
+* and drains what has arrived, so two tracks whose runs are laid out one
+* after another inside one `mdat` — which is how ffmpeg writes them — must
+* be drained in the order their bytes land. Within one track the offsets are
+* increasing anyway, so each track's own decode order is preserved.
+*/
+function readMoof(bytes, moof, tracks) {
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const kids = childBoxes(bytes, moof.contentStart, moof.end);
+	if (kids === null) return null;
+	const out = [];
+	for (const traf of kids) {
+		if (traf.type !== "traf") continue;
+		const trafKids = childBoxes(bytes, traf.contentStart, traf.end);
+		const tfhdBox = findBox(trafKids, "tfhd");
+		if (tfhdBox === null) return null;
+		const tfhd = readTfhd(view, tfhdBox);
+		if (tfhd === null) return null;
+		const kind = tfhd.trackId === tracks.video.id ? "video" : tracks.audio !== null && tfhd.trackId === tracks.audio.id ? "audio" : null;
+		if (kind === null) continue;
+		const trex = kind === "video" ? tracks.video.trex : tracks.audio?.trex ?? null;
+		if (trex === null) continue;
+		const tfdtBox = findBox(trafKids, "tfdt");
+		const startDts = tfdtBox === null ? 0 : readTfdt(view, bytes, tfdtBox);
+		if (startDts === null) return null;
+		const base = tfhd.baseDataOffset ?? moof.start;
+		let dts = startDts;
+		for (const trun of trafKids ?? []) {
+			if (trun.type !== "trun") continue;
+			const samples = readTrun({
+				view,
+				trun,
+				base,
+				startDts: dts,
+				trex,
+				traf: tfhd
+			});
+			if (samples === null) return null;
+			for (const sample of samples) out.push({
+				kind,
+				sample
+			});
+			const last = samples[samples.length - 1];
+			if (last !== void 0) dts = last.dts + last.duration;
+		}
+	}
+	return out.toSorted((a, b) => a.sample.offset - b.sample.offset);
+}
+/** Bytes are ABSOLUTE file offsets here, so the demuxer can reason about a
+*  sample announced by a `moof` whose `mdat` has not fully arrived. */
+var ByteWindow = class {
+	held = new Uint8Array(0);
+	/** Absolute offset of `held[0]`. */
+	base = 0;
+	/** Bytes still to DISCARD from the front of what arrives next — a skip
+	*  past the end of what is held (the tail of an mdat nobody follows). */
+	skipAhead = 0;
+	get start() {
+		return this.base;
+	}
+	get end() {
+		return this.base + this.held.length;
+	}
+	get length() {
+		return this.held.length;
+	}
+	append(chunk) {
+		let incoming = chunk;
+		if (this.skipAhead > 0) {
+			const drop = Math.min(this.skipAhead, incoming.length);
+			this.skipAhead -= drop;
+			this.base += drop;
+			incoming = incoming.subarray(drop);
+		}
+		if (incoming.length === 0) return;
+		if (this.held.length === 0) {
+			this.held = incoming;
+			return;
+		}
+		const next = new Uint8Array(this.held.length + incoming.length);
+		next.set(this.held, 0);
+		next.set(incoming, this.held.length);
+		this.held = next;
+	}
+	/** Drop everything before absolute `offset`, including bytes not yet arrived. */
+	consumeTo(offset) {
+		if (offset <= this.base) return;
+		const drop = Math.min(offset - this.base, this.held.length);
+		this.held = this.held.subarray(drop);
+		this.base += drop;
+		if (offset > this.base) {
+			this.skipAhead += offset - this.base;
+			this.base = offset;
+			this.held = new Uint8Array(0);
+		}
+	}
+	slice(absStart, absEnd) {
+		return this.held.subarray(absStart - this.base, absEnd - this.base);
+	}
+	view() {
+		return this.held;
+	}
+};
+function createFmp4StreamDemuxer(options = {}) {
+	const onAudio = options.onAudio;
+	const window = new ByteWindow();
+	let track = null;
+	let audioTrack = null;
+	let audioState = { kind: "unknown" };
+	let dead = null;
+	/** Samples announced by the current `moof`, not yet emitted, offset order. */
+	let announced = [];
+	/** Absolute end of the `mdat` the announced samples live in, once known. */
+	let mdatEnd = null;
+	/** The ONE origin both tracks are measured from — the first sample emitted. */
+	let origin = null;
+	let samples = 0;
+	let audioSamples = 0;
+	let durationTicks = 0;
+	const refuse = (reason, message) => {
+		dead = new Fmp4DemuxError(reason, message);
+		throw dead;
+	};
+	/** Anchor the shared origin on the first sample of EITHER track. */
+	const anchor = (cts, timescale) => {
+		origin ??= {
+			ticks: cts,
+			timescale
+		};
+		return origin;
+	};
+	const toAccessUnit = (sample, data) => {
+		if (track === null) throw new Error("unreachable: sample before moov");
+		const at = anchor(sample.cts, track.timescale);
+		const isHevc = track.codec === "H265";
+		let annexB;
+		try {
+			annexB = sample.sync ? buildKeyframeAnnexB(data, track.description, isHevc) : avccSampleToAnnexB(data, track.nalLengthSize);
+		} catch (err) {
+			return refuse("malformed", `sample ${samples} is not a valid AVCC/HVCC sample: ${String(err)}`);
+		}
+		samples += 1;
+		durationTicks += sample.duration;
+		return {
+			data: annexB,
+			ptsMs: ptsMsFrom(at, sample.cts, track.timescale),
+			keyframe: sample.sync,
+			codec: track.codec
+		};
+	};
+	const emitAudio = (sample, data) => {
+		if (audioTrack === null || onAudio === void 0) return;
+		const at = anchor(sample.cts, audioTrack.timescale);
+		audioSamples += 1;
+		onAudio({
+			data: data.slice(),
+			ptsMs: ptsMsFrom(at, sample.cts, audioTrack.timescale),
+			durationMs: Math.round(sample.duration * 1e3 / audioTrack.timescale),
+			codec: audioTrack.codec,
+			sampleRateHz: audioTrack.sampleRateHz,
+			channels: audioTrack.channels
+		});
+	};
+	/** Emit every announced sample whose bytes are in, in order; stop at the first that is not. */
+	const drainAnnounced = (out) => {
+		while (announced.length > 0) {
+			const next = announced[0];
+			if (next === void 0) return;
+			const sampleEnd = next.sample.offset + next.sample.size;
+			if (mdatEnd !== null && sampleEnd > mdatEnd) refuse("malformed", `a sample runs past its mdat (${sampleEnd} > ${mdatEnd})`);
+			if (next.sample.offset < window.start) refuse("malformed", `a sample points behind the bytes still held (${next.sample.offset} < ${window.start})`);
+			if (sampleEnd > window.end) return;
+			const bytes = window.slice(next.sample.offset, sampleEnd);
+			if (next.kind === "video") out.push(toAccessUnit(next.sample, bytes));
+			else emitAudio(next.sample, bytes);
+			announced = announced.slice(1);
+			window.consumeTo(sampleEnd);
+		}
+		if (mdatEnd !== null) {
+			window.consumeTo(mdatEnd);
+			mdatEnd = null;
+		}
+	};
+	const push = (chunk) => {
+		if (dead !== null) throw dead;
+		window.append(chunk);
+		const out = [];
+		for (;;) {
+			if (announced.length > 0 && mdatEnd !== null) {
+				drainAnnounced(out);
+				if (announced.length > 0) return out;
+			}
+			const held = window.view();
+			if (held.length < BOX_HEADER) return out;
+			const view = new DataView(held.buffer, held.byteOffset, held.byteLength);
+			const declared = u32(view, 0);
+			const type = fourcc(held, 4);
+			let size = declared;
+			let contentStart = BOX_HEADER;
+			if (declared === 1) {
+				if (held.length < LARGE_BOX_HEADER) return out;
+				size = u64(view, 8);
+				contentStart = LARGE_BOX_HEADER;
+			} else if (declared === 0) refuse("malformed", `a "${type}" box extends to end-of-file, which a stream never reaches`);
+			if (size < contentStart) refuse("malformed", `a "${type}" box declares ${size} bytes`);
+			const boxStart = window.start;
+			const boxEnd = boxStart + size;
+			if (type === "mdat") {
+				if (track === null) refuse("no-moov", "media arrived before any moov");
+				if (announced.length === 0) {
+					window.consumeTo(boxEnd);
+					continue;
+				}
+				mdatEnd = boxEnd;
+				window.consumeTo(boxStart + contentStart);
+				continue;
+			}
+			if (held.length < size) return out;
+			if (type === "moov") {
+				const moov = {
+					type,
+					start: 0,
+					end: size,
+					contentStart
+				};
+				const read = readVideoTrack(held, moov);
+				if (typeof read === "string") refuse(read, `the moov cannot be followed: ${read}`);
+				else track = read;
+				const audio = readAudioTrack$1(held, moov);
+				if ("kind" in audio) audioState = audio;
+				else {
+					audioTrack = audio;
+					audioState = {
+						kind: "ready",
+						codec: audio.codec,
+						sampleRateHz: audio.sampleRateHz,
+						channels: audio.channels
+					};
+				}
+			} else if (type === "moof") {
+				if (track === null) refuse("no-moov", "a moof arrived before any moov");
+				const announcedHere = readMoof(held, {
+					type,
+					start: 0,
+					end: size,
+					contentStart
+				}, {
+					video: track,
+					audio: onAudio === void 0 ? null : audioTrack
+				});
+				if (announcedHere === null) refuse("malformed", "a moof cannot be read");
+				announced = announcedHere.map((p) => ({
+					kind: p.kind,
+					sample: {
+						...p.sample,
+						offset: p.sample.offset + boxStart
+					}
+				}));
+			}
+			window.consumeTo(boxEnd);
+		}
+	};
+	return {
+		push,
+		end: () => ({
+			durationMs: track !== null && samples > 0 && durationTicks > 0 ? durationTicks * 1e3 / track.timescale : null,
+			samples,
+			audioSamples,
+			trailingBytes: window.length,
+			pendingSamples: announced.length
+		}),
+		get ready() {
+			return track !== null;
+		},
+		get codec() {
+			return track?.codec ?? null;
+		},
+		get audio() {
+			return audioState;
+		},
+		get pendingBytes() {
+			return window.length;
+		}
+	};
+}
+//#endregion
+//#region src/stream-broker/recorded/clip-stream-feeder.ts
+/**
+* clip-stream-feeder — a clip plays FROM A STREAM, forward-only (D597).
+*
+* The second clip feeder, beside `clip-file-source.ts` + `RecordedFeeder`
+* and not in their place. The file path fetches the whole clip by handle,
+* indexes `stbl`, and lets the recorded feeder PULL access units by time.
+* This path is the other shape: the provider's clip STREAM
+* (`/clip-stream/…`, stage 1) is a fragmented MP4 written from the first
+* muxed byte, with no index and no length, and the bytes reach this process
+* as the camera delivers them. Nothing here pulls — the stream PUSHES, the
+* demuxer emits access units as their bytes land, and this feeder paces them
+* onto the session's track at the playback rate.
+*
+* ## Forward-only, and what that means for every verb
+*
+* The camera offers no seek inside a recording (operator's decision from the
+* packet capture, 2026-09-22): a replay names a FILE, and the bytes behind
+* the head were never kept. So:
+*
+* - `seek(t)` with `t` behind the HEAD (the last frame pushed) is REFUSED BY
+*   NAME — logged, the position re-sent so the viewer's playhead snaps back
+*   to the truth, and nothing else changes. "Back to the start" is as
+*   impossible as any other backward move; `forward` is measured against the
+*   head, never against zero (the viewer's `clipSeekAllowed` says the same).
+* - `seek(t)` ahead of the head is honoured if the bytes have arrived: what
+*   was buffered before the last keyframe ≤ `t` is dropped, the run from that
+*   keyframe to `t` is BURST (decode priming, as the recorded feeder's seek
+*   prefix does), and pacing resumes from `t`. If the bytes have NOT arrived,
+*   the seek waits for them and lands when they do — a stream cannot answer
+*   faster than the camera sends.
+* - `stepFrame(-1)` and the scrub verbs are refused by name; `stepFrame(+1)`
+*   pushes the next buffered unit.
+* - `setRate` is the PLAYER's rate over frames already here ({0} ∪ [0.25, 4],
+*   the recorded domain). The camera's own `playSpeed` (8, 16 — real, the app
+*   reopens the replay at 8) is a different mechanism and is NOT wired: it
+*   would go on the dial (`videoclips.dialClipStream` → the cmd-5 replay's
+*   `<playSpeed>`), costing a new stream, and is named in D597 as open.
+*
+* ## Duration is unknown until it is known
+*
+* A stream has no length up front. `durationMs()` resolves when the stream
+* ENDS, with the demuxer's own sum, or with `null` when it was cut or left
+* before it ended — never `0` (D393). The session reports it then, named by
+* clip, exactly as it reports the file path's measure.
+*
+* ## D9/D18, stated
+*
+* Media crosses the process boundary here COMPRESSED, in one TCP stream, at
+* the camera's delivery rate — the same shape the live path ingests from an
+* RTSP camera, and the same shape the file path's one by-handle fetch has,
+* spread over time instead of held whole. What D9 forbids is RAW frames at
+* frame-rate across processes, and nothing raw exists until the session's
+* decoder, which is downstream of this process. The backlog is bounded
+* ({@link CLIP_STREAM_BUFFER_MAX_BYTES}, the file path's own ceiling): above
+* it the socket is PAUSED (D447 on the consuming hop — read no chunk you have
+* not taken), and the producer's drain gate is what decides a consumer that
+* never drains. Frames behind the head are released as soon as they are
+* pushed, which is the same fact as "no backward seek".
+*
+* ## Sound, and the one clock it shares with the picture (D600)
+*
+* The stream carries audio ALREADY in the session's negotiated codec — the
+* provider transcodes before it muxes, because it is the process that holds
+* the camera's AAC and it already runs an ffmpeg. So this feeder decodes
+* nothing: it frames (`clip-stream-audio.ts`) and paces, on ONE schedule with
+* the video, on the SAME `ptsMs` axis the demuxer anchors both tracks on, and
+* off ONE {@link MonotonicClock} whose output is converted to each track's
+* RTP rate ({@link ClipStreamFeeder.stampAudio}). One clock rather than the
+* recorded path's pair: two clocks re-base on their own last output at every
+* discontinuity, so each seek leaves them a frame further apart.
+*
+* Two rules keep it honest, and both exist because a wrong one is inaudible
+* in a unit test:
+*
+* - **Audio is never pushed late.** ffmpeg's muxer writes a track's run when
+*   its own fragment closes, so the first seconds of sound can land after the
+*   picture they belong to (measured: 43 ms behind at the head on a 60x
+*   delivery, and nothing after). A unit whose moment has passed by more than
+*   {@link CLIP_STREAM_AUDIO_LATE_MS} is DROPPED and counted — never pushed
+*   in a burst the receiver would have to discard anyway, and never silently.
+* - **Audio plays at 1x only**, like the recorded feeder's: a rate change
+*   would need a resample this path has no decoder for, and pitch-shifted
+*   sound is worse than none. Units dropped for the rate are counted apart.
+*
+* What the clip turned out to carry — sound, or silence and WHY — settles on
+* {@link ClipStreamFeeder.audio} the moment the `moov` is read, and is what
+* the session reports to the viewer. A dial that promises a codec promises
+* the codec, never the content: whether the recording has a microphone track
+* is only ever knowable from the stream.
+*
+* ## Every exit is logged
+*
+* Opened, first frame (with the time since the seek and since the dial),
+* ended, cut (by reason), refused (by the provider's code), disposed, every
+* refused verb, and every backpressure transition — each with `deviceId` in
+* `data`, which the broker's `onLog` puts in `tags`.
+*/
+/**
+* The same ceiling as the file path (`CLIP_SOURCE_MAX_BYTES`): a clip the
+* file path would refuse `too-large` is one this path stops taking. Frames
+* behind the head are released as they are pushed, so the backlog is the
+* distance between arrival and playback, not the clip.
+*/
+var CLIP_STREAM_BUFFER_MAX_BYTES = CLIP_SOURCE_MAX_BYTES;
+/** The RTP clock each codec's re-stamped timestamps are counted on. */
+var AUDIO_CLOCK_HZ = {
+	opus: 48e3,
+	pcmu: 8e3
+};
+/** A forward seek is a discontinuity for the receiver, like the recorded feeder's. */
+var SEEK_DISCONTINUITY_MS = 250;
+var WAIT_TICK_MS = 250;
+var POSITION_INTERVAL_MS = 1e3;
+function createClipStreamFeeder(deps) {
+	return new ClipStreamFeeder(deps);
+}
+var ClipStreamFeeder = class {
+	deps;
+	phase = "idle";
+	connection = null;
+	demuxer;
+	clock = new MonotonicClock();
+	/** The RTP rate the audio sender negotiated — a CONVERSION, not a clock. */
+	audioClockHz;
+	audioAsk;
+	audioPush;
+	audioFramer = null;
+	audioQueue = [];
+	audioQueuedBytes = 0;
+	audioPushed = 0;
+	audioDroppedLate = 0;
+	audioDroppedRate = 0;
+	audioDroppedSeek = 0;
+	firstAudioLogged = false;
+	audioReport = null;
+	audioWaiters = [];
+	clockHasAdvanced = false;
+	rate = 1;
+	queue = [];
+	queuedBytes = 0;
+	headMs = null;
+	arrivedMs = null;
+	pendingSeekMs = null;
+	pendingSteps = 0;
+	seekToken = 0;
+	anchorWall = 0;
+	anchorPts = 0;
+	paceTimer = null;
+	positionTimer = null;
+	stallTimer = null;
+	socketPaused = false;
+	streamEnded = false;
+	streamEnd = null;
+	duration = null;
+	durationWaiters = [];
+	lastAnnounced = null;
+	scrubRefusedFor = void 0;
+	pushed = 0;
+	dropped = 0;
+	bytesIn = 0;
+	dialedAt = null;
+	seekStartedAt = null;
+	firstFrameLogged = false;
+	maxBufferedBytes;
+	stallTimeoutMs;
+	now;
+	tags;
+	constructor(deps) {
+		this.deps = deps;
+		this.maxBufferedBytes = deps.maxBufferedBytes ?? CLIP_STREAM_BUFFER_MAX_BYTES;
+		this.stallTimeoutMs = deps.stallTimeoutMs ?? 15e3;
+		this.now = deps.now ?? (() => Date.now());
+		this.tags = {
+			deviceId: deps.handle.deviceId,
+			clipId: deps.handle.clipId
+		};
+		const push = this.resolveAudioPush(deps);
+		this.audioAsk = push === null ? "none" : deps.audio ?? "none";
+		this.audioPush = this.audioAsk === "none" ? null : push;
+		this.audioClockHz = this.audioAsk === "none" ? AUDIO_CLOCK_HZ.pcmu : AUDIO_CLOCK_HZ[this.audioAsk];
+		this.demuxer = createFmp4StreamDemuxer(this.audioPush === null ? {} : { onAudio: (unit) => this.onAudioUnit(unit) });
+		if (this.audioPush === null) this.settleAudio({
+			carried: false,
+			codec: null,
+			reason: "not-negotiated"
+		});
+	}
+	/**
+	* The sink function for the negotiated codec, or `null`.
+	*
+	* Mirrors `RecordedFeeder.resolveAudioPush`: the sink is what decides, and
+	* a session that offered a codec on the dial but wired no push for it would
+	* otherwise make the provider transcode for nobody.
+	*/
+	resolveAudioPush(deps) {
+		const { sink, audio } = deps;
+		if (audio === "opus") {
+			const opus = sink.pushAudioOpus;
+			return opus === void 0 ? null : (data, ts) => opus.call(sink, data, ts);
+		}
+		if (audio === "pcmu") {
+			const pcmu = sink.pushAudioPcmu;
+			return pcmu === void 0 ? null : (data, ts) => pcmu.call(sink, data, ts);
+		}
+		return null;
+	}
+	async seek(epochMs) {
+		const token = ++this.seekToken;
+		if (this.phase === "disposed" || this.phase === "cut" || this.phase === "refused") {
+			this.log("clip-stream:seek-after-exit", {
+				targetMs: epochMs,
+				phase: this.phase
+			});
+			return;
+		}
+		if (this.phase === "ended") {
+			this.log("clip-stream:seek-at-end", {
+				targetMs: epochMs,
+				headMs: this.headMs
+			});
+			if (this.headMs !== null) this.deps.onPosition(this.headMs);
+			return;
+		}
+		if (this.headMs !== null && epochMs < this.headMs) {
+			this.log("clip-stream:seek-backward-refused", {
+				targetMs: epochMs,
+				headMs: this.headMs,
+				behindMs: this.headMs - epochMs
+			});
+			this.deps.onPosition(this.headMs);
+			return;
+		}
+		this.seekStartedAt = this.now();
+		this.stopPacing();
+		this.pendingSeekMs = epochMs;
+		if (this.phase === "idle") {
+			await this.open(token);
+			if (token !== this.seekToken) return;
+			if (!this.isStreaming()) return;
+		} else if (this.headMs !== null && epochMs > this.headMs && this.clockHasAdvanced) {
+			this.clock.markDiscontinuity(SEEK_DISCONTINUITY_MS);
+			this.emitState("loading", "seek-forward", token);
+			this.log("clip-stream:seek-forward", {
+				targetMs: epochMs,
+				headMs: this.headMs,
+				arrivedMs: this.arrivedMs,
+				queued: this.queue.length
+			});
+		}
+		this.resolvePendingSeek(token);
+	}
+	setRate(rate) {
+		const next = clampPlaybackRate(rate);
+		if (next === 0) {
+			this.rate = 0;
+			this.stopPacing();
+			this.stopPositionReports();
+			if (this.phase === "streaming" && this.pendingSeekMs === null) this.emitState("paused", "set-rate-zero", this.seekToken);
+			return;
+		}
+		this.clock.setRate(next);
+		const wasPaused = this.rate === 0;
+		this.rate = next;
+		if (this.phase !== "streaming" || this.pendingSeekMs !== null) return;
+		if (wasPaused) this.emitState("playing", "set-rate-resume", this.seekToken);
+		this.startPacing();
+	}
+	stepFrame(dir) {
+		if (this.rate !== 0 || this.phase !== "streaming") return;
+		if (dir === -1) {
+			this.log("clip-stream:step-backward-refused", { headMs: this.headMs });
+			return;
+		}
+		if (!this.pushNext()) {
+			if (this.streamEnded) {
+				this.log("clip-stream:step-at-end", { headMs: this.headMs });
+				return;
+			}
+			this.pendingSteps += 1;
+		}
+	}
+	beginScrub(dragId) {
+		if (this.scrubRefusedFor === dragId) return;
+		this.scrubRefusedFor = dragId;
+		this.log("clip-stream:scrub-refused", {
+			dragId,
+			reason: "forward-only",
+			headMs: this.headMs
+		});
+	}
+	scrubTo() {}
+	scrubAck() {}
+	durationMs() {
+		if (this.duration !== null) return Promise.resolve(this.duration.value);
+		return new Promise((resolve) => this.durationWaiters.push(resolve));
+	}
+	/**
+	* What this clip turned out to carry as sound — the answer the viewer needs
+	* to say "this clip has no audio" rather than leave the operator wondering.
+	*
+	* Settles as soon as the stream's `moov` has been read, which is the first
+	* fragment, so it lands beside `durationMs()`'s much later answer rather
+	* than waiting for the stream to end.
+	*/
+	audio() {
+		const settled = this.audioReport;
+		if (settled !== null) return Promise.resolve(settled);
+		return new Promise((resolve) => this.audioWaiters.push(resolve));
+	}
+	dispose() {
+		if (this.phase === "disposed") return;
+		const before = this.phase;
+		this.phase = "disposed";
+		this.teardown();
+		this.settleDuration(null);
+		this.settleAudio({
+			carried: false,
+			codec: null,
+			reason: "stream-failed"
+		});
+		this.log("clip-stream:disposed", {
+			phaseBefore: before,
+			pushed: this.pushed,
+			dropped: this.dropped,
+			queued: this.queue.length,
+			bytesIn: this.bytesIn,
+			headMs: this.headMs
+		});
+		this.queue = [];
+		this.queuedBytes = 0;
+		this.audioQueue = [];
+		this.audioQueuedBytes = 0;
+	}
+	/** A method, not a field read: `open()` moves the phase behind an await
+	*  that control-flow analysis does not see through. */
+	isStreaming() {
+		return this.phase === "streaming";
+	}
+	async open(token) {
+		this.phase = "opening";
+		this.emitState("loading", "dial", token);
+		this.dialedAt = this.now();
+		let answer;
+		try {
+			answer = await this.deps.dial(this.deps.handle, this.audioAsk);
+		} catch (err) {
+			answer = {
+				kind: "refused",
+				code: "fetch-failed",
+				detail: describe(err)
+			};
+		}
+		if (this.phase !== "opening") return;
+		if (answer.kind !== "dialed") {
+			this.settleAudio({
+				carried: false,
+				codec: null,
+				reason: "stream-failed"
+			});
+			this.refuse(answer.kind === "unavailable" ? "stream-unavailable" : answer.code, answer.detail, token, answer.kind === "unavailable" ? "the provider predates videoclips.dialClipStream — deploy provider-reolink, or the file path" : void 0);
+			return;
+		}
+		if (this.deps.handle.profile === "high" && answer.served !== void 0 && answer.served !== "high") this.deps.onLog?.("clip stream: no main twin — streaming the sub copy for a `high` ask", {
+			deviceId: this.deps.handle.deviceId,
+			asked: "high",
+			served: answer.served
+		});
+		if (this.audioAsk !== "none" && answer.servedAudio !== this.audioAsk) {
+			this.settleAudio({
+				carried: false,
+				codec: null,
+				reason: "not-offered",
+				detail: answer.audioReason ?? answer.servedAudio ?? "the provider did not say"
+			});
+			this.log("clip-stream:audio-not-offered", {
+				asked: this.audioAsk,
+				servedAudio: answer.servedAudio ?? null,
+				audioReason: answer.audioReason ?? null
+			});
+		}
+		let opened;
+		try {
+			opened = await this.deps.open(answer.url, {
+				onData: (chunk) => this.onData(chunk),
+				onEnd: () => this.onEnd(),
+				onError: (err) => this.cut("stream-failed", err.message)
+			});
+		} catch (err) {
+			opened = {
+				kind: "refused",
+				status: 0,
+				code: "fetch-failed",
+				detail: describe(err)
+			};
+		}
+		if (this.phase !== "opening") {
+			if (opened.kind === "open") opened.connection.destroy();
+			return;
+		}
+		if (opened.kind === "refused") {
+			this.refuse(opened.code, opened.detail, token, void 0, opened.status);
+			return;
+		}
+		this.connection = opened.connection;
+		this.phase = "streaming";
+		this.armStall();
+		this.applyBackpressure();
+		this.log("clip-stream:opened", {
+			sinceDialMs: this.now() - (this.dialedAt ?? this.now()),
+			expiresInMs: answer.expiresAtMs - Date.now()
+		});
+	}
+	refuse(code, detail, token, hint, status) {
+		this.phase = "refused";
+		this.teardown();
+		this.settleDuration(null);
+		this.settleAudio({
+			carried: false,
+			codec: null,
+			reason: "stream-failed"
+		});
+		this.log("clip-stream:refused", {
+			code,
+			detail,
+			...hint !== void 0 ? { hint } : {},
+			...status !== void 0 ? { status } : {}
+		});
+		this.emitState("error", `refused:${code}`, token);
+	}
+	/**
+	* Bytes are taken while OPENING too. Node flushes body bytes it already
+	* holds on `process.nextTick` the moment the `data` listener attaches,
+	* and that tick runs BEFORE the promise continuation that flips this
+	* feeder to `streaming` — so the head of the stream (ftyp, moov) arrives
+	* while the phase still says `opening`. Dropping it there turned every
+	* live stream into `no-moov` while a fake opener, which delivered only
+	* after resolving, kept the suite green (2026-09-22).
+	*/
+	takesBytes() {
+		return this.phase === "streaming" || this.phase === "opening";
+	}
+	onData(chunk) {
+		if (!this.takesBytes()) return;
+		this.bytesIn += chunk.byteLength;
+		this.armStall();
+		let units;
+		try {
+			units = this.demuxer.push(chunk);
+		} catch (err) {
+			const reason = err instanceof Fmp4DemuxError ? err.reason : "malformed";
+			this.cut("demux-refused", `${reason}: ${describe(err)}`);
+			return;
+		}
+		for (const unit of units) {
+			this.queue.push(unit);
+			this.queuedBytes += unit.data.byteLength;
+			this.arrivedMs = unit.ptsMs;
+		}
+		this.settleAudioFromMoov();
+		if (units.length > 0 || this.audioQueue.length > 0) this.onUnitsArrived();
+		this.applyBackpressure();
+	}
+	/**
+	* What the stream really carries, decided from the `moov` and said ONCE.
+	*
+	* This is the answer a dial cannot give: the provider promises a codec
+	* before the camera has delivered a single audio frame, and whether the
+	* recording HAS sound is written in the container it produced. A track in a
+	* codec this process cannot forward, or in one the session did not
+	* negotiate, is named here and never re-encoded — a second transcode on
+	* this hop is exactly the backlog this path is built to avoid.
+	*/
+	settleAudioFromMoov() {
+		if (this.audioReport !== null || this.audioPush === null) return;
+		const state = this.demuxer.audio;
+		if (state.kind === "unknown") return;
+		if (state.kind === "absent") {
+			this.settleAudio({
+				carried: false,
+				codec: null,
+				reason: "no-audio-track"
+			});
+			this.log("clip-stream:audio-absent", { asked: this.audioAsk });
+			return;
+		}
+		if (state.kind === "unsupported") {
+			this.settleAudio({
+				carried: false,
+				codec: null,
+				reason: "unsupported-codec"
+			});
+			this.log("clip-stream:audio-unsupported", {
+				asked: this.audioAsk,
+				sampleEntry: state.sampleEntry
+			});
+			return;
+		}
+		if (state.codec !== this.audioAsk) {
+			this.settleAudio({
+				carried: false,
+				codec: null,
+				reason: "codec-mismatch"
+			});
+			this.log("clip-stream:audio-codec-mismatch", {
+				asked: this.audioAsk,
+				got: state.codec
+			});
+			return;
+		}
+		this.audioFramer = createClipAudioFramer(state.codec);
+		this.settleAudio({
+			carried: true,
+			codec: state.codec,
+			reason: null
+		});
+		this.log("clip-stream:audio-ready", {
+			codec: state.codec,
+			sampleRateHz: state.sampleRateHz,
+			channels: state.channels
+		});
+	}
+	/** One demuxed audio sample, framed and queued on the same axis as video. */
+	onAudioUnit(unit) {
+		this.settleAudioFromMoov();
+		const framer = this.audioFramer;
+		if (framer === null) return;
+		for (const frame of framer.push(unit)) {
+			this.audioQueue.push(frame);
+			this.audioQueuedBytes += frame.data.byteLength;
+		}
+	}
+	onUnitsArrived() {
+		if (this.pendingSeekMs !== null) {
+			this.resolvePendingSeek(this.seekToken);
+			return;
+		}
+		while (this.rate === 0 && this.pendingSteps > 0 && this.pushNext()) this.pendingSteps -= 1;
+		if (this.rate > 0 && this.paceTimer === null) this.tick();
+	}
+	onEnd() {
+		if (!this.takesBytes()) return;
+		this.streamEnded = true;
+		this.clearStall();
+		this.streamEnd = this.demuxer.end();
+		this.log("clip-stream:ended", {
+			samples: this.streamEnd.samples,
+			durationMs: this.streamEnd.durationMs,
+			bytesIn: this.bytesIn,
+			trailingBytes: this.streamEnd.trailingBytes,
+			pendingSamples: this.streamEnd.pendingSamples,
+			queued: this.queue.length
+		});
+		this.settleDuration(this.streamEnd.durationMs);
+		if (this.pendingSeekMs !== null) {
+			this.resolvePendingSeek(this.seekToken);
+			return;
+		}
+		if (this.rate > 0 && this.paceTimer === null) this.tick();
+	}
+	cut(reason, detail) {
+		if (this.phase !== "streaming" && this.phase !== "opening") return;
+		this.phase = "cut";
+		this.teardown();
+		this.settleDuration(null);
+		this.settleAudio({
+			carried: false,
+			codec: null,
+			reason: "stream-failed"
+		});
+		this.log("clip-stream:cut", {
+			reason,
+			detail,
+			pushed: this.pushed,
+			queued: this.queue.length,
+			bytesIn: this.bytesIn,
+			headMs: this.headMs,
+			arrivedMs: this.arrivedMs,
+			...this.audioTally()
+		});
+		this.emitState("error", `cut:${reason}`, this.seekToken);
+	}
+	armStall() {
+		this.clearStall();
+		this.stallTimer = setTimeout(() => this.cut("stream-stalled", `no bytes for ${this.stallTimeoutMs} ms`), this.stallTimeoutMs);
+	}
+	clearStall() {
+		if (this.stallTimer !== null) clearTimeout(this.stallTimer);
+		this.stallTimer = null;
+	}
+	/** D447 on the consuming hop: pause the socket above the bound, resume below half. */
+	applyBackpressure() {
+		if (this.connection === null) return;
+		const held = this.queuedBytes + this.audioQueuedBytes + this.demuxer.pendingBytes;
+		if (!this.socketPaused && held > this.maxBufferedBytes) {
+			this.socketPaused = true;
+			this.connection?.pause();
+			this.log("clip-stream:backpressure-paused", {
+				heldBytes: held,
+				maxBytes: this.maxBufferedBytes
+			});
+		} else if (this.socketPaused && held < this.maxBufferedBytes / 2) {
+			this.socketPaused = false;
+			this.connection?.resume();
+			this.log("clip-stream:backpressure-resumed", { heldBytes: held });
+		}
+	}
+	/**
+	* Land a pending seek if its bytes are here. Called on the seek itself,
+	* on every arrival while one is pending, and on end-of-stream (the last
+	* chance: a target past the end lands on the last frame and the clip ends).
+	*/
+	resolvePendingSeek(token) {
+		const target = this.pendingSeekMs;
+		if (target === null || this.phase !== "streaming") return;
+		let keep = 0;
+		for (let i = 0; i < this.queue.length; i++) {
+			const unit = this.queue[i];
+			if (unit === void 0 || unit.ptsMs > target) break;
+			if (unit.keyframe) keep = i;
+		}
+		if (keep > 0) {
+			for (let i = 0; i < keep; i++) this.queuedBytes -= this.queue[i]?.data.byteLength ?? 0;
+			this.dropped += keep;
+			this.queue = this.queue.slice(keep);
+		}
+		if (!(this.arrivedMs !== null && this.arrivedMs >= target) && !this.streamEnded) return;
+		if (this.queue.length === 0) {
+			if (this.streamEnded) {
+				this.pendingSeekMs = null;
+				this.log("clip-stream:seek-past-end", {
+					targetMs: target,
+					headMs: this.headMs
+				});
+				this.finish();
+			}
+			return;
+		}
+		let burst = 0;
+		while (this.queue.length > 0) {
+			const next = this.queue[0];
+			if (next === void 0 || burst > 0 && next.ptsMs > target) break;
+			this.pushNext();
+			burst += 1;
+		}
+		this.pendingSeekMs = null;
+		this.dropAudioBefore(this.headMs);
+		this.log("clip-stream:seek-landed", {
+			targetMs: target,
+			landedMs: this.headMs,
+			droppedUnits: keep,
+			burstUnits: burst,
+			queued: this.queue.length,
+			streamEnded: this.streamEnded
+		});
+		if (this.headMs !== null) this.deps.onPosition(this.headMs);
+		if (this.rate === 0) {
+			this.emitState("paused", "seek-landed-paused", token);
+			return;
+		}
+		this.emitState("playing", "seek-landed", token);
+		this.startPacing();
+	}
+	/**
+	* The audio RTP timestamp for a source instant — off the SAME clock as the
+	* video, converted to the negotiated rate.
+	*
+	* ONE mapping from source time to output time, not two. The recorded path
+	* runs a second `MonotonicClock` for audio and keeps the pair aligned by
+	* calling `markSeek()` on both, and that alignment is only as good as the
+	* discipline: each clock re-bases on its OWN last output, so every
+	* discontinuity leaves the two a frame further apart than it found them —
+	* a skew that is invisible on a short clip, grows with each seek, and is
+	* exactly the drift this path is not going to pay for twice. Deriving the
+	* audio stamp from the video clock's own output makes the alignment
+	* structural: there is nothing to keep in step.
+	*
+	* The conversion is exact to within a rounding tick (the video clock counts
+	* 90 kHz, so an output instant is known to 1/90 ms) and is computed from
+	* the source pts every time, never accumulated.
+	*/
+	stampAudio(ptsMs) {
+		return Math.round(this.clock.stamp(ptsMs) * this.audioClockHz / 9e4);
+	}
+	/** Forget sound the playhead has already passed — a forward seek's share. */
+	dropAudioBefore(headMs) {
+		if (headMs === null || this.audioQueue.length === 0) return;
+		let drop = 0;
+		while (drop < this.audioQueue.length) {
+			const frame = this.audioQueue[drop];
+			if (frame === void 0 || frame.ptsMs + frame.durationMs >= headMs) break;
+			this.audioQueuedBytes -= frame.data.byteLength;
+			drop += 1;
+		}
+		if (drop === 0) return;
+		this.audioQueue = this.audioQueue.slice(drop);
+		this.audioDroppedSeek += drop;
+	}
+	startPacing() {
+		this.stopPacing();
+		this.anchorWall = this.now();
+		this.anchorPts = this.headMs ?? this.queue[0]?.ptsMs ?? 0;
+		this.startPositionReports();
+		this.tick();
+	}
+	stopPacing() {
+		if (this.paceTimer !== null) clearTimeout(this.paceTimer);
+		this.paceTimer = null;
+	}
+	/**
+	* Push every unit that is due; sleep until the next; wait for data, or end.
+	*
+	* ONE schedule for both tracks, ordered by `ptsMs` with VIDEO first on a
+	* tie — the same ordering `RecordedFeeder.paceSegment` builds, so a clip
+	* and the recorder's own footage interleave identically. The two clocks
+	* stay separate (each codec's RTP rate) but they stamp the SAME axis.
+	*/
+	tick() {
+		this.paceTimer = null;
+		if (this.phase !== "streaming" || this.rate === 0 || this.pendingSeekMs !== null) return;
+		for (;;) {
+			const video = this.queue[0];
+			const audio = this.audioQueue[0];
+			if (video === void 0 && audio === void 0) {
+				if (this.streamEnded) this.finish();
+				return;
+			}
+			const takeVideo = video !== void 0 && (audio === void 0 || video.ptsMs <= audio.ptsMs);
+			const ptsMs = takeVideo ? video?.ptsMs ?? 0 : audio?.ptsMs ?? 0;
+			const wait = this.anchorWall + (ptsMs - this.anchorPts) / this.rate - this.now();
+			if (takeVideo) {
+				if (wait > 0) {
+					this.paceTimer = setTimeout(() => this.tick(), Math.min(wait, WAIT_TICK_MS));
+					return;
+				}
+				this.pushNext();
+				continue;
+			}
+			if (wait > 0) {
+				this.paceTimer = setTimeout(() => this.tick(), Math.min(wait, WAIT_TICK_MS));
+				return;
+			}
+			this.pushNextAudio(-wait);
+		}
+	}
+	/**
+	* Push or DROP the head of the audio queue. False only when it was empty.
+	*
+	* `lateMs` is how far the frame's moment has already passed. Past the
+	* bound it is dropped and counted: a receiver would discard it anyway, and
+	* pushing a run of them is the burst that makes a clip sound broken rather
+	* than silent. At any rate but 1x it is dropped for a different reason,
+	* counted apart, because resampling would need a decoder this path has not
+	* got and pitch-shifted sound is worse than none.
+	*/
+	pushNextAudio(lateMs) {
+		const frame = this.audioQueue[0];
+		if (frame === void 0) return false;
+		this.audioQueue = this.audioQueue.slice(1);
+		this.audioQueuedBytes -= frame.data.byteLength;
+		if (this.rate !== 1) {
+			this.audioDroppedRate += 1;
+			return true;
+		}
+		if (lateMs > 120) {
+			this.audioDroppedLate += 1;
+			return true;
+		}
+		this.audioPush?.(frame.data, this.stampAudio(frame.ptsMs));
+		this.audioPushed += 1;
+		if (!this.firstAudioLogged) {
+			this.firstAudioLogged = true;
+			this.log("clip-stream:first-audio", {
+				ptsMs: frame.ptsMs,
+				lateMs: Math.round(lateMs),
+				headMs: this.headMs,
+				droppedLate: this.audioDroppedLate
+			});
+		}
+		this.applyBackpressure();
+		return true;
+	}
+	/** Push the head of the queue onto the track. False when the queue is empty. */
+	pushNext() {
+		const unit = this.queue.shift();
+		if (unit === void 0) return false;
+		this.queuedBytes -= unit.data.byteLength;
+		this.deps.sink.pushAccessUnit(unit.data, this.clock.stamp(unit.ptsMs), unit.codec);
+		this.clockHasAdvanced = true;
+		this.headMs = this.headMs === null ? unit.ptsMs : Math.max(this.headMs, unit.ptsMs);
+		this.pushed += 1;
+		if (!this.firstFrameLogged) {
+			this.firstFrameLogged = true;
+			const at = this.now();
+			this.log("clip-stream:first-frame", {
+				sinceSeekMs: this.seekStartedAt === null ? null : at - this.seekStartedAt,
+				sinceDialMs: this.dialedAt === null ? null : at - this.dialedAt,
+				bytesIn: this.bytesIn,
+				ptsMs: unit.ptsMs,
+				codec: unit.codec
+			});
+		}
+		this.applyBackpressure();
+		return true;
+	}
+	finish() {
+		if (this.phase !== "streaming") return;
+		this.phase = "ended";
+		this.settleAudio({
+			carried: false,
+			codec: null,
+			reason: this.demuxer.ready ? "no-audio-track" : "stream-failed"
+		});
+		this.stopPacing();
+		this.stopPositionReports();
+		if (this.headMs !== null) this.deps.onPosition(this.headMs);
+		this.log("clip-stream:played-out", {
+			pushed: this.pushed,
+			dropped: this.dropped,
+			headMs: this.headMs,
+			durationMs: this.streamEnd?.durationMs ?? null,
+			...this.audioTally()
+		});
+		this.emitState("ended", "stream-played-out", this.seekToken);
+	}
+	startPositionReports() {
+		if (this.positionTimer !== null) return;
+		this.positionTimer = setInterval(() => {
+			if (this.headMs !== null && this.phase === "streaming") this.deps.onPosition(this.headMs);
+		}, POSITION_INTERVAL_MS);
+	}
+	stopPositionReports() {
+		if (this.positionTimer !== null) clearInterval(this.positionTimer);
+		this.positionTimer = null;
+	}
+	emitState(to, reason, seekToken) {
+		const from = this.lastAnnounced;
+		this.lastAnnounced = to;
+		this.deps.onState({
+			from,
+			to,
+			reason,
+			seekToken
+		});
+	}
+	/** The audio counters every exit line carries. Silence is never unexplained. */
+	audioTally() {
+		return {
+			audioAsked: this.audioAsk,
+			audioCarried: this.audioReport?.carried ?? false,
+			audioSilentReason: this.audioReport?.reason ?? null,
+			audioPushed: this.audioPushed,
+			audioDroppedLate: this.audioDroppedLate,
+			audioDroppedRate: this.audioDroppedRate,
+			audioDroppedSeek: this.audioDroppedSeek,
+			audioQueued: this.audioQueue.length
+		};
+	}
+	settleAudio(report) {
+		if (this.audioReport !== null) return;
+		this.audioReport = report;
+		const waiters = this.audioWaiters.splice(0);
+		for (const resolve of waiters) resolve(report);
+	}
+	settleDuration(value) {
+		if (this.duration !== null) return;
+		this.duration = {
+			settled: true,
+			value
+		};
+		const waiters = this.durationWaiters.splice(0);
+		for (const resolve of waiters) resolve(value);
+	}
+	teardown() {
+		this.stopPacing();
+		this.stopPositionReports();
+		this.clearStall();
+		const connection = this.connection;
+		this.connection = null;
+		connection?.destroy();
+	}
+	log(msg, data) {
+		this.deps.onLog?.(msg, {
+			...this.tags,
+			...data
+		});
+	}
+};
+function describe(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+function headerText(res, name) {
+	const value = res.headers[name];
+	if (Array.isArray(value)) return value[0];
+	return value;
+}
+function createHttpClipStreamOpener(options = {}) {
+	const headersTimeoutMs = options.headersTimeoutMs ?? 3e4;
+	return (url, handlers) => new Promise((resolve) => {
+		let settled = false;
+		const settle = (value) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve(value);
+		};
+		let target;
+		try {
+			target = new URL(url);
+		} catch (err) {
+			settle({
+				kind: "refused",
+				status: 0,
+				code: "bad-url",
+				detail: String(err)
+			});
+			return;
+		}
+		if (target.protocol !== "http:") {
+			settle({
+				kind: "refused",
+				status: 0,
+				code: "bad-url",
+				detail: `a clip stream is dialled over plain http on the provider's listener, not ${target.protocol}`
+			});
+			return;
+		}
+		const req = request(target, {
+			method: "GET",
+			headers: { accept: "video/mp4" }
+		});
+		const timer = setTimeout(() => {
+			req.destroy(/* @__PURE__ */ new Error(`no status line in ${headersTimeoutMs} ms`));
+		}, headersTimeoutMs);
+		req.on("error", (err) => {
+			settle({
+				kind: "refused",
+				status: 0,
+				code: "connect-failed",
+				detail: err.message
+			});
+		});
+		req.on("response", (res) => {
+			const status = res.statusCode ?? 0;
+			if (status !== 200) {
+				res.resume();
+				settle({
+					kind: "refused",
+					status,
+					code: headerText(res, "x-camstack-reason-code") ?? `http-${status}`,
+					detail: headerText(res, "x-camstack-reason") ?? ""
+				});
+				return;
+			}
+			if (headerText(res, "x-camstack-clip-transport") !== "forward-only") {
+				req.destroy();
+				settle({
+					kind: "refused",
+					status,
+					code: "not-a-stream",
+					detail: "the URL answered 200 without declaring the forward-only clip transport"
+				});
+				return;
+			}
+			res.on("data", (chunk) => handlers.onData(chunk));
+			res.on("end", () => handlers.onEnd());
+			res.on("error", (err) => handlers.onError(err));
+			settle({
+				kind: "open",
+				connection: {
+					pause: () => {
+						res.pause();
+					},
+					resume: () => {
+						res.resume();
+					},
+					destroy: () => {
+						req.destroy();
+					}
+				}
+			});
+		});
+		req.end();
+	});
+}
+//#endregion
 //#region src/stream-broker/recorded/demux-off-thread.ts
 /**
 * Off-thread JS demux client — mp4box parse on a `worker_threads` Worker
@@ -31332,6 +33226,7 @@ var BrokerWebrtcServer = class {
 	readRecordedSegmentBytes;
 	readRecordedGopBytes;
 	readClipBytes;
+	dialClipStream;
 	resolveFfmpegPath;
 	/**
 	* THE ffmpeg primitive, for the transcode leg. `null` until the manager wires
@@ -31425,6 +33320,7 @@ var BrokerWebrtcServer = class {
 		this.readRecordedSegmentBytes = options.readRecordedSegmentBytes;
 		this.readRecordedGopBytes = options.readRecordedGopBytes;
 		this.readClipBytes = options.readClipBytes;
+		this.dialClipStream = options.dialClipStream;
 		this.resolveFfmpegPath = options.resolveFfmpegPath;
 	}
 	registerBroker(brokerId, broker) {
@@ -32145,14 +34041,93 @@ var BrokerWebrtcServer = class {
 				};
 			} : void 0;
 			const readClip = this.readClipBytes;
+			const dialClip = this.dialClipStream;
+			const openClipStream = createHttpClipStreamOpener();
 			let timeline;
 			/**
 			* ONE feeder builder for BOTH sources (D575). `clip === null` is the
 			* recorder's own footage; a clip swaps only the two byte closures —
 			* everything else (demux, sink, audio codec branch, state/position/log
 			* seams) is identical, which is the whole claim the clip path makes.
+			*
+			* Since D597 a clip has TWO paths, and which one it gets is decided
+			* ONCE, here, by `chooseClipPath`, and logged with its reason: the
+			* STREAM for the sub twin (forward-only, first frame at the first
+			* fragment) whenever this broker can dial one, the FILE for `high` and
+			* for a broker with no dial. Never an implicit fallthrough.
 			*/
 			const buildFeeder = (profile, clip) => {
+				if (clip) {
+					const choice = chooseClipPath({
+						profile: clip.profile,
+						streamDialWired: dialClip !== void 0,
+						fileReadWired: readClip !== void 0
+					});
+					sessionLogger.info("clip playback: path chosen", {
+						tags: { deviceId: clip.deviceId },
+						meta: {
+							sessionId,
+							clipId: clip.clipId,
+							provider: clip.provider,
+							profile: clip.profile,
+							path: choice.path,
+							reason: choice.reason
+						}
+					});
+					const clipLog = (msg, data) => sessionLogger.info(msg, {
+						tags: { deviceId: clip.deviceId },
+						meta: {
+							sessionId,
+							clipId: clip.clipId,
+							...data
+						}
+					});
+					const onClipState = (t) => {
+						sessionLogger.info("recorded: feeder state", {
+							tags: { deviceId: clip.deviceId },
+							meta: {
+								sessionId,
+								deviceId,
+								profile,
+								clipId: clip.clipId,
+								path: choice.path,
+								from: t.from,
+								to: t.to,
+								reason: t.reason,
+								seekToken: t.seekToken
+							}
+						});
+						timeline._emitState(t.to);
+					};
+					if (choice.path === "none") return createRefusedClipFeeder({
+						handle: clip,
+						reason: choice.reason,
+						onState: onClipState,
+						onLog: clipLog
+					});
+					if (choice.path === "stream" && dialClip !== void 0) return createClipStreamFeeder({
+						handle: clip,
+						dial: (handle, audio) => dialClip({
+							deviceId: handle.deviceId,
+							clipId: handle.clipId,
+							provider: handle.provider,
+							profile: handle.profile,
+							audio
+						}),
+						open: openClipStream,
+						audio: session.isOpusAudio ? "opus" : "pcmu",
+						sink: session.isOpusAudio ? {
+							pushAccessUnit: (data, ts, codec) => session.pushRecordedAccessUnit(data, ts, codec),
+							pushAudioOpus: (opus, ts) => session.writeRecordedAudioOpus(Buffer.from(opus), ts)
+						} : {
+							pushAccessUnit: (data, ts, codec) => session.pushRecordedAccessUnit(data, ts, codec),
+							pushAudioPcmu: (pcmu, ts) => session.writeRecordedAudio(Buffer.from(pcmu), ts)
+						},
+						onState: onClipState,
+						onPosition: (epochMs) => timeline._emitPosition(epochMs),
+						onLog: clipLog
+					});
+				}
 				const opusSession = session.isOpusAudio;
 				const audioSink = opusSession ? {
 					pushAccessUnit: (data, ts, codec) => session.pushRecordedAccessUnit(data, ts, codec),
@@ -32266,7 +34241,7 @@ var BrokerWebrtcServer = class {
 					});
 				} : void 0,
 				makeFeeder: (profile) => buildFeeder(profile, null),
-				...readClip ? { makeClipFeeder: ({ handle }) => buildFeeder(handle.profile ?? "clip", handle) } : {},
+				...readClip || dialClip ? { makeClipFeeder: ({ handle }) => buildFeeder(handle.profile ?? "clip", handle) } : {},
 				onLog: (msg, data) => sessionLogger.warn(msg, {
 					tags: { deviceId },
 					meta: {
@@ -33311,6 +35286,51 @@ var WebrtcSessionProvider = class WebrtcSessionProvider {
 	}
 };
 //#endregion
+//#region src/stream-broker/recorded/clip-stream-dial-answer.ts
+/**
+* clip-stream-dial-answer — what a THROWN `videoclips.dialClipStream` means.
+*
+* The cap call has three ways to fail, and the feeder must tell them apart
+* because they lead to different lines and different states:
+*
+* - the provider PREDATES the method (`NOT_IMPLEMENTED`, "does not
+*   implement") — the stream does not exist on this cluster yet, which is a
+*   deploy-order fact, not a clip fact;
+* - the provider REFUSED in the clip vocabulary (`clipExportFailure`):
+*   `sleeping`, `catalog-miss`, `clip-in-progress`, `unsupported-option`… —
+*   the code is kept, the prose travels with it;
+* - anything else — the transport, a bug — is `fetch-failed` with the prose
+*   verbatim, exactly as the export engine treats an unknown error (D572).
+*/
+function trpcCodeOf(err) {
+	if (typeof err !== "object" || err === null) return null;
+	const shaped = err;
+	if (typeof shaped.data?.code === "string") return shaped.data.code;
+	if (typeof shaped.code === "string") return shaped.code;
+	return null;
+}
+function dialAnswerFromError(err) {
+	const message = err instanceof Error ? err.message : String(err);
+	if (trpcCodeOf(err) === "NOT_IMPLEMENTED" || /does not implement/i.test(message)) return {
+		kind: "unavailable",
+		detail: message
+	};
+	const code = clipExportFailureOf(message);
+	if (code !== null) {
+		const sep = message.indexOf(":");
+		return {
+			kind: "refused",
+			code,
+			detail: sep === -1 ? "" : message.slice(sep + 1).trim()
+		};
+	}
+	return {
+		kind: "refused",
+		code: "fetch-failed",
+		detail: message
+	};
+}
+//#endregion
 //#region src/stream-broker/event-loop-stall-monitor.ts
 var DEFAULT_INTERVAL_MS = 100;
 var DEFAULT_THRESHOLD_MS = 250;
@@ -33785,6 +35805,27 @@ var StreamBrokerAddon = class extends BaseAddon {
 				});
 				return new Uint8Array(Buffer.from(res.base64, "base64"));
 			},
+			dialClipStream: async (args) => {
+				try {
+					const dial = await this.ctx.api.videoclips.dialClipStream.query({
+						deviceId: args.deviceId,
+						clipId: args.clipId,
+						provider: args.provider,
+						...args.profile !== null ? { profile: args.profile } : {},
+						audio: args.audio
+					});
+					return {
+						kind: "dialed",
+						url: dial.url,
+						expiresAtMs: dial.expiresAtMs,
+						...typeof dial.served === "string" ? { served: dial.served } : {},
+						...typeof dial.servedAudio === "string" ? { servedAudio: dial.servedAudio } : {},
+						...typeof dial.audioReason === "string" ? { audioReason: dial.audioReason } : {}
+					};
+				} catch (err) {
+					return dialAnswerFromError(err);
+				}
+			},
 			readRecordedGopBytes: async (args) => {
 				try {
 					return await this.ctx.api.recording.readGopBytes.query({