Skip to content

The VS Code of video editing, built for agents.

TypeScript

Refactor timing traits to introduce Delay and Trim

konstantin-paulus589be2161dbd
diff --git a/apps/web/src/components/sidebar-right/inspector/time.tsx b/apps/web/src/components/sidebar-right/inspector/time.tsx
index 95119036..fe2c1bf1 100644
--- a/apps/web/src/components/sidebar-right/inspector/time.tsx
+++ b/apps/web/src/components/sidebar-right/inspector/time.tsx
@@ -33,11 +33,11 @@ import { store } from "@/init";
import { useTrait, useWorld } from "@diffusionstudio/koota-solid";
import {
Computed,
- End,
FrameRate,
Geometry,
PlaybackRate,
SourceFrameRate,
+ Trim,
findGeometryAsset,
findGeometryAssetSource,
getSequenceFrameRate,
@@ -115,13 +115,13 @@ export function TimeSettings(props: TimeSettingsProps) {
const fps = () => frameRate()?.value ?? 30;
const playbackRate = useTrait(entity, PlaybackRate);
- const authoredEnd = useTrait(entity, End);
+ const trim = useTrait(entity, Trim);
const start = useDerived(() => entity().get(Computed)?.start ?? 0);
const end = useDerived(() => entity().get(Computed)?.end ?? 0);
const isContainer = createMemo(() => isGroupLike(entity()));
- // A container authoring an End spans that rather than fitting its children.
- const hasTrim = () => authoredEnd() !== undefined;
+ // A container whose trim closes spans that rather than fitting its children.
+ const hasTrim = () => (trim()?.end ?? null) !== null;
const playbackRatePercent = createMemo(() => Math.round((playbackRate()?.value ?? 1) * 100));
diff --git a/apps/web/src/engine/editor.ts b/apps/web/src/engine/editor.ts
index 577dddb2..d06c07cd 100644
--- a/apps/web/src/engine/editor.ts
+++ b/apps/web/src/engine/editor.ts
@@ -10,7 +10,7 @@
* where the commands live.
*/
-import { Active, Background, Chars, colorToHex, Computed, DEFAULT_BACKGROUND, End, FrameRate, framesToSeconds, getActiveEntity, getEntityChildren, getEntityTree, getIntrinsicPaint, getParentEntity, getTimelineOrigin, isText, Loop, PaintType, Selected, Sequential, setActive, Size, Source, Stage, Start } from '@diffusionstudio/runtime';
+import { Active, Background, Chars, colorToHex, Computed, DEFAULT_BACKGROUND, FrameRate, framesToSeconds, getActiveEntity, getEntityChildren, getEntityTree, getIntrinsicPaint, getParentEntity, getTimelineOrigin, isText, Loop, PaintType, Selected, Sequential, setActive, Size, Source, Stage } from '@diffusionstudio/runtime';
import { isAssetRef, isPropValue, serializeAssetRef, SOURCE_ATTR } from '@diffusionstudio/jsx';
import { createRoot } from 'solid-js';
@@ -719,7 +719,7 @@ export class DocumentEditor {
* only the picture goes away: the box (a media element defaults to
* 1920x1080 where a rect is 100x100) and the span (a clip lasts its
* footage where a rect falls back to the default; the same pin the runtime
- * makes when a geometry loses its paint, see `pinEndToCurrentBounds`).
+ * makes when a geometry loses its paint, see `pinTrimToCurrentBounds`).
* Goes to the file the way the fill picker swaps a fill's kind: the
* insert of the rect, then the removal of the old element. The selection
* and the timeline's active pointer move to the rect. Returns the rect,
@@ -750,14 +750,13 @@ export class DocumentEditor {
const fps = this.world.get(FrameRate)?.value ?? 30;
if (props.start === undefined) {
- // A start the source derived (a syncTo correlation) rather than
+ // A start the runtime derived (a syncTo correlation) rather than
// the element authored.
- const start = node.get(Start)?.value ?? 0;
+ const start = Math.round((node.get(Computed)?.start ?? 0) - getTimelineOrigin(node));
if (start > 0) props.start = framesToSeconds(start, fps);
}
if (props.end === undefined) {
- const end = node.get(End)?.value
- ?? (node.get(Computed)?.end ?? 0) - getTimelineOrigin(node);
+ const end = (node.get(Computed)?.end ?? 0) - getTimelineOrigin(node);
if (end > 0) props.end = framesToSeconds(end, fps);
}
diff --git a/apps/web/src/engine/group.tsx b/apps/web/src/engine/group.tsx
index ce791717..1c9432ef 100644
--- a/apps/web/src/engine/group.tsx
+++ b/apps/web/src/engine/group.tsx
@@ -6,7 +6,6 @@ import { Group as GroupElement, Sequence as SequenceElement } from '@diffusionst
import {
AdjustmentLayer,
Computed,
- End,
Flip,
FrameRate,
Geometry,
@@ -15,7 +14,6 @@ import {
Selected,
Sequential,
Skew,
- Start,
computeLocalMatrix,
decompose2D,
entityAnchor,
@@ -36,6 +34,7 @@ import { getDocumentEditor } from './editor';
import { editTransform } from './input/interactions';
import { syncKeyframe } from './keyframes';
import { resolveNewSequenceOverlaps } from './overlap';
+import { authoredTime } from './timing';
import type { TransformWrite } from './input/interactions';
import type { Mat2D } from '@diffusionstudio/runtime';
@@ -231,9 +230,9 @@ function dissolveContainers(world: World, containers: Entity[]): void {
if (shift !== 0) {
const fps = world.get(FrameRate)?.value ?? 30;
- const start = (child.get(Start)?.value ?? 0) + shift;
+ const start = (authoredTime(world, child, 'start') ?? 0) + shift;
editor.editProperty(child, 'start', start === 0 ? false : framesToSeconds(start, fps));
- const end = child.get(End)?.value;
+ const end = authoredTime(world, child, 'end');
if (end !== undefined) editor.editProperty(child, 'end', framesToSeconds(end + shift, fps));
}
}
diff --git a/apps/web/src/engine/timeline/drag.ts b/apps/web/src/engine/timeline/drag.ts
index 036dcede..e9d2fe2d 100644
--- a/apps/web/src/engine/timeline/drag.ts
+++ b/apps/web/src/engine/timeline/drag.ts
@@ -20,7 +20,6 @@ import {
Group,
KeyframeDragOrigin,
Selected,
- Start,
TrimDragOrigin,
findAssetDuration,
store,
@@ -29,7 +28,7 @@ import { Not, Or } from 'koota';
import { clamp } from '@/utils';
import { resolveSequentialOverlaps } from '../overlap';
-import { moveEntityTo, trimIn, trimOut } from '../timing';
+import { authoredTime, moveEntityTo, trimIn, trimOut } from '../timing';
import { findSnapDelta, findSnapFrame } from './snapping';
import { framesToPixels, pixelsToFrames } from './view';
@@ -93,7 +92,7 @@ export function beginClipDrag(world: World, entity: Entity): void {
entity.add(ClipDragOrigin);
entity.set(ClipDragOrigin, {
- authored: entity.get(Start)?.value ?? 0,
+ authored: authoredTime(world, entity, 'start') ?? 0,
start: computed.start[eid] ?? 0,
end: computed.end[eid] ?? 0,
});
diff --git a/apps/web/src/engine/timing.ts b/apps/web/src/engine/timing.ts
index c42ef3ca..80d68789 100644
--- a/apps/web/src/engine/timing.ts
+++ b/apps/web/src/engine/timing.ts
@@ -5,30 +5,52 @@
/**
* 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 the traits themselves — that
+ * `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,
- End,
FrameRate,
- SourceOut,
- Start,
+ Host,
framesToSeconds,
getSourceFrameAt,
getTimelineOrigin,
+ secondsToFrames,
} 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
@@ -59,15 +81,15 @@ export function editWorkarea(world: World, scene: Entity, range: [start: number,
/**
* 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
+ * 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 (!entity.has(End)) {
+ 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.
+ // Both read the origin, which the start write moves.
const start = frame - getTimelineOrigin(entity);
const source = getSourceFrameAt(entity, frame);
editTime(world, entity, 'start', start);
@@ -77,10 +99,10 @@ export function trimIn(world: World, entity: Entity, frame: number): void {
/**
* 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.
+ * authors one; otherwise end alone says where the clip runs out.
*/
export function trimOut(world: World, entity: Entity, frame: number): void {
- if (entity.has(SourceOut)) {
+ if (authoredTime(world, entity, 'sourceOut') !== undefined) {
editTime(world, entity, 'sourceOut', getSourceFrameAt(entity, frame));
}
editTime(world, entity, 'end', frame - getTimelineOrigin(entity));
@@ -91,22 +113,22 @@ export function trimOut(world: World, entity: Entity, frame: number): void {
* 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` —
+ * 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
+ * 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 - (entity.get(Start)?.value ?? 0);
+ 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 = entity.get(End)?.value;
+ const end = authoredTime(world, entity, 'end');
if (end !== undefined) editTime(world, entity, 'end', end + delta);
editTime(world, entity, 'start', start);
diff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.ts
index de2c327f..181efdd5 100644
--- a/packages/reconciler/src/document.ts
+++ b/packages/reconciler/src/document.ts
@@ -3,7 +3,7 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-import { Active, AdjustmentLayer, Animation, AnimationPhase, AnimationType, appendChild, AssetId, Audio, Background, bindAsset, BlendMode, BlendModeType, Blur, Caption, CaptionAlign, CaptionType, Chars, ClipHeight, ClipsContent, CornerRadius, createEntity, DEFAULT_BACKGROUND, Color, ColorStop, Effect, EffectType, End, Expanded, FontStyle, FrameRate, Generating, GenerationRequest, Loop, LoadRequest, Geometry, GeometryType, getEntityTree, getParentEntity, getParentNode, Hidden, Host, IsMask, isText, ItemIndex, Keyframe, KeyframeTrack, MixedCornerRadius, Muted, Name, Offset, Opacity, Paint, PaintType, parseColor, PendingSource, Playback, PlaybackRate, Position, removeChild, RenderSurface, resizeEntity, Scale, ScaleMode, ScaleModeType, secondsToFrames, getAsset, getEntityChildren, Group, Sequential, Shader, Size, Stage, Root, Rotation, Scene, Selected, Shadow, Source, SourceError, SourceIn, SourceOut, SourceFrameRate, SourceModifiers, hasModifier, setCameraMatrix, Start, Stroke, StrokeCap, StrokeJoin, StrokeStyle, TextAlign, TextBaseline, TextCase, TextRange, TextStyle, TranscriptionRequest, Transition, TransitionType, UniformScale, Volume, Workarea } from '@diffusionstudio/runtime';
+import { Active, AdjustmentLayer, Animation, AnimationPhase, AnimationType, appendChild, AssetId, Audio, Background, bindAsset, BlendMode, BlendModeType, Blur, Caption, CaptionAlign, CaptionType, Chars, ClipHeight, ClipsContent, CornerRadius, createEntity, DEFAULT_BACKGROUND, Color, ColorStop, Delay, Effect, EffectType, Expanded, FontStyle, FrameRate, Generating, GenerationRequest, Loop, LoadRequest, Geometry, GeometryType, getEntityTree, getParentEntity, getParentNode, Hidden, Host, IsMask, isText, ItemIndex, Keyframe, KeyframeTrack, MixedCornerRadius, Muted, Name, Offset, Opacity, Paint, PaintType, parseColor, PendingSource, Playback, PlaybackRate, Position, removeChild, RenderSurface, resizeEntity, Scale, ScaleMode, ScaleModeType, secondsToFrames, getAsset, getEntityChildren, Group, Sequential, Shader, Size, Stage, Root, Rotation, Scene, Selected, Shadow, Source, SourceError, SourceFrameRate, SourceModifiers, hasModifier, setCameraMatrix, Stroke, StrokeCap, StrokeJoin, StrokeStyle, TextAlign, TextBaseline, TextCase, TextRange, TextStyle, TranscriptionRequest, Transition, TransitionType, Trim, UniformScale, Volume, Workarea } from '@diffusionstudio/runtime';
import { LOOP_ATTR, parseTime, SOURCE_ATTR } from '@diffusionstudio/jsx';
import { SVGElements } from 'solid-js/web';
import { IsExcluded } from 'koota';
@@ -122,13 +122,6 @@ function detach(node: SceneNode): void {
syncChars(parent);
}
-const TIME_TRAITS = {
- start: Start,
- end: End,
- sourceIn: SourceIn,
- sourceOut: SourceOut,
-} as const;
-
const PAINT_TYPES: Record<string, PaintType> = {
solidPaint: PaintType.SOLID,
linearGradientPaint: PaintType.LINEAR_GRADIENT,
@@ -919,11 +912,14 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {
const rate = toNumber(value);
if (rate === undefined || rate === 0) {
entity.remove(PlaybackRate);
- return;
+ } else {
+ entity.add(PlaybackRate);
+ entity.set(PlaybackRate, { value: rate });
}
- entity.add(PlaybackRate);
- entity.set(PlaybackRate, { value: rate });
+ // The rate scales the authored window onto the runtime's traits,
+ // so they are re-derived with it.
+ this.syncTiming(node);
return;
}
case 'transition': {
@@ -1076,16 +1072,7 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {
return;
}
- const trait = TIME_TRAITS[name];
- const seconds = toSeconds(value);
-
- if (seconds === undefined) {
- entity.remove(trait);
- return;
- }
-
- entity.add(trait);
- entity.set(trait, { value: this.toFrames(seconds) });
+ this.syncTiming(node);
return;
}
case 'frameRate': {
@@ -1384,6 +1371,58 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {
return secondsToFrames(seconds, this.world.get(FrameRate)?.value ?? 30);
}
+ /**
+ * Reconciles the authored time props (`start`/`end`/`sourceIn`/`sourceOut`,
+ * the copy this node holds) into the runtime's own vocabulary, Delay and
+ * Trim. Recomputed whole from the props on every one of them (and on
+ * `playbackRate`, which scales the window), so the order Solid sets them in
+ * does not matter.
+ *
+ * Delay places the node's local time 0 on its parent's timeline: the
+ * authored start, pulled back by the stretch of source the trim skips
+ * (`start - sourceIn/rate`), so the trimmed window opens at the start. The
+ * trim is the source window; an authored end becomes source frames through
+ * the rate, and whichever of it and sourceOut closes first wins. With no
+ * out bound at all the trim stays open (`end: null`) and the runtime runs
+ * the clip to its source's natural end.
+ */
+ private syncTiming(node: SceneNode): void {
+ const { entity, props } = node;
+
+ const rate = toNumber(props.playbackRate) || 1;
+ const start = toSeconds(props.start);
+ const end = toSeconds(props.end);
+ const sourceIn = toSeconds(props.sourceIn);
+ const sourceOut = toSeconds(props.sourceOut);
+
+ const startFrames = start === undefined ? 0 : this.toFrames(start);
+ const sourceInFrames = sourceIn === undefined ? 0 : this.toFrames(sourceIn);
+
+ const delay = startFrames - sourceInFrames / rate;
+ if (delay === 0) {
+ entity.remove(Delay);
+ } else {
+ entity.add(Delay);
+ entity.set(Delay, { value: delay });
+ }
+
+ let out: number | null = null;
+ if (end !== undefined) {
+ out = sourceInFrames + (this.toFrames(end) - startFrames) * rate;
+ }
+ if (sourceOut !== undefined) {
+ const frames = this.toFrames(sourceOut);
+ out = out === null ? frames : Math.min(out, frames);
+ }
+
+ if (sourceInFrames === 0 && out === null) {
+ entity.remove(Trim);
+ } else {
+ entity.add(Trim);
+ entity.set(Trim, { start: sourceInFrames, end: out });
+ }
+ }
+
/**
* Writes a track's runtime property path from its authored `property`,
* against the entity holding it (a `width` track under a stroke drives the
diff --git a/packages/runtime/src/actions/timing.ts b/packages/runtime/src/actions/timing.ts
index 70381864..86fe184c 100644
--- a/packages/runtime/src/actions/timing.ts
+++ b/packages/runtime/src/actions/timing.ts
@@ -4,80 +4,69 @@
// Time-range recomputation after structural or asset changes (was part of
// api/utils.ts). Computed is derived state (store writes, no events); the
-// authored time traits fire change events, so edits go through entity.set.
+// Delay/Trim time traits fire change events, so edits go through entity.set.
import { store } from '../world/store';
import { DEFAULT_DURATION_FRAMES } from '../constants';
import {
Geometry, Group, AdjustmentLayer, Paint, Caption, Cache, Computed,
- Start, End, SourceIn, SourceOut, PlaybackRate, CaptionDecoderHandle,
+ Delay, Trim, PlaybackRate, CaptionDecoderHandle,
} from '../traits';
import { isGroupLike } from '../queries/predicates';
import { getParentNode } from '../queries/hierarchy';
-import { findAssetDuration, getSourceFrameAt, getTimelineOrigin, isPaintEntity } from '../utils/time';
+import { findAssetDuration, getSourceFrameAt, isPaintEntity } from '../utils/time';
import type { Entity, World } from 'koota';
import type { Ignorable, TimeTrait } from '../utils/time';
/**
- * The authored value, or undefined when the node doesn't carry it. `ignore`
+ * The trait's value, or undefined when the node doesn't carry it. `ignore`
* reads one trait as absent: koota fires onRemove before it clears the trait,
* so a removal handler has to recompute against the value that is going away
* (the same reason rebuildCaches takes an exclude).
*/
-function authored(entity: Entity, trait: TimeTrait, ignore?: Ignorable): number | undefined {
+function stored(entity: Entity, trait: TimeTrait, ignore?: Ignorable): number | undefined {
return trait === ignore ? undefined : entity.get(trait)?.value;
}
+/** The node's Trim, with the same `ignore` reading as `stored`. */
+function storedTrim(entity: Entity, ignore?: Ignorable) {
+ return Trim === ignore ? undefined : entity.get(Trim);
+}
+
/**
- * How long the node lasts on its parent's timeline, in frames, from whichever
- * of the authored traits it carries.
- *
- * Each bound is optional and each one caps the duration, so when more than one
- * is present the shortest wins rather than one silently overriding another: an
- * End past the source runs out of frames, a SourceOut past the asset does too.
- * Source-side spans divide by the rate to become timeline frames. With no bound
- * at all the node runs for its whole source, or 16s when it has no source (a
- * shape or a text has nothing to run out of, so its asset length is a default
- * rather than a cap).
+ * Where the node's source window closes, in source frames. Each bound is
+ * optional and each one caps the window, so when more than one is present the
+ * shortest wins rather than one silently overriding another: a trim past the
+ * source runs out of frames. With no bound at all the node runs for its whole
+ * source, or 16s when it has no source (a shape or a text has nothing to run
+ * out of, so its asset length is a default rather than a cap).
*/
-function resolveDuration(
+function resolveSourceOut(
world: World,
entity: Entity,
- start: number,
- sourceIn: number,
+ trimStart: number,
+ trimEnd: number | null,
ignore?: Ignorable,
): number {
- const playbackRate = authored(entity, PlaybackRate, ignore) || 1;
const assetDuration = findAssetDuration(world, entity, ignore);
- let duration = Infinity;
-
- const end = authored(entity, End, ignore);
- if (end !== undefined) duration = end - start;
+ let out = trimEnd ?? Infinity;
- const sourceOut = authored(entity, SourceOut, ignore);
- if (sourceOut !== undefined) {
- duration = Math.min(duration, (sourceOut - sourceIn) / playbackRate);
- }
-
- if (assetDuration !== null) {
- duration = Math.min(duration, (assetDuration - sourceIn) / playbackRate);
- }
+ if (assetDuration !== null) out = Math.min(out, assetDuration);
- if (duration === Infinity) {
- duration = (DEFAULT_DURATION_FRAMES - sourceIn) / playbackRate;
- }
+ if (out === Infinity) out = DEFAULT_DURATION_FRAMES;
- return Math.max(0, duration);
+ return Math.max(trimStart, out);
}
/**
- * Resolve one node's authored time into its absolute bounds, origin, and rate.
+ * Resolve one node's time traits into its absolute bounds, origin, and rate.
*
- * Authored values are parent-relative; Computed is absolute, so everything
- * comparing two nodes works in one space. The rate places source frame 0, which
- * is the origin every descendant is measured against.
+ * Delay is parent-relative and Trim is in the node's own source frames;
+ * Computed is absolute, so everything comparing two nodes works in one space.
+ * The origin places source frame 0, which is what every descendant is
+ * measured against.
*/
export function recomputeEntityTimeRange(world: World, entity: Entity, ignore?: Ignorable): void {
const computed = store(world, Computed);
@@ -86,20 +75,21 @@ export function recomputeEntityTimeRange(world: World, entity: Entity, ignore?:
const parent = getParentNode(entity);
const parentOrigin = parent !== null ? (computed.origin[parent.id()] ?? 0) : 0;
- const authoredStart = authored(entity, Start, ignore) ?? 0;
- const sourceIn = authored(entity, SourceIn, ignore) ?? 0;
- const playbackRate = authored(entity, PlaybackRate, ignore) || 1;
+ const delay = stored(entity, Delay, ignore) ?? 0;
+ const playbackRate = stored(entity, PlaybackRate, ignore) || 1;
+ const trim = storedTrim(entity, ignore);
// Bounds land on frame boundaries, since everything comparing nodes works
// in whole frames, while the origin keeps its fraction so audio scheduled
// against it doesn't inherit a half-frame of slip.
- const origin = parentOrigin + authoredStart - sourceIn / playbackRate;
- const start = Math.round(parentOrigin + authoredStart);
+ const origin = parentOrigin + delay;
+ const trimStart = trim?.start ?? 0;
+ const start = Math.round(origin + trimStart / playbackRate);
computed.origin[eid] = origin;
computed.playbackRate[eid] = playbackRate;
- // A container with no End of its own spans whatever its children span.
+ // A container with no trimmed end of its own spans whatever its children span.
if (fitsChildren(entity, ignore)) {
const children = entity.get(Cache)?.children ?? [];
let fitStart = start;
@@ -124,7 +114,8 @@ export function recomputeEntityTimeRange(world: World, entity: Entity, ignore?:
return;
}
- const end = start + Math.round(resolveDuration(world, entity, authoredStart, sourceIn, ignore));
+ const sourceOut = resolveSourceOut(world, entity, trimStart, trim?.end ?? null, ignore);
+ const end = Math.max(start, Math.round(origin + sourceOut / playbackRate));
computed.start[eid] = start;
computed.end[eid] = end;
@@ -149,7 +140,7 @@ export function propagateTimeRangeDown(world: World, entity: Entity, ignore?: Ig
/**
* Walk upward recomputing any ancestor whose bounds depend on its children
- * (group-like without an explicit end). Call with the entity that changed.
+ * (group-like without a trimmed end). Call with the entity that changed.
*/
export function bubbleTimeRangeUp(world: World, child: Entity): void {
const entity = getParentNode(child);
@@ -161,59 +152,49 @@ export function bubbleTimeRangeUp(world: World, child: Entity): void {
bubbleTimeRangeUp(world, entity);
}
-/** Whether the node takes its bounds from its children rather than authoring them. */
+/** Whether the node takes its bounds from its children rather than trimming them. */
export function fitsChildren(entity: Entity, ignore?: Ignorable): boolean {
- return isGroupLike(entity) && authored(entity, End, ignore) === undefined;
+ if (!isGroupLike(entity)) return false;
+ return (storedTrim(entity, ignore)?.end ?? null) === null;
}
/**
- * Pin whatever the node currently spans as an authored End, so it keeps that
+ * Pin whatever the node currently spans as a trimmed end, so it keeps that
* span once the thing it was derived from is gone. Used when a paint is removed:
* without this the geometry silently falls back to the 16s default after losing
- * its asset source. A node that already authors an End is left alone.
+ * its asset source. A node whose trim already closes is left alone.
*/
-export function pinEndToCurrentBounds(world: World, entity: Entity): void {
- if (entity.has(End)) return;
+export function pinTrimToCurrentBounds(world: World, entity: Entity): void {
+ if ((entity.get(Trim)?.end ?? null) !== null) return;
- const end = store(world, Computed).end[entity.id()] ?? 0;
+ const computed = store(world, Computed);
+ const eid = entity.id();
+ const origin = computed.origin[eid] ?? 0;
+ const playbackRate = computed.playbackRate[eid] || 1;
+ const end = computed.end[eid] ?? 0;
- entity.add(End({ value: end - getTimelineOrigin(entity) }));
+ entity.add(Trim);
+ entity.set(Trim, { end: (end - origin) * playbackRate });
}
/**
* Move the node's in point to `frame` (scene time), keeping the rest of the
- * clip where it is: the source rolls forward by as much as the head lost, so
- * the frames left visible still line up with the timeline.
+ * clip where it is: the origin stays put and the trim opens later, so the
+ * frames left visible still line up with the timeline.
*/
export function trimEntityIn(world: World, entity: Entity, frame: number): void {
- // The out point is only implied while the node has no authored End; pin it
+ // The out point is only implied while the trim is open-ended; pin it
// before moving the head, or the tail would follow along.
- pinEndToCurrentBounds(world, entity);
+ pinTrimToCurrentBounds(world, entity);
- const start = frame - getTimelineOrigin(entity);
- const source = getSourceFrameAt(entity, frame);
-
- entity.add(Start);
- entity.set(Start, { value: start });
- entity.add(SourceIn);
- entity.set(SourceIn, { value: source });
+ entity.add(Trim);
+ entity.set(Trim, { start: getSourceFrameAt(entity, frame) });
}
-/**
- * Move the node's out point to `frame` (scene time). The source window follows
- * only if the node authors one: otherwise the End alone says where the clip
- * runs out, and leaving SourceOut absent keeps it that way.
- */
+/** Move the node's out point to `frame` (scene time): the trim closes there. */
export function trimEntityOut(_world: World, entity: Entity, frame: number): void {
- const end = frame - getTimelineOrigin(entity);
- const source = getSourceFrameAt(entity, frame);
-
- if (entity.has(SourceOut)) {
- entity.set(SourceOut, { value: source });
- }
-
- entity.add(End);
- entity.set(End, { value: end });
+ entity.add(Trim);
+ entity.set(Trim, { end: getSourceFrameAt(entity, frame) });
}
/**
@@ -243,9 +224,9 @@ export function reactToAssetChange(world: World, entity: Entity, ignore?: Ignora
/**
* Recompute the parent geometry against its new source and bubble the new
- * bounds up. Nothing authored needs fixing up: the asset length is one of the
- * caps resolveDuration takes, so a shorter source shortens the clip on its own
- * and a longer one gives back whatever the authored bounds still allow.
+ * bounds up. Nothing else needs fixing up: the asset length is one of the
+ * caps resolveSourceOut takes, so a shorter source shortens the clip on its
+ * own and a longer one gives back whatever the trim still allows.
*/
export function reactToPaintChange(world: World, paint: Entity) {
// A geometry's own Paint is its intrinsic paint: the geometry is the clip.
@@ -258,7 +239,7 @@ export function reactToPaintChange(world: World, paint: Entity) {
/**
* Recompute a geometry's bounds and bubble. Used when something other than its
- * own authored time shifts its duration (e.g. the intrinsic media its own
+ * own time traits shifts its duration (e.g. the intrinsic media its own
* asset id names).
*/
export function reactToGeometryDurationChange(world: World, entity: Entity) {
@@ -297,6 +278,6 @@ export function reactToChildDetached(world: World, child: Entity) {
if (parent === null || !parent.has(Geometry)) return;
// Pin the current duration before recomputing; otherwise the geometry
// would silently fall back to the 16s default after losing its paint.
- pinEndToCurrentBounds(world, parent);
+ pinTrimToCurrentBounds(world, parent);
}
}
diff --git a/packages/runtime/src/traits/timing.ts b/packages/runtime/src/traits/timing.ts
index 127c89a1..777df684 100644
--- a/packages/runtime/src/traits/timing.ts
+++ b/packages/runtime/src/traits/timing.ts
@@ -6,21 +6,18 @@ import { trait } from 'koota';
import { TransitionType } from '../constants';
-// The authored time of a node, in the vocabulary the JSX uses. One trait per
-// value, all frames, because a clip rarely says more than one of these things:
-// they are separate answers to separate questions, and absence is the answer
-// most nodes give. `resolveTimeRange` in actions/timing.ts fills the gaps.
-//
-// Start/End place the node on its parent's timeline. Absent Start is 0 (begin
-// with the parent), absent End is the source's natural duration, or 16s for a
-// node with no source. Scenes and groups without an End fit their children.
-export const Start = trait({ value: 0 });
-export const End = trait({ value: 0 });
-
-// SourceIn/SourceOut pick the slice of the node's own source that plays there.
-// Absent SourceIn is 0 (from the top), absent SourceOut is the natural end.
-export const SourceIn = trait({ value: 0 });
-export const SourceOut = trait({ value: 0 });
+// Offset where the node's local time 0 (source frame 0) sits on its parent's
+// timeline, in frames. May carry a fraction: audio is scheduled against it,
+// and a trimmed clip's origin sits sourceIn/rate before its first visible
+// frame. Absent is 0 (the node's time begins with its parent's).
+export const Delay = trait({ value: 0 });
+
+// The slice of the node's own source that plays, in source frames. A null
+// `end` is no fixed out point: the clip runs to its source's natural end (or
+// the 16s default for a node with no source). Absent entirely, `start` is 0
+// and scenes/groups fit their children; `resolveSourceOut` in actions/
+// timing.ts fills the gaps.
+export const Trim = trait({ start: 0, end: null as number | null });
// Frames per second a frames-directory source is played at, which is the only
// thing that says how long it lasts: a folder of pictures has a count, not a
diff --git a/packages/runtime/src/utils/time.ts b/packages/runtime/src/utils/time.ts
index 0d33116c..6fc54032 100644
--- a/packages/runtime/src/utils/time.ts
+++ b/packages/runtime/src/utils/time.ts
@@ -4,8 +4,8 @@
import { CONONICAL_TIME_BASE, PaintType } from '../constants';
import {
- Audio, AssetId, Cache, Computed, Geometry, Paint, SourceIn, Library, FrameRate,
- Start, IsMask, SourceFrameRate,
+ Audio, AssetId, Cache, Computed, Geometry, Paint, Trim, Library, FrameRate,
+ Delay, IsMask, PlaybackRate, SourceFrameRate,
} from '../traits';
import { getParentNode } from '../queries/hierarchy';
import { getSourceDuration } from '../actions/assets';
@@ -60,9 +60,9 @@ export function formatTimecode(seconds: number, frameRate: number): string {
}
/**
- * The scene frame that authored time 0 means for `entity`, its parent's
+ * The scene frame that local time 0 means for `entity`, its parent's
* origin. Converts between the absolute frames Computed works in and the
- * parent-relative frames Start and End are authored in.
+ * parent-relative frames Delay is expressed in.
*/
export function getTimelineOrigin(entity: Entity): number {
const parent = getParentNode(entity);
@@ -81,11 +81,11 @@ export function getSourceFrameAt(entity: Entity, frame: number): number {
/**
* The node's resolved source window, in source frames: where its in point is
* and how far its timeline span actually reaches into the source. Derived from
- * the resolved duration rather than read off SourceOut, so a window the node
- * never gets to play (an End that runs out first) is not reported as playing.
+ * the resolved duration rather than read off Trim's end, so a window the node
+ * never gets to play (a source the trim outruns) is not reported as playing.
*/
export function getSourceWindow(entity: Entity): { in: number; out: number } {
- const sourceIn = entity.get(SourceIn)?.value ?? 0;
+ const sourceIn = entity.get(Trim)?.start ?? 0;
const computed = entity.get(Computed);
const duration = computed?.duration ?? 0;
const playbackRate = computed?.playbackRate || 1;
@@ -140,18 +140,18 @@ export function findGeometryAsset(world: World, entity: Entity): Asset | null {
}
/**
- * One of the authored time traits: Start, End, SourceIn, SourceOut,
- * PlaybackRate, SourceFrameRate. They all carry a single frame count (or rate).
+ * A single-value time trait: Delay, PlaybackRate, SourceFrameRate. Each
+ * carries one frame count (or rate).
*/
-export type TimeTrait = typeof Start;
+export type TimeTrait = typeof Delay | typeof PlaybackRate | typeof SourceFrameRate;
/**
- * A trait a recompute may read as absent: one of the authored time traits, or
- * the node's own AssetId (its intrinsic media, another source of a length).
+ * A trait a recompute may read as absent: one of the time traits, or the
+ * node's own AssetId (its intrinsic media, another source of a length).
* koota fires onRemove before it clears the trait, so a removal handler has to
* ask for the length the node will have once it is gone.
*/
-export type Ignorable = TimeTrait | typeof AssetId | typeof IsMask;
+export type Ignorable = TimeTrait | typeof Trim | typeof AssetId | typeof IsMask;
/**
* Intrinsic duration (in project frames) of the media asset attached to an
diff --git a/packages/runtime/src/world/observers.ts b/packages/runtime/src/world/observers.ts
index fc749a57..f3268c60 100644
--- a/packages/runtime/src/world/observers.ts
+++ b/packages/runtime/src/world/observers.ts
@@ -6,7 +6,7 @@
import { store } from './store';
import {
ChildOf, Culled, Sequential, Group, Scene, Audio, Paint, AssetId,
- Start, End, SourceIn, SourceOut, PlaybackRate, SourceFrameRate, Keyframe, ItemIndex,
+ Delay, Trim, PlaybackRate, SourceFrameRate, Keyframe, ItemIndex,
Position, Offset, Rotation, Scale, UniformScale, Skew, Anchor, Flip,
Opacity, Color, Blur, Volume, Effect, CornerRadius, MixedCornerRadius,
ColorStop, StrokeStyle, Size, Computed, Active, Stage, IsMask,
@@ -161,7 +161,7 @@ export function observeWorld(world: World): () => void {
bubbleTimeRangeUp(world, entity);
};
- for (const trait of [Start, End, SourceIn, SourceOut, PlaybackRate]) {
+ for (const trait of [Delay, Trim, PlaybackRate]) {
subs.push(world.onAdd(trait, propagateAndBubble));
subs.push(world.onChange(trait, propagateAndBubble));
subs.push(world.onRemove(trait, (entity) => {
diff --git a/packages/runtime/src/world/serialize.ts b/packages/runtime/src/world/serialize.ts
index 90ec17e5..fa6f4f95 100644
--- a/packages/runtime/src/world/serialize.ts
+++ b/packages/runtime/src/world/serialize.ts
@@ -12,7 +12,7 @@ import {
Opacity, BlendMode, Color, CornerRadius, MixedCornerRadius, Blur, ScaleMode, Effect,
ColorStop, StrokeStyle, Shader,
Chars, TextStyle,
- Start, End, SourceIn, SourceOut, PlaybackRate, SourceFrameRate,
+ Delay, Trim, PlaybackRate, SourceFrameRate,
Playback, Sequential, Transition, ClipHeight, Expanded,
Volume, Muted,
KeyframeTrack, Keyframe, Animation, Stage,
@@ -127,10 +127,11 @@ export interface EntityRecord {
Playback?: {
loop?: number;
};
- Start?: number;
- End?: number;
- SourceIn?: number;
- SourceOut?: number;
+ Delay?: number;
+ Trim?: {
+ start: number;
+ end: number | null;
+ };
PlaybackRate?: number;
SourceFrameRate?: number;
Constraint?: {
@@ -334,17 +335,12 @@ export function serializeEntity(entity: Entity): EntityRecord {
loop: entity.get(Playback)!.loop ? 1 : 0,
};
}
- if (entity.has(Start)) {
- record.Start = entity.get(Start)!.value;
- }
- if (entity.has(End)) {
- record.End = entity.get(End)!.value;
- }
- if (entity.has(SourceIn)) {
- record.SourceIn = entity.get(SourceIn)!.value;
+ if (entity.has(Delay)) {
+ record.Delay = entity.get(Delay)!.value;
}
- if (entity.has(SourceOut)) {
- record.SourceOut = entity.get(SourceOut)!.value;
+ if (entity.has(Trim)) {
+ const trim = entity.get(Trim)!;
+ record.Trim = { start: trim.start, end: trim.end };
}
if (entity.has(SourceFrameRate)) {
record.SourceFrameRate = entity.get(SourceFrameRate)!.value;
@@ -584,17 +580,11 @@ export function deserializeEntity(entity: Entity, e: Partial<EntityRecord>): voi
entity.add(Playback);
entity.set(Playback, { loop: !!e.Playback.loop });
}
- if (e.Start !== undefined) {
- entity.add(Start({ value: e.Start }));
- }
- if (e.End !== undefined) {
- entity.add(End({ value: e.End }));
- }
- if (e.SourceIn !== undefined) {
- entity.add(SourceIn({ value: e.SourceIn }));
+ if (e.Delay !== undefined) {
+ entity.add(Delay({ value: e.Delay }));
}
- if (e.SourceOut !== undefined) {
- entity.add(SourceOut({ value: e.SourceOut }));
+ if (e.Trim !== undefined) {
+ entity.add(Trim({ start: e.Trim.start, end: e.Trim.end }));
}
if (e.SourceFrameRate !== undefined) {
entity.add(SourceFrameRate({ value: e.SourceFrameRate }));