@camstack/addon-pipeline 1.2.274 → 1.2.276

package/dist/stream-broker/index.mjs

@@ -1,10 +1,10 @@
 import { r as __toESM } from "../chunk-DnnnRqeS.mjs";
-import { $t as createEvent, B as cameraStreamsCapability, Bt as webrtcSessionCapability, Cn as union, D as RATE_CONTROL_RELAXED, F as addonWidgetsSourceCapability, G as deriveBatteryPresence, Gt as invocationFromEncodeProfile, H as createLogChannelsProvider, Ht as AUDIO_PRESETS, It as streamBrokerCapability, Jt as BaseAddon, Kt as isSoftwareDecode, M as RingBuffer, O as RATE_CONTROL_TIGHT, Sn as string, U as declareLogChannel, V as createHwAccelCache, Vt as errMsg, Wt as buildFfmpegArgs$1, X as egressTransportFromRequest, Xt as DeviceFeature, Y as egressTranscodeSharingKey, Yt as CAM_PROFILE_ORDER, Zt as DeviceType, _ as EncodeProfileSchema, _n as literal, an as makeProfileBrokerId, b as G711_SCALE_CORRECTION_DB, ct as logChannelsCapability, fn as _enum, hn as discriminatedUnion, i as BatteryStatusSchema, in as isEvent, kt as resolveEgressDecodeHwAccel, ln as parseProfileBrokerId, mn as boolean, nn as expandAudioChunkToF32le, on as makeSourceBrokerId, pn as array, qt as BOOT_RECOVERY_BACKOFF_MS, sn as nodePin, st as loadContributionCapability, ut as maskUrlCredentials, vn as number, wn as EventCategory, wt as rankStreams, xn as record, yn as object, z as batteryCapability } from "../dist-g5MfpiBh.mjs";
-import { i as NO_COST_CLAIM, n as Fmp4FragmentChild, o as probeFfmpegBinary, r as Fmp4FragmentPlane, t as ChildCostRegistry } from "../node-BXsHQH5h.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-C1pCVJk7.mjs";
+import { i as NO_COST_CLAIM, n as Fmp4FragmentChild, o as probeFfmpegBinary, r as Fmp4FragmentPlane, t as ChildCostRegistry } from "../node--UY0iepi.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-sYP_jndp.mjs";
+import { i as require_mp4box_all, n as demuxSegmentPreferJs, r as runFfmpegOnce, t as demuxSegmentFullJs } from "../segment-demux-js-B0_aAzN0.mjs";
 import { createRequire } from "node:module";
 import * as os from "node:os";
 import { networkInterfaces, tmpdir } from "node:os";
@@ -26566,6 +26566,21 @@ var ControlMessageSchema = discriminatedUnion("t", [
 		epoch: number(),
 		profile: string()
 	}),
