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/. */
/**
* Where a node sits on the timeline, moved the way every editor change moves:
* the document for the canvas, an edit for the file. The runtime has
* `trimEntityIn`/`trimEntityOut`, which write Delay/Trim themselves — that
* moves the clip on screen and nowhere else — so everything that trims a clip
* (the inspector's fields, the timeline's handles, a split) goes through here
* instead, and the file hears about it.
*
* The runtime no longer stores the file's time vocabulary: it reconciles
* `start`/`end`/`sourceIn`/`sourceOut` down to Delay and Trim. What a node
* authors is read back from the copy its host node keeps (`authoredTime`),
* which is what these edits rewrite.
*/
import {
Computed,
FrameRate,
Host,
framesToSeconds,
getSourceFrameAt,
getTimelineOrigin,
secondsToFrames,
setPlayhead,
store,
} from '@diffusionstudio/runtime';
import { parseTime } from '@diffusionstudio/jsx';
import { getDocumentEditor } from './editor';
import type { Time } from '@diffusionstudio/jsx';
import type { Entity, World } from 'koota';
/** The time a node authors, in the vocabulary of the JSX rather than the traits'. */
export type TimeProp = 'start' | 'end' | 'sourceIn' | 'sourceOut';
/**
* The time prop as the node's host holds it, in frames of this project, or
* undefined while the element doesn't author it. The authored copy rather
* than the traits: Delay and Trim fold the four props together, and an edit
* has to know what the file actually says to rewrite it.
*/
export function authoredTime(world: World, entity: Entity, name: TimeProp): number | undefined {
const value = entity.get(Host)?.props[name];
const seconds = typeof value === 'number' || typeof value === 'string'
? parseTime(value as Time | string)
: undefined;
if (seconds === undefined) return undefined;
return secondsToFrames(seconds, world.get(FrameRate)?.value ?? 30);
}
/**
* Writes a time prop from a frame count of this project; the file spells
* times in seconds. `null` unsets it: the document drops the trait, and the
* writer spells it as the attribute's absence (`false` is the one PropValue
* it removes for). A `start` or `sourceIn` of 0 is unset too, since absence
* is what 0 reads as on those.
*/
export function editTime(world: World, entity: Entity, name: TimeProp, frames: number | null): void {
const unset = frames === null || (frames === 0 && (name === 'start' || name === 'sourceIn'));
const fps = world.get(FrameRate)?.value ?? 30;
getDocumentEditor(world).editProperty(entity, name, unset ? false : framesToSeconds(frames, fps));
}
/**
* Writes the scene's work area from a frame range of this project, or takes
* it off with `null`. The file spells it in seconds like every other time,
* and `false` is the value the writer drops the attribute for.
*/
export function editWorkarea(world: World, scene: Entity, range: [start: number, end: number] | null): void {
const fps = world.get(FrameRate)?.value ?? 30;
getDocumentEditor(world).editProperty(
scene,
'workarea',
range ? [framesToSeconds(range[0], fps), framesToSeconds(range[1], fps)] : false,
);
}
/**
* Seeks the scene to `frame` and tells the file where the playhead now rests
* (`<scene playhead>`), so the project reopens there. Only a gesture on the
* timeline seeks this way: a step, a keyframe jump or playback itself moves
* the playhead with `setPlayhead` and no word to the file — a write per frame
* of playback is not worth what it costs — so the file lags until the next
* scrub. No `previous`, so it never enters the history. The first frame is
* reported as `false`, which the writer spells as the attribute's absence.
*/
export function editPlayhead(world: World, scene: Entity, frame: number): void {
setPlayhead(world, scene, frame);
const fps = world.get(FrameRate)?.value ?? 30;
const at = store(world, Computed).localTime[scene.id()] ?? 0;
getDocumentEditor(world).reportEdit(scene, 'playhead', at === 0 ? false : framesToSeconds(at, fps));
}
/**
* Moves the node's in point to scene frame `frame`, keeping the rest of the
* clip where it is: the runtime's `trimEntityIn`, as edits. The out point is
* only implied while the node authors no end, so it is pinned first, or the
* tail would follow the head; then start moves and sourceIn rolls forward by
* as much as the head lost.
*/
export function trimIn(world: World, entity: Entity, frame: number): void {
if (authoredTime(world, entity, 'end') === undefined) {
editTime(world, entity, 'end', (entity.get(Computed)?.end ?? 0) - getTimelineOrigin(entity));
}
// Both read the origin, which the start write moves.
const start = frame - getTimelineOrigin(entity);
const source = getSourceFrameAt(entity, frame);
editTime(world, entity, 'start', start);
editTime(world, entity, 'sourceIn', source);
}
/**
* Moves the node's out point to scene frame `frame` (the runtime's
* `trimEntityOut`, as edits). The source window follows only when the node
* authors one; otherwise end alone says where the clip runs out.
*/
export function trimOut(world: World, entity: Entity, frame: number): void {
if (authoredTime(world, entity, 'sourceOut') !== undefined) {
editTime(world, entity, 'sourceOut', getSourceFrameAt(entity, frame));
}
editTime(world, entity, 'end', frame - getTimelineOrigin(entity));
}
/**
* Moves the node so it starts at scene frame `frame`, keeping everything else
* about it: the same stretch of its source plays, for the same length, only
* later or earlier.
*
* Start and end are both parent-relative — a node's length is `end - start` —
* so a move is both of them by the same amount. Writing only the start would
* leave the end where it was and stretch the clip, which is a trim.
*
* A container that takes its bounds from its children authors no end, and so
* only its start moves: its children are placed against its origin, and they
* all travel with it.
*/
export function moveEntityTo(world: World, entity: Entity, frame: number): void {
const start = frame - getTimelineOrigin(entity);
const delta = start - (authoredTime(world, entity, 'start') ?? 0);
if (delta === 0) return;
// Before the start, which moves the origin the end would then be read
// against — both are worked out from what the node says now.
const end = authoredTime(world, entity, 'end');
if (end !== undefined) editTime(world, entity, 'end', end + delta);
editTime(world, entity, 'start', start);
}