@camstack/addon-pipeline 1.1.58 → 1.1.59

package/dist/stream-broker/index.mjs

@@ -1,7 +1,7 @@
 import { t as __require } from "../chunk-BdkLduGY.mjs";
-import { $ as discriminatedUnion, B as DeviceType, D as nodePin, F as webrtcSessionCapability, G as makeSourceBrokerId, I as errMsg, L as BaseAddon, N as streamBrokerCapability, Q as boolean, R as CAM_PROFILE_ORDER, U as isEvent, V as createEvent, W as makeProfileBrokerId, X as _enum, Z as array, at as string, c as EncodeProfileSchema, d as RingBuffer, g as cameraStreamsCapability, it as record, nt as number, ot as union, p as addonWidgetsSourceCapability, q as parseProfileBrokerId, rt as object, st as EventCategory, tt as literal, w as maskUrlCredentials, z as DeviceFeature } from "../dist-CnwwDzX3.mjs";
+import { $ as discriminatedUnion, B as DeviceType, D as nodePin, F as webrtcSessionCapability, G as makeSourceBrokerId, I as errMsg, L as BaseAddon, N as streamBrokerCapability, Q as boolean, R as CAM_PROFILE_ORDER, U as isEvent, V as createEvent, W as makeProfileBrokerId, X as _enum, Z as array, at as string, c as EncodeProfileSchema, d as RingBuffer, g as cameraStreamsCapability, it as record, nt as number, ot as union, p as addonWidgetsSourceCapability, q as parseProfileBrokerId, rt as object, st as EventCategory, tt as literal, w as maskUrlCredentials, z as DeviceFeature } from "../dist-DKeNH_5z.mjs";
 import { n as profileForStreamId } from "../remote-restream-BeHi78PZ.mjs";
-import { t as createFileDataPlaneHandler } from "../model-download-service-C-IHWnXx-3Mmeob3l.mjs";
+import { t as createFileDataPlaneHandler } from "../model-download-service-Cp9f4dk6-0wh7OK3s.mjs";
 import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
 import { pathToFileURL } from "node:url";
@@ -23,12 +23,28 @@ import { EventEmitter } from "node:events";
 //#region src/stream-broker/embed-file-handler.ts
 /** Build a `(req, res)` handler serving the embed bundle at `root` with SPA fallback.
 *  Web MIME types (`.html`/`.js`/`.css`/…) come from the core handler's defaults. */
+/** Cache-Control for the CONTENT-HASHED vite assets (`/assets/index-<hash>.js`):
+*  a new build changes the filename, so the old bytes can cache forever. The
+*  entry `index.html` keeps the handler's default `no-cache`. Without this the
+*  WebView re-downloaded the ~1.5MB bundle on EVERY player open — a real chunk
+*  of the "live stream takes ~10s to start" cold-start cost (worse on 4G). */
+var IMMUTABLE_CACHE = "public, max-age=31536000, immutable";
 function createEmbedSpaHandler(root) {
-	const fileHandler = createFileDataPlaneHandler({ getRoots: () => [root] });
+	const fileHandler = createFileDataPlaneHandler({
+		getRoots: () => [root],
+		cacheControl: (rel) => rel.startsWith("assets/") ? IMMUTABLE_CACHE : void 0
+	});
 	return (req, res) => {
 		const [pathPart = "/", query] = (req.url ?? "/").split("?");
 		const lastSegment = pathPart.split("/").pop() ?? "";
 		if (pathPart === "/" || pathPart === "" || !lastSegment.includes(".")) req.url = query !== void 0 ? `/index.html?${query}` : "/index.html";
+		else if (pathPart.startsWith("/assets/")) {
+			const origWriteHead = res.writeHead.bind(res);
+			res.writeHead = ((status, headers) => origWriteHead(status, {
+				...headers,
+				"cache-control": IMMUTABLE_CACHE
+			}));
+		}
 		return fileHandler(req, res);
 	};
 }
@@ -2234,6 +2250,133 @@ var H264Repacketizer = class {
 	}
 };
 //#endregion
