Skip to content

The VS Code of video editing, built for agents.

TypeScript

Update project and media documentation for asset handling

konstantin-paulusdf23d9c64929
diff --git a/apps/desktop/src/projects.ts b/apps/desktop/src/projects.ts
index 9621c454..92fd24ac 100644
--- a/apps/desktop/src/projects.ts
+++ b/apps/desktop/src/projects.ts
@@ -572,7 +572,7 @@ on the canvas.
| \`package.json\` | The project record: \`projectId\` (its identity, kept across renames), \`displayName\` (the name shown in the app), \`main\` (the entry), \`diffusion\` (how each scene is exported), and the dapi commands as scripts. |
| \`tsconfig.json\` | Types for the composition tags, through \`jsxImportSource\`. |
| \`assets.yml\` | The asset library: for every asset its library path, where its bytes are, and what it was found to be. Written by the app; hand edits are read on the next load. |
-| \`assets/\` | Files the app produced itself, generations under \`assets/generated/\`. Media imported from elsewhere on disk is linked where it lies, never copied. |
+| \`assets/\` | The library's files: put one here and it is taken in while the app watches, and the app writes its own here too — generations under \`assets/generated/\`. Media imported through the app is linked where it lies instead, never copied. |
| \`cache/\` | Derived data (thumbnails, waveforms). Disposable, and not checked in. |
| \`AGENTS.md\` | The agent entry point: what to read in \`.diffusion/docs/\` and how to work here. |
| \`.diffusion/\` | App-owned. \`docs/\` is the authoring reference and examples for the installed app version; the app regenerates it, and it is not checked in. |
diff --git a/reference/jsx/README.md b/reference/jsx/README.md
index 8c5fe5d5..526cbc6e 100644
--- a/reference/jsx/README.md
+++ b/reference/jsx/README.md
@@ -40,7 +40,7 @@ export default function Project() {
| [html.md](./html.md) | `<html>`: reactive HTML children drawn into the box |
| [surface-paint.md](./surface-paint.md) | `<surface>`: a ref-provided canvas you draw into, sampled every frame |
| [shader-paint.md](./shader-paint.md) | `<shaderPaint>`: a WGSL fragment shader over the media paint below it |
-| [media.md](./media.md) | `src` resolution (paths, URLs, asset ids, `AssetRef`), image sequences, modifiers |
+| [media.md](./media.md) | `src` resolution (paths, URLs, asset ids, `AssetRef`), image sequences, modifiers, adding an asset to the library |
| [timing.md](./timing.md) | `start` / `end` / `sourceIn` / `sourceOut` / `playbackRate`, time formats |
| [keyframes.md](./keyframes.md) | Keyframe animation and easing |
| [animations.md](./animations.md) | `<animation>`: preset in/out animations |
diff --git a/reference/jsx/media.md b/reference/jsx/media.md
index 229f8db3..181c28bd 100644
--- a/reference/jsx/media.md
+++ b/reference/jsx/media.md
@@ -10,6 +10,8 @@
Resolution is **asynchronous and non-blocking**: the element is on the canvas as soon as the project mounts, showing a generating state until its source lands. A source that never lands leaves the element carrying an [`error`](./errors.md#failed-sources).
+An `<img>` inside [`<html>`](./html.md) additionally takes a `data:` or `blob:` URL, which goes to the browser as it is.
+
## Image sequences
A path naming a **directory of numbered frames** (`shot_001.png`, `shot_002.png`, …) is an image sequence, and plays on `<video>` or `<image>` exactly as footage does.
@@ -42,6 +44,20 @@ Modifiers compose with declarations: `<image src={generate.image({ prompt: "a re
## The library
-A project's assets are recorded in `assets.yml` next to its entry file: for each asset, its library `path`, where its bytes are (`source`: the absolute path of a file imported from disk — imports never move or copy files — or a project-relative path under `assets/` for files the app produced), and what it was found to be. Folders are listed too, so an empty one survives a reload. Renaming or moving an asset in the panel rewrites the `src` props that named it. Files placed under `assets/` by hand are taken into the library on the next load.
+A project's assets are recorded in `assets.yml` next to its entry file: for each asset, its library `path`, where its bytes are (`source`: the absolute path of a file imported from disk — imports never move or copy files — or a project-relative path under `assets/` for files the app produced), and what it was found to be. Folders are listed too, so an empty one survives a reload. Renaming or moving an asset in the panel rewrites the `src` props that named it.
-An `<img>` inside [`<html>`](./html.md) additionally takes a `data:` or `blob:` URL, which goes to the browser as it is.
+## Adding an asset
+
+Put the file under the project's `assets/` folder and it is in the library. The app is watching, so it lands while the project is open; a project that is closed takes it in on the next open. Its library path is where it sits under `assets/` — folder and name, so `assets/b-roll/drone.mp4` is `"b-roll/drone.mp4"` and `assets/logo.png` is `"logo.png"`.
+
+```sh
+mkdir -p assets/b-roll && cp ~/Movies/drone.mp4 assets/b-roll/
+```
+
+```tsx
+<video src="b-roll/drone.mp4" width={1920} height={1080} />
+```
+
+A directory of numbered frames is taken in whole, as one [image sequence](#image-sequences), rather than as a file each. [`dapi fetch`](../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.
+
+This is the way in from outside the app: there is no command that adds an asset, and `assets.yml` is not an entry point — a record carries the content hash the app computes for it, and a malformed one is dropped on load. Importing *through* the app is what leaves a file where it lies: the asset panel links it rather than copying it, which no amount of writing to the folder can do. A file that should not move and does not need a library path is named by its absolute path in `src` instead, at the cost of the portability a library path has.