Skip to content

The VS Code of video editing, built for agents.

TypeScript

Refactor timing traits and entity management in Runtime

konstantin-paulus4e15ad775c99
diff --git a/packages/encoder/src/encoder.ts b/packages/encoder/src/encoder.ts
index 300fff98..f7b70a80 100644
--- a/packages/encoder/src/encoder.ts
+++ b/packages/encoder/src/encoder.ts
@@ -16,7 +16,8 @@ import {
playbackSystem, motionSystem, transformSystem, renderSystem,
AudioBus, AudioBusHandle,
ChildOf, Geometry, Group, Paint, Workarea, Playback,
- AudioPlayback, Computed, Delay, Trim, Transition, Keyframe, Animation,
+ AudioPlayback, Computed, Start, End, SourceIn, SourceOut,
+ Transition, Keyframe, Animation,
Position, Offset, Rotation, Scale, Skew,
Project, Mode, Time, FrameRate, RenderSurface, AudioEngine, Root,
resetCamera,
@@ -430,21 +431,20 @@ function rescaleFrameTimestamps(
const ratio = targetFrameRate / sourceFrameRate;
const rescale = (v: number) => Math.round(v * ratio);
- const delay = store(world, Delay);
- const trim = store(world, Trim);
const transition = store(world, Transition);
const keyframe = store(world, Keyframe);
const animation = store(world, Animation);
- for (const entity of world.query(Or(Delay, Trim, Transition, Keyframe, Animation))) {
- const eid = entity.id();
- if (entity.has(Delay)) {
- delay.value[eid] = rescale(delay.value[eid] ?? 0);
- }
- if (entity.has(Trim)) {
- trim.start[eid] = rescale(trim.start[eid] ?? 0);
- trim.end[eid] = rescale(trim.end[eid] ?? 0);
+ for (const trait of [Start, End, SourceIn, SourceOut]) {
+ const values = store(world, trait).value;
+ for (const entity of world.query(trait)) {
+ const eid = entity.id();
+ values[eid] = rescale(values[eid] ?? 0);
}
+ }
+
+ for (const entity of world.query(Or(Transition, Keyframe, Animation))) {
+ const eid = entity.id();
if (entity.has(Transition)) {
transition.duration[eid] = rescale(transition.duration[eid] ?? 0);
}
diff --git a/packages/encoder/src/image-encoder.ts b/packages/encoder/src/image-encoder.ts
index d7c58d1a..ad3533fe 100644
--- a/packages/encoder/src/image-encoder.ts
+++ b/packages/encoder/src/image-encoder.ts
@@ -44,13 +44,16 @@ export async function createImageEncoder(sourceWorld: World, config: ImageEncode
const records = subtree.map(entity => serializeEntity(entity));
// Re-root the node. Its parent isn't part of the clone, so a dangling
- // ChildOf would attach to an arbitrary entity in the new world; Delay and
- // Hidden only mean something on the timeline it was lifted out of.
+ // ChildOf would attach to an arbitrary entity in the new world;
const rootRecord = records.find(record => record.eid === config.entity);
assert(rootRecord !== undefined, `No such entity: ${config.entity}`);
delete rootRecord.ChildOf;
- delete rootRecord.Delay;
delete rootRecord.Hidden;
+ const rootStart = rootRecord.Start ?? 0;
+ delete rootRecord.Start;
+ if (rootRecord.End !== undefined) {
+ rootRecord.End -= rootStart;
+ }
const offscreenCanvas = new OffscreenCanvas(2, 2);
const offscreenCtx = offscreenCanvas.getContext('2d')!;
@@ -96,8 +99,8 @@ export async function createImageEncoder(sourceWorld: World, config: ImageEncode
recomputeAllTimeRanges(world);
- // Map "frame 0 = first visible frame": with Delay stripped the node's
- // computed start is 0 unless it carries a Trim, whose start offsets it.
+ // Map "frame 0 = first visible frame": the node now starts at 0, and its
+ // source window puts its own in point there.
const startFrame = computed.start[root.id()] ?? 0;
// Entities in the clone that own a timeline clock
diff --git a/packages/runtime/MIGRATION.md b/packages/runtime/MIGRATION.md
index ab81d7e0..4eb18e17 100644
--- a/packages/runtime/MIGRATION.md
+++ b/packages/runtime/MIGRATION.md
@@ -24,11 +24,11 @@ Working doc for migrating the editor engine from bitecs (in `apps/web/src/compon
| Transform system | `src/systems/transform.ts` | Store-indexed hot path (`store()` + `entity.id()`), no snapshots, no change events. Roots = `ChildOf(getDocument(world))`. Headless world without canvas skips culling instead of crashing |
| Motion system | `src/systems/motion.ts` | resetAnimatedValues + getPropertyPaths (property table) + sampleTrack + applyAnimation. animejs dep. See semantic notes |
| Moved verbatim | `src/math/*`, `src/utils/{text-motion,live-mounts}.ts`, `src/fonts/types.ts` | All dependency-free |
-| Time utils | `src/utils/time.ts` | snap/frames helpers, `computeTrimStart/End` (entity-based), `findGeometryAsset`, `findAssetDuration` (Assets + FrameRate world traits). `src/utils/assert.ts` added (was `@/utils`) |
+| Time utils | `src/utils/time.ts` | snap/frames helpers, `getTimelineOrigin`/`getSourceFrameAt`/`getSourceWindow` (entity-based), `findGeometryAsset`, `findAssetDuration` (Assets + FrameRate world traits). `src/utils/assert.ts` added (was `@/utils`) |
| Asset/folder model | `src/assets/types.ts`, world traits `Assets`/`Folders`/`AssetIds` | Structural types (no zod); `AssetFileHandle = { getFile() }` so node/Electron handles satisfy it. sqids dep for id allocation |
| Actions: entities, hierarchy | `src/actions/{entities,hierarchy}.ts` | See semantic notes. `createEntity` spawns Computed (with non-default width/height/end/duration/strokeWidth) + Cache + ChildOf(document) |
-| Actions: cache + timing upkeep | `src/actions/{cache,timing}.ts` | Split of `api/utils.ts`: rebuildCaches/aggregateKeyframeTracks/findClosestParentGeometry; recomputeEntityTimeRange, propagate/bubble, trim clamp/pin, reactTo* hooks |
-| Actions: resize, keyframe, overlap | `src/actions/{resize,keyframe,overlap}.ts` | Constraint seeding = ConstraintCache trait presence (was undefined store slots). Overlap uses cloneSubtree + computeTrimStart/End |
+| Actions: cache + timing upkeep | `src/actions/{cache,timing}.ts` | Split of `api/utils.ts`: rebuildCaches/aggregateKeyframeTracks/findClosestParentGeometry; resolveDuration/recomputeEntityTimeRange, propagate/bubble, pinEndToCurrentBounds, trimEntityIn/Out, reactTo* hooks |
+| Actions: resize, keyframe, overlap | `src/actions/{resize,keyframe,overlap}.ts` | Constraint seeding = ConstraintCache trait presence (was undefined store slots). Overlap uses cloneSubtree + trimEntityIn/Out |
| Actions: group, frame, clipboard | `src/actions/{group,frame,clipboard}.ts` | frame.ts also hosts `switchActiveScene` (was api/base.ts): sets the ActiveScene world trait, nothing else |
| Actions: assets, folders (model) | `src/actions/{assets,folders}.ts` | allocateId/raiseIdCounter, appendAssets/upsertAsset/removeAssets, getAssetFile/Blob, insertAssetInTimeline; folder tree ops return changed records for app persistence |
| Observers (runtime half) | `src/world/observers.ts` | koota subscriptions wiring cache upkeep, Computed mirrors, and time-range reactions; auto-registered by `createRuntimeWorld` (returns a disposer). See semantic notes |
@@ -59,6 +59,19 @@ Every world spawns one entity tagged `DocumentRoot` (`createRuntimeWorld`). All
- `ChildOf = relation({ exclusive: true, autoDestroy: 'orphan' })`, so `getDocument(world).destroy()` tears down the whole document; clearing a project = destroy + respawn root.
- Actions honor this: `createEntity` spawns as a document child; `appendChild` asserts `getParentNode(entity) === null` ("already has a parent" = has a non-document parent) and relies on exclusive re-targeting; `removeChild` re-parents to the document instead of dropping ChildOf. `cloneFromRecords` attaches parentless records to the document, so paste/duplicate roots land there too.
+## Authored time model
+
+`Delay` and `Trim` were replaced by four one-value traits carrying the vocabulary the JSX authors in, all frames: `Start`, `End`, `SourceIn`, `SourceOut`. Start/End place the node on its parent's timeline (parent-relative), SourceIn/SourceOut pick the slice of its own source that plays there. `PlaybackRate` is unchanged and stays authored.
+
+One trait per value rather than one trait with four fields, 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. A razor cut authors an `End` and nothing else; a clip dropped at the playhead authors a `Start` and nothing else.
+
+- **Defaults** (`resolveDuration` in `actions/timing.ts`): absent Start is 0, absent SourceIn is 0, and an absent bound means the node runs for its whole source, or 16s (`DEFAULT_DURATION_FRAMES`) when it has no source. Scenes and groups without an End still fit their children.
+- **Every bound caps, so the shortest wins.** With more than one present, none silently overrides another: an End that reaches past the source runs out of frames, a SourceOut past the asset does too, and the asset length caps both. Source-side spans divide by the rate to become timeline frames. The asset length only participates when there is an asset: a shape or a text has nothing to run out of, so its 16s is a default rather than a cap.
+- Because the caps are read at resolve time, nothing rewrites authored values behind the user's back. `clampTrimToAssetDuration` is gone: swapping in a shorter asset shortens the clip on its own, and swapping a longer one back in gives the authored bounds their reach again.
+- `Computed.delay` was renamed `Computed.origin` (the scene frame carrying source frame 0, which is what the field always held) and `Computed.playbackRate` joined it as a mirror, so the per-frame path reads the rate from the same record as the bounds it scales. `Computed.start/end` land on whole frames; `origin` keeps its fraction so audio scheduled against it doesn't inherit a half-frame of slip.
+- Editing helpers replaced the old frame-math ones: `trimEntityIn/Out(world, entity, frame)` move an in/out point at a scene frame (`computeTrimStart/End` only produced the local frame and left callers to write the trait). `trimEntityIn` pins the implied End first, so trimming the head no longer drags the tail along, and writes SourceIn since a head trim is what defines one. `trimEntityOut` writes SourceOut only when the node already carries one, keeping the common case down to a single trait. Overlap resolution (trim/split on drop) is the only runtime caller so far.
+- The five traits share one observer loop (add/change/remove all propagate through the subtree, since a child is placed against its parent's origin). Removal passes the trait being removed down to `recomputeEntityTimeRange` as `ignore`, because koota fires onRemove *before* it clears the trait: without that, `entity.remove(End)` would compute against the End that is going away. Same koota quirk `rebuildCaches`'s `exclude` param exists for.
+
## Deliberate semantic changes vs bitecs
- Single-value components became `{ value }` traits (Rotation, Name, Volume, Geometry, Paint, ...). `Playback.playing/loop` and `AudioPlayback.wasPlaying` are booleans on the trait, mapped to/from 0/1 at the serialize boundary.
@@ -69,10 +82,9 @@ Every world spawns one entity tagged `DocumentRoot` (`createRuntimeWorld`). All
- Actions are plain world-first functions (matching queries/systems), not koota `createActions`: they return entities/records and call each other freely, which the bound-record pattern only obscures. No history layer: bitecs `world.history.push/transaction` wrappers are gone; actions write directly and the app groups undo steps by observing koota events. Selection-scoped actions (group, frame, reorderSelection, clipboard) still key off the runtime-defined `Selected` trait.
- appendChild/removeChild dropped their bitecs side calls: `persistEntity`, `syncInteractiveState`, `rebuildTimelineIndex` (app-side via observers/signals) and `disconnectAudioBus` (media slice; decoder/bus disposal hooks return with it). `unpersistEntity` and the dispose* helpers from `api/utils.ts` were likewise not ported yet.
- Observers: the runtime half of `api/observers.ts` became koota subscriptions in `world/observers.ts` (`observeWorld`, auto-registered by `createRuntimeWorld`). appendChild/removeChild are assert + re-target only; cache/size/constraint/time-range fixups ride the ChildOf add/remove events, so `cloneFromRecords`/restore prime Cache, Computed, and time ranges through the same path as actions. `rebuildCaches`/`aggregateKeyframeTracks` take an `exclude` param because koota fires relation remove events while the departing child is still in the old parent's queries.
-- Observer-driven behavior faithful to bitecs: Sequential onAdd group-ifies and strips spatial traits; Group/Scene/Audio onAdd, Paint/AssetId/Delay/PlaybackRate/Trim onChange, and Trim onRemove run the timing recomputes; Keyframe/ItemIndex onChange resort caches; ChildOf onRemove rebuilds caches (+ `reactToChildDetached`, skipped when the parent is already destroyed); Trim onAdd defaults `end` to the current Computed.duration (the bitecs setComponent fallback). Authored→Computed mirrors register on add and change; trait removal does not reset Computed (same as bitecs).
+- Observer-driven behavior faithful to bitecs: Sequential onAdd group-ifies and strips spatial traits; Group/Scene/Audio onAdd and Paint/AssetId onChange run the timing recomputes; Start/End/SourceIn/SourceOut/PlaybackRate add/change/remove propagate them through the subtree; Keyframe/ItemIndex onChange resort caches; ChildOf onRemove rebuilds caches (+ `reactToChildDetached`, skipped when the parent is already destroyed). Authored→Computed mirrors register on add and change; trait removal does not reset Computed (same as bitecs).
- Not faithful on purpose: keyframe auto-sync on authored edits did not move into observers. koota change events don't say which field changed, and syncing every field of a trait would mint spurious keyframes on untouched properties. Editing surfaces call `syncKeyframeTrack` for the property they changed (resizeEntity already does for width/height).
- Size propagation is a Size observer now (`propagateSize` on add/change): bitecs restored sizes through `resizeEntity`, koota deserialization is a plain set. `resizeEntity` no longer calls propagateSize itself.
-- `clampTrimToAssetDuration` now goes through `entity.set(Trim)` (fires change events) but only when actually clamping; bitecs wrote the store silently. The Trim onChange handler re-enters once through the clamp and no-ops on the second pass.
- Still app-side from `api/observers.ts`: persistence scheduling, timeline index rebuilds, `syncInteractiveState`, Selected waveform show/hide, ClipHeight/Expanded, ExportSettings defaults, drag-origin traits.
- Media handle traits renamed with a `Handle` suffix (`VideoDecoderHandle`, `AudioBusHandle`, ...) and typed to the concrete classes via type-only imports, so the trait and the class it stores (`AudioDecoder`, `HtmlHost`, ...) share one export surface without colliding. Resolvers are entity-based (`resolveVideoDecoder(world, entity)`), read Assets/Mode world traits, and store instances with add+set on the handle trait.
- Dispose hooks are observers now: every `*Handle` trait disposes its value onRemove (destroy removes all traits, so deletion is covered without a subtree walk), Culled onAdd disposes decoders, ChildOf add/remove disconnects audio buses, and `reactToAssetChange`'s Caption branch drops the caption decoder. `src/media/dispose.ts` keeps only `disposeDecoders`/`disconnectAudioBus` for the still-alive cases.
diff --git a/packages/runtime/src/actions/assets.ts b/packages/runtime/src/actions/assets.ts
index 854a0854..2967bdc0 100644
--- a/packages/runtime/src/actions/assets.ts
+++ b/packages/runtime/src/actions/assets.ts
@@ -10,8 +10,8 @@ import Sqids from 'sqids';
import { GeometryType, PaintType } from '../constants';
import {
- Geometry, Paint, Audio, Caption, Hidden, Name, AssetId, Delay, Trim,
- KeepAspectRatio, Computed, Assets, AssetIds, ActiveScene,
+ Geometry, Paint, Audio, Caption, Hidden, Name, AssetId, Start, SourceIn,
+ SourceOut, KeepAspectRatio, Computed, Assets, AssetIds, ActiveScene,
} from '../traits';
import { store } from '../world/store';
import { secondsToFrames } from '../utils/time';
@@ -124,18 +124,18 @@ export async function insertAssetInTimeline(
const scene = world.get(ActiveScene)?.entity ?? null;
if (scene === null) return null;
- const delay = mode === 'playhead' ? store(world, Computed).localTime[scene.id()] ?? 0 : 0;
+ const start = mode === 'playhead' ? store(world, Computed).localTime[scene.id()] ?? 0 : 0;
// Resolve any async asset data up front so all the entity mutations below
// run synchronously (the app wraps them in a single undo step).
- let transcriptTrim: { start: number; end: number } | null = null;
+ let spokenWords: { start: number; end: number } | null = null;
if (asset.type === 'TRANSCRIPT') {
// Transcript should be trimmed to the span of recognized words
const file = await getAssetFile(asset);
const transcript = JSON.parse(await file.text()) as Transcript;
const lastWord = transcript.at(-1)?.words.at(-1);
const firstWord = transcript.at(0)?.words.at(0);
- transcriptTrim = {
+ spokenWords = {
start: secondsToFrames(firstWord?.start),
end: secondsToFrames(lastWord?.end),
};
@@ -144,8 +144,7 @@ export async function insertAssetInTimeline(
const entity = createEntity(world);
entity.add(Name);
entity.set(Name, { value: asset.name });
- entity.add(Delay);
- entity.set(Delay, { value: delay });
+ entity.add(Start({ value: start }));
if (asset.type === 'IMAGE' || asset.type === 'VIDEO' || asset.type === 'SEQUENCE') {
const width = Math.round(asset.width);
@@ -159,9 +158,10 @@ export async function insertAssetInTimeline(
entity.add(Geometry);
entity.set(Geometry, { value: GeometryType.TEXT });
entity.add(Caption);
- if (transcriptTrim) {
- entity.add(Trim);
- entity.set(Trim, transcriptTrim);
+ if (spokenWords) {
+ entity.set(Start, { value: start + spokenWords.start });
+ entity.add(SourceIn({ value: spokenWords.start }));
+ entity.add(SourceOut({ value: spokenWords.end }));
}
} else {
entity.add(Geometry);
diff --git a/packages/runtime/src/actions/overlap.ts b/packages/runtime/src/actions/overlap.ts
index 2962c114..47ad30eb 100644
--- a/packages/runtime/src/actions/overlap.ts
+++ b/packages/runtime/src/actions/overlap.ts
@@ -9,13 +9,13 @@ import { Or } from 'koota';
import { store } from '../world/store';
import {
- ChildOf, Geometry, Group, Sequential, Trim, Computed,
+ ChildOf, Geometry, Group, Sequential, Computed,
} from '../traits';
import { isGroup } from '../queries/predicates';
import { getEntityTree, getParentNode } from '../queries/hierarchy';
-import { computeTrimStart, computeTrimEnd } from '../utils/time';
import { cloneSubtree } from '../world/serialize';
import { deleteEntity } from './entities';
+import { trimEntityIn, trimEntityOut } from './timing';
import type { Entity, World } from 'koota';
@@ -154,27 +154,22 @@ function resolveEntityOverlap(
} else if (!startCovered && endCovered) {
// Overlaps the dropped clip's left edge: keep the left remainder by
// pulling the out-point back to the drop start.
- entity.add(Trim);
- entity.set(Trim, { end: computeTrimEnd(entity, occStart) });
+ trimEntityOut(world, entity, occStart);
} else if (startCovered && !endCovered) {
// Overlaps the dropped clip's right edge: keep the right remainder by
// pushing the in-point forward to the drop end.
- entity.add(Trim);
- entity.set(Trim, { start: computeTrimStart(entity, occEnd) });
+ trimEntityIn(world, entity, occEnd);
} else {
// The dropped clip lands inside this one: split it into two halves around
// the span. Clone first so the copy inherits the original (un-shrunk)
- // trim, then shrink the original to the left half and the copy to the
+ // window, then shrink the original to the left half and the copy to the
// right half.
- const copyTrimStart = computeTrimStart(entity, occEnd);
const result = cloneSubtree(world, getEntityTree(world, entity));
const copy = result.get(entity);
- entity.add(Trim);
- entity.set(Trim, { end: computeTrimEnd(entity, occStart) });
+ trimEntityOut(world, entity, occStart);
if (copy !== undefined) {
- copy.add(Trim);
- copy.set(Trim, { start: copyTrimStart });
+ trimEntityIn(world, copy, occEnd);
}
}
}
diff --git a/packages/runtime/src/actions/timing.ts b/packages/runtime/src/actions/timing.ts
index d4bceae6..95357688 100644
--- a/packages/runtime/src/actions/timing.ts
+++ b/packages/runtime/src/actions/timing.ts
@@ -3,135 +3,227 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
// Time-range recomputation after structural or asset changes (was part of
-// api/utils.ts). Computed is derived state (store writes, no events); Trim is
-// authored, so trim edits go through entity.set and fire change events.
+// api/utils.ts). Computed is derived state (store writes, no events); the
+// authored 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, Paint, Audio, Caption, Cache, Computed, Delay,
- PlaybackRate, Trim, CaptionDecoderHandle,
+ Geometry, Group, Paint, Audio, Caption, Cache, Computed,
+ Start, End, SourceIn, SourceOut, PlaybackRate, CaptionDecoderHandle,
} from '../traits';
import { isGroupLike } from '../queries/predicates';
import { getParentNode } from '../queries/hierarchy';
-import { findAssetDuration } from '../utils/time';
+import { findAssetDuration, getSourceFrameAt, getTimelineOrigin } from '../utils/time';
import type { Entity, World } from 'koota';
-export function recomputeEntityTimeRange(world: World, entity: Entity): void {
+/**
+ * One of the authored time traits: Start, End, SourceIn, SourceOut,
+ * PlaybackRate. They all carry a single frame count (or multiplier).
+ */
+type TimeTrait = typeof Start;
+
+/**
+ * The authored 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?: TimeTrait): number | undefined {
+ return trait === ignore ? undefined : entity.get(trait)?.value;
+}
+
+/**
+ * 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).
+ */
+function resolveDuration(
+ world: World,
+ entity: Entity,
+ start: number,
+ sourceIn: number,
+ ignore?: TimeTrait,
+): number {
+ const playbackRate = authored(entity, PlaybackRate, ignore) || 1;
+ const assetDuration = findAssetDuration(world, entity);
+
+ let duration = Infinity;
+
+ const end = authored(entity, End, ignore);
+ if (end !== undefined) duration = end - start;
+
+ 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 (duration === Infinity) {
+ duration = (DEFAULT_DURATION_FRAMES - sourceIn) / playbackRate;
+ }
+
+ return Math.max(0, duration);
+}
+
+/**
+ * Resolve one node's authored time 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.
+ */
+export function recomputeEntityTimeRange(world: World, entity: Entity, ignore?: TimeTrait): void {
const computed = store(world, Computed);
const eid = entity.id();
const parent = getParentNode(entity);
- const parentDelay = parent !== null ? (computed.delay[parent.id()] ?? 0) : 0;
- const ownDelay = entity.get(Delay)?.value ?? 0;
- const accumulatedDelay = parentDelay + ownDelay;
+ const parentOrigin = parent !== null ? (computed.origin[parent.id()] ?? 0) : 0;
- computed.delay[eid] = accumulatedDelay;
+ const authoredStart = authored(entity, Start, ignore) ?? 0;
+ const sourceIn = authored(entity, SourceIn, ignore) ?? 0;
+ const playbackRate = authored(entity, PlaybackRate, ignore) || 1;
- const playbackRate = entity.get(PlaybackRate)?.value ?? 1;
+ // 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);
- let start: number;
- let end: number;
+ computed.origin[eid] = origin;
+ computed.playbackRate[eid] = playbackRate;
- if (entity.has(Trim)) {
- const trim = entity.get(Trim)!;
- start = Math.round(accumulatedDelay + trim.start / playbackRate);
- end = Math.round(accumulatedDelay + trim.end / playbackRate);
- } else if (isGroupLike(entity)) {
+ // A container with no End of its own spans whatever its children span.
+ if (fitsChildren(entity, ignore)) {
const children = entity.get(Cache)?.children ?? [];
- if (children.length === 0) {
- start = accumulatedDelay;
- end = accumulatedDelay + DEFAULT_DURATION_FRAMES;
- } else {
+ let fitStart = start;
+ let fitEnd = start + DEFAULT_DURATION_FRAMES;
+
+ if (children.length > 0) {
let minStart = Infinity;
let maxEnd = -Infinity;
for (const child of children) {
- const cs = computed.start[child.id()] ?? accumulatedDelay;
- const ce = computed.end[child.id()] ?? accumulatedDelay;
+ const cs = computed.start[child.id()] ?? start;
+ const ce = computed.end[child.id()] ?? start;
if (cs < minStart) minStart = cs;
if (ce > maxEnd) maxEnd = ce;
}
- start = minStart;
- end = maxEnd;
+ fitStart = minStart;
+ fitEnd = maxEnd;
}
- } else {
- const assetDuration = findAssetDuration(world, entity);
- const sourceDuration = assetDuration ?? DEFAULT_DURATION_FRAMES;
- start = accumulatedDelay;
- end = Math.round(accumulatedDelay + sourceDuration / playbackRate);
+
+ computed.start[eid] = fitStart;
+ computed.end[eid] = fitEnd;
+ computed.duration[eid] = fitEnd - fitStart;
+ return;
}
+ const end = start + Math.round(resolveDuration(world, entity, authoredStart, sourceIn, ignore));
+
computed.start[eid] = start;
computed.end[eid] = end;
computed.duration[eid] = end - start;
}
/**
- * Recompute an entity and every descendant node. Use when something that
- * affects accumulated delay or playback rate changes; every child below
- * needs its delay refreshed.
+ * Recompute an entity and every descendant node. Use when something that moves
+ * the entity's origin or changes its rate has changed; every child below is
+ * placed against that origin and has to be re-derived.
*/
-export function propagateTimeRangeDown(world: World, entity: Entity): void {
- recomputeEntityTimeRange(world, entity);
+export function propagateTimeRangeDown(world: World, entity: Entity, ignore?: TimeTrait): void {
+ recomputeEntityTimeRange(world, entity, ignore);
for (const child of entity.get(Cache)?.children ?? []) {
propagateTimeRangeDown(world, child);
}
for (const mask of entity.get(Cache)?.masks ?? []) {
propagateTimeRangeDown(world, mask);
}
- recomputeEntityTimeRange(world, entity);
+ recomputeEntityTimeRange(world, entity, ignore);
}
/**
* Walk upward recomputing any ancestor whose bounds depend on its children
- * (group-like without an explicit Trim). Call with the entity that changed.
+ * (group-like without an explicit end). Call with the entity that changed.
*/
export function bubbleTimeRangeUp(world: World, child: Entity): void {
const entity = getParentNode(child);
if (entity === null) return;
- const dependsOnChildren = isGroupLike(entity) && !entity.has(Trim);
- if (!dependsOnChildren) return;
+ if (!fitsChildren(entity)) return;
recomputeEntityTimeRange(world, entity);
bubbleTimeRangeUp(world, entity);
}
+/** Whether the node takes its bounds from its children rather than authoring them. */
+export function fitsChildren(entity: Entity, ignore?: TimeTrait): boolean {
+ return isGroupLike(entity) && authored(entity, End, ignore) === undefined;
+}
+
/**
- * Clamp a Trim's end so it never exceeds the entity's available asset
- * duration. Caller is responsible for triggering downstream recomputes.
+ * Pin whatever the node currently spans as an authored 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.
*/
-export function clampTrimToAssetDuration(world: World, entity: Entity): void {
- if (!entity.has(Trim)) return;
+export function pinEndToCurrentBounds(world: World, entity: Entity): void {
+ if (entity.has(End)) return;
- const assetDuration = findAssetDuration(world, entity);
- if (!assetDuration) return;
+ const start = entity.get(Start)?.value ?? 0;
+ const duration = store(world, Computed).duration[entity.id()] ?? 0;
- const trim = entity.get(Trim)!;
- if (trim.end > assetDuration) {
- entity.set(Trim, { end: assetDuration });
- }
+ entity.add(End({ value: start + duration }));
+}
+
+/**
+ * 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.
+ */
+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
+ // before moving the head, or the tail would follow along.
+ pinEndToCurrentBounds(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 });
}
/**
- * "Paint is removed" rule: if the geometry has no Trim, pin its current
- * computed duration as a fresh Trim so the entity does not silently fall
- * back to the 16s default after losing its asset source.
+ * 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.
*/
-export function pinTrimToCurrentDuration(world: World, entity: Entity): void {
- if (entity.has(Trim)) return;
+export function trimEntityOut(_world: World, entity: Entity, frame: number): void {
+ const end = frame - getTimelineOrigin(entity);
+ const source = getSourceFrameAt(entity, frame);
- const playbackRate = entity.get(PlaybackRate)?.value ?? 1;
- const globalDuration = store(world, Computed).duration[entity.id()] ?? 0;
- const localDuration = Math.round(globalDuration * playbackRate);
+ if (entity.has(SourceOut)) {
+ entity.set(SourceOut, { value: source });
+ }
- entity.add(Trim);
- entity.set(Trim, { start: 0, end: localDuration });
+ entity.add(End);
+ entity.set(End, { value: end });
}
/**
- * Recompute trim when the asset id of an entity changes.
+ * Re-derive the time range when the asset id of an entity changes.
*/
export function reactToAssetChange(world: World, entity: Entity) {
if (entity.has(Paint)) {
@@ -149,26 +241,27 @@ export function reactToAssetChange(world: World, entity: Entity) {
}
/**
- * Re-clamp the parent geometry's trim and bubble the new bounds up.
+ * 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.
*/
export function reactToPaintChange(world: World, paint: Entity) {
const entity = getParentNode(paint);
if (entity === null || !entity.has(Geometry)) return;
- clampTrimToAssetDuration(world, entity);
recomputeEntityTimeRange(world, entity);
bubbleTimeRangeUp(world, entity);
}
/**
- * Recompute a geometry's bounds and bubble. Used when something other than
- * its own Trim/Delay shifts its duration (e.g. an attached asset id on an
- * Audio entity).
+ * Recompute a geometry's bounds and bubble. Used when something other than its
+ * own authored time shifts its duration (e.g. an attached asset id on an Audio
+ * entity).
*/
export function reactToGeometryDurationChange(world: World, entity: Entity) {
if (!entity.has(Geometry)) return;
- clampTrimToAssetDuration(world, entity);
recomputeEntityTimeRange(world, entity);
bubbleTimeRangeUp(world, entity);
}
@@ -189,7 +282,7 @@ export function reactToChildAttached(world: World, child: Entity) {
* ChildOf onRemove hook (covers the user-facing "remove" path). Mirror of
* reactToChildAttached: if the dying entity is a geometry the parent group's
* bounds may shrink; if it's a paint the parent geometry may lose its asset
- * source and needs a Trim pinned at its current duration.
+ * source and needs its current span pinned.
*/
export function reactToChildDetached(world: World, child: Entity) {
if (child.has(Geometry) || child.has(Group)) {
@@ -202,6 +295,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.
- pinTrimToCurrentDuration(world, parent);
+ pinEndToCurrentBounds(world, parent);
}
}
diff --git a/packages/runtime/src/queries/hierarchy.ts b/packages/runtime/src/queries/hierarchy.ts
index ab4d92f4..438322ac 100644
--- a/packages/runtime/src/queries/hierarchy.ts
+++ b/packages/runtime/src/queries/hierarchy.ts
@@ -2,9 +2,10 @@
* 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/. */
-import { ChildOf, Computed, Name, Playback, PlaybackRate } from '../traits';
+import { ChildOf, Computed, Name, Playback } from '../traits';
import { isDocument, isScene } from './predicates';
-import { sortByItemIndex } from '../utils';
+// Direct module, not the utils barrel: utils/time reaches back into this file.
+import { sortByItemIndex } from '../utils/sort';
import type { Entity, World, QueryParameter } from 'koota';
@@ -65,14 +66,15 @@ export function getEntityTree(world: World, root: Entity): Entity[] {
/**
* Returns the local frame for a node in its own source/content time: the
- * timeline frame relative to the node's delay, scaled by its playback rate.
+ * timeline frame relative to the node's origin, scaled by its playback rate.
* This matches `Computed.localTime` (the space keyframes are sampled
* in), so keyframes authored at any playback rate land on the right content
* frame.
*/
export function getNodeLocalFrame(node: Entity): number {
- const delay = node.get(Computed)?.delay ?? 0;
- const playbackRate = node.get(PlaybackRate)?.value ?? 1;
+ const computed = node.get(Computed);
+ const origin = computed?.origin ?? 0;
+ const playbackRate = computed?.playbackRate || 1;
let current: Entity | null = node;
while (current) {
@@ -81,7 +83,7 @@ export function getNodeLocalFrame(node: Entity): number {
// must be a top-level playback entity
if (current.has(Playback) && parent === null) {
const currentTime = current.get(Computed)?.localTime ?? 0;
- return Math.round((currentTime - delay) * playbackRate);
+ return Math.round((currentTime - origin) * playbackRate);
}
current = parent;
diff --git a/packages/runtime/src/systems/motion.ts b/packages/runtime/src/systems/motion.ts
index f5e6fb0d..2c798fdc 100644
--- a/packages/runtime/src/systems/motion.ts
+++ b/packages/runtime/src/systems/motion.ts
@@ -8,13 +8,14 @@ import { cubicBezier, steps, spring } from 'animejs';
import { store } from '../world/store';
import {
Geometry, Group, AdjustmentLayer, Hidden, Culled,
- Computed, Cache, Animation, KeyframeTrack, Keyframe, Trim, Chars,
+ Computed, Cache, Animation, KeyframeTrack, Keyframe, Chars,
UniformScale, Position, Offset, Rotation, Scale, Skew, Size, Appearance,
Color, Blur, Volume, Effect, StrokeStyle, CornerRadius, MixedCornerRadius,
ColorStop,
} from '../traits';
import { AnimationType, AnimationPhase } from '../constants';
import { revealChars, revealWords, scrambleChars } from '../utils/text-motion';
+import { getSourceWindow } from '../utils/time';
import type { Entity, World } from 'koota';
@@ -184,7 +185,6 @@ export function motionSystem(world: World): void {
const cache = store(world, Cache);
const animation = store(world, Animation);
const keyframeTrack = store(world, KeyframeTrack);
- const trimStore = store(world, Trim);
const worldProps = getPropertyPaths(world);
for (const entity of world.query(
@@ -200,13 +200,7 @@ export function motionSystem(world: World): void {
resetAnimatedValues(world, entity);
- let trimStart = 0;
- let trimEnd = computed.duration[eid];
-
- if (entity.has(Trim)) {
- trimStart = trimStore.start[eid];
- trimEnd = trimStore.end[eid] ?? trimEnd;
- }
+ const source = getSourceWindow(entity);
const localFrame = computed.localTime[eid];
@@ -219,8 +213,8 @@ export function motionSystem(world: World): void {
const delay = animation.delay[aid] ?? 0;
const isOut = animation.phase[aid] === AnimationPhase.OUT;
const windowStart = isOut
- ? trimEnd - duration - delay
- : trimStart + delay;
+ ? source.out - duration - delay
+ : source.in + delay;
const windowEnd = windowStart + duration;
if (isOut ? localFrame < windowStart : localFrame >= windowEnd) continue;
diff --git a/packages/runtime/src/systems/playback.ts b/packages/runtime/src/systems/playback.ts
index 6b38129f..968cc7fd 100644
--- a/packages/runtime/src/systems/playback.ts
+++ b/packages/runtime/src/systems/playback.ts
@@ -14,13 +14,14 @@ import { PaintType } from '../constants';
import {
ChildOf, Hidden, Culled, Dragging,
Geometry, Group, AdjustmentLayer, Paint, Audio, Caption, Muted, Soloed,
- Sequential, Transition, Playback, Workarea, Trim, PlaybackRate,
+ Sequential, Transition, Playback, Workarea,
AudioPlayback, Computed,
AudioDecoderHandle, AudioBusHandle, HtmlHostHandle,
Mode, FrameRate, Time, AudioEngine, FramePromises, Mounts,
Root,
} from '../traits';
import { getParentNode } from '../queries/hierarchy';
+import { getSourceWindow } from '../utils/time';
import { clamp } from '../math/common';
import { getTransitionWindow } from '../utils/transition';
import {
@@ -115,7 +116,6 @@ function advancePlayhead(world: World, entity: Entity): void {
function forwardVideoDecoder(world: World, scene: Entity, entity: Entity, fill: Entity): void {
const computed = store(world, Computed);
- const trim = store(world, Trim);
const eid = entity.id();
const fps = world.get(FrameRate)?.value ?? 30;
@@ -126,19 +126,13 @@ function forwardVideoDecoder(world: World, scene: Entity, entity: Entity, fill:
const hasCache = world.get(Mode)?.value === 'realtime';
const warmupDecoder = globalFrame >= start - WARMUP_FRAMES && globalFrame < end + WARMUP_FRAMES && hasCache;
- let trimStart = 0;
- let trimEnd = computed.duration[eid]!;
-
- if (entity.has(Trim)) {
- trimStart = trim.start[eid]!;
- trimEnd = trim.end[eid] ?? trimEnd;
- }
+ const source = getSourceWindow(entity);
const decoder = resolveVideoDecoder(world, fill);
if (!decoder) return;
if (computed.visibility[eid] === 1 || warmupDecoder) {
- const seekFrame = clamp(localFrame, trimStart, trimEnd);
+ const seekFrame = clamp(localFrame, source.in, source.out);
const seekPromise = decoder.seekTo(seekFrame, fps);
framePromises(world)?.push(seekPromise ?? null);
}
@@ -146,7 +140,6 @@ function forwardVideoDecoder(world: World, scene: Entity, entity: Entity, fill:
function forwardSequenceDecoder(world: World, scene: Entity, entity: Entity, fill: Entity): void {
const computed = store(world, Computed);
- const trim = store(world, Trim);
const eid = entity.id();
const fps = world.get(FrameRate)?.value ?? 30;
@@ -157,19 +150,13 @@ function forwardSequenceDecoder(world: World, scene: Entity, entity: Entity, fil
const hasCache = world.get(Mode)?.value === 'realtime';
const warmupDecoder = globalFrame >= start - WARMUP_FRAMES && globalFrame < end + WARMUP_FRAMES && hasCache;
- let trimStart = 0;
- let trimEnd = computed.duration[eid]!;
-
- if (entity.has(Trim)) {
- trimStart = trim.start[eid]!;
- trimEnd = trim.end[eid] ?? trimEnd;
- }
+ const source = getSourceWindow(entity);
const decoder = resolveSequenceDecoder(world, fill, hasCache);
if (!decoder) return;
if (computed.visibility[eid] === 1 || warmupDecoder) {
- const seekFrame = clamp(localFrame, trimStart, trimEnd);
+ const seekFrame = clamp(localFrame, source.in, source.out);
const seekPromise = decoder.seekTo(seekFrame, fps);
framePromises(world)?.push(seekPromise);
}
@@ -197,7 +184,6 @@ function forwardAudioDecoder(world: World, scene: Entity, entity: Entity, audioS
const { decoder, initPromise } = resolvedDecoder;
const computed = store(world, Computed);
- const trim = store(world, Trim);
const audioPlayback = store(world, AudioPlayback);
const playback = store(world, Playback);
const eid = entity.id();
@@ -206,11 +192,10 @@ function forwardAudioDecoder(world: World, scene: Entity, entity: Entity, audioS
const currentTime = computed.localTime[sid]!;
const localFrame = computed.localTime[eid]!;
- const trimStart = trim.start[eid] ?? 0;
+ const source = getSourceWindow(entity);
- const playbackRate = entity.get(PlaybackRate)?.value ?? 1;
- const delay = computed.delay[eid]!;
- const trimEnd = trim.end[eid] ?? computed.duration[eid] ?? 0;
+ const playbackRate = computed.playbackRate[eid] || 1;
+ const origin = computed.origin[eid]!;
const audioOffset = audioPlayback.contextOffsetInSeconds[sid] ?? 0;
const playbackOffset = audioPlayback.timelineOffsetInSeconds[sid] ?? 0;
@@ -226,11 +211,11 @@ function forwardAudioDecoder(world: World, scene: Entity, entity: Entity, audioS
const playPromise = decoder.playTo(bus, {
relativeFrom: localFrame / fps,
relativeTo: (localFrame + 15) / fps,
- trimStart: trimStart / fps,
- trimEnd: trimEnd / fps,
+ trimStart: source.in / fps,
+ trimEnd: source.out / fps,
playbackRate,
currentTime: currentTime / fps,
- relativeDelay: (delay / fps) + audioDelay,
+ relativeDelay: (origin / fps) + audioDelay,
});
framePromises(world)?.push(playPromise);
} else {
@@ -318,13 +303,13 @@ function updateVisibility(world: World, scene: Entity, entity: Entity): void {
computed.visibility[eid] = 1;
} else {
const globalFrame = computed.localTime[scene.id()]!;
- const delay = computed.delay[eid] ?? 0;
- const playbackRate = entity.get(PlaybackRate)?.value ?? 1;
+ const origin = computed.origin[eid] ?? 0;
+ const playbackRate = computed.playbackRate[eid] || 1;
const start = computed.start[eid]!;
const end = computed.end[eid]!;
- computed.localTime[eid] = Math.round((globalFrame - delay) * playbackRate);
+ computed.localTime[eid] = Math.round((globalFrame - origin) * playbackRate);
computed.visibility[eid] = globalFrame >= start && globalFrame < end ? 1 : 0;
}
diff --git a/packages/runtime/src/traits/derived.ts b/packages/runtime/src/traits/derived.ts
index e482dfe0..8433c9f9 100644
--- a/packages/runtime/src/traits/derived.ts
+++ b/packages/runtime/src/traits/derived.ts
@@ -40,10 +40,11 @@ export const Computed = trait({
chars: undefined as string | undefined,
localTimeInSeconds: 0, // playhead position in seconds
localTime: 0, // playhead position in frames (mirrors localTimeInSeconds)
- duration: 0, // frames
+ duration: 0, // end - start
start: 0,
end: 0,
- delay: 0,
+ origin: 0, // The origin of the node's own timeline
+ playbackRate: 1,
visibility: 1,
});
diff --git a/packages/runtime/src/traits/timing.ts b/packages/runtime/src/traits/timing.ts
index 7ac0e448..8b8ef17b 100644
--- a/packages/runtime/src/traits/timing.ts
+++ b/packages/runtime/src/traits/timing.ts
@@ -6,18 +6,27 @@ import { trait } from 'koota';
import { TransitionType } from '../constants';
-// Offset where the node starts inside its parent's timeline (frames).
-export const Delay = trait({ value: 0 });
-
-// Speed multiplier for the node's local time (1 = normal).
+// 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 });
+
+// Speed multiplier for the node's local time (1 = normal). Scales the source
+// window against the timeline window: at 2, twice the source frames fit into
+// the same stretch of timeline.
export const PlaybackRate = trait({ value: 1 });
-// Explicit duration window in the clip's own local time. When present, the
-// node has fixed bounds (workarea on scenes, trimmed source on media clips).
-// When absent: scenes auto-fit to their children, other nodes have no
-// inherent duration (the runtime adds Trim immediately on creation).
-export const Trim = trait({ start: 0, end: 0 });
-
// Explicit playback/export window on a scene.
export const Workarea = trait({ start: 0, end: 0 });
diff --git a/packages/runtime/src/utils/time.ts b/packages/runtime/src/utils/time.ts
index ebc6698e..7f5b2360 100644
--- a/packages/runtime/src/utils/time.ts
+++ b/packages/runtime/src/utils/time.ts
@@ -4,8 +4,9 @@
import { CONONICAL_TIME_BASE, PaintType } from '../constants';
import {
- Audio, AssetId, Cache, Computed, Paint, PlaybackRate, Assets, FrameRate,
+ Audio, AssetId, Cache, Computed, Paint, SourceIn, Assets, FrameRate,
} from '../traits';
+import { getParentNode } from '../queries/hierarchy';
import type { Entity, World } from 'koota';
import type { Asset } from '../assets/types';
@@ -57,25 +58,37 @@ export function formatTimecode(seconds: number, frameRate: number): string {
}
/**
- * Computes the trim start frame (local) for a given entity,
- * based on the specified start frame (global) and playback rate.
+ * The scene frame that authored 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.
*/
-export function computeTrimStart(entity: Entity, start: number) {
- const delay = entity.get(Computed)?.delay ?? 0;
- const playbackRate = entity.get(PlaybackRate)?.value ?? 1;
+export function getTimelineOrigin(entity: Entity): number {
+ const parent = getParentNode(entity);
+ return parent === null ? 0 : (parent.get(Computed)?.origin ?? 0);
+}
+
+/** The source frame `entity` is playing at scene frame `frame`. */
+export function getSourceFrameAt(entity: Entity, frame: number): number {
+ const computed = entity.get(Computed);
+ const origin = computed?.origin ?? 0;
+ const playbackRate = computed?.playbackRate || 1;
- return Math.round((start - delay) * playbackRate);
+ return Math.round((frame - origin) * playbackRate);
}
/**
- * Computes the trim end frame (local) for a given entity,
- * based on the specified end frame (global) and playback rate.
+ * 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.
*/
-export function computeTrimEnd(entity: Entity, end: number) {
- const delay = entity.get(Computed)?.delay ?? 0;
- const playbackRate = entity.get(PlaybackRate)?.value ?? 1;
+export function getSourceWindow(entity: Entity): { in: number; out: number } {
+ const sourceIn = entity.get(SourceIn)?.value ?? 0;
+ const computed = entity.get(Computed);
+ const duration = computed?.duration ?? 0;
+ const playbackRate = computed?.playbackRate || 1;
- return Math.round((end - delay) * playbackRate);
+ return { in: sourceIn, out: sourceIn + Math.round(duration * playbackRate) };
}
/** The asset backing a geometry: its own AssetId, or the first fill's. */
diff --git a/packages/runtime/src/world/observers.ts b/packages/runtime/src/world/observers.ts
index 88212252..1e11f84d 100644
--- a/packages/runtime/src/world/observers.ts
+++ b/packages/runtime/src/world/observers.ts
@@ -19,7 +19,7 @@
import { store } from './store';
import {
ChildOf, Culled, Sequential, Group, Scene, Audio, Paint, AssetId,
- Delay, PlaybackRate, Trim, Keyframe, ItemIndex,
+ Start, End, SourceIn, SourceOut, PlaybackRate, Keyframe, ItemIndex,
Position, Offset, Rotation, Scale, UniformScale, Skew, Anchor, Flip,
Appearance, Color, Blur, Volume, Effect, CornerRadius, MixedCornerRadius,
ColorStop, StrokeStyle, Size, Computed,
@@ -33,7 +33,7 @@ import { disposeDecoders, disconnectAudioBus } from '../media/dispose';
import {
reactToChildAttached, reactToChildDetached, reactToAssetChange,
reactToPaintChange, recomputeEntityTimeRange, propagateTimeRangeDown,
- bubbleTimeRangeUp, clampTrimToAssetDuration,
+ bubbleTimeRangeUp,
} from '../actions/timing';
import { propagateSize, resolveConstraintOffsets } from '../actions/resize';
@@ -105,14 +105,6 @@ export function observeWorld(world: World): () => void {
entity.remove(Position, Offset, Rotation, Scale, Skew, Anchor, Flip);
}));
- // First Trim on an entity defaults its end to the current duration (the
- // bitecs setComponent fallback), so a partial { start } set stays valid.
- subs.push(world.onAdd(Trim, (entity) => {
- if (entity.get(Trim)!.end === 0) {
- entity.set(Trim, { end: store(world, Computed).duration[entity.id()] ?? 0 });
- }
- }));
-
// ── Time ranges ───────────────────────────────────────────
const recomputeAndBubble = (entity: Entity) => {
@@ -137,16 +129,14 @@ export function observeWorld(world: World): () => void {
bubbleTimeRangeUp(world, entity);
};
- subs.push(world.onChange(Delay, propagateAndBubble));
- subs.push(world.onChange(PlaybackRate, propagateAndBubble));
-
- subs.push(world.onChange(Trim, (entity) => {
- // Clamping re-enters this handler once via set; the second pass no-ops.
- clampTrimToAssetDuration(world, entity);
- recomputeAndBubble(entity);
- }));
-
- subs.push(world.onRemove(Trim, recomputeAndBubble));
+ for (const trait of [Start, End, SourceIn, SourceOut, PlaybackRate]) {
+ subs.push(world.onAdd(trait, propagateAndBubble));
+ subs.push(world.onChange(trait, propagateAndBubble));
+ subs.push(world.onRemove(trait, (entity) => {
+ propagateTimeRangeDown(world, entity, trait);
+ bubbleTimeRangeUp(world, entity);
+ }));
+ }
// ── Authored → Computed mirrors ───────────────────────────
// Base values for entities the motion system skips (no animation data);
diff --git a/packages/runtime/src/world/serialize.ts b/packages/runtime/src/world/serialize.ts
index 414140b5..16d926ac 100644
--- a/packages/runtime/src/world/serialize.ts
+++ b/packages/runtime/src/world/serialize.ts
@@ -12,7 +12,8 @@ import {
Appearance, Color, CornerRadius, MixedCornerRadius, Blur, ScaleMode, Effect,
ColorStop, StrokeStyle, Shader,
Chars, TextStyle,
- Delay, PlaybackRate, Trim, Playback, Sequential, Transition, ClipHeight, Expanded,
+ Start, End, SourceIn, SourceOut, PlaybackRate,
+ Playback, Sequential, Transition, ClipHeight, Expanded,
Volume, Muted,
KeyframeTrack, Keyframe, Animation, DocumentRoot,
} from '../traits';
@@ -130,12 +131,11 @@ export interface EntityRecord {
Playback?: {
loop?: number;
};
- Delay?: number;
+ Start?: number;
+ End?: number;
+ SourceIn?: number;
+ SourceOut?: number;
PlaybackRate?: number;
- Trim?: {
- start?: number;
- end?: number;
- };
Constraint?: {
horizontal?: number;
vertical?: number;
@@ -336,16 +336,21 @@ export function serializeEntity(entity: Entity): EntityRecord {
loop: entity.get(Playback)!.loop ? 1 : 0,
};
}
- if (entity.has(Delay)) {
- record.Delay = entity.get(Delay)!.value;
+ 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(SourceOut)) {
+ record.SourceOut = entity.get(SourceOut)!.value;
}
if (entity.has(PlaybackRate)) {
record.PlaybackRate = entity.get(PlaybackRate)!.value;
}
- if (entity.has(Trim)) {
- const trim = entity.get(Trim)!;
- record.Trim = { start: trim.start, end: trim.end };
- }
if (entity.has(Transition)) {
const transition = entity.get(Transition)!;
record.Transition = { type: transition.type, duration: transition.duration };
@@ -574,17 +579,20 @@ export function deserializeEntity(entity: Entity, e: Partial<EntityRecord>): voi
entity.add(Playback);
entity.set(Playback, { loop: !!e.Playback.loop });
}
- if (e.Delay !== undefined) {
- entity.add(Delay);
- entity.set(Delay, { value: e.Delay });
+ if (e.Start !== undefined) {
+ entity.add(Start({ value: e.Start }));
}
- if (e.PlaybackRate !== undefined) {
- entity.add(PlaybackRate);
- entity.set(PlaybackRate, { value: e.PlaybackRate });
+ if (e.End !== undefined) {
+ entity.add(End({ value: e.End }));
+ }
+ if (e.SourceIn !== undefined) {
+ entity.add(SourceIn({ value: e.SourceIn }));
}
- if (e.Trim !== undefined) {
- entity.add(Trim);
- entity.set(Trim, defined(e.Trim));
+ if (e.SourceOut !== undefined) {
+ entity.add(SourceOut({ value: e.SourceOut }));
+ }
+ if (e.PlaybackRate !== undefined) {
+ entity.add(PlaybackRate({ value: e.PlaybackRate }));
}
if (e.Transition !== undefined) {
entity.add(Transition);