+//#region src/stream-broker/webrtc/paced-rtp-replay.ts
+var PACED_REPLAY_DEFAULTS = {
+	singleShotMax: 64,
+	tickMs: 5,
+	targetDurationMs: 300,
+	minChunkSize: 32,
+	maxChunkSize: 128
+};
+var defaultSchedule = (fn, ms) => {
+	const t = setTimeout(fn, ms);
+	return () => clearTimeout(t);
+};
+/**
+* Compute the per-tick chunk size for a burst of `total` packets: enough to
+* drain within `targetDurationMs` at one chunk per `tickMs`, clamped to
+* [minChunkSize, maxChunkSize]. Bursts ≤ `singleShotMax` are one chunk.
+*/
+function computeReplayChunkSize(total, tuning) {
+	if (total <= tuning.singleShotMax) return Math.max(total, 1);
+	const maxTicks = Math.max(1, Math.floor(tuning.targetDurationMs / tuning.tickMs));
+	const ideal = Math.ceil(total / maxTicks);
+	return Math.min(tuning.maxChunkSize, Math.max(tuning.minChunkSize, ideal));
+}
+/**
+* One in-flight paced replay. Create per burst; not reusable after
+* completion or abort.
+*/
+var PacedRtpReplay = class {
+	send;
+	onDone;
+	tuning;
+	schedule;
+	now;
+	queue = [];
+	cancelTimer = null;
+	started = false;
+	finished = false;
+	startedAt = 0;
+	chunkSize = 0;
+	initialPackets = 0;
+	enqueuedLive = 0;
+	sentCount = 0;
+	chunkCount = 0;
+	constructor(send, onDone, options) {
+		this.send = send;
+		this.onDone = onDone;
+		this.tuning = {
+			...PACED_REPLAY_DEFAULTS,
+			...options?.tuning
+		};
+		this.schedule = options?.schedule ?? defaultSchedule;
+		this.now = options?.now ?? Date.now;
+	}
+	/** True while packets remain to be drained (live packets must be enqueued,
+	*  not sent directly, to preserve order). */
+	get active() {
+		return this.started && !this.finished;
+	}
+	/**
+	* Begin the replay: sends the first chunk synchronously, then paces the
+	* rest. Calling `start` more than once is a no-op.
+	*/
+	start(initial) {
+		if (this.started) return;
+		this.started = true;
+		this.startedAt = this.now();
+		this.initialPackets = initial.length;
+		this.queue = [...initial];
+		this.chunkSize = computeReplayChunkSize(initial.length, this.tuning);
+		this.drainChunk();
+	}
+	/**
+	* Append a live packet behind the still-queued replay tail. No-op (returns
+	* false) when the replay is not active — the caller must then send the
+	* packet directly.
+	*/
+	enqueue(item) {
+		if (!this.active) return false;
+		this.queue.push(item);
+		this.enqueuedLive++;
+		return true;
+	}
+	/** Cancel the replay: pending packets are dropped, `onDone` fires with
+	*  `aborted: true`. Safe to call multiple times / before `start`. */
+	abort() {
+		if (this.finished) return;
+		if (!this.started) {
+			this.started = true;
+			this.startedAt = this.now();
+		}
+		this.finish(true);
+	}
+	drainChunk() {
+		if (this.finished) return;
+		this.chunkCount++;
+		const n = Math.min(this.chunkSize, this.queue.length);
+		for (let i = 0; i < n; i++) if (this.send(this.queue[i])) this.sentCount++;
+		this.queue = this.queue.slice(n);
+		if (this.queue.length === 0) {
+			this.finish(false);
+			return;
+		}
+		this.cancelTimer = this.schedule(() => {
+			this.cancelTimer = null;
+			this.drainChunk();
+		}, this.tuning.tickMs);
+	}
+	finish(aborted) {
+		if (this.finished) return;
+		this.finished = true;
+		if (this.cancelTimer) {
+			this.cancelTimer();
+			this.cancelTimer = null;
+		}
+		this.queue = [];
+		this.onDone({
+			packets: this.initialPackets,
+			enqueuedLive: this.enqueuedLive,
+			sent: this.sentCount,
+			chunks: this.chunkCount,
+			chunkSize: this.chunkSize,
+			durationMs: this.now() - this.startedAt,
+			aborted
+		});
+	}
+};
+//#endregion
 //#region src/stream-broker/webrtc/webrtc-fallback-profile.ts
 /**
 * Hardcoded fallback encode profile for the WebRTC viewer path. Used only
@@ -2839,6 +2982,10 @@ var AdaptiveSession = class AdaptiveSession {
 	/** Broker source-RTP pre-buffer accessor + one-shot replay guard. */
 	rtpBootstrap;
 	rtpBootstrapDone = false;
