3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Audit render-crucible-media skill for 0.21.0 (#1979)
Nguyen Xuan Anc9dffba51db4
diff --git a/changes/1979-render.md b/changes/1979-render.mdnew file mode 100644index 00000000..6f40e051--- /dev/null+++ b/changes/1979-render.md@@ -0,0 +1 @@+- The render-crucible-media skill matches 0.21.0 again: quality tiers, estimate and budget, transparent `stillCount` sequences, grid volumes in Cook, streamed texture sequences, caches, new limits and error rows (#1979)diff --git a/skills/render-crucible-media/SKILL.md b/skills/render-crucible-media/SKILL.mdindex 62bfc168..c6a8ebb4 100644--- a/skills/render-crucible-media/SKILL.md+++ b/skills/render-crucible-media/SKILL.md@@ -1,6 +1,6 @@---name: render-crucible-media-description: Export a Crucible scene to PNG stills, render passes or an MP4 through the MCP render job tools (scene_render_submit, scene_render_status, scene_render_result) of the npm package @codepawlhq/crucible. Use when an agent must render an image or video of a scene, play a camera or light animation to video, cut shots with a timeline, add a score, write depth or object-ID passes, path trace a still, choose GPU or CPU and an encoder, or stay inside memory limits. Also for "render ảnh 3D", "render video 3D", "xuất mp4", "export Crucible", "render bị lỗi bộ nhớ", "chất lượng MSAA". Scene building is the build-crucible-scene skill.+description: Export a Crucible scene to PNG stills, render passes or an MP4 through the MCP render job tools (scene_render_submit, scene_render_status, scene_render_result) of the npm package @codepawlhq/crucible. Use when an agent must render an image or video of a scene, play a camera or light animation to video, cut shots with a timeline, add a score, write depth or object-ID passes, make a transparent frame sequence, path trace a still, pick a quality tier, choose GPU or CPU and an encoder, or stay inside memory limits. Also for "render ảnh 3D", "render video 3D", "xuất mp4", "export Crucible", "render bị lỗi bộ nhớ", "chất lượng MSAA". Scene building is the build-crucible-scene skill.license: MIT---@@ -15,12 +15,15 @@ submit call fails: tell the user which launch option is missing.1. `scene_look` first. Never submit a job for a scene you have not looked at.2. `scene_inspect` for the current `revision`.-3. `scene_render_submit` with `expectedRevision` and `settings`. Start small: one image at 960x540.-4. `scene_render_status` with the `jobId` until the state is terminal (`completed`, `failed`, `cancelled`,- `interrupted`). Poll about every 5 to 10 seconds, and for video read the durable frame progress. Never loop tightly. Status and result- answer in a short `concise` form by default; pass `response_format: "detailed"` for the full record.+3. `scene_render_submit` with `expectedRevision` and `settings`. Start small and fast: one image at 960x540 with+ `quality: "draft"`. The reply carries `estimate` (`seconds`, `peakMemoryMiB`) and, with `quality`, which tier will run.+4. `scene_render_status` with the `jobId` alone (a `sessionId` is refused) until the state is terminal (`completed`,+ `failed`, `cancelled`, `interrupted`). Wait about the estimated seconds, then poll every 5 to 10 seconds and read the+ durable frame progress. Never loop tightly. Status and result answer in a short `concise` form by default; pass+ `response_format: "detailed"` for the full record.5. `scene_render_result`: output paths, sizes and metrics. Report the actual `width` and `height`, the backendand the seconds; memory limits can lower the size. `detailed` adds SHA-256 hashes and resource counters.+ `metrics.report.fallbacks` lists everything that ran differently from the request: read it.6. Keep what you need, then `scene_render_release` to remove the job's files.7. `scene_render_cancel` stops a job; poll `scene_render_status` until it is `cancelled` before editing again.@@ -28,26 +31,29 @@ submit call fails: tell the user which launch option is missing.| Task | Read ||---|---|-| Image, stills, video, motion clock, shots, audio, encoder, passes, path tracer | `${CLAUDE_SKILL_DIR}/references/jobs.md` |+| Image, stills, transparent sequences, video, motion clock, shots, audio, encoder, passes, path tracer, quality tiers, grid volumes and texture sequences | `${CLAUDE_SKILL_DIR}/references/jobs.md` || Size, memory, GPU or CPU, time limits, verifying the file | `${CLAUDE_SKILL_DIR}/references/limits-and-checks.md` || A job failed or the result looks wrong | `${CLAUDE_SKILL_DIR}/references/errors-and-recovery.md` || Rendering in a source checkout with `scripts/render-media.mjs` (contributors only) | `${CLAUDE_SKILL_DIR}/references/rendering.md` |## Rules-- Smallest output that meets the need: a still before a video, a 2 second slice before the full film.- Every film round starts as a small, low-quality preview with sound; full quality only after sign-off.+- Smallest output that meets the need: a `draft` still before a video, a 2 second slice before the full film.+ Every film round starts as a small, low-quality preview with sound; full quality (`final`, or a larger size) only+ after sign-off. Never submit the final render first.- Time is deterministic. A frame depends on its time only, so a seek gives the same pixels as the frame in a video.Never record the screen.- Use `settings.motion: { "start": 0 }` to play recipe tracks (camera, nodes, lights, sun, sky, effects). Without it thejob holds the first pose, which is the usual reason a video is a still frame. A recipe with a `timeline` uses`settings.timeline` and rejects `motion` and `animation`.-- A recipe whose only motion is `physics` (or `cloth`, `particles`) is filmed with the same `motion: { "start": 0 }`; the- job plays the bake on the scene clock, so do not `bake-motion` first. Video `duration` defaults to the bake length.+- A recipe whose only motion is `physics` (or `cloth`, `particles`), a grid volume sequence or a texture sequence is+ filmed with the same `motion: { "start": 0 }`; the job plays the bake on the scene clock, so do not `bake-motion`+ first. Video `duration` defaults to the bake length.- Imported clips use `settings.animation`; the two clocks are independent.-- For compositing, `settings.transparent`, `settings.format` (`png16`, `exr`) and `settings.region` are off by default; video runs up to 60 fps (`references/jobs.md`, Compositing output).-- Path tracing (`settings.renderer`) is offline and slow: judge a still first. A video job takes it too, one trace per- frame; passes, `transparent`, `format` and `region` need the rasterizer.+- For compositing, `settings.transparent`, `settings.format` (`png16`, `exr`) and `settings.region` are off by default; a+ transparent frame sequence is one `stills` job with `stillCount`; video runs up to 60 fps (`references/jobs.md`).+- Path tracing (`settings.renderer`, or `quality: "final"`) is offline and slow: judge a still first. A video job takes+ it too, one trace per frame; passes, `transparent`, `format` and `region` need the rasterizer.- Do not stop another session's process. Heavy local exports run at below-normal priority, one job at a time.- A GLB for Blender is `scene_export_glb`, not a render job.diff --git a/skills/render-crucible-media/references/errors-and-recovery.md b/skills/render-crucible-media/references/errors-and-recovery.mdindex f5d2515f..7455c482 100644--- a/skills/render-crucible-media/references/errors-and-recovery.md+++ b/skills/render-crucible-media/references/errors-and-recovery.md@@ -17,14 +17,21 @@ message first: each one names the cause and the next step.| `metrics.sync` difference over 50 ms | Encode drift. | The job fails; resubmit, and report it if it repeats. || Path tracer `gpu` refused | The server runs with `--backend cpu`. | Use `backend: "cpu"` or ask for a GPU server. || Smaller output than asked | The memory budget reduced it. | Report the actual size; ask for a larger `--memory` if size matters. |-| State `failed` with a time limit | The job passed 60 s plus 2 s per frame. | Lower the size, fps or samples, or split the film into parts. |+| State `failed` with a time limit | The job passed 60 s plus 2 s per frame of render time. | Lower the size, fps or samples, or split the film into parts. Under a shared GPU the message says to submit again. |+| `Motion settings require a recipe with authored motion, physics...` | Nothing in the recipe moves. | Add motion, physics, a placed clip, a map sequence or a grid volume sequence, or drop `motion`. |+| `duration is (stillCount - 1) / fps` | `stillCount` came with another `duration`. | Leave `duration` out. |+| `transparent`, `format` or `region` refused | Combined with `renderer` (traced PNG is opaque 8-bit) or, for `transparent` and `format`, with `kind: "video"`. | Drop `renderer` (or use a raster `quality`), or use `stills`. |+| `quality final` ran as another tier | `final` cannot draw `passes`, `transparent`, `region`, `multilayer` or a non-png `format`, or one frame would pass `maxSeconds`. | Read `quality.steps`; ask for the raster tier you want, or a smaller traced frame. |+| A path traced job is refused with a triangle count | The `cpu` tracer takes about 400,000 triangles; `native` is bounded by the adapter. | Use `backend: "native"` or `gpu`, or lower the scene. |+| Over the 64 MiB asset cap | Placed assets plus `.67vg` grid files of the scene. | Fewer frames, a lower grid resolution or smaller assets. |+| Memory guard error from a native job | The guard names the limit and the MiB it saw. | Raise `--memory`, or lower size and frames. || State `interrupted` | The server restarted during the job. | Recovery never restarts rendering; resubmit. |## Recover1. `scene_render_cancel` if it is still running, then poll `scene_render_status` until `cancelled`.2. Preview edits work again once the job is terminal.-3. Fix one setting, resubmit a small version (a still or 2 seconds) and check it before the full job.+3. Fix one setting, resubmit a small version (a `draft` still or 2 seconds) and check it before the full job.4. `scene_render_release` every job you are done with, failed ones too, so the store stays small.5. If a valid job fails with a graphics error or a crash, stop retrying. File an issue at `codepawl/crucible` with thesettings, the recipe from `scene_export_recipe` and the `scene_render_result` or status message. No local paths.diff --git a/skills/render-crucible-media/references/jobs.md b/skills/render-crucible-media/references/jobs.mdindex a603c96b..4af65380 100644--- a/skills/render-crucible-media/references/jobs.md+++ b/skills/render-crucible-media/references/jobs.md@@ -3,8 +3,9 @@<!-- skill-navigation:start -->This is the [Render job settings](#render-job-settings) reference. Read the opening paragraph, then only the section for the job:[One PNG](#one-png), [Eight stills](#eight-stills), [MP4 of recipe motion](#mp4-of-recipe-motion), [Shots, cuts and sound](#shots-cuts-and-sound),-[Encoder](#encoder), [Render passes](#render-passes), [Compositing output: alpha, 16-bit, EXR, region, 60 fps](#compositing-output-alpha-16-bit-exr-region-60-fps),-[Path traced still](#path-traced-still) (also traced video) and [Imported character clips](#imported-character-clips).+[Encoder](#encoder), [Quality tiers, estimate and budget](#quality-tiers-estimate-and-budget), [Render passes](#render-passes),+[Compositing output: alpha, 16-bit, EXR, region, 60 fps](#compositing-output-alpha-16-bit-exr-region-60-fps),+[Path traced still](#path-traced-still) (also traced video), [Grid volumes and texture sequences](#grid-volumes-and-texture-sequences) and [Imported character clips](#imported-character-clips).<!-- skill-navigation:end -->Every recipe is the arguments of `scene_render_submit`. `sessionId` may be left out. `expectedRevision` is the@@ -31,8 +32,10 @@ render the video.{ "expectedRevision": 3, "settings": { "kind": "stills", "width": 640, "height": 360, "duration": 4, "motion": { "start": 0 } } }```-`stillCount` (2 to 300) writes that many numbered PNGs instead, one per 1/`fps` s of the motion clock. Leave `duration` out: it is-`(stillCount - 1) / fps`. With `transparent: true` this gives an overlay in one job. For a longer clip, submit the next job with `motion.start` advanced by `stillCount / fps`.+`stillCount` (2 to 300) writes that many numbered PNGs (`frame-0.png` to `frame-<N-1>.png`) instead, one per 1/`fps` s of the motion clock, the+instants a video of that `fps` would show. Leave `duration` out: it is `(stillCount - 1) / fps`, and any other value is refused. With+`transparent: true` each frame is an RGBA PNG: a transparent frame sequence for compositing, in one job. For a longer clip, submit the next job with+`motion.start` advanced by `stillCount / fps`. One job's files stay under 128 MiB together (a `png16` or `exr` frame counts up to 4 times an 8-bit one).## MP4 of recipe motion@@ -74,6 +77,30 @@ longer than one job (60 s) render parts with `track: "pcm"` (lossless, no encodefails the job and does not fall back, so choose `cpu` unless you know the machine. The result reports`metrics.videoEncoder`, `captureSeconds` and `renderSeconds`.+## Quality tiers, estimate and budget++`settings.quality` says what the render is for, so you need not know the renderer behind it.++| Tier | What runs |+|---|---|+| `draft` | Glaze (the raster renderer), light shading, no multisampling, coarse detail: the fast preview |+| `realtime` | Glaze at the preview's own settings |+| `realtime-high` | Glaze with 8 samples and fine detail; needs a hardware GPU |+| `final` | The path tracer at 256 samples with the wavelet denoiser, on `native` when Cook and a ray query adapter exist, else `gpu`, else `cpu` |++```json+{ "expectedRevision": 3, "settings": { "kind": "image", "width": 640, "height": 360, "quality": "draft" } }+```++The same call with `"quality": "final"` is the offline image. Leave `renderer` out: `quality` picks it. `final` needs a lit PNG, so with `passes`,+`transparent`, `region`, `multilayer` or a `format` other than `png` it falls back. A tier the device cannot run falls back one tier at a time;+`scene_render_submit` returns `quality` with `requested`, `picked` and `steps` naming what was missing, so say which tier ran.+`scene_capabilities` topic `jobs` lists `tiers` for this device.++`scene_render_submit` also returns `estimate` (`seconds`, `peakMemoryMiB`, `framesPerSecond`). To let the job choose, give `settings.budget`:+`{ "secondsPerFrame": 2 }` (offline) or `{ "framesPerSecond": 30 }` (real time), with optional `memoryMiB`. Give exactly one of the two, and no+`renderer` or `quality` beside it. The reply has `budget.picked`, `fits` and `reason`.+## Render passes`image` and `stills` jobs take `passes`, a list of `albedo`, `normal`, `emission`, `depth`, `objectId`, `diffuse`, `glossy`, `shadow`, `ao` and `mist` (lighting terms: use `exr` for them).@@ -85,7 +112,8 @@ also writes one raw PNG per pass at the lit image's size, with no grading, bloom```Only opaque and cutout geometry appears. `scene_render_result` metrics carry `objectNames` (read the names for the IDs;-IDs follow draw order, not node order) and `depthRangeMetres`. Depth is metres over 100 in a 16-bit value (high byte+IDs follow draw order, not node order), `objectNodes` (the node of each ID) and `depthRangeMetres`; `cryptomatte` adds `metrics.cryptomatte`+(`{ objects, materials }`). Per-node line art is `environment.lines.nodes` in the recipe, not a pass. Depth is metres over 100 in a 16-bit value (high bytein red, low in green); background is `255, 255, 0`. Videos hold the lit image only.## Compositing output: alpha, 16-bit, EXR, region, 60 fps@@ -124,10 +152,29 @@ stops at 30 minutes, so keep a traced video short and small. It writes no passes`backend` is `cpu` (default, reproducible), `gpu` (needs a server started with `--backend gpu`) or `native`(hardware ray queries; it falls back to `gpu` or `cpu` and `metrics.pathTracer.backendNote` says why). Start with 16-samples to judge the light, then raise them. Ranges: `samples` 1 to 1024, `bounces` 1 to 16, `maxSeconds` 1 to 600.-`denoise` is `true` (the built-in filter), `false`, or `"oidn"` where the server has that optional package.+samples to judge the light, then raise them. Ranges: `samples` 1 to 1024 (default 64, 16 with `oidn`), `bounces` 1 to 16 (default 8), `maxSeconds` 1 to 600+(default 120), `seed` 0 to 2147483647, `noiseThreshold` 0 to 0.1 (0 draws every sample).+`denoise` is `true` (the built-in filter), `false`, `"wavelet"`, `"none"` or `"oidn"` where the server has that optional package.+A scene far over the `cpu` tracer's 400,000 triangles is refused at submit with the count; `native` takes more, up to what the adapter reports, and refuses a bigger scene+with the count and the limit. `metrics.report.noise.verdict` says whether to raise `samples`. Native traces grid volumes (next section).The OIDN package `@codepawlhq/crucible-denoise-oidn` is a separate package: `npm install @codepawlhq/crucible-denoise-oidn`, then `node node_modules/@codepawlhq/crucible-denoise-oidn/fetch-oidn.mjs` (or set `OIDN_DENOISE_PATH`). Without it the job does not fail: it runs the wavelet filter (the GPU a-trous filter on `backend: "native"`) and says so in `metrics.pathTracer.denoiser` and `denoiserNote`. Check `denoiser` before you judge grain.+## Grid volumes and texture sequences++New in 0.21.0. Both play on the `motion` clock, so a recipe whose only animation is one of them takes `motion: { "start": 0 }`.++- Grid volumes (a blast from `add-explosion`, or your own `.67vg` files): a `grid` or each `frames` entry is a plain file name ending in `.67vg` in the server's grid+ folder (its working directory, or the folder `JS67_GRID_DIRECTORY` names). The frame drawn is `floor(time * fps)`. A grid file is at most 64 MiB, and all grid files+ plus the placed assets of one call at most 64 MiB. They draw in Glaze, the CPU and WebGPU path tracers and `renderer.backend: "native"` (Cook). With the scene's+ motion blur on, bake with `velocity: true` so the blast smears along its flow. Older grid fires with `blackbodyIntensity` look 3 to 4 times dimmer than before 0.21.0:+ raise it or the exposure.+- The first draw of a grid volume compiles a shader, so a first `scene_create` or job may take tens of seconds (limit 60 s). The server keeps the blast bake+ (`CRUCIBLE_BAKE_CACHE`) and Chrome's compiled shaders (`CRUCIBLE_SHADER_CACHE`, GPU backend) between runs, so later runs are fast; `off` or `0` turns them off.+ A cold first frame is the same pixels as a warm one.+- Texture sequences: a material `map.sequence` lists up to 4096 frames of up to 2048 pixels. Over 64 frames it streams: the host decodes the frame of each time and keeps+ two, so a video walks the frames in order. A folder of more than 256 numbered images is one `sequences` entry in `scene_asset_catalog`; name it with `catalog` instead of+ listing the frames.+## Imported character clips`animation: { "clip": 0, "start": 1 }` samples an imported asset's clip and `rendererTime` sets shader time. Theydiff --git a/skills/render-crucible-media/references/limits-and-checks.md b/skills/render-crucible-media/references/limits-and-checks.mdindex 0d7690a1..d085abb6 100644--- a/skills/render-crucible-media/references/limits-and-checks.md+++ b/skills/render-crucible-media/references/limits-and-checks.md@@ -9,17 +9,23 @@| `--jobs <abs dir>` | Private store for job files. Required for any job. || `--ffmpeg <abs path>` | Needed for MP4 when ffmpeg is not on PATH. || `--audio <abs dir>` | The folder `settings.audio.file` names a file from. |+| `--gpu-queue <abs exe or JSON array>` and `--gpu-queue-wait` | Optional queue command that looks, reviews, bakes and render jobs wait for before they take the GPU, so the server can share a card. |`scene_capabilities` reports the backend, memory, job limits and the job UUIDs it holds after a restart. Check itbefore you promise a size or a sound track.## Job limits-- Width and height 64 to 1920 each (an image job up to 3840, at most 3840x2160), within the memory budget. A video or stills job that does not fit is reduced, and an image job larger than 1920x1080 is refused with the --memory it needs; the result reports- the actual dimensions, so say them.-- Video: at most 60 s and 900 frames (60 s needs 15 fps or less), even dimensions, shots up to 64 and 60 s total.-- Time allowed: 60 s plus 2 s per frame (more above 1024x576), at most 30 minutes. A path traced still has its own- `maxSeconds`.+- Width and height 64 to 1920 each (an image job up to 3840, at most 3840x2160), within the memory budget. A square frame fits up to 1440 for stills and video+ and 2880 for an image. A video or stills job that does not fit is reduced, and an image job larger than 1920x1080 is refused with the --memory it needs; the result reports+ the actual dimensions, so say them. `metrics.report.fallbacks` says when a frame was cut.+- Video: at most 60 s and 900 frames (60 s needs 15 fps or less), even dimensions, shots up to 64 and 60 s total. A stills job writes 2 to 300 frames+ (`stillCount`, default 8).+- Time allowed: 60 s plus 2 s per frame (more above 1024x576), at most 30 minutes, counted from when the render starts. The wait behind other calls+ (and a shared GPU queue) is bounded apart, at 5 minutes. A job over its deadline under a shared GPU fails with advice to submit again. A path traced job has its own+ `maxSeconds` per frame.+- Output files of one job: 128 MiB in all, 12 MiB a frame (48 MiB for `png16` or `exr`); a job over it fails with that limit.+- Placed assets and `.67vg` grid files of one scene count together toward a 64 MiB cap; a scene over it fails with the cap message.- A job leases the single preview renderer: previews and edits pause while it runs, inspection and recipe export stayavailable. Plan one job at a time.@@ -36,8 +42,11 @@ before you promise a size or a sound track.second difference `|f[t+1] - 2 f[t] + f[t-1]|` in 8-bit grey. Smooth camera motion cancels in it; noise stays. Astill-looking film scores about 1. Above 2, fix it before showing anyone: blend each denoised frame into thereprojected history of the frames before it (first-hit depth and the two cameras). More samples alone did not fix- it in a room lit through one window: 1024 spp still scored 2 (An caught it, 2026-11-13).-6. The framebuffer figure is an allocation model, not total VRAM, and Node and browser heap samples do not cover every+ it in a room lit through one window: 1024 spp still scored 2.+6. A path traced still from `backend: "native"` can differ from the raster look: put a `draft` still of the same scene beside it before trusting either. Open reports:+ an `environment.skyMap` sun may sit near world -z instead of along `sunDirection` (codepawl/cook#65), and a native trace of an unlit night scene may ignore+ environment lighting and exposure and render bright (#1833). If the two stills disagree on the sun or the exposure, say so and file the issue.+7. The framebuffer figure is an allocation model, not total VRAM, and Node and browser heap samples do not cover everyallocation. Report them as estimates.## Speeddiff --git a/skills/render-crucible-media/references/rendering.md b/skills/render-crucible-media/references/rendering.mdindex 0648d6c5..c2fd0abd 100644--- a/skills/render-crucible-media/references/rendering.md+++ b/skills/render-crucible-media/references/rendering.md@@ -10,7 +10,7 @@ node scripts/score.mjsnode scripts/render-media.mjs --kind video --scene film --backend gpu --preset balanced --encoder gpu --output artifacts/critical.mp4```-The available scenes are `object`, `nature`, `film`, `motion`, `view2d` and `assets`.+The available scenes are `object`, `nature`, `film`, `motion`, `view2d`, `assets`, `modeling` and `file` (`--scene file --config <scene.json>`; `--config`, `--camera` and `--root` need it).GPU rendering selects hardware WebGL through Chrome. CPU rendering requests ANGLE SwiftShader.The CPU exporter verifies that the selected backend reports SwiftShader.@@ -30,19 +30,17 @@ It disposes the previous scene before uploading the next scene.For object images, `--assembly 1` explodes the model. The default value `0` assembles it.Each option requires a value. Dimensions range from 64 to 4096 pixels.-Memory ranges from 32 to 1024 MiB. Duration ranges from 0.1 to 120 seconds.-MCP render jobs (`scene_render_submit`) take up to 1920x1080 (each side up to 1920, at most that many pixels), and an image job up to 3840x2160 (measured: 2880x1620 of a plain scene needs `--memory 373`, textures need more) and `--memory` up to half of the machine's RAM (at most 4096 MiB). A 1920x1080 frame needs about 175 MiB of targets, so use `--memory 256` for it. A job gets 60 s plus 2 s per frame (more for frames above 1024x576), at most 30 minutes; the video encoder waits 30 s to drain and to finish.+Memory ranges from 32 to 1024 MiB (8192 for `--scene file`, which defaults to the budget in its config). Duration ranges from 0.1 to 240 seconds, and `--fps` from 1 to 60.+The limits of MCP render jobs are a different set: see `limits-and-checks.md`.-The video encoder can use `--encoder cpu` or `--encoder gpu` independently of the renderer backend.-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.+`--encoder` is `auto` (the default for the GPU backend: NVENC when the probe finds it, else libx264), `cpu` or `gpu`, independently of the renderer backend.+`--encoder gpu` 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`) 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 auto`, the default for video, uses WebCodecs and falls back to screenshots (never raw readback, which is slower) when the browser cannot hardware encode the size or `--encoder cpu` or `--backend cpu` is requested. `--capture webcodecs` fails instead of falling back, `--capture jpeg` and `--capture png` keep screenshots, and `--capture raw` keeps the `readPixels` and WebSocket path as opt in. The hardware encoder is the browser's, so the bitstream can differ between machines and drivers even though the frames are deterministic, which is why `--encoder cpu` keeps libx264 on screenshots.-Profile of the first readback design (10 s of the film, 240 frames, RTX 3060, 1280 by 720): 94 ms a frame in capture, of which `readPixels` was 6.6 ms and ffmpeg was nothing, because ffmpeg alone with vflip, the BT.709 conversion and NVENC took 3.7 ms a frame (3.0 ms with no filter). The cost was moving 3.7 MB of pixels from Chrome to Node over a WebSocket: 27 to 52 ms a frame depending on frames in flight and sockets, about 100 to 140 MB a second, and still 9 to 16 ms for the 1.4 MB a YUV 4:2:0 frame would need. Chrome's WebCodecs `VideoEncoder` removes the pixels from the trip. The page encodes each frame with the browser's hardware H.264 encoder (fixed quantizer 20, no B-frames), so only about 5 to 60 kB of encoded chunks a frame cross the socket, and `ffmpeg -c copy` muxes them with the audio. Measured on the full 4,488 frame film at 1280 by 720: 20.6 s in all, draw 2.0 ms and capture 2.2 ms a frame, no encoder backpressure. The same machine, same evening, screenshots took 139.6 s (capture 25.1 ms a frame) and the first raw readback took 405.1 s (capture 84.8 ms a frame). On a 10 s clip within one hour, capture was 4.2 ms with WebCodecs, 22.1 ms with screenshots and 93.9 ms with raw readback. The result matches the NVENC raw path of the same clip at 44.8 dB PSNR (quantizer 22 when measured), is tagged BT.709 limited range, and has all 4,488 frames.-Returning the pixels through Playwright instead cost 55 ms a frame, and a fetch with a Blob body failed after about 100 frames, so neither is used.+Why WebCodecs is the default (measured on one RTX 3060, 1280 by 720, the 4,488 frame film, one evening): in-page encoding took 20.6 s in all (draw 2.0 ms and capture 2.2 ms a frame), screenshots 139.6 s, and raw `readPixels` over a WebSocket 405.1 s, because moving 3.7 MB of pixels to Node cost 27 to 52 ms a frame. Only 5 to 60 kB of encoded chunks a frame cross the socket, and `ffmpeg -c copy` muxes them with the audio. The output is BT.709 limited range.A decoded raw frame matches the PNG seek of the same time at 41.0 dB PSNR on SwiftShader (`npm run smoke:capture-parity`).`scripts/score.mjs` generates the original film score.