+	object({
+		t: literal("playClip"),
+		deviceId: number(),
+		clipId: string().min(1),
+		offsetMs: number().min(0),
+		/**
+		* Which TWIN of the clip — the vendor's own quality pair, on the one
+		* quality scale the system has. `auto` is deliberately not in
+		* `CamProfileSchema`'s domain here for the same reason
+		* `videoclips.getClipPlayback` refuses it: a stored file has no broker
+		* session to resolve an adaptive tier against. Absent ⇒ the provider's own
+		* default; never invented here.
+		*/
+		profile: CamProfileSchema.optional()
+	}),
 	object({
 		t: literal("seek"),
 		epoch: number()
@@ -29885,6 +29900,18 @@ var TimelineSession = class {
 	* old recorded position is not where the viewer is coming from.
 	*/
 	lastPositionMs = null;
+	/**
+	* The clip the pointer is on, or `null` when the recorded source is the
+	* recorder's own footage.
+	*
+	* It is deliberately NOT a third `mode`. Clip playback IS recorded mode with
+	* a different byte source, so `currentMode` still reads `recorded` and every
+	* invariant built on it holds unchanged — the adaptive ladder still suspends
+	* itself while the pointer is off live, and `goLive` still leaves in one
+	* dispatch (D570's go-live terminator: a mode `GO_LIVE` cannot leave is a
+	* loop, and the cheapest way not to have one is not to add the mode).
+	*/
+	clip = null;
 	constructor(deps) {
 		this.deps = deps;
 		deps.session.setLiveFeedGate(false);
@@ -29903,13 +29930,26 @@ var TimelineSession = class {
 		this.emitLiveProfile();
 		switch (msg.t) {
 			case "playRecorded":
+				this.leaveClip();
 				this.requestedProfile = msg.profile;
 				await this.playAt(msg.epoch, msg.profile, { travelFromMs: this.lastPositionMs });
 				break;
+			case "playClip":
+				await this.playClip(msg.deviceId, msg.clipId, msg.profile ?? null, msg.offsetMs);
+				break;
 			case "seek":
+				if (this.clip) {
+					await this.feeder?.seek(msg.epoch);
+					break;
+				}
 				await this.playAt(msg.epoch, this.requestedProfile, { travelFromMs: this.lastPositionMs });
 				break;
 			case "scrubCommit":
+				if (this.clip) {
+					if (msg.dragId !== void 0) await this.feeder?.seek(msg.epoch, { dragId: msg.dragId });
+					else await this.feeder?.seek(msg.epoch);
+					break;
+				}
 				if (msg.dragId !== void 0) await this.playAt(msg.epoch, this.requestedProfile, { dragId: msg.dragId });
 				else await this.playAt(msg.epoch, this.requestedProfile);
 				break;
@@ -29935,6 +29975,14 @@ var TimelineSession = class {
 				if (this.mode === "recorded") this.feeder?.stepFrame(msg.dir);
 				break;
 			case "setProfile":
+				if (this.clip) {
+					this.deps.onLog?.("clip playback: setProfile ignored — a clip file has no recorded tier", {
+						deviceId: this.clip.deviceId,
+						clipId: this.clip.clipId,
+						requested: msg.profile
+					});
+					break;
+				}
 				this.requestedProfile = msg.profile;
 				if (msg.profile === this.profile) break;
 				this.profile = msg.profile;
@@ -29953,12 +30001,52 @@ var TimelineSession = class {
 		this.feeder?.dispose();
 		this.deps.session.setLiveFeedGate(true);
 		this.mode = "recorded";
-		const feeder = this.deps.makeFeeder(this.profile);
+		const clip = this.clip;
+		const makeClip = this.deps.makeClipFeeder;
+		const feeder = clip && makeClip ? makeClip({ handle: clip }) : this.deps.makeFeeder(this.profile);
 		if (this.rate !== 1) feeder.setRate(this.rate);
 		this.feeder = feeder;
 		return feeder;
 	}
 	/**
+	* Put the pointer on a clip file: same track, same feeder, same control
+	* protocol, on the clip's own axis.
+	*
+	* A session with no clip byte source REFUSES by name — it never gates the
+	* live feed, never builds a feeder and never leaves the operator on a frozen
+	* frame with no explanation (D391: the branch that accepts work and produces
+	* nothing is the same branch as the one that drops it).
+	*/
+	async playClip(deviceId, clipId, profile, offsetMs) {
+		if (!this.deps.makeClipFeeder) {
+			this.deps.onLog?.("clip playback: refused — no clip byte source wired on this session (videoclips.readClipBytes absent)", {
+				deviceId,
+				clipId,
+				profile,
+				offsetMs
+			});
+			this._emitState("error");
+			return;
+		}
+		this.clip = {
+			deviceId,
+			clipId,
+			profile
+		};
+		this.lastPositionMs = null;
+		await this.enterRecorded().seek(offsetMs);
+	}
+	/** Drop the clip pointer. Every path back to the recorder's own footage — a
+	*  `playRecorded` and `goLive` — goes through here, so there is exactly one
+	*  place that can forget to. */
+	leaveClip() {
+		if (!this.clip) return;
+		this.clip = null;
+		this.feeder?.dispose();
+		this.feeder = null;
+		this.mode = "live";
+	}
+	/**
 	* Play recorded footage at `epochMs`. If `locate` is wired and the requested
 	* profile has no segment, try high → mid → low so events-mode cameras that
 	* only kept one tier still play.
@@ -30049,6 +30137,7 @@ var TimelineSession = class {
 		}));
 	}
 	goLive() {
+		this.clip = null;
 		this.feeder?.dispose();
 		this.feeder = null;
 		this.lastPositionMs = null;
@@ -30092,6 +30181,331 @@ var TimelineSession = class {
 	}
 };
 //#endregion
+//#region src/stream-broker/recorded/clip-mp4-index.ts
+/**
+* The sample index for a CLIP FILE, so a clip can be another position of the
+* recorded source pointer (D575).
+*
+* `RecordedFeeder` asks its byte source two questions — "is there a segment at
+* `epochMs`?" and "give me its bytes" — and the recorder answers both from the
+* segment's own `mfra`. A clip is a progressive `+faststart` MP4: it has a
+* `moov` at the FRONT and no `mfra` at all, so the time→sample map has to be
+* read out of `stbl` instead. That is what this module does, and it is the only
+* place in the clip path that parses MP4 structure.
+*
+* **It is a TIME index, not a byte index, and that is deliberate.** The
+* offsets in a progressive `moov` (`stco`/`stsc`) are absolute to the WHOLE
+* file, so a GOP-ranged slice of one is not a standalone-demuxable MP4 — making
+* it one means rewriting `stbl`, i.e. a remux. A clip arrives whole and
+* already compressed (one bounded by-handle fetch, D9/D18), so the file IS its
+* byte range, exactly as `RecordedFeederDeps.readGop` says of the playback
+* path. Parsing offsets nobody reads would be a leftover describing a design
+* this slice does not have.
+*
+* What the index IS for:
+* 1. **The gate.** A file with no usable sample table cannot join the recorded
+*    path, and is refused BY NAME rather than served as a zero-length
+*    timeline. Measured 2026-09-20: an HKSV clip has `mvhd.duration = 0`,
+*    `mdhd.duration = 0`, no `sidx` and no `mfra` — ffmpeg writes the trailer
+*    only on close and the tee cuts like a pipe.
+* 2. **The file-relative timeline.** `durationMs` is the segment span the
+*    feeder plays and the bound `ended` is decided on; `firstSyncMs` is where a
+*    seek before the first keyframe snaps to.
+*/
+var FOURCC_LENGTH = 4;
+var BOX_HEADER_LENGTH = 8;
+var LARGE_SIZE_HEADER_LENGTH = 16;
+/**
+* Walk the direct children of `[start, end)`. Returns `null` when the region is
+* 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) {
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const out = [];
+	let off = start;
+	while (off + BOX_HEADER_LENGTH <= end) {
+		const declared = view.getUint32(off);
+		let type = "";
+		for (let i = 0; i < FOURCC_LENGTH; i++) type += String.fromCharCode(bytes[off + 4 + i] ?? 0);
+		let size = declared;
+		let contentStart = off + BOX_HEADER_LENGTH;
+		if (declared === 1) {
+			if (off + LARGE_SIZE_HEADER_LENGTH > end) return null;
+			const hi = view.getUint32(off + 8);
+			const lo = view.getUint32(off + 12);
+			size = hi * 4294967296 + lo;
+			contentStart = off + LARGE_SIZE_HEADER_LENGTH;
+		} 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) {
+	for (const b of boxes) if (b.type === type) return b;
+	return null;
+}
+function readSttsRuns(bytes, box) {
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const base = box.contentStart + 4;
+	if (base + 4 > box.end) return null;
+	const entries = view.getUint32(base);
+	if (base + 4 + entries * 8 > box.end) return null;
+	const runs = [];
+	for (let i = 0; i < entries; i++) {
+		const at = base + 4 + i * 8;
+		runs.push({
+			count: view.getUint32(at),
+			delta: view.getUint32(at + 4)
+		});
+	}
+	return runs;
+}
+function readSyncSampleNumbers(bytes, box) {
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const base = box.contentStart + 4;
+	if (base + 4 > box.end) return null;
+	const entries = view.getUint32(base);
+	if (base + 4 + entries * 4 > box.end) return null;
+	const out = /* @__PURE__ */ new Set();
+	for (let i = 0; i < entries; i++) out.add(view.getUint32(base + 4 + i * 4));
+	return out;
+}
+function mediaTimescale(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);
+	if (at + 4 > mdhd.end) return null;
+	const ts = view.getUint32(at);
+	return ts > 0 ? ts : null;
+}
+function handlerType(bytes, hdlr) {
+	const at = hdlr.contentStart + 8;
+	if (at + FOURCC_LENGTH > hdlr.end) return "";
+	let out = "";
+	for (let i = 0; i < FOURCC_LENGTH; i++) out += String.fromCharCode(bytes[at + i] ?? 0);
+	return out;
+}
+/** The video `trak` of a `moov`, or `null` when it has none. */
+function videoTrack(bytes, moov) {
+	const children = childBoxes(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;
+		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;
+	}
+	return null;
+}
+/**
+* Read a clip file's time→sample map. Never throws: every structural failure
+* 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);
+	if (!top) return {
+		kind: "refused",
+		reason: "malformed"
+	};
+	const moov = findBox(top, "moov");
+	if (!moov) return {
+		kind: "refused",
+		reason: "no-moov"
+	};
+	const mdia = videoTrack(bytes, moov);
+	if (!mdia) return {
+		kind: "refused",
+		reason: "no-video-track"
+	};
+	const mdiaKids = childBoxes(bytes, mdia.contentStart, mdia.end);
+	if (!mdiaKids) return {
+		kind: "refused",
+		reason: "malformed"
+	};
+	const mdhd = findBox(mdiaKids, "mdhd");
+	const minf = findBox(mdiaKids, "minf");
+	if (!mdhd || !minf) return {
+		kind: "refused",
+		reason: "malformed"
+	};
+	const timescale = mediaTimescale(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;
+	if (!stbl) return {
+		kind: "refused",
+		reason: "no-samples"
+	};
+	const stblKids = childBoxes(bytes, stbl.contentStart, stbl.end);
+	if (!stblKids) return {
+		kind: "refused",
+		reason: "malformed"
+	};
+	const sttsBox = findBox(stblKids, "stts");
+	if (!sttsBox) return {
+		kind: "refused",
+		reason: "no-samples"
+	};
+	const runs = readSttsRuns(bytes, sttsBox);
+	if (!runs) return {
+		kind: "refused",
+		reason: "malformed"
+	};
+	const stssBox = findBox(stblKids, "stss");
+	const syncNumbers = stssBox === null ? null : readSyncSampleNumbers(bytes, stssBox);
+	if (stssBox !== null && syncNumbers === null) return {
+		kind: "refused",
+		reason: "malformed"
+	};
+	const samples = [];
+	let ticks = 0;
+	let syncSampleCount = 0;
+	let firstSyncMs = null;
+	for (const run of runs) for (let i = 0; i < run.count; i++) {
+		const sampleNumber = samples.length + 1;
+		const sync = syncNumbers === null ? true : syncNumbers.has(sampleNumber);
+		const startMs = ticks * 1e3 / timescale;
+		const durMs = run.delta * 1e3 / timescale;
+		if (sync) {
+			syncSampleCount++;
+			if (firstSyncMs === null) firstSyncMs = startMs;
+		}
+		samples.push({
+			startMs,
+			durMs,
+			sync
+		});
+		ticks += run.delta;
+	}
+	if (samples.length === 0 || ticks === 0) return {
+		kind: "refused",
+		reason: "no-samples"
+	};
+	return {
+		kind: "index",
+		durationMs: ticks * 1e3 / timescale,
+		firstSyncMs: firstSyncMs ?? 0,
+		syncSampleCount,
+		samples
+	};
+}
+//#endregion
+//#region src/stream-broker/recorded/clip-file-source.ts
+var ClipSourceError = class extends Error {
+	reason;
+	constructor(reason, message) {
+		super(message);
+		this.reason = reason;
+		this.name = "ClipSourceError";
+	}
+};
+function createClipFileSource(deps) {
+	const maxBytes = deps.maxBytes ?? 67108864;
+	const { deviceId, clipId, profile } = deps.handle;
+	let resolved = null;
+	let inFlight = null;
+	/**
+	* A refusal that can never change for this file — it is unindexable, or it
+	* is over the bound. Cached so a drag does not re-fetch a 35 MB file per
+	* pointer move. A FETCH failure is deliberately NOT cached: a sleeping
+	* battery camera is a transient no, and the operator's retry must reach it.
+	*/
+	let terminal = null;
+	const refuse = (reason, message, data) => {
+		const err = new ClipSourceError(reason, message);
+		deps.onLog?.(message, {
+			deviceId,
+			clipId,
+			profile,
+			reason,
+			...data
+		});
+		return err;
+	};
+	const load = async () => {
+		let bytes;
+		try {
+			bytes = await deps.read({
+				deviceId,
+				clipId,
+				profile
+			});
+		} catch (err) {
+			throw refuse("fetch-failed", "clip playback: byte fetch failed", { error: err instanceof Error ? err.message : String(err) });
+		}
+		if (bytes.length > maxBytes) {
+			terminal = refuse("too-large", "clip playback: clip exceeds the broker byte bound", {
+				bytes: bytes.length,
+				maxBytes
+			});
+			throw terminal;
+		}
+		const index = indexClipMp4(bytes);
+		if (index.kind === "refused") {
+			terminal = refuse(index.reason, "clip playback: clip cannot be indexed — it will not play in the recorded path", { bytes: bytes.length });
+			throw terminal;
+		}
+		return {
+			bytes,
+			index
+		};
+	};
+	const ensure = async () => {
+		if (terminal) throw terminal;
+		if (resolved) return resolved;
+		if (!inFlight) inFlight = load().then((r) => {
+			resolved = r;
+			return r;
+		}).finally(() => {
+			inFlight = null;
+		});
+		return inFlight;
+	};
+	return {
+		async locate(args) {
+			const { index, bytes } = await ensure();
+			if (args.epochMs >= index.durationMs) return {
+				kind: "gap",
+				nearestEdgeMs: null,
+				prevEndMs: index.durationMs
+			};
+			if (args.epochMs < index.firstSyncMs) return {
+				kind: "gap",
+				nearestEdgeMs: index.firstSyncMs,
+				prevEndMs: null
+			};
+			return {
+				kind: "segment",
+				startMs: 0,
+				durMs: index.durationMs,
+				bytes: bytes.length
+			};
+		},
+		async readBytes() {
+			return (await ensure()).bytes;
+		},
+		async durationMs() {
+			return (await ensure()).index.durationMs;
+		}
+	};
+}
+//#endregion
 //#region src/stream-broker/recorded/demux-off-thread.ts
 /**
 * Off-thread JS demux client — mp4box parse on a `worker_threads` Worker
@@ -30837,6 +31251,7 @@ var BrokerWebrtcServer = class {
 	locateRecordedSegment;
 	readRecordedSegmentBytes;
 	readRecordedGopBytes;
+	readClipBytes;
 	resolveFfmpegPath;
 	/**
 	* THE ffmpeg primitive, for the transcode leg. `null` until the manager wires
@@ -30929,6 +31344,7 @@ var BrokerWebrtcServer = class {
 		this.locateRecordedSegment = options.locateRecordedSegment;
 		this.readRecordedSegmentBytes = options.readRecordedSegmentBytes;
 		this.readRecordedGopBytes = options.readRecordedGopBytes;
+		this.readClipBytes = options.readClipBytes;
 		this.resolveFfmpegPath = options.resolveFfmpegPath;
 	}
 	registerBroker(brokerId, broker) {
@@ -31648,7 +32064,96 @@ var BrokerWebrtcServer = class {
 					bytes: res.data
 				};
 			} : void 0;
+			const readClip = this.readClipBytes;
 			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.
+			*/
+			const buildFeeder = (profile, clip) => {
+				const opusSession = session.isOpusAudio;
+				const audioSink = opusSession ? {
+					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)
+				};
+				const demuxAudio = opusSession ? async (b) => {
+					return (await demuxSegmentAudioOpusPreferJs(b, {
+						ffmpegPath: resolveFfmpeg?.(),
+						onFfmpegFallback: (reason) => {
+							if (audioOpusFallbackLogged) return;
+							audioOpusFallbackLogged = true;
+							sessionLogger.warn("recorded audio: JS Opus demux missed — ffmpeg AAC→Opus fallback (once/session)", { meta: {
+								sessionId,
+								deviceId,
+								profile,
+								reason
+							} });
+						}
+					})).map((au) => ({
+						data: au.data,
+						ptsMs: au.ptsMs
+					}));
+				} : (b) => demuxSegmentToPcmu(b, resolveFfmpeg?.());
+				const clipSource = clip && readClip ? createClipFileSource({
+					handle: clip,
+					read: readClip,
+					onLog: (msg, data) => sessionLogger.warn(msg, {
+						tags: { deviceId: clip.deviceId },
+						meta: {
+							sessionId,
+							...data
+						}
+					})
+				}) : null;
+				return new RecordedFeeder({
+					deviceId: clip ? clip.deviceId : deviceId,
+					profile,
+					locate: clipSource ? clipSource.locate : locateRecorded,
+					readBytes: clipSource ? clipSource.readBytes : readRecorded,
+					...clipSource ? {} : {
+						readGop,
+						fragmentCache: scrubCache
+					},
+					demux: demuxVideo,
+					demuxTally,
+					demuxAudio,
+					audioClockRateHz: opusSession ? 48e3 : 8e3,
+					sink: audioSink,
+					onState: (t) => {
+						sessionLogger.info("recorded: feeder state", {
+							tags: { deviceId: clip ? clip.deviceId : deviceId },
+							meta: {
+								sessionId,
+								deviceId,
+								profile,
+								clipId: clip?.clipId,
+								from: t.from,
+								to: t.to,
+								reason: t.reason,
+								seekToken: t.seekToken,
+								dragId: t.dragId
+							}
+						});
+						timeline._emitState(t.to);
+					},
+					onPosition: (epochMs, pushSeq) => timeline._emitPosition(epochMs, pushSeq),
+					onLog: (msg, data) => sessionLogger.info(msg, {
+						tags: { deviceId: clip ? clip.deviceId : deviceId },
+						meta: {
+							sessionId,
+							deviceId,
+							profile,
+							clipId: clip?.clipId,
+							...data
+						}
+					})
+				});
+			};
 			timeline = new TimelineSession({
 				session,
 				deviceId,
@@ -31679,71 +32184,15 @@ var BrokerWebrtcServer = class {
 						} });
 					});
 				} : void 0,
