@camstack/addon-pipeline 1.2.273 → 1.2.274

package/dist/recorder/index.js

@@ -3,8 +3,8 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../chunk-emK7D4bc.js");
-const require_dist = require("../dist-DRDzfOnl.js");
-const require_node = require("../node-BmTPPuIg.js");
+const require_dist = require("../dist-k6Vu-AhZ.js");
+const require_node = require("../node--u_jUObS.js");
 const require_hub_hostname = require("../hub-hostname-DAJXlOgV.js");
 const require_restream_intent = require("../restream-intent-7uDNqMKs.js");
 const require_retire_root_keys = require("../retire-root-keys-Csb8z2f3.js");
@@ -13496,6 +13496,567 @@ var PlacementService = class {
 	}
 };
 //#endregion
+//#region src/recorder/addon/videoclip-visits.ts
+/**
+* Videoclip visits — the grain a clip should have on an events-mode camera.
+*
+* Disk writes one fMP4 per ffmpeg roll (~8–12 s). The recorder calendar merges
+* only gaps ≤ 5 s, so a single pantry walk shows up as several availability
+* ranges with ~8 s GOP holes between them. Analytics then mints one 15 s clip
+* per motion heartbeat. A *visit* is the keep-window those fragments belong
+* to: cluster availability with {@link VISIT_MERGE_GAP_MS}, annotate with
+* overlapping events. No second copy of the media; the files stay the source
+* of truth.
+*/
+/** Synthetic event-id slot in `analytics:<start>:<end>:<id>` for a visit clip. */
+var VISIT_EVENT_ID = "visit";
+function clusterFootageVisits(ranges, gapMs = require_dist.VISIT_MERGE_GAP_MS) {
+	if (ranges.length === 0) return [];
+	const sorted = [...ranges].toSorted((a, b) => a.startMs - b.startMs);
+	const visits = [];
+	let pieces = [sorted[0]];
+	let endMs = sorted[0].endMs;
+	for (let i = 1; i < sorted.length; i++) {
+		const next = sorted[i];
+		if (next.startMs <= endMs + gapMs) {
+			pieces.push(next);
+			endMs = Math.max(endMs, next.endMs);
+			continue;
+		}
+		visits.push(finishVisit(pieces, endMs));
+		pieces = [next];
+		endMs = next.endMs;
+	}
+	visits.push(finishVisit(pieces, endMs));
+	return visits;
+}
+function finishVisit(pieces, endMs) {
+	const holes = [];
+	for (let i = 1; i < pieces.length; i++) {
+		const prevEnd = pieces[i - 1].endMs;
+		const nextStart = pieces[i].startMs;
+		if (nextStart > prevEnd) holes.push({
+			startMs: prevEnd,
+			endMs: nextStart
+		});
+	}
+	return {
+		startMs: pieces[0].startMs,
+		endMs,
+		ranges: pieces,
+		holes
+	};
+}
+var KIND_ORDER = [
+	"object",
+	"motion",
+	"audio"
+];
+function eventOverlapsVisit(event, visit, pad) {
+	if (event.timestamp >= visit.startMs && event.timestamp <= visit.endMs) return true;
+	const windowStart = event.timestamp - pad.preMs;
+	const windowEnd = event.timestamp + pad.postMs;
+	return windowStart < visit.endMs && windowEnd > visit.startMs;
+}
+function dominantKind(attached) {
+	for (const kind of KIND_ORDER) if (attached.some((a) => a.kind === kind)) return kind;
+	return "motion";
+}
+/**
+* The instant a recorded still can actually be decoded inside a visit: the
+* midpoint of its LONGEST contiguous range.
+*
+* NOT the midpoint of the visit. A visit spans its holes by construction (it is
+* ranges glued across gaps up to `VISIT_MERGE_GAP_MS`), so the naive midpoint
+* lands in dead air roughly as often as not and the recorder's still route
+* answers 204 for a visit with plenty of footage.
+*/
+function stillInstantMs(ranges) {
+	let best;
+	for (const range of ranges) if (best === void 0 || range.endMs - range.startMs > best.endMs - best.startMs) best = range;
+	if (best === void 0) return void 0;
+	return Math.floor((best.startMs + best.endMs) / 2);
+}
+/**
+* The distinct object classes attached to a visit, most frequent first,
+* capped at {@link MAX_CLIP_LABELS}. Empty when nothing classified overlapped
+* — the caller then omits the field so a motion/audio-only visit keeps its
+* kind label instead of carrying an empty array every consumer length-checks.
+*/
+function dominantLabels(attached) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const a of attached) {
+		if (a.kind !== "object") continue;
+		const name = a.event.className;
+		if (typeof name !== "string" || name.length === 0) continue;
+		counts.set(name, (counts.get(name) ?? 0) + 1);
+	}
+	return [...counts.entries()].toSorted((x, y) => y[1] - x[1]).slice(0, 3).map(([name]) => name);
+}
+function visitsToClips(visits, events, pad, vouched) {
+	const tagged = [
+		...events.object.map((event) => ({
+			kind: "object",
+			event
+		})),
+		...events.motion.map((event) => ({
+			kind: "motion",
+			event
+		})),
+		...events.audio.map((event) => ({
+			kind: "audio",
+			event
+		}))
+	];
+	return visits.map((visit) => {
+		const attached = tagged.filter((t) => eventOverlapsVisit(t.event, visit, pad));
+		const kind = dominantKind(attached);
+		const withThumb = attached.find((a) => a.kind === kind && a.event.mediaUrl && vouched.has(a.event.id)) ?? attached.find((a) => a.event.mediaUrl && vouched.has(a.event.id));
+		const stillAtMs = stillInstantMs(visit.ranges);
+		const labels = dominantLabels(attached);
+		return {
+			id: `analytics:${visit.startMs}:${visit.endMs}:${VISIT_EVENT_ID}`,
+			source: "analytics",
+			kind,
+			timeRange: {
+				startMs: visit.startMs,
+				endMs: visit.endMs
+			},
+			...withThumb?.event.mediaUrl !== void 0 ? { thumbnail: withThumb.event.mediaUrl } : {},
+			...stillAtMs !== void 0 ? { stillAtMs } : {},
+			eventIds: attached.slice(0, 24).map((a) => a.event.id),
+			eventCount: attached.length,
+			holes: [...visit.holes],
+			...labels.length > 0 ? { labels } : {}
+		};
+	}).toSorted((a, b) => b.timeRange.startMs - a.timeRange.startMs);
+}
+//#endregion
+//#region src/recorder/addon/videoclips-provider.ts
+/**
+* Default `videoclips` provider — composes recorded footage visits with the
+* analytics event log. A clip is a time-WINDOW over existing footage, never a
+* separate file: `getClipPlayback` resolves to
+* `recording.getPlaybackManifest(startMs, endMs)`.
+*
+* When availability is present the grain is a *visit* (events-mode keep-window
+* clustered at `VISIT_MERGE_GAP_MS`), not one clip per motion heartbeat. The
+* clip id still encodes the window (`analytics:<startMs>:<endMs>:visit`) so
+* playback is self-contained. Without availability (or when that read fails)
+* the provider falls back to per-event padded windows.
+*
+* Pure helpers (`eventsToClips` / `clusterFootageVisits` / `clipIdFor` /
+* `parseClipId`) are unit-tested in isolation; the provider factory wires
+* injected fetch/resolve deps so the compose logic is testable without I/O.
+*/
+var SOURCE = "analytics";
+/** The addon that registers this provider — stamped on its source row. */
+var CLIP_SOURCE_ADDON_ID = "recorder";
+/**
+* Backstop on the ANNOTATION read — never on the clip list.
+*
+* A visit is annotated by every event inside it, so the clip `limit` must not
+* reach this fetch (one 615 visit legitimately spans 2 345 motion rows). This
+* bound exists only so a pathological camera-day cannot pull an unbounded page:
+* the store orders `timestamp DESC`, so a truncation drops the OLDEST rows and
+* the EARLIEST visits silently lose their annotations — which is why hitting it
+* is logged, per camera, rather than absorbed.
+*/
+var VISIT_EVENT_FETCH_LIMIT = 5e3;
+function clipIdFor(eventId, startMs, endMs) {
+	return `${SOURCE}:${startMs}:${endMs}:${eventId}`;
+}
+/** Parse a default-provider clip id back into its window + event id. Returns
+*  `null` for any id this provider did not mint (e.g. a native clip id). */
+function parseClipId(clipId) {
+	const parts = clipId.split(":");
+	if (parts.length < 4 || parts[0] !== SOURCE) return null;
+	const startMs = Number(parts[1]);
+	const endMs = Number(parts[2]);
+	if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) return null;
+	const eventId = parts.slice(3).join(":");
+	if (!eventId) return null;
+	return {
+		eventId,
+		startMs,
+		endMs
+	};
+}
+/** Map per-kind events into time-ranged clips, newest-first. Pure. */
+function eventsToClips(events, pad, vouched) {
+	const make = (e, kind) => {
+		const startMs = e.timestamp - pad.preMs;
+		const endMs = e.timestamp + pad.postMs;
+		return {
+			id: clipIdFor(e.id, startMs, endMs),
+			source: SOURCE,
+			kind,
+			timeRange: {
+				startMs,
+				endMs
+			},
+			...e.mediaUrl !== void 0 && vouched.has(e.id) ? { thumbnail: e.mediaUrl } : {}
+		};
+	};
+	return [
+		...events.motion.map((e) => make(e, "motion")),
+		...events.object.map((e) => make(e, "object")),
+		...events.audio.map((e) => make(e, "audio"))
+	].toSorted((a, b) => b.timeRange.startMs - a.timeRange.startMs);
+}
+/** Every id in the three buckets, in the order the composers tag them. */
+function allEventIds(events) {
+	return [
+		...events.motion,
+		...events.object,
+		...events.audio
+	].map((e) => e.id);
+}
+/**
+* Resolve the event ids whose `mediaUrl` is backed by real bytes, mirroring
+* `resolveDefaultEventMedia`: the event's OWN media when it has any, else its
+* owning TRACK's. Up to four batched index reads — one PER EVENT KIND that has
+* any ids (D476: `motion` / `object` / `audio` are separate owner kinds now,
+* so a single combined read can no longer ask "does any of these ids own
+* media" — a motion id and an object id can be the same number post-D474 and
+* are answered by different rows) — plus the track fallback, only over the
+* object events the first pass did not already answer for (motion and audio
+* are trackless roots, so they never need it).
+*
+* THROWS on a failed read. The caller fails closed on the CLAIM and open on the
+* LIST; swallowing here would collapse those two opposite directions into one.
+*/
+async function resolveVouchedEvents(deviceId, events, fetchMediaOwners) {
+	const ownMedia = /* @__PURE__ */ new Set();
+	for (const ownerType of require_dist.EVENT_OWNER_TYPES) {
+		const ownerIds = events[ownerType].map((e) => e.id);
+		if (ownerIds.length === 0) continue;
+		const found = await fetchMediaOwners({
+			deviceId,
+			ownerKind: ownerType,
+			ownerIds
+		});
+		for (const id of found) ownMedia.add(id);
+	}
+	const residualTracks = [];
+	const seenTracks = /* @__PURE__ */ new Set();
+	for (const event of events.object) {
+		const trackId = event.trackId;
+		if (trackId === void 0 || ownMedia.has(event.id) || seenTracks.has(trackId)) continue;
+		seenTracks.add(trackId);
+		residualTracks.push(trackId);
+	}
+	const trackMedia = residualTracks.length === 0 ? /* @__PURE__ */ new Set() : await fetchMediaOwners({
+		deviceId,
+		ownerKind: "track",
+		ownerIds: residualTracks
+	});
+	const vouched = new Set(ownMedia);
+	for (const event of events.object) {
+		const trackId = event.trackId;
+		if (trackId !== void 0 && trackMedia.has(trackId)) vouched.add(event.id);
+	}
+	return vouched;
+}
+/** Keep only clips that actually touch the caller's window. The reads are
+*  widened by {@link leftOverhangMs}; the ANSWER is not. */
+function intersectsWindow(clip, since, until) {
+	return clip.timeRange.startMs < until && clip.timeRange.endMs > since;
+}
+/**
+* How far BEFORE `since` the event + availability reads must reach.
+*
+* A visit straddling `since` keeps its heartbeat rows and loses the transition
+* row — the only one that ever carries a snapshot — so the same visit shows a
+* picture or doesn't depending on where the operator scrolled. One wider range
+* scan on an indexed column buys a list that stops changing under the cursor.
+*/
+function leftOverhangMs(pad) {
+	return require_dist.VISIT_MERGE_GAP_MS + pad.preMs;
+}
+/** No events at all — what the degraded branch annotates its visits with. */
+var NO_EVENTS = {
+	motion: [],
+	object: [],
+	audio: []
+};
+function createVideoclipsProvider(deps) {
+	/**
+	* Cameras whose LAST `listClips` could not read the analytics event log, with
+	* the refusal verbatim.
+	*
+	* Not a cache of anybody else's fact (D224): it is this provider reporting
+	* what IT just did, refreshed on the same call that produces it and cleared
+	* by the next read that succeeds. `listSources` has no window argument and
+	* must not go and ask again — an extra events read on the listing path would
+	* be a second, disagreeing answer to the question `listClips` already
+	* answered.
+	*/
+	const eventsUnreachable = /* @__PURE__ */ new Map();
+	return {
+		listClips: async ({ deviceId, since, until, limit }) => {
+			const readSince = since - leftOverhangMs(deps.defaultPad);
+			let events;
+			try {
+				events = await deps.fetchEvents({
+					deviceId,
+					since: readSince,
+					until,
+					limit: deps.fetchAvailability ? VISIT_EVENT_FETCH_LIMIT : limit
+				});
+			} catch (err) {
+				return await listWithoutEvents(deps, eventsUnreachable, errMessage(err), {
+					deviceId,
+					since,
+					until,
+					readSince,
+					limit
+				});
+			}
+			eventsUnreachable.delete(deviceId);
+			warnOnTruncatedFetch(deps, deviceId, events);
+			let vouched = /* @__PURE__ */ new Set();
+			try {
+				vouched = await resolveVouchedEvents(deviceId, events, deps.fetchMediaOwners);
+			} catch (err) {
+				deps.logWarn?.("videoclips: media presence read failed — listing without thumbnails", {
+					deviceId,
+					events: allEventIds(events).length,
+					error: err instanceof Error ? err.message : String(err)
+				});
+			}
+			let clips = eventsToClips(events, deps.defaultPad, vouched);
+			if (deps.fetchAvailability) try {
+				clips = visitsToClips(clusterFootageVisits(await deps.fetchAvailability({
+					deviceId,
+					since: readSince,
+					until
+				}), require_dist.VISIT_MERGE_GAP_MS), events, deps.defaultPad, vouched);
+			} catch (err) {
+				deps.logWarn?.("videoclips: availability read failed — listing unfiltered", {
+					deviceId,
+					error: err instanceof Error ? err.message : String(err)
+				});
+			}
+			const inWindow = clips.filter((c) => intersectsWindow(c, since, until));
+			const answer = limit != null ? inWindow.slice(0, limit) : inWindow;
+			reportUnvouchedClips(deps, deviceId, answer);
+			return answer;
+		},
+		/**
+		* The one source this provider serves, on every camera: the hub's own
+		* analytics visits over recorded footage.
+		*
+		* Always `ok`, and that is not optimism — this source IS the process
+		* answering the call, so there is no reachability question to report. A
+		* read that fails INSIDE `listClips` degrades that list (and logs it); a
+		* source that cannot be reached at all is reported by the collection
+		* dispatcher, which is the only layer that can tell the difference.
+		* `label` is what the picker draws.
+		*/
+		listSources: async ({ deviceId }) => {
+			const outage = eventsUnreachable.get(deviceId);
+			return [{
+				source: SOURCE,
+				addonId: CLIP_SOURCE_ADDON_ID,
+				label: "CamStack recordings",
+				availability: outage === void 0 ? { state: "ok" } : {
+					state: "ok",
+					reason: `${EVENTS_UNREACHABLE_NOTICE} (${outage})`
+				}
+			}];
+		},
+		getClipPlayback: async ({ deviceId, clipId }) => {
+			const parsed = parseClipId(clipId);
+			if (!parsed) throw new Error(`videoclips: unrecognized clipId "${clipId}"`);
+			return {
+				...await deps.resolvePlayback({
+					deviceId,
+					startMs: parsed.startMs,
+					endMs: parsed.endMs
+				}),
+				format: "hls"
+			};
+		}
+	};
+}
+/** What the source row says while the event log is down. */
+var EVENTS_UNREACHABLE_NOTICE = "The analytics event log could not be read on the last listing — these clips are recorded footage only, with no labels, stills or event counts";
+function errMessage(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/**
+* Footage present, EVENTS unreachable — the mirror of the two degradations
+* this provider already had, and the one that could not happen while a single
+* addon held both halves (D560).
+*
+* A visit is a window over recorded footage; the events only ANNOTATE it. So
+* when availability answers, the visits are still real and still playable —
+* their ids encode the window — and the honest answer is that list without its
+* annotations. An availability that answered `[]` yields an empty list that is
+* TRUE about footage: with availability present a clip only ever comes from a
+* recorded range, so it is the same answer a successful events read would have
+* given.
+*
+* Without availability (absent, or its read failed too) the clips ARE the
+* events, so there is nothing left that is true to say. That is a REFUSAL
+* naming both reads — never an empty list, which reads as "this camera has no
+* recordings".
+*/
+async function listWithoutEvents(deps, eventsUnreachable, reason, window) {
+	const { deviceId, since, until, readSince, limit } = window;
+	const fetchAvailability = deps.fetchAvailability;
+	if (fetchAvailability === void 0) {
+		eventsUnreachable.set(deviceId, reason);
+		throw new Error(`videoclips: the analytics event log is unreachable for device ${deviceId} (${reason}) and this source lists no recorded footage — refusing rather than answering an empty list`);
+	}
+	let ranges;
+	try {
+		ranges = await fetchAvailability({
+			deviceId,
+			since: readSince,
+			until
+		});
+	} catch (err) {
+		eventsUnreachable.set(deviceId, reason);
+		throw new Error(`videoclips: neither read answered for device ${deviceId} — events: ${reason}; footage: ${errMessage(err)}. Refusing rather than answering an empty list.`);
+	}
+	eventsUnreachable.set(deviceId, reason);
+	deps.logWarn?.("videoclips: event log unreachable — listing the recorded footage visits without their events", {
+		deviceId,
+		error: reason,
+		ranges: ranges.length
+	});
+	const clips = visitsToClips(clusterFootageVisits(ranges, require_dist.VISIT_MERGE_GAP_MS), NO_EVENTS, deps.defaultPad, /* @__PURE__ */ new Set()).filter((clip) => intersectsWindow(clip, since, until));
+	return limit != null ? clips.slice(0, limit) : clips;
+}
+/** The annotation backstop biting is a SILENT loss of the earliest visits'
+*  events — say so, per camera, instead of shipping a thinner list. */
+function warnOnTruncatedFetch(deps, deviceId, events) {
+	if (!deps.fetchAvailability) return;
+	const truncated = [
+		"motion",
+		"object",
+		"audio"
+	].filter((kind) => events[kind].length >= VISIT_EVENT_FETCH_LIMIT);
+	if (truncated.length === 0) return;
+	deps.logWarn?.("videoclips: annotation fetch truncated — earliest visits lose their events", {
+		deviceId,
+		kinds: truncated,
+		limit: VISIT_EVENT_FETCH_LIMIT
+	});
+}
+/** The operator's acceptance criterion as a number: a rising count on one
+*  camera is its motion-snapshot capturer failing, not a quiet day. */
+function reportUnvouchedClips(deps, deviceId, clips) {
+	const clipsWithoutStill = clips.filter((c) => c.thumbnail === void 0).length;
+	if (clipsWithoutStill === 0) return;
+	deps.logInfo?.("videoclips: visit has no vouched still", {
+		deviceId,
+		clipsWithoutStill,
+		clips: clips.length
+	});
+}
+//#endregion
+//#region src/recorder/addon/videoclips-shared.ts
+/** Stringify the numeric event ids of one bucket. Lossless. */
+function toEventLike(events) {
+	return events.map((e) => ({
+		...e,
+		id: String(e.id)
+	}));
+}
+//#endregion
+//#region src/recorder/addon/videoclips-wiring.ts
+/**
+* The `videoclips` source over THIS addon's archive — the deps half.
+*
+* The composer (`videoclips-provider.ts`, `videoclip-visits.ts`) is unchanged
+* and moved here verbatim from `addon-post-analysis`: a clip is still a time
+* WINDOW over recorded footage, visits are still clustered at
+* `VISIT_MERGE_GAP_MS`, and `getClipPlayback` still resolves through
+* `recording.getPlaybackManifest`. What moved is WHO registers it — the addon
+* that owns the footage, not one that borrowed it (D560).
+*
+* All four reads go over `ctx.api`, the recorder's own two included. That is
+* not laziness:
+*
+*   - `recorder` is `placement: 'any-node'`, so several nodes register this
+*     capability and the hub's collection dispatcher resolves the binding to
+*     ONE of them (`addonIdentityOf` strips the `@<nodeId>`). That registration
+*     is not necessarily the node holding this camera's segments.
+*   - `ctx.api.recording.*` is device-scoped and routes to the node that IS
+*     holding them. A short cut to the local `RecordingProvider` would answer a
+*     camera recorded on little-unraid out of the hub's empty index — an empty
+*     clip list on a camera with weeks of footage, which is the exact
+*     misreading this whole line of work exists to end.
+*
+* The events arriving over a process boundary is the new failure mode, and the
+* provider answers it per branch — see `listWithoutEvents`.
+*/
+/**
+* Every log line about a camera carries `tags: { deviceId }`, always the
+* numeric id. A miss rate or a media gap is always asked per camera, and a line
+* that omits the tag cannot answer it.
+*/
+function stamp(logger, level) {
+	return (message, meta) => {
+		logger[level](message, {
+			tags: { deviceId: Number(meta["deviceId"]) },
+			meta
+		});
+	};
+}
+function createRecorderVideoclipsProvider(deps) {
+	const api = deps.api;
+	return createVideoclipsProvider({
+		defaultPad: require_dist.EVENT_PAD_MS,
+		fetchEvents: async ({ deviceId, since, until, limit }) => {
+			const query = {
+				deviceId,
+				since,
+				until,
+				limit,
+				projection: "slim"
+			};
+			const [motion, object, audio] = await Promise.all([
+				api.pipelineAnalytics.getMotionEvents.query(query),
+				api.pipelineAnalytics.getObjectEvents.query(query),
+				api.pipelineAnalytics.getAudioEvents.query(query)
+			]);
+			return {
+				motion: toEventLike(motion),
+				object: toEventLike(object),
+				audio: toEventLike(audio)
+			};
+		},
+		fetchMediaOwners: async ({ deviceId, ownerKind, ownerIds }) => new Set(await api.pipelineAnalytics.ownersWithMedia.query({
+			deviceId,
+			ownerKind,
+			ownerIds
+		})),
+		fetchAvailability: async ({ deviceId, since, until }) => (await api.recording.getAvailability.query({
+			deviceId,
+			fromMs: since,
+			toMs: until
+		})).ranges,
+		logWarn: stamp(deps.logger, "warn"),
+		logInfo: stamp(deps.logger, "info"),
+		resolvePlayback: async ({ deviceId, startMs, endMs }) => {
+			const manifest = await api.recording.getPlaybackManifest.query({
+				deviceId,
+				fromMs: startMs,
+				toMs: endMs
+			});
+			if (manifest.playbackUrl == null) throw new Error(`videoclips: no footage for clip window [${String(startMs)},${String(endMs)}] on device ${String(deviceId)}`);
+			return {
+				playbackUrl: manifest.playbackUrl,
+				...manifest.playbackEndpoints === void 0 ? {} : { playbackEndpoints: [...manifest.playbackEndpoints] }
+			};
+		}
+	});
+}
+//#endregion
 //#region src/recorder/band-engine.ts
 function toMin(hhmm) {
 	const [h, m] = hhmm.split(":");
@@ -18653,6 +19214,13 @@ var RecorderV2Addon = class extends require_dist.BaseAddon {
 				capability: require_dist.recordingCapability,
 				provider: recordingProvider
 			},
+			{
+				capability: require_dist.videoclipsCapability,
+				provider: createRecorderVideoclipsProvider({
+					api: this.ctx.api,
+					logger: this.ctx.logger
+				})
+			},
 			{
 				capability: require_dist.storageEvictableCapability,
 				provider: evictableProvider