@camstack/shm-ring 1.0.12 → 1.0.13

package/dist/testing/index.d.ts

@@ -2,8 +2,8 @@
  * `@camstack/shm-ring/testing` — test-only utilities for the Phase 5 (D9)
  * shared-memory frame plane.
  *
- * Kept on a separate entry from the package's runtime surface so importing
- * these helpers does not pull `node-av` into a production consumer.
+ * Kept on a separate entry from the package's runtime surface. The frame source
+ * is synthetic (no `node-av`), so these helpers pull no native decoder.
  */
-export { createLoopingClipFrameSource, MissingClipError, } from './looping-clip-frame-source.js';
-export type { LoopingClipFrameSource, LoopingClipFrameSourceOptions, ClipFrame, ClipCodec, EmittedFrameFormat, OnFrame, } from './looping-clip-frame-source.js';
+export { createLoopingClipFrameSource } from './looping-clip-frame-source.js';
+export type { LoopingClipFrameSource, LoopingClipFrameSourceOptions, ClipFrame, EmittedFrameFormat, OnFrame, } from './looping-clip-frame-source.js';

package/dist/testing/index.js

@@ -1,98 +1,71 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-let node_fs = require("node:fs");
 //#region src/testing/looping-clip-frame-source.ts
-/**
-* `LoopingClipFrameSource` — a real-video decoded-frame source for Phase 5 (D9)
-* shm-frame-plane tests.
-*
-* A metadata-only synthetic camera has no decodable video. The intensive shm
-* tests (perf comparison, frame-integrity,
-* soak) need a stream of *genuine* decoded pixels at a controlled fps. This
-* utility decodes a real `.h264` / `.hevc` clip via `node-av` and emits decoded
-* frames to a callback at a target rate, looping back to the clip start at EOF.
-*
-* The decoder wiring is ported from `scripts/bench-nodeav.mts` (the working
-* decode-from-file path) — software decode, no hardware accel, kept
-* dependency-light. Decoded frames are scaled to a known packed pixel format
-* (`rgb` / `bgr` / `gray`) so every emitted buffer has a deterministic
-* `width × height × bpp` byte length the tests can assert on.
-*
-* The clips live under `test-output/bench/` which is gitignored — they are NOT
-* committed. `createLoopingClipFrameSource` therefore validates the clip path
-* up front and surfaces a missing clip as a typed `MissingClipError`, so a
-* test can skip-with-a-clear-message rather than fail opaquely.
-*/
-/** Thrown when the requested clip file does not exist (clips are gitignored). */
-var MissingClipError = class extends Error {
-	clipPath;
-	constructor(clipPath) {
-		super(`LoopingClipFrameSource: clip not found at "${clipPath}". Bench clips under test-output/bench/ are gitignored and not committed — this test must be skipped when the clip is absent.`);
-		this.name = "MissingClipError";
-		this.clipPath = clipPath;
-	}
-};
+/** Default synthetic frame geometry when the caller does not specify one. */
+var DEFAULT_WIDTH = 640;
+var DEFAULT_HEIGHT = 360;
+/** How many distinct synthetic frames to cycle through (looped at EOF). */
+var DEFAULT_FRAME_COUNT = 30;
 /** Bytes per pixel for an emitted packed format. */
 function bytesPerPixel(format) {
 	return format === "gray" ? 1 : 3;
 }
