@camstack/addon-provider-reolink 1.2.158 → 1.2.159

package/dist/addon.mjs

@@ -5385,7 +5385,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#endregion
-//#region ../types/dist/sleep-BVhJDJka.mjs
+//#region ../types/dist/sleep-CUmLTud7.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -76810,7 +76810,7 @@ var require_lz4 = /* @__PURE__ */ __commonJSMin(((exports) => {
 	};
 }));
 //#endregion
-//#region node_modules/@apocaliss92/nodelink-js/dist/chunk-5PJ6XPBF.js
+//#region node_modules/@apocaliss92/nodelink-js/dist/chunk-GNC5U3YA.js
 var import_fxp = require_fxp();
 var import_lz4 = /* @__PURE__ */ __toESM(require_lz4(), 1);
 function encodeHeader(h) {
@@ -80975,6 +80975,7 @@ var BaichuanClient = class _BaichuanClient extends EventEmitter {
 						lockedChannelId = frame.header.channelId;
 						lockedStreamType = frame.header.streamType;
 					}
+					params.onChunk?.(decrypted);
 					chunks.push(decrypted);
 					armIdleFinish();
 					if (frame.header.responseCode === 201) finish(Buffer.concat(chunks));
@@ -92981,7 +92982,8 @@ ${stderr}`));
 				payloadXml,
 				streamType: 0,
 				timeoutMs,
-				...params.idleTimeoutMs != null ? { idleTimeoutMs: params.idleTimeoutMs } : {}
+				...params.idleTimeoutMs != null ? { idleTimeoutMs: params.idleTimeoutMs } : {},
+				...params.onChunk ? { onChunk: params.onChunk } : {}
 			});
 		} catch (e) {
 			trace(`download failed: ${e instanceof Error ? e.message : String(e)}`);
@@ -149045,6 +149047,123 @@ function createClipPlaybackHandler(deps) {
 		}).pipe(res);
 	};
 }
+/**
+* `/addon/provider-reolink/clip-stream/<deviceId>/<clipKey>.mp4` — the same
+* recording as `clip/…`, served as it ARRIVES from the camera.
+*
+* **Not `Range`-able, and it says so.** The response has no length: it is a
+* fragmented MP4 written by an ffmpeg that is still reading the camera when
+* the first byte leaves. So there is no `content-length`, `accept-ranges` is
+* `none`, a `Range` header is IGNORED (a 206 over something with no length
+* would be a lie), and the peer may not cache it (`no-store`) — a stream is
+* not an immutable artifact, the file route is. The status line is written
+* on the first muxed byte, never before: until then every refusal still owns
+* it, and a camera that serves nothing answers a status with a reason, not an
+* empty 200 (D391).
+*
+* `HEAD` answers the headers and touches no camera.
+*/
+var CLIP_STREAM_PREFIX = "clip-stream";
+var STREAM_HEADERS = {
+	"content-type": "video/mp4",
+	"accept-ranges": "none",
+	"cache-control": "no-store",
+	["x-camstack-clip-transport"]: "forward-only"
+};
+/** The status a refusal answers. `404` = nothing here to serve; `409` = a
+*  clip that exists and cannot be served right now; `502` = the camera. */
+function streamRefusalStatus(code) {
+	switch (code) {
+		case "unknown-device":
+		case "no-catalog-row": return 404;
+		case "sleeping":
+		case "uid-missing":
+		case "clip-in-progress": return 409;
+		case "camera-refused":
+		case "fetch-failed": return 502;
+	}
+}
+function createClipStreamHandler(deps) {
+	return async (req, res) => {
+		if (req.method !== "GET" && req.method !== "HEAD") {
+			res.writeHead(405, { allow: "GET, HEAD" });
+			res.end();
+			return;
+		}
+		const match = MEDIA_PATH.exec(pathnameOf(req));
+		if (match === null) {
+			res.writeHead(400);
+			res.end();
+			return;
+		}
+		const deviceId = Number(match[1]);
+		const clipKey = match[2] ?? "";
+		if (req.method === "HEAD") {
+			res.writeHead(200, STREAM_HEADERS);
+			res.end();
+			return;
+		}
+		if (req.headers.range !== void 0) deps.logger.debug("videoclips: a Range header on the clip stream route is ignored", {
+			tags: { deviceId },
+			meta: {
+				clipKey,
+				range: req.headers.range
+			}
+		});
+		const sink = {
+			begin: () => {
+				res.writeHead(200, STREAM_HEADERS);
+			},
+			write: (chunk) => res.write(chunk),
+			onceDrain: (listener) => {
+				res.once("drain", listener);
+			},
+			onceClose: (listener) => {
+				res.once("close", listener);
+			},
+			end: () => {
+				res.end();
+			},
+			destroy: () => {
+				res.destroy();
+			}
+		};
+		let outcome;
+		try {
+			outcome = await deps.stream(deviceId, clipKey, sink);
+		} catch (err) {
+			deps.logger.warn("videoclips: the clip stream route threw", {
+				tags: { deviceId },
+				meta: {
+					clipKey,
+					branch: "stream-threw",
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
+			if (res.headersSent) res.destroy();
+			else {
+				res.writeHead(500);
+				res.end();
+			}
+			return;
+		}
+		if (outcome.kind !== "refused") return;
+		deps.logger.info("videoclips: clip stream not served", {
+			tags: { deviceId },
+			meta: {
+				clipKey,
+				code: outcome.code,
+				reason: outcome.detail,
+				status: streamRefusalStatus(outcome.code)
+			}
+		});
+		res.writeHead(streamRefusalStatus(outcome.code), {
+			[CLIP_STILL_REASON_HEADER]: outcome.detail.slice(0, 500),
+			[CLIP_STILL_REASON_CODE_HEADER]: outcome.code
+		});
+		res.end();
+	};
+}
 //#endregion
 //#region src/clips/clip-mux.ts
 /** A clip that has not transferred by here is not going to. */
@@ -149202,6 +149321,94 @@ function describeMuxFailure(run) {
 	if (run.code !== 0) return `mux-failed (exit ${String(run.code)}): ${run.stderr.slice(0, 300)}`;
 	return null;
 }
+/** The fragmented container a stream is muxed into — see the file header. */
+var CLIP_STREAM_MOVFLAGS = "frag_keyframe+empty_moov+default_base_moof";
+/**
+* The rate the probe measured, through the library's one derivation.
+*
+* `estimateVideoTiming` falls back to the info header when the timestamps
+* cannot say; that fallback is REFUSED here (`fpsSource: 'unmeasured'`), as
+* D567 says, so a guess is never handed to `-r` under a measurement's name.
+*/
+function probeClipStreamRate(timestampsUs) {
+	const timing = estimateVideoTiming({ timestampsUs });
+	if (timing.fpsSource !== "timestamps" || timing.fps === null) return {
+		fps: null,
+		fpsSource: "unmeasured",
+		accessUnits: timestampsUs.length
+	};
+	return {
+		fps: timing.fps,
+		fpsSource: "timestamps",
+		accessUnits: timestampsUs.length
+	};
+}
+/**
+* One ffmpeg, stdin to stdout, video only, fragmented MP4.
+*
+* Mirrors `buildClipMuxArgs` where a stream can: the demuxer is named from
+* the DETECTED codec (the BcMedia header lies on a hub child), `-r` is an
+* input option before its own `-i`, and the video is copied. Where it
+* cannot — `+faststart`, the audio input — the file header says why.
+*/
+function buildClipStreamMuxArgs(input) {
+	const demuxer = input.videoType === "H265" ? "hevc" : "h264";
+	return [
+		"-hide_banner",
+		"-loglevel",
+		"error",
+		"-nostdin",
+		...input.fps !== null && Number.isFinite(input.fps) && input.fps > 0 ? ["-r", String(input.fps)] : [],
+		"-f",
+		demuxer,
+		"-i",
+		"pipe:0",
+		"-c:v",
+		"copy",
+		"-movflags",
+		CLIP_STREAM_MOVFLAGS,
+		"-f",
+		"mp4",
+		"pipe:1"
+	];
+}
+/**
+* The D447 rule as a state machine, so it can be proved without a socket.
+*
+* A `false` write ARMS the timer; further `false` writes while it is armed do
+* not push the deadline out. `drain` — the hop's own word that it took what
+* it held — disarms it. Stall fires at most once, and a disposed gate is
+* silent for ever.
+*/
+function createDrainGate(deps) {
+	let handle = null;
+	let stalled = false;
+	const disarm = () => {
+		if (handle !== null) clearTimeout(handle);
+		handle = null;
+	};
+	return {
+		wrote(accepted) {
+			if (accepted || handle !== null || stalled) return;
+			handle = setTimeout(() => {
+				handle = null;
+				if (stalled) return;
+				stalled = true;
+				deps.onStall();
+			}, deps.timeoutMs);
+		},
+		drained() {
+			disarm();
+		},
+		waiting() {
+			return handle !== null;
+		},
+		dispose() {
+			disarm();
+			stalled = true;
+		}
+	};
+}
 //#endregion
 //#region src/clips/clip-truncation.ts
 /**
@@ -149248,6 +149455,500 @@ function judgeClipDuration(input) {
 	};
 }
 //#endregion
+//#region src/clips/clip-stream.ts
+var defaultDecoder = (handlers) => new BcMediaAnnexBDecoder({
+	strict: false,
+	onVideoAccessUnit: handlers.onVideoAccessUnit,
+	onAudioFrame: () => handlers.onAudioFrame()
+});
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function createClipStreamProducer(deps) {
+	const sleep = deps.sleep ?? defaultSleep;
+	const createDecoder = deps.createDecoder ?? defaultDecoder;
+	const drainTimeoutMs = deps.drainTimeoutMs ?? 1e4;
+	const flushTimeoutMs = deps.flushTimeoutMs ?? 15e3;
+	const lanes = /* @__PURE__ */ new Map();
+	const activeByHost = /* @__PURE__ */ new Map();
+	const runAttempt = (input, attempt) => new ClipStreamRun({
+		logger: deps.logger,
+		spawnMux: deps.spawnMux,
+		createDecoder,
+		drainTimeoutMs,
+		flushTimeoutMs
+	}, input, attempt).run();
+	const runAttempts = async (input) => {
+		const { deviceId } = input.device;
+		let lastDetail = "no reason given";
+		for (let attempt = 1; attempt <= 3; attempt += 1) {
+			if (attempt > 1) await sleep(500 * 2 ** (attempt - 2));
+			const result = await runAttempt(input, attempt);
+			if (result.kind !== "no-media") return result;
+			lastDetail = result.detail;
+			deps.logger.warn("videoclips: a clip stream produced no media — retrying", {
+				tags: { deviceId },
+				meta: {
+					clipKey: input.row.clipKey,
+					twin: input.twin,
+					branch: "stream-no-media",
+					attempt,
+					error: lastDetail
+				}
+			});
+		}
+		deps.logger.warn("videoclips: the camera never delivered this clip stream", {
+			tags: { deviceId },
+			meta: {
+				clipKey: input.row.clipKey,
+				twin: input.twin,
+				branch: "camera-refused",
+				attempts: 3,
+				error: lastDetail
+			}
+		});
+		return {
+			kind: "refused",
+			code: "camera-refused",
+			detail: `clip stream never landed after 3 attempts — ${lastDetail}`,
+			attempts: 3
+		};
+	};
+	return {
+		active: (hostKey) => activeByHost.get(hostKey) ?? 0,
+		stream: (input) => {
+			const { hostKey, deviceId } = input.device;
+			const ahead = activeByHost.get(hostKey) ?? 0;
+			if (ahead > 0) deps.logger.info("videoclips: a clip stream is queued behind another on this host", {
+				tags: { deviceId },
+				meta: {
+					clipKey: input.row.clipKey,
+					twin: input.twin,
+					branch: "stream-queued",
+					ahead
+				}
+			});
+			activeByHost.set(hostKey, ahead + 1);
+			const run = (lanes.get(hostKey) ?? Promise.resolve()).then(() => runAttempts(input)).finally(() => {
+				const left = (activeByHost.get(hostKey) ?? 1) - 1;
+				if (left <= 0) activeByHost.delete(hostKey);
+				else activeByHost.set(hostKey, left);
+			});
+			lanes.set(hostKey, run.then(() => void 0, () => void 0));
+			return run;
+		}
+	};
+}
+/**
+* One transfer: camera → decoder → ffmpeg → peer, with a cut on every hop.
+*
+* A class because the run is a state machine with a dozen fields the chunk
+* callback and the download promise both touch; passing them around as
+* closures over `let`s was less readable, not more immutable.
+*/
+var ClipStreamRun = class {
+	deps;
+	input;
+	attempt;
+	accessUnits = 0;
+	audioFrames = 0;
+	timestampsUs = [];
+	/** Access units held until the rate is probed — the frames in flight. */
+	probe = [];
+	mux = null;
+	muxStderr = "";
+	muxClosed = null;
+	rate = {
+		fps: null,
+		fpsSource: "unmeasured",
+		accessUnits: 0
+	};
+	videoType = null;
+	begun = false;
+	ended = false;
+	bytesOut = 0;
+	cut = null;
+	stdinGate;
+	peerGate;
+	tags;
+	constructor(deps, input, attempt) {
+		this.deps = deps;
+		this.input = input;
+		this.attempt = attempt;
+		this.tags = { deviceId: input.device.deviceId };
+		this.stdinGate = createDrainGate({
+			timeoutMs: deps.drainTimeoutMs,
+			onStall: () => this.sever("mux-stalled", "ffmpeg stopped taking access units")
+		});
+		this.peerGate = createDrainGate({
+			timeoutMs: deps.drainTimeoutMs,
+			onStall: () => this.sever("peer-stalled", "the peer stopped taking bytes")
+		});
+	}
+	async run() {
+		const { device, row, fileName, twin, sink } = this.input;
+		sink.onceClose(() => {
+			if (!this.ended) this.sever("peer-closed", "the peer closed the connection");
+		});
+		const decoder = this.deps.createDecoder({
+			onVideoAccessUnit: (unit) => this.onAccessUnit(unit),
+			onAudioFrame: () => {
+				this.audioFrames += 1;
+			}
+		});
+		this.deps.logger.info("videoclips: streaming a clip file from the camera", {
+			tags: this.tags,
+			meta: {
+				clipKey: row.clipKey,
+				twin,
+				fileName,
+				startMs: row.startMs,
+				endMs: row.endMs,
+				attempt: this.attempt,
+				idleTimeoutMs: 300
+			}
+		});
+		let api;
+		try {
+			api = await device.getApi();
+		} catch (err) {
+			return {
+				kind: "no-media",
+				detail: describe(err)
+			};
+		}
+		try {
+			await api.fileInfoListReplayBinaryDownload({
+				channel: device.channel,
+				...device.uid !== void 0 ? { uid: device.uid } : {},
+				fileName,
+				idleTimeoutMs: 300,
+				onChunk: (chunk) => this.onChunk(decoder, chunk)
+			});
+		} catch (err) {
+			return this.onTransferFailed(err);
+		}
+		return this.onTransferEnded();
+	}
+	/** The camera's bytes, as they arrive. A cut run THROWS here: the only stop. */
+	onChunk(decoder, chunk) {
+		if (this.cut !== null) throw new Error(`clip stream cut: ${this.cut.reason}`);
+		try {
+			decoder.push(chunk);
+		} catch (err) {
+			this.sever("decode-failed", describe(err));
+			throw err;
+		}
+	}
+	onAccessUnit(unit) {
+		if (this.cut !== null) return;
+		this.accessUnits += 1;
+		this.timestampsUs.push(unit.microseconds);
+		if (this.mux === null) {
+			this.probe = [...this.probe, unit];
+			if (this.probe.length >= 16) this.startMux();
+			return;
+		}
+		this.feed(unit.annexB);
+	}
+	/** Spawn ffmpeg with the probed rate and hand it what was held. */
+	startMux() {
+		const first = this.probe[0];
+		if (first === void 0 || this.mux !== null) return;
+		this.videoType = first.videoType;
+		this.rate = probeClipStreamRate(this.timestampsUs);
+		const { row, twin } = this.input;
+		if (this.rate.fpsSource !== "timestamps") this.deps.logger.warn("videoclips: no measured frame rate for this clip stream", {
+			tags: this.tags,
+			meta: {
+				clipKey: row.clipKey,
+				twin,
+				branch: "fps-unmeasured",
+				probeAccessUnits: this.rate.accessUnits
+			}
+		});
+		let mux;
+		try {
+			mux = this.deps.spawnMux(buildClipStreamMuxArgs({
+				videoType: this.videoType,
+				fps: this.rate.fps
+			}));
+		} catch (err) {
+			this.sever("mux-failed", `ffmpeg could not be spawned: ${describe(err)}`);
+			return;
+		}
+		this.mux = mux;
+		this.muxClosed = new Promise((resolve) => {
+			mux.on("close", (code) => resolve(code));
+			mux.on("error", (err) => {
+				this.sever("mux-failed", `ffmpeg failed: ${err.message}`);
+				resolve(null);
+			});
+		});
+		mux.stderr?.on("data", (chunk) => {
+			if (this.muxStderr.length < 2e3) this.muxStderr += chunk.toString("utf8");
+		});
+		mux.stdin?.on("error", (err) => this.sever("mux-failed", `ffmpeg stdin: ${err.message}`));
+		mux.stdin?.on("drain", () => this.stdinGate.drained());
+		mux.stdout?.on("data", (chunk) => this.onMuxOut(chunk));
+		mux.stdout?.on("end", () => this.finishSink());
+		this.deps.logger.info("videoclips: a clip stream is muxing", {
+			tags: this.tags,
+			meta: {
+				clipKey: row.clipKey,
+				twin,
+				videoType: this.videoType,
+				fps: this.rate.fps,
+				fpsSource: this.rate.fpsSource,
+				probeAccessUnits: this.rate.accessUnits
+			}
+		});
+		const held = this.probe;
+		this.probe = [];
+		for (const unit of held) this.feed(unit.annexB);
+	}
+	feed(annexB) {
+		if (this.cut !== null || this.mux?.stdin === null || this.mux?.stdin === void 0) return;
+		this.stdinGate.wrote(this.mux.stdin.write(annexB));
+	}
+	/** ffmpeg's output, to the peer, honouring `write()`'s return (D447). */
+	onMuxOut(chunk) {
+		if (this.cut !== null) return;
+		const { sink } = this.input;
+		if (!this.begun) {
+			this.begun = true;
+			sink.begin();
+		}
+		const accepted = sink.write(chunk);
+		this.bytesOut += chunk.byteLength;
+		this.peerGate.wrote(accepted);
+		if (accepted) return;
+		const stdout = this.mux?.stdout;
+		stdout?.pause();
+		sink.onceDrain(() => {
+			this.peerGate.drained();
+			stdout?.resume();
+		});
+	}
+	finishSink() {
+		if (this.cut !== null || this.ended) return;
+		this.ended = true;
+		this.input.sink.end();
+	}
+	/** Sever every hop, once, and say why. */
+	sever(reason, detail) {
+		if (this.cut !== null) return;
+		this.cut = {
+			reason,
+			detail
+		};
+		this.stdinGate.dispose();
+		this.peerGate.dispose();
+		this.mux?.kill("SIGKILL");
+		this.deps.logger.warn("videoclips: a clip stream was cut", {
+			tags: this.tags,
+			meta: {
+				clipKey: this.input.row.clipKey,
+				twin: this.input.twin,
+				branch: reason,
+				detail,
+				accessUnits: this.accessUnits,
+				bytesOut: this.bytesOut,
+				begun: this.begun
+			}
+		});
+		if (this.begun) this.input.sink.destroy();
+	}
+	cutOutcome(cut) {
+		if (this.begun) return {
+			kind: "cut",
+			reason: cut.reason,
+			detail: cut.detail,
+			bytesOut: this.bytesOut
+		};
+		return {
+			kind: "refused",
+			code: "fetch-failed",
+			detail: `${cut.reason}: ${cut.detail}`,
+			attempts: this.attempt
+		};
+	}
+	onTransferFailed(err) {
+		if (this.cut !== null) return this.cutOutcome(this.cut);
+		if (this.accessUnits === 0) return {
+			kind: "no-media",
+			detail: describe(err)
+		};
+		this.sever("camera-failed", describe(err));
+		return this.cutOutcome({
+			reason: "camera-failed",
+			detail: describe(err)
+		});
+	}
+	async onTransferEnded() {
+		if (this.cut !== null) return this.cutOutcome(this.cut);
+		if (this.accessUnits === 0) return {
+			kind: "no-media",
+			detail: "the camera answered the transfer with no access unit"
+		};
+		if (this.mux === null) this.startMux();
+		const cutAtStart = this.cut;
+		if (cutAtStart !== null) return this.cutOutcome(cutAtStart);
+		const mux = this.mux;
+		if (mux === null || this.muxClosed === null) return this.cutOutcome({
+			reason: "mux-failed",
+			detail: "no mux after the transfer ended"
+		});
+		mux.stdin?.end();
+		const flush = setTimeout(() => this.sever("mux-hung", `ffmpeg did not exit ${this.deps.flushTimeoutMs} ms after its input ended`), this.deps.flushTimeoutMs);
+		const code = await this.muxClosed;
+		clearTimeout(flush);
+		const cutAfter = this.cut;
+		if (cutAfter !== null) return this.cutOutcome(cutAfter);
+		if (code !== 0) {
+			this.sever("mux-failed", `ffmpeg exited ${String(code)}: ${this.muxStderr.slice(0, 300)}`);
+			return this.cutOutcome({
+				reason: "mux-failed",
+				detail: this.muxStderr.slice(0, 300)
+			});
+		}
+		this.finishSink();
+		return this.served();
+	}
+	/** The stream landed: judge it against the row, out loud, and answer. */
+	served() {
+		const { row, twin } = this.input;
+		const timing = estimateVideoTiming({ timestampsUs: this.timestampsUs });
+		const durationSeconds = timing.fpsSource === "timestamps" ? timing.durationSeconds : null;
+		const verdict = judgeClipDuration({
+			expectedMs: row.endMs - row.startMs,
+			decodedSeconds: durationSeconds,
+			...row.inProgress === true ? { inProgress: true } : {}
+		});
+		const meta = {
+			clipKey: row.clipKey,
+			twin,
+			attempt: this.attempt,
+			accessUnits: this.accessUnits,
+			bytesOut: this.bytesOut,
+			durationSeconds,
+			expectedMs: row.endMs - row.startMs,
+			fps: this.rate.fps,
+			fpsSource: this.rate.fpsSource,
+			videoType: this.videoType
+		};
+		if (verdict.kind === "short") this.deps.logger.warn("videoclips: a clip stream came up short against its row", {
+			tags: this.tags,
+			meta: {
+				...meta,
+				branch: "stream-short",
+				shortfallSeconds: verdict.shortfallSeconds,
+				retried: false
+			}
+		});
+		else if (verdict.kind === "unknown") this.deps.logger.warn("videoclips: a clip stream could not be checked for truncation", {
+			tags: this.tags,
+			meta: {
+				...meta,
+				branch: "completeness-unverified",
+				reason: verdict.reason
+			}
+		});
+		else this.deps.logger.info("videoclips: a clip stream landed whole", {
+			tags: this.tags,
+			meta: {
+				...meta,
+				branch: "stream-served"
+			}
+		});
+		if (this.audioFrames > 0) this.deps.logger.warn("videoclips: a clip stream was served without sound", {
+			tags: this.tags,
+			meta: {
+				clipKey: row.clipKey,
+				twin,
+				branch: "stream-video-only",
+				audioFramesDropped: this.audioFrames
+			}
+		});
+		return {
+			kind: "served",
+			accessUnits: this.accessUnits,
+			audioFramesDropped: this.audioFrames,
+			bytesOut: this.bytesOut,
+			durationSeconds,
+			verdict,
+			rate: this.rate,
+			attempts: this.attempt
+		};
+	}
+};
+function describe(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+//#endregion
+//#region src/clips/clip-stream-route.ts
+function createClipStreamRoute(deps) {
+	return async (deviceId, clipKey, sink) => {
+		const twin = "sub";
+		const gate = await deps.gate({
+			deviceId,
+			clipKey,
+			twin,
+			path: "stream"
+		});
+		if (gate.kind === "refused") return {
+			kind: "refused",
+			code: gate.branch,
+			detail: gate.detail
+		};
+		const row = deps.rowFor(deviceId, clipKey);
+		if (row === null) {
+			deps.logger.warn("videoclips: no catalog row for this clip stream", {
+				tags: { deviceId },
+				meta: {
+					clipKey,
+					twin,
+					branch: "no-catalog-row"
+				}
+			});
+			return {
+				kind: "refused",
+				code: "no-catalog-row",
+				detail: "no-catalog-row: list this day before asking for its stream"
+			};
+		}
+		if (row.inProgress === true) {
+			deps.logger.warn("videoclips: refusing to stream a clip the camera is still writing", {
+				tags: { deviceId },
+				meta: {
+					clipKey,
+					twin,
+					branch: "clip-in-progress"
+				}
+			});
+			return {
+				kind: "refused",
+				code: "clip-in-progress",
+				detail: "clip-in-progress: the camera is still writing this file; it has no end to stream to"
+			};
+		}
+		const outcome = await deps.producer.stream({
+			device: gate.device,
+			row,
+			fileName: row.subFileName,
+			twin,
+			sink
+		});
+		switch (outcome.kind) {
+			case "served": return { kind: "served" };
+			case "cut": return { kind: "cut" };
+			case "refused": return {
+				kind: "refused",
+				code: outcome.code,
+				detail: outcome.detail
+			};
+		}
+	};
+}
+//#endregion
 //#region src/clips/clip-thumb-queue.ts
 /**
 * The provider's OWN CoverPreview lane — two queues, one in flight per host.
@@ -149427,6 +150128,59 @@ function decideClipPrefetch(input) {
 	return { kind: "run" };
 }
 //#endregion
+//#region src/clips/clip-window.ts
+/**
+* Does this row overlap the window?
+*
+* Half-open on both ends (`start < until`, `end > since`), so a clip that ends
+* exactly when the window begins is OUT and a clip that begins exactly when it
+* ends is OUT — otherwise two adjacent windows both claim the same boundary
+* clip and a surface paging through them renders it twice.
+*
+* A row whose `endMs` is not after its `startMs` is treated as an INSTANT at
+* `startMs`. That is not defensive padding: a clip still being written carries
+* a frozen `endMs` from the camera's index (D563), and on this fleet that has
+* been observed equal to — and once behind — its own start. Judging such a row
+* by a bad end would drop a recording that is happening right now.
+*/
+function clipOverlapsWindow(row, window) {
+	const end = row.endMs > row.startMs ? row.endMs : row.startMs;
+	return row.startMs < window.until && end > window.since;
+}
+/**
+* What the provider ANSWERS with — the one gate, so there is a single place
+* that decides what leaves this listing and a single line that reports it.
+*
+* ## Why a clip still being written is not listed
+*
+* The operator, 2026-09-22: *"Niente clips in preparazione, non ha senso
+* visualizzarle."* He is right, and the reasons had been accumulating:
+*
+* - its `endMs` is a frozen guess — the camera's index keeps whatever it held
+*   when the file was opened, measured on 592 as the same `endTime` for eight
+*   minutes (D563) — so the row's duration, its position on the axis and its
+*   height are all wrong and all move;
+* - `readClipBytes` already refuses it by name (`clip-in-progress`): it has no
+*   end to export against, so the completion rule has nothing to prove the
+*   fetch finished (D568);
+* - it cannot be looped, and the surface has to explain why (`resolveClipLoop`);
+* - the player route would file a TRUNCATED copy under an immutable key, so
+*   the first seconds become permanently what that clip is.
+*
+* Four different places bending around a row that cannot be played properly.
+* Not listing it deletes all four questions instead of answering them: the
+* clip appears, whole, on the next listing after the camera closes the file.
+*/
+function listableClips(rows, window) {
+	const inWindow = rows.filter((row) => clipOverlapsWindow(row, window));
+	const kept = inWindow.filter((row) => row.inProgress !== true);
+	return {
+		kept,
+		outOfWindow: rows.length - inWindow.length,
+		inProgress: inWindow.length - kept.length
+	};
+}
+//#endregion
 //#region src/clips/clip-identity.ts
 /**
 * A Reolink clip's IDENTITY — the id the operator's surface carries around and
@@ -150199,7 +150953,24 @@ function createReolinkVideoclipsProvider(deps) {
 			state: "ok",
 			catalogAsOf: deps.now()
 		});
-		return rows;
+		for (const row of rows) rowsByKey.set(`${device.deviceId}|${row.clipKey}`, row);
+		const narrowed = listableClips(rows, {
+			since,
+			until
+		});
+		if (narrowed.outOfWindow > 0 || narrowed.inProgress > 0) deps.logger.info("videoclips: narrowed a day listing to what it can answer", {
+			tags,
+			meta: {
+				branch: "listing-narrowed",
+				listed: rows.length,
+				kept: narrowed.kept.length,
+				outOfWindow: narrowed.outOfWindow,
+				inProgress: narrowed.inProgress,
+				since,
+				until
+			}
+		});
+		return narrowed.kept;
 	};
 	/**
 	* Give a day's rows a class when the FILES carried none.
@@ -151107,9 +151878,15 @@ function createClipService(deps) {
 	* clip-export vocabulary, so the provider can hand the engine a token it
 	* believes rather than prose it has to guess at (D572).
 	*/
-	const produceTwin = async (input) => {
-		const { deviceId, row, fileName, twin } = input;
-		const clipKey = row.clipKey;
+	/**
+	* The gates every clip byte path runs, in ONE place: the device, the
+	* sleeping standalone, the uid. The file producer and the stream producer
+	* both call this and neither decides any of it again — a second copy of
+	* the sleeping gate is a second chance to wake a camera nobody authorised.
+	* Every refusal is logged HERE, with its branch, so a caller cannot forget.
+	*/
+	const gateClipDevice = async (input) => {
+		const { deviceId, clipKey, twin, path } = input;
 		const tags = { deviceId };
 		const device = await deps.resolveDevice(deviceId);
 		if (device === null) {
@@ -151118,11 +151895,13 @@ function createClipService(deps) {
 				meta: {
 					clipKey,
 					twin,
+					path,
 					branch: "unknown-device"
 				}
 			});
 			return {
 				kind: "refused",
+				branch: "unknown-device",
 				code: "catalog-unreachable",
 				detail: `device ${deviceId} is not a Reolink camera on this node`
 			};
@@ -151134,11 +151913,13 @@ function createClipService(deps) {
 					meta: {
 						clipKey,
 						twin,
+						path,
 						branch: "sleeping"
 					}
 				});
 				return {
 					kind: "refused",
+					branch: "sleeping",
 					code: "sleeping",
 					detail: `device ${deviceId} is a standalone battery camera and is sleeping — fetching a clip would wake it, and no operator authorisation was carried`
 				};
@@ -151148,6 +151929,7 @@ function createClipService(deps) {
 				meta: {
 					clipKey,
 					twin,
+					path,
 					branch: "wake-authorised"
 				}
 			});
@@ -151158,15 +151940,39 @@ function createClipService(deps) {
 				meta: {
 					clipKey,
 					twin,
+					path,
 					branch: "uid-missing"
 				}
 			});
 			return {
 				kind: "refused",
+				branch: "uid-missing",
 				code: "catalog-unreachable",
 				detail: UID_MISSING_REASON
 			};
 		}
+		return {
+			kind: "ok",
+			device
+		};
+	};
+	const produceTwin = async (input) => {
+		const { deviceId, row, fileName, twin } = input;
+		const clipKey = row.clipKey;
+		const tags = { deviceId };
+		const gate = await gateClipDevice({
+			deviceId,
+			clipKey,
+			twin,
+			path: "file",
+			...input.wake !== void 0 ? { wake: input.wake } : {}
+		});
+		if (gate.kind === "refused") return {
+			kind: "refused",
+			code: gate.code,
+			detail: gate.detail
+		};
+		const { device } = gate;
 		let downloaded;
 		deps.logger.info("videoclips: fetching a clip file from the camera", {
 			tags,
@@ -151344,6 +152150,23 @@ function createClipService(deps) {
 		if (outcome.kind === "ok" && twin === "sub") await media.put(deviceId, row.clipKey, outcome.bytes);
 		return outcome;
 	};
+	/**
+	* The STREAM's path (`clip-stream-route.ts`): the same gates, the same row,
+	* nothing written. Beside the file path, not in its place.
+	*/
+	const streamClip = createClipStreamRoute({
+		logger: deps.logger,
+		gate: gateClipDevice,
+		rowFor,
+		producer: createClipStreamProducer({
+			logger: deps.logger,
+			spawnMux: (args) => spawn$1(deps.ffmpegBinaryPath ?? "ffmpeg", [...args], { stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			] })
+		})
+	});
 	const provider = createReolinkVideoclipsProvider({
 		now,
 		cache,
@@ -151373,6 +152196,11 @@ function createClipService(deps) {
 		hostBusy: (hostKey) => queue.busy(hostKey),
 		thumbPrefix: CLIP_THUMB_PREFIX,
 		mediaPrefix: CLIP_MEDIA_PREFIX,
+		streamPrefix: CLIP_STREAM_PREFIX,
+		streamHandler: createClipStreamHandler({
+			stream: streamClip,
+			logger: deps.logger
+		}),
 		thumbHandler: createClipThumbHandler({
 			readCached: (deviceId, clipKey) => thumbs.read(deviceId, clipKey),
 			mint: (deviceId, clipKey) => mintThumbnail(deviceId, clipKey, "interactive"),
@@ -165612,11 +166440,18 @@ var ReolinkProviderAddon = class extends BaseDeviceProvider {
 				access: "authenticated",
 				handler: service.playbackHandler
 			});
+			const stream = await this.ctx.dataPlane?.serve({
+				prefix: service.streamPrefix,
+				access: "authenticated",
+				handler: service.streamHandler
+			});
 			this.ctx.logger.info("Reolink clip data planes served", { meta: {
 				thumbPath: `/addon/${REOLINK_ADDON_ID}/${service.thumbPrefix}`,
 				mediaPath: `/addon/${REOLINK_ADDON_ID}/${service.mediaPrefix}`,
+				streamPath: `/addon/${REOLINK_ADDON_ID}/${service.streamPrefix}`,
 				thumbServed: thumb !== void 0,
-				mediaServed: media !== void 0
+				mediaServed: media !== void 0,
+				streamServed: stream !== void 0
 			} });
 		} catch (err) {
 			this.ctx.logger.warn("Reolink clip data planes failed to serve — clips will not render", { meta: { error: err instanceof Error ? err.message : String(err) } });