The VS Code of video editing, built for agents.
TypeScript
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
/**
* Keyframes as edits. In the source a keyframed prop is a `<keyframeTrack
* property>` under the element whose prop it drives, holding `<keyframe time
* value easing>` children; so adding a keyframe inserts an element, changing
* one writes its `value`, and removing the last one removes the track. These
* are the runtime's `toggleKeyframeTrack`/`syncKeyframeTrack`/
* `removeKeyframeTrack` in that vocabulary, routed through the editor so the
* file hears about them. Properties are named as the JSX names them
* (`AnimatableProperty`), the way a track in the file is.
*/
import { Keyframe as KeyframeElement, KeyframeTrack as KeyframeTrackElement, trackPropertyPath } from "@diffusionstudio/reconciler";
import {
Cache,
ChildOf,
Keyframe,
KeyframeTrack,
FrameRate,
colorToHex,
findKeyframeTargetNode,
formatPath,
framesToSeconds,
getNodeLocalFrame,
getPathGeometry,
getParentEntity,
getPropertyPaths,
Paint,
PaintType,
} from "@diffusionstudio/runtime";
import type { AnimatableProperty } from "@diffusionstudio/jsx";
import type { Entity, World } from "koota";
import type { DocumentEditor } from "./editor";
/** The track driving `target`'s `property`, if any. */
export function findKeyframeTrack(world: World, target: Entity, property: AnimatableProperty): Entity | null {
const path = trackPropertyPath(target, property);
if (!path) return null;
for (const track of world.query(KeyframeTrack, ChildOf(target))) {
if (track.get(KeyframeTrack)!.property === path) return track;
}
return null;
}
/** The keyframe of `track` at local `frame`, if any. */
export function findKeyframeAt(track: Entity, frame: number): Entity | null {
const keyframes = track.get(Cache)?.keyframes ?? [];
return keyframes.find((keyframe) => Math.round(keyframe.get(Keyframe)!.time) === frame) ?? null;
}
/** The local frame `target`'s keyframes are authored at: its node's, in the node's source time. */
export function keyframeFrame(target: Entity): number | null {
const node = findKeyframeTargetNode(target);
return node === null ? null : getNodeLocalFrame(node);
}
/**
* The value of `target`'s `property` as shown right now: the computed one,
* which is what a keyframe added here should hold. Colors come back as the
* CSS hex a color track's keyframe is spelled with, outlines as path data.
*/
function currentValue(world: World, target: Entity, property: AnimatableProperty): number | string | null {
// An outline, as the path data a `d` keyframe is spelled with.
if (property === "d") {
const geometry = getPathGeometry(world, target);
return geometry === null ? null : formatPath(geometry);
}
const path = trackPropertyPath(target, property);
if (!path) return null;
const value = getPropertyPaths(world)[path]?.computed[target.id()];
if (typeof value !== "number") return null;
return property === "color" ? colorToHex(value) : value;
}
/** A keyframe's `time` as the file spells it: seconds of this project's frame rate. */
function keyframeTime(world: World, frame: number): number {
return framesToSeconds(frame, world.get(FrameRate)?.value ?? 30);
}
/**
* Writes a keyframe for `target`'s `property` at the current local frame
* holding `value` (the shown value when omitted): the keyframe already there
* takes the value, else one is inserted, into the track or into a new track.
* Returns the keyframe, or null when the target is not keyframable (no node
* above it, no source to write under, a property it does not have).
*/
export function writeKeyframe(world: World, editor: DocumentEditor, target: Entity, property: AnimatableProperty, value?: number | string): Entity | null {
const frame = keyframeFrame(target);
if (frame === null) return null;
const held = value ?? currentValue(world, target, property);
if (held === null) return null;
const track = findKeyframeTrack(world, target, property);
const existing = track && findKeyframeAt(track, frame);
if (existing) {
editor.editProperty(existing, "value", held);
return existing;
}
const time = keyframeTime(world, frame);
if (track) {
const [keyframe] = editor.insertElement(track, () => <KeyframeElement time={time} value={held} />);
return keyframe ?? null;
}
const [created] = editor.insertElement(target, () => (
<KeyframeTrackElement property={property}>
<KeyframeElement time={time} value={held} />
</KeyframeTrackElement>
));
return created ? findKeyframeAt(created, frame) : null;
}
/**
* Adds a keyframe for `target`'s `property` at the current local frame, or
* removes the one already there; the track goes with its last keyframe.
*/
export function toggleKeyframe(world: World, editor: DocumentEditor, target: Entity, property: AnimatableProperty): void {
const frame = keyframeFrame(target);
if (frame === null) return;
const track = findKeyframeTrack(world, target, property);
const existing = track && findKeyframeAt(track, frame);
if (!existing) {
writeKeyframe(world, editor, target, property);
return;
}
const last = (track.get(Cache)?.keyframes.length ?? 0) <= 1;
editor.remove(last ? track : existing);
}
/**
* Keeps a keyframed prop's track in step with an edit of its value: the
* keyframe at the current frame takes `value`, or one is added holding it.
* Nothing happens without a track; editing surfaces call this after
* writing the prop, since the motion system would otherwise overwrite the
* edit on the next tick.
*/
export function syncKeyframe(world: World, editor: DocumentEditor, target: Entity, property: AnimatableProperty, value: number | string): void {
if (findKeyframeTrack(world, target, property) === null) return;
writeKeyframe(world, editor, target, property, value);
}
/** Removes the track driving `target`'s `property`, keyframes included. */
export function removeKeyframeTrack(world: World, editor: DocumentEditor, target: Entity, property: AnimatableProperty): void {
const track = findKeyframeTrack(world, target, property);
if (track) editor.remove(track);
}
/**
* `entities` plus every track they would leave without keyframes, so that
* removing a track's last keyframes removes the track too.
*/
export function withEmptiedTracks(entities: Entity[]): Entity[] {
const doomed = new Set(entities);
for (const entity of entities) {
if (!entity.has(Keyframe)) continue;
const track = getParentEntity(entity);
if (!track?.has(KeyframeTrack) || doomed.has(track)) continue;
const keyframes = track.get(Cache)?.keyframes ?? [];
if (keyframes.every((keyframe) => doomed.has(keyframe))) doomed.add(track);
}
return [...doomed];
}
/** The props a paint's keyframe holds, by what the paint is. A gradient's stops keep their own. */
function paintProperties(paint: Entity): AnimatableProperty[] {
switch (paint.get(Paint)?.value ?? PaintType.SOLID) {
case PaintType.SOLID:
return ["color", "opacity"];
case PaintType.LINEAR_GRADIENT:
return ["opacity", "x1", "y1", "x2", "y2"];
case PaintType.RADIAL_GRADIENT:
case PaintType.ANGULAR_GRADIENT:
return ["opacity", "cx", "cy", "rx", "ry", "rotation"];
default:
return ["opacity"];
}
}
/**
* The tracks behind a paint's keyframe. Only its own props count: a stroke
* standing in as its own paint also holds a `width` track, which is not one.
*/
export function findPaintKeyframeTracks(world: World, paint: Entity): Entity[] {
const paths: (string | undefined)[] = paintProperties(paint).map((property) => trackPropertyPath(paint, property));
return [...world.query(KeyframeTrack, ChildOf(paint))].filter((track) => paths.includes(track.get(KeyframeTrack)!.property));
}
/**
* A paint has one keyframe for all its props. With any of them keyed at the
* current frame, those keyframes are removed (each track with its last);
* otherwise every prop is keyed at its shown value.
*/
export function togglePaintKeyframe(world: World, editor: DocumentEditor, paint: Entity): void {
const frame = keyframeFrame(paint);
if (frame === null) return;
const existing: Entity[] = [];
for (const track of findPaintKeyframeTracks(world, paint)) {
const keyframe = findKeyframeAt(track, frame);
if (!keyframe) continue;
const last = (track.get(Cache)?.keyframes.length ?? 0) <= 1;
existing.push(last ? track : keyframe);
}
if (existing.length > 0) {
editor.remove(existing);
return;
}
for (const property of paintProperties(paint)) writeKeyframe(world, editor, paint, property);
}