-/** Infer the clip codec from its file extension. */
-function inferCodec(clipPath) {
-	const lower = clipPath.toLowerCase();
-	return lower.endsWith(".hevc") || lower.endsWith(".h265") ? "h265" : "h264";
-}
 /**
-* Create a looping-clip decoded-frame source.
+* Create a looping synthetic-frame source.
 *
-* Validates the clip path eagerly: a missing clip throws `MissingClipError`
-* synchronously so callers can `try { … } catch (MissingClipError) { skip }`.
+* @throws If `targetFps`, `width`, `height`, or `frameCount` are not positive.
 */
 function createLoopingClipFrameSource(options) {
-	const { clipPath, targetFps } = options;
+	const { targetFps } = options;
 	const format = options.format ?? "rgb";
-	const codec = options.codec ?? inferCodec(clipPath);
+	const width = options.width ?? DEFAULT_WIDTH;
+	const height = options.height ?? DEFAULT_HEIGHT;
+	const frameCount = options.frameCount ?? DEFAULT_FRAME_COUNT;
 	if (!Number.isFinite(targetFps) || targetFps <= 0) throw new Error(`LoopingClipFrameSource: targetFps must be > 0, got ${targetFps}`);
-	if (!(0, node_fs.existsSync)(clipPath)) throw new MissingClipError(clipPath);
-	return new LoopingClipFrameSourceImpl(clipPath, targetFps, format, codec);
+	if (!Number.isInteger(width) || width <= 0 || !Number.isInteger(height) || height <= 0) throw new Error(`LoopingClipFrameSource: width/height must be positive integers`);
+	if (!Number.isInteger(frameCount) || frameCount <= 0) throw new Error(`LoopingClipFrameSource: frameCount must be a positive integer`);
+	return new SyntheticFrameSourceImpl(targetFps, format, width, height, frameCount);
 }
