Skip to content

The VS Code of video editing, built for agents.

TypeScript

Enhance node capture command with timestamp options and documentation updates

konstantin-paulus125a156fcbb6
diff --git a/apps/cli/reference/node/capture.md b/apps/cli/reference/node/capture.md
index 2ce8749b..f3902407 100644
--- a/apps/cli/reference/node/capture.md
+++ b/apps/cli/reference/node/capture.md
@@ -1,11 +1,12 @@
# `dapi node capture [id] [-t, --time <time...>]`
-Focuses the node on the canvas and captures it, writing one PNG to the system temp directory per timeline position. 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, writing one PNG to the system temp directory per timeline position. Each capture is stamped in the top-left with its `HH:MM:SS:FF` timestamp. 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
- `[id]`: node id (optional; defaults to the canvas)
- `-t, --time <time...>`: one or more timeline positions at which to record the node, each a `Time` value (optional; defaults to the current playhead position)
+- `--no-timestamp`: don't stamp each capture with its `HH:MM:SS:FF` timestamp label
## Output
diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts
index 92b8975e..51e72b20 100644
--- a/apps/cli/src/index.ts
+++ b/apps/cli/src/index.ts
@@ -430,7 +430,7 @@ async function grepNodes(pattern: string, id: string | undefined, opts: NodeGrep
}
}
-type CaptureOptions = { time?: string[] };
+type CaptureOptions = { time?: string[]; timestamp?: boolean };
async function nodeCapture(id: string | undefined, opts: CaptureOptions): Promise<void> {
const eid = id !== undefined ? parseNodeIds([id])[0] : undefined;
@@ -443,7 +443,7 @@ async function nodeCapture(id: string | undefined, opts: CaptureOptions): Promis
}
try {
- const shots = await editor.node.capture.query({ id: eid, frames });
+ const shots = await editor.node.capture.query({ id: eid, frames, timestamp: opts.timestamp });
for (const [i, { base64 }] of shots.entries()) {
const path = join(tmpdir(), `${randomUUID()}.png`);
writeFileSync(path, Buffer.from(base64, "base64"));
@@ -1299,9 +1299,10 @@ node
node
.command("capture")
- .description(`Focus a node on the canvas and capture it as a PNG, one per timeline position. 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")}`)
+ .description(`Focus a node on the canvas and capture it as a PNG, one per timeline position, each stamped in the top-left with its HH:MM:SS:FF timestamp. 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...>", `one or more timeline positions to record at — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: the current playhead)`)
+ .option("--no-timestamp", "don't stamp each capture with its HH:MM:SS:FF timestamp label")
.action((id: string | undefined, opts: CaptureOptions) => nodeCapture(id, opts));
node
diff --git a/apps/web/src/components/engine/utils/transcode.ts b/apps/web/src/components/engine/utils/transcode.ts
index 429c7c30..cebbcd7b 100644
--- a/apps/web/src/components/engine/utils/transcode.ts
+++ b/apps/web/src/components/engine/utils/transcode.ts
@@ -98,6 +98,30 @@ export function formatTimestamp(seconds: number, frameRate: number): string {
return [hh, mm, ss, frames].map((v) => String(v).padStart(2, '0')).join(':');
}
+// Draws a timestamp label into the top-left corner of a canvas: white text with
+// a black outline, sized relative to the canvas so it reads at any resolution.
+export function stampTimestampLabel(
+ ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
+ height: number,
+ label: string,
+): void {
+ const bandHeight = Math.max(20, Math.round(height * 0.06));
+ const fontSize = Math.round(bandHeight * 0.72);
+ const paddingLeft = Math.round(bandHeight * 0.4);
+ const y = paddingLeft + bandHeight / 2;
+
+ ctx.font = `normal ${fontSize}px sans-serif`;
+ ctx.textBaseline = 'middle';
+ ctx.textAlign = 'left';
+
+ ctx.lineJoin = 'round';
+ ctx.lineWidth = Math.max(2, Math.round(fontSize / 3));
+ ctx.strokeStyle = '#000';
+ ctx.strokeText(label, paddingLeft, y);
+ ctx.fillStyle = '#FFF';
+ ctx.fillText(label, paddingLeft, y);
+}
+
export type RenderedPreview = {
dataUrl: string;
};
diff --git a/apps/web/src/context/editor-api/media.ts b/apps/web/src/context/editor-api/media.ts
index 4ac2d427..97307558 100644
--- a/apps/web/src/context/editor-api/media.ts
+++ b/apps/web/src/context/editor-api/media.ts
@@ -5,7 +5,7 @@
import { ALL_FORMATS, BlobSource, CanvasSink, Input } from 'mediabunny';
import { ElectronFileHandle } from '@/lib/electron-file-handle';
import { trpc } from '@/lib/trpc';
-import { uploadBlob, filmstripAsset, waveformAsset, describeFileAsset, getAssetFile, formatTimestamp } from '@/components/engine';
+import { uploadBlob, filmstripAsset, waveformAsset, describeFileAsset, getAssetFile, formatTimestamp, stampTimestampLabel } from '@/components/engine';
import { assert } from '@/utils';
import {
transcodeForTranscription,
@@ -177,22 +177,7 @@ export function handleMediaFrame(engine: Accessor<Engine>) {
const ctx = wrapped.canvas.getContext("2d");
if (ctx && timestamp !== false) {
- const label = formatTimestamp(time, asset.frameRate)
- const bandHeight = Math.max(20, Math.round(wrapped.canvas.height * 0.06));
- const fontSize = Math.round(bandHeight * 0.72);
- const paddingLeft = Math.round(bandHeight * 0.4);
- const y = paddingLeft + bandHeight / 2;
-
- ctx.font = `normal ${fontSize}px sans-serif`;
- ctx.textBaseline = "middle";
- ctx.textAlign = "left";
-
- ctx.lineJoin = "round";
- ctx.lineWidth = Math.max(2, Math.round(fontSize / 3));
- ctx.strokeStyle = "#000";
- ctx.strokeText(label, paddingLeft, y);
- ctx.fillStyle = "#FFF";
- ctx.fillText(label, paddingLeft, y);
+ stampTimestampLabel(ctx, wrapped.canvas.height, formatTimestamp(time, asset.frameRate));
}
result[index] = { time, base64: await canvasToPngBase64(wrapped.canvas) };
diff --git a/apps/web/src/context/editor-api/node.ts b/apps/web/src/context/editor-api/node.ts
index abaa9446..06110620 100644
--- a/apps/web/src/context/editor-api/node.ts
+++ b/apps/web/src/context/editor-api/node.ts
@@ -18,6 +18,8 @@ import {
getEntityTree,
cloneSubtree,
serializeEntity,
+ formatTimestamp,
+ stampTimestampLabel,
} from "@/components/engine";
import { ChildOf } from "@/components/engine/components";
import { WorldDocument } from "@/utils/jsx";
@@ -285,7 +287,7 @@ function sceneOfNode(world: EngineWorld, eid: number): number | null {
}
export function handleNodeCapture(engine: Accessor<Engine>) {
- return async ({ id, frames }: { id?: number; frames?: number[] }): Promise<{ base64: string }[]> => {
+ return async ({ id, frames, timestamp }: { id?: number; frames?: number[]; timestamp?: boolean }): Promise<{ base64: string }[]> => {
const e = engine();
const w = e.world;
const c = w.components;
@@ -329,12 +331,32 @@ export function handleNodeCapture(engine: Accessor<Engine>) {
if (!(canvas instanceof HTMLCanvasElement)) {
throw new Error("Canvas is not ready");
}
- results.push({ base64: canvas.toDataURL("image/png").split(",")[1] ?? "" });
+
+ // The effective frame is the one we just seeked to, or the live playhead.
+ const shotFrame = frame ?? (sceneEid !== null ? c.Computed.localTime[sceneEid] : undefined);
+ results.push({ base64: stampedPng(canvas, timestamp !== false && shotFrame !== undefined ? formatTimestamp(shotFrame / w.frameRate, w.frameRate) : undefined) });
}
return results;
};
}
+// Composites the live canvas onto a fresh one so the timestamp label can't leak
+// into the on-screen editor, and returns it as base64 PNG (no data-url prefix).
+function stampedPng(source: HTMLCanvasElement, label: string | undefined): string {
+ const toBase64 = (c: HTMLCanvasElement) => c.toDataURL("image/png").split(",")[1] ?? "";
+ if (label === undefined) return toBase64(source);
+
+ const out = document.createElement("canvas");
+ out.width = source.width;
+ out.height = source.height;
+ const ctx = out.getContext("2d");
+ if (!ctx) return toBase64(source);
+
+ ctx.drawImage(source, 0, 0);
+ stampTimestampLabel(ctx, out.height, label);
+ return toBase64(out);
+}
+
export function handleNodeRender(engine: Accessor<Engine>) {
return async ({ id, output, config }: NodeRenderRequest): Promise<NodeRenderResult> => {
const e = engine();
diff --git a/docs/cli.md b/docs/cli.md
index f16641b7..af146c05 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -106,10 +106,10 @@ Searches entity records by regex and prints matching entities with the component
### `node capture`
```sh
-dapi node capture [id] [-t, --time <time...>]
+dapi node capture [id] [-t, --time <time...>] [--no-timestamp]
```
-Focuses the node (or the active scene, if omitted) and captures it to a PNG at each given timeline position. Prints one `{ time, path }` JSON line per capture.
+Focuses the node (or the active scene, if omitted) and captures it to a PNG at each given timeline position, each stamped in the top-left with its `HH:MM:SS:FF` timestamp (disable with `--no-timestamp`). Prints one `{ time, path }` JSON line per capture.
### `selection`