The VS Code of video editing, built for agents.
TypeScript
Update documentation and refine tool references
konstantin-paulus28135e68ccdb
diff --git a/README.md b/README.mdindex 37436f54..7672ab65 100644--- a/README.md+++ b/README.md@@ -61,7 +61,7 @@ Download the desktop app, it walks you through setting everything up:<a href="https://www.diffusion.studio/download"><img src="https://img.shields.io/badge/Download-Diffusion%20Studio-161616?style=for-the-badge&logo=apple&logoColor=F8F8F8&labelColor=000000" alt="Download Diffusion Studio" /></a>-Use with Claude Code, Codex, Cursor, Copilot, or Gemini CLI. `/editor` is the main skill you'll use. Ask for what you want in plain language. Behind it is `dapi`, the CLI that drives the app.+Use with Claude Code, Codex, Cursor, Copilot, or Gemini CLI. `/editor` is the main skill you'll use. Ask for what you want in plain language. Behind it is the app's MCP server, which the app registers with your agent; `dapi` is the same set of tools as a CLI.## Prompt examples@@ -127,7 +127,7 @@ Both were created by prompting. The compositions are published in [diffusionstud## Compositions as code-A project is a folder of that JSX: `dapi open <dir>` once, then edit the files. Saving recompiles the entry file and mounts it directly into the editor's ECS.+A project is a folder of that JSX: `open` a folder once (`dapi open <dir>` from a shell), then edit the files. Saving recompiles the entry file and mounts it directly into the editor's ECS.Every element carries an `id`, which is how the write-back finds its target: a rect dragged on the canvas, a clip trimmed on the timeline, or a retyped line lands as a prop on the element that authored it.@@ -176,7 +176,7 @@ Everything a mount produces stays a first-class editor node, so a person can pic## Seeing and hearing the media-Cutting footage requires understanding it. The CLI ships the inspection tools an agent needs to work with media it cannot watch:+Cutting footage requires understanding it. The app exposes the inspection tools an agent needs to work with media it cannot watch — as MCP tools, and as the same commands in a shell:```shdapi media probe clip.mp4 # container + codec metadata, like ffprobe@@ -188,6 +188,8 @@ dapi media listen interview.mp4 -p "what is said in the intro?" # ask a multimdapi capture intro -t 0 2 4 # the frames a render would produce, by scene id```+Each command is the MCP tool of the same name: `dapi media grab` is `media_grab`, `--per-sheet` is `perSheet`.+| Command | Purpose || --- | --- || `dapi open` | Launch the app and open (or create) a project folder, anywhere on disk |@@ -199,9 +201,9 @@ dapi capture intro -t 0 2 4 # the frames a render w| `dapi screenshot` / `dapi logs` | The app itself: capture the window, read recent console output || `dapi fetch` | Download a video from yt/tt/ig || `dapi whoami` | The authenticated account |-| `dapi report` | Report a bug in the CLI or the app: diagnostics bundled, filed as a GitHub issue via `gh` |+| `dapi report` | Report a bug in the tools or the app: diagnostics bundled, filed as a GitHub issue via `gh` |-Conventions throughout: single results are one JSON value, collections are JSON Lines, errors go to stderr with exit code `1`. Everything is built to be piped, grepped, and driven by a program.+Conventions throughout: every result is one JSON object, the same structured content the MCP tool returns; errors go to stderr with exit code `1`. Everything is built to be piped, grepped, and driven by a program.## Documentationdiff --git a/docs/mcp-server.md b/docs/mcp-server.mdindex 37946dac..b9058250 100644--- a/docs/mcp-server.md+++ b/docs/mcp-server.md@@ -199,9 +199,9 @@ The CLI ships inside the app bundle, so there is no compatibility window to main1. **Catalog.** Create `packages/dapi` with the tool catalog, `Time`, and `DapiError`, plus tests. Point the renderer handlers' request and result types at it. Delete `apps/cli/src/cli-channels.ts`; `apps/cli/src/protocol.ts` keeps only the handshake and envelope types of the current transport. No behaviour change. *Landed on `mcp-support`.*2. **Renderer.** Replace the tRPC router in `api.tsx` with one handler per tool behind a uniform `(args, ctx)` signature, validated by the catalog schemas, with an `AbortSignal` per call. Handlers return bytes; the WebSocket transport carries them as tagged base64 until step 3 replaces it. The CLI drops tRPC for a typed `call(name, input)` over the same catalog, so it keeps working at every step and its import of `apps/web` is gone. *Landed on `mcp-support`.*3. **Main.** Add `dapi/server.ts` with catalog registration, `dapi/renderer-calls.ts` with the in-flight map, `dapi/present.ts` for files and inline images, and the `logs`, `fonts`, `fetch` and `report` handlers. The socket transport lives in `@diffusionstudio/dapi/socket`, shared with the CLI, which becomes an MCP client over it in this step so it keeps working. Delete `cli-server.ts`. *Landed on `mcp-support`; verified by an in-process client/server round trip, not yet against the running app.*-4. **CLI.** Add `dapi mcp` and `dapi call`, and generate the wrappers from the catalog. Update `cli-install.ts` and the settings UI to offer MCP registration. *Landed on `mcp-support`, with two changes. `dapi call` was dropped. The CLI ships inside the app, so it always matches the app's catalog and every tool has a wrapper; a generic client would only duplicate what an MCP inspector on `dapi mcp` shows. `dapi mcp` is a byte pipe in `apps/cli/src/mcp-proxy.ts`; every wrapper's description and option help comes from the catalog through `apps/cli/src/help.ts`, which also validates the input locally with the same schemas, and prints the tool's structured content unchanged. And registration writes the HTTP URL, not the proxy: the app registers `http://127.0.0.1:3274/mcp` with every agent present on the machine that speaks Streamable HTTP (Claude Code, Codex, Cursor, Gemini CLI, Windsurf) and `<bundle>/Contents/Resources/cli/bin/dapi mcp` with the one that does not (Claude Desktop), each under the keys its config format uses (`apps/desktop/src/mcp-install.ts`, merge rules in `mcp-config.ts`), from the onboarding screen and a menu item. The PATH symlink install stays as its own onboarding row and menu item.*-5. **Docs.** Update the skill and regenerate `reference/`. Update the installation reference the skill points to.-6. **Cleanup.** Remove `CLI_WIRE`, the handshake types, and the `./protocol` and `./channels` exports from the CLI package.+4. **CLI.** Add `dapi mcp` and `dapi call`, and generate the wrappers from the catalog. Update `cli-install.ts` and the settings UI to offer MCP registration. *Landed on `mcp-support`, with two changes. `dapi call` was dropped. The CLI ships inside the app, so it always matches the app's catalog and every tool has a wrapper; a generic client would only duplicate what an MCP inspector on `dapi mcp` shows. `dapi mcp` is a byte pipe in `apps/cli/src/mcp-proxy.ts`; every wrapper's description and option help comes from the catalog, the input is validated locally with the same schemas, and the tool's structured content is printed unchanged. And registration writes the HTTP URL, not the proxy: the app registers `http://127.0.0.1:3274/mcp` with every agent present on the machine that speaks Streamable HTTP (Claude Code, Codex, Cursor, Gemini CLI, Windsurf) and `<bundle>/Contents/Resources/cli/bin/dapi mcp` with the one that does not (Claude Desktop), each under the keys its config format uses (`apps/desktop/src/mcp-install.ts`, merge rules in `mcp-config.ts`), from the onboarding screen and a menu item. The PATH symlink install stays as its own onboarding row and menu item.*+5. **Docs.** Update the skill and regenerate `reference/`. Update the installation reference the skill points to. *Landed on `mcp-support`. The knowledge base is written for both surfaces: tools are named as MCP lists them, and the naming rule that turns a tool into a `dapi` command (`media_grab` is `dapi media grab`, `perSheet` is `--per-sheet`) is stated once in `knowledge/reference/tools/README.md` and in the server instructions. Each tool page opens with the catalog description verbatim, the MCP name and CLI synopsis, and a table of the input fields with the flag that carries each; the prose after it is surface-neutral. The option tables are kept in step with the catalog by hand.*+6. **Cleanup.** Remove `CLI_WIRE`, the handshake types, and the `./protocol` and `./channels` exports from the CLI package. *Landed on `mcp-support`.*## Open questionsdiff --git a/knowledge/INSTRUCTIONS.md b/knowledge/INSTRUCTIONS.mdindex 873e3fad..742ac41e 100644--- a/knowledge/INSTRUCTIONS.md+++ b/knowledge/INSTRUCTIONS.md@@ -2,22 +2,23 @@ Diffusion Studio, a video editor, is running on this machine and you are connectProjects are folders of JSX; `open` a folder once, then write its files and save — the app recompiles and re-renders.+The tools are the whole API, and their descriptions are authoritative. The same tools exist as `dapi` commands for shells and scripts: `media_grab` is `dapi media grab`, a field like `perSheet` is `--per-sheet`, and the result is the same JSON either way. Each tool is documented once for both under `dapi://reference/tools/`.+---name: editordescription: >-- Understand, generate, and edit footage with Diffusion Studio via the `dapi`- CLI: analyze video/audio/images, generate them with AI, and compose video- compositions. Use for any media analysis, media generation, or video editing- task.+ Understand, generate, and edit footage with Diffusion Studio: analyze+ video/audio/images, generate them with AI, and compose video compositions.+ Use for any media analysis, media generation, or video editing task.path: dapi://skills/editor.md---name: watchdescription: >-- Watch and understand footage with Diffusion Studio via the `dapi` CLI: answer- questions about a video or audio file, summarize it, find- scenes and moments, pull quotes, and describe what happens and when. Use- whenever the user asks what's in a piece of footage, wants a summary or- recap, wants to locate a moment ("where does X happen", "find the scene- where..."), or needs a claim about a video or audio file checked.+ Watch and understand footage with Diffusion Studio: answer questions about a+ video or audio file, summarize it, find scenes and moments, pull quotes, and+ describe what happens and when. Use whenever the user asks what's in a piece+ of footage, wants a summary or recap, wants to locate a moment ("where does X+ happen", "find the scene where..."), or needs a claim about a video or audio+ file checked.path: dapi://skills/watch.md---diff --git a/knowledge/examples/README.md b/knowledge/examples/README.mdindex 5eb0fb02..4fd1c4d7 100644--- a/knowledge/examples/README.md+++ b/knowledge/examples/README.md@@ -3,7 +3,7 @@Self-contained compositions demonstrating the JSX API (see [reference/jsx](../reference/jsx/README.md)).Each one is a whole project entry file: it default-exports a component rendering a`<stage>` with one `<scene>` in it. To run one, copy it into a project folder as the-entry and open that folder:+entry and [`open`](../reference/tools/open.md) that folder — from a shell:```shcp examples/01-basics.tsx ~/Projects/basics/index.tsxdiff --git a/knowledge/guides/prompts/media-listen.md b/knowledge/guides/prompts/media-listen.mdindex 1362652e..75ce57cc 100644--- a/knowledge/guides/prompts/media-listen.md+++ b/knowledge/guides/prompts/media-listen.md@@ -1,6 +1,6 @@-# Writing prompts for `dapi media listen`+# Writing prompts for `media_listen`-`media listen` puts a multimodal model in front of an audio track and answers a prompt about it. A good prompt is specific about what you want and asks for timestamps so the answer lines up with the timeline. With no prompt it returns a general description; the examples below shape that into something more useful.+[`media_listen`](../../reference/tools/media/listen.md) puts a multimodal model in front of an audio track and answers a prompt about it. A good prompt is specific about what you want and asks for timestamps so the answer lines up with the timeline. With no prompt it returns a general description; the examples below shape that into something more useful.## ExamplesWhen you refer to a specific moment inside a prompt, use `MM:SS` (e.g. `01:15` for one minute fifteen seconds).diff --git a/knowledge/guides/walkthroughs/podcast-clip.md b/knowledge/guides/walkthroughs/podcast-clip.mdindex b9d75c63..8b9268a9 100644--- a/knowledge/guides/walkthroughs/podcast-clip.md+++ b/knowledge/guides/walkthroughs/podcast-clip.md@@ -8,7 +8,7 @@ Write the brief first: the source URL or file, how many clips are wanted, the ta## 2. Audio-only pass-Download the audio track alone. It is a fraction of the bytes, and the best moments are found without visuals.+Download the audio track alone with `fetch` (`audio: true`, `output: podcast.m4a`). It is a fraction of the bytes, and the best moments are found without visuals. From a shell:```bashdapi fetch <url> -a -o podcast.m4a@@ -16,34 +16,34 @@ dapi fetch <url> -a -o podcast.m4a## 3. Segment the audio-A three-hour track is too long for one analysis pass, so split it into segments and analyze each. Segments are **windows**, not files: `listen -s/-e` takes the range directly, and the timestamps it returns are relative to `-s`. Pick one of three ways to choose the boundaries:+A three-hour track is too long for one analysis pass, so split it into segments and analyze each. Segments are **windows**, not files: `media_listen` takes the range as `start`/`end`, and the timestamps it returns are relative to `start`. Pick one of three ways to choose the boundaries:-1. **Waveform.** `dapi media waveform` renders loudness over the whole track and returns the silent spans as second ranges. Cut segments at those spans — the boundaries land between thoughts instead of inside them.+1. **Waveform.** `media_waveform` renders loudness over the whole track and returns the silent spans as second ranges. Cut segments at those spans — the boundaries land between thoughts instead of inside them.2. **Naive.** Fixed 15–30 minute segments. Nothing to parse, and good enough because the analysis reports its own timestamps; a moment straddling a boundary is the only loss.3. **Source transcript.** Many platforms publish one (YouTube captions, show notes with chapter markers). Parse its timestamps and use chapters or topic shifts as boundaries — the cheapest option when it exists, since it needs no decoding at all.## 4. Find the clip-worthy moments-Run `dapi media listen` on each segment with a prompt that spells out the criteria and demands timestamps.+Run `media_listen` on each segment (`start` 15:00, `end` 45:00, and so on) with a prompt that spells out the criteria and demands timestamps:-```bash-dapi media listen podcast.m4a -s '15:00' -e '45:00' -p 'This is a podcast. Find the 3 most clip-worthy self-contained moments in this segment for a vertical social short. Criteria: a complete thought, punchline, or surprising revelation that works with NO prior context; roughly 25-35 seconds long; opens on a strong hook line and lands on a clean button. For each give: exact start and end timestamp (MM:SS, relative to this segment), who is speaking, a one-line summary of what is said, and a hook-strength rating 1-10. Be strict about self-containment.'+```text+This is a podcast. Find the 3 most clip-worthy self-contained moments in this segment for a vertical social short. Criteria: a complete thought, punchline, or surprising revelation that works with NO prior context; roughly 25-35 seconds long; opens on a strong hook line and lands on a clean button. For each give: exact start and end timestamp (MM:SS, relative to this segment), who is speaking, a one-line summary of what is said, and a hook-strength rating 1-10. Be strict about self-containment.```-Asking for a rating and a one-line summary is what makes the candidates comparable across segments. Add the segment's `-s` offset back to each returned timestamp to get absolute positions in the source, then pick the winner on hook strength and self-containment — not on how interesting the topic is.+Asking for a rating and a one-line summary is what makes the candidates comparable across segments. Add the segment's `start` offset back to each returned timestamp to get absolute positions in the source, then pick the winner on hook strength and self-containment — not on how interesting the topic is.## 5. Lock the exact cut pointsThe analysis gives you seconds; a clip needs the frame. Tighten both ends against the real audio:-- `dapi media transcribe` prints word-level start/end times (use ffmpeg to shorten). Put the in-point on the first word of the hook line and the out-point after the last word of the button.-- `dapi media waveform podcast.m4a -s <in> -e <out>` shows the breaths around those words, so you can open the in-point a beat early and let the out-point land on the silence after the line instead of clipping its tail.+- `media_transcribe` returns word-level start/end times (use ffmpeg to shorten). Put the in-point on the first word of the hook line and the out-point after the last word of the button.+- `media_waveform` with `start`/`end` around the cut shows the breaths around those words, so you can open the in-point a beat early and let the out-point land on the silence after the line instead of clipping its tail.## 6. Download the segment and lay it outNow fetch the video, and **download with padding** — a few seconds either side of the locked range — so the trim can still be nudged without downloading again.-`dapi media probe clip-raw.mp4` gives the source dimensions (a podcast is almost always 1920×1080) and confirms where the padded range actually starts, since a keyframe-aligned download can begin slightly early.+`media_probe` on the download gives the source dimensions (a podcast is almost always 1920×1080) and confirms where the padded range actually starts, since a keyframe-aligned download can begin slightly early.Give the node the **source's own aspect ratio**, scaled to the scene height, rather than the scene's box: the node is then wider than the scene, and the scene crops it. That geometry is what makes the framing in the next step possible.@@ -72,7 +72,7 @@ export default function Project() {}```-Save the file and get the trim right before framing or captions — `dapi capture <sceneId> -t 0` on the in-point and the out-point is the check.+Save the file and get the trim right before framing or captions — `capture` at the in-point and the out-point is the check.## 7. Frame the active speaker (optional if necessary)@@ -111,4 +111,4 @@ If the caption block lands on the speakers' faces, push it off with `offsetY` ra<captions preset="classic" verticalAlign="center" offsetY={420} />```-Capture a frame per caption line with `dapi capture` and check readability at delivery size — a caption over a mouth is worse than no caption.+Capture a frame per caption line with `capture` and check readability at delivery size — a caption over a mouth is worse than no caption.diff --git a/knowledge/guides/walkthroughs/talking-head.md b/knowledge/guides/walkthroughs/talking-head.mdindex 6f3e8436..3d384225 100644--- a/knowledge/guides/walkthroughs/talking-head.md+++ b/knowledge/guides/walkthroughs/talking-head.md@@ -10,9 +10,9 @@ Write the brief first. It records the source files, the target duration (or "keeThe transcript is the spine, so transcribe everything with speech.-- **Transcribe every video and any external audio.** `dapi media transcribe <id|path>` prints word-level start/end times — the times you cut on. Run it on each camera take and on any separate recording (a lav or interface track you will sync to).-- **Render the waveform to read the gaps.** `dapi media waveform <id|path>` marks silence in red and returns it as second ranges. A transcript marks only speech, so a gap in it can be silence *or* something to keep — a laugh, a breath. The waveform tells them apart: red is dead air to cut; a gap that still shows signal is performance to keep.-- **Resolve double takes visually.** The transcript shows repeated lines; usually the **last** take is the keeper. When takes read equally well, `dapi media grab -t` the first word of each and keep the sharpest — motion blur means a bad take.+- **Transcribe every video and any external audio.** `media_transcribe` returns word-level start/end times — the times you cut on. Run it on each camera take and on any separate recording (a lav or interface track you will sync to).+- **Render the waveform to read the gaps.** `media_waveform` marks silence in red and returns it as second ranges. A transcript marks only speech, so a gap in it can be silence *or* something to keep — a laugh, a breath. The waveform tells them apart: red is dead air to cut; a gap that still shows signal is performance to keep.+- **Resolve double takes visually.** The transcript shows repeated lines; usually the **last** take is the keeper. When takes read equally well, `media_grab` the first word of each and keep the sharpest — motion blur means a bad take.## 3. Lay out the A-roll@@ -70,9 +70,9 @@ Save the file — the app recompiles and re-renders it — and get the spine rig## 5. Verification-Run `dapi check <sceneId>` first: on a long timeline of many clips, a `sourceOut`/`start` that don't meet leaves a gap no sampled frame would land on, and the check names those spans outright.+Run `check` on the scene first: on a long timeline of many clips, a `sourceOut`/`start` that don't meet leaves a gap no sampled frame would land on, and the check names those spans outright.-Then the cut points, which matter most. Capture the **first frame of every clip** with `dapi capture <sceneId> -t ...` at each clip's `start`, and check the cut didn't land on a bad frame — motion blur is the usual tell; nudge `sourceIn` a few frames to a settled one. Reconcile against the brief, and re-check neighbouring cuts after any structural change.+Then the cut points, which matter most. Capture the **first frame of every clip** with `capture` at each clip's `start`, and check the cut didn't land on a bad frame — motion blur is the usual tell; nudge `sourceIn` a few frames to a settled one. Reconcile against the brief, and re-check neighbouring cuts after any structural change.## 6. Visual hook (optional)diff --git a/knowledge/reference/jsx/README.md b/knowledge/reference/jsx/README.mdindex 2a232ea1..6608dee3 100644--- a/knowledge/reference/jsx/README.md+++ b/knowledge/reference/jsx/README.md@@ -34,7 +34,7 @@ export default function Project() {| [scene.md](./scene.md) | `<scene>`: the clipped, playable frame and the timeline its children sit on || [elements.md](./elements.md) | Element-to-node mapping, coordinates and sizing, the shared property table || [group.md](./group.md), [rect.md](./rect.md), [text.md](./text.md), [video.md](./video.md), [image.md](./image.md), [audio.md](./audio.md) | Per-element props |-| [fonts.md](./fonts.md) | Fonts for `<text>` and HTML: local families, `dapi fonts` |+| [fonts.md](./fonts.md) | Fonts for `<text>` and HTML: local families, the `fonts` tool || [paints.md](./paints.md) | `<solidPaint>`, gradients, `<colorStop>`, `<imagePaint>` / `<videoPaint>` || [styles.md](./styles.md) | `<stroke>`, `<shadow>`, `<effect>`: outlines, drop shadows and filters || [html.md](./html.md) | `<html>`: reactive HTML children drawn into the box |@@ -62,7 +62,7 @@ Everything below runs in the app, on open and again on every save of a project f2. **Compile**: the entry file bundles with esbuild + `babel-preset-solid` in `universal` mode, so JSX compiles against the editor's renderer runtime instead of the DOM. `solid-js`, `solid-js/store` and `@diffusionstudio/jsx` are external — the app supplies its own instances; everything else is bundled. A compile error is reported and the canvas keeps the last good render.3. **Evaluate**: the app imports the module. Top-level code runs to completion. The module's **default export** is the project component.4. **Mount**: the component tree renders **directly into the world**. There is no staging tree: each element materializes as an entity as it is created, and the root `<stage>` is the one already there. Mounting is synchronous, and a throw part-way through leaves nothing behind — the document is disposed and the previous render stays on the canvas.-5. **Resolve**: every `src` resolves in the background — a path or asset id is loaded, a `generate.*` declaration is generated in dependency order, a `<captions>` without a `src` transcribes its scene. Each element renders a generating state until its asset lands, and an element that fails carries the reason (see [generate.md](./generate.md), [errors.md](./errors.md)). Non-blocking: the composition is on the canvas and editable while this runs, and [`dapi context`](../tools/context.md) reports where each generation stands.+5. **Resolve**: every `src` resolves in the background — a path or asset id is loaded, a `generate.*` declaration is generated in dependency order, a `<captions>` without a `src` transcribes its scene. Each element renders a generating state until its asset lands, and an element that fails carries the reason (see [generate.md](./generate.md), [errors.md](./errors.md)). Non-blocking: the composition is on the canvas and editable while this runs, and [`context`](../tools/context.md) reports where each generation stands.6. **Live**: the reactive graph keeps running for as long as the project is open — signals, effects, `useTicker` (see [lifecycle.md](./lifecycle.md)). Export, capture and the next open re-execute the same module.A save replaces the whole run: the old mount is disposed and the new one takes the stage. Scenes are rebuilt rather than accumulated, and the entities the previous render owned go with it.diff --git a/knowledge/reference/jsx/elements.md b/knowledge/reference/jsx/elements.mdindex 66309a4d..5be77819 100644--- a/knowledge/reference/jsx/elements.md+++ b/knowledge/reference/jsx/elements.md@@ -81,7 +81,7 @@ Every node accepts:| Prop | Type | Default | Meaning || ---- | ---- | ------- | ------- |-| `id` | `string` | stamped | How the element is addressed — by the editor writing back to it, by `dapi capture`, by [`syncTo`](./audio-sync.md). Written into your source if you leave it out (see [module.md](./module.md#ids)). |+| `id` | `string` | stamped | How the element is addressed — by the editor writing back to it, by `capture`, by [`syncTo`](./audio-sync.md). Written into your source if you leave it out (see [module.md](./module.md#ids)). || `ref` | `SceneNode` variable or `(node: SceneNode) => void` | none | SolidJS-style ref; receives the element's node when it is created. For `<surface>`/`<surfacePaint>` the node's `element` is the backing canvas (see [surface-paint.md](./surface-paint.md)). || `name` | `string` | none | Human-readable node name; what labels the node in the editor. || `x`, `y` | `number` | `0` | Position relative to the parent, px. |diff --git a/knowledge/reference/jsx/errors.md b/knowledge/reference/jsx/errors.mdindex 3dc3099d..5b2148f6 100644--- a/knowledge/reference/jsx/errors.md+++ b/knowledge/reference/jsx/errors.md@@ -4,9 +4,9 @@ Where each [pipeline](./README.md#pipeline) stage fails, and with what effect:| Stage | Where it surfaces | Effect || ----- | ----------------- | ------ |-| **Compile** (syntax, an unresolved import, a PascalCase composition tag, a control-flow component with no import) | A "Project failed to compile" toast, with the compiler's message; also on the app console ([`dapi logs`](../tools/logs.md)) | Nothing is remounted. The canvas keeps the last good render, so a project in the middle of an edit is never blanked. |+| **Compile** (syntax, an unresolved import, a PascalCase composition tag, a control-flow component with no import) | A "Project failed to compile" toast, with the compiler's message; also on the app console ([`logs`](../tools/logs.md)) | Nothing is remounted. The canvas keeps the last good render, so a project in the middle of an edit is never blanked. || **Evaluate / mount** (a throw at module scope or during render, a root that is not `<stage>`, a tag the host does not know, an element parented into its own subtree) | A "Project failed to render" toast with the thrown message | The half-built document is disposed — **nothing is left behind** — and the previous render stays on the canvas. |-| **Source resolution** (a path that does not exist, an unreachable URL, a per-model constraint on `aspectRatio` / `duration` / a feature flag, a caption with no audible audio in its scene) | The element on the canvas, and `generations` in [`dapi context`](../tools/context.md) | Per element, not per mount: everything else stays mounted and playable. The element stops showing its generating state and is left without a paint, carrying the reason — see below. |+| **Source resolution** (a path that does not exist, an unreachable URL, a per-model constraint on `aspectRatio` / `duration` / a feature flag, a caption with no audible audio in its scene) | The element on the canvas, and `generations` in [`context`](../tools/context.md) | Per element, not per mount: everything else stays mounted and playable. The element stops showing its generating state and is left without a paint, carrying the reason — see below. |Runtime errors are reported against the compiled module. Since types are stripped rather than checked, run `npx tsc --noEmit` in the project folder to catch what the compile will not.@@ -31,4 +31,4 @@ A composition that looks right in the viewport but captures black, frozen, or pa1. **A stateful animation seek.** anime.js records a tween's start values at the tween's *first* render, and captures/exports sample frames out of order — so a tween whose target was written to outside the timeline before its first render bakes that mutated state in as its starting values and replays it at every subsequent frame. Symptom: deterministic but *order-dependent* wrong frames — the same time renders when requested first and comes out wrong when requested after a later frame. See the caveat in [html.md](./html.md): give tweens explicit start values with `{ from, to }`, never write to or reset tween targets between seeks, and derive capture-critical values statelessly from `time()`.2. **`scale()` on a large or clipped subtree.** The rasterizer renders these as empty (see [html.md limitations](./html.md#requirements-and-limitations)). Symptom: one wrapper's entire subtree missing at every sampled time while siblings render. Fix: translate/opacity animation; `scale` only on small content-sized leaves without inner clips.3. **Fractional `opacity` nested under fractional `opacity`.** The rasterizer drops the ancestor's whole subtree while its opacity is between 0 and 1 if any descendant carries its own `opacity` < 1 (see [html.md limitations](./html.md#requirements-and-limitations)). Symptom: an element blank at every time its entrance/exit fade is mid-flight, rendering normally the moment the animated opacity reaches exactly 1 — deterministic per time and independent of sampling order. Fix: animate `opacity` on one level only; dim children with `rgba()`/`hsl()` alpha colors.-4. **`Error drawing <HtmlPaint> content: … No cached paint record for element`** in `dapi logs`, or html content missing from the first sampled frame(s) of a capture while later frames render: the offline draw raced the browser's paint snapshot for a freshly mounted host. Engine-side, not a composition bug — until the `whenReady` paint-snapshot fix ships, re-request the affected time or lead the capture with a throwaway frame.+4. **`Error drawing <HtmlPaint> content: … No cached paint record for element`** in `logs`, or html content missing from the first sampled frame(s) of a capture while later frames render: the offline draw raced the browser's paint snapshot for a freshly mounted host. Engine-side, not a composition bug — until the `whenReady` paint-snapshot fix ships, re-request the affected time or lead the capture with a throwaway frame.diff --git a/knowledge/reference/jsx/fonts.md b/knowledge/reference/jsx/fonts.mdindex d65fa0fc..edb0d727 100644--- a/knowledge/reference/jsx/fonts.md+++ b/knowledge/reference/jsx/fonts.md@@ -1,10 +1,10 @@# Fonts-Both text paths draw with fonts **installed on the machine**. Discover what is available with [`dapi fonts`](../tools/fonts.md) (filter by family, weight, or style); the active project's families are also on [`dapi context`](../tools/context.md) as `fontFamilies`. macOS resolves these families for both the native renderer and the browser, so there is nothing to bundle or load.+Both text paths draw with fonts **installed on the machine**. Discover what is available with [`fonts`](../tools/fonts.md) (filter by family, weight, or style); the active project's families are also on [`context`](../tools/context.md) as `fontFamilies`. macOS resolves these families for both the native renderer and the browser, so there is nothing to bundle or load.## Native `<text>`-Name a family on the [`<text>`](./text.md) element with `fontFamily`; pick the variant with `fontWeight` and `fontStyle`. The value must be a family present in `dapi fonts`; an unknown family falls back to the editor default.+Name a family on the [`<text>`](./text.md) element with `fontFamily`; pick the variant with `fontWeight` and `fontStyle`. The value must be a family listed by `fonts`; an unknown family falls back to the editor default.```tsx<text fontFamily="Inter" fontWeight={700} fontSize={128} textAlign="center" textBaseline="middle">@@ -22,9 +22,9 @@ In [`<html>`](./html.md) you style text with ordinary CSS, so **use a locally in</html>```-Remote web fonts work too (a Google Fonts `<link>`, or an `@font-face` with a `url()` source). However the cost is that every render then depends on the network and on the font host staying up, so a local family from [`dapi fonts`](../tools/fonts.md) is the safer default for anything you have to be able to re-render on demand.+Remote web fonts work too (a Google Fonts `<link>`, or an `@font-face` with a `url()` source). However the cost is that every render then depends on the network and on the font host staying up, so a local family from [`fonts`](../tools/fonts.md) is the safer default for anything you have to be able to re-render on demand.-If you want to pin an exact variant, declare an `@font-face` whose source is the CSS `local()` string that `dapi fonts` reports for that variant (never a `url()`):+If you want to pin an exact variant, declare an `@font-face` whose source is the CSS `local()` string that `fonts` reports for that variant (never a `url()`):```tsx<html width={700} height={110}>diff --git a/knowledge/reference/jsx/generate.md b/knowledge/reference/jsx/generate.mdindex 1c50607b..f2b7286a 100644--- a/knowledge/reference/jsx/generate.md+++ b/knowledge/reference/jsx/generate.md@@ -34,18 +34,18 @@ export default function Project() {Declarations are **pure**: calling `generate.*` validates its options and returns a ref; nothing is requested until an element carrying it mounts. A ref that is never used by a mounted element (directly or as an input to another asset) is never generated. Declarations may live at module scope or inside components.-Generation is **asynchronous and non-blocking**: the element is on the canvas immediately, showing a generating state, and its paint attaches when the asset lands. [`dapi context`](../tools/context.md) reports where each one stands — generating, failed with the reason, or done with the library path it landed as — and a declaration that fails leaves its element carrying an [`error`](./errors.md#failed-sources).+Generation is **asynchronous and non-blocking**: the element is on the canvas immediately, showing a generating state, and its paint attaches when the asset lands. [`context`](../tools/context.md) reports where each one stands — generating, failed with the reason, or done with the library path it landed as — and a declaration that fails leaves its element carrying an [`error`](./errors.md#failed-sources).## Declaration options-Run [`dapi models <type>`](../tools/models.md) to discover valid `model` ids and per-model constraints; [`dapi voices`](../tools/voices.md) lists voices.+[`models`](../tools/models.md) lists valid `model` ids and per-model constraints; [`voices`](../tools/voices.md) lists voices.```tstype AssetInput = string | AssetRef; // path, URL, asset id, or another declarationgenerate.image(opts: {prompt: string; // required- model?: string; // default: first model from `dapi models image`+ model?: string; // default: the first image model from `models`aspectRatio?: "1:1" | "4:3" | "3:4" | "16:9" | "9:16"; // default "16:9"refs?: AssetInput[]; // image referencesseed?: number; // reproducible generation@@ -53,7 +53,7 @@ generate.image(opts: {generate.video(opts: {prompt: string; // required- model?: string; // default: first model from `dapi models video`+ model?: string; // default: the first video model from `models`aspectRatio?: "1:1" | "4:3" | "3:4" | "16:9" | "9:16"; // default "16:9"duration?: number; // whole seconds; default 5audio?: boolean; // generate audio alongside; models with the `audio` feature only@@ -64,13 +64,13 @@ generate.video(opts: {generate.voice(opts: {prompt: string; // required: the text to speak- voice?: string; // default: first voice from `dapi voices`+ voice?: string; // default: the first voice from `voices`seed?: number;}): AssetRef;generate.audio(opts: {prompt: string; // required- model?: string; // default: first model from `dapi models audio`+ model?: string; // default: the first audio model from `models`duration?: number; // seconds; default 30 for music, the model's own default for sfxseed?: number;}): AssetRef;diff --git a/knowledge/reference/jsx/html.md b/knowledge/reference/jsx/html.mdindex df9df88a..112d31a3 100644--- a/knowledge/reference/jsx/html.md+++ b/knowledge/reference/jsx/html.md@@ -75,7 +75,7 @@ Like all paints, `<htmlPaint>` stacks with siblings in document order and clips## Persistence and export-The module is re-executed in every context: on reload, export, and [`dapi capture`](../tools/capture.md) the engine re-executes it and rebuilds the DOM content in that context. Exports wait for the browser's rendering update before sampling each frame, so the drawn HTML appears in the output; ticker-driven signals follow the playhead and animate frame-accurately. This assumes the module's structure is deterministic (`Math.random()`/`Date.now()` must not decide the shape of the tree).+The module is re-executed in every context: on reload, export, and [`capture`](../tools/capture.md) the engine re-executes it and rebuilds the DOM content in that context. Exports wait for the browser's rendering update before sampling each frame, so the drawn HTML appears in the output; ticker-driven signals follow the playhead and animate frame-accurately. This assumes the module's structure is deterministic (`Math.random()`/`Date.now()` must not decide the shape of the tree).## Requirements and limitationsdiff --git a/knowledge/reference/jsx/media.md b/knowledge/reference/jsx/media.mdindex 0b6a594a..3d68c203 100644--- a/knowledge/reference/jsx/media.md+++ b/knowledge/reference/jsx/media.md@@ -58,7 +58,7 @@ mkdir -p assets/b-roll && ln -s ~/Movies/drone.mp4 assets/b-roll/<video src="b-roll/drone.mp4" width={1920} height={1080} />```-Link rather than copy: the bytes stay where they are, the project holds nothing but a name for them, and the library still gets a portable path to reach them by. Give `ln -s` an absolute target — a relative link is read against the folder the link sits in, so it breaks as soon as the project moves. A directory of numbered frames is taken in whole, as one [image sequence](#image-sequences), rather than as a file each, and a link to that directory does the same. [`dapi fetch`](../tools/fetch.md) writes to disk and nothing else, so `-o assets/b-roll/` is how a download becomes an asset; `generate.*` results arrive under `assets/generated/` on their own.+Link rather than copy: the bytes stay where they are, the project holds nothing but a name for them, and the library still gets a portable path to reach them by. Give `ln -s` an absolute target — a relative link is read against the folder the link sits in, so it breaks as soon as the project moves. A directory of numbered frames is taken in whole, as one [image sequence](#image-sequences), rather than as a file each, and a link to that directory does the same. [`fetch`](../tools/fetch.md) writes to disk and nothing else, so an `output` under `assets/b-roll/` is how a download becomes an asset; `generate.*` results arrive under `assets/generated/` on their own.A link is the project's, and what it points at is not. Deleting a linked asset in the panel removes the link and stops there.diff --git a/knowledge/reference/jsx/module.md b/knowledge/reference/jsx/module.mdindex bb5de2e6..e204e442 100644--- a/knowledge/reference/jsx/module.md+++ b/knowledge/reference/jsx/module.md@@ -14,7 +14,7 @@ export default function Project() {}```-The component receives no props. [`dapi open <dir>`](../tools/open.md) opens the folder — creating it, and an `index.tsx` holding an empty stage, if it is not a project yet.+The component receives no props. [`open`](../tools/open.md) opens the folder — creating it, and an `index.tsx` holding an empty stage, if it is not a project yet.## The folder@@ -40,7 +40,7 @@ Every composition element carries an `id`, and the app stamps one onto every ele<rect id="k3f9x1" x={40} y={40} width={640} height={360} fill="#FF0055" />```-An id is what makes an element addressable: it is how an entity is traced back to the JSX that produced it, so a change made on the canvas can be written to the element it came from, and it is what [`dapi capture`](../tools/capture.md) takes to render one node. It is also how elements point at each other within a render — [`syncTo`](./audio-sync.md) names the id of the clip it aligns against.+An id is what makes an element addressable: it is how an entity is traced back to the JSX that produced it, so a change made on the canvas can be written to the element it came from, and it is what [`capture`](../tools/capture.md) takes to render one node. It is also how elements point at each other within a render — [`syncTo`](./audio-sync.md) names the id of the clip it aligns against.**Ids are yours to write.** Any string is valid, and `id="hero"` is worth more to read than anything minted. The stamp only fills in elements that have none, so renaming one by hand is safe. Ids are stripped at compile time and never reach the runtime as a prop; what survives is the stamp that carries them.diff --git a/knowledge/reference/jsx/scene.md b/knowledge/reference/jsx/scene.mdindex c7b029f8..1235b501 100644--- a/knowledge/reference/jsx/scene.md+++ b/knowledge/reference/jsx/scene.md@@ -18,7 +18,7 @@ A scene is the **clipped, playable frame** a composition is made in, and the onl| `fill` | `string` | none | Background fill, any CSS color; alpha is ignored. A scene without one is transparent, and exports with alpha. || `name` | `string` | none | Human-readable node name; what labels the scene in the editor. Recommended. || `volume` | `number` | `0` | Decibels on the scene's own bus, which everything in it mixes into — the master fader. `0` = unity, negative attenuates (`-6` ≈ half as loud), `-Infinity` = silence. A clip's own `volume` composes with this one. |-| `active` | `boolean` | absent | Whether this is the scene the playhead, the timeline and `dapi capture` operate on. |+| `active` | `boolean` | absent | Whether this is the scene the playhead, the timeline and `capture` operate on. || `workarea` | `[in, out] \| null` | `null` | The stretch of the scene that plays and exports, in any [time format](./timing.md#time-formats). || `selected` | `boolean` | absent | Whether the editor has the scene selected. || `timeline` | `[zoom, x, y]` | absent | Where the scene's timeline is looking: `zoom` in pixels per second of timeline, horizontal scroll in seconds, vertical scroll in pixels. Absent means the default zoom, at the beginning. |@@ -31,7 +31,7 @@ A scene also takes paints as children, exactly as a `<rect>` does (see [paints.mTwo rules the runtime holds for `active`: **at most one element is active**, and **only a root** — a direct child of `<stage>` — can be. A nested `active` is dropped, and when a file names more than one the last one rendered wins.-**Mark one scene `active` in every project you author.** Nothing activates on its own, and a project that opens with no active scene opens on an empty timeline: there is no playhead to scrub, `dapi capture` has nothing pointed at it, and an export has no scene to render. One scene, one `active`; with several, the one the project should open on — pair it with the [`<stage>`](./stage.md) `camera` that frames it.+**Mark one scene `active` in every project you author.** Nothing activates on its own, and a project that opens with no active scene opens on an empty timeline: there is no playhead to scrub, `capture` has nothing pointed at it, and an export has no scene to render. One scene, one `active`; with several, the one the project should open on — pair it with the [`<stage>`](./stage.md) `camera` that frames it.`workarea` is the exception among them: it is carried by the source the way `active` is (the timeline's brackets have nowhere else to go), but it is read wherever the file is, so **what it says is what comes out of a render**. Playback loops within it, and an export is of it and nothing else.diff --git a/knowledge/reference/jsx/shader-paint.md b/knowledge/reference/jsx/shader-paint.mdindex 389fb84f..9fbceed4 100644--- a/knowledge/reference/jsx/shader-paint.md+++ b/knowledge/reference/jsx/shader-paint.md@@ -96,7 +96,7 @@ Swapping `wgsl` recompiles the pipeline asynchronously; the media shows unshaded## Errors and limitations-- WGSL compile errors are reported on the app console ([`dapi logs`](../tools/logs.md)) with line numbers relative to your source; the paint renders as passthrough until a fix lands.+- WGSL compile errors are reported on the app console ([`logs`](../tools/logs.md)) with line numbers relative to your source; the paint renders as passthrough until a fix lands.- Pipeline compilation is asynchronous. Live playback may show the first frames unshaded; exports wait for compilation, so rendered output is always shaded.- One shader reads one media paint; shaders do not chain and do not read solid/gradient/html/surface paints or the composited stack (over those the shader runs procedurally and stacks on top).- For full custom pipelines (own vertex stage, WebGL, three.js) use [`<surface>`](./surface-paint.md), which owns its canvas outright.diff --git a/knowledge/reference/jsx/stage.md b/knowledge/reference/jsx/stage.mdindex 15b5a7cb..f69900b9 100644--- a/knowledge/reference/jsx/stage.md+++ b/knowledge/reference/jsx/stage.md@@ -42,4 +42,4 @@ The stage takes no timing, no transform and no paints — it is not a node, it iA root's place on the canvas is its own `x`/`y`, in the same document space the camera matrix moves through. Roots that do not say where they sit all sit at the origin, on top of each other; give each after the first an `x` clear of the ones before it, as the example above does.-Which scene the playhead, the timeline and [`dapi capture`](../tools/capture.md) are pointed at is a scene's `active`, not the stage's business. At most one scene carries it, and only a direct child of `<stage>` can.+Which scene the playhead, the timeline and [`capture`](../tools/capture.md) are pointed at is a scene's `active`, not the stage's business. At most one scene carries it, and only a direct child of `<stage>` can.diff --git a/knowledge/reference/jsx/surface-paint.md b/knowledge/reference/jsx/surface-paint.mdindex 415072e4..6ee46bae 100644--- a/knowledge/reference/jsx/surface-paint.md+++ b/knowledge/reference/jsx/surface-paint.md@@ -126,7 +126,7 @@ Like all paints it stacks with siblings in document order and clips to the paren## Persistence and export-The module is re-executed in every context, so the drawing is reproducible rather than ephemeral: on reload, export, and [`dapi capture`](../tools/capture.md) the engine re-runs your drawing code against a fresh canvas driven by that context's playhead, so ticker surfaces animate in exports. The bitmap itself is not stored; your code reproduces it. This assumes the module's structure is deterministic (`Math.random()`/`Date.now()` must not decide the shape of the tree; using them inside a draw effect is fine).+The module is re-executed in every context, so the drawing is reproducible rather than ephemeral: on reload, export, and [`capture`](../tools/capture.md) the engine re-runs your drawing code against a fresh canvas driven by that context's playhead, so ticker surfaces animate in exports. The bitmap itself is not stored; your code reproduces it. This assumes the module's structure is deterministic (`Math.random()`/`Date.now()` must not decide the shape of the tree; using them inside a draw effect is fine).**Async setup has to be held.** Because that re-execution is a fresh mount, a model, a texture, or a device your drawing waits for is fetched again there — and sampling begins as soon as the render returns, so the first frames are written from a canvas nothing has drawn into yet. Hand the promise to [`useTicker().hold`](./lifecycle.md#hold) and those frames wait for it:diff --git a/knowledge/reference/jsx/text.md b/knowledge/reference/jsx/text.mdindex 8e9d1fe0..1ffc6bb2 100644--- a/knowledge/reference/jsx/text.md+++ b/knowledge/reference/jsx/text.md@@ -18,7 +18,7 @@ All [common props](./elements.md#common-props), plus:| ---- | ---- | ------- | ------- || children | `string` (or expressions resolving to strings) | **required** | The text content, alongside any `<textRange>`, paint, `<stroke>`, `<shadow>`, `<effect>`, `<animation>` and `<keyframeTrack>` children. || `color` | `string` | none | The glyph color; any CSS color, alpha ignored (use `opacity`). Drawn beneath any paint children (see [paints.md](./paints.md)); animate it with a `color` [keyframe track](./keyframes.md). A text with neither `color` nor a paint child draws no glyphs. |-| `fontFamily` | `string` | `Inter` | A family available on the machine ([`dapi fonts`](../tools/fonts.md)); see [fonts.md](./fonts.md). |+| `fontFamily` | `string` | `Inter` | A family available on the machine ([`fonts`](../tools/fonts.md)); see [fonts.md](./fonts.md). || `fontSize` | `number` | `16` | Px. || `fontWeight` | `number \| "normal" \| "bold"` | `"normal"` | CSS weights `100`–`900`. || `fontStyle` | `"normal" \| "italic" \| "oblique"` | `"normal"` | |diff --git a/knowledge/reference/tools/README.md b/knowledge/reference/tools/README.mdindex ef0f979c..c2efeafd 100644--- a/knowledge/reference/tools/README.md+++ b/knowledge/reference/tools/README.md@@ -1,77 +1,70 @@-# dapi CLI Reference+# Tool reference-Reference for `dapi`, the Diffusion Studio CLI. Every canvas and project command talks to the running app over a local socket. Responses are JSON written to stdout; errors are human-readable messages on stderr with a non-zero exit.+Diffusion Studio exposes one set of tools, reachable two ways:-Each feature command has its own file (linked below). The JSX code syntax specified in [jsx/](../jsx/README.md) is **pseudo-SVG**, mirroring SVG's shape-and-paint model with the editor's own tags and props rather than the SVG spec.+- **MCP.** The running app serves an MCP server at `http://127.0.0.1:3274/mcp` (Streamable HTTP) and on a local socket; `dapi mcp` pipes that socket to stdio for clients that only spawn processes. A connected agent gets every tool in `tools/list`, with the descriptions on these pages, this knowledge base as resources under `dapi://`, and two live resources, `dapi://context` and `dapi://logs`.+- **CLI.** `dapi`, the command-line client shipped with the app, wraps every tool as a command for shells, scripts and CI. `dapi <command> --help` prints the same description and the same field help.-A project is a folder of that JSX, and **the source is the document**: the app compiles the entry file and renders every element into an editable node, and edits made on the canvas are written back to the element that authored them. So the loop is `dapi open <dir>` once, then edit the files — there is no command that pushes content into the app. What the commands do is read the running app ([`context`](./context.md), [`capture`](./capture.md), [`logs`](./logs.md)), inspect media, and list what a declaration may name.+Both validate against the same schemas and return the same result, so each tool is documented once, on its own page. The catalog behind all three (server, CLI, these pages) lives in `packages/dapi`.-## Groups+The JSX code syntax specified in [jsx/](../jsx/README.md) is **pseudo-SVG**, mirroring SVG's shape-and-paint model with the editor's own tags and props rather than the SVG spec. A project is a folder of that JSX, and **the source is the document**: the app compiles the entry file and renders every element into an editable node, and edits made on the canvas are written back to the element that authored them. So the loop is [`open`](./open.md) once, then edit the files — there is no tool that pushes content into the app. What the tools do is read the running app ([`context`](./context.md), [`capture`](./capture.md), [`logs`](./logs.md)), inspect media, and list what a declaration may name.-**Top-level:** [`whoami`](./whoami.md), [`logs`](./logs.md), [`screenshot`](./screenshot.md), [`report`](./report.md), [`context`](./context.md) (alias `ctx`), [`capture`](./capture.md), [`check`](./check.md), [`export`](./export.md), [`models`](./models.md), [`voices`](./voices.md), [`fonts`](./fonts.md), [`fetch`](./fetch.md).+## Names-| Group | Alias | Scope |-| ----- | ----- | ----- |-| `media` | `m` | Inspect a media file by path, without adding it to the project. Local files and URLs work with or without an open project; library paths need one. |+A tool is named as MCP lists it, and the CLI spelling follows from the name:-How the surface is divided:--- AI asset generation (image / video / speech / audio) is declared in the project module (`generate.*`, see [jsx/generate.md](../jsx/generate.md)). `models` and `voices` list what those declarations can reference.-- Inspecting an existing asset (probe / transcribe / listen / filmstrip / waveform / grab) lives under `media`.--## Commands--### App--- [`dapi whoami`](./whoami.md): print the authenticated account-- [`dapi logs`](./logs.md): recent console output from the running app-- [`dapi screenshot`](./screenshot.md): capture the entire application window as a PNG-- [`dapi report`](./report.md): file a GitHub issue about a bug in the CLI or the app, with diagnostics attached+- `_` in a tool name is a space on the command line: `media_grab` is `dapi media grab`. The `media` group is also `m`.+- A tool's first field is the positional argument: `capture`'s `id` is `dapi capture <id>`.+- Every other field is an option in kebab-case: `perSheet` is `--per-sheet`, `separate` is `--separate`. Short forms are listed on each page.+- Times are written the same way everywhere: seconds (`1.5`), frames at the project's rate (`45f`), or a clock string (`1:30`, `00:01:30`). Times in **results** are plain seconds.-### Document+## Results-- [`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 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-- [`dapi export`](./export.md): encode a scene to a video file, with the settings saved in the project's `package.json`+Every tool returns one JSON object, its *structured content*. Over MCP that is the result's `structuredContent`, repeated as a text block for clients that ignore structured content; the CLI prints it to stdout, unchanged. Tools that render images (`capture`, `media_grab`, `media_filmstrip`, `media_waveform`, `screenshot`) write PNGs to disk and return their paths; over MCP a result of at most four images, none over a megabyte, also carries them inline as image content, so a contact sheet arrives in context without opening anything.-### Media+## Errors-- [`dapi media probe`](./media/probe.md): container and track metadata-- [`dapi media transcribe`](./media/transcribe.md): timed speech transcript-- [`dapi media grab`](./media/grab.md): decode video frames to a labelled contact sheet, or one PNG per frame-- [`dapi media filmstrip`](./media/filmstrip.md): grid of video frames as a PNG-- [`dapi media waveform`](./media/waveform.md): audio waveform PNG with silence highlighting-- [`dapi media listen`](./media/listen.md): AI description of an audio track+A failure is a sentence written to be read, e.g. `No project open — run open first`. Over MCP it arrives as a tool result with `isError: true`, not as a protocol error; the CLI prints it to stderr and exits `1`. Each page's Errors section lists what the tool fails on; only the delivery differs by surface.-### Generation reference+Every tool runs inside the app, so the app has to be running. Over MCP that is a given — the connection is to the app. From a shell, `dapi open` launches it (macOS) or surfaces the running instance; every other command prints a launch instruction and exits `1` while the app is down.-- [`dapi models`](./models.md): list generation models and constraints-- [`dapi voices`](./voices.md): list speech voices+## The tools-### Fonts+| Tool | CLI | Does |+| --- | --- | --- |+| [`open`](./open.md) | `dapi open` | Open project |+| [`context`](./context.md) | `dapi context` | App context |+| [`capture`](./capture.md) | `dapi capture` | Capture frames |+| [`check`](./check.md) | `dapi check` | Check structure |+| [`export`](./export.md) | `dapi export` | Export scene |+| [`media_probe`](./media/probe.md) | `dapi media probe` | Probe media |+| [`media_grab`](./media/grab.md) | `dapi media grab` | Grab frames |+| [`media_transcribe`](./media/transcribe.md) | `dapi media transcribe` | Transcribe speech |+| [`media_filmstrip`](./media/filmstrip.md) | `dapi media filmstrip` | Filmstrip preview |+| [`media_waveform`](./media/waveform.md) | `dapi media waveform` | Waveform preview |+| [`media_listen`](./media/listen.md) | `dapi media listen` | Listen to audio |+| [`models`](./models.md) | `dapi models` | Generation models |+| [`voices`](./voices.md) | `dapi voices` | Speech voices |+| [`whoami`](./whoami.md) | `dapi whoami` | Signed-in account |+| [`logs`](./logs.md) | `dapi logs` | App logs |+| [`screenshot`](./screenshot.md) | `dapi screenshot` | Window screenshot |+| [`fonts`](./fonts.md) | `dapi fonts` | Local fonts |+| [`fetch`](./fetch.md) | `dapi fetch` | Fetch video |+| [`report`](./report.md) | `dapi report` | Report a bug |-- [`dapi fonts`](./fonts.md): list local fonts--### Download+How the surface is divided:-- [`dapi fetch`](./fetch.md): download a video with yt-dlp (installed separately)+- **The project loop.** [`open`](./open.md) a folder, edit its JSX, [`context`](./context.md) for what the source cannot say, [`capture`](./capture.md) and [`check`](./check.md) to verify, [`export`](./export.md) when asked.+- **Media inspection** (`media_*`): a file by path, without adding it to the project. Absolute paths and URLs work with or without an open project; library paths (`b-roll/clip.mp4`) need one.+- **What a declaration may name.** [`models`](./models.md), [`voices`](./voices.md), [`fonts`](./fonts.md). Generation itself is declared in the project module (`generate.*`, see [jsx/generate.md](../jsx/generate.md)); no tool generates.+- **The app and the machine.** [`whoami`](./whoami.md), [`logs`](./logs.md), [`screenshot`](./screenshot.md), [`report`](./report.md), and [`fetch`](./fetch.md) for downloads.## Shared types```tsAsset = { id: string; path: string; type: string } // asset ids are content hashes; `path` is the library path-Time = number | `${number}f` | "MM:SS" // seconds, frames at 30 fps ("45f"), or a clock string; see jsx/timing.md+Time = number | `${number}f` | "MM:SS" // seconds, frames at the project's rate ("45f"), or a clock string; see jsx/timing.mdNodeId = string // an element's `id` in the project's JSX; `file:id` when two files collide```-Time inputs take the `Time` format unless noted otherwise. Times in **outputs** are plain seconds.--## Conventions--- **Stdout is the tool's result.** Every command prints one JSON object: the structured content the app's MCP tool returns, exactly what an agent connected to the app's MCP server receives. No command reshapes it.-- **Unix-style names are canonical.** Commands without a natural Unix equivalent (`context`, `whoami`) keep their descriptive names.-- **Stderr:** human-readable error messages.-- **Exit codes:** `0` on success, `1` on any error (missing file, app not running, invalid input, IPC error).-- **App must be running:** every command except `fonts` and `fetch` talks to the open Diffusion Studio instance. If the app isn't running, the CLI prints an instruction to launch it and exits `1`. `report` is the one command that reads from the app but tolerates its absence, recording it in the issue instead of failing.+Time inputs take the `Time` format unless noted otherwise.diff --git a/knowledge/reference/tools/capture.md b/knowledge/reference/tools/capture.mdindex 47a30876..3546987b 100644--- a/knowledge/reference/tools/capture.md+++ b/knowledge/reference/tools/capture.md@@ -1,18 +1,29 @@-# `dapi capture <id> [-t, --times <time...>]`+# capture-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.+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: true 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.-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).+| | |+| --- | --- |+| MCP tool | `capture` |+| CLI | `dapi capture <id> [options]` |## Input-- `<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, --times <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.+| Field | Type | CLI | Description |+| --- | --- | --- | --- |+| `id` | `string`, required | `<id>` | scene id from the project's JSX, or `file:id` when two files use the same id |+| `times` | `Time[]` | `-t, --times <time...>` | 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]) |+| `separate` | `boolean` | `-S, --separate` | write one image per position instead of merging them into contact sheets of up to 12 cells, each labelled with its timecode |+| `perSheet` | `integer` | `--per-sheet <n>` | positions per contact sheet, 1-12; fewer means a larger cell each (default: as many as fit) |+| `output` | `string` | `-o, --output <dir>` | absolute directory to write the PNGs into (default: a fresh directory under the system temp dir) |++## Frames++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.++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).++With `separate`, each position is rendered at 720p height and named after its timecode (e.g. `01s12f.png`). Without an `output` directory the images land in a fresh `dapi-capture-*` directory under 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@@ -20,7 +31,7 @@ Cell labels, the `timecode` field, and the filenames all use the same stamp, whi## 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 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:+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 ||---|---|---|@@ -33,14 +44,14 @@ Sheets are opaque: a scene's transparent background composites onto flat grey, a## Output-One JSON object with one entry per written image: a contact sheet by default, a position with `--separate`.+One JSON object with one entry per written image: a contact sheet by default, a position with `separate`.```ts{ images: Array<{ timecode: string; path: string }> } // e.g. { "images": [{ "timecode": "0f-01s15f", "path": "/tmp/dapi-capture-3f2c1a8e/0f-01s15f.png" }] }```-A sheet's timecode is the span it covers; a single position's is its own. Sheets come in timeline order, and their cells in the order the positions were requested in.+A sheet's timecode is the span it covers; a single position's is its own. Sheets come in timeline order, and their cells in the order the positions were requested in. Over MCP, up to four images of at most a megabyte each also arrive inline.## 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 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.+Fails when no project is open (`No project open` — run [`open`](./open.md) 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), `perSheet` is outside 1 to 12 or combined with `separate`, or a PNG can't be written.diff --git a/knowledge/reference/tools/check.md b/knowledge/reference/tools/check.mdindex 79ff5599..cd6e4bbe 100644--- a/knowledge/reference/tools/check.md+++ b/knowledge/reference/tools/check.md@@ -1,12 +1,21 @@-# `dapi check <id>`+# check-Checks a node's subtree for obvious structural mistakes, without rendering: spans of the node's play window 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. Alongside the issues it reports subtree stats — node count by kind, nesting depth, and played duration — so it doubles as a quick structural summary of a scene.+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). Times in issue ranges are seconds relative to the node's start — for a scene whose workarea starts at 0, the same clock capture uses. Structural only: a scheduled clip can still render black (dark footage, content smaller than the canvas), so confirm suspicious spans visually with capture.-The analysis is structural, from the resolved timeline alone, so it is instant and costs no credits — and it can only say *nothing is scheduled*, not *the frame is black*. A scheduled clip can still render black (dark footage, content smaller than the canvas, a transparent asset); confirm suspicious spans visually with [`capture`](./capture.md) at a time inside the range.+| | |+| --- | --- |+| MCP tool | `check` |+| CLI | `dapi check <id>` |## Input-- `<id>`: node id to check (required) — the element's `id` attribute in the project's JSX, or `file:id` when two files use the same id. Same resolution rules as [`capture`](./capture.md).+| Field | Type | CLI | Description |+| --- | --- | --- | --- |+| `id` | `string`, required | `<id>` | node id from the project's JSX, or `file:id` when two files use the same id |++## What it can and cannot see++The analysis is structural, from the resolved timeline alone, so it is instant and costs no credits — and it can only say *nothing is scheduled*, not *the frame is black*. A scheduled clip can still render black (dark footage, content smaller than the canvas, a transparent asset); confirm suspicious spans visually with [`capture`](./capture.md) at a time inside the range. Alongside the issues it reports subtree stats — node count by kind, nesting depth, and played duration — so it doubles as a quick structural summary of a scene. The `id` resolves by the same rules as [`capture`](./capture.md)'s.## What counts as visual coverage@@ -29,7 +38,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 — for a scene whose workarea starts at 0, the clock `capture --times` 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` positions use}>;}```@@ -45,6 +54,10 @@ One JSON object:| `transparent` | warning | A node with static opacity 0 (nodes with keyframes are given the benefit of the doubt) || `source-error` | error | An asset that failed to load or generate, with the failure message |-## Exit code+## Severity and the shell++Finding issues is not a failure: the result is the same object either way, and the caller reads `issues`. From a shell, `dapi check` additionally exits `1` when an error-severity issue is found (warnings alone stay `0`), so it can gate a script.++## Errors-`0` when no error-severity issue is found (warnings alone stay `0`), `1` when one is — or when the check itself can't run (no project open, unknown id).+Fails when the check itself can't run: no project is open, or the id is unknown or ambiguous.diff --git a/knowledge/reference/tools/context.md b/knowledge/reference/tools/context.mdindex 8b5a86aa..7445751e 100644--- a/knowledge/reference/tools/context.md+++ b/knowledge/reference/tools/context.md@@ -1,14 +1,21 @@-# `dapi context`+# context-Summary of app state: what the project's source cannot say. The composition-itself — its scenes, what is selected, which scene is active, the work area —-is all in the JSX, and a caller that wants any of it reads the file. Alias:-`ctx`.+Report the current app context: the application root folder (always reported), the folder of the project the app has open (null when none is), where its playhead sits in seconds, the registered font families, and where its `generate.*` declarations stand. Poll it to wait for generations without blocking.++| | |+| --- | --- |+| MCP tool | `context` |+| CLI | `dapi context` |+| CLI aliases | `dapi ctx` |## InputNone.+## What it does not say++The composition itself — its scenes, what is selected, which scene is active, the work area — is all in the JSX, and a caller that wants any of it reads the file. This report is only what the source cannot say. Over MCP it is also the live resource `dapi://context`.+## OutputOne JSON object:@@ -29,27 +36,14 @@ One JSON object:}```-With no project open (the app sits at the dashboard) the report is just-`{ rootDir, projectDir: null }`: there is no playhead, no world, and no fonts-to speak of. Open one with [`dapi open`](./open.md).+With no project open (the app sits at the dashboard) the report is just `{ rootDir, projectDir: null }`: there is no playhead, no world, and no fonts to speak of. Open one with [`open`](./open.md).-`rootDir` is reported whether or not a project is open — it is where a caller-with nothing open goes to create or find one.+`rootDir` is reported whether or not a project is open — it is where a caller with nothing open goes to create or find one.-`currentTime` is local to the active scene, the same origin a clip's `start`-and `end` are placed against, and in the same unit.+`currentTime` is local to the active scene, the same origin a clip's `start` and `end` are placed against, and in the same unit.-`projectDir` is the folder the app is editing, which is not necessarily the-one a command was run from: check it before writing to source files.+`projectDir` is the folder the app is editing, which is not necessarily the one a command was run from: check it before writing to source files.-`fontFamilies` is what text can be drawn with right now — loaded into the world,-not merely named in the source — and always includes the editor default. For-every family installed on the machine, see [`dapi fonts`](./fonts.md).+`fontFamilies` is what text can be drawn with right now — loaded into the world, not merely named in the source — and always includes the editor default. For every family installed on the machine, see [`fonts`](./fonts.md).-`generations` is how a caller waits for `generate.*` declarations without-blocking: generation is asynchronous, so poll this until nothing is-`generating`. A `done` row's `asset` is a library path, ready for-[`dapi media probe`](./media/probe.md) and its siblings; a `failed` row's-`error` is the same message the element carries as its `error` prop, which is-what keeps it from being generated again (see-[jsx/errors.md](../jsx/errors.md#failed-sources)).+`generations` is how a caller waits for `generate.*` declarations without blocking: generation is asynchronous, so poll this until nothing is `generating`. A `done` row's `asset` is a library path, ready for [`media_probe`](./media/probe.md) and its siblings; a `failed` row's `error` is the same message the element carries as its `error` prop, which is what keeps it from being generated again (see [jsx/errors.md](../jsx/errors.md#failed-sources)).diff --git a/knowledge/reference/tools/export.md b/knowledge/reference/tools/export.mdindex f3823172..84f5be57 100644--- a/knowledge/reference/tools/export.md+++ b/knowledge/reference/tools/export.md@@ -1,15 +1,32 @@-# `dapi export <id> [output]`+# export-Encodes a scene to a video file — the full render the app's own export runs: the scene re-rendered from a fresh mount at its own size, the workarea from start to end, video and audio, streamed to the output file as it encodes. What [`capture`](./capture.md) shows one frame of, `export` writes all of.+Encode a scene to a video file — the same render the app's export runs, covering the scene's workarea. Settings come from the scene's `diffusion.export.<id>` entry in the project's package.json (the entry the app's export panel writes); a scene without one exports with the defaults (1080p H.264 MP4, AAC audio). The output path's extension picks the container, overriding the configured format. Returns the written path and the settings used. One export runs at a time; progress shows in the app. Only export when asked to: capture is the tool for checking a composition.-**The settings live in the project, not on the command.** The export is made with the scene's entry in the project's `package.json` — the same entry the app's export panel writes — so a CLI export reproduces the in-app one exactly, and the settings version with the project. The command decides only what to export and where to put it; a hand edit to `package.json` is picked up by the running app immediately, no reload needed.--Renders take as long as the scene demands (the CLI waits up to 60 minutes). The app shows the export's progress overlay while it runs, with a working Cancel button; one export runs at a time. Verify frames with [`capture`](./capture.md) and structure with [`check`](./check.md) before spending the render time.+| | |+| --- | --- |+| MCP tool | `export` |+| CLI | `dapi export <id> [output]` |## Input-- `<id>`: scene id to export (required) — the scene's `id` attribute in the project's JSX, or `file:id` when two files use the same id. Scenes only: a scene is the unit an export renders, and the error names the scene to export when the id is some other node's.-- `[output]`: output file path, ffmpeg-style (optional; relative paths resolve against the working directory). Its extension picks the container — `.mp4`, `.webm`, `.ogg` (audio only), `.mov` — overriding the configured format, so the file is always what its name says. A path without one of those extensions is an error. Omitted, the file lands at `exports/<id>.<format>` in the project folder (parent directories are created); an existing file is overwritten.+| Field | Type | CLI | Description |+| --- | --- | --- | --- |+| `id` | `string`, required | `<id>` | scene id from the project's JSX, or `file:id` when two files use the same id |+| `path` | `string` | `[output]` | absolute output file path, ffmpeg-style; its extension picks the container (default: exports/<id>.<format> in the project folder) |++## Rendering++The full render the app's own export runs: the scene re-rendered from a fresh mount at its own size, the workarea from start to end, video and audio, streamed to the output file as it encodes. What [`capture`](./capture.md) shows one frame of, `export` writes all of.++**The settings live in the project, not on the call.** The export is made with the scene's entry in the project's `package.json` — the same entry the app's export panel writes — so a tool export reproduces the in-app one exactly, and the settings version with the project. The call decides only what to export and where to put it; a hand edit to `package.json` is picked up by the running app immediately, no reload needed.++Renders take as long as the scene demands: the CLI waits up to 60 minutes, and an MCP client should give the call a comparable timeout. The app shows the export's progress overlay while it runs, with a working Cancel button; one export runs at a time. Verify frames with [`capture`](./capture.md) and structure with [`check`](./check.md) before spending the render time.++Scenes only: a scene is the unit an export renders, and the error names the scene to export when the id is some other node's.++## Output path++The `path` extension picks the container — `.mp4`, `.webm`, `.ogg` (audio only), `.mov` — overriding the configured format, so the file is always what its name says. A path without one of those extensions is an error. Omitted, the file lands at `exports/<id>.<format>` in the project folder (parent directories are created); an existing file is overwritten. From a shell, a relative path resolves against the working directory.## Settings@@ -65,4 +82,4 @@ The echoed `config` is the confirmation of what a `package.json` edit actually d## Errors-Exits non-zero if no project is open (`No project open` — run `dapi open <dir>` first), the id is unknown or ambiguous (pass `file:id`), the id names a node that is not a scene (the error names the scene to export instead), the output path lacks a container extension, the entry's format is unknown, the configuration is unencodable on this machine (codec × resolution × bitrate — the error says what to lower), another export is already running, or the export is canceled in the app. A failed or canceled export deletes the partial file.+Fails when no project is open (`No project open` — run [`open`](./open.md) first), the id is unknown or ambiguous (pass `file:id`), the id names a node that is not a scene (the error names the scene to export instead), the output path lacks a container extension, the entry's format is unknown, the configuration is unencodable on this machine (codec × resolution × bitrate — the error says what to lower), another export is already running, or the export is canceled in the app. A failed or canceled export deletes the partial file.diff --git a/knowledge/reference/tools/fetch.md b/knowledge/reference/tools/fetch.mdindex 64c5d403..e35544c0 100644--- a/knowledge/reference/tools/fetch.md+++ b/knowledge/reference/tools/fetch.md@@ -1,22 +1,33 @@-# `dapi fetch <url>`+# fetch-Downloads a video with [yt-dlp](https://github.com/yt-dlp/yt-dlp). Does not require the app to be running. yt-dlp is not bundled: install it separately (`brew install yt-dlp`, or `pipx install yt-dlp`). If it is not on `PATH`, the command exits `1` with an install hint; set `YT_DLP_PATH` to point at a specific binary.+Download a video with yt-dlp (installed separately). Writes files to disk only and returns their paths (a single URL can yield several, e.g. a playlist).-This writes the file to disk only; it does not touch the open project.+| | |+| --- | --- |+| MCP tool | `fetch` |+| CLI | `dapi fetch <url> [options]` |-## Arguments+## Input-- `<url>`: the video or page URL to download.+| Field | Type | CLI | Description |+| --- | --- | --- | --- |+| `url` | `string`, required | `<url>` | video or page URL to download |+| `output` | `string` | `-o, --output <path>` | output file path or directory (yt-dlp -o template; default: yt-dlp's default) |+| `format` | `string` | `-f, --format <selector>` | yt-dlp format selector (default: prefer mp4), e.g. "bv*+ba/b" |+| `audio` | `boolean` | `-a, --audio` | extract audio only (yt-dlp -x) |+| `raw` | `string[]` | `-- <yt-dlp flags...>` | raw yt-dlp flags passed through, e.g. ["--sponsorblock-remove", "all"] |-## Options+[yt-dlp](https://github.com/yt-dlp/yt-dlp) is not bundled: install it separately (`brew install yt-dlp`, or `pipx install yt-dlp`). The download runs in the app's main process, so no project needs to be open; yt-dlp is looked up on the app's `PATH`, or at `YT_DLP_PATH` in the app's environment when set. Without it the call fails with an install hint before anything is downloaded.-- `-o, --output <path>`: output file path or directory (yt-dlp `-o` template). Default: yt-dlp's own default template in the current directory.-- `-f, --format <selector>`: yt-dlp format selector, e.g. `"bv*+ba/b"`. Default: prefer mp4/m4a streams and remux the result to `.mp4` (`--merge-output-format mp4`), falling back to the best available if no mp4 source exists.-- `-a, --audio`: extract audio only (yt-dlp `-x`). Takes precedence over the mp4 default.+This writes files to disk only; it does not touch the open project. A download becomes an asset by landing under the project's `assets/` folder (see [jsx/media.md](../jsx/media.md)).++## Format++Without `format`, the download prefers mp4/m4a streams and remuxes the result to `.mp4` (`--merge-output-format mp4`), falling back to the best available if no mp4 source exists. `audio` extracts audio only (yt-dlp `-x`) and takes precedence over the mp4 default; an explicit `format` opts out of both.## Passthrough-Forward raw yt-dlp flags after `--`; they are appended verbatim:+`raw` is a list of yt-dlp flags appended verbatim. From a shell they go after `--`:```shdapi fetch https://youtu.be/xyz -f "bv*+ba/b" -- --sponsorblock-remove all --limit-rate 2M@@ -30,9 +41,8 @@ One JSON object (a single URL can yield several files, e.g. a playlist):{ paths: string[] } // absolute paths of the files on disk, after any extraction / rename```-Download progress is rendered by yt-dlp on stderr while the command runs.+The resolved path comes from yt-dlp's `after_move:filepath`, so it reflects the real name after audio extraction or renaming, not a guess.-## Notes+## Errors-- The resolved path comes from yt-dlp's `after_move:filepath`, so it reflects the real name after audio extraction or renaming, not a guess.-- Exit code is `0` on success; on failure the command surfaces yt-dlp's exit code and prints its stderr.+Fails when yt-dlp is not installed or not runnable, or when yt-dlp itself fails; its `ERROR` line is the message. Canceling the call kills the download.diff --git a/knowledge/reference/tools/fonts.md b/knowledge/reference/tools/fonts.mdindex 15470aab..d7aa766c 100644--- a/knowledge/reference/tools/fonts.md+++ b/knowledge/reference/tools/fonts.md@@ -1,13 +1,22 @@-# `dapi fonts`+# fonts-Lists local fonts available on this machine. macOS only. Does not require the app to be running. Font families listed here are valid `fontFamily` values on [`<text>`](../jsx/text.md).+List the local fonts available on this machine (macOS only). These family names are valid `fontFamily` values on <text>; each family lists its variants.-## Options+| | |+| --- | --- |+| MCP tool | `fonts` |+| CLI | `dapi fonts [options]` |-- `-f, --family <pattern>`: filter to families whose name contains `<pattern>` (case-insensitive)-- `-w, --weights <weights...>`: filter to variants with the given CSS weight(s), e.g. `-w 400 700`-- `-s, --style <style>`: `"normal"` or `"italic"`-- `-l, --limit <n>`: output at most `<n>` families+## Input++| Field | Type | CLI | Description |+| --- | --- | --- | --- |+| `family` | `string` | `-f, --family <pattern>` | filter to families whose name contains this (case-insensitive) |+| `weights` | `string[]` | `-w, --weights <weights...>` | filter to variants with the given CSS weights, e.g. ["400", "700"] |+| `style` | `"normal" \| "italic"` | `-s, --style <style>` | filter to variants with the given style, normal or italic |+| `limit` | `integer` | `-l, --limit <n>` | return at most this many families |++Font families listed here are valid `fontFamily` values on [`<text>`](../jsx/text.md); see [jsx/fonts.md](../jsx/fonts.md) for how a family and variant are named in a composition, and [`context`](./context.md) for the families the open project has actually registered. Runs in the app's main process, so no project needs to be open.## Outputdiff --git a/knowledge/reference/tools/logs.md b/knowledge/reference/tools/logs.mdindex a4a6fcc8..c7d8ca17 100644--- a/knowledge/reference/tools/logs.md+++ b/knowledge/reference/tools/logs.md@@ -1,11 +1,20 @@-# `dapi logs`+# logs-Prints recent console output from the running app: everything the devtools console shows, including page logs, worker logs, uncaught errors, and Chromium warnings. Oldest first. The app buffers the last 2000 entries in its main process, so the log survives page reloads and project switches; use this instead of relaunching with `ELECTRON_ENABLE_LOGGING=1` to see renderer-side errors.+Recent console output from the running app (what the devtools console shows: page logs, worker logs, uncaught errors), oldest first. The app buffers the last 2000 entries across reloads and project switches, so this replaces relaunching with ELECTRON_ENABLE_LOGGING=1 when debugging renderer-side behavior.-## Options+| | |+| --- | --- |+| MCP tool | `logs` |+| CLI | `dapi logs [options]` |-- `-n, --tail <n>`: output only the last `<n>` entries (positive integer)-- `-l, --level <level>`: minimum level to include: `"debug"`, `"info"`, `"warning"`, or `"error"`+## Input++| Field | Type | CLI | Description |+| --- | --- | --- | --- |+| `tail` | `integer` | `-n, --tail <n>` | return only the last n entries |+| `level` | `"debug" \| "info" \| "warning" \| "error"` | `-l, --level <level>` | minimum level to include: debug, info, warning, or error |++The buffer lives in the app's main process, so the log survives page reloads and project switches. Over MCP the same entries are the live resource `dapi://logs`. Progress of long operations — an export's percentage, a generation landing — shows up here, so polling `logs` is how a caller follows work it started.## Output@@ -24,4 +33,4 @@ One JSON object, the entries oldest first:## Errors-Exits non-zero on an invalid `--tail` or `--level`, or if the app is not running.+Fails when `tail` is not a positive integer or `level` is not one of the four levels.diff --git a/knowledge/reference/tools/media/filmstrip.md b/knowledge/reference/tools/media/filmstrip.mdindex 01180e14..a094ef54 100644--- a/knowledge/reference/tools/media/filmstrip.md+++ b/knowledge/reference/tools/media/filmstrip.md@@ -1,27 +1,37 @@-# `dapi media filmstrip <path>`+# media_filmstrip-Renders a **filmstrip** of a video to a PNG, written to a file in the system temp directory: a grid of frames sampled at even intervals across the window, each row stamped with a timestamp ruler. Video only; use [`dapi media waveform`](./waveform.md) to inspect the audio track. Renders locally; no credits. Alias: `film`.+Render a grid of thumbnails sampled across the timeline to a PNG (local render, no credits), each row stamped with an HH:MM:SS:FF ruler. A fast, token-efficient video track preview; narrow the window to zoom into a region of interest. Video only (use media_waveform for audio).-Tick labels use `HH:MM:SS:FF` timecode (hours, minutes, seconds, frame within the second) at every zoom level, so labels stay comparable regardless of the window's span. Frames count against the video's frame rate.+| | |+| --- | --- |+| MCP tool | `media_filmstrip` |+| CLI | `dapi media filmstrip <path> [options]` |+| CLI aliases | `dapi media film` |## Input-- `<path>`: a local video file to preview in place without adding it to the library, or a project library path (required; library paths need an open project).-- `-s, --start <time>`: start of the window to preview, a `Time` value in source/content time (optional; default `0`).-- `-e, --end <time>`: end of the window to preview, a `Time` value (optional; default the asset's duration).-- `-x, --scale <factor>`: scale factor for the thumbnails (optional; default `1`, clamped to `0.25`-`4`). The overall canvas size stays fixed, so smaller thumbnails fit **more rows and columns** (a denser grid sampling more moments) and larger thumbnails fit fewer but show more detail each.-- `-o, --output <path>`: write the PNG here instead of a temp file (optional).+| Field | Type | CLI | Description |+| --- | --- | --- | --- |+| `path` | `string`, required | `<path>` | absolute file path or URL (works with or without an open project), or a library path like `b-roll/clip.mp4` (needs an open project) |+| `start` | `Time` | `-s, --start <time>` | start of the window — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: 0) |+| `end` | `Time` | `-e, --end <time>` | end of the window — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: asset duration) |+| `output` | `string` | `-o, --output <path>` | absolute path to write the PNG to (default: a fresh file under the system temp dir) |+| `scale` | `number` | `-x, --scale <factor>` | scale factor for the thumbnails; smaller fits more rows and columns, larger fits fewer (default: 1) |++Frames are sampled at even intervals across the window. Tick labels use `HH:MM:SS:FF` timecode (hours, minutes, seconds, frame within the second) at every zoom level, so labels stay comparable regardless of the window's span; frames count against the video's frame rate. Video only; use [`media_waveform`](./waveform.md) to inspect the audio track.++The overall canvas size stays fixed, so a smaller `scale` (clamped to `0.25`–`4`) fits **more rows and columns** — a denser grid sampling more moments — and a larger one fits fewer but shows more detail each. Without `output` the PNG lands in a fresh file under the system temp directory.## Output-One JSON object, the absolute path to the written PNG:+One JSON object, the absolute path to the written PNG. Over MCP the image also arrives inline when it is under a megabyte.```ts{- path: string, // e.g. "/tmp/3f2c1a8e-....png", or the --output path+ path: string, // e.g. "/tmp/dapi-filmstrip-3f2c1a8e-….png", or the `output` path}```## Errors-Exits non-zero if the path can't be resolved, the asset isn't a video, `--start`/`--end` fall outside the asset or cross (`--start` >= `--end`), `--scale` isn't a positive number, or `--output` can't be written.+Fails when the path can't be resolved, the asset isn't a video, `start`/`end` fall outside the asset or cross (`start` >= `end`), `scale` isn't a positive number, or the PNG can't be written.diff --git a/knowledge/reference/tools/media/grab.md b/knowledge/reference/tools/media/grab.mdindex 8b204748..a76e1caf 100644--- a/knowledge/reference/tools/media/grab.md+++ b/knowledge/reference/tools/media/grab.md@@ -1,23 +1,44 @@-# `dapi media grab <path>`+# media_grab-Decodes one or more frames of a video asset at the given times and merges them into **contact sheets**: up to 12 frames per PNG, each cell labelled with its timecode and drawn as large as the sheet allows, so a handful of frames arrives as one high-resolution picture instead of a directory to open one by one. `--separate` writes a PNG per frame instead. Like [`capture`](../capture.md), but grabs the asset's own pixels (unlike `capture`, which renders the composited node). Renders locally; no credits. Past ~12 frames, [`media filmstrip`](./filmstrip.md) is the cheaper way to scan a clip.+Decode frames of a video file and write them as PNGs (local render, no credits). By default the frames are merged into contact sheets: up to 12 per image, each cell labelled with its timecode (`08s10f`, zero segments dropped) and drawn as large as fits, so a handful of frames arrives as one high-resolution picture instead of a directory to open one by one (separate: true writes a PNG per frame). Grabs the asset's own pixels, unlike capture which renders the composited node. The recommended tool for understanding a video at the frame level; past ~12 frames prefer media_filmstrip.++| | |+| --- | --- |+| MCP tool | `media_grab` |+| CLI | `dapi media grab <path> [options]` |+| CLI aliases | `dapi media sample` |## Input-- `<path>`: a local video file to grab frames from in place without adding it to the library, or a project library path (required; library paths need an open project).-- `-t, --times <time...>`: one or more timestamps to grab, `Time` values in source/content time (optional; default `0`). A negative value is an offset back from the end of the clip, so `-1` is one second before the end and `-1f` one frame before it. Order is preserved in the output regardless of the order given. Mutually exclusive with `--count`.-- `-c, --count <n>`: instead of `--times`, grab `n` frames evenly spaced across the clip at a fixed interval of `window / n`, starting at the window start (optional; positive integer).-- `-s, --start <time>`: with `--count`, the start of the window to sample (optional; `Time` value; default `0`).-- `-e, --end <time>`: with `--count`, the end of the window to sample (optional; `Time` value; default the asset duration).-- `-q, --quality <preset>`: per-frame resolution preset (optional). One of `small` (384x384), `medium` (768x768), `large` (1536x1536), or `fullres` (native); each caps the total pixel count while preserving aspect ratio. Defaults to as much detail as the sheet cell can show, or `small` with `--separate`.-- `-S, --separate`: write one PNG per frame instead of merging them into contact sheets (optional). The frames keep their own resolution and alpha, and each file is named after its timecode (e.g. `01s12f.png`).-- `--per-sheet <n>`: frames per contact sheet, 1 to 12 (optional; default as many as fit). Fewer frames per sheet means a larger cell each. Sheets are balanced, so 13 frames become 7 + 6 rather than 12 + 1.-- `--uncapped`: lift the 100-frame safety cap (optional). Without it, requesting more than 100 frames (via `--count` or `--times`) is rejected.-- `-o, --output <dir>`: directory to write the PNGs into (optional; default a fresh `dapi-grab-*` 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.+| Field | Type | CLI | Description |+| --- | --- | --- | --- |+| `path` | `string`, required | `<path>` | absolute file path or URL (works with or without an open project), or a library path like `b-roll/clip.mp4` (needs an open project) |+| `times` | `Time[]` | `-t, --times <time...>` | timestamps to grab — seconds ("1.5"), frames ("45f"), or "MM:SS"; negatives count back from the end, so -1 is one second before the end and -1f one frame before it (default: [0]) |+| `count` | `integer` | `-c, --count <n>` | instead of times, grab this many frames evenly spaced across the clip (or across the start/end window) |+| `auto` | `boolean` | `-a, --auto` | scan the clip at 2fps and keep a frame each time the footage settles into a new visual state (transitions are waited out, so picks stay sharp); returns at most count frames (default cap: 30), static footage like screen recordings returns far fewer; requires WebGPU |+| `start` | `Time` | `-s, --start <time>` | with count or auto, start of the window to sample (default: 0) |+| `end` | `Time` | `-e, --end <time>` | with count or auto, end of the window to sample (default: asset duration) |+| `quality` | `"small" \| "medium" \| "large" \| "fullres"` | `-q, --quality <preset>` | frame resolution: small (384x384), medium (768x768), large (1536x1536), or fullres (native); default: as large as the sheet cell allows, or small with separate: true |+| `separate` | `boolean` | `-S, --separate` | write one image per position instead of merging them into contact sheets of up to 12 cells, each labelled with its timecode |+| `perSheet` | `integer` | `--per-sheet <n>` | positions per contact sheet, 1-12; fewer means a larger cell each (default: as many as fit) |+| `uncapped` | `boolean` | `--uncapped` | lift the 100-frame safety cap (grabbing many frames is slow and token-heavy) |+| `output` | `string` | `-o, --output <dir>` | absolute directory to write the PNGs into (default: a fresh directory under the system temp dir) |++## Sampling++Three ways to say which frames, mutually exclusive:++- `times`: explicit timestamps in source time. A negative value counts back from the end of the clip, so `-1` is one second before the end and `-1f` one frame before it.+- `count`: that many frames evenly spaced across the clip, or across the `start`/`end` window, at a fixed interval of `window / count`, starting at the window start.+- `auto`: a scan at 2 fps that keeps a frame each time the picture settles into a new visual state, dropping near-duplicates and waiting out transitions so picks stay sharp. Returns at most `count` frames (default cap 30); static footage such as a screen recording returns far fewer. Needs WebGPU.++`start` and `end` only apply with `count` or `auto`. Like [`capture`](../capture.md), but this grabs the asset's own pixels; `capture` renders the composited node. Renders locally; no credits. Past ~12 frames, [`media_filmstrip`](./filmstrip.md) is the cheaper way to scan a clip.++With `separate`, frames keep their own resolution and alpha, and each file is named after its timecode (e.g. `01s12f.png`). Without an `output` directory the images land in a fresh `dapi-grab-*` directory under 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 first frame is `0f`. Each segment carries its unit, so nothing is ambiguous once the empty ones are gone. (The rulers `filmstrip` and `waveform` draw stay on fixed-width `HH:MM:SS:FF`, so their ticks line up.)+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 first frame is `0f`. Each segment carries its unit, so nothing is ambiguous once the empty ones are gone. (The rulers [`media_filmstrip`](./filmstrip.md) and [`media_waveform`](./waveform.md) draw stay on fixed-width `HH:MM:SS:FF`, so their ticks line up.)## Layout@@ -32,14 +53,14 @@ A sheet never exceeds 2576x1456, the largest image a vision model reads at full## Output-One JSON object with one entry per written image: a contact sheet by default, a frame with `--separate`.+One JSON object with one entry per written image: a contact sheet by default, a frame with `separate`.```ts{ images: Array<{ timecode: string; path: string }> } // e.g. { "images": [{ "timecode": "0f-08s10f", "path": "…/0f-08s10f.png" }] }```-A sheet's timecode is the span it covers; a frame's is its own. Sheets come in time order, and their cells in the order the times were requested in.+A sheet's timecode is the span it covers; a frame's is its own. Sheets come in time order, and their cells in the order the times were requested in. Over MCP, up to four images of at most a megabyte each also arrive inline.## Errors-Exits non-zero if the path can't be resolved, the asset is not a video, any `--times` value is past the asset's duration, the `--count` window is empty, `--times` and `--count` are combined, `--start`/`--end` are given without `--count`, `--per-sheet` is outside 1 to 12, more than 100 frames are requested without `--uncapped`, or a PNG can't be written.+Fails when the path can't be resolved, the asset is not a video, any of `times` is past the asset's duration, the window is empty or `start` is not before `end`, `times` is combined with `count` or `auto`, `start`/`end` are given without `count` or `auto`, `perSheet` is outside 1 to 12 or combined with `separate`, more than 100 frames are requested without `uncapped`, or a PNG can't be written.diff --git a/knowledge/reference/tools/media/listen.md b/knowledge/reference/tools/media/listen.mdindex db5dd692..a4dcc40d 100644--- a/knowledge/reference/tools/media/listen.md+++ b/knowledge/reference/tools/media/listen.md@@ -1,17 +1,26 @@-# `dapi media listen <path>`+# media_listen-Puts a multimodal model in front of an audio track and returns its answer. With no prompt it returns a general description of what is heard; with `--prompt` it answers that question about the audio (e.g. "who is speaking?", "what music is playing?", "summarize what is said"). Accepts an audio file or a video; of a video only the audio track is analyzed. Alias: `watch`.+Prompt a multimodal model for a semantic analysis of an audio track and return its answer. Shines on audio semantics (the name of the music playing, who is speaking, the spoken content with second-granularity timestamps). Accepts an audio file or a video; of a video only the audio track is analyzed. Needs a signed-in account.++| | |+| --- | --- |+| MCP tool | `media_listen` |+| CLI | `dapi media listen <path> [options]` |## Input-- `<path>`: a local audio or video file to analyze in place without adding it to the library, or a project library path (required; library paths need an open project).-- `-p, --prompt <str>`: question or instruction about the audio (optional; defaults to a general description).-- `-s, --start <time>`: start of the segment to analyze, a `Time` value (optional; default `0`). Timestamps in the analysis are relative to this point.-- `-e, --end <time>`: end of the segment to analyze, a `Time` value (optional; default the asset's duration).+| Field | Type | CLI | Description |+| --- | --- | --- | --- |+| `path` | `string`, required | `<path>` | absolute file path or URL (works with or without an open project), or a library path like `b-roll/clip.mp4` (needs an open project) |+| `prompt` | `string` | `-p, --prompt <str>` | question or instruction to guide the analysis |+| `start` | `Time` | `-s, --start <time>` | start of the segment to analyze (default: 0); timestamps in the analysis are relative to this point |+| `end` | `Time` | `-e, --end <time>` | end of the segment to analyze (default: media duration) |++With no `prompt` it returns a general description of what is heard; with one it answers that question about the audio (e.g. "who is speaking?", "what music is playing?", "summarize what is said"). See [the prompt guide](../../../guides/prompts/media-listen.md) for prompts that work. Costs credits, and needs a signed-in account ([`whoami`](../whoami.md)).## Output-One JSON object, the model's answer. `start`/`end` echo the analyzed window (in seconds) and are present only when `-s`/`-e` were given:+One JSON object, the model's answer. `start`/`end` echo the analyzed window (in seconds) and are present only when a window was given:```ts{ result: string, start?: number, end?: number }@@ -19,4 +28,4 @@ One JSON object, the model's answer. `start`/`end` echo the analyzed window (in## Errors-Exits non-zero if the path can't be resolved, the asset isn't a video or audio asset, or `--start`/`--end` cross (`--start` >= `--end`).+Fails when the path can't be resolved, the asset isn't a video or audio asset, `start`/`end` cross (`start` >= `end`), or no account is signed in.diff --git a/knowledge/reference/tools/media/probe.md b/knowledge/reference/tools/media/probe.mdindex a1740961..55559028 100644--- a/knowledge/reference/tools/media/probe.md+++ b/knowledge/reference/tools/media/probe.md@@ -1,15 +1,37 @@-# `dapi media probe <path>`+# media_probe-Reads the container and per-track technical metadata of an asset; like `ffprobe`, but demuxed locally with mediabunny. Reports the container format, duration, metadata tags, and every track's codec parameters without decoding any media. Reads locally; no credits.+Read the container and per-track technical metadata of a media file (local read, no credits): container format, duration, tags, and each track's codec params, without decoding. Commonly useful for a quick technical read, e.g. checking codec compatibility or duration before cutting. Packet stats (fps, bitrate) are estimated from a leading sample; images and transcripts report file-level info only.++| | |+| --- | --- |+| MCP tool | `media_probe` |+| CLI | `dapi media probe <path>` |## Input-- `<path>`: a local file to probe in place without adding it to the library, or a project library path (required; library paths need an open project). Any asset type is accepted.+| Field | Type | CLI | Description |+| --- | --- | --- | --- |+| `path` | `string`, required | `<path>` | absolute file path or URL (works with or without an open project), or a library path like `b-roll/clip.mp4` (needs an open project) |++Like `ffprobe`, but demuxed locally with mediabunny; any asset type is accepted.## OutputOne JSON object. The shape is **not yet stable**: it reports whatever mediabunny surfaces about the container and its tracks. Packet stats (frame rate, bitrate, packet count) are estimated from a leading sample of packets, so they are fast but approximate. Assets mediabunny can't demux (images, transcripts) don't error; they report file-level info only, with `format: null` and no tracks.+```ts+{+ id: string; name: string; path: string; type: string;+ mimeType?: string;+ size: number; // bytes+ width?: number; height?: number;+ format: string | null; // container name; null when the file could not be read as media+ duration?: number; // seconds+ tags?: Record<string, unknown>;+ tracks: Array<{ id: number; type: string; codec: string | null; language: string; firstTimestamp: number; duration: number; /* … */ }>;+}+```+## Errors-Exits non-zero if the path can't be resolved.+Fails when the path can't be resolved.diff --git a/knowledge/reference/tools/media/transcribe.md b/knowledge/reference/tools/media/transcribe.mdindex ae5e29ff..653eedca 100644--- a/knowledge/reference/tools/media/transcribe.md+++ b/knowledge/reference/tools/media/transcribe.md@@ -1,12 +1,19 @@-# `dapi media transcribe <path>`+# media_transcribe-Transcribes the speech in a video or audio asset and returns the timed transcript. Word-level start/end times are in **seconds** (source/content time).+Transcribe the speech in a video or audio file and return the timed transcript, with word-level start/end times in seconds. Commonly useful for footage with speakers (talking head, interview), where the word times let you cut on a line. A transcript marks only speech; the gaps are not necessarily silent (music, score, applause).++| | |+| --- | --- |+| MCP tool | `media_transcribe` |+| CLI | `dapi media transcribe <path>` |## Input-- `<path>`: a local video or audio file to transcribe in place without adding it to the library, or a project library path (required; library paths need an open project).+| Field | Type | CLI | Description |+| --- | --- | --- | --- |+| `path` | `string`, required | `<path>` | absolute file path or URL (works with or without an open project), or a library path like `b-roll/clip.mp4` (needs an open project) |-The whole asset is transcribed once per app session (cached in memory, keyed by file content; an app restart or an edited file re-transcribes).+Times are in **seconds** of source/content time. The whole asset is transcribed once per app session (cached in memory, keyed by file content; an app restart or an edited file re-transcribes).## Output@@ -23,4 +30,4 @@ One JSON object, the transcript:## Errors-Exits non-zero if the path can't be resolved or the asset is not a video/audio asset, or if no speech is detected in the audio at all (`No speech detected`).+Fails when the path can't be resolved, the asset is not a video/audio asset, or no speech is detected in the audio at all (`No speech detected`).diff --git a/knowledge/reference/tools/media/waveform.md b/knowledge/reference/tools/media/waveform.mdindex 7d7ef2db..9e6fe0be 100644--- a/knowledge/reference/tools/media/waveform.md+++ b/knowledge/reference/tools/media/waveform.md@@ -1,28 +1,38 @@-# `dapi media waveform <path>`+# media_waveform-Renders the audio track of a video or audio file as an amplitude **waveform** PNG, written to a file in the system temp directory: loudness over time drawn from decoded audio peaks, with a timestamp ruler. Silent stretches are highlighted in red. Renders locally; no credits. Alias: `wave`.+Render the audio track of a video or audio file as a waveform PNG (local render, no credits) with a timestamp ruler: loudness over time, with silent stretches highlighted in red. A fast, token-efficient audio track preview; the silent spans are also returned as second ranges.-Tick labels use `HH:MM:SS:FF` timecode (hours, minutes, seconds, frame within the second) at every zoom level, so labels stay comparable regardless of the window's span. For a video, frames count against the video's frame rate; for a standalone audio asset, the ruler counts against a nominal 30 fps.+| | |+| --- | --- |+| MCP tool | `media_waveform` |+| CLI | `dapi media waveform <path> [options]` |+| CLI aliases | `dapi media wave` |## Input-- `<path>`: a local video or audio file to preview in place without adding it to the library, or a project library path (required; library paths need an open project).-- `-s, --start <time>`: start of the window to preview, a `Time` value in source/content time (optional; default `0`).-- `-e, --end <time>`: end of the window to preview, a `Time` value (optional; default the asset's duration).-- `-x, --scale <factor>`: scale factor for the waveform (optional; default `1`, clamped to `0.25`-`4`). The overall canvas size stays fixed, so a smaller scale fits **more rows and columns** (a denser time axis) and a larger scale fits fewer but taller rows.-- `-o, --output <path>`: write the PNG here instead of a temp file (optional).+| Field | Type | CLI | Description |+| --- | --- | --- | --- |+| `path` | `string`, required | `<path>` | absolute file path or URL (works with or without an open project), or a library path like `b-roll/clip.mp4` (needs an open project) |+| `start` | `Time` | `-s, --start <time>` | start of the window — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: 0) |+| `end` | `Time` | `-e, --end <time>` | end of the window — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: asset duration) |+| `output` | `string` | `-o, --output <path>` | absolute path to write the PNG to (default: a fresh file under the system temp dir) |+| `scale` | `number` | `-x, --scale <factor>` | scale factor for the thumbnails; smaller fits more rows and columns, larger fits fewer (default: 1) |++Loudness over time is drawn from decoded audio peaks. Tick labels use `HH:MM:SS:FF` timecode (hours, minutes, seconds, frame within the second) at every zoom level, so labels stay comparable regardless of the window's span. For a video, frames count against the video's frame rate; for a standalone audio asset, the ruler counts against a nominal 30 fps.++The overall canvas size stays fixed, so a smaller `scale` (clamped to `0.25`–`4`) fits **more rows and columns** — a denser time axis — and a larger one fits fewer but taller rows. Without `output` the PNG lands in a fresh file under the system temp directory.## Output-One JSON object, the absolute path to the written PNG plus the silent stretches (the red spans on the waveform) as `[start, end]` second ranges, in absolute seconds (offset by `--start` when a window is used):+One JSON object: the absolute path to the written PNG plus the silent stretches (the red spans on the waveform) as `[start, end]` second ranges, in absolute seconds (offset by `start` when a window is used). Over MCP the image also arrives inline when it is under a megabyte.```ts{- path: string, // e.g. "/tmp/3f2c1a8e-....png", or the --output path+ path: string, // e.g. "/tmp/dapi-waveform-3f2c1a8e-….png", or the `output` pathsilences: Array<{ start: number, end: number }>,}```## Errors-Exits non-zero if the path can't be resolved, the asset has no decodable audio track, `--start`/`--end` fall outside the asset or cross (`--start` >= `--end`), `--scale` isn't a positive number, or `--output` can't be written.+Fails when the path can't be resolved, the asset has no decodable audio track, `start`/`end` fall outside the asset or cross (`start` >= `end`), `scale` isn't a positive number, or the PNG can't be written.diff --git a/knowledge/reference/tools/models.md b/knowledge/reference/tools/models.mdindex b7b93c8a..ea67dee0 100644--- a/knowledge/reference/tools/models.md+++ b/knowledge/reference/tools/models.md@@ -1,12 +1,19 @@-# `dapi models [type]`+# models-Lists the generation models available for a media type, including each model's capabilities. Use it to discover valid model ids and the per-model constraints (durations, aspect ratios, features) to set on an asset declaration (see [jsx/generate.md](../jsx/generate.md)).+List available AI generation models and their per-model constraints (durations, aspect ratios, features), for `generate.*` asset declarations in a project module.-There are no CLI commands that generate; asset generation is declared in the project module and produced on mount.+| | |+| --- | --- |+| MCP tool | `models` |+| CLI | `dapi models [type]` |## Input-- `[type]` (optional): one of `image`, `video`, `audio`. Omit to list all three groups.+| Field | Type | CLI | Description |+| --- | --- | --- | --- |+| `type` | `"image" \| "video" \| "audio"` | `[type]` | filter to one kind of model, image, video, or audio (default: all three) |++Use it to discover valid model ids and the per-model constraints (durations, aspect ratios, features) to set on an asset declaration (see [jsx/generate.md](../jsx/generate.md)). No tool generates: asset generation is declared in the project module and produced on mount.## Outputdiff --git a/knowledge/reference/tools/open.md b/knowledge/reference/tools/open.mdindex 934ee176..251687bc 100644--- a/knowledge/reference/tools/open.md+++ b/knowledge/reference/tools/open.md@@ -1,35 +1,39 @@-# `dapi open [path]`+# open-Launches Diffusion Studio — or surfaces the running instance — and, given a-path, opens that folder as a project. The first command of the core loop:-`open`, then mount, then render.+Open a folder as a project in the running app, creating the project files if the folder is not one yet, and show it in the editor. Returns the project's id, display name, and folder. Run this once before tools that need an open project (capture, check, export, context, and library paths in media tools).-The folder may live anywhere on disk, and does not have to be a project yet.-Opening is what makes it one, writing as little as that takes:+| | |+| --- | --- |+| MCP tool | `open` |+| CLI | `dapi open [path] [options]` |++## Input++| Field | Type | CLI | Description |+| --- | --- | --- | --- |+| `dir` | `string`, required | `[path]` | absolute path of the project folder to open or create |+| — | | `-b, --background` | launch or keep the app in the background, without raising a window (CLI only) |++## What opening writes++The folder may live anywhere on disk, and does not have to be a project yet. Opening is what makes it one, writing as little as that takes:- a missing folder is created;-- a folder with no entry file (package.json `main`, or `index.tsx` and- friends) gains an `index.tsx` holding an empty stage.+- a folder with no entry file (package.json `main`, or `index.tsx` and friends) gains an `index.tsx` holding an empty stage.-Nothing else is written — no package.json, tsconfig, README, or manifest. A-project is its JSX; the rest of the scaffold appears lazily, each piece when-something first needs it. A folder that is already a project is opened-untouched, wherever it lives.+Nothing else is written — no package.json, tsconfig, README, or manifest. A project is its JSX; the rest of the scaffold appears lazily, each piece when something first needs it. A folder that is already a project is opened untouched, wherever it lives.-The app remembers the folder, so the project reopens across app relaunches-and stays addressable by folder name or project id.+The app remembers the folder, so the project reopens across app relaunches and stays addressable by folder name or project id.-## Input+## From a shell-- `[path]`: project folder to open or create (optional; with no path the- command just makes sure the app is up). Relative paths resolve against the- shell's working directory.-- `-b, --background`: launch or keep the app in the background, without- raising a window. The way to drive the editor headless.+`dapi open` is also how the app starts: it launches Diffusion Studio (macOS) or surfaces the running instance, then, given a path, calls the tool. With no path it only makes sure the app is up, printing nothing and exiting `0` once the app answers. Relative paths resolve against the shell's working directory. `--background` launches or keeps the app without raising a window — the way to drive the editor headless.++Over MCP the app is already running, since that is what the connection is to; the tool only opens the folder, and `dir` must be absolute.## Output-With a path, the opened project as one JSON object:+The opened project:```ts{@@ -39,10 +43,7 @@ With a path, the opened project as one JSON object:}```-With no path, nothing: exit code `0` says the app is up.-## Errors- The path exists but is not a folder.-- Off macOS, the app cannot be launched; the command then requires it to- already be running.+- From a shell off macOS, the app cannot be launched; the command then requires it to already be running.diff --git a/knowledge/reference/tools/report.md b/knowledge/reference/tools/report.mdindex b74b415b..6eac3190 100644--- a/knowledge/reference/tools/report.md+++ b/knowledge/reference/tools/report.md@@ -1,22 +1,27 @@-# `dapi report <title>`+# report-Reports a bug in `dapi` itself or in the app behind it: a command that errors, contradicts this reference, or returns something it shouldn't. Bundles the description with diagnostics (dapi version, platform, node version, the app's recent console output) and files it as a GitHub issue on [diffusionstudio/editor](https://github.com/diffusionstudio/editor/issues), printing the URL of the created issue.+Report a bug in dapi or the app itself. Files a GitHub issue on diffusionstudio/editor with diagnostics attached (dapi version, platform, recent app logs) and returns its URL. Submits immediately and publicly through the gh CLI, which must be installed and authenticated; there is no review step, so only report real defects and check the attached logs for anything private.-The issue is submitted immediately, in the background, with no review step: the command returns once the issue exists. Filing goes through the [`gh`](https://cli.github.com) CLI, which must be installed and authenticated (`gh auth login`); without it the command exits `1` and files nothing.--This is for defects in the tooling, not for problems inside a project: a composition that looks wrong, a node in the wrong place, or a generation that missed the prompt are editing problems, not reported here.+| | |+| --- | --- |+| MCP tool | `report` |+| CLI | `dapi report <title> [options]` |+| CLI aliases | `dapi issue` |-Does not require the app to be running. If the app is down or unreachable, the report records that instead of failing, since that is often the bug being reported.+## Input-## Arguments+| Field | Type | CLI | Description |+| --- | --- | --- | --- |+| `title` | `string`, required | `<title>` | one-line summary of the problem |+| `body` | `string` | `-b, --body <text>` | what happened, in markdown: expected vs actual, and anything the diagnostics won't show |+| `commands` | `string[]` | `-c, --commands <cmd...>` | the dapi commands or tool calls that reproduce it, in order |+| `logs` | `integer` | `--logs <n>` | trailing app log entries to attach (0 to omit; default: 50) |-- `<title>`: one-line summary of the problem, used as the issue title.+For a tool that errors, contradicts this reference, or returns something it shouldn't. The description is bundled with diagnostics (app version, platform, Electron version, the app's recent console output) and filed as a GitHub issue on [diffusionstudio/editor](https://github.com/diffusionstudio/editor/issues).-## Options+The issue is submitted immediately, with no review step: the call returns once the issue exists. Filing goes through the [`gh`](https://cli.github.com) CLI, which must be installed and authenticated (`gh auth login`) on this machine; without it nothing is filed. It runs in the app's main process, so no project needs to be open.-- `-b, --body <text>`: what happened, in markdown: what you expected, what you got, and anything the diagnostics won't show.-- `-c, --commands <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.+This is for defects in the tooling, not for problems inside a project: a composition that looks wrong, a node in the wrong place, or a generation that missed the prompt are editing problems, not reported here.## Output@@ -30,7 +35,7 @@ One JSON object:## Issue layout-The title is the issue title; the body is assembled from the options and the diagnostics:+The title is the issue title; the body is assembled from the fields and the diagnostics:````md<body>@@ -45,10 +50,9 @@ dapi capture intro| | || --- | --- |-| dapi | 0.129.0 |+| app | 0.204.1 || platform | darwin 25.5.0 (arm64) |-| node | v20.19.0 |-| app | running |+| electron | 38.2.0 |## App logs@@ -57,10 +61,12 @@ dapi capture intro```````-The `app` row reads `running`, `not running`, `not checked` (with `--logs 0`), or the reason it was unreachable.+`commands` are rendered as a shell block under `## Repro`, in the order given; from a shell, `-c` is repeatable (`-c "dapi context" -c "dapi capture intro"`). `logs: 0` omits the log section.## Notes-- Attached logs are the same entries [`logs`](./logs.md) prints, and can contain project names, file paths, and prompt text. They go straight to a public issue: pass `--logs 0`, or check what [`logs`](./logs.md) currently holds, before reporting from a sensitive project.-- Exits non-zero on an empty title, an invalid `--logs`, a missing `gh`, or a failure from `gh` (not authenticated, no access to the repo); the message from `gh` is passed through.-- `dapi issue` is an alias of this command.+- Attached logs are the same entries [`logs`](./logs.md) returns, and can contain project names, file paths, and prompt text. They go straight to a public issue: pass `logs: 0`, or check what [`logs`](./logs.md) currently holds, before reporting from a sensitive project.++## Errors++Fails on an empty title, a `logs` value below 0, a missing `gh`, or a failure from `gh` (not authenticated, no access to the repo); the message from `gh` is passed through.diff --git a/knowledge/reference/tools/screenshot.md b/knowledge/reference/tools/screenshot.mdindex 70116903..0bfd1801 100644--- a/knowledge/reference/tools/screenshot.md+++ b/knowledge/reference/tools/screenshot.md@@ -1,21 +1,24 @@-# `dapi screenshot`+# screenshot-Captures the entire application window as a PNG: the full UI as the user sees it (panels, timeline, asset library, canvas viewport), at the window's current size. Use it to check what the app itself looks like; to render a node or scene cleanly for composition checks use [`capture`](./capture.md) instead.+Capture the entire application window as a PNG — the full UI as the user sees it (panels, timeline, asset library, canvas viewport), at the window's current size. The tool for checking what the app itself looks like; to render a node or scene cleanly for composition checks use capture instead.-The shot is taken from the app's own window buffer, so it works even when the window is hidden or covered by other windows, and never includes anything outside the app.+| | |+| --- | --- |+| MCP tool | `screenshot` |+| CLI | `dapi screenshot [options]` |-## Options+## Input-- `-o, --output <dir>`: directory to write the PNG into (default: the system temp directory)+| Field | Type | CLI | Description |+| --- | --- | --- | --- |+| `output` | `string` | `-o, --output <dir>` | absolute directory to write the PNGs into (default: a fresh directory under the system temp dir) |++The shot is taken from the app's own window buffer, so it works even when the window is hidden or covered by other windows, and never includes anything outside the app. The file is named `diffusion-studio_<date>_<time>.png`; without an `output` directory it lands in the system temp directory.## Output-One JSON object: the absolute path to a freshly written PNG, plus the image's pixel dimensions.+One JSON object: the absolute path to the freshly written PNG, plus the image's pixel dimensions. Over MCP the image also arrives inline when it is under a megabyte.```ts{ path: string, width: number, height: number }```--## Errors--Exits non-zero if the app is not running.diff --git a/knowledge/reference/tools/voices.md b/knowledge/reference/tools/voices.mdindex f6600c77..305e71a6 100644--- a/knowledge/reference/tools/voices.md+++ b/knowledge/reference/tools/voices.md@@ -1,11 +1,18 @@-# `dapi voices`+# voices-Lists the speech voices available for `generate.voice` declarations (see [jsx/generate.md](../jsx/generate.md)).+List the speech voices available for `generate.voice` declarations in a project module.++| | |+| --- | --- |+| MCP tool | `voices` |+| CLI | `dapi voices` |## InputNone.+See [jsx/generate.md](../jsx/generate.md) for the declaration a voice id goes on.+## OutputOne JSON object:diff --git a/knowledge/reference/tools/whoami.md b/knowledge/reference/tools/whoami.mdindex c514b6de..8d67f713 100644--- a/knowledge/reference/tools/whoami.md+++ b/knowledge/reference/tools/whoami.md@@ -1,6 +1,11 @@-# `dapi whoami`+# whoami-Prints the authenticated account, or `null` if signed out.+Report the authenticated account, or null if signed out.++| | |+| --- | --- |+| MCP tool | `whoami` |+| CLI | `dapi whoami` |## Inputdiff --git a/knowledge/skills/editor.md b/knowledge/skills/editor.mdindex 26154020..e7266e6b 100644--- a/knowledge/skills/editor.md+++ b/knowledge/skills/editor.md@@ -2,11 +2,11 @@How to understand source material before editing it. Inspect only the modalities the decision turns on — speech, action, music, graphics, or atmosphere may lead, so there is no fixed priority. Sample the picture against what the audio tells you.-- **Always probe first.** `dapi media probe <id|path>` reports the container and its tracks, telling you up front whether the file has a video track, an audio track, or both. Everything after branches on that.-- **Get the lay of the land.** Render a `dapi media waveform` (audio) and a `dapi media filmstrip` (video) for a fast, cheap overview of where the loud and quiet stretches fall, and where the visual scene changes are. A filmstrip shows coarse structure and scene state, not crop, framing, readability, or an exact cut frame.-- **Listen to the audio.** Run `dapi media listen` with a prompt tailored to the context (what you actually need to know), and explicitly ask the model to include timestamps in its answer. See [media-listen.md](../guides/prompts/media-listen.md) for prompt patterns.-- **Transcribe speech.** For speech, `dapi media transcribe` prints the full transcript with word-level start/end times directly — read any segment straight from it.-- **Sample the video against the audio.** Use `dapi media grab` to pull frames. When the audio has already pointed you at specific moments, feed those timestamps straight in from the transcript or listen output, e.g. `-t '00:32' '00:45' ...`. When you need a visual pass without such cues, reach for `--auto`: it scans the footage and keeps only the frames where the picture settles into a new visual state, dropping near-duplicates.+- **Always probe first.** `media_probe` reports the container and its tracks, telling you up front whether the file has a video track, an audio track, or both. Everything after branches on that.+- **Get the lay of the land.** Render a `media_waveform` (audio) and a `media_filmstrip` (video) for a fast, cheap overview of where the loud and quiet stretches fall, and where the visual scene changes are. A filmstrip shows coarse structure and scene state, not crop, framing, readability, or an exact cut frame.+- **Listen to the audio.** Run `media_listen` with a prompt tailored to the context (what you actually need to know), and explicitly ask the model to include timestamps in its answer. See [media-listen.md](../guides/prompts/media-listen.md) for prompt patterns.+- **Transcribe speech.** For speech, `media_transcribe` returns the full transcript with word-level start/end times directly — read any segment straight from it.+- **Sample the video against the audio.** Use `media_grab` to pull frames. When the audio has already pointed you at specific moments, feed those timestamps straight in from the transcript or listen output as `times` (e.g. `00:32`, `00:45`). When you need a visual pass without such cues, reach for `auto`: it scans the footage and keeps only the frames where the picture settles into a new visual state, dropping near-duplicates.# The editing loop@@ -14,9 +14,9 @@ How to understand source material before editing it. Inspect only the modalities- Lay down the A-roll. Assemble the primary footage as JSX and save. Get the spine of the edit right before anything else.- Layer the rest on top. Once the A-roll holds, add B-roll and secondary assets (sound effects, captions, overlays) in the same source.- Symlink media the project uses into its `assets/` folder and name it by library path (`assets/b-roll/drone.mp4` is `"b-roll/drone.mp4"`); local and remote paths work too but stay outside the library.-- `dapi context` reports which folder the app actually has open, where the playhead sits, and where every `generate.*` declaration stands — poll it to wait for generations without blocking.+- `context` reports which folder the app actually has open, where the playhead sits, and where every `generate.*` declaration stands — poll it to wait for generations without blocking.-**The source is the document.** A project is a folder of JSX; Use `dapi open <dir>` once, then write the files and save. Saving recompiles and re-renders the canvas.+**The source is the document.** A project is a folder of JSX; `open` a folder once, then write the files and save. Saving recompiles and re-renders the canvas.# Compositing@@ -31,14 +31,14 @@ How to understand source material before editing it. Inspect only the modalitiesHow to confirm a change actually produced what you intended. A clean save does not guarantee a correct-looking composition.-- Run `dapi check <id>` first. It catches black frames, clips that never become visible, zero-duration or fully transparent nodes, and assets that failed to load or generate.-- Use `dapi capture <id>` to see what the viewer actually gets.+- Run `check` on the scene first. It catches black frames, clips that never become visible, zero-duration or fully transparent nodes, and assets that failed to load or generate.+- Use `capture` on the scene to see what the viewer actually gets.- Reconcile captured frames with the brief, and the brief with these guidelines.- Verify after every stage, not only at the end — build the composition incrementally so a problem is caught next to the change that caused it.- Scale verification to the change. A small or incremental tweak the user asked for needs no visual confirmation so the user gets the result back fast and can keep iterating.- Fix the largest viewer-facing problem before polishing details, and recheck related moments after structural changes, since pacing, continuity, emphasis, and meaning are relational.- Use `screenshot` or `logs` to debug issues.-- DO NOT export/render the scene for visual confirmation — `dapi capture` is equivalent to a render but far more efficient. Rendering to a video should be a user-triggered action unless explicitly requested in the prompt.+- DO NOT export/render the scene for visual confirmation — `capture` is equivalent to a render but far more efficient. Rendering to a video should be a user-triggered action unless explicitly requested in the prompt.# Best practices@@ -49,7 +49,7 @@ How to confirm a change actually produced what you intended. A clean save does n- For motion graphics, overlays and UI-heavy graphics, the `<html>` tag driven by a paused [anime.js](https://animejs.com) timeline- Before animating anything, read the [easings reference](../guides/motion/easings.md) and choose easings deliberately — default or linear easing is what makes motion read as a slideshow.- Add auto captions last, after everything else is assembled, so they transcribe the finished audio at its final placement.-- Open the application in the background (`dapi open -b`) for tasks that don't require an editing UI.+- For tasks that don't need an editing UI, keep the app in the background: from a shell, `dapi open -b <dir>` launches it that way. Over MCP the app is already running, and `open` only opens the folder.- Only render (export) the result when prompted.- Start with a fresh project.@@ -58,7 +58,7 @@ How to confirm a change actually produced what you intended. A clean save does nThe authoring reference is served by the app for the installed version: read it there and trust it over memory.- [JSX reference — elements, timing, paints, generation, captions](../reference/jsx/README.md)-- [Tool reference — every tool, its arguments and its output](../reference/tools/README.md)+- [Tool reference — every tool, its fields, its CLI spelling and its output](../reference/tools/README.md)- [Examples — complete compositions, basics through shaders](../examples/README.md)- [Easings: which cubic-bezier to use and when](../guides/motion/easings.md)- [Diffusion Studio brand — the fallback when no other branding is specified](../brand/README.md)@@ -74,4 +74,4 @@ Read worked example(s) that match your context.## Prompts-- [Writing prompts for `dapi media listen`](../guides/prompts/media-listen.md)+- [Writing prompts for `media_listen`](../guides/prompts/media-listen.md)diff --git a/knowledge/skills/watch.md b/knowledge/skills/watch.mdindex caeee52a..c44de813 100644--- a/knowledge/skills/watch.md+++ b/knowledge/skills/watch.md@@ -2,20 +2,20 @@How to understand source material. Inspect only the modalities the question turns on — speech, action, music, graphics, or atmosphere may lead, so there is no fixed priority. Sample the picture against what the audio tells you.-- **Always probe first.** `dapi media probe <id|path>` reports the container and its tracks, telling you up front whether the file has a video track, an audio track, or both. Everything after branches on that.-- **Get the lay of the land.** Render a `dapi media waveform` (audio) and a `dapi media filmstrip` (video) for a fast, cheap overview of where the loud and quiet stretches fall, and where the visual scene changes are. A filmstrip shows coarse structure and scene state, not crop, framing, readability, or an exact cut frame.-- **Listen to the audio.** Run `dapi media listen` with a prompt tailored to the context (what you actually need to know), and explicitly ask the model to include timestamps in its answer. See [media-listen.md](../guides/prompts/media-listen.md) for prompt patterns.-- **Transcribe speech.** For speech, `dapi media transcribe` prints the full transcript with word-level start/end times directly — read any segment straight from it.-- **Sample the video against the audio.** Use `dapi media grab` to pull frames. When the audio has already pointed you at specific moments, feed those timestamps straight in from the transcript or listen output, e.g. `-t '00:32' '00:45' ...`. When you need a visual pass without such cues, reach for `--auto`: it scans the footage and keeps only the frames where the picture settles into a new visual state, dropping near-duplicates.+- **Always probe first.** `media_probe` reports the container and its tracks, telling you up front whether the file has a video track, an audio track, or both. Everything after branches on that.+- **Get the lay of the land.** Render a `media_waveform` (audio) and a `media_filmstrip` (video) for a fast, cheap overview of where the loud and quiet stretches fall, and where the visual scene changes are. A filmstrip shows coarse structure and scene state, not crop, framing, readability, or an exact cut frame.+- **Listen to the audio.** Run `media_listen` with a prompt tailored to the context (what you actually need to know), and explicitly ask the model to include timestamps in its answer. See [media-listen.md](../guides/prompts/media-listen.md) for prompt patterns.+- **Transcribe speech.** For speech, `media_transcribe` returns the full transcript with word-level start/end times directly — read any segment straight from it.+- **Sample the video against the audio.** Use `media_grab` to pull frames. When the audio has already pointed you at specific moments, feed those timestamps straight in from the transcript or listen output as `times` (e.g. `00:32`, `00:45`). When you need a visual pass without such cues, reach for `auto`: it scans the footage and keeps only the frames where the picture settles into a new visual state, dropping near-duplicates.# Matching depth to the question-Read only as much of the footage as the answer requires — each pass costs time, and `listen` costs credits.+Read only as much of the footage as the answer requires — each pass costs time, and `media_listen` costs credits.-- A duration or format question ends at `probe`.+- A duration or format question ends at `media_probe`.- "Where is the quiet part" or "how is it paced" is usually answered by the waveform and filmstrip alone.-- A question about what was said resolves fastest through `transcribe`; quote the transcript and its times directly.-- Questions about non-speech audio (music, tone, sound events, speaker identity) are what `listen` is for.+- A question about what was said resolves fastest through `media_transcribe`; quote the transcript and its times directly.+- Questions about non-speech audio (music, tone, sound events, speaker identity) are what `media_listen` is for.- Only questions about what is *seen* need frames — and the audio pass usually tells you which moments to grab, so grab those instead of scanning blind.- For open-ended questions ("summarize this", "what happens here"), combine passes: structure from waveform + filmstrip, content from transcript or listen, then frames at the salient moments to confirm what the picture shows.