-var LoopingClipFrameSourceImpl = class {
-	clipPath;
+var SyntheticFrameSourceImpl = class {
 	targetFps;
 	format;
-	codec;
+	width;
+	height;
 	timer = null;
-	clip = null;
+	frames;
 	nextIndex = 0;
 	nextPts = 0;
 	running = false;
-	constructor(clipPath, targetFps, format, codec) {
-		this.clipPath = clipPath;
+	constructor(targetFps, format, width, height, frameCount) {
 		this.targetFps = targetFps;
 		this.format = format;
-		this.codec = codec;
+		this.width = width;
+		this.height = height;
+		const byteLength = width * height * bytesPerPixel(format);
+		const frames = [];
+		for (let f = 0; f < frameCount; f += 1) {
+			const buf = Buffer.allocUnsafe(byteLength);
+			const base = f * 37 + 11;
+			for (let i = 0; i < byteLength; i += 1) buf[i] = base + i & 255;
+			frames.push(buf);
+		}
+		this.frames = frames;
 	}
 	async start(onFrame) {
 		if (this.running) throw new Error("LoopingClipFrameSource: already started");
 		this.running = true;
-		const clip = await decodeClip(this.clipPath, this.codec, this.format);
-		if (clip.frames.length === 0) {
-			this.running = false;
-			throw new Error(`LoopingClipFrameSource: clip "${this.clipPath}" decoded to zero frames`);
-		}
-		this.clip = clip;
 		const periodMs = 1e3 / this.targetFps;
 		const ptsStepUs = Math.round(1e6 / this.targetFps);
 		this.timer = setInterval(() => {
-			if (!this.running || this.clip === null) return;
-			const { frames, width, height } = this.clip;
-			const pixels = frames[this.nextIndex];
+			if (!this.running) return;
+			const pixels = this.frames[this.nextIndex];
 			if (pixels === void 0) return;
 			const pts = this.nextPts;
 			this.nextPts += ptsStepUs;
-			this.nextIndex = (this.nextIndex + 1) % frames.length;
+			this.nextIndex = (this.nextIndex + 1) % this.frames.length;
 			onFrame({
 				pixels,
-				width,
-				height,
+				width: this.width,
+				height: this.height,
 				format: this.format,
 				pts
 			});
@@ -104,121 +77,7 @@ var LoopingClipFrameSourceImpl = class {
 			clearInterval(this.timer);
 			this.timer = null;
 		}
-		this.clip = null;
 	}
 };
-/**
-* Decode an entire raw Annex-B clip to packed pixel buffers.
-*
-* Ported from `scripts/bench-nodeav.mts` — software decode (no hwaccel, so the
-* path is deterministic and headless-safe), then a `SoftwareScaleContext`
-* scales each frame to the requested packed format at native resolution.
-*/
-async function decodeClip(clipPath, codec, format) {
-	const rawData = (0, node_fs.readFileSync)(clipPath);
-	const nav = await import("node-av");
-	const C = await import("node-av/constants");
-	nav.Log.setLevel(C.AV_LOG_FATAL);
-	const codecId = codec === "h265" ? C.AV_CODEC_ID_HEVC : C.AV_CODEC_ID_H264;
-	const decoderCodec = nav.Codec.findDecoder(codecId);
-	if (!decoderCodec) throw new Error(`LoopingClipFrameSource: no decoder for ${codec}`);
-	const parser = new nav.CodecParser();
-	parser.init(codecId);
-	const ctx = new nav.CodecContext();
-	ctx.allocContext3(decoderCodec);
-	ctx.threadCount = 2;
-	const openRet = await ctx.open2(decoderCodec);
-	if (openRet < 0) throw new Error(`LoopingClipFrameSource: decoder open2 failed (rc=${openRet})`);
-	const navPixFmt = pixelFormatConstant(C, format);
-	const channels = bytesPerPixel(format);
-	const pkt = new nav.Packet();
-	pkt.alloc();
-	const frame = new nav.Frame();
-	frame.alloc();
-	const scaler = new nav.SoftwareScaleContext();
-	let scalerReady = false;
-	const dstFrame = new nav.Frame();
-	dstFrame.alloc();
-	const frames = [];
-	let width = 0;
-	let height = 0;
-	try {
-		let offset = 0;
-		while (offset < rawData.length) {
-			const remaining = rawData.subarray(offset);
-			const consumed = parser.parse2(ctx, pkt, remaining, BigInt(offset), BigInt(offset), offset);
-			if (consumed < 0) break;
-			offset += consumed;
-			if (consumed === 0 && pkt.size === 0) break;
-			if (pkt.size > 0) {
-				const sendRet = ctx.sendPacketSync(pkt);
-				pkt.unref();
-				if (sendRet < 0 && sendRet !== C.AVERROR_EAGAIN) continue;
-				drainFrames();
-			}
-		}
-		ctx.sendPacketSync(null);
-		drainFrames();
-	} finally {
-		parser[Symbol.dispose]?.();
-		pkt[Symbol.dispose]?.();
-		frame[Symbol.dispose]?.();
-		dstFrame[Symbol.dispose]?.();
-		scaler[Symbol.dispose]?.();
-		ctx[Symbol.dispose]?.();
-	}
-	return {
-		frames,
-		width,
-		height
-	};
-	/** Receive + scale every frame currently buffered in the decoder. */
-	function drainFrames() {
-		while (true) {
-			if (ctx.receiveFrameSync(frame) < 0) break;
-			if (width === 0) {
-				width = frame.width;
-				height = frame.height;
-			}
-			if (!scalerReady) {
-				dstFrame.width = width;
-				dstFrame.height = height;
-				dstFrame.format = navPixFmt;
-				dstFrame.allocBuffer();
-				const srcPixFmt = frame.format;
-				scaler.getContext(frame.width, frame.height, srcPixFmt, width, height, navPixFmt, C.SWS_FAST_BILINEAR);
-				scaler.initContext();
-				scalerReady = true;
-			}
-			dstFrame.makeWritable();
-			scaler.scaleFrameSync(dstFrame, frame);
-			frames.push(extractPacked(dstFrame, width, height, channels));
-		}
-	}
-}
-/** Map an emitted packed format to its `node-av` `AV_PIX_FMT_*` constant. */
-function pixelFormatConstant(C, format) {
-	switch (format) {
-		case "rgb": return C.AV_PIX_FMT_RGB24;
-		case "bgr": return C.AV_PIX_FMT_BGR24;
-		case "gray": return C.AV_PIX_FMT_GRAY8;
-	}
-}
-/**
-* Extract a tightly packed (stride === width*channels) pixel buffer from a
-* scaled `node-av` frame. The scaler may pad each row to a wider linesize —
-* copy row-by-row when so, ported from `bench-nodeav.mts`.
-*/
-function extractPacked(dstFrame, width, height, channels) {
-	const expectedStride = width * channels;
-	const actualStride = dstFrame.linesize[0] ?? expectedStride;
-	const plane = dstFrame.data?.[0];
-	if (!plane) throw new Error("LoopingClipFrameSource: scaled frame has no pixel plane");
-	if (actualStride === expectedStride) return Buffer.from(plane.subarray(0, expectedStride * height));
-	const packed = Buffer.allocUnsafe(expectedStride * height);
-	for (let y = 0; y < height; y += 1) plane.copy(packed, y * expectedStride, y * actualStride, y * actualStride + expectedStride);
-	return packed;
-}
 //#endregion
-exports.MissingClipError = MissingClipError;
 exports.createLoopingClipFrameSource = createLoopingClipFrameSource;

package/dist/testing/index.mjs

@@ -1,97 +1,70 @@
-import { existsSync, readFileSync } from "node:fs";
 //#region src/testing/looping-clip-frame-source.ts
-/**
-* `LoopingClipFrameSource` — a real-video decoded-frame source for Phase 5 (D9)
-* shm-frame-plane tests.
-*
-* A metadata-only synthetic camera has no decodable video. The intensive shm
-* tests (perf comparison, frame-integrity,
-* soak) need a stream of *genuine* decoded pixels at a controlled fps. This
-* utility decodes a real `.h264` / `.hevc` clip via `node-av` and emits decoded
-* frames to a callback at a target rate, looping back to the clip start at EOF.
-*
-* The decoder wiring is ported from `scripts/bench-nodeav.mts` (the working
-* decode-from-file path) — software decode, no hardware accel, kept
-* dependency-light. Decoded frames are scaled to a known packed pixel format
-* (`rgb` / `bgr` / `gray`) so every emitted buffer has a deterministic
-* `width × height × bpp` byte length the tests can assert on.
-*
-* The clips live under `test-output/bench/` which is gitignored — they are NOT
-* committed. `createLoopingClipFrameSource` therefore validates the clip path
-* up front and surfaces a missing clip as a typed `MissingClipError`, so a
-* test can skip-with-a-clear-message rather than fail opaquely.
-*/
-/** Thrown when the requested clip file does not exist (clips are gitignored). */
-var MissingClipError = class extends Error {
-	clipPath;
-	constructor(clipPath) {
-		super(`LoopingClipFrameSource: clip not found at "${clipPath}". Bench clips under test-output/bench/ are gitignored and not committed — this test must be skipped when the clip is absent.`);
-		this.name = "MissingClipError";
-		this.clipPath = clipPath;
-	}
-};
+/** Default synthetic frame geometry when the caller does not specify one. */
+var DEFAULT_WIDTH = 640;
+var DEFAULT_HEIGHT = 360;
+/** How many distinct synthetic frames to cycle through (looped at EOF). */
+var DEFAULT_FRAME_COUNT = 30;
 /** Bytes per pixel for an emitted packed format. */
 function bytesPerPixel(format) {
 	return format === "gray" ? 1 : 3;
 }
-/** Infer the clip codec from its file extension. */
-function inferCodec(clipPath) {
-	const lower = clipPath.toLowerCase();
-	return lower.endsWith(".hevc") || lower.endsWith(".h265") ? "h265" : "h264";
-}
 /**
-* Create a looping-clip decoded-frame source.
+* Create a looping synthetic-frame source.
 *
-* Validates the clip path eagerly: a missing clip throws `MissingClipError`
-* synchronously so callers can `try { … } catch (MissingClipError) { skip }`.
+* @throws If `targetFps`, `width`, `height`, or `frameCount` are not positive.
 */
 function createLoopingClipFrameSource(options) {
-	const { clipPath, targetFps } = options;
+	const { targetFps } = options;
 	const format = options.format ?? "rgb";
-	const codec = options.codec ?? inferCodec(clipPath);
+	const width = options.width ?? DEFAULT_WIDTH;
+	const height = options.height ?? DEFAULT_HEIGHT;
+	const frameCount = options.frameCount ?? DEFAULT_FRAME_COUNT;
 	if (!Number.isFinite(targetFps) || targetFps <= 0) throw new Error(`LoopingClipFrameSource: targetFps must be > 0, got ${targetFps}`);
-	if (!existsSync(clipPath)) throw new MissingClipError(clipPath);
-	return new LoopingClipFrameSourceImpl(clipPath, targetFps, format, codec);
+	if (!Number.isInteger(width) || width <= 0 || !Number.isInteger(height) || height <= 0) throw new Error(`LoopingClipFrameSource: width/height must be positive integers`);
+	if (!Number.isInteger(frameCount) || frameCount <= 0) throw new Error(`LoopingClipFrameSource: frameCount must be a positive integer`);
+	return new SyntheticFrameSourceImpl(targetFps, format, width, height, frameCount);
 }
-var LoopingClipFrameSourceImpl = class {
-	clipPath;
+var SyntheticFrameSourceImpl = class {
 	targetFps;
 	format;
-	codec;
+	width;
+	height;
 	timer = null;
-	clip = null;
+	frames;
 	nextIndex = 0;
 	nextPts = 0;
 	running = false;
-	constructor(clipPath, targetFps, format, codec) {
-		this.clipPath = clipPath;
+	constructor(targetFps, format, width, height, frameCount) {
 		this.targetFps = targetFps;
 		this.format = format;
-		this.codec = codec;
+		this.width = width;
+		this.height = height;
+		const byteLength = width * height * bytesPerPixel(format);
+		const frames = [];
+		for (let f = 0; f < frameCount; f += 1) {
+			const buf = Buffer.allocUnsafe(byteLength);
+			const base = f * 37 + 11;
+			for (let i = 0; i < byteLength; i += 1) buf[i] = base + i & 255;
+			frames.push(buf);
+		}
+		this.frames = frames;
 	}
 	async start(onFrame) {
 		if (this.running) throw new Error("LoopingClipFrameSource: already started");
 		this.running = true;
-		const clip = await decodeClip(this.clipPath, this.codec, this.format);
-		if (clip.frames.length === 0) {
-			this.running = false;
-			throw new Error(`LoopingClipFrameSource: clip "${this.clipPath}" decoded to zero frames`);
-		}
-		this.clip = clip;
 		const periodMs = 1e3 / this.targetFps;
 		const ptsStepUs = Math.round(1e6 / this.targetFps);
 		this.timer = setInterval(() => {
-			if (!this.running || this.clip === null) return;
-			const { frames, width, height } = this.clip;
-			const pixels = frames[this.nextIndex];
+			if (!this.running) return;
+			const pixels = this.frames[this.nextIndex];
 			if (pixels === void 0) return;
 			const pts = this.nextPts;
 			this.nextPts += ptsStepUs;
-			this.nextIndex = (this.nextIndex + 1) % frames.length;
+			this.nextIndex = (this.nextIndex + 1) % this.frames.length;
 			onFrame({
 				pixels,
-				width,
-				height,
+				width: this.width,
+				height: this.height,
 				format: this.format,
 				pts
 			});
@@ -103,120 +76,7 @@ var LoopingClipFrameSourceImpl = class {
 			clearInterval(this.timer);
 			this.timer = null;
 		}
-		this.clip = null;
 	}
 };
-/**
-* Decode an entire raw Annex-B clip to packed pixel buffers.
-*
-* Ported from `scripts/bench-nodeav.mts` — software decode (no hwaccel, so the
-* path is deterministic and headless-safe), then a `SoftwareScaleContext`
-* scales each frame to the requested packed format at native resolution.
-*/
-async function decodeClip(clipPath, codec, format) {
-	const rawData = readFileSync(clipPath);
-	const nav = await import("node-av");
-	const C = await import("node-av/constants");
-	nav.Log.setLevel(C.AV_LOG_FATAL);
-	const codecId = codec === "h265" ? C.AV_CODEC_ID_HEVC : C.AV_CODEC_ID_H264;
-	const decoderCodec = nav.Codec.findDecoder(codecId);
-	if (!decoderCodec) throw new Error(`LoopingClipFrameSource: no decoder for ${codec}`);
-	const parser = new nav.CodecParser();
-	parser.init(codecId);
-	const ctx = new nav.CodecContext();
-	ctx.allocContext3(decoderCodec);
-	ctx.threadCount = 2;
-	const openRet = await ctx.open2(decoderCodec);
-	if (openRet < 0) throw new Error(`LoopingClipFrameSource: decoder open2 failed (rc=${openRet})`);
-	const navPixFmt = pixelFormatConstant(C, format);
-	const channels = bytesPerPixel(format);
-	const pkt = new nav.Packet();
-	pkt.alloc();
-	const frame = new nav.Frame();
-	frame.alloc();
-	const scaler = new nav.SoftwareScaleContext();
-	let scalerReady = false;
-	const dstFrame = new nav.Frame();
-	dstFrame.alloc();
-	const frames = [];
-	let width = 0;
-	let height = 0;
-	try {
-		let offset = 0;
-		while (offset < rawData.length) {
-			const remaining = rawData.subarray(offset);
-			const consumed = parser.parse2(ctx, pkt, remaining, BigInt(offset), BigInt(offset), offset);
-			if (consumed < 0) break;
-			offset += consumed;
-			if (consumed === 0 && pkt.size === 0) break;
-			if (pkt.size > 0) {
-				const sendRet = ctx.sendPacketSync(pkt);
-				pkt.unref();
-				if (sendRet < 0 && sendRet !== C.AVERROR_EAGAIN) continue;
-				drainFrames();
-			}
-		}
-		ctx.sendPacketSync(null);
-		drainFrames();
-	} finally {
-		parser[Symbol.dispose]?.();
-		pkt[Symbol.dispose]?.();
-		frame[Symbol.dispose]?.();
-		dstFrame[Symbol.dispose]?.();
-		scaler[Symbol.dispose]?.();
-		ctx[Symbol.dispose]?.();
-	}
-	return {
-		frames,
-		width,
-		height
-	};
-	/** Receive + scale every frame currently buffered in the decoder. */
-	function drainFrames() {
-		while (true) {
-			if (ctx.receiveFrameSync(frame) < 0) break;
-			if (width === 0) {
-				width = frame.width;
-				height = frame.height;
-			}
-			if (!scalerReady) {
-				dstFrame.width = width;
-				dstFrame.height = height;
-				dstFrame.format = navPixFmt;
-				dstFrame.allocBuffer();
-				const srcPixFmt = frame.format;
-				scaler.getContext(frame.width, frame.height, srcPixFmt, width, height, navPixFmt, C.SWS_FAST_BILINEAR);
-				scaler.initContext();
-				scalerReady = true;
-			}
-			dstFrame.makeWritable();
-			scaler.scaleFrameSync(dstFrame, frame);
-			frames.push(extractPacked(dstFrame, width, height, channels));
-		}
-	}
-}
-/** Map an emitted packed format to its `node-av` `AV_PIX_FMT_*` constant. */
-function pixelFormatConstant(C, format) {
-	switch (format) {
-		case "rgb": return C.AV_PIX_FMT_RGB24;
-		case "bgr": return C.AV_PIX_FMT_BGR24;
-		case "gray": return C.AV_PIX_FMT_GRAY8;
-	}
-}
-/**
-* Extract a tightly packed (stride === width*channels) pixel buffer from a
-* scaled `node-av` frame. The scaler may pad each row to a wider linesize —
-* copy row-by-row when so, ported from `bench-nodeav.mts`.
-*/
-function extractPacked(dstFrame, width, height, channels) {
-	const expectedStride = width * channels;
-	const actualStride = dstFrame.linesize[0] ?? expectedStride;
-	const plane = dstFrame.data?.[0];
-	if (!plane) throw new Error("LoopingClipFrameSource: scaled frame has no pixel plane");
-	if (actualStride === expectedStride) return Buffer.from(plane.subarray(0, expectedStride * height));
-	const packed = Buffer.allocUnsafe(expectedStride * height);
-	for (let y = 0; y < height; y += 1) plane.copy(packed, y * expectedStride, y * actualStride, y * actualStride + expectedStride);
-	return packed;
-}
 //#endregion
-export { MissingClipError, createLoopingClipFrameSource };
+export { createLoopingClipFrameSource };

package/dist/testing/looping-clip-frame-source.d.ts

@@ -1,5 +1,5 @@
 import { FrameFormat } from '@camstack/types';
-/** A decoded frame handed to the `onFrame` callback. */
+/** A generated frame handed to the `onFrame` callback. */
 export interface ClipFrame {
     /** Packed pixel bytes in `format` — length is exactly `width * height * bpp`. */
     readonly pixels: Buffer;
@@ -11,46 +11,37 @@ export interface ClipFrame {
 }
 /** Pixel formats this source can emit — the packed, fixed-bpp subset of `FrameFormat`. */
 export type EmittedFrameFormat = Extract<FrameFormat, 'rgb' | 'bgr' | 'gray'>;
-/** Callback invoked once per emitted decoded frame. */
+/** Callback invoked once per emitted frame. */
 export type OnFrame = (frame: ClipFrame) => void;
 /** Options for `createLoopingClipFrameSource`. */
 export interface LoopingClipFrameSourceOptions {
-    /** Absolute (or cwd-relative) path to a raw `.h264` / `.hevc` Annex-B clip. */
-    readonly clipPath: string;
     /** Target emission rate, frames per second. Must be > 0. */
     readonly targetFps: number;
     /**
-     * Packed pixel format every emitted frame is scaled to. Defaults to `rgb`.
+     * Packed pixel format every emitted frame uses. Defaults to `rgb`.
      * `gray` is 1 byte/px; `rgb` / `bgr` are 3 bytes/px.
      */
     readonly format?: EmittedFrameFormat;
-    /**
-     * Codec of the clip. Defaults to inference from the file extension
-     * (`.hevc` / `.h265` → `h265`, otherwise `h264`).
-     */
-    readonly codec?: ClipCodec;
+    /** Emitted frame width in pixels. Defaults to {@link DEFAULT_WIDTH}. */
+    readonly width?: number;
+    /** Emitted frame height in pixels. Defaults to {@link DEFAULT_HEIGHT}. */
+    readonly height?: number;
+    /** How many distinct frames to cycle through. Defaults to {@link DEFAULT_FRAME_COUNT}. */
+    readonly frameCount?: number;
 }
-/** Supported clip codecs. */
-export type ClipCodec = 'h264' | 'h265';
 /** The running frame source returned by `createLoopingClipFrameSource`. */
 export interface LoopingClipFrameSource {
     /**
-     * Begin decoding + emitting frames to `onFrame` at the target fps. Resolves
-     * once emission has started; rejects if the decoder cannot be initialised.
+     * Begin emitting frames to `onFrame` at the target fps. Resolves once
+     * emission has started.
      */
     start(onFrame: OnFrame): Promise<void>;
-    /** Halt emission and release the decoder. Idempotent. */
+    /** Halt emission. Idempotent. */
     stop(): Promise<void>;
 }
-/** Thrown when the requested clip file does not exist (clips are gitignored). */
-export declare class MissingClipError extends Error {
-    readonly clipPath: string;
-    constructor(clipPath: string);
-}
 /**
- * Create a looping-clip decoded-frame source.
+ * Create a looping synthetic-frame source.
  *
- * Validates the clip path eagerly: a missing clip throws `MissingClipError`
- * synchronously so callers can `try { … } catch (MissingClipError) { skip }`.
+ * @throws If `targetFps`, `width`, `height`, or `frameCount` are not positive.
  */
 export declare function createLoopingClipFrameSource(options: LoopingClipFrameSourceOptions): LoopingClipFrameSource;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/shm-ring",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "CamStack shared-memory frame ring — cross-platform N-API segment mapping + seqlock ring",
   "keywords": [
     "camstack",
@@ -46,11 +46,9 @@
   "dependencies": {
     "@camstack/types": "*",
     "node-addon-api": "^8.7.0",
-    "node-av": "^6.0.0",
     "node-gyp-build": "^4.8.4"
   },
   "devDependencies": {
-    "node-av": "^6.0.0",
     "prebuildify": "^6.0.1",
     "typescript": "~6.0.3",
     "vite": "^8.0.11",