Skip to content

The VS Code of video editing, built for agents.

TypeScript

Update capture functionality and documentation for node IDs

konstantin-paulus8eafe46f1696
diff --git a/README.md b/README.md
index a3fd0c1c..dcdd6ce4 100644
--- a/README.md
+++ b/README.md
@@ -171,7 +171,7 @@ dapi media filmstrip clip.mp4 # grid of video frames
dapi media waveform track.mp3 # audio waveform, silence flagged
dapi media transcribe interview.wav # timed, word-level transcript
dapi media listen interview.mp4 -p "what is said in the intro?" # ask a multimodal model
-dapi capture 42 # see the canvas itself
+dapi capture intro # see the canvas itself, by the node's id in the JSX
```
## CLI at a glance
diff --git a/apps/cli/src/cli-channels.ts b/apps/cli/src/cli-channels.ts
index e6a7943e..5b6161bf 100644
--- a/apps/cli/src/cli-channels.ts
+++ b/apps/cli/src/cli-channels.ts
@@ -58,7 +58,7 @@ export type TimecodedImage = { timecode: string; base64: string };
export type MediaFrameResult = TimecodedImage[];
export type CaptureRequest = {
- id: number;
+ id: string;
frames?: number[];
combine?: boolean;
perSheet?: number;
diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts
index ffe2c5ae..89aff7f5 100644
--- a/apps/cli/src/index.ts
+++ b/apps/cli/src/index.ts
@@ -283,22 +283,9 @@ async function mediaWaveform(ref: string, opts: MediaPreviewOptions): Promise<vo
}
}
-// Node ids are entity ids — integers. argv is always string, so the
-// conversion belongs here, at the one boundary, with a strict check. Coercing
-// app-side with Number() would silently accept "0x1f", "1e3", " 7 ", "" → 0.
-function parseNodeId(id: string): number {
- if (!/^\d+$/.test(id)) {
- console.error(`Invalid node id: ${JSON.stringify(id)} (expected a non-negative integer)`);
- process.exit(1);
- }
- return Number(id);
-}
-
type CaptureOptions = { time?: string[]; output?: string; separate?: boolean; perSheet?: string };
async function captureNode(id: string, opts: CaptureOptions): Promise<void> {
- const eid = parseNodeId(id);
-
const times = (opts.time ?? ["0"]).map((t) => parseTimeArg(t, "--time"));
const frames = times.map((t) => Math.round(t * TIME_FPS));
const perSheet = parsePerSheet(opts.perSheet, opts.separate);
@@ -307,7 +294,7 @@ async function captureNode(id: string, opts: CaptureOptions): Promise<void> {
mkdirSync(dir, { recursive: true });
try {
const images = await editor.capture.query(
- { id: eid, frames, combine: !opts.separate, perSheet },
+ { id, frames, combine: !opts.separate, perSheet },
GENERATE,
);
writeImages(images, dir);
@@ -620,7 +607,7 @@ program
.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\`.`,
)
- .argument("<id>", "node id to capture")
+ .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)`)
.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)")
diff --git a/apps/web/src/context/dapi/capture.ts b/apps/web/src/context/dapi/capture.ts
index d3fb2e4e..a5a623ef 100644
--- a/apps/web/src/context/dapi/capture.ts
+++ b/apps/web/src/context/dapi/capture.ts
@@ -2,7 +2,8 @@
* 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 { AdjustmentLayer, Geometry, Group, Scene } from "@diffusionstudio/runtime";
+import { AdjustmentLayer, Geometry, Group, Scene, Source } from "@diffusionstudio/runtime";
+import { parseSource } from "@diffusionstudio/jsx";
import {
composeSheet,
createImageEncoder,
@@ -28,15 +29,36 @@ function isNode(entity: Entity): boolean {
}
/**
- * The entity `id` names. An id is a koota entity value handed straight back,
- * so it only has to still be alive and still be something worth drawing.
+ * The entity `id` names. An id is a source id — the durable name an element
+ * carries in the project's JSX — not a koota entity number, which is minted
+ * anew on every recompile and so names nothing across calls. The bare id is
+ * enough while it names one element; `file:id` settles a tie between files,
+ * and a positional stamp (`index.tsx:12`) addresses elements that have no id.
*/
-function resolveNode(world: World, id: number): Entity {
- const entity = id as Entity;
- if (!Number.isInteger(id) || id < 0 || !world.has(entity) || !isNode(entity)) {
- throw new Error(`No such node: ${id}`);
+function resolveNode(world: World, id: string): Entity {
+ const matches = world.query(Source).filter((entity) => {
+ const stamp = entity.get(Source)!.value;
+ if (stamp === id) return true;
+ const parsed = parseSource(stamp);
+ return parsed !== undefined && String(parsed.locator) === id;
+ });
+ if (!matches.length) {
+ throw new Error(`No such node: "${id}" — node ids are the id attributes in the project's JSX`);
}
- return entity;
+
+ const nodes = matches.filter(isNode);
+ if (!nodes.length) {
+ throw new Error(`"${id}" is not a renderable node; capture a scene, group, clip, or adjustment layer`);
+ }
+ if (nodes.length > 1) {
+ const stamps = [...new Set(nodes.map((node) => node.get(Source)!.value))];
+ if (stamps.length === 1) {
+ // One element, many entities: a loop renders its body once per item.
+ throw new Error(`"${id}" renders ${nodes.length} times (it sits in a loop) — capture its scene instead`);
+ }
+ throw new Error(`"${id}" is ambiguous between ${stamps.map((stamp) => `"${stamp}"`).join(", ")} — use the file:id form`);
+ }
+ return nodes[0]!;
}
// Ceiling on the height a sheet cell renders a node at.
diff --git a/reference/capture.md b/reference/capture.md
index 910c1240..6bbc5073 100644
--- a/reference/capture.md
+++ b/reference/capture.md
@@ -4,7 +4,7 @@ Renders a node in isolation at one or more timeline positions and merges them in
## Input
-- `<id>`: node id to capture (required)
+- `<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.
- `--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.
@@ -39,4 +39,4 @@ A sheet's timecode is the span it covers; a single position's is its own. Sheets
## Errors
-Exits non-zero if the id is unknown, 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 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.
diff --git a/reference/report.md b/reference/report.md
index c3c73632..bcbb4703 100644
--- a/reference/report.md
+++ b/reference/report.md
@@ -15,7 +15,7 @@ Does not require the app to be running. If the app is down or unreachable, the r
## Options
- `-b, --body <text>`: what happened, in markdown: what you expected, what you got, and anything the diagnostics won't show.
-- `-c, --command <cmd...>`: the `dapi` command(s) that reproduce it, in order. Repeatable (`-c "dapi context" -c "dapi capture 5"`); rendered as a shell block under `## Repro`.
+- `-c, --command <cmd...>`: the `dapi` command(s) that reproduce it, in order. Repeatable (`-c "dapi context" -c "dapi capture intro"`); rendered as a shell block under `## Repro`.
- `--logs <n>`: trailing app log entries to attach (default: 50). `--logs 0` omits the section, and then the app is not contacted at all.
## Output
@@ -38,7 +38,7 @@ The title is the issue title; the body is assembled from the options and the dia
## Repro
```sh
-dapi capture 42
+dapi capture intro
```
## Environment