Revised the README to better describe Diffusion Studio's functionality, emphasizing the role of the `dapi` CLI and providing detailed prompt examples for video understanding, motion graphics, video editing, and clipping. Additionally, clarified the caching behavior of transcripts in the captions documentation by removing the optional seed parameter reference, ensuring accurate information for users.
dapi CLI 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.
Each feature command has its own file (linked below). The JSX code syntax consumed by mount and node insert is specified in jsx/; the markup is pseudo-SVG, mirroring SVG's shape-and-paint model with the editor's own tags and props rather than the SVG spec.
Groups
Top-level: open, whoami, logs, screenshot, context (alias ctx), mount, models, voices, fonts, fetch.
| Group | Alias | Scope |
|---|---|---|
selection |
sel |
Read and mutate the current node selection. |
node |
n, entity |
Anything that targets one or more nodes; scenes are nodes too. |
project |
p |
Create, list, open, and delete projects. |
asset |
a |
Manage and inspect assets in the open project. |
folder |
fld |
Organize the asset library into folders. |
How the surface is divided:
- Declarative composition happens through
mount, which renders a Solid JSX project into the canvas (see jsx/);node insertruns the same pipeline but inserts the rendered nodes into an existing parent entity instead of mounting document roots. - Scenes are created declaratively via
mount(thesceneproperty on a root, e.g.<rect scene="...">); there is no imperative scene command. - AI asset generation (image / video / speech / audio) is declared in the project module (
generate.*, see jsx/generate.md) and produced on mount.modelsandvoiceslist what those declarations can reference. - Inspecting an existing asset (probe / transcribe / listen / filmstrip / waveform / grab) lives under
media; writing an asset's original file back to disk isasset export. - Organizing the library lives under
folder; moving assets between folders isasset mv.
Commands
App
dapi open: launch the app, or open a file, folder, or deep linkdapi whoami: print the authenticated accountdapi logs: recent console output from the running appdapi screenshot: capture the entire application window as a PNG
Document
dapi context: essential context about the open projectdapi mount: compile a Solid JSX project module and mount it into the canvas
Selection
dapi selection ls: list the selected nodesdapi selection set: replace the selectiondapi selection focus: frame the selection on the canvas
Nodes
dapi node ls: raw entity recordsdapi node tree: an entity's subtree as nested JSONdapi node grep: search entity records with a regexdapi node capture: capture a node as a PNGdapi node insert: insert JSX tags into an existing parentdapi node rm: delete entitiesdapi node cp: deep-clone nodesdapi node patch: assign JSX props on existing entitiesdapi node render: render a scene to a video file
Projects
dapi project active: print the active projectdapi project ls: list projectsdapi project create: create and open a projectdapi project set: set the active projectdapi project rm: delete a project
Assets
dapi asset add: add local files as assetsdapi asset ls: raw asset recordsdapi asset tree: the library as its folder treedapi asset rm: delete assetsdapi asset mv: move assets into a folderdapi asset export: write assets' original bytes to disk
Media
dapi media probe: container and track metadatadapi media transcribe: timed speech transcriptdapi media grab: decode video frames to PNGsdapi media filmstrip: grid of video frames as a PNGdapi media waveform: audio waveform PNG with silence highlightingdapi media listen: AI description of an audio track
Folders
dapi folder ls: list child foldersdapi folder create: create a folderdapi folder rename: rename a folderdapi folder mv: reparent foldersdapi folder rm: delete folders (cascades)
Generation reference
dapi models: list generation models and constraintsdapi voices: list speech voices
Fonts
dapi fonts: list local fonts
Download
dapi fetch: download a video with yt-dlp (installed separately)
Shared types
NodeRef = { id: number; name: string; type: string } // node ids are entity ids: integers
Size = { width: number; height: number }
Asset = { id: string; name: string; type: string } // asset ids are opaque strings (sqids)
Folder = { id: string; name: string; type: 'folder' } // folder ids are opaque strings (sqids)
Time = number | `${number}f` | "MM:SS" // seconds, frames at 30 fps ("45f"), or a clock string; see jsx/timing.md
Time inputs take the Time format unless noted otherwise. Times in outputs are plain seconds, except the raw records of node ls, which use engine units (frames at 30 fps, packed colors, dB).
Conventions
- Stdout is JSON. Commands that return a single record emit one JSON value. Commands that return a collection emit JSON Lines (one object per line, no surrounding array) so per-item results stay streamable.
node treeandasset treeemit one nested object per root. Exceptions:openfor file / URL / no-target writes nothing;fonts --names-onlywrites plain family names;logswrites plain formatted log lines;mountandnode insertwrite nothing. - Batch commands are fail-fast (
node rm,node patch,asset add, …): one invalid input fails the whole command with a single stderr message and exit1. Ids are validated before anything changes, so a failedrm/mv/cpchanges nothing; there are no per-item partial results. - Unix-style names are canonical: list/read is
ls, delete isrm, duplicate iscp, move/reparent ismv, search isgrep. The longer English forms (list,remove,duplicate,move) are aliases of the Unix forms, not the other way around.getis a universal alias forls. Commands without a natural Unix equivalent (tree,rename,patch,add,create,active,context,whoami,open,focus,set) keep their descriptive names. - Stderr: human-readable error messages.
- Exit codes:
0on success,1on any error (missing file, app not running, invalid input, IPC error). - App must be running: every command except
open,fonts, andfetchtalks to the open Diffusion Studio instance. If the app isn't running, the CLI prints an instruction to launch it and exits1.