Skip to content

The VS Code of video editing, built for agents.

TypeScript

Refactor screenshot command to capture and update documentation

konstantin-paulus6199baf1ab44
diff --git a/README.md b/README.md
index 4e13bb95..c54202d7 100644
--- a/README.md
+++ b/README.md
@@ -66,7 +66,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 node screenshot # see the canvas itself
+dapi node capture # see the canvas itself
```
## CLI at a glance
@@ -76,7 +76,7 @@ dapi node screenshot # see the canvas itself
| `dapi open` | Launch the app, open a file, or turn a folder of footage into a project |
| `dapi context` | Summary of the open project: scenes, playhead, fonts |
| `dapi mount` | Compile and mount a JSX composition |
-| `dapi node …` | The scene graph: `ls`, `tree`, `grep`, `patch`, `insert`, `cp`, `rm`, `screenshot`, `render` |
+| `dapi node …` | The scene graph: `ls`, `tree`, `grep`, `patch`, `insert`, `cp`, `rm`, `capture`, `render` |
| `dapi asset …` | The media library: `add`, `ls`, `tree`, `mv`, `rm`, `export` |
| `dapi media …` | Inspect a file by id or path: `probe`, `grab`, `filmstrip`, `waveform`, `transcribe`, `listen` |
| `dapi project …` / `dapi folder …` / `dapi selection …` | Projects, library folders, canvas selection |
diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md
index e5927541..eb57f845 100644
--- a/apps/cli/reference/README.md
+++ b/apps/cli/reference/README.md
@@ -47,7 +47,7 @@ How the surface is divided:
- [`dapi node ls`](./node/ls.md): raw entity records
- [`dapi node tree`](./node/tree.md): an entity's subtree as nested JSON
- [`dapi node grep`](./node/grep.md): search entity records with a regex
-- [`dapi node screenshot`](./node/screenshot.md): capture a node as a PNG
+- [`dapi node capture`](./node/capture.md): capture a node as a PNG
- [`dapi node insert`](./node/insert.md): render a JSX module into an existing parent
- [`dapi node rm`](./node/rm.md): delete entities
- [`dapi node cp`](./node/cp.md): deep-clone nodes
diff --git a/apps/cli/reference/jsx/timing.md b/apps/cli/reference/jsx/timing.md
index bc621483..141f5501 100644
--- a/apps/cli/reference/jsx/timing.md
+++ b/apps/cli/reference/jsx/timing.md
@@ -31,4 +31,4 @@ The canonical internal unit is frames at **30 fps**; all formats are converted o
| `"MM:SS"` | `"02:30"` | Minutes and seconds. |
| `"HH:MM:SS"` | `"01:02:30"` | Hours, minutes, seconds. |
-CLI flags documented as taking a `Time` value (e.g. `--time` on [`node screenshot`](../node/screenshot.md) and [`media grab`](../media/grab.md)) accept the same formats.
+CLI flags documented as taking a `Time` value (e.g. `--time` on [`node capture`](../node/capture.md) and [`media grab`](../media/grab.md)) accept the same formats.
diff --git a/apps/cli/reference/media/grab.md b/apps/cli/reference/media/grab.md
index 3a564586..08a17403 100644
--- a/apps/cli/reference/media/grab.md
+++ b/apps/cli/reference/media/grab.md
@@ -1,6 +1,6 @@
# `dapi media grab <id|path>`
-Decodes one or more frames of a video asset at the given times and writes each to a PNG file; like [`node screenshot`](../node/screenshot.md), but grabs the asset's own pixels at full resolution (unlike `node screenshot`, which captures the composited canvas). Renders locally; no credits.
+Decodes one or more frames of a video asset at the given times and writes each to a PNG file; like [`node capture`](../node/capture.md), but grabs the asset's own pixels at full resolution (unlike `node capture`, which captures the composited canvas). Renders locally; no credits.
## Input
diff --git a/apps/cli/reference/node/screenshot.md b/apps/cli/reference/node/capture.md
similarity index 52%
rename from apps/cli/reference/node/screenshot.md
rename to apps/cli/reference/node/capture.md
index c6f9df02..fa9c1326 100644
--- a/apps/cli/reference/node/screenshot.md
+++ b/apps/cli/reference/node/capture.md
@@ -1,6 +1,6 @@
-# `dapi node screenshot [id] [-t, --time <time>]`
+# `dapi node capture [id] [-t, --time <time>]`
-Focuses the node on the canvas and captures a screenshot, written to a PNG file in the system temp directory. If `[id]` is omitted, captures the canvas (the active scene). To grab a video asset's own pixels at full resolution instead of the composited canvas, use [`media grab`](../media/grab.md).
+Focuses the node on the canvas and captures it, written to a PNG file in the system temp directory. If `[id]` is omitted, captures the canvas (the active scene). To grab a video asset's own pixels at full resolution instead of the composited canvas, use [`media grab`](../media/grab.md).
## Input
diff --git a/apps/cli/reference/selection/focus.md b/apps/cli/reference/selection/focus.md
index 0fdbb12e..8509b11c 100644
--- a/apps/cli/reference/selection/focus.md
+++ b/apps/cli/reference/selection/focus.md
@@ -1,6 +1,6 @@
# `dapi selection focus`
-Pans and zooms the canvas to fit the currently selected nodes in view, framing them with padding; the same focus [`node screenshot`](../node/screenshot.md) uses before it captures. No-op if nothing is selected (the canvas is left unchanged).
+Pans and zooms the canvas to fit the currently selected nodes in view, framing them with padding; the same focus [`node capture`](../node/capture.md) uses before it captures. No-op if nothing is selected (the canvas is left unchanged).
## Input
diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts
index b3e051ab..e5722b51 100644
--- a/apps/cli/src/index.ts
+++ b/apps/cli/src/index.ts
@@ -430,9 +430,9 @@ async function grepNodes(pattern: string, id: string | undefined, opts: NodeGrep
}
}
-type ScreenshotOptions = { time?: string };
+type CaptureOptions = { time?: string };
-async function nodeScreenshot(id: string | undefined, opts: ScreenshotOptions): Promise<void> {
+async function nodeCapture(id: string | undefined, opts: CaptureOptions): Promise<void> {
const eid = id !== undefined ? parseNodeIds([id])[0] : undefined;
let frame: number | undefined;
@@ -441,7 +441,7 @@ async function nodeScreenshot(id: string | undefined, opts: ScreenshotOptions):
}
try {
- const { base64 } = await editor.node.screenshot.query({ id: eid, frame });
+ const { base64 } = await editor.node.capture.query({ id: eid, frame });
const path = join(tmpdir(), `${randomUUID()}.png`);
writeFileSync(path, Buffer.from(base64, "base64"));
console.log(JSON.stringify({ path }));
@@ -1294,11 +1294,11 @@ node
.action((pattern: string, id: string | undefined, opts: NodeGrepOptions) => grepNodes(pattern, id, opts));
node
- .command("screenshot")
- .description(`Focus a node on the canvas and capture a screenshot as a PNG. Commonly useful to confirm what the viewer actually sees at a moment (layout, overlaps, text, timing), since the composited canvas is the truest "what plays at time T" check${docs("node/screenshot")}`)
+ .command("capture")
+ .description(`Focus a node on the canvas and capture it as a PNG. Commonly useful to confirm what the viewer actually sees at a moment (layout, overlaps, text, timing), since the composited canvas is the truest "what plays at time T" check${docs("node/capture")}`)
.argument("[id]", "node id to capture (optional; defaults to the canvas)")
.option("-t, --time <time>", `timeline position to record at — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: the current playhead)`)
- .action((id: string | undefined, opts: ScreenshotOptions) => nodeScreenshot(id, opts));
+ .action((id: string | undefined, opts: CaptureOptions) => nodeCapture(id, opts));
node
.command("insert")
diff --git a/apps/web/src/context/editor-api/api.tsx b/apps/web/src/context/editor-api/api.tsx
index 282c175e..a97bb8b6 100644
--- a/apps/web/src/context/editor-api/api.tsx
+++ b/apps/web/src/context/editor-api/api.tsx
@@ -12,7 +12,7 @@ import { handleAssetsAdd, handleAssetsList, handleAssetTree, handleAssetsDelete,
import { handleMediaProbe, handleMediaFrame, handleMediaTranscribe, handleMediaFilmstrip, handleMediaWaveform, handleMediaListen } from "./media";
import { handleFoldersList, handleFolderCreate, handleFolderRename, handleFoldersMove, handleFoldersDelete } from "./folders";
import { handleSelectionFocus, handleSelectionList, handleSelectionSet } from "./selection";
-import { handleNodeList, handleNodeTree, handleNodeGrep, handleNodeScreenshot, handleNodeDelete, handleNodePatch, handleNodeDuplicate, handleNodeRender } from "./node";
+import { handleNodeList, handleNodeTree, handleNodeGrep, handleNodeCapture, handleNodeDelete, handleNodePatch, handleNodeDuplicate, handleNodeRender } from "./node";
import { handleMount, handleNodeInsert } from "./mount";
import { handleProjectActive, handleProjectList, handleProjectCreate, handleProjectDelete, handleProjectOpen } from "./project";
import { handleModels } from "./models";
@@ -130,7 +130,7 @@ function createAppRouter({ getEngine, getUser, requireAuth, setParams }: AppRout
list: q(handleNodeList(getEngine)),
tree: q(handleNodeTree(getEngine)),
grep: q(handleNodeGrep(getEngine)),
- screenshot: q(handleNodeScreenshot(getEngine)),
+ capture: q(handleNodeCapture(getEngine)),
insert: m(handleNodeInsert(getEngine)),
delete: m(handleNodeDelete(getEngine)),
patch: m(handleNodePatch(getEngine)),
diff --git a/apps/web/src/context/editor-api/node.ts b/apps/web/src/context/editor-api/node.ts
index 97b71fba..3d65953e 100644
--- a/apps/web/src/context/editor-api/node.ts
+++ b/apps/web/src/context/editor-api/node.ts
@@ -284,7 +284,7 @@ function sceneOfNode(world: EngineWorld, eid: number): number | null {
return null;
}
-export function handleNodeScreenshot(engine: Accessor<Engine>) {
+export function handleNodeCapture(engine: Accessor<Engine>) {
return async ({ id, frame }: { id?: number; frame?: number }): Promise<{ base64: string }> => {
const e = engine();
const w = e.world;
@@ -304,7 +304,7 @@ export function handleNodeScreenshot(engine: Accessor<Engine>) {
c.Computed.localTimeInSeconds[sceneEid] = frame / w.frameRate;
}
- // Select the captured node so the screenshot shows its bounds.
+ // Select the captured node so the capture shows its bounds.
if (eid !== undefined) {
for (const sel of query(w, [c.Selected, Or(c.Geometry, c.Group, c.AdjustmentLayer)])) {
removeComponent(w, sel, c.Selected, false);
diff --git a/docs/assets.md b/docs/assets.md
index 80cf049b..7aacc6eb 100644
--- a/docs/assets.md
+++ b/docs/assets.md
@@ -46,7 +46,7 @@ Container and per-track technical metadata (format, duration, codec parameters),
dapi media grab <id|path> [-t <time...>] [-o <dir>]
```
-Decodes video frames at the given timestamps to PNGs, at the asset's full resolution. Prints `{ time, path }` per frame. (For the *composited* canvas instead of the raw asset, use `dapi node screenshot`.)
+Decodes video frames at the given timestamps to PNGs, at the asset's full resolution. Prints `{ time, path }` per frame. (For the *composited* canvas instead of the raw asset, use `dapi node capture`.)
### `media filmstrip`
@@ -91,6 +91,6 @@ dapi media filmstrip gbHJ # what does it look like o
dapi media transcribe gbHJ # what is said, and when?
dapi media listen gbHJ -p "what is said in the intro?"
dapi mount cut.tsx # compose the edit
-dapi node screenshot # verify visually
+dapi node capture # verify visually
dapi node render -o cut.mp4 # ship it
```
diff --git a/docs/cli.md b/docs/cli.md
index b63fe847..05248a46 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -103,10 +103,10 @@ dapi node grep <pattern> [id] [-i] [-t <types...>] [-k <components...>] [-l] [-c
Searches entity records by regex and prints matching entities with the components that matched. `[id]` scopes to a subtree. `-t` filters by node type, `-k` restricts to specific components, `-l` prints refs only, `-c` prints a count. Find nodes by name with `dapi node grep -k Name Title`; find every entity with a `Trim` component with `dapi node grep -k Trim .`.
-### `node screenshot`
+### `node capture`
```sh
-dapi node screenshot [id] [-t, --time <time>]
+dapi node capture [id] [-t, --time <time>]
```
Focuses the node (or the active scene, if omitted) and captures it to a PNG at the given timeline position. Prints `{ path }`.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 1dad9453..edd3e9a5 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -60,7 +60,7 @@ The `key` is the scene's stable identity: re-running the mount rebuilds that sce
Check the result visually:
```sh
-dapi node screenshot # prints { "path": "/tmp/….png" }
+dapi node capture # prints { "path": "/tmp/….png" }
```
## Render