@camstack/addon-pipeline 1.1.66 → 1.1.67

package/dist/session-decode/decode-worker-child.js

@@ -6,6 +6,133 @@ let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs);
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);
+//#region src/session-decode/color-conversion.ts
+/**
+* Explicit YUV→RGB colorspace/range resolution for the session-decode worker.
+*
+* WHY THIS EXISTS (RC-5, `docs/superpowers/specs/2026-07-19-track-media-bugs-analysis.md`):
+* an intermittent ~one-GOP DESATURATED stretch was measured on cam 615 — the
+* classic "limited-range YUV interpreted as full-range" signature (lifted
+* blacks, washed color, JPEG size collapse). Root cause: NONE of the decode
+* worker's YUV→RGB conversion sites pinned an explicit colorspace/range, so the
+* conversion depended on whatever `colorspace`/`color_range` metadata each
+* decoded frame happened to carry. A GOP replayed/decoded by a DIFFERENT path
+* (hwaccel-cascade / keyframe-seed fallback, see `docs/design/decode-path.md`)
+* can carry UNSPECIFIED (or a different) range, which the libav auto-inserted
+* converter then guesses differently than its neighbours → one washed-out GOP,
+* then a snap back.
+*
+* The fix is to resolve every frame's source color to an EXPLICIT
+* `(matrix, range)` — using the frame's own tags when present, and a STABLE
+* default (bt709 / limited, the typical H.264/H.265 HD signalling) when they
+* are unspecified — and to pin the conversion to that + full-range RGB output
+* IDENTICALLY at every site. An unspecified/fallback GOP then converts exactly
+* like its neighbours instead of being auto-guessed, so the desaturation cannot
+* recur regardless of which decode path produced the GOP.
+*
+* These functions operate on the raw FFmpeg `AVColorSpace` / `AVColorRange`
+* enum integers (stable ABI values) so they are unit-testable without loading
+* node-av. node-av's branded `AVColorSpace`/`AVColorRange` are `number`
+* subtypes and pass through directly.
+*/
+/**
+* FFmpeg `AVColorSpace` enum values we map to a libswscale/`scale`-filter
+* `in_color_matrix` token. Stable ABI integers (libavutil `pixfmt.h`).
+*/
+var AVCOL_SPC_BT709 = 1;
+var AVCOL_SPC_FCC = 4;
+var AVCOL_SPC_BT470BG = 5;
+var AVCOL_SPC_SMPTE170M = 6;
+var AVCOL_SPC_SMPTE240M = 7;
+var AVCOL_SPC_BT2020_NCL = 9;
+var AVCOL_SPC_BT2020_CL = 10;
+/** FFmpeg `AVColorRange` enum values. Stable ABI integers. */
+var AVCOL_RANGE_MPEG = 1;
+var AVCOL_RANGE_JPEG = 2;
+/**
+* Default source matrix when the frame carries no (or an unusable) colorspace
+* tag — bt709, the near-universal signalling for HD H.264/H.265 IP cameras.
+*/
+var DEFAULT_COLOR_MATRIX = "bt709";
+/**
+* Default source range when the frame carries no (or an unspecified) range tag
+* — limited/mpeg, the near-universal signalling for camera video. Guessing
+* full here is the exact mistake that produced the desaturated GOP.
+*/
+var DEFAULT_COLOR_RANGE = "limited";
+/**
+* Output RGB range — always FULL (0-255). Every RGB conversion site converges
+* on this so downstream media/inference sees a single, path-independent RGB
+* contract.
+*/
+var OUTPUT_RGB_RANGE = "full";
+/** Map an `AVColorSpace` enum integer to a `scale`-filter matrix token. */
+function resolveColorMatrix(colorSpace) {
+	switch (colorSpace) {
+		case AVCOL_SPC_BT709: return "bt709";
+		case AVCOL_SPC_BT470BG:
+		case AVCOL_SPC_SMPTE170M: return "bt601";
+		case AVCOL_SPC_FCC: return "fcc";
+		case AVCOL_SPC_SMPTE240M: return "smpte240m";
+		case AVCOL_SPC_BT2020_NCL:
+		case AVCOL_SPC_BT2020_CL: return "bt2020nc";
+		default: return DEFAULT_COLOR_MATRIX;
+	}
+}
+/** Map an `AVColorRange` enum integer to a `scale`-filter range token. */
+function resolveColorRange(colorRange) {
+	switch (colorRange) {
+		case AVCOL_RANGE_JPEG: return "full";
+		case AVCOL_RANGE_MPEG: return "limited";
+		default: return DEFAULT_COLOR_RANGE;
+	}
+}
+/**
+* Resolve a frame's `(colorSpace, colorRange)` tags to the explicit
+* `(matrix, range)` every conversion site pins — applying the stable defaults
+* when a tag is unspecified/unusable.
+*/
+function resolveSourceColor(colorSpace, colorRange) {
+	return {
+		inColorMatrix: resolveColorMatrix(colorSpace),
+		inRange: resolveColorRange(colorRange),
+		colorSpaceDefaulted: !(colorSpace === AVCOL_SPC_BT709 || colorSpace === AVCOL_SPC_BT470BG || colorSpace === AVCOL_SPC_SMPTE170M || colorSpace === AVCOL_SPC_FCC || colorSpace === AVCOL_SPC_SMPTE240M || colorSpace === AVCOL_SPC_BT2020_NCL || colorSpace === AVCOL_SPC_BT2020_CL),
+		colorRangeDefaulted: !(colorRange === AVCOL_RANGE_JPEG || colorRange === AVCOL_RANGE_MPEG),
+		rawColorSpace: colorSpace,
+		rawColorRange: colorRange
+	};
+}
+/**
+* The `scale`-filter option fragment that pins the explicit YUV→(full)RGB
+* conversion — appended to a `scale=...` filter in the GPU/CPU filtergraph
+* (`scale=W:H:<fragment>` or `scale=<fragment>` for an identity-size convert).
+* Always converges output on full-range RGB; `out_color_matrix` is intentionally
+* omitted (irrelevant for an RGB/gray packed output).
+*/
+function colorConvertFilterOptions(resolved) {
+	return `in_color_matrix=${resolved.inColorMatrix}:in_range=${resolved.inRange}:out_range=${OUTPUT_RGB_RANGE}`;
+}
+/**
+* A stable cache key for the resolved source color — folded into the GPU
+* filtergraph key so a mid-session colorspace/range change rebuilds the graph
+* (and re-emits the provenance transition marker) instead of reusing a graph
+* pinned to the old color.
+*/
+function sourceColorKey(resolved) {
+	return `${resolved.inColorMatrix}:${resolved.inRange}`;
+}
+/**
+* One-line provenance marker: which decode/scale path produced a frame + the
+* (raw and resolved) source color it was converted with. Emitted on a color
+* TRANSITION (rare, diagnostic-gold: pinpoints an intermittent recurrence) and,
+* behind the debug flag, per frame. Includes a trailing newline for `emitStderr`.
+*/
+function colorProvenanceLine(path, resolved, transition) {
+	const spaceTag = resolved.colorSpaceDefaulted ? `${resolved.rawColorSpace}->${resolved.inColorMatrix}(default)` : `${resolved.rawColorSpace}->${resolved.inColorMatrix}`;
+	const rangeTag = resolved.colorRangeDefaulted ? `${resolved.rawColorRange}->${resolved.inRange}(default)` : `${resolved.rawColorRange}->${resolved.inRange}`;
+	return `session-decode color${transition ? " TRANSITION" : ""} {path:${path}, colorSpace:${spaceTag}, colorRange:${rangeTag}, out:rgb-${OUTPUT_RGB_RANGE}}\n`;
+}
+//#endregion
 //#region src/session-decode/crop-geometry.ts
 /** Clamp to [min,max] then floor to the nearest even number (YUV420P chroma is 2x2 subsampled). */
 function clampEven(value, min, max) {
@@ -638,9 +765,10 @@ function backendToHwDeviceConst(backend, consts) {
 * It is correct and never crashes; it just forgoes the GPU win for that rare
 * call — exactly the safety/behaviour trade-off the task calls for.
 */
-function buildGpuFilterDescription(scaleFilter, region, target, fullFrame, pixel) {
-	if (fullFrame) return `${scaleFilter}=w=${target.width}:h=${target.height},hwdownload,format=nv12,format=${pixel}`;
-	return `hwdownload,format=nv12,crop=${region.width}:${region.height}:${region.left}:${region.top},scale=${target.width}:${target.height},format=${pixel}`;
+function buildGpuFilterDescription(scaleFilter, region, target, fullFrame, pixel, color) {
+	const convert = `scale=${colorConvertFilterOptions(color)}`;
+	if (fullFrame) return `${scaleFilter}=w=${target.width}:h=${target.height},hwdownload,format=nv12,${convert},format=${pixel}`;
+	return `hwdownload,format=nv12,crop=${region.width}:${region.height}:${region.left}:${region.top},scale=${target.width}:${target.height}:${colorConvertFilterOptions(color)},format=${pixel}`;
 }
 /**
 * Copy a single-plane packed frame (rgb24 / gray8 out of the filtergraph) into
@@ -771,6 +899,15 @@ var DecodeWorkerChild = class {
 	/** Throttled native-crop hit/miss counters, emitted with the throughput line. */
 	nativeCropHits = 0;
 	nativeCropMisses = 0;
+	/**
+	* Last `(path, rawColorSpace, rawColorRange)` provenance key emitted — a
+	* change re-emits a one-line TRANSITION marker (RC-5 diagnostic: pinpoints an
+	* intermittent desaturation recurrence by showing the exact GOP whose color
+	* tags drifted). See {@link logColorProvenance}.
+	*/
+	lastColorProvenanceKey = "";
+	/** Per-frame color provenance logging (opt-in; the transition marker is always on). */
+	colorDebug = process.env["CAMSTACK_DECODE_COLOR_DEBUG"] === "1";
 	/** Scrypted-style throughput counters (plain integers, no per-frame allocation). */
 	framesDecoded = 0;
 	/** Child-side skips only (HW-guard drops + probe/degrade frees); slot drops add {@link FrameSlot.droppedCount}. */
@@ -971,6 +1108,28 @@ var DecodeWorkerChild = class {
 		return this.nativeRing.get(frameId) ?? this.frames.toBuffer(frameId);
 	}
 	/**
+	* Resolve a decoded frame's `(colorSpace, colorRange)` tags to the EXPLICIT
+	* `(matrix, range)` every RGB conversion site pins — the RC-5 fix. `colorSpace`
+	* / `colorRange` are node-av branded `number` subtypes, so they pass to the
+	* plain-number helper directly.
+	*/
+	resolveFrameColor(frame) {
+		return resolveSourceColor(frame.colorSpace, frame.colorRange);
+	}
+	/**
+	* Emit the color-provenance marker: which decode/scale path produced this
+	* frame + its raw and resolved source color. Always logs on a TRANSITION (the
+	* path or the frame's raw color tags changed vs the last emit — rare, and the
+	* exact signal a desaturation recurrence leaves); logs every frame only under
+	* the `CAMSTACK_DECODE_COLOR_DEBUG` flag.
+	*/
+	logColorProvenance(path, color) {
+		const key = `${path}|${color.rawColorSpace}|${color.rawColorRange}`;
+		const transition = key !== this.lastColorProvenanceKey;
+		if (transition) this.lastColorProvenanceKey = key;
+		if (transition || this.colorDebug) this.emitStderr(colorProvenanceLine(path, color, transition));
+	}
+	/**
 	* Retain a just-superseded DELIVERED frame for later native crops. Transfers
 	* ownership from the {@link FrameSlot} (the caller MUST NOT free when this
 	* returns `true`).
@@ -1053,6 +1212,7 @@ var DecodeWorkerChild = class {
 		const nav = this.nav;
 		const C = this.consts;
 		if (!nav || !C) throw new Error("node-av not initialized");
+		this.logColorProvenance("sw-crop", this.resolveFrameColor(frame));
 		const { region, target } = resolved;
 		const planes = frame.data;
 		const strides = frame.linesize;
@@ -1091,7 +1251,9 @@ var DecodeWorkerChild = class {
 	*/
 	nativeHwCropToBuffer(frame, resolved) {
 		const { region, target } = resolved;
-		const outputs = this.ensureNativeCropHwFilter(region, target).processAllSync(frame);
+		const color = this.resolveFrameColor(frame);
+		this.logColorProvenance("hw-crop", color);
+		const outputs = this.ensureNativeCropHwFilter(region, target, color).processAllSync(frame);
 		const first = outputs[0];
 		if (!first) {
 			for (const out of outputs) out.free();
@@ -1125,17 +1287,17 @@ var DecodeWorkerChild = class {
 		return scaler;
 	}
 	/** Build-once / reuse the dedicated native-crop GPU filtergraph (rgb out). */
-	ensureNativeCropHwFilter(region, target) {
+	ensureNativeCropHwFilter(region, target, color) {
 		const nav = this.nav;
 		const scaleFilter = this.gpuScaleFilter;
 		if (!nav || !scaleFilter || !this.hwContext) throw new Error("decode-worker-child: native GPU crop requested without a HW context");
-		const key = `${region.left},${region.top},${region.width},${region.height}->${target.width}x${target.height}`;
+		const key = `${region.left},${region.top},${region.width},${region.height}->${target.width}x${target.height}:${sourceColorKey(color)}`;
 		const cached = this.nativeCropHwFilter;
 		if (cached && key === this.nativeCropHwFilterKey) return cached;
 		this.nativeCropHwFilter?.close();
 		this.nativeCropHwFilter = null;
 		this.nativeCropHwFilterKey = "";
-		const description = buildGpuFilterDescription(scaleFilter, region, target, false, "rgb24");
+		const description = buildGpuFilterDescription(scaleFilter, region, target, false, "rgb24", color);
 		const filter = nav.FilterAPI.create(description, { hardware: this.hwContext });
 		this.nativeCropHwFilter = filter;
 		this.nativeCropHwFilterKey = key;
@@ -1344,6 +1506,7 @@ var DecodeWorkerChild = class {
 		const format = opts?.format ?? this.sessionFormat;
 		const dstFmt = format === "gray" ? C.AV_PIX_FMT_GRAY8 : C.AV_PIX_FMT_RGB24;
 		const channels = format === "gray" ? 1 : 3;
+		this.logColorProvenance(isFullFrameRegion(region, frame.width, frame.height) ? "sw-fullframe" : "sw-crop", this.resolveFrameColor(frame));
 		const planes = frame.data;
 		const strides = frame.linesize;
 		const yPlane = planes?.[0];
@@ -1415,7 +1578,9 @@ var DecodeWorkerChild = class {
 			const target = resolveResizeTarget(region.width, region.height, opts?.resize);
 			const format = opts?.format ?? this.sessionFormat;
 			const channels = format === "gray" ? 1 : 3;
-			const outputs = this.ensureHwFilter(region, target, frame.width, frame.height, format).processAllSync(frame);
+			const color = this.resolveFrameColor(frame);
+			this.logColorProvenance(isFullFrameRegion(region, frame.width, frame.height) ? "hw-fullframe" : "hw-crop", color);
+			const outputs = this.ensureHwFilter(region, target, frame.width, frame.height, format, color).processAllSync(frame);
 			const first = outputs[0];
 			if (!first) throw new Error("GPU filtergraph produced no frame");
 			try {
@@ -1437,19 +1602,19 @@ var DecodeWorkerChild = class {
 	* only when the key changes; detection's ROI + resize target are stable, so
 	* this is a per-worker singleton in the steady state.
 	*/
-	ensureHwFilter(region, target, srcW, srcH, format) {
+	ensureHwFilter(region, target, srcW, srcH, format, color) {
 		const nav = this.nav;
 		const scaleFilter = this.gpuScaleFilter;
 		if (!nav || !scaleFilter || !this.hwContext) throw new Error("decode-worker-child: GPU filter requested without a HW context");
 		const fullFrame = isFullFrameRegion(region, srcW, srcH);
 		const pixel = pixelFilterName(format);
-		const key = `${region.left},${region.top},${region.width},${region.height}->${target.width}x${target.height}:${pixel}`;
+		const key = `${region.left},${region.top},${region.width},${region.height}->${target.width}x${target.height}:${pixel}:${sourceColorKey(color)}`;
 		const cached = this.hwFilter;
 		if (cached && key === this.hwFilterKey) return cached;
 		this.hwFilter?.close();
 		this.hwFilter = null;
 		this.hwFilterKey = "";
-		const description = buildGpuFilterDescription(scaleFilter, region, target, fullFrame, pixel);
+		const description = buildGpuFilterDescription(scaleFilter, region, target, fullFrame, pixel, color);
 		const filter = nav.FilterAPI.create(description, { hardware: this.hwContext });
 		this.hwFilter = filter;
 		this.hwFilterKey = key;

package/dist/session-decode/decode-worker-child.mjs

@@ -2,6 +2,133 @@ import { n as isWorkerRequest } from "../worker-protocol-CyVJTZEO.mjs";
 import { pathToFileURL } from "node:url";
 import * as fs from "node:fs";
 import * as path$1 from "node:path";
+//#region src/session-decode/color-conversion.ts
+/**
+* Explicit YUV→RGB colorspace/range resolution for the session-decode worker.
+*
+* WHY THIS EXISTS (RC-5, `docs/superpowers/specs/2026-07-19-track-media-bugs-analysis.md`):
+* an intermittent ~one-GOP DESATURATED stretch was measured on cam 615 — the
+* classic "limited-range YUV interpreted as full-range" signature (lifted
+* blacks, washed color, JPEG size collapse). Root cause: NONE of the decode
+* worker's YUV→RGB conversion sites pinned an explicit colorspace/range, so the
+* conversion depended on whatever `colorspace`/`color_range` metadata each
+* decoded frame happened to carry. A GOP replayed/decoded by a DIFFERENT path
+* (hwaccel-cascade / keyframe-seed fallback, see `docs/design/decode-path.md`)
+* can carry UNSPECIFIED (or a different) range, which the libav auto-inserted
+* converter then guesses differently than its neighbours → one washed-out GOP,
+* then a snap back.
+*
+* The fix is to resolve every frame's source color to an EXPLICIT
+* `(matrix, range)` — using the frame's own tags when present, and a STABLE
+* default (bt709 / limited, the typical H.264/H.265 HD signalling) when they
+* are unspecified — and to pin the conversion to that + full-range RGB output
+* IDENTICALLY at every site. An unspecified/fallback GOP then converts exactly
+* like its neighbours instead of being auto-guessed, so the desaturation cannot
+* recur regardless of which decode path produced the GOP.
+*
+* These functions operate on the raw FFmpeg `AVColorSpace` / `AVColorRange`
+* enum integers (stable ABI values) so they are unit-testable without loading
+* node-av. node-av's branded `AVColorSpace`/`AVColorRange` are `number`
+* subtypes and pass through directly.
+*/
+/**
+* FFmpeg `AVColorSpace` enum values we map to a libswscale/`scale`-filter
+* `in_color_matrix` token. Stable ABI integers (libavutil `pixfmt.h`).
+*/
+var AVCOL_SPC_BT709 = 1;
+var AVCOL_SPC_FCC = 4;
+var AVCOL_SPC_BT470BG = 5;
+var AVCOL_SPC_SMPTE170M = 6;
+var AVCOL_SPC_SMPTE240M = 7;
+var AVCOL_SPC_BT2020_NCL = 9;
+var AVCOL_SPC_BT2020_CL = 10;
+/** FFmpeg `AVColorRange` enum values. Stable ABI integers. */
+var AVCOL_RANGE_MPEG = 1;
+var AVCOL_RANGE_JPEG = 2;
+/**
+* Default source matrix when the frame carries no (or an unusable) colorspace
+* tag — bt709, the near-universal signalling for HD H.264/H.265 IP cameras.
+*/
+var DEFAULT_COLOR_MATRIX = "bt709";
+/**
+* Default source range when the frame carries no (or an unspecified) range tag
+* — limited/mpeg, the near-universal signalling for camera video. Guessing
+* full here is the exact mistake that produced the desaturated GOP.
+*/
+var DEFAULT_COLOR_RANGE = "limited";
+/**
+* Output RGB range — always FULL (0-255). Every RGB conversion site converges
+* on this so downstream media/inference sees a single, path-independent RGB
+* contract.
+*/
+var OUTPUT_RGB_RANGE = "full";
+/** Map an `AVColorSpace` enum integer to a `scale`-filter matrix token. */
+function resolveColorMatrix(colorSpace) {
+	switch (colorSpace) {
+		case AVCOL_SPC_BT709: return "bt709";
+		case AVCOL_SPC_BT470BG:
+		case AVCOL_SPC_SMPTE170M: return "bt601";
+		case AVCOL_SPC_FCC: return "fcc";
+		case AVCOL_SPC_SMPTE240M: return "smpte240m";
+		case AVCOL_SPC_BT2020_NCL:
+		case AVCOL_SPC_BT2020_CL: return "bt2020nc";
+		default: return DEFAULT_COLOR_MATRIX;
+	}
+}
+/** Map an `AVColorRange` enum integer to a `scale`-filter range token. */
+function resolveColorRange(colorRange) {
+	switch (colorRange) {
+		case AVCOL_RANGE_JPEG: return "full";
+		case AVCOL_RANGE_MPEG: return "limited";
+		default: return DEFAULT_COLOR_RANGE;
+	}
+}
+/**
+* Resolve a frame's `(colorSpace, colorRange)` tags to the explicit
+* `(matrix, range)` every conversion site pins — applying the stable defaults
+* when a tag is unspecified/unusable.
+*/
+function resolveSourceColor(colorSpace, colorRange) {
+	return {
+		inColorMatrix: resolveColorMatrix(colorSpace),
+		inRange: resolveColorRange(colorRange),
+		colorSpaceDefaulted: !(colorSpace === AVCOL_SPC_BT709 || colorSpace === AVCOL_SPC_BT470BG || colorSpace === AVCOL_SPC_SMPTE170M || colorSpace === AVCOL_SPC_FCC || colorSpace === AVCOL_SPC_SMPTE240M || colorSpace === AVCOL_SPC_BT2020_NCL || colorSpace === AVCOL_SPC_BT2020_CL),
+		colorRangeDefaulted: !(colorRange === AVCOL_RANGE_JPEG || colorRange === AVCOL_RANGE_MPEG),
+		rawColorSpace: colorSpace,
+		rawColorRange: colorRange
+	};
+}
+/**
+* The `scale`-filter option fragment that pins the explicit YUV→(full)RGB
+* conversion — appended to a `scale=...` filter in the GPU/CPU filtergraph
+* (`scale=W:H:<fragment>` or `scale=<fragment>` for an identity-size convert).
+* Always converges output on full-range RGB; `out_color_matrix` is intentionally
+* omitted (irrelevant for an RGB/gray packed output).
+*/
+function colorConvertFilterOptions(resolved) {
+	return `in_color_matrix=${resolved.inColorMatrix}:in_range=${resolved.inRange}:out_range=${OUTPUT_RGB_RANGE}`;
+}
+/**
+* A stable cache key for the resolved source color — folded into the GPU
+* filtergraph key so a mid-session colorspace/range change rebuilds the graph
+* (and re-emits the provenance transition marker) instead of reusing a graph
+* pinned to the old color.
+*/
+function sourceColorKey(resolved) {
+	return `${resolved.inColorMatrix}:${resolved.inRange}`;
+}
+/**
+* One-line provenance marker: which decode/scale path produced a frame + the
+* (raw and resolved) source color it was converted with. Emitted on a color
+* TRANSITION (rare, diagnostic-gold: pinpoints an intermittent recurrence) and,
+* behind the debug flag, per frame. Includes a trailing newline for `emitStderr`.
+*/
+function colorProvenanceLine(path, resolved, transition) {
+	const spaceTag = resolved.colorSpaceDefaulted ? `${resolved.rawColorSpace}->${resolved.inColorMatrix}(default)` : `${resolved.rawColorSpace}->${resolved.inColorMatrix}`;
+	const rangeTag = resolved.colorRangeDefaulted ? `${resolved.rawColorRange}->${resolved.inRange}(default)` : `${resolved.rawColorRange}->${resolved.inRange}`;
+	return `session-decode color${transition ? " TRANSITION" : ""} {path:${path}, colorSpace:${spaceTag}, colorRange:${rangeTag}, out:rgb-${OUTPUT_RGB_RANGE}}\n`;
+}
+//#endregion
 //#region src/session-decode/crop-geometry.ts
 /** Clamp to [min,max] then floor to the nearest even number (YUV420P chroma is 2x2 subsampled). */
 function clampEven(value, min, max) {
@@ -634,9 +761,10 @@ function backendToHwDeviceConst(backend, consts) {
 * It is correct and never crashes; it just forgoes the GPU win for that rare
 * call — exactly the safety/behaviour trade-off the task calls for.
 */
-function buildGpuFilterDescription(scaleFilter, region, target, fullFrame, pixel) {
-	if (fullFrame) return `${scaleFilter}=w=${target.width}:h=${target.height},hwdownload,format=nv12,format=${pixel}`;
-	return `hwdownload,format=nv12,crop=${region.width}:${region.height}:${region.left}:${region.top},scale=${target.width}:${target.height},format=${pixel}`;
+function buildGpuFilterDescription(scaleFilter, region, target, fullFrame, pixel, color) {
+	const convert = `scale=${colorConvertFilterOptions(color)}`;
+	if (fullFrame) return `${scaleFilter}=w=${target.width}:h=${target.height},hwdownload,format=nv12,${convert},format=${pixel}`;
+	return `hwdownload,format=nv12,crop=${region.width}:${region.height}:${region.left}:${region.top},scale=${target.width}:${target.height}:${colorConvertFilterOptions(color)},format=${pixel}`;
 }
 /**
 * Copy a single-plane packed frame (rgb24 / gray8 out of the filtergraph) into
@@ -767,6 +895,15 @@ var DecodeWorkerChild = class {
 	/** Throttled native-crop hit/miss counters, emitted with the throughput line. */
 	nativeCropHits = 0;
 	nativeCropMisses = 0;
+	/**
+	* Last `(path, rawColorSpace, rawColorRange)` provenance key emitted — a
+	* change re-emits a one-line TRANSITION marker (RC-5 diagnostic: pinpoints an
+	* intermittent desaturation recurrence by showing the exact GOP whose color
+	* tags drifted). See {@link logColorProvenance}.
+	*/
+	lastColorProvenanceKey = "";
+	/** Per-frame color provenance logging (opt-in; the transition marker is always on). */
+	colorDebug = process.env["CAMSTACK_DECODE_COLOR_DEBUG"] === "1";
 	/** Scrypted-style throughput counters (plain integers, no per-frame allocation). */
 	framesDecoded = 0;
 	/** Child-side skips only (HW-guard drops + probe/degrade frees); slot drops add {@link FrameSlot.droppedCount}. */
@@ -967,6 +1104,28 @@ var DecodeWorkerChild = class {
 		return this.nativeRing.get(frameId) ?? this.frames.toBuffer(frameId);
 	}
 	/**
+	* Resolve a decoded frame's `(colorSpace, colorRange)` tags to the EXPLICIT
+	* `(matrix, range)` every RGB conversion site pins — the RC-5 fix. `colorSpace`
+	* / `colorRange` are node-av branded `number` subtypes, so they pass to the
+	* plain-number helper directly.
+	*/
+	resolveFrameColor(frame) {
+		return resolveSourceColor(frame.colorSpace, frame.colorRange);
+	}
+	/**
+	* Emit the color-provenance marker: which decode/scale path produced this
+	* frame + its raw and resolved source color. Always logs on a TRANSITION (the
+	* path or the frame's raw color tags changed vs the last emit — rare, and the
+	* exact signal a desaturation recurrence leaves); logs every frame only under
+	* the `CAMSTACK_DECODE_COLOR_DEBUG` flag.
+	*/
+	logColorProvenance(path, color) {
+		const key = `${path}|${color.rawColorSpace}|${color.rawColorRange}`;
+		const transition = key !== this.lastColorProvenanceKey;
+		if (transition) this.lastColorProvenanceKey = key;
+		if (transition || this.colorDebug) this.emitStderr(colorProvenanceLine(path, color, transition));
+	}
+	/**
 	* Retain a just-superseded DELIVERED frame for later native crops. Transfers
 	* ownership from the {@link FrameSlot} (the caller MUST NOT free when this
 	* returns `true`).
@@ -1049,6 +1208,7 @@ var DecodeWorkerChild = class {
 		const nav = this.nav;
 		const C = this.consts;
 		if (!nav || !C) throw new Error("node-av not initialized");
+		this.logColorProvenance("sw-crop", this.resolveFrameColor(frame));
 		const { region, target } = resolved;
 		const planes = frame.data;
 		const strides = frame.linesize;
@@ -1087,7 +1247,9 @@ var DecodeWorkerChild = class {
 	*/
 	nativeHwCropToBuffer(frame, resolved) {
 		const { region, target } = resolved;
-		const outputs = this.ensureNativeCropHwFilter(region, target).processAllSync(frame);
+		const color = this.resolveFrameColor(frame);
+		this.logColorProvenance("hw-crop", color);
+		const outputs = this.ensureNativeCropHwFilter(region, target, color).processAllSync(frame);
 		const first = outputs[0];
 		if (!first) {
 			for (const out of outputs) out.free();
@@ -1121,17 +1283,17 @@ var DecodeWorkerChild = class {
 		return scaler;
 	}
 	/** Build-once / reuse the dedicated native-crop GPU filtergraph (rgb out). */
-	ensureNativeCropHwFilter(region, target) {
+	ensureNativeCropHwFilter(region, target, color) {
 		const nav = this.nav;
 		const scaleFilter = this.gpuScaleFilter;
 		if (!nav || !scaleFilter || !this.hwContext) throw new Error("decode-worker-child: native GPU crop requested without a HW context");
-		const key = `${region.left},${region.top},${region.width},${region.height}->${target.width}x${target.height}`;
+		const key = `${region.left},${region.top},${region.width},${region.height}->${target.width}x${target.height}:${sourceColorKey(color)}`;
 		const cached = this.nativeCropHwFilter;
 		if (cached && key === this.nativeCropHwFilterKey) return cached;
 		this.nativeCropHwFilter?.close();
 		this.nativeCropHwFilter = null;
 		this.nativeCropHwFilterKey = "";
-		const description = buildGpuFilterDescription(scaleFilter, region, target, false, "rgb24");
+		const description = buildGpuFilterDescription(scaleFilter, region, target, false, "rgb24", color);
 		const filter = nav.FilterAPI.create(description, { hardware: this.hwContext });
 		this.nativeCropHwFilter = filter;
 		this.nativeCropHwFilterKey = key;
@@ -1340,6 +1502,7 @@ var DecodeWorkerChild = class {
 		const format = opts?.format ?? this.sessionFormat;
 		const dstFmt = format === "gray" ? C.AV_PIX_FMT_GRAY8 : C.AV_PIX_FMT_RGB24;
 		const channels = format === "gray" ? 1 : 3;
+		this.logColorProvenance(isFullFrameRegion(region, frame.width, frame.height) ? "sw-fullframe" : "sw-crop", this.resolveFrameColor(frame));
 		const planes = frame.data;
 		const strides = frame.linesize;
 		const yPlane = planes?.[0];
@@ -1411,7 +1574,9 @@ var DecodeWorkerChild = class {
 			const target = resolveResizeTarget(region.width, region.height, opts?.resize);
 			const format = opts?.format ?? this.sessionFormat;
 			const channels = format === "gray" ? 1 : 3;
-			const outputs = this.ensureHwFilter(region, target, frame.width, frame.height, format).processAllSync(frame);
+			const color = this.resolveFrameColor(frame);
+			this.logColorProvenance(isFullFrameRegion(region, frame.width, frame.height) ? "hw-fullframe" : "hw-crop", color);
+			const outputs = this.ensureHwFilter(region, target, frame.width, frame.height, format, color).processAllSync(frame);
 			const first = outputs[0];
 			if (!first) throw new Error("GPU filtergraph produced no frame");
 			try {
@@ -1433,19 +1598,19 @@ var DecodeWorkerChild = class {
 	* only when the key changes; detection's ROI + resize target are stable, so
 	* this is a per-worker singleton in the steady state.
 	*/
-	ensureHwFilter(region, target, srcW, srcH, format) {
+	ensureHwFilter(region, target, srcW, srcH, format, color) {
 		const nav = this.nav;
 		const scaleFilter = this.gpuScaleFilter;
 		if (!nav || !scaleFilter || !this.hwContext) throw new Error("decode-worker-child: GPU filter requested without a HW context");
 		const fullFrame = isFullFrameRegion(region, srcW, srcH);
 		const pixel = pixelFilterName(format);
-		const key = `${region.left},${region.top},${region.width},${region.height}->${target.width}x${target.height}:${pixel}`;
+		const key = `${region.left},${region.top},${region.width},${region.height}->${target.width}x${target.height}:${pixel}:${sourceColorKey(color)}`;
 		const cached = this.hwFilter;
 		if (cached && key === this.hwFilterKey) return cached;
 		this.hwFilter?.close();
 		this.hwFilter = null;
 		this.hwFilterKey = "";
-		const description = buildGpuFilterDescription(scaleFilter, region, target, fullFrame, pixel);
+		const description = buildGpuFilterDescription(scaleFilter, region, target, fullFrame, pixel, color);
 		const filter = nav.FilterAPI.create(description, { hardware: this.hwContext });
 		this.hwFilter = filter;
 		this.hwFilterKey = key;

package/dist/{step-definitions-81eYyJbW.js → step-definitions-CAs0RD2N.js}

@@ -1,4 +1,4 @@
-const require_dist = require("./dist-D5o9fGxq.js");
+const require_dist = require("./dist-BxxVKcnw.js");
 //#region src/detection-pipeline/registry/model-catalogs.ts
 var HF_REPO = "camstack/camstack-models";
 var HF_SCRYPTED = "scrypted/plugin-models";

package/dist/{step-definitions-D6R9X0V7.mjs → step-definitions-Delhq28w.mjs}

@@ -1,4 +1,4 @@
-import { a as COCO_TO_MACRO, i as COCO_80_LABELS, r as AUDIO_MACRO_LABELS, w as hfModelUrl } from "./dist-BpWot5-w.mjs";
+import { a as COCO_TO_MACRO, i as COCO_80_LABELS, r as AUDIO_MACRO_LABELS, w as hfModelUrl } from "./dist-DkGHtAaK.mjs";
 //#region src/detection-pipeline/registry/model-catalogs.ts
 var HF_REPO = "camstack/camstack-models";
 var HF_SCRYPTED = "scrypted/plugin-models";

package/dist/stream-broker/_stub.js

@@ -2,7 +2,7 @@ import { a as e, c as t, d as n, i as r, l as i, n as a, o, r as s, s as c, t as
 import { a as d, i as f, n as p, o as m, r as h, t as g } from "./_virtual_mf___mfe_internal__addon_stream_broker_widgets__loadShare__react__loadShare__.js-C9j-2lBe.mjs";
 import { n as _, r as v, t as y } from "./_virtual_mf___mfe_internal__addon_stream_broker_widgets__loadShare__react_mf_1_jsx_mf_2_runtime__loadShare__.js-XO0-Pyu6.mjs";
 import { n as b, t as x } from "./_virtual_mf___mfe_internal__addon_stream_broker_widgets__loadShare___mf_0_tanstack_mf_1_react_mf_2_query__loadShare__.js-BO7TIbJV.mjs";
-import { t as S } from "./_virtual_mf___mfe_internal__addon_stream_broker_widgets__loadShare___mf_0_camstack_mf_1_types__loadShare__.js-CPbLcza9.mjs";
+import { t as S } from "./_virtual_mf___mfe_internal__addon_stream_broker_widgets__loadShare___mf_0_camstack_mf_1_types__loadShare__.js-D68Lj69v.mjs";
 //#region ../../node_modules/lucide-react/dist/esm/shared/src/utils.js
 var C = (e) => e.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase(), w = (e) => e.replace(/^([A-Z])|[\s-_]+(\w)/g, (e, t, n) => n ? n.toUpperCase() : t.toLowerCase()), T = (e) => {
 	let t = w(e);

package/dist/stream-broker/{_virtual_mf-localSharedImportMap___mfe_internal__addon_stream_broker_widgets-CIIIVPzB.mjs → _virtual_mf-localSharedImportMap___mfe_internal__addon_stream_broker_widgets-CfFsU700.mjs}

@@ -18,7 +18,7 @@ var e = {
 	},
 	"@camstack/types": {
 		name: "@camstack/types",
-		version: "1.1.53",
+		version: "1.1.54",
 		scope: ["default"],
 		loaded: !1,
 		from: "addon_stream_broker_widgets",