Skip to content

The VS Code of video editing, built for agents.

TypeScript

Add animations prop to various components and documentation

konstantin-paulus5a8b56d29bf9
diff --git a/apps/cli/reference/jsx/README.md b/apps/cli/reference/jsx/README.md
index 99316488..0a0b562c 100644
--- a/apps/cli/reference/jsx/README.md
+++ b/apps/cli/reference/jsx/README.md
@@ -20,6 +20,7 @@ The pipeline is driven by two commands: [`dapi mount`](../mount.md) renders the
| [media.md](./media.md) | `src` resolution (paths, URLs, asset ids, `AssetRef`) |
| [timing.md](./timing.md) | `start` / `end` / `sourceIn` / `sourceOut`, time formats |
| [keyframes.md](./keyframes.md) | Keyframe animation and easing |
+| [animations.md](./animations.md) | The `animations` prop: preset in/out animations |
| [transitions.md](./transitions.md) | The `transition` prop on sequence clips |
| [sequences.md](./sequences.md) | `<sequence>` sequential placement |
| [audio-sync.md](./audio-sync.md) | `syncTo` audio alignment |
diff --git a/apps/cli/reference/jsx/animations.md b/apps/cli/reference/jsx/animations.md
new file mode 100644
index 00000000..97fdd000
--- /dev/null
+++ b/apps/cli/reference/jsx/animations.md
@@ -0,0 +1,50 @@
+# Animations
+
+`animations` declares **preset in/out animations** on a clip: each entry plays over the clip's head (`"in"`) or tail (`"out"`), between the node's static state and the preset's start/end state. For hand-authored motion on individual props, use [keyframes](./keyframes.md); the two compose on distinct properties.
+
+```tsx
+<video
+ src="/Movies/intro.mp4"
+ start={0} end={8}
+ animations={[
+ { type: "fade", duration: "15f" },
+ { type: "slideUp", phase: "out", duration: 0.5, delay: 0.2 },
+ ]}
+/>
+```
+
+```ts
+type AnimationSpec = {
+ type: AnimationType; // preset, see below
+ phase?: "in" | "out"; // default "in"
+ duration?: Time; // default 1 second
+ delay?: Time; // gap between the clip edge and the animation; default 0
+};
+```
+
+## Types
+
+The editor's animations inspector options:
+
+| `type` | Effect |
+| ------ | ------ |
+| `"fade"` | Opacity ramp. |
+| `"slideLeft"`, `"slideRight"`, `"slideUp"`, `"slideDown"` | Slide in from (or out toward) the named direction, fading. |
+| `"grow"` | Scales up from 50%. |
+| `"shrink"` | Scales down from 150%. |
+| `"spin"` | Scale plus rotation. |
+| `"twist"` | Overscale plus rotation and offset. |
+| `"blur"` | 24px blur ramp. |
+| `"appearWord"` | Text only: reveals the text word by word. |
+| `"appearChar"` | Text only: reveals the text character by character. |
+| `"scramble"` | Text only: resolves scrambled characters into the text. |
+| `"gain"` | Audio only: volume ramp (fade-in/fade-out of the mix). No visual effect. |
+
+Text types apply only to [`<text>`](./text.md) and [`<captions>`](./captions.md); a mount that puts them elsewhere fails validation.
+
+## Semantics
+
+- `duration` and `delay` take any [time format](./timing.md#time-formats). An `"in"` animation plays over `[delay, delay + duration]` from the clip's in point; an `"out"` animation ends `delay` before the clip's out point. Both track the clip when it is retimed.
+- A node takes **any number of animations**; overlapping entries apply in list order, later ones writing over earlier ones on the properties they share. A [keyframe](./keyframes.md) track on the same property (say, keyframed `opacity` next to `"fade"`) overrides the preset while it has effect; presets and keyframes on distinct properties compose freely.
+- The list is **mount-shaped**: setting `animations` replaces the node's existing animations, `[]` removes them all, and an omitted prop leaves hand-added ones untouched.
+- Animations land as regular editor animations, editable in the inspector. Part of the shared property table: [`dapi node patch`](../node/patch.md) accepts `animations` with identical semantics, e.g. `--json '[{ "id": 42, "animations": [{ "type": "fade" }] }]'`, and they list under `animations` in [`dapi node tree`](../node/tree.md).
diff --git a/apps/cli/reference/jsx/audio.md b/apps/cli/reference/jsx/audio.md
index d738fa5d..f9146c55 100644
--- a/apps/cli/reference/jsx/audio.md
+++ b/apps/cli/reference/jsx/audio.md
@@ -16,3 +16,4 @@ An audio clip: no visual output, no spatial props; carries volume. When timing i
| `volume` | `Animatable<number>` | `0` | Decibels: `0` = unity, negative attenuates (`-6` ≈ half as loud), `-Infinity` = silence. Not linear. |
| `muted` | `boolean` | `false` | Excludes the node's audio from the mix; independent of `volume`. |
| `syncTo` | `string` | none | Key of another element carrying audio; derives `start` by audio alignment (see [audio-sync.md](./audio-sync.md)). Mutually exclusive with `start`. |
+| `animations` | `AnimationSpec[]` | none | Preset in/out animations (see [animations.md](./animations.md)); only `"gain"` is audible. |
diff --git a/apps/cli/reference/jsx/elements.md b/apps/cli/reference/jsx/elements.md
index 6cb0b874..8c77a60c 100644
--- a/apps/cli/reference/jsx/elements.md
+++ b/apps/cli/reference/jsx/elements.md
@@ -40,6 +40,7 @@ All visual elements accept:
| `cornerRadius` | `Animatable<number>` | `0` | Uniform corner radius, px. |
| `start`, `end`, `sourceIn`, `sourceOut` | `Time` | see [timing.md](./timing.md) | Temporal placement. |
| `transition` | `TransitionSpec \| null` | none | Transition into the next clip; direct children of `<sequence>` only (see [transitions.md](./transitions.md)). |
+| `animations` | `AnimationSpec[]` | none | Preset in/out animations over the clip's head and tail (see [animations.md](./animations.md)). |
`Animatable` props also take a keyframe list; see [keyframes.md](./keyframes.md).
diff --git a/apps/cli/reference/jsx/keyframes.md b/apps/cli/reference/jsx/keyframes.md
index d6852394..e7e2904f 100644
--- a/apps/cli/reference/jsx/keyframes.md
+++ b/apps/cli/reference/jsx/keyframes.md
@@ -19,7 +19,7 @@ type Keyframe<T> = { time: Time; value: T; easing?: Easing };
type Animatable<T> = T | Keyframe<T>[];
```
-Animatable props: `x`, `y`, `width`, `height`, `rotation`, `opacity`, `cornerRadius`, `volume`, `color`, `offset`. As part of the shared property table this applies to [`dapi node patch`](../node/patch.md) identically, and to [paints and color stops](./paints.md) (`color`, `opacity`, `offset` animate gradients).
+Animatable props: `x`, `y`, `width`, `height`, `rotation`, `opacity`, `cornerRadius`, `volume`, `color`, `offset`. As part of the shared property table this applies to [`dapi node patch`](../node/patch.md) identically, and to [paints and color stops](./paints.md) (`color`, `opacity`, `offset` animate gradients). For preset in/out effects (fade, slides, text reveals, ...) use the [`animations` prop](./animations.md) instead.
## Semantics
diff --git a/apps/cli/reference/jsx/text.md b/apps/cli/reference/jsx/text.md
index 158e0ad8..6803248c 100644
--- a/apps/cli/reference/jsx/text.md
+++ b/apps/cli/reference/jsx/text.md
@@ -22,3 +22,5 @@ All [common props](./elements.md#common-props), plus:
| `fill` | `string` | white | The glyph color; any CSS color, alpha ignored (use `opacity`). Shorthand for a solid paint child (see [paints.md](./paints.md)); animate it by declaring the paint explicitly. |
| `textAlign` | `"left" \| "center" \| "right"` | `"left"` | Horizontal alignment of glyphs within the box. |
| `textBaseline` | `"top" \| "middle" \| "bottom"` | `"top"` | Vertical alignment within the box. |
+
+The text-only [animation types](./animations.md) (`"appearWord"`, `"appearChar"`, `"scramble"`) animate the glyphs themselves.
diff --git a/apps/cli/reference/node/patch.md b/apps/cli/reference/node/patch.md
index 20b7becb..40a692ad 100644
--- a/apps/cli/reference/node/patch.md
+++ b/apps/cli/reference/node/patch.md
@@ -23,6 +23,7 @@ All props are optional; a patch may set any subset. An unsupported property or a
- `src` takes a path, URL, or asset id (`generate.*` declarations are JSX-only). The source resolves asynchronously after the other props land; if resolution fails, the command fails at that entity even though its other props were applied. Patch `src` on its own to avoid ambiguity.
- `syncTo` re-runs audio alignment against the document node carrying the given key and writes the entity's `start` from the measured offset (see [jsx/audio-sync.md](../jsx/audio-sync.md)). The command blocks until alignment settles; a failed alignment rejects the entity.
- `transition` sets, merges into, or (with `null`) removes the clip's transition into the next clip (see [jsx/transitions.md](../jsx/transitions.md)).
+- `animations` replaces the entity's preset in/out animations with the given list; `[]` removes them all (see [jsx/animations.md](../jsx/animations.md)).
- Keyframe lists are accepted wherever the property is animatable, with the same semantics as mount (see [jsx/keyframes.md](../jsx/keyframes.md)); a static value replaces any existing keyframes.
- Element applicability is not checked: props are applied wherever `mount` would apply them (e.g. `fontSize` only makes sense on a text node).
diff --git a/apps/web/src/components/sidebar-left/assets.tsx b/apps/web/src/components/sidebar-left/assets.tsx
index 858e94be..c6da7118 100644
--- a/apps/web/src/components/sidebar-left/assets.tsx
+++ b/apps/web/src/components/sidebar-left/assets.tsx
@@ -43,6 +43,7 @@ import { LazyAssetItem } from "./asset-item";
import { FolderItem, handleFolderDrop, ASSET_DRAG_TYPE, FOLDER_DRAG_TYPE } from "./folder-item";
import type { EngineWorld } from "@/components/engine";
+import type { ElectronFileHandle } from "@/lib/electron-file-handle";
export function Assets() {
let root: HTMLDivElement | undefined;
@@ -122,7 +123,7 @@ export function Assets() {
}
});
- const importAssets = async (handles: ReadonlyArray<File | FileSystemFileHandle | DataTransferItem>) => {
+ const importAssets = async (handles: ReadonlyArray<File | FileSystemFileHandle | ElectronFileHandle | DataTransferItem>) => {
if (handles.length === 0) return;
try {
diff --git a/apps/web/src/context/editor-api/node.ts b/apps/web/src/context/editor-api/node.ts
index a3e57a4b..c2215bd2 100644
--- a/apps/web/src/context/editor-api/node.ts
+++ b/apps/web/src/context/editor-api/node.ts
@@ -9,6 +9,7 @@ import { createImageEncoder } from "@/components/engine/encode/image-encoder";
import { ElectronWritableFileHandle } from "@/lib/electron-file-writable";
import {
+ AnimationPhase,
deleteEntity,
isText,
isScene,
@@ -17,7 +18,7 @@ import {
serializeEntity,
} from "@/components/engine";
import { ChildOf } from "@/components/engine/components";
-import { WorldDocument } from "@/utils/jsx";
+import { ANIMATION_TYPE_MAP, WorldDocument } from "@/utils/jsx";
import { entityType } from "./selection";
import type { EngineWorld, Engine } from "@/components/engine";
@@ -38,6 +39,11 @@ import type {
import type { EncoderConfig } from "@/components/engine/encode/interfaces";
import type { Accessor } from "solid-js";
+// The JSX animation names, keyed by engine preset.
+const ANIMATION_TYPE_NAMES: Record<number, string> = Object.fromEntries(
+ Object.entries(ANIMATION_TYPE_MAP).map(([name, type]) => [type, name]),
+);
+
// Scenes are nodes too, so node ops accept them alongside geometry, groups,
// and adjustment layers.
export function isNode(world: EngineWorld, eid: number): boolean {
@@ -153,6 +159,14 @@ function describeEntity(world: EngineWorld, eid: number): string {
parts.push(`time: ${fmtTime(c.Keyframe.time[eid] ?? 0)}`, `value: ${c.Keyframe.value[eid]}`);
if (c.Keyframe.easing[eid]) parts.push(`easing: ${c.Keyframe.easing[eid]}`);
}
+ if (hasComponent(world, eid, c.Animation)) {
+ parts.push(
+ `type: ${ANIMATION_TYPE_NAMES[c.Animation.type[eid] ?? 0] ?? c.Animation.type[eid]}`,
+ `phase: ${c.Animation.phase[eid] === AnimationPhase.OUT ? "out" : "in"}`,
+ `duration: ${fmtTime(c.Animation.duration[eid] ?? 0)}`,
+ );
+ if (c.Animation.delay[eid]) parts.push(`delay: ${fmtTime(c.Animation.delay[eid])}`);
+ }
if (hasComponent(world, eid, c.TextRange)) {
parts.push(`range: ${c.TextRange.start[eid] ?? 0}–${c.TextRange.end[eid] ?? "end"}`);
}
diff --git a/apps/web/src/utils/jsx.ts b/apps/web/src/utils/jsx.ts
index 0a85cfc4..c4e3f5c5 100644
--- a/apps/web/src/utils/jsx.ts
+++ b/apps/web/src/utils/jsx.ts
@@ -8,6 +8,8 @@ import * as solid from "solid-js";
import * as solidStore from "solid-js/store";
import * as diffusionJsx from "@diffusionstudio/jsx";
import {
+ AnimationPhase,
+ AnimationType,
CaptionType,
FontStyle,
GeometryType,
@@ -180,6 +182,77 @@ function parseTransitionDuration(value: unknown): number {
return frames;
}
+// JSX animation names, mapped to the presets the animations inspector writes.
+// Exported for `node tree`'s entity descriptions.
+export const ANIMATION_TYPE_MAP = {
+ fade: AnimationType.FADE,
+ gain: AnimationType.GAIN,
+ grow: AnimationType.GROW,
+ shrink: AnimationType.SHRINK,
+ blur: AnimationType.BLUR,
+ slideLeft: AnimationType.SLIDE_LEFT,
+ slideRight: AnimationType.SLIDE_RIGHT,
+ slideUp: AnimationType.SLIDE_UP,
+ slideDown: AnimationType.SLIDE_DOWN,
+ spin: AnimationType.SPIN,
+ twist: AnimationType.TWIST,
+ appearWord: AnimationType.APPEAR_WORD,
+ appearChar: AnimationType.APPEAR_CHAR,
+ scramble: AnimationType.SCRAMBLE,
+} as const;
+
+const TEXT_ANIMATION_TYPES: ReadonlySet<AnimationType> = new Set([
+ AnimationType.APPEAR_WORD,
+ AnimationType.APPEAR_CHAR,
+ AnimationType.SCRAMBLE,
+]);
+
+// 1 second at the canonical 30 fps — the animations inspector's default.
+const ANIMATION_DEFAULT_DURATION = 30;
+
+function parseAnimationSpec(
+ entry: unknown,
+ isTextNode: boolean,
+): { type: AnimationType; phase: AnimationPhase; duration: number; delay: number } {
+ assert(
+ typeof entry === "object" && entry !== null && !Array.isArray(entry),
+ "`animations` entries must be { type, phase?, duration?, delay? } objects" + `, value: ${entry}`,
+ );
+ const { type, phase, duration, delay } = entry as Record<string, unknown>;
+
+ assert(typeof type === "string", "animation `type` must be a string" + `, value: ${type}`);
+ const parsedType = ANIMATION_TYPE_MAP[type as keyof typeof ANIMATION_TYPE_MAP];
+ assert(parsedType !== undefined, `invalid animation type: "${type}"`);
+ assert(
+ isTextNode || !TEXT_ANIMATION_TYPES.has(parsedType),
+ `animation type "${type}" only applies to text elements`,
+ );
+
+ let parsedPhase = AnimationPhase.IN;
+ if (phase !== undefined) {
+ assert(phase === "in" || phase === "out", 'animation `phase` must be "in" or "out"' + `, value: ${phase}`);
+ if (phase === "out") parsedPhase = AnimationPhase.OUT;
+ }
+
+ let parsedDuration = ANIMATION_DEFAULT_DURATION;
+ if (duration !== undefined) {
+ const frames = parseFrames(String(duration), 30);
+ assert(typeof frames === "number", "animation `duration` must be a time value" + `, value: ${duration}`);
+ assert(frames > 0, "animation `duration` must be > 0");
+ parsedDuration = frames;
+ }
+
+ let parsedDelay = 0;
+ if (delay !== undefined) {
+ const frames = parseFrames(String(delay), 30);
+ assert(typeof frames === "number", "animation `delay` must be a time value" + `, value: ${delay}`);
+ assert(frames >= 0, "animation `delay` must be >= 0");
+ parsedDelay = frames;
+ }
+
+ return { type: parsedType, phase: parsedPhase, duration: parsedDuration, delay: parsedDelay };
+}
+
const CAPTION_PRESET_MAP = {
classic: CaptionType.CLASSIC,
cascade: CaptionType.CASCADE,
@@ -684,6 +757,25 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {
}
setComponent(world, eid, c.Transition, spec);
break;
+ } case "animations": {
+ assert(
+ Array.isArray(value),
+ "`animations` must be an array of { type, phase?, duration?, delay? } objects" + `, value: ${value}`,
+ );
+ const isTextNode = c.Geometry[eid] === GeometryType.TEXT;
+ const specs = value.map((entry) => parseAnimationSpec(entry, isTextNode));
+
+ // The list replaces the node's existing animations; [] clears them.
+ // Materialized before deleting — removal mutates the live query.
+ for (const aid of [...query(world, [c.Animation, ChildOf(eid), Not(c.Deleted)])]) {
+ deleteEntity(world, aid);
+ }
+ for (const spec of specs) {
+ const aid = createEntity(world);
+ setComponent(world, aid, c.Animation, spec);
+ appendChild(world, aid, eid);
+ }
+ break;
} case "src": {
if (isAssetRef(value)) {
world.history.untrack(() => addComponent(world, eid, c.Generating));
diff --git a/packages/jsx/src/index.ts b/packages/jsx/src/index.ts
index a8f35940..804b62b5 100644
--- a/packages/jsx/src/index.ts
+++ b/packages/jsx/src/index.ts
@@ -17,6 +17,8 @@ export { PATCH_PROP_KEYS } from "./types";
export { parseTime, TIME_FPS } from "./time";
export type {
Animatable,
+ AnimationSpec,
+ AnimationType,
AudioProps,
CaptionPreset,
CaptionsProps,
diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.ts
index a1159526..34fac85b 100644
--- a/packages/jsx/src/types.ts
+++ b/packages/jsx/src/types.ts
@@ -63,6 +63,42 @@ export type TransitionSpec = {
duration?: Time;
};
+/**
+ * Preset animation styles — the editor's animations inspector options.
+ * "appearWord" / "appearChar" / "scramble" apply only to text elements;
+ * "gain" ramps audio and has no visual effect.
+ */
+export type AnimationType =
+ | "fade"
+ | "gain"
+ | "grow"
+ | "shrink"
+ | "blur"
+ | "slideLeft"
+ | "slideRight"
+ | "slideUp"
+ | "slideDown"
+ | "spin"
+ | "twist"
+ | "appearWord"
+ | "appearChar"
+ | "scramble";
+
+/** One entry of the `animations` prop's list — see `PatchProps["animations"]`. */
+export type AnimationSpec = {
+ /** Animation style. */
+ type: AnimationType;
+ /** "in" plays from the clip's head, "out" into its tail. Default "in". */
+ phase?: "in" | "out";
+ /** Length of the animation. Any `Time` format. Default 1 second. */
+ duration?: Time;
+ /**
+ * Gap between the clip edge and the animation: after the head for "in",
+ * before the tail for "out". Any `Time` format. Default 0.
+ */
+ delay?: Time;
+};
+
/** Caption style presets — the editor's caption inspector presets. */
export type CaptionPreset =
| "classic"
@@ -120,6 +156,11 @@ export type PatchProps = {
* merges into the clip's existing transition, `null` removes it.
*/
transition?: TransitionSpec | null;
+ /**
+ * Preset in/out animations, played over the clip's head and tail. The list
+ * replaces the node's existing animations; `[]` removes them all.
+ */
+ animations?: AnimationSpec[];
/** Any CSS color, applied to the node's solid fill (created if absent); alpha is ignored — use `opacity`. */
fill?: string;
/**
@@ -172,6 +213,7 @@ export const PATCH_PROP_KEYS = Object.keys({
sourceOut: true,
syncTo: true,
transition: true,
+ animations: true,
fill: true,
src: true,
objectFit: true,
@@ -195,7 +237,7 @@ type CommonProps = TimingProps &
Pick<
PatchProps,
| "key" | "name" | "x" | "y" | "width" | "height" | "rotation" | "opacity" | "cornerRadius"
- | "transition"
+ | "transition" | "animations"
>;
export type SceneProps = {
@@ -246,7 +288,7 @@ export type ImageProps = CommonProps &
export type AudioProps = TimingProps &
Required<Pick<PatchProps, "src">> &
- Pick<PatchProps, "name" | "volume" | "muted" | "syncTo">;
+ Pick<PatchProps, "name" | "volume" | "muted" | "syncTo" | "animations">;
export type TextProps = CommonProps &
Pick<
@@ -261,4 +303,4 @@ export type SequenceProps = Pick<PatchProps, "name"> & {
children?: SolidJSX.Element;
};
-export type CaptionsProps = Pick<PatchProps, "preset" | "colors" | "src" | "start">;
+export type CaptionsProps = Pick<PatchProps, "preset" | "colors" | "src" | "start" | "animations">;