Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Add an opt-in raw frame capture to the film render script

Nguyen Xuan An17f2dcccb643
diff --git a/changes/301.md b/changes/301.md
new file mode 100644
index 00000000..c0353434
--- /dev/null
+++ b/changes/301.md
@@ -0,0 +1 @@
+- Add `--capture raw` to `scripts/render-media.mjs` (issue #301), which reads each video frame from the drawing buffer with `readPixels` and pipes RGBA to ffmpeg instead of taking a JPEG screenshot, and make the script pick a free port and read Vite's coloured ready line. It is opt in until it survives a full film (a 20 s clip ran 97 frames at 55 fps against 22 fps with screenshots, then a post failed).
diff --git a/docs/agent-render-jobs.md b/docs/agent-render-jobs.md
index 11ac089d..0478a154 100644
--- a/docs/agent-render-jobs.md
+++ b/docs/agent-render-jobs.md
@@ -36,6 +36,8 @@ The source revision, pose and checkpoints survive completion or cancellation.
Cancellation becomes terminal after the owned encoder and job page stop and the preview recovers.
Video uses H.264 (CPU by default, see `settings.encoder`), even dimensions and one streamed frame at a time.
+MCP video jobs still take a JPEG screenshot per frame. Measured at 1280 by 720 on an RTX 3060, capture is 28.8 ms and the draw 7.4 ms a frame, and `metrics.captureSeconds` and `metrics.renderSeconds` report both.
+A raw read of the drawing buffer exists in `scripts/render-media.mjs` as `--capture raw` and is not yet in the MCP job (issue #301).
The render backend can use GPU or CPU. Memory limits can reduce the actual output dimensions.
Results report actual dimensions and measured timings. They do not embed video bytes.
diff --git a/scripts/frame-encoder.mjs b/scripts/frame-encoder.mjs
index 3db12bd4..c2641ee6 100644
--- a/scripts/frame-encoder.mjs
+++ b/scripts/frame-encoder.mjs
@@ -1,27 +1,32 @@
import { spawn } from 'node:child_process';
import { stat } from 'node:fs/promises';
import { performance } from 'node:perf_hooks';
+import { rawFrameInputArguments } from './gpu-frame-reader.mjs';
/** Drain and finalization wait this long: below-normal priority jobs on a busy machine need more than 5 s. */
export const DEFAULT_ENCODER_TIMEOUT_MS = 30000;
/** One streamed frame at a time. The caller owns output publication and cleanup. */
export function createFrameEncoder({ executable = 'ffmpeg', output, fps, format = 'jpeg', backend = 'cpu',
- audioArguments = [], signal, maximumFrameBytes = 1024 * 1024,
+ audioArguments = [], width, height, signal, maximumFrameBytes = 1024 * 1024,
maximumOutputBytes = 128 * 1024 * 1024, timeoutMs = DEFAULT_ENCODER_TIMEOUT_MS } = {}) {
if (typeof output !== 'string' || !output || !Number.isFinite(fps) || fps < 1 || fps > 60 ||
- !['jpeg', 'png'].includes(format) || !['cpu', 'gpu'].includes(backend)) {
+ !['jpeg', 'png', 'rawvideo'].includes(format) || !['cpu', 'gpu'].includes(backend)) {
throw new TypeError('Encoder requires an output path, valid fps, format and backend.');
}
for (const value of [maximumFrameBytes, maximumOutputBytes, timeoutMs]) {
if (!Number.isSafeInteger(value) || value <= 0) throw new RangeError('Encoder limits must be positive safe integers.');
}
+ if (format === 'rawvideo' && !(Number.isSafeInteger(width) && Number.isSafeInteger(height) && width > 0 && height > 0)) {
+ throw new TypeError('Raw video frames need a width and a height.');
+ }
signal?.throwIfAborted();
+ const raw = format === 'rawvideo' ? rawFrameInputArguments({ width, height, fps }) : undefined;
const codec = backend === 'gpu'
? ['-c:v', 'h264_nvenc', '-preset', 'p5', '-cq', '20']
: ['-c:v', 'libx264', '-preset', 'fast', '-crf', '18', '-threads', '2'];
- const argumentsValue = ['-hide_banner', '-loglevel', 'error', '-y', '-f', 'image2pipe', '-framerate', String(fps),
- '-vcodec', format === 'jpeg' ? 'mjpeg' : 'png', '-i', 'pipe:0', ...audioArguments, ...codec,
+ const argumentsValue = ['-hide_banner', '-loglevel', 'error', '-y', ...(raw ? raw.input : ['-f', 'image2pipe', '-framerate', String(fps), '-vcodec', format === 'jpeg' ? 'mjpeg' : 'png']),
+ '-i', 'pipe:0', ...audioArguments, ...(raw ? raw.filter : []), ...codec,
'-pix_fmt', 'yuv420p', '-color_primaries', 'bt709', '-color_trc', 'bt709', '-colorspace', 'bt709',
'-movflags', '+faststart', ...(audioArguments.length ? ['-c:a', 'aac', '-b:a', '192k', '-shortest'] : []),
'-f', 'mp4', output];
diff --git a/scripts/gpu-frame-reader.mjs b/scripts/gpu-frame-reader.mjs
new file mode 100644
index 00000000..8aefbe77
--- /dev/null
+++ b/scripts/gpu-frame-reader.mjs
@@ -0,0 +1,115 @@
+// Raw video frames straight from the drawing buffer, shared by the MCP render job and scripts/render-media.mjs.
+// A DevTools screenshot makes the compositor encode a JPEG and send it as base64, 84 percent of a film job (issue #301).
+// A read of the drawing buffer skips both. It must run in the same task as the draw, because the browser clears the
+// drawing buffer once it has presented the frame. The page then posts the bytes to a Node receiver as a binary body:
+// returning a typed array from Playwright's evaluate costs about 50 ms for a 1280 by 720 frame, a post costs a few.
+import { randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+
+/** Runs in the page. Defines window.__finishDraw() and window.__readFrame(url), which posts the bottom-up RGBA pixels. */
+function installFrameReader() {
+ let pixels;
+ const canvasContext = () => document.querySelector('canvas').getContext('webgl2');
+ // Waits for the GPU to finish the draw, so that draw time is not counted as read time.
+ window.__finishDraw = () => canvasContext().finish();
+ window.__readFrame = async (url) => {
+ const context = canvasContext();
+ const { drawingBufferWidth: width, drawingBufferHeight: height } = context;
+ if (!pixels || pixels.length !== width * height * 4) pixels = new Uint8Array(width * height * 4);
+ const readStarted = performance.now();
+ context.readPixels(0, 0, width, height, context.RGBA, context.UNSIGNED_BYTE, pixels);
+ const readMilliseconds = performance.now() - readStarted;
+ // A Blob body: Playwright keeps a copy of every typed-array body it sees (3.7 MB a frame) until the page closes.
+ // A connection that the server closed while idle fails the first post, so one retry follows.
+ let response;
+ try { response = await fetch(url, { method: 'POST', body: new Blob([pixels]) }); }
+ catch { response = await fetch(url, { method: 'POST', body: new Blob([pixels]) }); }
+ if (!response.ok) throw new Error(`The frame receiver answered ${response.status}.`);
+ return { width, height, readMilliseconds };
+ };
+}
+
+/** Call once per page before the first frame. */
+export async function installFrameReaderInPage(page) {
+ await page.evaluate(installFrameReader);
+}
+
+/** The ffmpeg input arguments for raw frames. GL rows run bottom-up, so the picture is flipped, and RGB converts with BT.709. */
+export function rawFrameInputArguments({ width, height, fps }) {
+ return { input: ['-f', 'rawvideo', '-pix_fmt', 'rgba', '-s', `${width}x${height}`, '-framerate', String(fps)],
+ filter: ['-vf', 'vflip,scale=out_color_matrix=bt709:out_range=tv'] };
+}
+
+/** A slow frame on the CPU backend takes longer than the default five seconds a server keeps an idle connection. */
+export const KEEP_ALIVE_MILLISECONDS = 120000;
+
+/**
+ * Receives one posted frame at a time on a path nobody else knows. `handle(request, response)` returns true when it
+ * took the request. `crossOrigin` answers with the headers a page on another port needs.
+ */
+export function createFrameReceiver({ maximumBytes, crossOrigin = false }) {
+ const path = `/__frame/${randomBytes(12).toString('hex')}`;
+ // One buffer is reused for every frame, so a long film does not leave a buffer of garbage per frame for the collector.
+ const frameBuffer = Buffer.allocUnsafe(maximumBytes);
+ let received;
+ function handle(request, response) {
+ if (request.url !== path) return false;
+ if (crossOrigin) response.setHeader('Access-Control-Allow-Origin', '*');
+ if (request.method !== 'POST') {
+ response.writeHead(405);
+ response.end();
+ return true;
+ }
+ let total = 0;
+ let tooLarge = false;
+ request.on('data', chunk => {
+ if (tooLarge) return;
+ if (total + chunk.length > maximumBytes) {
+ tooLarge = true;
+ response.writeHead(413);
+ response.end();
+ return;
+ }
+ chunk.copy(frameBuffer, total);
+ total += chunk.length;
+ });
+ request.on('end', () => {
+ if (tooLarge) return;
+ received = frameBuffer.subarray(0, total);
+ response.writeHead(204);
+ response.end();
+ });
+ return true;
+ }
+ return Object.freeze({
+ path,
+ handle,
+ /** The frame the page posted since the last call, checked against the size the encoder was started with. */
+ take({ width, height }, info) {
+ if (info.width !== width || info.height !== height) {
+ throw new Error(`The drawing buffer is ${info.width}x${info.height} but the video is ${width}x${height}.`);
+ }
+ const frame = received;
+ received = undefined;
+ if (!frame || frame.length !== width * height * 4) throw new Error('The page did not deliver a complete frame.');
+ return frame;
+ },
+ });
+}
+
+/** A loopback server that only receives frames, for pages that another server already serves. */
+export async function startFrameServer(receiver) {
+ const server = createServer((request, response) => {
+ if (!receiver.handle(request, response)) {
+ response.writeHead(404);
+ response.end();
+ }
+ });
+ await new Promise((resolve, reject) => {
+ server.keepAliveTimeout = KEEP_ALIVE_MILLISECONDS;
+ server.once('error', reject);
+ server.listen(0, '127.0.0.1', resolve);
+ });
+ return { url: `http://127.0.0.1:${server.address().port}${receiver.path}`,
+ close: () => new Promise(resolve => { server.closeAllConnections(); server.close(resolve); }) };
+}
diff --git a/scripts/render-media.mjs b/scripts/render-media.mjs
index d0bf0356..3b002daa 100644
--- a/scripts/render-media.mjs
+++ b/scripts/render-media.mjs
@@ -2,11 +2,13 @@ import { chromium } from 'playwright';
import { spawn } from 'node:child_process';
import { mkdir, writeFile, stat } from 'node:fs/promises';
import { existsSync } from 'node:fs';
+import { createServer } from 'node:net';
import { fileURLToPath } from 'node:url';
import { resolve, dirname, basename } from 'node:path';
import { FILM_DURATION } from '../src/film.js';
import { RENDER_PRESETS } from '../src/budget.js';
import { createFrameEncoder } from './frame-encoder.mjs';
+import { createFrameReceiver, installFrameReaderInPage, startFrameServer } from './gpu-frame-reader.mjs';
function argumentsFrom(values) {
const result = {};
@@ -52,7 +54,8 @@ export function parseRenderOptions(values) {
const memory = numberOption('memory', preset.memoryBudgetMiB, 32, 1024);
const assembly = numberOption('assembly', 0, 0, 1);
const captureFormat = options.capture ?? (kind === 'video' ? 'jpeg' : 'png');
- if (!['jpeg', 'png'].includes(captureFormat)) throw new Error('Capture must be jpeg or png.');
+ if (!['jpeg', 'png', 'raw'].includes(captureFormat)) throw new Error('Capture must be raw, jpeg or png.');
+ if (captureFormat === 'raw' && kind !== 'video') throw new Error('Raw capture is for video only. Stills are PNG or JPEG screenshots.');
const jpegQuality = numberOption('jpeg-quality', 95, 1, 100);
if (!Number.isInteger(jpegQuality)) throw new Error('JPEG quality must be an integer.');
const output = resolve(options.output ?? `artifacts/${scene}-${backend}.${kind === 'video' ? 'mp4' : captureFormat === 'jpeg' ? 'jpg' : 'png'}`);
@@ -94,6 +97,18 @@ function probeNvenc(ffmpeg) {
});
}
+/** Another render or dev server on this machine may already hold a fixed port, so ask the system for a free one. */
+function freePort() {
+ return new Promise((resolvePort, reject) => {
+ const probe = createServer();
+ probe.once('error', reject);
+ probe.listen(0, '127.0.0.1', () => {
+ const { port } = probe.address();
+ probe.close(() => resolvePort(port));
+ });
+ });
+}
+
export async function renderMedia(values = process.argv.slice(2)) {
const plan = parseRenderOptions(values);
const { options, kind, backend, scene, presetName, preset, aspect, width, height, fps, time, start, memory, assembly, output, captureFormat, jpegQuality } = plan;
@@ -107,8 +122,11 @@ export async function renderMedia(values = process.argv.slice(2)) {
const ffmpeg = process.platform === 'win32' ? resolve(process.env.USERPROFILE, '.local/bin/ffmpeg.exe') : 'ffmpeg';
const encoderBackend = kind === 'video' ? await selectEncoderBackend(plan.encoderBackend, () => probeNvenc(ffmpeg)) : null;
const chrome = 'C:/Program Files/Google/Chrome/Application/chrome.exe';
- const server = spawn(process.execPath, ['node_modules/vite/bin/vite.js', '--config', 'scripts/render-vite.config.mjs', '--host', '127.0.0.1', '--port', '5181', '--strictPort'], { cwd: root, windowsHide: true, stdio: 'pipe' });
+ const serverPort = await freePort();
+ const server = spawn(process.execPath, ['node_modules/vite/bin/vite.js', '--config', 'scripts/render-vite.config.mjs', '--host', '127.0.0.1', '--port', String(serverPort), '--strictPort'], { cwd: root, windowsHide: true, stdio: 'pipe' });
let browser;
+ let frameReceiver;
+ let frameServer;
let encoder;
let peakNodeBytes = 0;
let peakBrowserHeap = 0;
@@ -117,13 +135,14 @@ export async function renderMedia(values = process.argv.slice(2)) {
let firstFrameBytes = 0;
let actualRenderSize;
let capturedFrames = 0;
- const stageTimings = { renderSeconds: 0, captureSeconds: 0, encoderBackpressureSeconds: 0, encoderFinishSeconds: 0 };
+ const stageTimings = { renderSeconds: 0, captureSeconds: 0, readPixelsSeconds: 0, encoderBackpressureSeconds: 0, encoderFinishSeconds: 0 };
const started = performance.now();
try {
await new Promise((resolveStarted, reject) => {
const timeout = setTimeout(() => reject(new Error('Render server did not start.')), 15000);
server.stdout.on('data', (data) => {
- if (data.toString().includes('127.0.0.1:5181')) { clearTimeout(timeout); resolveStarted(); }
+ // Vite bolds the port number when colour is forced, so strip the colour codes before looking for it.
+ if (data.toString().replace(/\u001b\[[0-9;]*m/g, '').includes(`127.0.0.1:${serverPort}`)) { clearTimeout(timeout); resolveStarted(); }
});
server.on('error', reject);
server.on('exit', (code) => { clearTimeout(timeout); reject(new Error(`Render server exited ${code}.`)); });
@@ -136,7 +155,7 @@ export async function renderMedia(values = process.argv.slice(2)) {
page.on('pageerror', (error) => errors.push(error.message));
const route = scene === 'object' ? 'object.html' : `${scene}.html`;
const query = new URLSearchParams({ export: '1', width: String(width), height: String(height), aspect, memory: String(memory), samples: String(backend === 'cpu' ? 1 : preset.samples) });
- await page.goto(`http://127.0.0.1:5181/${route}?${query}`);
+ await page.goto(`http://127.0.0.1:${serverPort}/${route}?${query}`);
await page.waitForFunction((mode) => window.__scene?.renderer || (mode === 'film' ? window.__filmReady : mode === 'nature' ? window.__nature?.renderer : mode === 'object' ? window.__studio?.renderer : false), scene, { timeout: 60000 });
if (options.asset) {
await page.locator('#file').setInputFiles(resolve(options.asset));
@@ -173,28 +192,49 @@ export async function renderMedia(values = process.argv.slice(2)) {
} else window.renderAt = (time) => window.__nature.renderAt(time);
}, { memory, width, height, samples: backend === 'cpu' ? 1 : preset.samples, scene, assembly });
const session = await page.context().newCDPSession(page);
+ if (captureFormat === 'raw') {
+ await installFrameReaderInPage(page);
+ frameReceiver = createFrameReceiver({ maximumBytes: width * height * 4, crossOrigin: true });
+ frameServer = await startFrameServer(frameReceiver);
+ }
+ // A raw frame is read from the drawing buffer in the same task as the draw. The round trip beyond the draw is capture.
const render = async (seconds) => {
if (errors.length) throw new Error(`Browser render errors: ${errors.join('; ')}`);
const renderStarted = performance.now();
- const rendererPlan = await page.evaluate((value) => {
+ const drawn = await page.evaluate(async ({ value, readFrame, receiverUrl }) => {
+ const drawStarted = performance.now();
if (window.__scene) window.__scene.renderAt(value);
else if (window.renderAt) window.renderAt(value);
else window.__nature.renderAt(value);
const renderer = window.__scene?.renderer ?? window.__film?.renderer ?? window.__nature?.renderer ?? window.__studio?.renderer;
const glError = renderer.context.getError();
if (glError !== 0) throw new Error(`WebGL render error ${glError}.`);
- return renderer.memoryPlan;
- }, seconds);
- stageTimings.renderSeconds += (performance.now() - renderStarted) / 1000;
+ if (readFrame) window.__finishDraw();
+ const drawMilliseconds = performance.now() - drawStarted;
+ return { rendererPlan: renderer.memoryPlan, drawMilliseconds, frame: readFrame ? await window.__readFrame(receiverUrl) : undefined };
+ }, { value: seconds, readFrame: captureFormat === 'raw', receiverUrl: frameServer?.url });
+ const rendererPlan = drawn.rendererPlan;
+ const roundTripSeconds = (performance.now() - renderStarted) / 1000;
+ const drawSeconds = drawn.frame ? drawn.drawMilliseconds / 1000 : roundTripSeconds;
+ stageTimings.renderSeconds += drawSeconds;
+ stageTimings.captureSeconds += roundTripSeconds - drawSeconds;
+ stageTimings.readPixelsSeconds += (drawn.frame?.readMilliseconds ?? 0) / 1000;
peakEstimatedRenderBytes = Math.max(peakEstimatedRenderBytes, rendererPlan.estimatedBytes);
actualRenderSize = { width: rendererPlan.width, height: rendererPlan.height, reduced: rendererPlan.reduced };
if (rendererPlan.estimatedBytes > memory * 1024 ** 2) throw new Error('Render target exceeded the configured memory budget.');
const nodeBytes = process.memoryUsage().rss;
peakNodeBytes = Math.max(peakNodeBytes, nodeBytes);
if (nodeBytes > 512 * 1024 ** 2) throw new Error('Capture process exceeded 512 MiB. Export stopped before buffering more frames.');
+ return drawn.frame;
};
async function capture(seconds) {
- await render(seconds);
+ const rawFrame = await render(seconds);
+ if (rawFrame) {
+ capturedFrames++;
+ const bytes = frameReceiver.take({ width, height }, rawFrame);
+ if (!firstFrameBytes) firstFrameBytes = bytes.byteLength;
+ return bytes;
+ }
const captureStarted = performance.now();
const screenshot = await session.send('Page.captureScreenshot', {
format: captureFormat,
@@ -211,8 +251,8 @@ export async function renderMedia(values = process.argv.slice(2)) {
const audioPath = plan.audio ? resolve(plan.audio) : null;
if (options.audio && !existsSync(audioPath)) throw new Error('The selected audio file was not found.');
const audioArguments = audioPath && existsSync(audioPath) ? ['-ss', String(start), '-i', audioPath] : [];
- encoder = createFrameEncoder({ executable: ffmpeg, output, fps, format: captureFormat,
- backend: encoderBackend, audioArguments, maximumFrameBytes: 64 * 1024 * 1024,
+ encoder = createFrameEncoder({ executable: ffmpeg, output, fps, format: captureFormat === 'raw' ? 'rawvideo' : captureFormat,
+ width, height, backend: encoderBackend, audioArguments, maximumFrameBytes: 64 * 1024 * 1024,
maximumOutputBytes: Number.MAX_SAFE_INTEGER });
const frameCount = Math.ceil(duration * fps);
const captureSequenceStarted = performance.now();
@@ -228,7 +268,7 @@ export async function renderMedia(values = process.argv.slice(2)) {
const elapsed = (performance.now() - captureSequenceStarted) / 1000;
const effectiveFps = (frame + 1) / elapsed;
const remainingSeconds = (frameCount - frame - 1) / effectiveFps;
- const message = `Rendered ${frame + 1}/${frameCount} frames | ${effectiveFps.toFixed(1)} fps | ${(effectiveFps / fps).toFixed(2)}x | ETA ${Math.ceil(remainingSeconds)}s`;
+ const message = `Rendered ${frame + 1}/${frameCount} frames | ${effectiveFps.toFixed(1)} fps | ${(effectiveFps / fps).toFixed(2)}x | ETA ${Math.ceil(remainingSeconds)}s | Node ${Math.round(process.memoryUsage().rss / 2 ** 20)} MiB`;
console.log(message);
}
}
@@ -263,7 +303,10 @@ export async function renderMedia(values = process.argv.slice(2)) {
await encoder?.close();
} finally {
try { await browser?.close(); }
- finally { server.kill(); }
+ finally {
+ try { await frameServer?.close(); }
+ finally { server.kill(); }
+ }
}
}
}
diff --git a/scripts/smoke-frame-encoder.mjs b/scripts/smoke-frame-encoder.mjs
index f638b367..003603d0 100644
--- a/scripts/smoke-frame-encoder.mjs
+++ b/scripts/smoke-frame-encoder.mjs
@@ -33,6 +33,26 @@ assert.equal(probe.streams[0].color_space, 'bt709');
assert.equal(Number(probe.format.duration), 2);
const decoded = run('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-i', output, '-frames:v', '2', '-f', 'rawvideo', '-pix_fmt', 'rgb24', 'pipe:1'], true);
assert.notDeepEqual(decoded.subarray(0, 64 * 64 * 3), decoded.subarray(64 * 64 * 3));
+// Raw frames are bottom-up RGBA, as readPixels gives them: the first row written (red) must decode at the bottom.
+const rawPixels = Buffer.alloc(64 * 64 * 4);
+for (let row = 0; row < 64; row++) {
+ for (let column = 0; column < 64; column++) {
+ const offset = (row * 64 + column) * 4;
+ rawPixels[offset + (row < 32 ? 0 : 2)] = 255;
+ rawPixels[offset + 3] = 255;
+ }
+}
+const rawOutput = join(directory, 'raw.mp4.partial');
+const rawEncoder = createFrameEncoder({ output: rawOutput, fps: 4, format: 'rawvideo', width: 64, height: 64 });
+try {
+ for (let index = 0; index < 4; index++) await rawEncoder.writeFrame(rawPixels);
+ await rawEncoder.finish();
+} finally { await rawEncoder.close(); }
+const rawDecoded = run('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-i', rawOutput, '-frames:v', '1', '-f', 'rawvideo', '-pix_fmt', 'rgb24', 'pipe:1'], true);
+const pixelAt = (row) => rawDecoded.subarray((row * 64 + 32) * 3, (row * 64 + 32) * 3 + 3);
+assert.ok(pixelAt(60)[0] > 200 && pixelAt(60)[2] < 60, 'the first row written must decode at the bottom as red');
+assert.ok(pixelAt(4)[2] > 200 && pixelAt(4)[0] < 60, 'the last rows written must decode at the top as blue');
+assert.throws(() => createFrameEncoder({ output: rawOutput, fps: 4, format: 'rawvideo' }), /width and a height/);
const cancelled = new AbortController();
const abortEncoder = createFrameEncoder({ output: join(directory, 'cancel.mp4.partial'), fps: 24, format: 'png', signal: cancelled.signal });
await abortEncoder.writeFrame(frames[0]);
diff --git a/skills/render-67js-media/references/rendering.md b/skills/render-67js-media/references/rendering.md
index ca67e833..818dfbf8 100644
--- a/skills/render-67js-media/references/rendering.md
+++ b/skills/render-67js-media/references/rendering.md
@@ -37,6 +37,14 @@ The video encoder can use `--encoder cpu` or `--encoder gpu` independently of th
The hardware encoder requires NVENC. A failed encoder stops the export and reports its error.
The renderer does not silently replace a failed hardware export with a lower-quality output.
+Video capture cost (measured on an RTX 3060 at 1280x720 on a loaded machine, 20 s of the film, 480 frames, NVENC).
+Screenshots (`--capture jpeg`, the default) cost 28.8 ms a frame to capture and 7.4 ms to draw, 21.5 s for the clip.
+Every report has `stageTimings.captureSeconds` and `renderSeconds`.
+`--capture raw` reads the drawing buffer with `readPixels` (3.3 ms a frame) and posts it to a local receiver as a binary body.
+It ran 97 frames at 55 fps, about 18 ms a frame in all, and then a post failed, so it is not the default yet and a full film is not proven.
+Returning the pixels through Playwright instead cost 55 ms a frame, worse than a screenshot.
+A typed-array post makes Playwright keep 3.7 MB per frame in Node. A Blob post does not.
+
`scripts/score.mjs` generates the original film score.
The `--audio <path>` option selects an existing score.
Only `film` selects the CRITICAL score automatically.
diff --git a/tests/export-options.test.js b/tests/export-options.test.js
index 7243712f..e460c793 100644
--- a/tests/export-options.test.js
+++ b/tests/export-options.test.js
@@ -59,6 +59,8 @@ test('video defaults to JPEG 95 and auto encoding while stills retain lossless P
const video = parseRenderOptions(['--kind', 'video']);
assert.equal(video.captureFormat, 'jpeg');
assert.equal(video.jpegQuality, 95);
+ assert.throws(() => parseRenderOptions(['--capture', 'raw']));
+ assert.equal(parseRenderOptions(['--kind', 'video', '--capture', 'raw']).captureFormat, 'raw');
assert.equal(video.encoderBackend, 'auto');
assert.equal(parseRenderOptions([]).captureFormat, 'png');
assert.equal(parseRenderOptions(['--kind', 'stills']).captureFormat, 'png');