@camstack/addon-pipeline 1.1.20 → 1.1.21

package/dist/decoder-ffmpeg/index.mjs

@@ -1,8 +1,292 @@
 import { B as BaseAddon, b as decoderCapability, f as RingBuffer, s as DEFAULT_DECODER_HWACCEL_CONFIG, u as HWACCEL_OPTIONS, z as errMsg } from "../dist-tzhTTRq4.mjs";
-import { n as logBannerArgs, r as FrameDropper } from "../ffmpeg-args-common-c3p-nWtU.mjs";
+import { r as logBannerArgs, t as FrameDropper } from "../frame-dropper-CwkBTPGV.mjs";
 import { FrameRingReaderCache, FrameRingWriter, MIN_RING_SLOTS, computeSegmentSize, computeSlotByteLength, createSegment, deriveSlotCount } from "@camstack/shm-ring";
 import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
+//#region src/decoder-ffmpeg/ffmpeg-args.ts
+/**
+* Pure, side-effect-free ffmpeg argument construction for the
+* `decoder-ffmpeg` addon.
+*
+* The addon decodes video in an **ffmpeg subprocess** (unlike `decoder-nodeav`
+* which decodes in-process via node-av's native bindings). On the Intel hub,
+* node-av's VA-API decode path SIGBUSes (uncatchable) on 8MP h264 and takes the
+* whole decoder runner down; ffmpeg-as-subprocess decodes the same hardware
+* cleanly because a crash is isolated to the child process.
+*
+* These helpers are extracted from the session so the argument shape is
+* unit-testable without spawning a real ffmpeg binary.
+*
+* Validated working command on the Intel hub (renderD128, 8MP h264, ~50fps,
+* exit 0):
+*
+*   ffmpeg -hwaccel vaapi -hwaccel_device /dev/dri/renderD128 \
+*     -hwaccel_output_format vaapi -f h264 -i <in> \
+*     -vf hwdownload,format=nv12,scale=640:360,format=gray \
+*     -f rawvideo -y /dev/null
+*/
+/** Default DRM render node used for the VA-API / QSV hardware decode path. */
+var DEFAULT_VAAPI_RENDER_DEVICE = "/dev/dri/renderD128";
+/** Whether a resolved hwaccel value means "decode in software" (no `-hwaccel`). */
+function isSoftwareHwAccel(hwaccel) {
+	return hwaccel === null || hwaccel === "" || hwaccel === "none";
+}
+/** Backends whose decoded frames stay on the GPU and need an explicit
+*  `-hwaccel_output_format <m>` + `hwdownload,format=nv12` chain. */
+function needsHwDownload(hwaccel) {
+	return hwaccel === "vaapi" || hwaccel === "qsv";
+}
+/** Decode backend → its GPU scaler filter. */
+var GPU_SCALE_FILTER_BY_BACKEND = {
+	vaapi: "scale_vaapi",
+	qsv: "scale_qsv",
+	videotoolbox: "scale_vt"
+};
+/** Every GPU scaler this addon knows how to drive — used to scan `-filters`. */
+var KNOWN_GPU_SCALE_FILTERS = [
+	"scale_vaapi",
+	"scale_qsv",
+	"scale_vt"
+];
+/**
+* The GPU scaler that pairs with a decode backend, ignoring build support — a
+* static hwaccel → filter map. Returns null for software / a backend with no
+* GPU scaler (e.g. `cuda`, `drm`). Case-insensitive.
+*/
+function gpuScaleFilterForBackend(hwaccel) {
+	if (hwaccel === null) return null;
+	return GPU_SCALE_FILTER_BY_BACKEND[hwaccel.toLowerCase()] ?? null;
+}
+/**
+* Resolve the GPU scaler to use for a decode backend GIVEN the filters the
+* configured ffmpeg build actually offers ({@link parseAvailableGpuScaleFilters}).
+* Returns the filter when the backend maps to one AND the build has it; null
+* otherwise — the caller then emits the CPU-scale chain (graceful fallback).
+*/
+function resolveGpuScaleFilter(hwaccel, availableFilters) {
+	const filter = gpuScaleFilterForBackend(hwaccel);
+	if (filter === null) return null;
+	return availableFilters.has(filter) ? filter : null;
+}
+/**
+* Parse `ffmpeg -filters` stdout into the set of {@link KNOWN_GPU_SCALE_FILTERS}
+* the build offers. Matches whole filter tokens (word-boundary) so the plain
+* `scale` filter is never mistaken for a GPU scaler. PURE — the spawn lives in
+* the addon; only the parse is here so it is unit-tested.
+*/
+function parseAvailableGpuScaleFilters(filtersStdout) {
+	const present = /* @__PURE__ */ new Set();
+	for (const filter of KNOWN_GPU_SCALE_FILTERS) if (new RegExp(`\\b${filter}\\b`).test(filtersStdout)) present.add(filter);
+	return present;
+}
+/**
+* Whether the decode keeps frames on the GPU — needs `-hwaccel_output_format`
+* and an `hwdownload` in the filtergraph. VA-API / QSV always do (their decoded
+* surfaces live on the GPU); another backend only when a GPU scaler will run on
+* those surfaces (e.g. `videotoolbox` + `scale_vt`).
+*/
+function keepFramesOnGpu(hwaccel, gpuScaleFilter) {
+	return needsHwDownload(hwaccel) || gpuScaleFilter !== null;
+}
+/** Map a cap codec string to the ffmpeg `-f` input demuxer/format. */
+function codecToInputFormat(codec) {
+	switch (codec.toLowerCase()) {
+		case "h265":
+		case "hevc": return "hevc";
+		default: return "h264";
+	}
+}
+/** Map the cap-level output format to a raw ffmpeg pixel format. */
+function rawPixelForFormat(outputFormat) {
+	return outputFormat === "gray" ? "gray" : "rgb24";
+}
+/** Packed bytes-per-pixel for a raw output format (rgb24 = 3, gray = 1). */
+function channelsForPixel(pixel) {
+	return pixel === "gray" ? 1 : 3;
+}
+/**
+* The maximum output width for a given `scale` divisor — matches the node-av
+* scaler's `maxW = floor(640 / scale)` rule so both decoders produce
+* comparably-sized frames for the motion / detection pipeline.
+*/
+function maxDecodeWidth(scale) {
+	return Math.max(2, Math.floor(640 / (scale > 1 ? scale : 1)));
+}
+/**
+* Compute exact output geometry from a known source resolution — the node-av
+* rule (`outWidth = min(srcW, floor(640/scale))`, `outHeight =
+* round(outWidth*srcH/srcW)`). Provided for callers that DO know the source
+* dimensions; the live broker path leaves them to ffmpeg (`-2` height).
+*/
+function computeOutputGeometry(srcWidth, srcHeight, scale) {
+	const width = Math.min(srcWidth, maxDecodeWidth(scale));
+	return {
+		width,
+		height: Math.round(width * srcHeight / srcWidth)
+	};
+}
+/** Build the `-vf` filtergraph string for the requested hwaccel + pixel format. */
+function buildVideoFilter(hwaccel, pixel, outWidth, outHeight, maxW, gpuScaleFilter) {
+	const exact = outWidth !== void 0 && outWidth > 0 && outHeight !== void 0 && outHeight > 0;
+	if (gpuScaleFilter !== null) return `${gpuScaleFilter}=${exact ? `w=${outWidth}:h=${outHeight}` : `w=min(iw\\,${maxW}):h=-2`},hwdownload,format=nv12,format=${pixel}`;
+	const scaleAndFormat = `scale=${exact ? `${outWidth}:${outHeight}` : `min(iw\\,${maxW}):-2`},format=${pixel}`;
+	return needsHwDownload(hwaccel) ? `hwdownload,format=nv12,${scaleAndFormat}` : scaleAndFormat;
+}
+/**
+* Build the full ffmpeg argv for a decode session. PURE — no spawn, no env
+* access — so the argument shape is asserted in unit tests.
+*
+* Notes:
+* - `-loglevel info -nostats`: the session parses the muxer's `Output #0`
+*   stream line from stderr to learn the exact output W×H (the broker does not
+*   pass source geometry for the shm path). `-nostats` suppresses the periodic
+*   `frame= …` counter while keeping the one-shot Output block.
+* - The input is `pipe:0` (Annex-B packets written to stdin); the output is raw
+*   video on `pipe:1`.
+*/
+function buildFfmpegDecodeArgs(config, options) {
+	const inputFormat = codecToInputFormat(config.codec);
+	const pixel = rawPixelForFormat(config.outputFormat);
+	const maxW = maxDecodeWidth(config.scale);
+	const { hwaccel } = options;
+	const gpuScaleFilter = options.gpuScaleFilter ?? null;
+	const vf = buildVideoFilter(hwaccel, pixel, options.outWidth, options.outHeight, maxW, gpuScaleFilter);
+	let hwaccelArgs;
+	if (isSoftwareHwAccel(hwaccel) || hwaccel === null) hwaccelArgs = [];
+	else {
+		hwaccelArgs = ["-hwaccel", hwaccel];
+		if (needsHwDownload(hwaccel)) hwaccelArgs.push("-hwaccel_device", options.renderDevice ?? "/dev/dri/renderD128");
+		if (keepFramesOnGpu(hwaccel, gpuScaleFilter)) hwaccelArgs.push("-hwaccel_output_format", hwaccel);
+	}
+	return [
+		...logBannerArgs("info"),
+		"-nostats",
+		"-fflags",
+		"+nobuffer+flush_packets",
+		"-flags",
+		"low_delay",
+		"-probesize",
+		"1M",
+		"-analyzeduration",
+		"0",
+		...hwaccelArgs,
+		"-f",
+		inputFormat,
+		"-i",
+		"pipe:0",
+		"-vf",
+		vf,
+		"-f",
+		"rawvideo",
+		"-pix_fmt",
+		pixel,
+		"pipe:1"
+	];
+}
+/**
+* Parse the exact output geometry from ffmpeg's stderr. The muxer prints an
+* `Output #0, rawvideo …` block whose `Stream #0:0: Video: rawvideo …, <fmt>,
+* WIDTHxHEIGHT …` line carries the scaled dimensions. Gating on the `Output #`
+* marker avoids picking up the INPUT stream's (source) resolution, which is
+* printed earlier.
+*
+* Returns `null` until the Output block with a `WxH` token has been seen.
+*/
+function parseFfmpegOutputDims(stderr) {
+	const outputIdx = stderr.indexOf("Output #");
+	if (outputIdx < 0) return null;
+	const match = stderr.slice(outputIdx).match(/(\d{2,5})x(\d{2,5})/);
+	if (!match) return null;
+	const width = Number(match[1]);
+	const height = Number(match[2]);
+	if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) return null;
+	return {
+		width,
+		height
+	};
+}
+/**
+* Pick the first kernel-preferred `-hwaccel` method the configured ffmpeg build
+* actually supports, or `null` (software) when it supports none. Mirrors the
+* broker's `pickDecodeHwAccel` (`ffmpeg-invocation.ts`) so the decoder gates
+* decode-hwaccel against the same probed evidence:
+* - empty `preferred` → `null` (software);
+* - empty `supportedMethods` (probe miss) → keep the top preference and let the
+*   session's per-child software fallback cover a genuine failure;
+* - otherwise the first preference the build supports, or `null`.
+*/
+function pickDecodeHwAccel(preferred, supportedMethods) {
+	if (preferred.length === 0) return null;
+	if (supportedMethods.length === 0) return preferred[0] ?? null;
+	const supported = new Set(supportedMethods.map((m) => m.toLowerCase()));
+	return preferred.find((name) => supported.has(name.toLowerCase())) ?? null;
+}
+/**
+* Canonical decode-hwaccel preference order for the ffmpeg-subprocess decoder.
+*
+* `vaapi` is ranked ABOVE `qsv` deliberately: on the Intel hub the `qsv` decode
+* child exits early (`code=171`, no frames) while the `vaapi` path decodes 8MP
+* h264 cleanly at ~50fps. The kernel probe (`resolveHwAccel`) tends to surface
+* `qsv` first on Intel, so we re-rank its result through this table before
+* building the attempt chain. `videotoolbox` leads for macOS; `cuda` / `nvdec`
+* trail for NVIDIA. A method not listed here keeps its incoming relative order,
+* placed AFTER every ranked one.
+*/
+var DECODE_HWACCEL_RANK = [
+	"videotoolbox",
+	"vaapi",
+	"qsv",
+	"cuda",
+	"nvdec",
+	"d3d11va",
+	"dxva2",
+	"amf",
+	"vdpau",
+	"drm"
+];
+/** Rank index for {@link DECODE_HWACCEL_RANK} — unranked methods sort last. */
+function decodeHwAccelRankIndex(method) {
+	const idx = DECODE_HWACCEL_RANK.indexOf(method.toLowerCase());
+	return idx < 0 ? DECODE_HWACCEL_RANK.length : idx;
+}
+/**
+* Build the ORDERED list of hardware `-hwaccel` methods to attempt for an
+* `'auto'` decode session, best-first. The session walks this chain on an
+* early-exit-with-no-frames and only falls to software once it is exhausted.
+*
+* Strategy:
+* - Seed candidates from the kernel-preferred order UNION the canonical rank
+*   UNION the build's supported list, so a method the kernel omitted but the
+*   build supports (the Intel `vaapi` case — kernel surfaces only `qsv`) is
+*   still attempted.
+* - When the build's supported-method list is known (non-empty), keep only
+*   methods it actually offers; on a probe miss (empty) keep just the kernel
+*   preferences (avoid blindly spawning every backend).
+* - Re-rank the survivors by {@link DECODE_HWACCEL_RANK} so `vaapi` precedes
+*   `qsv`. A supported method not in the rank table keeps its position AFTER
+*   every ranked one (stable sort). Returns lowercased method names; empty ⇒
+*   pure software.
+*/
+function rankDecodeHwAccels(preferred, supportedMethods) {
+	const supported = new Set(supportedMethods.map((m) => m.toLowerCase()));
+	const hasSupportList = supported.size > 0;
+	const pool = hasSupportList ? [
+		...preferred,
+		...DECODE_HWACCEL_RANK,
+		...supportedMethods
+	] : [...preferred];
+	const seen = /* @__PURE__ */ new Set();
+	const candidates = [];
+	for (const raw of pool) {
+		const method = raw.toLowerCase();
+		if (seen.has(method)) continue;
+		seen.add(method);
+		if (hasSupportList && !supported.has(method)) continue;
+		candidates.push(method);
+	}
+	return candidates.sort((a, b) => decodeHwAccelRankIndex(a) - decodeHwAccelRankIndex(b));
+}
+//#endregion
 //#region src/decoder-ffmpeg/frame-ring-sink.ts
 /**
 * `DecoderFrameRingSink` — the decoder's shared-memory write side (Phase 5 / D9).
@@ -267,238 +551,55 @@ var DecoderFrameRingSink = class {
 	}
 };
 //#endregion
-//#region src/decoder-ffmpeg/ffmpeg-args.ts
-/**
-* Pure, side-effect-free ffmpeg argument construction for the
-* `decoder-ffmpeg` addon.
-*
-* The addon decodes video in an **ffmpeg subprocess** (unlike `decoder-nodeav`
-* which decodes in-process via node-av's native bindings). On the Intel hub,
-* node-av's VA-API decode path SIGBUSes (uncatchable) on 8MP h264 and takes the
-* whole decoder runner down; ffmpeg-as-subprocess decodes the same hardware
-* cleanly because a crash is isolated to the child process.
-*
-* These helpers are extracted from the session so the argument shape is
-* unit-testable without spawning a real ffmpeg binary.
-*
-* Validated working command on the Intel hub (renderD128, 8MP h264, ~50fps,
-* exit 0):
-*
-*   ffmpeg -hwaccel vaapi -hwaccel_device /dev/dri/renderD128 \
-*     -hwaccel_output_format vaapi -f h264 -i <in> \
-*     -vf hwdownload,format=nv12,scale=640:360,format=gray \
-*     -f rawvideo -y /dev/null
-*/
-/** Default DRM render node used for the VA-API / QSV hardware decode path. */
-var DEFAULT_VAAPI_RENDER_DEVICE = "/dev/dri/renderD128";
-/** Whether a resolved hwaccel value means "decode in software" (no `-hwaccel`). */
-function isSoftwareHwAccel(hwaccel) {
-	return hwaccel === null || hwaccel === "" || hwaccel === "none";
-}
-/** Backends whose decoded frames stay on the GPU and need an explicit
-*  `-hwaccel_output_format <m>` + `hwdownload,format=nv12` chain. */
-function needsHwDownload(hwaccel) {
-	return hwaccel === "vaapi" || hwaccel === "qsv";
-}
-/** Map a cap codec string to the ffmpeg `-f` input demuxer/format. */
-function codecToInputFormat(codec) {
-	switch (codec.toLowerCase()) {
-		case "h265":
-		case "hevc": return "hevc";
-		default: return "h264";
+//#region src/decoder-ffmpeg/frame-stream-splitter.ts
+var FrameStreamSplitter = class {
+	frameSize;
+	ctl;
+	/** Whether a frame is currently being filled (partially received). */
+	open = false;
+	/** The current frame's fill target, or `null` when the open frame is dropped. */
+	target = null;
+	/** Bytes already written into the current frame. */
+	filled = 0;
+	constructor(frameSize, ctl) {
+		if (!Number.isInteger(frameSize) || frameSize <= 0) throw new Error(`FrameStreamSplitter: frameSize must be a positive integer, got ${frameSize}`);
+		this.frameSize = frameSize;
+		this.ctl = ctl;
 	}
-}
-/** Map the cap-level output format to a raw ffmpeg pixel format. */
-function rawPixelForFormat(outputFormat) {
-	return outputFormat === "gray" ? "gray" : "rgb24";
-}
-/** Packed bytes-per-pixel for a raw output format (rgb24 = 3, gray = 1). */
-function channelsForPixel(pixel) {
-	return pixel === "gray" ? 1 : 3;
-}
-/**
-* The maximum output width for a given `scale` divisor — matches the node-av
-* scaler's `maxW = floor(640 / scale)` rule so both decoders produce
-* comparably-sized frames for the motion / detection pipeline.
-*/
-function maxDecodeWidth(scale) {
-	return Math.max(2, Math.floor(640 / (scale > 1 ? scale : 1)));
-}
-/**
-* Compute exact output geometry from a known source resolution — the node-av
-* rule (`outWidth = min(srcW, floor(640/scale))`, `outHeight =
-* round(outWidth*srcH/srcW)`). Provided for callers that DO know the source
-* dimensions; the live broker path leaves them to ffmpeg (`-2` height).
-*/
-function computeOutputGeometry(srcWidth, srcHeight, scale) {
-	const width = Math.min(srcWidth, maxDecodeWidth(scale));
-	return {
-		width,
-		height: Math.round(width * srcHeight / srcWidth)
-	};
-}
-/** Build the `-vf` filtergraph string for the requested hwaccel + pixel format. */
-function buildVideoFilter(hwaccel, pixel, outWidth, outHeight, maxW) {
-	const scaleAndFormat = `scale=${outWidth !== void 0 && outWidth > 0 && outHeight !== void 0 && outHeight > 0 ? `${outWidth}:${outHeight}` : `min(iw\\,${maxW}):-2`},format=${pixel}`;
-	return needsHwDownload(hwaccel) ? `hwdownload,format=nv12,${scaleAndFormat}` : scaleAndFormat;
-}
-/**
-* Build the full ffmpeg argv for a decode session. PURE — no spawn, no env
-* access — so the argument shape is asserted in unit tests.
-*
-* Notes:
-* - `-loglevel info -nostats`: the session parses the muxer's `Output #0`
-*   stream line from stderr to learn the exact output W×H (the broker does not
-*   pass source geometry for the shm path). `-nostats` suppresses the periodic
-*   `frame= …` counter while keeping the one-shot Output block.
-* - The input is `pipe:0` (Annex-B packets written to stdin); the output is raw
-*   video on `pipe:1`.
-*/
-function buildFfmpegDecodeArgs(config, options) {
-	const inputFormat = codecToInputFormat(config.codec);
-	const pixel = rawPixelForFormat(config.outputFormat);
-	const maxW = maxDecodeWidth(config.scale);
-	const vf = buildVideoFilter(options.hwaccel, pixel, options.outWidth, options.outHeight, maxW);
-	const { hwaccel } = options;
-	let hwaccelArgs;
-	if (isSoftwareHwAccel(hwaccel) || hwaccel === null) hwaccelArgs = [];
-	else if (needsHwDownload(hwaccel)) hwaccelArgs = [
-		"-hwaccel",
-		hwaccel,
-		"-hwaccel_device",
-		options.renderDevice ?? "/dev/dri/renderD128",
-		"-hwaccel_output_format",
-		hwaccel
-	];
-	else hwaccelArgs = ["-hwaccel", hwaccel];
-	return [
-		...logBannerArgs("info"),
-		"-nostats",
-		"-fflags",
-		"+nobuffer+flush_packets",
-		"-flags",
-		"low_delay",
-		"-probesize",
-		"1M",
-		"-analyzeduration",
-		"0",
-		...hwaccelArgs,
-		"-f",
-		inputFormat,
-		"-i",
-		"pipe:0",
-		"-vf",
-		vf,
-		"-f",
-		"rawvideo",
-		"-pix_fmt",
-		pixel,
-		"pipe:1"
-	];
-}
-/**
-* Parse the exact output geometry from ffmpeg's stderr. The muxer prints an
-* `Output #0, rawvideo …` block whose `Stream #0:0: Video: rawvideo …, <fmt>,
-* WIDTHxHEIGHT …` line carries the scaled dimensions. Gating on the `Output #`
-* marker avoids picking up the INPUT stream's (source) resolution, which is
-* printed earlier.
-*
-* Returns `null` until the Output block with a `WxH` token has been seen.
-*/
-function parseFfmpegOutputDims(stderr) {
-	const outputIdx = stderr.indexOf("Output #");
-	if (outputIdx < 0) return null;
-	const match = stderr.slice(outputIdx).match(/(\d{2,5})x(\d{2,5})/);
-	if (!match) return null;
-	const width = Number(match[1]);
-	const height = Number(match[2]);
-	if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) return null;
-	return {
-		width,
-		height
-	};
-}
-/**
-* Pick the first kernel-preferred `-hwaccel` method the configured ffmpeg build
-* actually supports, or `null` (software) when it supports none. Mirrors the
-* broker's `pickDecodeHwAccel` (`ffmpeg-invocation.ts`) so the decoder gates
-* decode-hwaccel against the same probed evidence:
-* - empty `preferred` → `null` (software);
-* - empty `supportedMethods` (probe miss) → keep the top preference and let the
-*   session's per-child software fallback cover a genuine failure;
-* - otherwise the first preference the build supports, or `null`.
-*/
-function pickDecodeHwAccel(preferred, supportedMethods) {
-	if (preferred.length === 0) return null;
-	if (supportedMethods.length === 0) return preferred[0] ?? null;
-	const supported = new Set(supportedMethods.map((m) => m.toLowerCase()));
-	return preferred.find((name) => supported.has(name.toLowerCase())) ?? null;
-}
-/**
-* Canonical decode-hwaccel preference order for the ffmpeg-subprocess decoder.
-*
-* `vaapi` is ranked ABOVE `qsv` deliberately: on the Intel hub the `qsv` decode
-* child exits early (`code=171`, no frames) while the `vaapi` path decodes 8MP
-* h264 cleanly at ~50fps. The kernel probe (`resolveHwAccel`) tends to surface
-* `qsv` first on Intel, so we re-rank its result through this table before
-* building the attempt chain. `videotoolbox` leads for macOS; `cuda` / `nvdec`
-* trail for NVIDIA. A method not listed here keeps its incoming relative order,
-* placed AFTER every ranked one.
-*/
-var DECODE_HWACCEL_RANK = [
-	"videotoolbox",
-	"vaapi",
-	"qsv",
-	"cuda",
-	"nvdec",
-	"d3d11va",
-	"dxva2",
-	"amf",
-	"vdpau",
-	"drm"
-];
-/** Rank index for {@link DECODE_HWACCEL_RANK} — unranked methods sort last. */
-function decodeHwAccelRankIndex(method) {
-	const idx = DECODE_HWACCEL_RANK.indexOf(method.toLowerCase());
-	return idx < 0 ? DECODE_HWACCEL_RANK.length : idx;
-}
-/**
-* Build the ORDERED list of hardware `-hwaccel` methods to attempt for an
-* `'auto'` decode session, best-first. The session walks this chain on an
-* early-exit-with-no-frames and only falls to software once it is exhausted.
-*
-* Strategy:
-* - Seed candidates from the kernel-preferred order UNION the canonical rank
-*   UNION the build's supported list, so a method the kernel omitted but the
-*   build supports (the Intel `vaapi` case — kernel surfaces only `qsv`) is
-*   still attempted.
-* - When the build's supported-method list is known (non-empty), keep only
-*   methods it actually offers; on a probe miss (empty) keep just the kernel
-*   preferences (avoid blindly spawning every backend).
-* - Re-rank the survivors by {@link DECODE_HWACCEL_RANK} so `vaapi` precedes
-*   `qsv`. A supported method not in the rank table keeps its position AFTER
-*   every ranked one (stable sort). Returns lowercased method names; empty ⇒
-*   pure software.
-*/
-function rankDecodeHwAccels(preferred, supportedMethods) {
-	const supported = new Set(supportedMethods.map((m) => m.toLowerCase()));
-	const hasSupportList = supported.size > 0;
-	const pool = hasSupportList ? [
-		...preferred,
-		...DECODE_HWACCEL_RANK,
-		...supportedMethods
-	] : [...preferred];
-	const seen = /* @__PURE__ */ new Set();
-	const candidates = [];
-	for (const raw of pool) {
-		const method = raw.toLowerCase();
-		if (seen.has(method)) continue;
-		seen.add(method);
-		if (hasSupportList && !supported.has(method)) continue;
-		candidates.push(method);
+	/** True while a frame has been started (a live slot may be open) but not yet
+	*  completed — the session aborts an open slot on teardown. */
+	get hasOpenFrame() {
+		return this.open && this.target !== null;
 	}
-	return candidates.sort((a, b) => decodeHwAccelRankIndex(a) - decodeHwAccelRankIndex(b));
-}
+	/**
+	* Consume a stdout chunk, emitting every frame boundary it completes. A chunk
+	* may finish the open frame, contain several whole frames, and/or leave a
+	* partial frame buffered for the next chunk.
+	*/
+	push(chunk) {
+		const n = chunk.length;
+		let off = 0;
+		while (off < n) {
+			if (!this.open) {
+				this.target = this.ctl.startFrame();
+				this.open = true;
+				this.filled = 0;
+			}
+			const take = Math.min(this.frameSize - this.filled, n - off);
+			if (this.target !== null) chunk.copy(this.target, this.filled, off, off + take);
+			this.filled += take;
+			off += take;
+			if (this.filled === this.frameSize) {
+				const finished = this.target;
+				this.open = false;
+				this.target = null;
+				this.filled = 0;
+				if (finished !== null) this.ctl.finishFrame(finished);
+				else this.ctl.dropFrame();
+			}
+		}
+	}
+};
 //#endregion
 //#region src/decoder-ffmpeg/ffmpeg-decoder-session.ts
 /**
@@ -514,10 +615,14 @@ function rankDecodeHwAccels(preferred, supportedMethods) {
 *
 * Data flow per session:
 *   Annex-B packets → ffmpeg stdin (pipe:0)
-*   ffmpeg  → `-vf [hwdownload,format=nv12,]scale=…,format=<rgb24|gray>`
-*   raw video → ffmpeg stdout (pipe:1) → fixed-size frame slices
-*   each slice → `DecoderFrameRingSink.writeFrame` → `FrameHandle` (shm mode)
-*                 or `DecodedFrame` via `onFrame` (callback mode)
+*   ffmpeg  → `-vf <scale_vaapi=…,hwdownload,… | hwdownload,…,scale=…>` (GPU or
+*             CPU scale, per {@link buildFfmpegDecodeArgs})
+*   raw video → ffmpeg stdout (pipe:1) → a {@link FrameStreamSplitter} that fills
+*             each frame's bytes DIRECTLY into its shm ring slot (zero-copy
+*             `beginFrame`/`commitFrame`) → `FrameHandle` (shm mode), or into a
+*             per-frame buffer → `DecodedFrame` via `onFrame` (callback mode).
+*             No `Buffer.concat` accumulator, one copy per byte, none for dropped
+*             frames.
 *
 * Output geometry: the broker does not pass source width/height for the shm
 * path, so ffmpeg picks the height (`scale=min(iw\,maxW):-2`) and the session
@@ -556,9 +661,31 @@ var FfmpegDecoderSession = class {
 	hwaccelChain;
 	hwaccelIndex = 0;
 	hwaccel;
+	/** GPU scalers the build offers; drives whether decode scales on the GPU. */
+	availableGpuScaleFilters;
+	onGpuScaleUnsupported;
+	/**
+	* Whether the CURRENT backend attempt may use its GPU scaler. Starts true for
+	* each backend; a GPU-scale child that dies immediately with no frames flips
+	* it false and the SAME backend is retried on the CPU-scale chain (so a broken
+	* GPU scaler degrades to hw-decode + CPU-scale, never to software decode).
+	*/
+	gpuScaleEnabled = true;
+	/** The GPU scaler the live child was spawned with, or null (CPU scale). */
+	activeGpuScaleFilter = null;
 	process = null;
 	spawnedAtMs = 0;
-	outputBuffer = Buffer.alloc(0);
+	/**
+	* Splits ffmpeg's raw stdout byte stream into frames, filling each DIRECTLY
+	* into its shm slot (zero-copy) — created once the output geometry is known.
+	*/
+	splitter = null;
+	/** Stdout chunks received BEFORE geometry is known — replayed into the
+	*  splitter once `frameSize` is learned. A short-lived list (no concat). */
+	pendingStdout = [];
+	/** The shm ring slot the splitter is currently filling, if any — aborted on
+	*  respawn / teardown so a half-filled slot never publishes. */
+	openSlot = null;
 	stderrAccum = "";
 	destroyed = false;
 	pixel;
@@ -589,6 +716,8 @@ var FfmpegDecoderSession = class {
 		const seededChain = options?.hwaccelChain ?? (options?.hwaccel != null && !isSoftwareHwAccel(options.hwaccel) ? [options.hwaccel] : []);
 		this.hwaccelChain = seededChain.filter((m) => !isSoftwareHwAccel(m));
 		this.hwaccel = this.currentHwAccel();
+		this.availableGpuScaleFilters = options?.availableGpuScaleFilters ?? /* @__PURE__ */ new Set();
+		this.onGpuScaleUnsupported = options?.onGpuScaleUnsupported;
 		this.pixel = rawPixelForFormat(config.outputFormat);
 		this.channels = channelsForPixel(this.pixel);
 		this.frameFormat = this.pixel === "gray" ? "gray" : "rgb";
@@ -619,18 +748,22 @@ var FfmpegDecoderSession = class {
 	spawnFfmpeg() {
 		if (this.destroyed) return;
 		this.killFfmpeg();
-		this.outputBuffer = Buffer.alloc(0);
+		this.abortOpenSlot();
+		this.splitter = null;
+		this.pendingStdout = [];
 		this.stderrAccum = "";
 		this.outWidth = 0;
 		this.outHeight = 0;
 		this.frameSize = 0;
+		this.activeGpuScaleFilter = this.gpuScaleEnabled ? resolveGpuScaleFilter(this.hwaccel, this.availableGpuScaleFilters) : null;
 		const args = buildFfmpegDecodeArgs({
 			codec: this.config.codec,
 			scale: this.config.scale,
 			outputFormat: this.config.outputFormat
 		}, {
 			hwaccel: this.hwaccel,
-			renderDevice: this.renderDevice
+			renderDevice: this.renderDevice,
+			gpuScaleFilter: this.activeGpuScaleFilter
 		});
 		let child;
 		try {
@@ -650,6 +783,7 @@ var FfmpegDecoderSession = class {
 		child.on("exit", (code, signal) => this.handleExit(code, signal));
 		this.logger.info("ffmpeg decoder: spawned", { meta: {
 			hwaccel: this.hwaccel,
+			gpuScale: this.activeGpuScaleFilter ?? "cpu",
 			codec: this.config.codec,
 			format: this.frameFormat,
 			sink: this.frameSink
@@ -681,9 +815,24 @@ var FfmpegDecoderSession = class {
 		if (this.destroyed) return;
 		const diedFast = Date.now() - this.spawnedAtMs < HWACCEL_FALLBACK_WINDOW_MS;
 		if (!isSoftwareHwAccel(this.hwaccel) && this.outputFrames === 0 && diedFast) {
+			if (this.activeGpuScaleFilter !== null) {
+				const brokenFilter = this.activeGpuScaleFilter;
+				this.gpuScaleEnabled = false;
+				this.onGpuScaleUnsupported?.(brokenFilter);
+				this.logger.warn("ffmpeg decoder: GPU-scale child exited early with no frames — retrying same backend with CPU scale", { meta: {
+					hwaccel: this.hwaccel,
+					gpuScaleFilter: brokenFilter,
+					code,
+					signal
+				} });
+				this.process = null;
+				this.spawnFfmpeg();
+				return;
+			}
 			const failed = this.hwaccel;
 			this.hwaccelIndex += 1;
 			this.hwaccel = this.currentHwAccel();
+			this.gpuScaleEnabled = true;
 			const next = isSoftwareHwAccel(this.hwaccel) ? "software" : this.hwaccel;
 			this.logger.warn("ffmpeg decoder: hwaccel child exited early with no frames — trying next decode path", { meta: {
 				failed,
@@ -729,58 +878,79 @@ var FfmpegDecoderSession = class {
 			channels: this.channels,
 			frameSize: this.frameSize
 		} });
-		this.drainFrames();
+		this.splitter = new FrameStreamSplitter(this.frameSize, this.makeSlotController());
+		const pending = this.pendingStdout;
+		this.pendingStdout = [];
+		for (const chunk of pending) this.splitter.push(chunk);
 	}
 	handleStdout(chunk) {
-		this.outputBuffer = this.outputBuffer.length === 0 ? chunk : Buffer.concat([this.outputBuffer, chunk]);
-		if (this.frameSize === 0) return;
-		this.drainFrames();
-	}
-	drainFrames() {
-		const size = this.frameSize;
-		if (size === 0) return;
-		let offset = 0;
-		while (this.outputBuffer.length - offset >= size) {
-			const slice = this.outputBuffer.subarray(offset, offset + size);
-			offset += size;
-			this.emitFrame(slice);
-		}
-		if (offset > 0) this.outputBuffer = Buffer.from(this.outputBuffer.subarray(offset));
-	}
-	emitFrame(slice) {
-		if (!this.frameDropper.shouldKeep()) {
-			this.droppedFrames++;
+		if (this.splitter === null) {
+			this.pendingStdout.push(chunk);
 			return;
 		}
-		const pixels = Buffer.from(slice);
-		this.outputFrames++;
-		if (this.frameSink === "shm") {
-			const handle = this.ensureFrameRingSink().writeFrame(pixels, {
-				width: this.outWidth,
-				height: this.outHeight,
-				format: this.frameFormat,
-				pts: performance.now(),
-				byteLength: pixels.byteLength
-			});
-			if (handle === null) {
+		this.splitter.push(chunk);
+	}
+	/**
+	* The frame lifecycle the {@link FrameStreamSplitter} drives. `startFrame`
+	* reserves a shm slot (zero-copy: the splitter fills the slot view in place)
+	* or, for the callback sink, allocates one frame buffer; `finishFrame`
+	* publishes the filled frame; `dropFrame` accounts an FPS-skipped one.
+	*/
+	makeSlotController() {
+		return {
+			startFrame: () => {
+				if (!this.frameDropper.shouldKeep()) return null;
+				if (this.frameSink === "shm") {
+					const reserved = this.ensureFrameRingSink().beginFrame(this.outWidth, this.outHeight, this.frameFormat);
+					if (reserved === null) return null;
+					this.openSlot = reserved.slot;
+					return reserved.buffer;
+				}
+				return Buffer.allocUnsafe(this.frameSize);
+			},
+			finishFrame: (target) => {
+				this.outputFrames++;
+				if (this.frameSink === "shm") {
+					const slot = this.openSlot;
+					this.openSlot = null;
+					const sink = this.frameRingSink;
+					if (slot === null || sink === null) return;
+					const handle = sink.commitFrame(slot, {
+						width: this.outWidth,
+						height: this.outHeight,
+						format: this.frameFormat,
+						pts: performance.now(),
+						byteLength: this.frameSize
+					});
+					if (handle === null) return;
+					const delivered = {
+						handle,
+						timestamp: Date.now()
+					};
+					for (const cb of this.handleCallbacks) cb(delivered);
+					return;
+				}
+				const frame = {
+					data: target,
+					width: this.outWidth,
+					height: this.outHeight,
+					format: this.frameFormat,
+					timestamp: Date.now()
+				};
+				for (const cb of this.frameCallbacks) cb(frame);
+			},
+			dropFrame: () => {
 				this.droppedFrames++;
-				return;
 			}
-			const delivered = {
-				handle,
-				timestamp: Date.now()
-			};
-			for (const cb of this.handleCallbacks) cb(delivered);
-			return;
-		}
-		const frame = {
-			data: pixels,
-			width: this.outWidth,
-			height: this.outHeight,
-			format: this.frameFormat,
-			timestamp: Date.now()
 		};
-		for (const cb of this.frameCallbacks) cb(frame);
+	}
+	/** Abandon a shm slot the splitter left open (respawn / teardown mid-frame),
+	*  so a half-filled slot is never published. */
+	abortOpenSlot() {
+		const slot = this.openSlot;
+		if (slot === null) return;
+		this.openSlot = null;
+		this.frameRingSink?.abortFrame(slot);
 	}
 	pushPacket(packet) {
 		if (this.destroyed) return;
@@ -817,6 +987,8 @@ var FfmpegDecoderSession = class {
 		if (this.destroyed) return;
 		this.destroyed = true;
 		this.killFfmpeg();
+		this.abortOpenSlot();
+		this.splitter = null;
 		this.frameRingSink?.destroy();
 		this.frameRingSink = null;
 		this.frameCallbacks.clear();
@@ -833,6 +1005,64 @@ var FfmpegDecoderSession = class {
 	}
 };
 //#endregion
+//#region src/decoder-ffmpeg/ffmpeg-filter-probe.ts
+/**
+* One-shot probe of the GPU scale filters an ffmpeg build offers.
+*
+* The decoder runs the downscale on the GPU (`scale_vaapi` / `scale_qsv` /
+* `scale_vt`) instead of downloading the full-resolution frame and scaling it on
+* the CPU — a large saving on VA-API. Whether a given build even compiled those
+* filters in is build-specific, so the addon probes `ffmpeg -filters` ONCE at
+* init and passes the result into every session. The parse
+* ({@link parseAvailableGpuScaleFilters}) is a pure function unit-tested in
+* `ffmpeg-args.spec.ts`; only the spawn lives here.
+*/
+/** How long to wait for `ffmpeg -filters` before giving up (→ empty set). */
+var PROBE_TIMEOUT_MS = 5e3;
+/**
+* Run `<ffmpegPath> -hide_banner -filters` and return the {@link GpuScaleFilter}s
+* the build lists. Never throws — a missing / slow / failing binary resolves to
+* an empty set, which makes every session fall back to the CPU-scale chain.
+*/
+function probeGpuScaleFilters(ffmpegPath, logger) {
+	return new Promise((resolve) => {
+		let stdout = "";
+		let settled = false;
+		const done = (set) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve(set);
+		};
+		let child;
+		try {
+			child = spawn(ffmpegPath, ["-hide_banner", "-filters"]);
+		} catch (err) {
+			logger.warn("decoder-ffmpeg: GPU-scale filter probe spawn failed — CPU scale", { meta: { error: errMsg(err) } });
+			done(/* @__PURE__ */ new Set());
+			return;
+		}
+		const timer = setTimeout(() => {
+			try {
+				child.kill("SIGKILL");
+			} catch {}
+			logger.warn("decoder-ffmpeg: GPU-scale filter probe timed out — CPU scale");
+			done(/* @__PURE__ */ new Set());
+		}, PROBE_TIMEOUT_MS);
+		timer.unref?.();
+		child.stdout?.on("data", (chunk) => {
+			stdout += chunk.toString();
+		});
+		child.on("error", (err) => {
+			logger.warn("decoder-ffmpeg: GPU-scale filter probe errored — CPU scale", { meta: { error: err.message } });
+			done(/* @__PURE__ */ new Set());
+		});
+		child.on("exit", () => {
+			done(parseAvailableGpuScaleFilters(stdout));
+		});
+	});
+}
+//#endregion
 //#region src/decoder-ffmpeg/addon/index.ts
 var FRAME_BUFFER_CAPACITY = 32;
 var DecoderFfmpegAddon = class extends BaseAddon {
@@ -851,6 +1081,19 @@ var DecoderFfmpegAddon = class extends BaseAddon {
 	* decode-accel probe reports for the right build.
 	*/
 	ffmpegPath = "ffmpeg";
+	/**
+	* GPU scale filters the resolved ffmpeg build offers (`scale_vaapi` /
+	* `scale_qsv` / `scale_vt`), probed once at init. A session running one of
+	* these downscales on the GPU instead of the CPU (a large VA-API saving).
+	*/
+	probedGpuScaleFilters = /* @__PURE__ */ new Set();
+	/**
+	* GPU scalers the build LISTS but that proved non-functional at runtime (a
+	* session's GPU-scale child died with no frames and self-healed to CPU scale).
+	* Excluded from later sessions so the failed spawn happens at most once per
+	* process — e.g. a videotoolbox build whose decode returns software frames.
+	*/
+	unsupportedGpuScaleFilters = /* @__PURE__ */ new Set();
 	constructor() {
 		super(DEFAULT_DECODER_HWACCEL_CONFIG);
 	}
@@ -886,6 +1129,11 @@ var DecoderFfmpegAddon = class extends BaseAddon {
 		this.ctx.logger.info("ffmpeg decoder addon initialized");
 		this.frameReaders = new FrameRingReaderCache(this.ctx.logger);
 		this.ffmpegPath = await this.resolveFfmpegBinaryPath();
+		this.probedGpuScaleFilters = await probeGpuScaleFilters(this.ffmpegPath, this.ctx.logger);
+		this.ctx.logger.info("decoder-ffmpeg: probed GPU scale filters", { meta: {
+			filters: [...this.probedGpuScaleFilters],
+			ffmpeg: this.ffmpegPath
+		} });
 		if (!this.config.probedBestHwaccel) this.reprobeHwaccel().catch((err) => {
 			this.ctx.logger.warn("ffmpeg: auto-reprobe hwaccel failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
 		});
@@ -1001,11 +1249,18 @@ var DecoderFfmpegAddon = class extends BaseAddon {
 		const { frameSink } = config;
 		const nodeId = this.resolveLocalNodeId();
 		const hwaccelChain = await this.resolveDecodeHwaccelChain();
+		const availableGpuScaleFilters = new Set([...this.probedGpuScaleFilters].filter((f) => !this.unsupportedGpuScaleFilters.has(f)));
 		const session = new FfmpegDecoderSession(config, this.ctx.logger, {
 			hwaccelChain,
 			ffmpegPath: this.ffmpegPath,
 			frameSink,
-			nodeId
+			nodeId,
+			availableGpuScaleFilters,
+			onGpuScaleUnsupported: (filter) => {
+				if (this.unsupportedGpuScaleFilters.has(filter)) return;
+				this.unsupportedGpuScaleFilters.add(filter);
+				this.ctx.logger.warn("decoder-ffmpeg: GPU scaler non-functional on this build — future sessions use CPU scale", { meta: { filter } });
+			}
 		});
 		const unsub = frameSink === "shm" ? this.wireShmSink(sessionId, session) : this.wireCallbackSink(sessionId, session);
 		this.sessions.set(sessionId, session);