Skip to content

The VS Code of video editing, built for agents.

TypeScript

Implement transition support in JSX and rendering systems. Introduce `transition` prop for clips within `<sequence>`, allowing for various transition types and durations. Update related type definitions and documentation to reflect these changes, ensuring clarity on usage and behavior of transitions in the composition system.

konstantin-paulus7acdd6200865
diff --git a/apps/web/src/utils/jsx.ts b/apps/web/src/utils/jsx.ts
index 2cf851e0..16aeef47 100644
--- a/apps/web/src/utils/jsx.ts
+++ b/apps/web/src/utils/jsx.ts
@@ -17,6 +17,7 @@ import {
ScaleMode,
TextAlign,
TextBaseline,
+ TransitionType,
addComponent,
appendChild,
computeAudioSyncOffsetCached,
@@ -154,6 +155,31 @@ function parseKeyframes(
return keyframes.sort((a, b) => a.time - b.time);
}
+const TRANSITION_TYPE_MAP = {
+ dissolve: TransitionType.DISSOLVE,
+ slideFromRight: TransitionType.SLIDE_FROM_RIGHT,
+ slideFromLeft: TransitionType.SLIDE_FROM_LEFT,
+ fadeToBlack: TransitionType.FADE_TO_BLACK,
+ fadeToWhite: TransitionType.FADE_TO_WHITE,
+} as const;
+
+// 1 second at the canonical 30 fps — the transition inspector's default.
+const TRANSITION_DEFAULT_DURATION = 30;
+
+function parseTransitionType(value: unknown): number {
+ assert(typeof value === "string", "transition `type` must be a string" + `, value: ${value}`);
+ const type = TRANSITION_TYPE_MAP[value as keyof typeof TRANSITION_TYPE_MAP];
+ assert(type !== undefined, `invalid transition type: "${value}"`);
+ return type;
+}
+
+function parseTransitionDuration(value: unknown): number {
+ const frames = parseFrames(String(value), 30);
+ assert(typeof frames === "number", "transition `duration` must be a time value" + `, value: ${value}`);
+ assert(frames > 0, "transition `duration` must be > 0");
+ return frames;
+}
+
const CAPTION_PRESET_MAP = {
classic: CaptionType.CLASSIC,
cascade: CaptionType.CASCADE,
@@ -276,75 +302,97 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {
public createElement(tag: string): DocumentNode {
const world = this.world;
const c = world.components;
- const eid = createEntity(world);
- const node: DocumentNode = { kind: "element", eid };
switch (tag) {
case "scene": {
+ const eid = createEntity(world);
+ const node: DocumentNode = { kind: "element", eid };
setComponent(world, eid, c.Geometry, GeometryType.RECT);
addComponent(world, eid, c.Scene);
addComponent(world, eid, c.ClipsContent);
setComponent(world, eid, c.Name, getNextName(world, "Scene"));
- break;
+ return node;
} case "group": {
+ const eid = createEntity(world);
+ const node: DocumentNode = { kind: "element", eid };
setComponent(world, eid, c.Geometry, GeometryType.RECT);
addComponent(world, eid, c.Group);
setComponent(world, eid, c.Name, getNextName(world, "Group"));
- break;
+ return node;
} case "rect": {
+ const eid = createEntity(world);
+ const node: DocumentNode = { kind: "element", eid };
setComponent(world, eid, c.Geometry, GeometryType.RECT);
setComponent(world, eid, c.Name, getNextName(world, "Rect"));
- break;
+ return node;
} case "sequence": {
+ const eid = createEntity(world);
+ const node: DocumentNode = { kind: "element", eid };
addComponent(world, eid, c.Group);
addComponent(world, eid, c.Sequential);
setComponent(world, eid, c.Name, getNextName(world, "Sequence"));
- break;
+ return node;
} case "video": {
+ const eid = createEntity(world);
+ const node: DocumentNode = { kind: "element", eid };
setComponent(world, eid, c.Geometry, GeometryType.RECT);
setComponent(world, eid, c.Name, getNextName(world, "Video"));
- break;
+ return node;
} case "image": {
+ const eid = createEntity(world);
+ const node: DocumentNode = { kind: "element", eid };
setComponent(world, eid, c.Geometry, GeometryType.RECT);
setComponent(world, eid, c.Name, getNextName(world, "Image"));
- break;
+ return node;
} case "audio": {
+ const eid = createEntity(world);
+ const node: DocumentNode = { kind: "element", eid };
addComponent(world, eid, c.Audio);
setComponent(world, eid, c.Geometry, GeometryType.RECT);
setComponent(world, eid, c.Name, getNextName(world, "Audio"));
- break;
+ return node;
} case "text": {
+ const eid = createEntity(world);
+ const node: DocumentNode = { kind: "element", eid };
setComponent(world, eid, c.Geometry, GeometryType.TEXT);
const fid = createEntity(world);
setComponent(world, fid, c.Paint, PaintType.SOLID);
setComponent(world, fid, c.Color, 0xffffff);
appendChild(world, fid, eid);
- break;
+ return node;
} case "captions": {
+ const eid = createEntity(world);
+ const node: DocumentNode = { kind: "element", eid };
setComponent(world, eid, c.Geometry, GeometryType.TEXT);
setComponent(world, eid, c.Caption, {});
setComponent(world, eid, c.Name, getNextName(world, "Captions"));
this.queue.push({ node, type: "caption" });
- break;
+ return node;
} case "solidPaint": {
+ const eid = createEntity(world);
+ const node: DocumentNode = { kind: "element", eid };
setComponent(world, eid, c.Paint, PaintType.SOLID);
setComponent(world, eid, c.Color, 0xE0E0E0);
- break;
+ return node;
} case "linearGradientPaint": {
+ const eid = createEntity(world);
+ const node: DocumentNode = { kind: "element", eid };
setComponent(world, eid, c.Paint, PaintType.LINEAR_GRADIENT);
- break;
+ return node;
} case "radialGradientPaint": {
+ const eid = createEntity(world);
+ const node: DocumentNode = { kind: "element", eid };
setComponent(world, eid, c.Paint, PaintType.RADIAL_GRADIENT);
- break;
+ return node;
} case "colorStop": {
+ const eid = createEntity(world);
+ const node: DocumentNode = { kind: "element", eid };
setComponent(world, eid, c.ColorStop, {});
- break;
+ return node;
} default: {
assert(false, `unknown tag: "${tag}"`);
}
}
-
- return node;
}
public createTextNode(text: string): DocumentNode {
@@ -584,6 +632,26 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {
assert(value.trim().length > 0, "`syncTo` must be a non-empty string");
this.queue.push({ node, targetKey: value.trim(), type: "sync" });
break;
+ } case "transition": {
+ if (value === null) {
+ removeComponent(world, eid, c.Transition);
+ break;
+ }
+ assert(
+ typeof value === "object" && !Array.isArray(value),
+ "`transition` must be a { type?, duration? } object or null" + `, value: ${value}`,
+ );
+ const { type, duration } = value as Record<string, unknown>;
+ const spec: { type?: number; duration?: number } = {};
+ if (type !== undefined) spec.type = parseTransitionType(type);
+ if (duration !== undefined) spec.duration = parseTransitionDuration(duration);
+
+ if (!hasComponent(world, eid, c.Transition)) {
+ spec.type ??= TransitionType.DISSOLVE;
+ spec.duration ??= TRANSITION_DEFAULT_DURATION;
+ }
+ setComponent(world, eid, c.Transition, spec);
+ break;
} case "src": {
if (isAssetRef(value)) {
world.history.untrack(() => addComponent(world, eid, c.Generating));
@@ -822,6 +890,7 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {
setComponent(world, eid, c.Name, asset.name);
}
+
}
function placeholderSize(spec: AssetSpecInput): { width: number; height: number } {
diff --git a/docs/cli.md b/docs/cli.md
index 42752713..586d896f 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -69,7 +69,7 @@ dapi node insert <paintId> --code '<colorStop offset={0.5} color="#FF0055" />'
dapi node patch ([path.json] | --json <str>)
```
-Assigns JSX props on existing entities. The payload is an array of `{ id, …props }`, taking exactly the props a JSX element takes (see the [element reference](composition.md#elements)). A rejected entry applies none of its props. Renaming is patching `name`; recoloring is patching `fill`; paints and color stops are patchable too.
+Assigns JSX props on existing entities. The payload is an array of `{ id, …props }`, taking exactly the props a JSX element takes (see the [element reference](composition.md#elements)). A rejected entry applies none of its props. Renaming is patching `name`; recoloring is patching `fill`; paints and color stops are patchable too. A [transition](composition.md#transitions) is patched as a `transition` prop on the outgoing clip (`null` removes it).
```sh
dapi node patch --json '[{ "id": 42, "x": 100, "opacity": 0.5 }]'
diff --git a/docs/composition.md b/docs/composition.md
index 072620e1..0c5b4a0e 100644
--- a/docs/composition.md
+++ b/docs/composition.md
@@ -54,6 +54,7 @@ User-defined components are ordinary Solid components; only intrinsic elements p
| `opacity` | `1` | `0`–`1`. Animatable. |
| `cornerRadius` | `0` | Px. Animatable. |
| `inPoint`, `outPoint`, `startTime` | see [Timing](#timing) | Temporal placement. |
+| `transition` | none | Cut into the next clip; `<sequence>` children only. See [Transitions](#transitions). |
Animatable props also take a keyframe list — see [Animation](#animation).
@@ -110,6 +111,29 @@ Composition-relative, Lottie-inspired. Values take any [time format](cli.md#time
`syncTo` and `startTime` are mutually exclusive; `inPoint`/`outPoint` stay yours, and when omitted the window defaults to the overlap with the target's window. Alignment runs after generated assets land (either side may be generated), locally and cached, and blocks the mount; an alignment too weak to trust fails the mount and the node keeps its default placement.
+## Transitions
+
+A clip inside a `<sequence>` takes a `transition` prop rendering the cut into the clip that follows it:
+
+```tsx
+<sequence>
+ <video src="/Movies/a.mp4" outPoint={8} transition={{ type: "fadeToBlack", duration: 0.5 }} />
+ <video src="/Movies/b.mp4" />
+</sequence>
+```
+
+| Type | Effect |
+| --- | --- |
+| `"dissolve"` (default) | Crossfade: the incoming clip fades in over the outgoing one. |
+| `"slideFromRight"` | The incoming clip slides in over the outgoing one, decelerating. |
+| `"slideFromLeft"` | Same, from the left. |
+| `"fadeToBlack"` | Dip to black: fade out, then fade the incoming clip in. |
+| `"fadeToWhite"` | Same, through white. |
+
+- `duration` takes any [time format](cli.md#time-values) (default 1 s) and runs centered on the cut. Timing is untouched: the clips stay back-to-back and the renderer overlaps them only while the transition runs.
+- `transition` only renders on a direct child of `<sequence>` that has a clip after it. On the last clip it waits until one follows, matching the editor's inspector; outside a sequence the engine drops it.
+- It's the same transition the inspector edits, and `dapi node patch` takes it like any other prop: a partial value merges into the clip's existing transition (`{ "id": 42, "transition": { "duration": 2 } }` keeps the type), and `"transition": null` removes it.
+
## Animation
Animatable props (`x`, `y`, `width`, `height`, `rotation`, `opacity`, `cornerRadius`, `volume`, `color`, `offset`) accept a keyframe list in place of a static value:
diff --git a/packages/solid/src/index.ts b/packages/solid/src/index.ts
index b0d2669a..ff1ecc5b 100644
--- a/packages/solid/src/index.ts
+++ b/packages/solid/src/index.ts
@@ -24,6 +24,8 @@ export type {
SolidPaintProps,
TextProps,
Time,
+ TransitionSpec,
+ TransitionType,
VideoProps,
} from "./types";
diff --git a/packages/solid/src/types.ts b/packages/solid/src/types.ts
index 185d4c73..d93299dc 100644
--- a/packages/solid/src/types.ts
+++ b/packages/solid/src/types.ts
@@ -47,6 +47,22 @@ export type Keyframe<T> = {
*/
export type Animatable<T> = T | Keyframe<T>[];
+/** Transition styles — the editor's transition inspector options. */
+export type TransitionType =
+ | "dissolve"
+ | "slideFromRight"
+ | "slideFromLeft"
+ | "fadeToBlack"
+ | "fadeToWhite";
+
+/** The `transition` prop's value — see `PatchProps["transition"]`. */
+export type TransitionSpec = {
+ /** Transition style. Default "dissolve". */
+ type?: TransitionType;
+ /** Length of the transition, centered on the cut. Any `Time` format. Default 1 second. */
+ duration?: Time;
+};
+
/** Caption style presets — the editor's caption inspector presets. */
export type CaptionPreset =
| "classic"
@@ -96,6 +112,12 @@ export type PatchProps = {
* timeline. Mutually exclusive with `startTime`.
*/
syncTo?: string;
+ /**
+ * Transition into the next clip, rendered centered on the cut, set on the
+ * outgoing clip. Only on direct children of `<sequence>`; a partial value
+ * merges into the clip's existing transition, `null` removes it.
+ */
+ transition?: TransitionSpec | null;
/** Any CSS color, applied to the node's solid fill (created if absent); alpha is ignored — use `opacity`. */
fill?: string;
/** Path, URL, asset id, or a `generate.*` declaration. */
@@ -142,6 +164,7 @@ export const PATCH_PROP_KEYS = Object.keys({
outPoint: true,
startTime: true,
syncTo: true,
+ transition: true,
fill: true,
src: true,
objectFit: true,
@@ -164,7 +187,8 @@ type TimingProps = Pick<PatchProps, "inPoint" | "outPoint" | "startTime">;
type CommonProps = TimingProps &
Pick<
PatchProps,
- "key" | "name" | "x" | "y" | "width" | "height" | "rotation" | "opacity" | "cornerRadius"
+ | "key" | "name" | "x" | "y" | "width" | "height" | "rotation" | "opacity" | "cornerRadius"
+ | "transition"
>;
export type SceneProps = {