Skip to content

The VS Code of video editing, built for agents.

TypeScript

Update capture command to render scene frames and improve documentation

konstantin-paulus22c75e7e2645
diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts
index 8a5c3fa4..c869ab38 100644
--- a/apps/cli/src/index.ts
+++ b/apps/cli/src/index.ts
@@ -615,10 +615,10 @@ program
program
.command("capture")
.description(
- `Render a node in isolation to PNGs. By default the positions are merged into contact sheets: up to 12 per image, each cell labelled with its timecode (\`08s10f\`, zero segments dropped) and rendered as large as fits, so a few positions arrive as one high-resolution picture instead of a directory to open one by one (\`--separate\` writes a PNG per position, at 720p height, keeping the alpha channel). The node is drawn offscreen, tightly framed to its own bounds on a transparent background; siblings and overlapping scene content are not included, so capture a scene id to check composition ("what plays at time T": layout, overlaps, text, timing). For a video asset's own full-resolution pixels use \`media grab\`.`,
+ `Render single frames of a scene to PNGs — each frame is the frame an export of that scene would encode, drawn offscreen at the scene's own size. By default the positions are merged into contact sheets: up to 12 per image, each cell labelled with its timecode (\`08s10f\`, zero segments dropped) and rendered as large as fits, so a few positions arrive as one high-resolution picture instead of a directory to open one by one (\`--separate\` writes a PNG per position, at 720p height). The tool for checking composition ("what plays at time T": layout, overlaps, text, timing) and for verifying frames before an export. Scenes only — a single element renders inside its scene, so capture the scene at the times it plays. For a video asset's own full-resolution pixels use \`media grab\`.`,
)
- .argument("<id>", 'node id to capture or `file:id` when two files use the same id')
- .option("-t, --time <time...>", `one or more positions to capture, relative to the node's start (0 = its first visible frame) — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: 0, the node's first visible frame)`)
+ .argument("<id>", 'scene id to capture or `file:id` when two files use the same id')
+ .option("-t, --time <time...>", `one or more positions to capture, relative to the export's first frame, the workarea's start (0 = the export's frame 0) — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: 0)`)
.option("-S, --separate", "write one PNG per position instead of merging them into contact sheets")
.option("--per-sheet <n>", "positions per contact sheet, 1-12; fewer means a larger cell each (default: as many as fit)")
.option("-o, --output <dir>", "directory to write the PNGs into (default: a fresh dir in the system temp dir)")
@@ -627,7 +627,7 @@ program
program
.command("check")
.description(
- `Check a node's subtree for obvious structural mistakes, without rendering (local analysis, no credits): spans where no visual is scheduled (likely black frames), children that never become visible, zero-duration or fully transparent nodes, and assets that failed to load or generate — plus subtree stats (node count by kind, nesting depth, played duration). Prints one JSON object; times in issue ranges are seconds relative to the node's start, the same clock \`capture --time\` uses. Exits 1 when an error-severity issue is found. Structural only: a scheduled clip can still render black (dark footage, content smaller than the canvas), so confirm suspicious spans visually with \`capture\`.`,
+ `Check a node's subtree for obvious structural mistakes, without rendering (local analysis, no credits): spans where no visual is scheduled (likely black frames), children that never become visible, zero-duration or fully transparent nodes, and assets that failed to load or generate — plus subtree stats (node count by kind, nesting depth, played duration). Prints one JSON object; times in issue ranges are seconds relative to the node's start — for a scene whose workarea starts at 0, the same clock \`capture --time\` uses. Exits 1 when an error-severity issue is found. Structural only: a scheduled clip can still render black (dark footage, content smaller than the canvas), so confirm suspicious spans visually with \`capture\`.`,
)
.argument("<id>", 'node id to check or `file:id` when two files use the same id')
.action((id: string) => checkNode(id));
diff --git a/apps/desktop/src/projects.ts b/apps/desktop/src/projects.ts
index 02cb8458..7b690c7b 100644
--- a/apps/desktop/src/projects.ts
+++ b/apps/desktop/src/projects.ts
@@ -644,7 +644,7 @@ All of them talk to the running app, except \`fonts\` and \`fetch\`.
| ------ | ------- | ------------ |
| \`open\` | \`dapi open .\` | Launch the app with this project open. |
| \`context\` | \`dapi context\` | Which project the app has open, where its playhead sits, its fonts, where its generations stand. |
-| \`capture\` | \`dapi capture <id>\` | Render one node in isolation to labelled PNG contact sheets. |
+| \`capture\` | \`dapi capture <id>\` | Render frames of a scene, as an export would, to labelled PNG contact sheets. |
| \`probe\` | \`dapi media probe <id\\|path>\` | Container and per-track metadata, without decoding. |
| \`transcribe\` | \`dapi media transcribe <id\\|path>\` | Timed speech transcript, word by word. |
| \`grab\` | \`dapi media grab <id\\|path>\` | Decode frames of a video to labelled PNG contact sheets. |
@@ -704,8 +704,9 @@ never edit it, and trust it over memory.
\`npm run <name> -- <args>\` runs one.
- \`npm run context\` reports what the app has open, where its playhead sits,
and where generations stand.
-- Verify visually with \`npm run capture -- <id>\`: it renders a node exactly
- as the viewer gets it. Do not export a video to check work.
+- Verify visually with \`npm run capture -- <sceneId>\`: it renders the
+ scene's frames exactly as an export encodes them. Do not export a video to
+ check work.
- Position and size are explicit, in pixels. There is no layout pass and no CSS.
- A composition you author from scratch marks one scene \`active\` and gives
\`<stage>\` a \`camera\` framing it, or the project opens on an empty timeline
diff --git a/apps/web/src/context/dapi/capture.ts b/apps/web/src/context/dapi/capture.ts
index eca0624b..28034ae0 100644
--- a/apps/web/src/context/dapi/capture.ts
+++ b/apps/web/src/context/dapi/capture.ts
@@ -11,6 +11,8 @@ import {
sheetTimecode,
} from "@diffusionstudio/encoder";
+import { getParentNode, isScene, Source } from "@diffusionstudio/runtime";
+
import { createCapture } from "@/engine/capture";
import { resolveNode } from "./nodes";
@@ -25,13 +27,29 @@ export function handleCapture(session: () => EditorSession) {
const { world, project } = session();
const node = resolveNode(world, id);
- // `undefined` means the node's first visible frame (the encoder's frame 0).
+ // Scenes only: a capture's promise is that its frames are the frames an
+ // export encodes, and a scene is the unit an export renders — framing an
+ // arbitrary node would need its bounds measured across the requested
+ // positions first, and that pre-roll runs the project's code ahead of the
+ // frames being drawn, which is exactly what an export never does.
+ if (!isScene(node)) {
+ let scene = getParentNode(node);
+ while (scene !== null && !isScene(scene)) scene = getParentNode(scene);
+ const stamp = scene?.get(Source)?.value;
+ throw new Error(
+ stamp
+ ? `"${id}" is not a scene — capture renders what an export renders. Capture its scene "${stamp}" instead.`
+ : `"${id}" is not a scene — capture renders what an export renders, so it takes a scene id.`,
+ );
+ }
+
+ // `undefined` means the export's first frame (the workarea's start).
let shots = frames;
if (shots === undefined || shots.length === 0) {
shots = [0];
}
- // The project re-rendered into a world of its own, reduced to this node:
+ // The project re-rendered into a world of its own, reduced to this scene:
// the same arrangement an export runs against, and the encoder's to draw.
const capture = await createCapture(world, node, { dir: project.dir() });
@@ -42,9 +60,9 @@ export function handleCapture(session: () => EditorSession) {
});
// Sheets render at their cell size instead of the flat 720p: with a few
- // frames that is sharper than a standalone capture, never coarser. A node
- // is drawn, not decoded, so a small one is worth rendering past its own
- // bounds; beyond SHEET_CAPTURE_HEIGHT that only costs tokens.
+ // frames that is sharper than a standalone capture, never coarser. A
+ // scene is drawn, not decoded, so a small one is worth rendering past
+ // its own size; beyond SHEET_CAPTURE_HEIGHT that only costs tokens.
const aspect = encoder.bounds.width / encoder.bounds.height;
const height = Math.max(encoder.bounds.height, SHEET_CAPTURE_HEIGHT);
const sizes = combine ? planSheetSizes(shots.length, perSheet) : [];
diff --git a/packages/encoder/src/encoder.ts b/packages/encoder/src/encoder.ts
index 5f3415f5..61d75fda 100644
--- a/packages/encoder/src/encoder.ts
+++ b/packages/encoder/src/encoder.ts
@@ -8,13 +8,13 @@ import {
AudioSample,
AudioSampleSource,
} from 'mediabunny';
-import { Not, Or } from 'koota';
+import { Not } from 'koota';
import {
- setActive, propagateTimeRangeDown, framesToSeconds,
+ setActive, framesToSeconds,
assert, store, isScene,
assetSystem, playbackSystem, motionSystem, transformSystem, renderSystem,
AudioBus, AudioBusHandle,
- ChildOf, Geometry, Group, Paint, Workarea, Playback,
+ ChildOf, Geometry, Paint, Workarea, Playback,
AudioPlayback, Computed,
Position, Offset, Rotation, Scale, Skew,
Time, FrameRate, RenderSurface, AudioEngine, Root,
@@ -34,7 +34,7 @@ import type { ExportResult } from './types';
* what to encode is the whole of what is in it — so a stage with anything
* else under it is a caller that has not finished preparing the world.
*/
-function captureScene(world: World): Entity {
+export function captureScene(world: World): Entity {
const roots = [...world.query(ChildOf(world.get(Root)!))];
assert(roots.length === 1, `A capture world holds one scene, this one holds ${roots.length}`);
@@ -410,7 +410,7 @@ function createThrottledCallback<T>(callback: ((value: T) => void) | undefined,
};
}
-function normalizeSceneTransform(world: World, sceneId: number): void {
+export function normalizeSceneTransform(world: World, sceneId: number): void {
const position = store(world, Position);
const offset = store(world, Offset);
const rotation = store(world, Rotation);
@@ -459,15 +459,3 @@ export async function resolverSystem(world: World) {
}
}
-/**
- * Refresh every entity's accumulated delay + time bounds after raw store
- * rewrites. propagateTimeRangeDown recomputes top-down and then re-derives
- * each parent after its children, since koota has no hierarchy-ordered
- * queries to walk in one pass.
- */
-export function recomputeAllTimeRanges(world: World): void {
- const stage = world.get(Root)!;
- for (const node of world.query(Or(Geometry, Group), ChildOf(stage))) {
- propagateTimeRangeDown(world, node);
- }
-}
diff --git a/packages/encoder/src/image-encoder.ts b/packages/encoder/src/image-encoder.ts
index f76247d3..85441422 100644
--- a/packages/encoder/src/image-encoder.ts
+++ b/packages/encoder/src/image-encoder.ts
@@ -2,22 +2,16 @@
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-import { Or } from 'koota';
import {
- createEntity, appendChild, getEntityTree, framesToSeconds,
- formatTimecode, assert, store,
+ setActive, framesToSeconds, formatTimecode, assert, store, getEntityTree,
assetSystem, playbackSystem, motionSystem, transformSystem, renderSystem,
- ChildOf, Geometry, Group, Hidden, IsMask, Muted, Culled,
- ClipsContent, Playback, Computed, WorldBounds,
- RenderSurface, AudioEngine, Root,
- setCamera,
- Time, FrameRate,
+ Muted, Workarea, Playback, Computed,
+ Time, FrameRate, RenderSurface, AudioEngine,
} from '@diffusionstudio/runtime';
-import { resolverSystem, recomputeAllTimeRanges, warmupAssets } from './encoder';
+import { captureScene, normalizeSceneTransform, resolverSystem, warmupAssets } from './encoder';
-import type { Entity, World } from 'koota';
-import type { AABB } from '@diffusionstudio/runtime';
+import type { World } from 'koota';
import type { ImageEncoderConfig } from './interfaces';
/** One capture: the PNG plus the timecode of the frame rendered, e.g. `01s15f`. */
@@ -29,22 +23,24 @@ export type ImageExportResult =
| { type: 'error'; error: Error };
/**
- * Renders single frames of the node a capture world holds into standalone
+ * Renders single frames of the scene a capture world holds into standalone
* PNGs (base64, no data-url prefix).
*
- * `world` is the caller's, built for this capture and holding the node as the
- * stage's only child — the same arrangement `createEncoder` takes, and for
- * the same reason. The canvas is sized to the union of the node's world-space
- * AABBs across the requested frames and the camera shifts that box onto it,
- * so the node is fully visible wherever it sat in the scene it was rendered
- * in.
+ * `world` is the caller's, built for this capture and holding the scene as
+ * the stage's only child — the same arrangement `createEncoder` takes, and
+ * for the same reason. A frame here is the frame an export would encode: the
+ * canvas is the scene's own size, frame 0 is the workarea's first frame, and
+ * the world is stepped the way an export steps it — the same systems, in the
+ * same order, forward only. Seeking runs the project's own code, and a
+ * DOM-backed node keeps what a seek did to it, so requested frames are
+ * rendered in ascending order whatever order they were asked in, and never
+ * measured or pre-rolled ahead of the first one drawn.
*/
export async function createImageEncoder(world: World, config: ImageEncoderConfig) {
assert(config.frames.length > 0, 'No frames requested');
- const roots = [...world.query(ChildOf(world.get(Root)!))];
- assert(roots.length === 1, `A capture world holds one node, this one holds ${roots.length}`);
- const root = roots[0]!;
+ const scene = captureScene(world);
+ const sceneId = scene.id();
const canvas = world.get(RenderSurface)?.canvas;
assert(canvas instanceof HTMLCanvasElement, 'The capture world has no canvas to draw into');
@@ -53,146 +49,88 @@ export async function createImageEncoder(world: World, config: ImageEncoderConfi
// for the lazy audio-bus wiring to have something to bind to.
world.set(AudioEngine, { context: new OfflineAudioContext(2, 1, 48000) });
- await warmupAssets(world);
-
- const frameRate = world.get(FrameRate)?.value ?? 30;
- const computed = store(world, Computed);
- const playback = store(world, Playback);
- const worldBounds = store(world, WorldBounds);
-
- const subtree = getEntityTree(world, root);
-
// Mute everything so the playback system never initializes audio decoders.
- for (const entity of subtree) {
+ for (const entity of getEntityTree(world, scene)) {
entity.add(Muted);
}
- // The motion system only samples parented entities, so the node's own
- // keyframes would be skipped as a top-level root. A synthetic group above
- // it owns the playhead instead and keeps the node an ordinary child. It
- // goes under the stage, or nothing below it would be walked at all.
- const clock = createEntity(world);
- clock.add(Group);
- clock.add(Playback);
- appendChild(world, clock, world.get(Root)!);
- appendChild(world, root, clock);
-
- recomputeAllTimeRanges(world);
-
- // Map "frame 0 = the node's first visible frame": the node keeps the time
- // it was authored at, so where it begins is the offset every requested
- // frame is counted from.
- const startFrame = computed.start[root.id()] ?? 0;
-
- // Everything in this world that owns a timeline clock, the synthetic one
- // above included.
- const clocks = [...world.query(Playback)];
-
- const seek = (frame: number) => {
- const stageFrame = startFrame + frame;
- const stageSeconds = framesToSeconds(stageFrame, frameRate);
-
- for (const entity of clocks) {
- computed.localTime[entity.id()] = stageFrame;
- computed.localTimeInSeconds[entity.id()] = stageSeconds;
- playback.playing[entity.id()] = true;
- }
-
- const delta = 1000 / frameRate;
- const time = world.get(Time)!;
- world.set(Time, { delta, now: time.now + delta });
-
- // Cull flags derived from a stale canvas/camera would make the motion
- // system skip entities and keep decoders idle — clear them every tick.
- for (const entity of subtree) {
- if (entity.has(Culled)) entity.remove(Culled);
- }
+ await warmupAssets(world);
- playbackSystem(world);
- };
+ const computed = store(world, Computed);
+ const playback = store(world, Playback);
- // Union an entity's world-space AABB into `bounds`, descending so children
- // that overflow a leaf's own rect still count — except where content is
- // clipped. Group bounds already aggregate their children.
- const measure = (entity: Entity, bounds: AABB): void => {
- if (entity.has(Hidden) || entity.has(IsMask)) return;
- if (computed.visibility[entity.id()] === 0) return;
-
- bounds.minX = Math.min(bounds.minX, worldBounds.minX[entity.id()]!);
- bounds.minY = Math.min(bounds.minY, worldBounds.minY[entity.id()]!);
- bounds.maxX = Math.max(bounds.maxX, worldBounds.maxX[entity.id()]!);
- bounds.maxY = Math.max(bounds.maxY, worldBounds.maxY[entity.id()]!);
-
- if (entity.has(ClipsContent)) return;
- for (const child of world.query(Or(Geometry, Group), ChildOf(entity))) {
- measure(child, bounds);
- }
- };
+ const frameRate = world.get(FrameRate)?.value ?? 30;
+ const sceneWidth = computed.width[sceneId]!;
+ const sceneHeight = computed.height[sceneId]!;
+ const sceneEnd = computed.end[sceneId]!;
- // Warm-up tick: group bounds aggregate from their children's local
- // matrices, which don't exist until the first transform walk has visited
- // them — measuring on that walk would union stale boxes.
- seek(config.frames[0]!);
- motionSystem(world);
- transformSystem(world);
-
- // Measure pass: run motion + transforms over every requested frame with an
- // identity camera and union the bounds, so an animated node stays fully
- // visible in a fixed-size output across all frames.
- const bounds: AABB = { minX: Infinity, minY: Infinity, maxX: -Infinity, maxY: -Infinity };
- for (const frame of config.frames) {
- seek(frame);
- motionSystem(world);
- transformSystem(world);
- measure(root, bounds);
- }
- assert(Number.isFinite(bounds.minX), 'Entity is not visible at any of the requested frames');
+ // Frame 0 is the export's frame 0: the workarea's first frame.
+ const workarea = scene.get(Workarea);
+ const workareaStart = workarea ? Math.max(0, Math.min(sceneEnd, workarea.start)) : 0;
+ const playheadStartSeconds = framesToSeconds(workareaStart, frameRate);
- await resolverSystem(world);
+ setActive(world, scene);
+ playback.playing[sceneId] = true;
+ playback.loop[sceneId] = false;
+ playback.speed[sceneId] = 1;
- const boundsWidth = Math.max(1, bounds.maxX - bounds.minX);
- const boundsHeight = Math.max(1, bounds.maxY - bounds.minY);
+ // Ascending and deduplicated: the render loop only ever moves the world
+ // forward, the way an export advances — never back.
+ const order = [...new Set(config.frames)].sort((a, b) => a - b);
- /** Re-target the output height; callers that lay frames out do this once measured. */
+ /** Re-target the output height; callers that lay frames out do this once sized. */
const resize = (height?: number) => {
- const scale = height ? height / boundsHeight : 1;
- canvas.width = Math.max(1, Math.round(boundsWidth * scale));
- canvas.height = Math.max(1, Math.round(boundsHeight * scale));
+ // The export's own scale and rounding, so a capture at a resolution is
+ // pixel-for-pixel the encoded frame at that resolution.
+ const scale = Math.round((height ?? sceneHeight) * 1e6 / sceneHeight) / 1e6;
+ canvas.width = Math.round(sceneWidth * scale / 2) * 2;
+ canvas.height = Math.round(sceneHeight * scale / 2) * 2;
world.set(RenderSurface, { resolution: scale });
};
resize(config.resolution);
- // Shift the measured box onto the canvas so the node is centered in view;
- // the camera translation is scaled by the surface resolution at render time.
- setCamera(world, { e: -bounds.minX, f: -bounds.minY });
let canceled = false;
const cancel = () => (canceled = true);
const render = async (): Promise<ImageExportResult> => {
try {
- const images: CapturedImage[] = [];
+ // Rendered in `order` and dealt back out in the requested order; a
+ // frame asked for twice is drawn once.
+ const images = new Map<number, CapturedImage>();
+
+ const frameDuration = 1 / frameRate;
- for (const frame of config.frames) {
+ for (const frame of order) {
if (canceled) {
return { type: 'canceled' };
}
- seek(frame);
+ const playheadSeconds = playheadStartSeconds + frame * frameDuration;
+
+ // The export's tick, verbatim: the encoder owns the playhead and
+ // writes both seconds + frames before each systems pass.
+ computed.localTimeInSeconds[sceneId] = playheadSeconds;
+ computed.localTime[sceneId] = Math.round(playheadSeconds * frameRate);
+ const time = world.get(Time)!;
+ world.set(Time, { delta: frameDuration * 1000, now: time.now + frameDuration * 1000 });
+
assetSystem(world);
+ playbackSystem(world);
await resolverSystem(world);
motionSystem(world);
+ // May be changed by a system
+ normalizeSceneTransform(world, sceneId);
transformSystem(world);
renderSystem(world);
- const stampFrame = startFrame + frame;
- images.push({
+ images.set(frame, {
base64: await toBase64Png(canvas),
- timecode: formatTimecode(framesToSeconds(stampFrame, frameRate), frameRate),
+ timecode: formatTimecode(playheadSeconds, frameRate),
});
}
- return { type: 'success', data: images };
+ return { type: 'success', data: config.frames.map((frame) => images.get(frame)!) };
} catch (e) {
return {
type: 'error',
@@ -206,7 +144,7 @@ export async function createImageEncoder(world: World, config: ImageEncoderConfi
render,
cancel,
resize,
- bounds: { width: boundsWidth, height: boundsHeight },
+ bounds: { width: sceneWidth, height: sceneHeight },
};
}
diff --git a/reference/README.md b/reference/README.md
index df15fcad..71fd8f9e 100644
--- a/reference/README.md
+++ b/reference/README.md
@@ -32,7 +32,7 @@ How the surface is divided:
- [`dapi open`](./open.md): launch the app and open (or create) a project folder, anywhere on disk
- [`dapi context`](./context.md): which project the app has open, where its playhead sits, its registered fonts, and where its generations stand
-- [`dapi capture`](./capture.md): render a node in isolation to a labelled contact sheet, or one PNG per position
+- [`dapi capture`](./capture.md): render frames of a scene, as an export would, to a labelled contact sheet or one PNG per position
- [`dapi check`](./check.md): check a node's subtree for structural mistakes (black-frame gaps, never-visible nodes, failed sources) and report subtree stats
### Media
diff --git a/reference/capture.md b/reference/capture.md
index 2761bb79..dd7cd1be 100644
--- a/reference/capture.md
+++ b/reference/capture.md
@@ -1,22 +1,26 @@
# `dapi capture <id> [-t, --time <time...>]`
-Renders a node in isolation at one or more timeline positions and merges them into **contact sheets**: up to 12 positions per PNG, each cell labelled with the timecode of the frame actually rendered and drawn as large as the sheet allows, so a few positions arrive as one high-resolution picture instead of a directory to open one by one. `--separate` writes a PNG per position instead. The node is drawn offscreen, tightly framed to its own bounds; siblings and overlapping scene content are not included, so capture a scene id to check composition. To grab a video asset's own pixels instead of the composited node, use [`media grab`](./media/grab.md).
+Renders single frames of a scene at one or more timeline positions and merges them into **contact sheets**: up to 12 positions per PNG, each cell labelled with the timecode of the frame actually rendered and drawn as large as the sheet allows, so a few positions arrive as one high-resolution picture instead of a directory to open one by one. `--separate` writes a PNG per position instead.
+
+Each frame is **the frame an export of that scene would encode**: the scene is re-rendered from a fresh mount at its own size, position `0` is the workarea's first frame, and the requested positions are evaluated in timeline order, forward only — the way an export advances — so a composition whose look depends on having played (an `<html>` node's own animation state, for instance) captures exactly as it exports. The tool for checking composition ("what plays at time T": layout, overlaps, text, timing) and for verifying frames before an export.
+
+Scenes only: a single element renders inside its scene, so capture the scene at the times the element plays. To grab a video asset's own pixels instead of a composited frame, use [`media grab`](./media/grab.md).
## Input
-- `<id>`: node id to capture (required) — the element's `id` attribute in the project's JSX (e.g. `hero`), or its position in the file for elements that have none. When two files use the same id, the `file:id` form (`index.tsx:hero`) settles it. Entity numbers are not accepted; they change on every recompile.
-- `-t, --time <time...>`: one or more positions to capture, relative to the node's start (`0` = its first visible frame), each a `Time` value (optional; default `0`)
-- `-S, --separate`: write one PNG per position instead of merging them into contact sheets (optional). Each is rendered at 720p height on a transparent background and named after its timecode (e.g. `01s12f.png`). The way to keep the alpha channel.
+- `<id>`: scene id to capture (required) — the scene's `id` attribute in the project's JSX (e.g. `intro`), or its position in the file when it has none. When two files use the same id, the `file:id` form (`index.tsx:intro`) settles it. Entity numbers are not accepted; they change on every recompile.
+- `-t, --time <time...>`: one or more positions to capture, relative to the export's first frame — the workarea's start, so `0` is the export's frame 0 — each a `Time` value (optional; default `0`)
+- `-S, --separate`: write one PNG per position instead of merging them into contact sheets (optional). Each is rendered at 720p height and named after its timecode (e.g. `01s12f.png`).
- `--per-sheet <n>`: positions per contact sheet, 1 to 12 (optional; default as many as fit). Fewer positions per sheet means a larger cell each. Sheets are balanced, so 13 positions become 7 + 6 rather than 12 + 1.
- `-o, --output <dir>`: directory to write the PNGs into (optional; default a fresh `dapi-capture-*` directory in the system temp directory, so runs never overwrite each other). Writing into the same directory twice overwrites images whose name matches; with `--separate`, requested times that land on the same frame share one file.
## Timecodes
-Cell labels, the `timecode` field, and the filenames all use the same stamp, which drops its zero segments: `08s10f` is 8 seconds and 10 frames, `01m05s` is 65 seconds, and the node's first visible frame is `0f`. Each segment carries its unit, so nothing is ambiguous once the empty ones are gone.
+Cell labels, the `timecode` field, and the filenames all use the same stamp, which drops its zero segments: `08s10f` is 8 seconds and 10 frames, `01m05s` is 65 seconds, and the export's first frame is `0f`. Each segment carries its unit, so nothing is ambiguous once the empty ones are gone.
## Layout
-A sheet never exceeds 2576x1456, the largest image a vision model reads at full detail. Within that budget the grid is the one that draws each frame largest, and the last row may be partially filled. Cells render at their own size rather than the flat 720p of `--separate`, so a few positions are sharper than a standalone capture and never coarser; a node smaller than 1080p tall is rendered up to that height, and nothing is rendered beyond it. Sheets are named after the span they cover, e.g. `0f-11s.png`. For a 16:9 scene the cell sizes are:
+A sheet never exceeds 2576x1456, the largest image a vision model reads at full detail. Within that budget the grid is the one that draws each frame largest, and the last row may be partially filled. Cells render at their own size rather than the flat 720p of `--separate`, so a few positions are sharper than a standalone capture and never coarser; a scene smaller than 1080p tall is rendered up to that height, and nothing is rendered beyond it. Sheets are named after the span they cover, e.g. `0f-11s.png`. For a 16:9 scene the cell sizes are:
| Positions | Grid | Per-frame |
|---|---|---|
@@ -25,7 +29,7 @@ A sheet never exceeds 2576x1456, the largest image a vision model reads at full
| 5-9 | 3x2, 3x3 | 850x478 |
| 10-12 | 4x3 | 636x357 |
-Sheets are opaque: the node's transparent background composites onto flat grey, and the gutters between cells use the same grey. Use `--separate` when the alpha channel itself matters.
+Sheets are opaque: a scene's transparent background composites onto flat grey, and the gutters between cells use the same grey.
## Output
@@ -39,4 +43,4 @@ A sheet's timecode is the span it covers; a single position's is its own. Sheets
## Errors
-Exits non-zero if no project is open (`No project open` — run `dapi open <dir>` first), the id is unknown, the id is ambiguous (two files use it — pass `file:id`), the id names an element inside a loop (capture its scene instead), the node has no timeline clock of its own (capture its scene instead), the node is not visible at any requested position, `--per-sheet` is outside 1 to 12, or a PNG can't be written.
+Exits non-zero if no project is open (`No project open` — run `dapi open <dir>` first), the id is unknown, the id is ambiguous (two files use it — pass `file:id`), the id names a node that is not a scene (the error names the scene to capture instead), `--per-sheet` is outside 1 to 12, or a PNG can't be written.
diff --git a/reference/check.md b/reference/check.md
index f448deda..e09a3f0d 100644
--- a/reference/check.md
+++ b/reference/check.md
@@ -29,7 +29,7 @@ One JSON object:
severity: "error" | "warning";
message: string;
node?: string; // source stamp of the offending node; absent for subtree-wide issues
- ranges?: Array<{ start: number; end: number }>; // seconds relative to the node's start — the clock `capture --time` uses
+ ranges?: Array<{ start: number; end: number }>; // seconds relative to the node's start — for a scene whose workarea starts at 0, the clock `capture --time` uses
}>;
}
```