+	/** In-flight paced pre-buffer replay (instant-start bootstrap or PLI
+	*  recovery). While active, live source-RTP packets are enqueued behind
+	*  the replay tail to preserve packet order. Aborted on close/rebind. */
+	activeRtpReplay = null;
 	/**
 	* Trickle ICE: the server's locally-gathered candidates, buffered as werift
 	* surfaces them via `onIceCandidate`. The client polls `getIceCandidates`
@@ -2870,6 +3017,8 @@ var AdaptiveSession = class AdaptiveSession {
 	/** Drop the repacketizer + bootstrap/sync state so a newly bound source
 	*  stream re-seeds its SPS/PPS and replays instant-start cleanly. */
 	resetRepacketizer() {
+		this.activeRtpReplay?.abort();
+		this.activeRtpReplay = null;
 		this.h264Repacketizer = null;
 		this.h265Repacketizer = null;
 		this.videoRtpSynced = false;
@@ -3570,6 +3719,10 @@ var AdaptiveSession = class AdaptiveSession {
 			this.feedAbort.abort();
 			this.feedAbort = null;
 		}
+		if (this.activeRtpReplay) {
+			this.activeRtpReplay.abort();
+			this.activeRtpReplay = null;
+		}
 		try {
 			await this.source.return(void 0);
 		} catch {}
@@ -3667,18 +3820,11 @@ var AdaptiveSession = class AdaptiveSession {
 			this.rtpBootstrapDone = true;
 			const bootstrap = this.rtpBootstrap?.() ?? [];
 			if (bootstrap.length > 0) {
-				let sent = 0;
-				for (const b of bootstrap) if (this.sendSourceRtpPacket(b, codec)) sent++;
-				this.logger.info("replayed source-RTP pre-buffer (instant start)", { meta: {
-					phase: "session",
-					sessionId: this.sessionId,
-					codec,
-					packets: bootstrap.length,
-					sent
-				} });
+				this.startPacedRtpReplay(bootstrap, codec, "replayed source-RTP pre-buffer (instant start)");
 				return;
 			}
 		}
+		if (this.activeRtpReplay?.active && this.activeRtpReplay.enqueue(rtpData)) return;
 		this.sendSourceRtpPacket(rtpData, codec);
 	}
 	/**
@@ -3768,6 +3914,35 @@ var AdaptiveSession = class AdaptiveSession {
 		}
 		return sent;
 	}
+	/**
+	* Start a paced replay of a source-RTP pre-buffer burst (instant-start
+	* bootstrap or PLI recovery). The first chunk goes out synchronously; the
+	* rest drain on a short timer cadence (see `PACED_REPLAY_DEFAULTS`:
+	* 5 ms ticks, 32-128 packets/tick scaled to finish within ~300 ms).
+	* An already-running replay is aborted first (goLive re-bootstrap). The
+	* completion log preserves the historical message and adds pacing stats.
+	*/
+	startPacedRtpReplay(bootstrap, codec, logMessage) {
+		this.activeRtpReplay?.abort();
+		const replay = new PacedRtpReplay((pkt) => this.sendSourceRtpPacket(pkt, codec), (stats) => {
+			if (this.activeRtpReplay === replay) this.activeRtpReplay = null;
+			const meta = {
+				phase: "session",
+				sessionId: this.sessionId,
+				codec,
+				packets: stats.packets,
+				sent: stats.sent,
+				chunks: stats.chunks,
+				chunkSize: stats.chunkSize,
+				durationMs: stats.durationMs,
+				enqueuedLive: stats.enqueuedLive
+			};
+			if (stats.aborted) this.logger.debug(`${logMessage} — aborted mid-replay`, { meta });
+			else this.logger.info(logMessage, { meta });
+		});
+		this.activeRtpReplay = replay;
+		replay.start(bootstrap);
+	}
 	setupPliListener() {
 		const sender = this.videoSender;
 		if (!sender) return;
@@ -3806,20 +3981,19 @@ var AdaptiveSession = class AdaptiveSession {
 		const now = Date.now();
 		if (now - this.lastPliResendAt < AdaptiveSession.PLI_RESEND_COOLDOWN_MS) return;
 		this.lastPliResendAt = now;
+		if (this.activeRtpReplay?.active) {
+			this.logger.debug("PLI received — paced pre-buffer replay already in flight", { meta: {
+				phase: "session",
+				sessionId: this.sessionId
+			} });
+			return;
+		}
 		if (this.rtpBootstrap) {
 			const codec = this.negotiatedCodec;
 			if (codec === "H264" || codec === "H265") {
 				const bootstrap = this.rtpBootstrap();
 				if (bootstrap.length > 0) {
-					let sent = 0;
-					for (const b of bootstrap) if (this.sendSourceRtpPacket(b, codec)) sent++;
-					this.logger.info("PLI received — replayed source-RTP pre-buffer", { meta: {
-						phase: "session",
-						sessionId: this.sessionId,
-						codec,
-						packets: bootstrap.length,
-						sent
-					} });
+					this.startPacedRtpReplay(bootstrap, codec, "PLI received — replayed source-RTP pre-buffer");
 					return;
 				}
 			}
@@ -16665,6 +16839,73 @@ var AdaptiveController = class {
 	}
 };
 //#endregion
+//#region src/stream-broker/recorded/control-protocol.ts
+var ControlMessageSchema = discriminatedUnion("t", [
+	object({
+		t: literal("playRecorded"),
+		deviceId: number(),
+		epoch: number(),
+		profile: string()
+	}),
+	object({
+		t: literal("seek"),
+		epoch: number()
+	}),
+	object({
+		t: literal("scrubCommit"),
+		epoch: number()
+	}),
+	object({
+		t: literal("setRate"),
+		rate: number().min(0).max(4)
+	}),
+	object({
+		t: literal("stepFrame"),
+		dir: union([literal(1), literal(-1)])
+	}),
+	object({ t: literal("goLive") }),
+	object({
+		t: literal("setProfile"),
+		profile: string()
+	})
+]);
+/**
+* Clamp a requested playback rate onto the supported domain: {0} ∪ [0.25, 4].
+* 0 (and any non-finite / non-positive input) pauses; anything else is a
+* continuous rate clamped into [0.25, 4]. Single server-side authority — the
+* feeder applies it to every inbound `setRate`.
+*/
+function clampPlaybackRate(rate) {
+	if (!Number.isFinite(rate) || rate <= 0) return 0;
+	return Math.min(4, Math.max(.25, rate));
+}
+var ServerMessageSchema = discriminatedUnion("t", [object({
+	t: literal("state"),
+	state: _enum([
+		"live",
+		"loading",
+		"playing",
+		"paused",
+		"gap",
+		"ended",
+		"error"
+	])
+}), object({
+	t: literal("position"),
+	epochMs: number()
+})]);
+function parseControlMessage(raw) {
+	try {
+		const parsed = ControlMessageSchema.safeParse(JSON.parse(raw));
+		return parsed.success ? parsed.data : null;
+	} catch {
+		return null;
+	}
+}
+function serializeServerMessage(msg) {
+	return JSON.stringify(ServerMessageSchema.parse(msg));
+}
+//#endregion
 //#region src/stream-broker/recorded/feed-clock.ts
 /**
 * Maps arbitrary, possibly-resetting source PTS (ms) onto a strictly increasing
@@ -16672,26 +16913,70 @@ var AdaptiveController = class {
 * seek the output keeps advancing while the source anchor re-bases, so
 * per-segment PTS resets never rewind the track. Video and audio use SEPARATE
 * instances that `markSeek()` together to stay A/V aligned across boundaries.
+*
+* Playback rate: `setRate(r)` divides SOURCE elapsed time by `r` on the output
+* timeline (2× → half the output spacing → the receiver plays frames twice as
+* fast). A mid-stream rate change re-anchors at the last stamped point so the
+* output stays continuous and monotonic across the change (like `markSeek`,
+* but without discarding source continuity).
 */
 var MonotonicClock = class {
 	rateHz;
 	srcAnchorMs = null;
+	lastSrcMs = null;
 	outBaseMs = 0;
 	lastOutMs = 0;
+	rate = 1;
 	constructor(rateHz = 9e4) {
 		this.rateHz = rateHz;
 	}
 	stamp(srcPtsMs) {
 		if (this.srcAnchorMs === null) this.srcAnchorMs = srcPtsMs;
-		const elapsed = Math.max(0, srcPtsMs - this.srcAnchorMs);
+		this.lastSrcMs = srcPtsMs;
+		const elapsed = Math.max(0, (srcPtsMs - this.srcAnchorMs) / this.rate);
 		const outMs = this.outBaseMs + elapsed;
 		this.lastOutMs = Math.max(this.lastOutMs, outMs);
 		return Math.round(this.lastOutMs * this.rateHz / 1e3);
 	}
-	/** Call before feeding a new segment after a seek. */
+	/**
+	* Call before feeding a new CONTIGUOUS segment (the per-segment PTS reset at
+	* a boundary during forward playback, or a paused frame-step re-feed).
+	* Advances the output ~1 frame past the last emitted ts. The nudge lives in
+	* the OUTPUT domain, so it scales with the rate factor (at 2× a source frame
+	* occupies ~16.5 output ms) to preserve the perceived frame cadence across
+	* the boundary.
+	*/
 	markSeek() {
-		this.outBaseMs = this.lastOutMs + 33;
+		this.markDiscontinuity(33 / this.rate);
+	}
+	/**
+	* Call before feeding a NON-contiguous position (a seek / scrub commit).
+	* Like `markSeek` but with an explicit, caller-chosen output gap: a seek must
+	* be unmistakable to the receiver — with only a ~1-frame nudge, stale
+	* in-flight access units from the aborted feed and the new GOP look like one
+	* contiguous stream, and a lost IDR then smears the new deltas onto pre-seek
+	* references. The gap is an intentional discontinuity, so it is NOT
+	* rate-scaled.
+	*/
+	markDiscontinuity(gapMs) {
+		this.outBaseMs = this.lastOutMs + gapMs;
 		this.srcAnchorMs = null;
+		this.lastSrcMs = null;
+	}
+	/**
+	* Change the playback-rate factor (r > 0; 0/negative/redundant are no-ops —
+	* "paused" is the absence of stamping, not a clock rate). Re-anchors both the
+	* source and output baselines at the last stamped point so already-emitted
+	* timestamps stay fixed and the next stamp continues monotonically at the new
+	* rate.
+	*/
+	setRate(rate) {
+		if (!(rate > 0) || rate === this.rate) return;
+		if (this.srcAnchorMs !== null && this.lastSrcMs !== null) {
+			this.outBaseMs = this.lastOutMs;
+			this.srcAnchorMs = this.lastSrcMs;
+		}
+		this.rate = rate;
 	}
 };
 //#endregion
@@ -16705,23 +16990,54 @@ var POSITION_INTERVAL_MS = 1e3;
 * keeping seeks responsive without per-frame drift.
 */
 var WAIT_TICK_MS = 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
+* pace loop's last access units are already in the RTP send path when the new
+* feed starts; with only the ~1-frame (+33 ms) continuation nudge the receiver
+* sees ONE contiguous timestamp stream, so if any packet of the new feed's IDR
+* is lost in the seek burst, the decoder decodes the following deltas against
+* PRE-seek reference frames — the classic wrong-reference smear. A 250 ms jump
+* makes the seek an unambiguous stream discontinuity: stale lower-ts units
+* 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 RecordedFeeder = class {
 	deps;
 	clock = new MonotonicClock();
 	/** Separate 8 kHz clock for PCMU audio; re-anchored together with video. */
 	audioClock = new MonotonicClock(8e3);
 	clockHasAdvanced = false;
+	/** Playback rate: 0 (paused) or a continuous factor in [0.25, 4]. */
 	rate = 1;
 	disposed = false;
 	seekToken = 0;
 	advanceToken = 0;
 	cursorMs = 0;
 	positionTimer = null;
+	/**
+	* The demuxed segment "under the cursor" — the frame-step working set. Kept
+	* in lockstep with every feed path (seek burst, paused partial feed, pacing)
+	* so a pause at any moment can step from the exact last-fed frame.
+	*/
+	currentSegment = null;
+	/** Index (into `currentSegment.aus`) of the last video AU fed; -1 = none. */
+	lastFedVideoIdx = -1;
+	/** Serializes frame steps: a step arriving while one is in flight is dropped. */
+	stepInFlight = false;
+	/**
+	* Target epoch of the seek currently in flight (null when none). A rate
+	* change re-enters via seek(); while a seek is still resolving, `cursorMs`
+	* is stale — re-seeking the in-flight target instead avoids snapping back to
+	* the pre-seek position when the client changes rate right after a seek.
+	*/
+	inFlightSeekEpochMs = null;
 	constructor(deps) {
 		this.deps = deps;
 	}
 	/**
-	* Seek to an epoch and (if rate is 1) begin forward playback. Resolves after
+	* Seek to an epoch and (if rate > 0) begin forward playback. Resolves after
 	* the FIRST located segment is fed; the forward `advance` loop is started
 	* fire-and-forget so seek never blocks on its pacing. Latest-wins: a newer
 	* seek bumps the token and silently abandons this one.
@@ -16729,11 +17045,12 @@ var RecordedFeeder = class {
 	async seek(epochMs) {
 		const token = ++this.seekToken;
 		this.advanceToken++;
+		this.inFlightSeekEpochMs = epochMs;
 		try {
 			this.deps.onState("loading");
 			if (this.clockHasAdvanced) {
-				this.clock.markSeek();
-				this.audioClock.markSeek();
+				this.clock.markDiscontinuity(SEEK_DISCONTINUITY_MS);
+				this.audioClock.markDiscontinuity(SEEK_DISCONTINUITY_MS);
 			}
 			const loc = await this.withTimeout(this.deps.locate({
 				deviceId: this.deps.deviceId,
@@ -16742,93 +17059,274 @@ var RecordedFeeder = class {
 			}));
 			if (this.disposed || token !== this.seekToken) return;
 			if (loc.kind === "gap") {
+				this.currentSegment = null;
+				this.lastFedVideoIdx = -1;
 				this.stopPositionReports();
 				this.deps.onState("gap");
 				return;
 			}
 			this.cursorMs = loc.startMs;
-			await this.feedSegment(loc.startMs, token);
-			if (this.disposed || token !== this.seekToken) return;
-			this.cursorMs = loc.startMs + loc.durMs;
-			this.deps.onState(this.rate === 0 ? "paused" : "playing");
+			const loaded = await this.loadAus(loc.startMs, this.rate !== 0);
+			if (this.disposed || token !== this.seekToken || loaded === null) return;
+			this.feedPrefix(loc, loaded.video, epochMs);
+			if (this.rate === 0) {
+				this.deps.onState("paused");
+				this.deps.onPosition(this.cursorMs);
+				this.startPositionReports();
+				return;
+			}
+			this.deps.onState("playing");
+			this.deps.onPosition(this.cursorMs);
 			this.startPositionReports();
-			if (this.rate === 1) this.startAdvance();
+			const lastFedAu = this.lastFedVideoIdx >= 0 ? loaded.video[this.lastFedVideoIdx] : void 0;
+			this.startAdvance({
+				prepared: {
+					startMs: loc.startMs,
+					durMs: loc.durMs,
+					aus: loaded.video,
+					audio: loaded.audio
+				},
+				resumeAfterPtsMs: lastFedAu ? lastFedAu.ptsMs : null
+			});
 		} catch {
 			if (!this.disposed && token === this.seekToken) {
 				this.stopPositionReports();
 				this.deps.onState("error");
 			}
+		} finally {
+			if (token === this.seekToken) this.inFlightSeekEpochMs = null;
 		}
 	}
-	/** Set playback rate. 0 pauses; 1 (re)starts the forward advance loop. */
+	/**
+	* Set playback rate. 0 pauses in place (the pacing loop aborts on its next
+	* guard check); any other value is clamped to [0.25, 4].
+	*
+	* Rate-change strategy (documented choice): every transition TO a non-zero
+	* rate — resume from pause AND a playing→playing rate change — re-enters via
+	* `seek(cursorMs)`. seek() bumps `advanceToken` up-front, which aborts any
+	* mid-segment pacing loop, then re-feeds the covering segment from its IDR
+	* (a burst — the decoder needs the GOP head) and restarts the advance loop
+	* pacing at the new rate. No in-place re-pacing of a half-delivered segment.
+	*/
 	setRate(rate) {
 		if (this.disposed) return;
-		if (rate === this.rate) return;
-		this.rate = rate;
-		if (rate === 0) this.stopPositionReports();
-		this.deps.onState(rate === 0 ? "paused" : "playing");
-		if (rate === 1) this.startAdvance();
+		const next = clampPlaybackRate(rate);
+		if (next === this.rate) return;
+		this.rate = next;
+		if (next === 0) {
+			this.stopPositionReports();
+			this.deps.onState("paused");
+			return;
+		}
+		this.clock.setRate(next);
+		this.seek(this.inFlightSeekEpochMs ?? this.cursorMs);
+	}
+	/**
+	* Feed exactly one frame forward (+1) or backward (-1). Only meaningful while
+	* paused over a segment (rate 0, recorded mode) — ignored otherwise. Forward
+	* at a segment end crosses into the next segment (gaps are skipped via the
+	* same lookahead the advance loop uses); backward at a segment start loads
+	* the PREVIOUS segment and lands on its last frame. Backward re-feeds from
+	* the nearest keyframe at-or-before the target so the decoder has a valid
+	* GOP head. Edge no-ops: forward past the end of the recording, backward
+	* into a gap/start of the recording, and a step while another cross-segment
+	* step is still in flight.
+	*/
+	stepFrame(dir) {
+		if (this.disposed || this.rate !== 0 || this.stepInFlight) return;
+		this.stepInFlight = true;
+		this.doStep(dir).catch(() => {}).finally(() => {
+			this.stepInFlight = false;
+		});
 	}
-	async feedSegment(startMs, token) {
-		const bytes = await this.withTimeout(this.deps.readBytes({
+	async doStep(dir) {
+		const seg = this.currentSegment;
+		if (!seg || seg.aus.length === 0) return;
+		const token = this.seekToken;
+		const gen = this.advanceToken;
+		if (dir === 1) {
+			const nextIdx = this.lastFedVideoIdx + 1;
+			if (nextIdx < seg.aus.length) {
+				this.feedOneAu(seg, nextIdx);
+				return;
+			}
+			const prepared = await this.prepareNext(seg.startMs + seg.durMs, gen);
+			if (prepared === null || prepared === "ended") return;
+			if (this.disposed || token !== this.seekToken || this.rate !== 0) return;
+			if (prepared.aus.length === 0) return;
+			if (this.clockHasAdvanced) {
+				this.clock.markSeek();
+				this.audioClock.markSeek();
+			}
+			this.currentSegment = {
+				startMs: prepared.startMs,
+				durMs: prepared.durMs,
+				aus: prepared.aus
+			};
+			this.feedOneAu(this.currentSegment, 0);
+			return;
+		}
+		if (this.lastFedVideoIdx > 0) {
+			this.refeedUpTo(seg, this.lastFedVideoIdx - 1);
+			return;
+		}
+		let loc = await this.withTimeout(this.deps.locate({
 			deviceId: this.deps.deviceId,
 			profile: this.deps.profile,
-			startMs
+			epochMs: seg.startMs - 1
 		}));
-		if (this.disposed || token !== this.seekToken) return;
-		const aus = await this.withTimeout(this.deps.demux(bytes));
-		if (this.disposed || token !== this.seekToken) return;
-		for (const au of aus) this.deps.sink.pushAccessUnit(au.data, this.clock.stamp(au.ptsMs), au.codec);
-		if (aus.length > 0) this.clockHasAdvanced = true;
-		await this.feedAudio(bytes, token);
-	}
-	/**
-	* Demux+transcode the segment's audio to PCMU and push it, re-stamped on the
-	* 8 kHz audio clock. Best-effort: audio NEVER blocks video — a demux/transcode
-	* failure or a video-only sink simply yields silence.
-	*/
-	async feedAudio(bytes, token) {
-		const demuxAudio = this.deps.demuxAudio;
-		const pushAudio = this.deps.sink.pushAudioPcmu;
-		if (!demuxAudio || !pushAudio) return;
-		let audio;
-		try {
-			audio = await this.withTimeout(demuxAudio(bytes));
-		} catch {
+		if (this.disposed || token !== this.seekToken || this.rate !== 0) return;
+		if (loc.kind === "gap" && loc.prevEndMs != null && loc.prevEndMs <= seg.startMs) {
+			loc = await this.withTimeout(this.deps.locate({
+				deviceId: this.deps.deviceId,
+				profile: this.deps.profile,
+				epochMs: loc.prevEndMs - 1
+			}));
+			if (this.disposed || token !== this.seekToken || this.rate !== 0) return;
+		}
+		if (loc.kind !== "segment" || loc.startMs >= seg.startMs) return;
+		const loaded = await this.loadAus(loc.startMs, false);
+		if (loaded === null || loaded.video.length === 0) return;
+		if (this.disposed || this.rate !== 0) return;
+		this.currentSegment = {
+			startMs: loc.startMs,
+			durMs: loc.durMs,
+			aus: loaded.video
+		};
+		this.refeedUpTo(this.currentSegment, this.currentSegment.aus.length - 1);
+	}
+	/**
+	* Clamp a frame-derived cursor into the segment's covered window
+	* [startMs, startMs + durMs). Real frames can outlive the muxed `durMs`
+	* (last pts − first pts ≥ durMs), and `startMs + durMs` itself is already
+	* inside the inter-segment crack — a cursor parked there makes the next
+	* `seek(cursorMs)` (resume/rate-change) locate a GAP and freeze playback.
+	*/
+	clampIntoSegment(seg, epochMs) {
+		return Math.min(Math.max(epochMs, seg.startMs), seg.startMs + seg.durMs - 1);
+	}
+	/** Push exactly one AU of `seg`, move the step cursor onto it, report position. */
+	feedOneAu(seg, idx) {
+		const au = seg.aus[idx];
+		const first = seg.aus[0];
+		if (!au || !first) return;
+		this.deps.sink.pushAccessUnit(au.data, this.clock.stamp(au.ptsMs), au.codec);
+		this.clockHasAdvanced = true;
+		this.lastFedVideoIdx = idx;
+		this.cursorMs = this.clampIntoSegment(seg, seg.startMs + (au.ptsMs - first.ptsMs));
+		this.deps.onPosition(this.cursorMs);
+	}
+	/**
+	* Backward-step render: re-feed from the nearest keyframe at-or-before
+	* `targetIdx` up TO `targetIdx` (decode needs the GOP head; the burst renders
+	* fast and the display lands exactly one frame earlier). Re-anchors the
+	* clocks first — the re-fed PTS run BEHIND the monotonic clock's anchor and
+	* would otherwise clamp into duplicate output timestamps.
+	*/
+	refeedUpTo(seg, targetIdx) {
+		const first = seg.aus[0];
+		const target = seg.aus[targetIdx];
+		if (!first || !target) return;
+		let fromIdx = 0;
+		for (let i = targetIdx; i >= 0; i--) if (seg.aus[i]?.keyframe) {
+			fromIdx = i;
+			break;
+		}
+		if (this.clockHasAdvanced) {
+			this.clock.markSeek();
+			this.audioClock.markSeek();
+		}
+		for (let i = fromIdx; i <= targetIdx; i++) {
+			const au = seg.aus[i];
+			if (au) this.deps.sink.pushAccessUnit(au.data, this.clock.stamp(au.ptsMs), au.codec);
+		}
+		this.clockHasAdvanced = true;
+		this.lastFedVideoIdx = targetIdx;
+		this.cursorMs = this.clampIntoSegment(seg, seg.startMs + (target.ptsMs - first.ptsMs));
+		this.deps.onPosition(this.cursorMs);
+	}
+	/**
+	* Seek prefix feed (decode priming): push only the AUs with
+	* `ptsMs − firstPtsMs ≤ requestedEpochMs − loc.startMs` — always at least the
+	* first (IDR-led) AU so the feed is never empty — then park the cursor at the
+	* requested epoch (clamped into the segment window). While paused this IS the
+	* feed (exact-frame render); at rate > 0 it primes the decoder up to the
+	* cursor and the advance loop paces the remainder. The demuxer contract
+	* guarantees `aus[0]` is the segment's params-fused IDR, so the prefix always
+	* starts at a keyframe.
+	*/
+	feedPrefix(loc, aus, requestedEpochMs) {
+		const clampedEpoch = Math.min(Math.max(requestedEpochMs, loc.startMs), loc.startMs + loc.durMs - 1);
+		this.currentSegment = {
+			startMs: loc.startMs,
+			durMs: loc.durMs,
+			aus
+		};
+		const first = aus[0];
+		if (!first) {
+			this.lastFedVideoIdx = -1;
+			this.cursorMs = clampedEpoch;
 			return;
 		}
-		if (this.disposed || token !== this.seekToken) return;
-		for (const au of audio) pushAudio.call(this.deps.sink, au.data, this.audioClock.stamp(au.ptsMs));
+		const offsetMs = requestedEpochMs - loc.startMs;
+		let lastIdx = 0;
+		for (let i = 1; i < aus.length; i++) {
+			const au = aus[i];
+			if (au && au.ptsMs - first.ptsMs <= offsetMs) lastIdx = i;
+			else break;
+		}
+		for (let i = 0; i <= lastIdx; i++) {
+			const au = aus[i];
+			if (au) this.deps.sink.pushAccessUnit(au.data, this.clock.stamp(au.ptsMs), au.codec);
+		}
+		this.clockHasAdvanced = true;
+		this.lastFedVideoIdx = lastIdx;
+		this.cursorMs = clampedEpoch;
 	}
 	/**
 	* Start (or restart) the single forward advance loop. Bumping `advanceToken`
 	* invalidates any loop already running, guaranteeing at most one survives.
+	* `initial` hands the loop the seek's already-loaded covering segment plus
+	* the prefix boundary, so pacing resumes FROM THE CURSOR instead of the loop
+	* re-locating (and thereby skipping) the segment under it.
 	*/
-	startAdvance() {
+	startAdvance(initial) {
 		const gen = ++this.advanceToken;
-		this.advanceLoop(gen).catch(() => {
+		this.advanceLoop(gen, initial).catch(() => {
 			if (!this.disposed && gen === this.advanceToken) {
 				this.stopPositionReports();
 				this.deps.onState("error");
 			}
 		});
 	}
-	async advanceLoop(gen) {
-		let prepared = await this.prepareNext(this.cursorMs, gen);
-		while (!this.disposed && gen === this.advanceToken && this.rate === 1) {
+	async advanceLoop(gen, initial) {
+		let prepared;
+		let resumeAfterPtsMs = null;
+		let isResumedSegment = false;
+		if (initial) {
+			prepared = initial.prepared;
+			resumeAfterPtsMs = initial.resumeAfterPtsMs;
+			isResumedSegment = true;
+		} else prepared = await this.prepareNext(this.cursorMs, gen);
+		while (!this.disposed && gen === this.advanceToken && this.rate > 0) {
 			if (prepared === null) return;
 			if (prepared === "ended") {
 				this.stopPositionReports();
 				this.deps.onState("ended");
 				return;
 			}
-			this.cursorMs = prepared.startMs;
-			if (this.clockHasAdvanced) {
-				this.clock.markSeek();
-				this.audioClock.markSeek();
+			if (isResumedSegment) {} else {
+				this.cursorMs = prepared.startMs;
+				if (this.clockHasAdvanced) {
+					this.clock.markSeek();
+					this.audioClock.markSeek();
+				}
 			}
 			const prefetch = this.prepareNext(prepared.startMs + prepared.durMs, gen);
-			if (await this.paceSegment(prepared, gen)) {
+			const aborted = await this.paceSegment(prepared, gen, resumeAfterPtsMs);
+			resumeAfterPtsMs = null;
+			isResumedSegment = false;
+			if (aborted) {
 				prefetch.catch(() => {});
 				return;
 			}
@@ -16839,45 +17337,67 @@ var RecordedFeeder = class {
 	/**
 	* Drip one prepared segment to the sink at its real frame cadence: build a
 	* single PTS-ordered schedule of the segment's video + audio access units and
-	* push each at `segmentStart + (pts - firstPts)` wall-clock time, sleeping
-	* between items with a drift-free absolute-time wait. RTP timestamps come from
-	* the SAME `clock.stamp` / `audioClock.stamp` calls as before — only delivery
-	* timing changes. Returns `true` if a seek/dispose/rate-change aborted pacing
-	* mid-segment (the caller must stop without advancing the cursor).
-	*/
-	async paceSegment(prepared, gen) {
-		const hasAudioSink = typeof this.deps.sink.pushAudioPcmu === "function";
+	* push each at `segmentStart + (pts - firstPts) / rate` wall-clock time,
+	* sleeping between items with a drift-free absolute-time wait. RTP timestamps
+	* come from the SAME `clock.stamp` / `audioClock.stamp` calls as before (the
+	* clock itself carries the rate factor) — only delivery timing changes.
+	* `resumeAfterPtsMs` (a resumed covering segment) paces only the items
+	* strictly after the seek prefix, over the segment's REMAINING window.
+	* Returns `true` if a seek/dispose/pause aborted pacing mid-segment (the
+	* caller must stop without advancing the cursor).
+	*/
+	async paceSegment(prepared, gen, resumeAfterPtsMs = null) {
+		const rate = this.rate;
+		const hasAudioSink = typeof this.deps.sink.pushAudioPcmu === "function" && rate === 1;
 		const schedule = [];
-		for (const au of prepared.aus) schedule.push({
+		for (const au of prepared.aus) if (resumeAfterPtsMs === null || au.ptsMs > resumeAfterPtsMs) schedule.push({
 			ptsMs: au.ptsMs,
 			video: au
 		});
-		if (hasAudioSink) for (const au of prepared.audio) schedule.push({
-			ptsMs: au.ptsMs,
-			audio: au
-		});
+		if (hasAudioSink) {
+			for (const au of prepared.audio) if (resumeAfterPtsMs === null || au.ptsMs > resumeAfterPtsMs) schedule.push({
+				ptsMs: au.ptsMs,
+				audio: au
+			});
+		}
 		schedule.sort((a, b) => {
 			if (a.ptsMs !== b.ptsMs) return a.ptsMs - b.ptsMs;
 			return (a.video ? 0 : 1) - (b.video ? 0 : 1);
 		});
-		if (schedule.length === 0) return await this.sleepUntil(performance.now() + prepared.durMs, gen);
-		const firstPtsMs = schedule[0].ptsMs;
+		this.currentSegment = {
+			startMs: prepared.startMs,
+			durMs: prepared.durMs,
+			aus: prepared.aus
+		};
+		let videoIdx = 0;
+		if (resumeAfterPtsMs === null) this.lastFedVideoIdx = -1;
+		else {
+			while (videoIdx < prepared.aus.length && prepared.aus[videoIdx].ptsMs <= resumeAfterPtsMs) videoIdx++;
+			this.lastFedVideoIdx = videoIdx - 1;
+		}
+		const firstVideoPtsMs = prepared.aus[0]?.ptsMs ?? 0;
+		const consumedMs = resumeAfterPtsMs === null ? 0 : Math.max(0, resumeAfterPtsMs - firstVideoPtsMs);
+		const remainingWindowMs = Math.max(0, prepared.durMs - consumedMs);
+		if (schedule.length === 0) return await this.sleepUntil(performance.now() + remainingWindowMs / rate, gen);
+		const baselinePtsMs = resumeAfterPtsMs ?? schedule[0].ptsMs;
 		const segmentStartWall = performance.now();
 		let pushedVideo = false;
 		for (const item of schedule) {
-			const targetWall = segmentStartWall + (item.ptsMs - firstPtsMs);
+			const targetWall = segmentStartWall + (item.ptsMs - baselinePtsMs) / rate;
 			if (await this.sleepUntil(targetWall, gen)) return true;
-			if (this.disposed || gen !== this.advanceToken || this.rate !== 1) return true;
+			if (this.disposed || gen !== this.advanceToken || this.rate === 0) return true;
 			if (item.video) {
 				this.deps.sink.pushAccessUnit(item.video.data, this.clock.stamp(item.video.ptsMs), item.video.codec);
 				pushedVideo = true;
+				this.lastFedVideoIdx = videoIdx++;
+				this.cursorMs = prepared.startMs + (item.video.ptsMs - firstVideoPtsMs);
 			} else if (item.audio) {
 				const pushAudio = this.deps.sink.pushAudioPcmu;
 				if (pushAudio) pushAudio.call(this.deps.sink, item.audio.data, this.audioClock.stamp(item.audio.ptsMs));
 			}
 		}
 		if (pushedVideo) this.clockHasAdvanced = true;
-		const segmentEndWall = segmentStartWall + prepared.durMs;
+		const segmentEndWall = segmentStartWall + remainingWindowMs / rate;
 		return await this.sleepUntil(segmentEndWall, gen);
 	}
 	/**
@@ -16885,11 +17405,13 @@ var RecordedFeeder = class {
 	* value). Re-derives the remaining interval each tick and caps each individual
 	* timeout so a long inter-frame gap can't delay seek/dispose responsiveness —
 	* the loop re-checks `gen === advanceToken` between ticks. Returns `true` if a
-	* dispose/seek/rate-change aborted the wait, so the caller stops pushing.
+	* dispose/seek/pause aborted the wait, so the caller stops pushing. (A rate
+	* CHANGE aborts via the gen guard — setRate re-enters through seek(), which
+	* bumps advanceToken; rate 0 is the direct pause abort.)
 	*/
 	async sleepUntil(targetWall, gen) {
 		for (;;) {
-			if (this.disposed || gen !== this.advanceToken || this.rate !== 1) return true;
+			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);
@@ -16937,8 +17459,9 @@ var RecordedFeeder = class {
 	/** Read + demux one segment's bytes into video (+ best-effort PCMU audio)
 	*  access units. Keyed on `seekToken` so a fresh seek aborts an in-flight load
 	*  (latest-wins). Returns null on abort. Audio demux failures yield [] (audio
-	*  never blocks video). */
-	async loadAus(startMs) {
+	*  never blocks video). `wantAudio: false` skips the audio transcode entirely
+	*  (paused scrubs would throw it away). */
+	async loadAus(startMs, wantAudio = true) {
 		const token = this.seekToken;
 		const bytes = await this.withTimeout(this.deps.readBytes({
 			deviceId: this.deps.deviceId,
@@ -16949,7 +17472,7 @@ var RecordedFeeder = class {
 		const video = await this.withTimeout(this.deps.demux(bytes));
 		if (this.disposed || token !== this.seekToken) return null;
 		let audio = [];
-		if (this.deps.demuxAudio && this.deps.sink.pushAudioPcmu) {
+		if (wantAudio && this.deps.demuxAudio && this.deps.sink.pushAudioPcmu) {
 			try {
 				audio = await this.withTimeout(this.deps.demuxAudio(bytes));
 			} catch {
@@ -16999,59 +17522,6 @@ var RecordedFeeder = class {
 	}
 };
 //#endregion
-//#region src/stream-broker/recorded/control-protocol.ts
-var ControlMessageSchema = discriminatedUnion("t", [
-	object({
-		t: literal("playRecorded"),
-		deviceId: number(),
-		epoch: number(),
-		profile: string()
-	}),
-	object({
-		t: literal("seek"),
-		epoch: number()
-	}),
-	object({
-		t: literal("scrubCommit"),
-		epoch: number()
-	}),
-	object({
-		t: literal("setRate"),
-		rate: union([literal(0), literal(1)])
-	}),
-	object({ t: literal("goLive") }),
-	object({
-		t: literal("setProfile"),
-		profile: string()
-	})
-]);
-var ServerMessageSchema = discriminatedUnion("t", [object({
-	t: literal("state"),
-	state: _enum([
-		"live",
-		"loading",
-		"playing",
-		"paused",
-		"gap",
-		"ended",
-		"error"
-	])
-}), object({
-	t: literal("position"),
-	epochMs: number()
-})]);
-function parseControlMessage(raw) {
-	try {
-		const parsed = ControlMessageSchema.safeParse(JSON.parse(raw));
-		return parsed.success ? parsed.data : null;
-	} catch {
-		return null;
-	}
-}
-function serializeServerMessage(msg) {
-	return JSON.stringify(ServerMessageSchema.parse(msg));
-}
-//#endregion
 //#region src/stream-broker/recorded/timeline-session.ts
 /**
 * Per-viewer coordinator over one broker WebRTC session. Owns the playback mode
@@ -17084,6 +17554,9 @@ var TimelineSession = class {
 			case "setRate":
 				this.feeder?.setRate(msg.rate);
 				break;
+			case "stepFrame":
+				if (this.mode === "recorded") this.feeder?.stepFrame(msg.dir);
+				break;
 			case "setProfile":
 				this.profile = msg.profile;
 				if (this.mode === "recorded") this.enterRecorded();