-				makeFeeder: (profile) => {
-					const opusSession = session.isOpusAudio;
-					return new RecordedFeeder({
-						deviceId,
-						profile,
-						locate: locateRecorded,
-						readBytes: readRecorded,
-						readGop,
-						fragmentCache: scrubCache,
-						demux: demuxVideo,
-						demuxTally,
-						demuxAudio: opusSession ? async (b) => {
-							return (await demuxSegmentAudioOpusPreferJs(b, {
-								ffmpegPath: resolveFfmpeg?.(),
-								onFfmpegFallback: (reason) => {
-									if (audioOpusFallbackLogged) return;
-									audioOpusFallbackLogged = true;
-									sessionLogger.warn("recorded audio: JS Opus demux missed — ffmpeg AAC→Opus fallback (once/session)", { meta: {
-										sessionId,
-										deviceId,
-										profile,
-										reason
-									} });
-								}
-							})).map((au) => ({
-								data: au.data,
-								ptsMs: au.ptsMs
-							}));
-						} : (b) => demuxSegmentToPcmu(b, resolveFfmpeg?.()),
-						audioClockRateHz: opusSession ? 48e3 : 8e3,
-						sink: opusSession ? {
-							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: (t) => {
-							sessionLogger.info("recorded: feeder state", {
-								tags: { deviceId },
-								meta: {
-									sessionId,
-									deviceId,
-									profile,
-									from: t.from,
-									to: t.to,
-									reason: t.reason,
-									seekToken: t.seekToken,
-									dragId: t.dragId
-								}
-							});
-							timeline._emitState(t.to);
-						},
-						onPosition: (epochMs, pushSeq) => timeline._emitPosition(epochMs, pushSeq),
-						onLog: (msg, data) => sessionLogger.info(msg, {
-							tags: { deviceId },
-							meta: {
-								sessionId,
-								deviceId,
-								profile,
-								...data
-							}
-						})
-					});
-				}
+				makeFeeder: (profile) => buildFeeder(profile, null),
+				...readClip ? { makeClipFeeder: ({ handle }) => buildFeeder(handle.profile ?? "clip", handle) } : {},
+				onLog: (msg, data) => sessionLogger.warn(msg, {
+					tags: { deviceId },
+					meta: {
+						sessionId,
+						...data
+					}
+				})
 			});
 			entry.timeline = timeline;
 			sessionLogger.info("recorded: TimelineSession wired (control accessors present)", { meta: {
@@ -33246,6 +33695,14 @@ var StreamBrokerAddon = class extends BaseAddon {
 			},
 			locateRecordedSegment: (args) => this.ctx.api.recording.locateSegment.query(args),
 			readRecordedSegmentBytes: async (args) => (await this.ctx.api.recording.readSegmentBytes.query(args)).data,
+			readClipBytes: async (args) => {
+				const res = await this.ctx.api.videoclips.readClipBytes.query({
+					deviceId: args.deviceId,
+					clipId: args.clipId,
+					...args.profile !== null ? { profile: args.profile } : {}
+				});
+				return new Uint8Array(Buffer.from(res.base64, "base64"));
+			},
 			readRecordedGopBytes: async (args) => {
 				try {
 					return await this.ctx.api.recording.readGopBytes.query({