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/. */
/**
* Moving and trimming clips. A gesture lives on the entities it touches — the
* snapshot traits say a drag is in flight and what it started from — rather
* than in a variable here, so a clip scrolled off screen and back is still
* being dragged, and so the drag survives the frame it began on.
*
* Every write goes through the editor's time props, so dragging a clip in the
* timeline is the same edit as typing its start into the inspector.
*/
import {
AdjustmentLayer,
ClipDragOrigin,
Computed,
Geometry,
Group,
Keyframe,
KeyframeDragOrigin,
Selected,
TrimDragOrigin,
findAssetDuration,
findClosestParentGeometry,
framesToSeconds,
store,
} from '@diffusionstudio/runtime';
import { Not, Or } from 'koota';
import { clamp } from '@/utils';
import { getDocumentEditor } from '../editor';
import { resolveSequentialOverlaps } from '../overlap';
import { authoredTime, moveEntityTo, trimIn, trimOut } from '../timing';
import { findSnapDelta, findSnapFrame } from './snapping';
import { framesToPixels, getFrameRate, getResolution, pixelsToFrames } from './view';
import type { Entity, World } from 'koota';
import type { TimelineSurfaceState } from './surface';
const NODES = Or(Geometry, Group, AdjustmentLayer);
/** Which edge of a clip a trim is holding. */
export type TrimEdge = 'in' | 'out';
/**
* Opens and closes the gestures in flight, once a frame before anything is
* drawn.
*
* Closing is what has to happen here rather than where the drag was applied:
* a gesture ends when the pointer is let go, which is not an event any clip
* receives — the clip only ever hears that it is still being dragged.
*/
export function updateDragGestures(world: World, scene: Entity, surface: TimelineSurfaceState): void {
const position = surface.pointer?.position;
const dragging = !!position && position.state !== 'idle';
if (!dragging) {
endGesture(world, ClipDragOrigin);
endGesture(world, TrimDragOrigin);
// Keyframes have no sequence to settle: they sit where they are put.
for (const keyframe of world.query(KeyframeDragOrigin)) keyframe.remove(KeyframeDragOrigin);
return;
}
// A drag of a selected clip is a drag of the selection, so the rest of it
// is snapshotted the moment the first clip starts moving. Done here, once,
// rather than per clip: a clip scrolled out of view is not drawn, and it
// would otherwise be left behind by the drag.
if (world.query(NODES, ClipDragOrigin, Selected).length > 0) {
for (const entity of world.query(NODES, Selected, Not(ClipDragOrigin))) {
beginClipDrag(world, entity);
}
}
// Keyframes likewise, and moved here rather than where they are drawn: a
// selected keyframe scrolled out of view, or on a collapsed track, still
// has to go with the rest.
if (world.query(KeyframeDragOrigin, Selected).length > 0) {
for (const keyframe of world.query(Keyframe, Selected, Not(KeyframeDragOrigin))) {
beginKeyframeDrag(keyframe);
}
}
for (const keyframe of world.query(KeyframeDragOrigin)) {
applyKeyframeDrag(world, scene, surface, keyframe);
}
}
/**
* Ends whichever gesture `origin` marks: the snapshots come off, and the
* sequences the clips landed in are settled around them (the clips that moved
* win, and their neighbours give way).
*/
function endGesture(world: World, origin: typeof ClipDragOrigin | typeof TrimDragOrigin): void {
const moved = [...world.query(NODES, origin)];
if (moved.length === 0) return;
for (const entity of moved) entity.remove(origin);
resolveSequentialOverlaps(world, moved);
}
/** Notes where `entity` is, so the frames of the drag can be measured from it. */
export function beginClipDrag(world: World, entity: Entity): void {
const computed = store(world, Computed);
const eid = entity.id();
entity.add(ClipDragOrigin);
entity.set(ClipDragOrigin, {
authored: authoredTime(world, entity, 'start') ?? 0,
start: computed.start[eid] ?? 0,
end: computed.end[eid] ?? 0,
});
}
/**
* Places `entity` at where it started plus how far the pointer has come,
* pulled to a snap if one is near, and never before the start of the scene.
*/
export function applyClipDrag(
world: World,
surface: TimelineSurfaceState,
entity: Entity,
resolution: number,
): void {
const origin = entity.get(ClipDragOrigin)!;
const floor = -earliestDraggedStart(world);
const offset = Math.max(pixelsToFrames(draggedPixels(surface), resolution), floor);
// One snap for the whole drag, found from every clip in it — unless it
// would pull the drag back past the floor the pointer just hit.
const snap = findSnapDelta(world, resolution, offset);
const snapped = snap !== null && offset - snap.delta >= floor;
if (snapped) surface.snapX = framesToPixels(snap.frame, resolution);
moveEntityTo(world, entity, origin.start + offset - (snapped ? snap.delta : 0));
}
/** Where the first clip of the drag in flight started, from the snapshots. */
function earliestDraggedStart(world: World): number {
const origins = store(world, ClipDragOrigin);
let earliest = Number.POSITIVE_INFINITY;
for (const entity of world.query(NODES, ClipDragOrigin)) {
earliest = Math.min(earliest, origins.start[entity.id()] ?? 0);
}
return Number.isFinite(earliest) ? earliest : 0;
}
/** Notes where `keyframe` is, in its clip's own time. */
export function beginKeyframeDrag(keyframe: Entity): void {
keyframe.add(KeyframeDragOrigin);
keyframe.set(KeyframeDragOrigin, { time: keyframe.get(Keyframe)?.time ?? 0 });
}
/**
* Places `keyframe` at where it started plus how far the pointer has come. A
* keyframe's time is a prop of its element, so a drag of it is an edit like
* any other.
*/
function applyKeyframeDrag(world: World, scene: Entity, surface: TimelineSurfaceState, keyframe: Entity): void {
const origin = keyframe.get(KeyframeDragOrigin)!;
// The pointer moves in scene frames; the keyframe lives in the clip's,
// which run `rate` times as fast.
const rate = findClosestParentGeometry(keyframe)?.get(Computed)?.playbackRate || 1;
const moved = pixelsToFrames(draggedPixels(surface), getResolution(world, scene)) * rate;
getDocumentEditor(world).editProperty(
keyframe,
'time',
framesToSeconds(Math.max(0, origin.time + moved), getFrameRate(world)),
);
}
/** Notes where `entity`'s edges are, so a trim can be measured from them. */
export function beginTrim(world: World, entity: Entity): void {
const computed = store(world, Computed);
const eid = entity.id();
entity.add(TrimDragOrigin);
entity.set(TrimDragOrigin, {
start: computed.start[eid] ?? 0,
end: computed.end[eid] ?? 0,
});
}
/**
* Moves the edge being held to where the pointer has taken it, within what
* the clip can actually do: never past its other edge, and never past the end
* of what it has to play.
*/
export function applyTrim(
world: World,
surface: TimelineSurfaceState,
entity: Entity,
edge: TrimEdge,
resolution: number,
): void {
const origin = entity.get(TrimDragOrigin)!;
const offset = pixelsToFrames(draggedPixels(surface), resolution);
const [min, max] = trimBounds(world, entity, edge, origin);
const wanted = (edge === 'in' ? origin.start : origin.end) + offset;
// Snapped only where the snap is somewhere the edge could have gone
// anyway; otherwise it would look like it stuck and then slipped.
const snapped = findSnapFrame(world, resolution, wanted);
const frame = clamp(snapped !== null && snapped > min && snapped < max ? snapped : wanted, min, max);
if (snapped !== null && frame === snapped) surface.snapX = framesToPixels(frame, resolution);
if (edge === 'in') trimIn(world, entity, frame);
else trimOut(world, entity, frame);
}
/**
* How far the edge can go. Each clip is its own row, so a neighbour is no
* constraint — only the clip's other edge, and how much source there is left
* to show at this end.
*/
function trimBounds(
world: World,
entity: Entity,
edge: TrimEdge,
origin: { start: number; end: number },
): [min: number, max: number] {
let min = edge === 'in' ? 0 : origin.start + 1;
let max = edge === 'in' ? origin.end - 1 : Number.POSITIVE_INFINITY;
const duration = findAssetDuration(world, entity);
if (duration === null) return [min, max];
const computed = entity.get(Computed);
const rate = computed?.playbackRate || 1;
// The scene frame the source starts at, and the one it runs out at.
const sourceStart = computed?.origin ?? 0;
if (edge === 'in') min = Math.max(min, sourceStart);
else max = Math.min(max, sourceStart + duration / rate);
return [min, max];
}
/** How far the pointer has come since the press, in pixels. */
function draggedPixels(surface: TimelineSurfaceState): number {
const position = surface.pointer?.position;
return position && position.state !== 'idle' ? position.deltaX : 0;
}
/** Whether a gesture is currently moving `entity`. */
export function isDragging(entity: Entity): boolean {
return entity.has(ClipDragOrigin) || entity.has(TrimDragOrigin);
}