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/. */
/**
* The DOM around the timeline: which canvas it draws on, how big that is,
* and what the wheel does to it. Everything it changes is view state on the
* scene (see `./view`), which the draw pass reads back a frame later — the
* controller itself never paints.
*/
import { AdjustmentLayer, Geometry, Group, getSelection, getTimelineView } from '@diffusionstudio/runtime';
import { Or } from 'koota';
import { assert, clamp } from '@/utils';
import { getDocumentEditor } from '@/engine/editor';
import { createPointer } from './pointer';
import { TimelineSurface } from './surface';
import { timelineSystem } from './timeline';
import {
getResolution,
getScrollX,
getScrollY,
getTimelineScene,
pixelsToFrames,
setResolution,
setScrollX,
setScrollY,
updateTimelineTransform,
} from './view';
import {
SCROLL_X_SENSITIVITY,
TIMELINE_RESOLUTION_RANGE,
WHEEL_LINE_HEIGHT,
WHEEL_PAGE_HEIGHT,
ZOOM_DELTA_CLAMP,
ZOOM_SENSITIVITY,
} from './config';
import { getFrameRate } from './view';
import type { Entity, World } from 'koota';
export type TimelineController = ReturnType<typeof createTimelineController>;
export function createTimelineController(world: World) {
const surface = world.get(TimelineSurface)!;
const pointer = createPointer({
get marquee() { return surface.marquee; },
get canvas() { return surface.canvas; },
get ctx() { return surface.ctx; },
});
let layersEl: HTMLElement | null = null;
let layersViewportEl: HTMLElement | null = null;
// How far the row labels have been scrolled sideways, in pixels. A DOM
// concern rather than the scene's: it is the same for every scene.
let layerScrollX = 0;
/** Runs `action` against the scene on show, if there is one. */
const withScene = (action: (scene: Entity) => void): void => {
const scene = getTimelineScene(world);
if (scene !== null) action(scene);
};
/**
* A gesture moved the view: report it so the file remembers where the
* scene's timeline is looking (`<scene timeline>`), the way the camera
* controller reports a pan. No `previous`, so it never enters the history.
*/
const reportView = (scene: Entity): void => {
const view = getTimelineView(world, scene);
if (view) getDocumentEditor(world).reportEdit(scene, 'timeline', view);
};
const applyResize = (): void => {
const { canvas } = surface;
const parent = canvas?.parentElement;
if (!parent || !canvas) return;
surface.layout = parent.getBoundingClientRect();
applyScroll();
const dpr = window.devicePixelRatio;
canvas.style.width = `${surface.layout.width}px`;
canvas.style.height = `${surface.layout.height}px`;
const width = Math.floor(surface.layout.width * dpr);
const height = Math.floor(surface.layout.height * dpr);
if (canvas.width === width && canvas.height === height) return;
canvas.width = width;
canvas.height = height;
};
const resize = (): void => {
applyResize();
withScene((scene) => updateTimelineTransform(world, scene));
timelineSystem(world);
};
const observer = new ResizeObserver(resize);
const layerObserver = new ResizeObserver(() => {
applyScroll();
withScene((scene) => updateTimelineTransform(world, scene));
});
/**
* Moves the row labels to match the scroll the canvas is drawn at. They
* are DOM, so they cannot be drawn scrolled — they are translated instead,
* and the scroll is clamped to what there is to scroll through.
*/
const applyScroll = (): void => {
if (!layersEl || !layersViewportEl) return;
withScene((scene) => {
const scrollY = clamp(getScrollY(world, scene), 0, Math.max(0, layersEl!.scrollHeight - layersViewportEl!.clientHeight));
setScrollY(world, scene, scrollY);
layersEl!.style.transform = `translateY(${-scrollY}px)`;
});
// The labels scroll sideways only as far as the widest one overflows.
let maxScrollX = 0;
for (const label of layersEl.querySelectorAll<HTMLElement>('[data-layer-label]')) {
maxScrollX = Math.max(maxScrollX, label.scrollWidth - label.clientWidth);
}
layerScrollX = clamp(layerScrollX, 0, maxScrollX);
layersEl.style.setProperty('--layer-x', `${layerScrollX}px`);
};
/**
* One axis at a time, in the order the gesture is most likely to have
* meant: zoom while a modifier is held, then whichever of the two scroll
* axes the wheel moved further in.
*/
const handleWheel = (event: WheelEvent): void => {
event.preventDefault();
withScene((scene) => {
const { deltaX, deltaY } = normalizeWheel(event);
const resolution = getResolution(world, scene);
const scrollX = getScrollX(world, scene);
if (event.ctrlKey || event.metaKey) {
const rect = surface.canvas?.getBoundingClientRect();
const anchor = event.clientX - (rect?.left ?? 0);
const delta = clamp(deltaY, -ZOOM_DELTA_CLAMP, ZOOM_DELTA_CLAMP);
const next = clamp(
resolution * Math.exp(-delta * ZOOM_SENSITIVITY),
1 / TIMELINE_RESOLUTION_RANGE[1],
1 / TIMELINE_RESOLUTION_RANGE[0],
);
// The frame under the pointer stays under it: the scroll takes
// up whatever the change in scale moved it by.
setResolution(world, scene, next);
setScrollX(world, scene, scrollX + anchor / resolution - anchor / next);
} else {
// Shift is a sideways gesture, and a mouse wheel reports it on
// deltaY: Windows and Linux swap only the browser's default
// action, never the event's axes, so `deltaX` stays 0 and the
// axis has to be read out of the deltas instead.
const [wheelX, wheelY] = shiftScroll(event.shiftKey, deltaX, deltaY);
if (Math.abs(wheelX) > Math.abs(wheelY)) {
setScrollX(world, scene, scrollX + (wheelX * SCROLL_X_SENSITIVITY) / resolution);
} else {
setScrollY(world, scene, getScrollY(world, scene) + wheelY);
applyScroll();
}
}
updateTimelineTransform(world, scene);
reportView(scene);
});
};
/** The wheel over the row labels, which scroll but do not zoom. */
const scroll = (event: WheelEvent): void => {
event.preventDefault();
withScene((scene) => {
const { deltaX, deltaY } = normalizeWheel(event);
const [wheelX, wheelY] = shiftScroll(event.shiftKey, deltaX, deltaY);
if (Math.abs(wheelX) > Math.abs(wheelY)) {
layerScrollX += wheelX;
} else {
setScrollY(world, scene, getScrollY(world, scene) + wheelY);
}
applyScroll();
updateTimelineTransform(world, scene);
reportView(scene);
});
};
/** Programmatic vertical scroll, for gestures that hold near an edge. */
const scrollBy = (deltaY: number): void => {
withScene((scene) => {
setScrollY(world, scene, getScrollY(world, scene) + deltaY);
applyScroll();
updateTimelineTransform(world, scene);
reportView(scene);
});
};
const clientToFrame = (clientX: number): number => {
const scene = getTimelineScene(world);
if (scene === null) return 0;
const resolution = getResolution(world, scene);
const rect = surface.canvas?.getBoundingClientRect();
return pixelsToFrames(clientX - (rect?.left ?? 0) + getScrollX(world, scene) * resolution, resolution);
};
const clientToTime = (clientX: number): number => clientToFrame(clientX) / getFrameRate(world);
/**
* The nodes a right-click at `event` is on. A clip's regions are scoped
* to its entity's id (see `renderClip`), so the scope names the node; a
* keyframe's is scoped to its track, which is not one, and stands for
* what is selected, as do the ruler and the work area. Empty over the
* space behind the rows.
*/
const nodesAt = (event: MouseEvent): Entity[] => {
const rect = surface.canvas?.getBoundingClientRect();
if (!rect) return [];
const scope = pointer.regionAt(event.clientX - rect.left, event.clientY - rect.top)?.split('/')[0];
if (scope === undefined || scope === 'canvas') return [];
const node = world.query(Or(Geometry, Group, AdjustmentLayer)).find((entity) => String(entity.id()) === scope);
return node ? [node] : getSelection(world);
};
const setMinimized = (minimized: boolean): void => {
surface.minimized = minimized;
};
const attachCanvas = (): void => {
const canvas = document.getElementById('timeline-canvas') as HTMLCanvasElement | null;
assert(canvas, 'Timeline canvas must be defined');
const parent = canvas.parentElement;
assert(parent, 'Timeline canvas must have a parent element');
surface.canvas = canvas;
surface.ctx = canvas.getContext('2d');
surface.layout = parent.getBoundingClientRect();
observer.observe(parent);
canvas.addEventListener('wheel', handleWheel);
canvas.addEventListener('pointerdown', pointer.down, { passive: true });
applyResize();
};
const detachCanvas = (): void => {
observer.disconnect();
surface.canvas?.removeEventListener('wheel', handleWheel);
surface.canvas?.removeEventListener('pointerdown', pointer.down);
// Dropped rather than kept stale: the draw pass no-ops until another
// canvas is attached.
surface.canvas = null;
surface.ctx = null;
};
/**
* The row labels and the pointer, which outlive the canvas: the timeline
* can be collapsed and reopened without the rows going anywhere.
*/
const mount = (): void => {
const layers = document.querySelector<HTMLElement>('[data-timeline-layers]');
assert(layers, 'Timeline layers element must be defined');
const viewport = document.querySelector<HTMLElement>('[data-timeline-layers-viewport]');
assert(viewport, 'Timeline layers viewport element must be defined');
layersEl = layers;
layersViewportEl = viewport;
surface.pointer = pointer;
layerObserver.observe(layers);
// On the body, so a drag that leaves the canvas still finishes.
document.body.addEventListener('pointermove', pointer.move, { passive: true });
document.body.addEventListener('pointerup', pointer.up, { passive: true });
};
const unmount = (): void => {
layerObserver.disconnect();
surface.pointer = null;
document.body.removeEventListener('pointermove', pointer.move);
document.body.removeEventListener('pointerup', pointer.up);
};
return {
mount,
unmount,
attachCanvas,
detachCanvas,
scroll,
scrollBy,
clientToFrame,
clientToTime,
nodesAt,
setMinimized,
};
}
/**
* Wheel deltas in the units the event says they are in. A line or a page is
* whatever the platform decides; pixels are the only comparable unit.
*/
function normalizeWheel(event: WheelEvent): { deltaX: number; deltaY: number } {
const scale = event.deltaMode === WheelEvent.DOM_DELTA_LINE
? WHEEL_LINE_HEIGHT
: event.deltaMode === WheelEvent.DOM_DELTA_PAGE
? WHEEL_PAGE_HEIGHT
: 1;
return { deltaX: event.deltaX * scale, deltaY: event.deltaY * scale };
}
/**
* The deltas as the gesture meant them. With Shift held the wheel is a
* sideways one, but only a trackpad and macOS say so in the event: on
* Windows and Linux a mouse keeps reporting it on `deltaY`, because the
* browser swaps its default action rather than the event's axes. A delta
* that arrived on its own axis wins over one that has to be borrowed.
*/
function shiftScroll(shift: boolean, deltaX: number, deltaY: number): [number, number] {
if (!shift) return [deltaX, deltaY];
return Math.abs(deltaY) > Math.abs(deltaX) ? [deltaY, 0] : [deltaX, 0];
}