Skip to content

The VS Code of video editing, built for agents.

TypeScript

Implement playback system in runtime package for time advancement and media synchronization

konstantin-paulusdf07fd1209a1
diff --git a/packages/runtime/MIGRATION.md b/packages/runtime/MIGRATION.md
index 2e1833a7..c0001200 100644
--- a/packages/runtime/MIGRATION.md
+++ b/packages/runtime/MIGRATION.md
@@ -37,6 +37,7 @@ Working doc for migrating the editor engine from bitecs (in `apps/web/src/compon
| Text rendering | `src/utils/text.ts` (full port) | tokenize/shape/render joined the Token seed; reads RenderSurface.ctx + Camera; no-ops without a surface. Gradient construction split into `src/systems/gradients.ts` (render system reuses it) |
| Fonts | `src/fonts/{fixtures,utils}.ts` | WebFonts fixtures verbatim; `loadWebFont` uses the Fonts world trait, resolves the FontFaceSet via globalThis (worker-capable), guards on missing FontFace (headless), and drops db persistence (app wraps it). `getLocalFonts` + `restoreFonts` stay app-side |
| Support utils | `src/utils/{color,async}.ts`, `clamp` in math | parseColor/colorToHex/rgbToColor (colord dep), AsyncMutex/attempt |
+| Playback system | `src/systems/playback.ts`, `src/utils/transition.ts` | Playhead advance, visibility/local-time recursion, decoder forwarding, transitions, solo muting, live mounts step; `resolveAudioBus` exported from here. See semantic notes |
| Seeds (types only, rest follows) | `src/utils/text.ts` (Token/Line/TokenOptions), `src/capture/format.ts` (ContainerFormat) | The remaining engine files merge into these on their slice |
Verification style used so far: `npx tsc --noEmit` in the package, plus throwaway `smoke-test.tmp.ts` in the package root run with `npm exec --yes tsx@latest -- smoke-test.tmp.ts`, deleted afterwards (no test infra in the package yet). koota caps live worlds at 16; call `world.destroy()` in test loops.
@@ -72,6 +73,8 @@ Every world spawns one entity tagged `DocumentRoot` (`createRuntimeWorld`). All
- Caption presets write playhead-driven text via `setChars` (raw store write, no change events) so per-frame caption content never reaches app persistence, same as the bitecs raw array writes. Preset fills/ranges go through createEntity/appendChild, so caches prime via the observers.
- DOM caveats, all lazy (nothing touches DOM at import time): HtmlHost/SurfaceHost create elements at construction (html-in-canvas is Chromium-flag-only anyway), ShaderHost needs WebGPU, `loadWebFont` no-ops without FontFace. tsconfig gained `DOM.Iterable` + `@webgpu/types`.
- `SequenceDecoder` iterates the structural `AssetDirectoryHandle` (entries with `getFile`) instead of concrete FileSystemFileHandle, so node hosts can feed frame directories.
+- Playback: the bitecs top-level query `Not(ChildOf('*'))` became `ChildOf(document)`. Playhead advance, auto-stop, and visibility/localTime writes stay raw store writes (no change events, same as bitecs), and `AudioPlayback` is lazily added to playback roots on first tick. `resolveAudioBus` returns null when the world has no AudioEngine context (headless-without-audio; `AudioDecoder.playTo(null, ...)` already no-ops), and the context/offset reads guard the same way. The transition-cleanup `removeComponent(..., false)` became a plain `entity.remove(Transition)`; the app's history layer must treat Transition onRemove during a tick as system-driven, not undoable.
+- `systems/schedule.ts` is still a stub: the realtime tick order is playback → motion → transform → render (per `api/engine.ts`), and the helper composing it lands with the render/capture slices when all members exist.
- `switchActiveScene` only sets the ActiveScene world trait; timeline buffer clearing and index rebuild stay app-side. `frameSelection` calls it once (bitecs called it redundantly inside and outside the transaction).
- `insertAssetInTimeline` returns the created entity or null when no scene is active (no toast). Folder ops are sync and return the changed records (`deleteFolder` returns removed folder/asset ids) so the app can persist; `moveAssetsToFolder` updates records in place instead of re-fronting them like `saveAsset` did. Panel navigation state (current folder) stays app-side.
- Decoder/host handle traits (`src/traits/media.ts`) are AoS traits typed as opaque `object` until the decoders move in; `entity.get(VideoDecoder)` returns the instance directly.
@@ -90,12 +93,11 @@ Every world spawns one entity tagged `DocumentRoot` (`createRuntimeWorld`). All
## Remaining work (suggested order)
-1. **Playback system**: `systems/playback.ts` (computes `Computed.localTime/start/end/duration/visibility`, drives decoders via the media resolvers, pushes into `FramePromises`, uses AudioEngine + Mounts; `resolveAudioBus` lives here).
-2. **Capture** (`src/capture/`): `engine/encode/*` (encoder, image-encoder, buffer, format, utils). Uses Mode, FramePromises, RenderSurface.
-3. **Render system**: `systems/render.ts` is runtime-capable (OffscreenCanvas) and needed for headless capture; text rendering and gradients are already in (`utils/text.ts`, `systems/gradients.ts`; `addStopsTo` stayed private to gradients).
-4. **Remaining utils**: captions, transition, contact-sheet, audio-sync, transcode (audit each for DOM/app deps; DOM-touching ones stay app-side).
-5. **App rewrite** (`apps/web`): engine shell wires canvas/AudioContext/DPR into world traits, app-side world traits (input, HUD, selection tool, history, store, timelineIndex signal), history/persistence via koota events (including wrapping the folder/asset model ops with Dexie writes, font persistence around `loadWebFont` + `restoreFonts`/`getLocalFonts`, re-implementing `syncInteractiveState` over `ChildOf(document)` queries: `Not(ChildOf('*'))` throws in koota, and re-adding the editing-surface `syncKeyframeTrack` calls the observers slice dropped), Deleted-tombstone pruning + `unpersistEntity`, UI to `packages/koota-solid` hooks, timeline UI consumes new `TimelineNode.entity`. Delete `engine/components`, `engine/api` progressively.
-6. **CLI**: point node capture at the runtime package.
+1. **Capture** (`src/capture/`): `engine/encode/*` (encoder, image-encoder, buffer, format, utils). Uses Mode, FramePromises, RenderSurface. Fill `systems/schedule.ts` once render exists.
+2. **Render system**: `systems/render.ts` is runtime-capable (OffscreenCanvas) and needed for headless capture; text rendering and gradients are already in (`utils/text.ts`, `systems/gradients.ts`; `addStopsTo` stayed private to gradients).
+3. **Remaining utils**: captions, contact-sheet, audio-sync, transcode (audit each for DOM/app deps; DOM-touching ones stay app-side).
+4. **App rewrite** (`apps/web`): engine shell wires canvas/AudioContext/DPR into world traits, app-side world traits (input, HUD, selection tool, history, store, timelineIndex signal), history/persistence via koota events (including wrapping the folder/asset model ops with Dexie writes, font persistence around `loadWebFont` + `restoreFonts`/`getLocalFonts`, re-implementing `syncInteractiveState` over `ChildOf(document)` queries: `Not(ChildOf('*'))` throws in koota, and re-adding the editing-surface `syncKeyframeTrack` calls the observers slice dropped), Deleted-tombstone pruning + `unpersistEntity`, UI to `packages/koota-solid` hooks, timeline UI consumes new `TimelineNode.entity`. Delete `engine/components`, `engine/api` progressively.
+5. **CLI**: point node capture at the runtime package.
## Layout reminders
diff --git a/packages/runtime/src/systems/index.ts b/packages/runtime/src/systems/index.ts
index 7df32c4a..ac687b3e 100644
--- a/packages/runtime/src/systems/index.ts
+++ b/packages/runtime/src/systems/index.ts
@@ -2,3 +2,4 @@
export * from './transform';
export * from './motion';
export * from './gradients';
+export * from './playback';
diff --git a/packages/runtime/src/systems/playback.ts b/packages/runtime/src/systems/playback.ts
index 803a768f..f4e05b8e 100644
--- a/packages/runtime/src/systems/playback.ts
+++ b/packages/runtime/src/systems/playback.ts
@@ -1 +1,466 @@
-// Playback system: time advancement and clip activation (was systems/playback.ts, minus DOM audio wiring).
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+// Playback system (was systems/playback.ts): advances root playheads, derives
+// per-entity local time + visibility, forwards decoders/hosts, keeps the
+// audio bus tree in sync, and steps live mounts. In offline modes the encoder
+// sets the playhead explicitly and awaits FramePromises.
+
+import { Not, Or } from 'koota';
+
+import { store } from '../world/store';
+import { PaintType } from '../constants';
+import {
+ ChildOf, Deleted, Hidden, Culled, Dragging,
+ Geometry, Group, AdjustmentLayer, Paint, Audio, Caption, Muted, Soloed,
+ Sequential, Transition, Playback, Workarea, Trim, PlaybackRate,
+ AudioPlayback, Computed,
+ AudioDecoderHandle, AudioBusHandle, HtmlHostHandle,
+ Mode, FrameRate, Time, AudioEngine, FramePromises, Mounts,
+} from '../traits';
+import { getDocument, getParentNode } from '../queries/hierarchy';
+import { clamp } from '../math/common';
+import { getTransitionWindow } from '../utils/transition';
+import {
+ resolveAudioDecoder, resolveCaptionDecoder, resolveImageDecoder,
+ resolveSequenceDecoder, resolveShaderHost, resolveVideoDecoder,
+} from '../media';
+import { AudioBus } from '../media/audio-bus';
+
+import type { Entity, World } from 'koota';
+
+const WARMUP_FRAMES = 15;
+
+function framePromises(world: World) {
+ return world.get(FramePromises)?.list ?? null;
+}
+
+function advancePlayhead(world: World, entity: Entity): void {
+ // In offline mode the encoder sets the playhead explicitly per frame, so
+ // skip the delta-based advance — running it would either double-step or
+ // drift depending on how the caller set `Time.delta`.
+ if (world.get(Mode)?.value !== 'realtime') return;
+
+ const playback = store(world, Playback);
+ const computed = store(world, Computed);
+ const eid = entity.id();
+ const fps = world.get(FrameRate)?.value ?? 30;
+ let looped = false;
+
+ // Only advance the playhead while playing. The audio play/stop bookkeeping
+ // below must still run when stopped, otherwise a manual stop (playing
+ // flipped off externally) is never observed — `wasPlaying` stays stuck and
+ // the next play isn't re-anchored, so scheduled buffers land in the past
+ // and play silently.
+ if (playback.playing[eid] === true) {
+ const dt = (world.get(Time)?.delta ?? 0) / 1000;
+ const speed = playback.speed[eid] || 1;
+ const previousTime = computed.localTimeInSeconds[eid]!;
+ let time = previousTime + dt * speed;
+
+ const hasWorkarea = entity.has(Workarea);
+ const workarea = store(world, Workarea);
+ const duration = computed.duration[eid]!;
+ const durationSeconds = duration / fps;
+
+ const maxSeconds = hasWorkarea
+ ? (workarea.end[eid] ?? duration) / fps
+ : durationSeconds;
+
+ const minSeconds = hasWorkarea
+ ? (workarea.start[eid] ?? 0) / fps
+ : 0;
+
+ if (time >= maxSeconds) {
+ if (playback.loop[eid] === true) {
+ time = minSeconds;
+ looped = true;
+ } else {
+ playback.playing[eid] = false;
+ }
+ } else if (time <= minSeconds) {
+ if (playback.loop[eid] === true) {
+ time = maxSeconds;
+ looped = true;
+ } else {
+ playback.playing[eid] = false;
+ time = minSeconds;
+ }
+ }
+
+ computed.localTimeInSeconds[eid] = clamp(time, minSeconds, maxSeconds);
+ computed.localTime[eid] = Math.round(computed.localTimeInSeconds[eid]! * fps);
+ }
+
+ // Handle audio play/stop transitions
+ if (!entity.has(AudioPlayback)) entity.add(AudioPlayback);
+ const audioPlayback = store(world, AudioPlayback);
+ const ctx = world.get(AudioEngine)?.context;
+ const playing = playback.playing[eid] ?? false;
+ const wasPlaying = audioPlayback.wasPlaying[eid] ?? false;
+
+ if ((playing && !wasPlaying) || looped) {
+ audioPlayback.contextOffsetInSeconds[eid] = ctx?.currentTime ?? 0;
+ audioPlayback.timelineOffsetInSeconds[eid] = computed.localTimeInSeconds[eid]!;
+ }
+
+ if (!playing && wasPlaying) {
+ resetDecoders(world, entity);
+ }
+
+ audioPlayback.wasPlaying[eid] = playing;
+}
+
+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;
+
+ const globalFrame = computed.localTime[scene.id()]!;
+ const localFrame = computed.localTime[eid]!;
+ const start = computed.start[eid]!;
+ const end = computed.end[eid]!;
+ 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 decoder = resolveVideoDecoder(world, fill);
+ if (!decoder) return;
+
+ if (computed.visibility[eid] === 1 || warmupDecoder) {
+ const seekFrame = clamp(localFrame, trimStart, trimEnd);
+ const seekPromise = decoder.seekTo(seekFrame, fps);
+ framePromises(world)?.push(seekPromise ?? null);
+ }
+}
+
+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;
+
+ const globalFrame = computed.localTime[scene.id()]!;
+ const localFrame = computed.localTime[eid]!;
+ const start = computed.start[eid]!;
+ const end = computed.end[eid]!;
+ 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 decoder = resolveSequenceDecoder(world, fill, hasCache);
+ if (!decoder) return;
+
+ if (computed.visibility[eid] === 1 || warmupDecoder) {
+ const seekFrame = clamp(localFrame, trimStart, trimEnd);
+ const seekPromise = decoder.seekTo(seekFrame, fps);
+ framePromises(world)?.push(seekPromise);
+ }
+}
+
+function forwardCaptionDecoder(world: World, _scene: Entity, entity: Entity): void {
+ const localFrame = store(world, Computed).localTime[entity.id()]!;
+ const fps = world.get(FrameRate)?.value ?? 30;
+
+ const decoder = resolveCaptionDecoder(world, entity);
+ decoder?.seekTo(world, entity, localFrame / fps);
+}
+
+/**
+ * Forward the audio decoder for a child entity. `audioSource` optionally
+ * points at the sub-entity carrying the audio (a video fill), while the
+ * timing still comes from the clip entity itself.
+ */
+function forwardAudioDecoder(world: World, scene: Entity, entity: Entity, audioSource?: Entity): void {
+ if (entity.has(Muted)) return;
+
+ const resolvedDecoder = resolveAudioDecoder(world, audioSource ?? entity);
+ if (!resolvedDecoder) return;
+
+ 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();
+ const sid = scene.id();
+ const fps = world.get(FrameRate)?.value ?? 30;
+
+ const currentTime = computed.localTime[sid]!;
+ const localFrame = computed.localTime[eid]!;
+ const trimStart = trim.start[eid] ?? 0;
+
+ const playbackRate = entity.get(PlaybackRate)?.value ?? 1;
+ const delay = computed.delay[eid]!;
+ const trimEnd = trim.end[eid] ?? computed.duration[eid] ?? 0;
+
+ const audioOffset = audioPlayback.contextOffsetInSeconds[sid] ?? 0;
+ const playbackOffset = audioPlayback.timelineOffsetInSeconds[sid] ?? 0;
+ // In offline rendering the encoder pins contextOffset to 0 and playbackOffset
+ // to the workarea start, so this term shifts scheduled audio back into the
+ // encoded window (and resolves to 0 when there is no workarea).
+ const audioDelay = audioOffset - playbackOffset;
+ const bus = resolveAudioBus(world, entity);
+
+ if (!decoder.ready) {
+ framePromises(world)?.push(initPromise);
+ } else if (computed.visibility[eid] === 1 && playback.playing[sid] === true) {
+ const playPromise = decoder.playTo(bus, {
+ relativeFrom: localFrame / fps,
+ relativeTo: (localFrame + 15) / fps,
+ trimStart: trimStart / fps,
+ trimEnd: trimEnd / fps,
+ playbackRate,
+ currentTime: currentTime / fps,
+ relativeDelay: (delay / fps) + audioDelay,
+ });
+ framePromises(world)?.push(playPromise);
+ } else {
+ decoder.reset();
+ }
+}
+
+function forwardHtmlHost(world: World, scene: Entity, entity: Entity, fill: Entity): void {
+ const computed = store(world, Computed);
+ const host = fill.has(HtmlHostHandle) ? fill.get(HtmlHostHandle) : null;
+ if (world.get(Mode)?.value === 'realtime' || computed.visibility[entity.id()] !== 1 || !host) return;
+ framePromises(world)?.push(host.whenReady(computed.localTimeInSeconds[scene.id()] ?? 0));
+}
+
+function forwardImageDecoder(world: World, _scene: Entity, _entity: Entity, fill: Entity): void {
+ const resolvedDecoder = resolveImageDecoder(world, fill);
+ if (!resolvedDecoder) return;
+
+ const { decoder, initPromise } = resolvedDecoder;
+
+ if (!decoder.ready) {
+ framePromises(world)?.push(initPromise);
+ }
+}
+
+/**
+ * Forward decoders for a child entity and its node descendants.
+ */
+function forwardDecoders(world: World, scene: Entity, entity: Entity): void {
+ const paintStore = store(world, Paint);
+
+ const hidden = entity.has(Hidden) || entity.has(Culled);
+ const visualsEnabled = !hidden && world.get(Mode)?.value !== 'offline-audio';
+
+ let paintAudioSource: Entity | undefined;
+ if (!hidden) {
+ for (const fill of world.query(ChildOf(entity), Paint, Not(Deleted), Not(Hidden))) {
+ const paint = paintStore.value[fill.id()];
+
+ if (paint === PaintType.VIDEO) {
+ if (visualsEnabled) {
+ forwardVideoDecoder(world, scene, entity, fill);
+ }
+ paintAudioSource = fill;
+ }
+
+ if (paint === PaintType.SEQUENCE && visualsEnabled) {
+ forwardSequenceDecoder(world, scene, entity, fill);
+ }
+
+ if (paint === PaintType.IMAGE && visualsEnabled) {
+ forwardImageDecoder(world, scene, entity, fill);
+ }
+
+ if (paint === PaintType.HTML && visualsEnabled) {
+ forwardHtmlHost(world, scene, entity, fill);
+ }
+
+ if (paint === PaintType.SHADER && visualsEnabled) {
+ const ready = resolveShaderHost(world, fill)?.whenReady();
+ if (ready) framePromises(world)?.push(ready);
+ }
+ }
+ }
+
+ if (entity.has(Caption) && visualsEnabled) {
+ forwardCaptionDecoder(world, scene, entity);
+ }
+
+ if (entity.has(Audio) || paintAudioSource) {
+ forwardAudioDecoder(world, scene, entity, paintAudioSource);
+ }
+
+ for (const child of world.query(ChildOf(entity), Or(Geometry, Group, AdjustmentLayer), Not(Deleted), Not(Hidden))) {
+ forwardDecoders(world, scene, child);
+ }
+}
+
+function updateVisibility(world: World, scene: Entity, entity: Entity): void {
+ const computed = store(world, Computed);
+ const eid = entity.id();
+
+ // Root or dragging entity is always visible
+ if (entity === scene || entity.has(Dragging)) {
+ 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 start = computed.start[eid]!;
+ const end = computed.end[eid]!;
+
+ computed.localTime[eid] = Math.round((globalFrame - delay) * playbackRate);
+ computed.visibility[eid] = globalFrame >= start && globalFrame < end ? 1 : 0;
+ }
+
+ for (const child of world.query(Or(Geometry, Group, AdjustmentLayer), ChildOf(entity), Not(Deleted))) {
+ updateVisibility(world, scene, child);
+ }
+}
+
+function resetDecoders(world: World, entity: Entity): void {
+ if (entity.has(AudioDecoderHandle)) {
+ entity.get(AudioDecoderHandle)?.reset();
+ }
+
+ for (const child of world.query(ChildOf(entity), AudioDecoderHandle, Not(Deleted))) {
+ resetDecoders(world, child);
+ }
+}
+
+
+function collectAncestors(entity: Entity): Entity[] {
+ const path: Entity[] = [];
+
+ let current: Entity | null = entity;
+ while (current) {
+ path.push(current);
+ current = getParentNode(current);
+ }
+
+ return path.toReversed();
+}
+
+/**
+ * The entity's audio bus, building (and wiring) the ancestor bus chain on
+ * first use. Null when the world has no audio context.
+ */
+export function resolveAudioBus(world: World, entity: Entity): AudioBus | null {
+ const existing = entity.has(AudioBusHandle) ? entity.get(AudioBusHandle) : null;
+ if (existing) return existing;
+
+ const context = world.get(AudioEngine)?.context;
+ if (!context) return null;
+
+ const ancestors = collectAncestors(entity);
+
+ // Walk root -> leaf, connecting each bus's gain into its parent's input
+ // (root connects into the context destination). Reuse buses that already
+ // exist; only newly created ones need wiring.
+ let currentInput: AudioNode = context.destination;
+
+ for (const ancestor of ancestors) {
+ let bus = ancestor.has(AudioBusHandle) ? ancestor.get(AudioBusHandle) : null;
+
+ if (!bus) {
+ bus = new AudioBus(world, ancestor);
+ ancestor.add(AudioBusHandle);
+ ancestor.set(AudioBusHandle, bus);
+ bus.connect(currentInput);
+ }
+
+ currentInput = bus.input;
+ }
+
+ return entity.get(AudioBusHandle) ?? null;
+}
+
+function getGlobalFrame(world: World, entity: Entity): number {
+ const computed = store(world, Computed);
+
+ let current: Entity | null = entity;
+ while (current) {
+ if (current.has(Playback)) {
+ return computed.localTime[current.id()]!;
+ }
+ current = getParentNode(current);
+ }
+
+ return 0;
+}
+
+export function playbackSystem(world: World): void {
+ const computed = store(world, Computed);
+
+ // handle root playback
+ for (const entity of world.query(Playback, Not(Deleted))) {
+ advancePlayhead(world, entity);
+ }
+
+ const document = getDocument(world);
+ for (const entity of world.query(Or(Geometry, Group, AdjustmentLayer), ChildOf(document), Not(Deleted))) {
+ updateVisibility(world, entity, entity);
+ forwardDecoders(world, entity, entity);
+ }
+
+ // handle transition visibility
+ for (const clip of world.query(Or(Geometry, Group, AdjustmentLayer), Transition, Not(Deleted))) {
+ const parent = getParentNode(clip);
+
+ if (parent == null || !parent.has(Sequential)) {
+ console.info('Removing transition due to non-sequential parent', clip);
+ // System-driven cleanup of orphaned state — not a user edit.
+ clip.remove(Transition);
+ continue;
+ }
+
+ const children = world.query(ChildOf(parent), Or(Geometry, Group, AdjustmentLayer), Not(Deleted));
+ const partner = children.find(sibling => computed.start[sibling.id()] === computed.end[clip.id()]);
+ if (!partner) continue;
+ const window = getTransitionWindow(world, clip, partner);
+ const globalFrame = getGlobalFrame(world, clip);
+ if (globalFrame >= window.start && globalFrame < window.end) {
+ computed.visibility[clip.id()] = 1;
+ computed.visibility[partner.id()] = 1;
+ }
+ }
+
+ // Sync audio buses
+ let soloed: Set<Entity> | null = null;
+ for (const entity of world.query(AudioBusHandle, Not(Deleted))) {
+ entity.get(AudioBusHandle)?.sync();
+ if (!entity.has(Soloed)) continue;
+
+ if (soloed === null) {
+ soloed = new Set();
+ }
+
+ for (const ancestor of collectAncestors(entity)) {
+ soloed.add(ancestor);
+ }
+ }
+
+ if (soloed) {
+ for (const entity of world.query(AudioBusHandle, Not(Deleted))) {
+ if (!soloed.has(entity)) {
+ entity.get(AudioBusHandle)?.mute();
+ }
+ }
+ }
+
+ world.get(Mounts)?.advance();
+}
diff --git a/packages/runtime/src/utils/index.ts b/packages/runtime/src/utils/index.ts
index 6487bfec..198f68fc 100644
--- a/packages/runtime/src/utils/index.ts
+++ b/packages/runtime/src/utils/index.ts
@@ -7,3 +7,4 @@ export * from './live-mounts';
export * from './sort';
export * from './text-motion';
export * from './time';
+export * from './transition';
diff --git a/packages/runtime/src/utils/transition.ts b/packages/runtime/src/utils/transition.ts
new file mode 100644
index 00000000..3de916a1
--- /dev/null
+++ b/packages/runtime/src/utils/transition.ts
@@ -0,0 +1,36 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import { store } from '../world/store';
+import { Transition, Computed } from '../traits';
+
+import type { Entity, World } from 'koota';
+
+export type TransitionWindow = { start: number; end: number; midpointFrame: number };
+
+/**
+ * Compute the transition window between two adjacent clips.
+ *
+ * The left clip carries the Transition trait (describing the transition into
+ * its right neighbour).
+ */
+export function getTransitionWindow(
+ world: World,
+ left: Entity,
+ right: Entity,
+): TransitionWindow {
+ const computed = store(world, Computed);
+
+ const leftEnd = computed.end[left.id()]!;
+ const rightStart = computed.start[right.id()]!;
+
+ // Midpoint between the two clips, but never before the left clip ends
+ const midpointFrame = Math.max(Math.floor((leftEnd + rightStart) / 2), leftEnd);
+
+ const duration = store(world, Transition).duration[left.id()] ?? 1;
+ const start = midpointFrame - duration / 2;
+ const end = midpointFrame + duration / 2;
+
+ return { start, end, midpointFrame };
+}