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.tsindex 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.mdindex 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.mdindex 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 sequencesA 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.