The VS Code of video editing, built for agents.
TypeScript
Enhance playhead management and update scene documentation
konstantin-paulus763ce7aa5c7c
diff --git a/apps/web/src/engine/history.ts b/apps/web/src/engine/history.tsindex 7b61c2ac..0f637b8c 100644--- a/apps/web/src/engine/history.ts+++ b/apps/web/src/engine/history.ts@@ -38,7 +38,7 @@ import type { CapturedNode, DocumentEditor, EntityEdit } from './editor';* is not what anyone means by undo, so they pass through to the file without* entering the history.*/-const EXCLUDED_PROPS: ReadonlySet<string> = new Set(['selected', 'active', 'camera', 'expanded', 'clipHeight', 'timeline']);+const EXCLUDED_PROPS: ReadonlySet<string> = new Set(['selected', 'active', 'camera', 'expanded', 'clipHeight', 'timeline', 'playhead']);/*** How long after one step a same-shaped step still merges into it. Editsdiff --git a/apps/web/src/engine/timeline/render/ruler.ts b/apps/web/src/engine/timeline/render/ruler.tsindex 129d6828..ddeb4429 100644--- a/apps/web/src/engine/timeline/render/ruler.ts+++ b/apps/web/src/engine/timeline/render/ruler.ts@@ -2,7 +2,7 @@* 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 { Playback, setPlayhead } from '@diffusionstudio/runtime';+import { Playback } from '@diffusionstudio/runtime';import { assert } from '@/utils';import { RULER_INTERVALS } from '../constants';@@ -13,7 +13,7 @@ import {RULER_TICK_HEIGHT_MINOR,TARGET_MAJOR_TICK_DISTANCE,} from '../config';-import { editWorkarea } from '../../timing';+import { editPlayhead, editWorkarea } from '../../timing';import { framesToPixels, getFrameRate, getResolution, getScrollX, getViewport, pixelsToFrames } from '../view';import type { Entity, World } from 'koota';@@ -21,9 +21,9 @@ import type { TimelineSurfaceState } from '../surface';/*** The time ruler, and the two gestures that belong to it: a drag scrubs the- * playhead, a shift-drag sets the work area. Both are ephemeral state, so- * neither is an edit — the file has nothing to say about where the playhead- * is or what part of the scene is being previewed.+ * playhead, a shift-drag sets the work area. Both go to the file, which is+ * where the project remembers them (`<scene playhead>`, `<scene workarea>`);+ * the writer coalesces a gesture's frames into one write.*/export function renderRuler(world: World, scene: Entity, surface: TimelineSurfaceState): void {const { ctx, pointer } = surface;@@ -50,7 +50,7 @@ export function renderRuler(world: World, scene: Entity, surface: TimelineSurfac// change something: the transport button is watching.if (scene.get(Playback)?.playing) scene.set(Playback, { playing: false });- setPlayhead(world, scene, pixelsToFrames(pointer.position.currentX + scrollX * resolution, resolution));+ editPlayhead(world, scene, pixelsToFrames(pointer.position.currentX + scrollX * resolution, resolution));}if (dragging && pointer.shiftPressed) {@@ -64,7 +64,7 @@ export function renderRuler(world: World, scene: Entity, surface: TimelineSurfac// The playhead follows the edge being dragged, so the frame under the// pointer is the one on the canvas.- setPlayhead(world, scene, pointer.position.currentX > pointer.position.initialX ? end : start);+ editPlayhead(world, scene, pointer.position.currentX > pointer.position.initialX ? end : start);}const interval = getRulerInterval(resolution);diff --git a/apps/web/src/engine/timing.ts b/apps/web/src/engine/timing.tsindex 80d68789..accaab3d 100644--- a/apps/web/src/engine/timing.ts+++ b/apps/web/src/engine/timing.ts@@ -24,6 +24,8 @@ import {getSourceFrameAt,getTimelineOrigin,secondsToFrames,+ setPlayhead,+ store,} from '@diffusionstudio/runtime';import { parseTime } from '@diffusionstudio/jsx';@@ -78,6 +80,22 @@ export function editWorkarea(world: World, scene: Entity, range: [start: number,);}+/**+ * Seeks the scene to `frame` and tells the file where the playhead now rests+ * (`<scene playhead>`), so the project reopens there. Only a gesture on the+ * timeline seeks this way: a step, a keyframe jump or playback itself moves+ * the playhead with `setPlayhead` and no word to the file — a write per frame+ * of playback is not worth what it costs — so the file lags until the next+ * scrub. No `previous`, so it never enters the history. The first frame is+ * reported as `false`, which the writer spells as the attribute's absence.+ */+export function editPlayhead(world: World, scene: Entity, frame: number): void {+ setPlayhead(world, scene, frame);+ const fps = world.get(FrameRate)?.value ?? 30;+ const at = store(world, Computed).localTime[scene.id()] ?? 0;+ getDocumentEditor(world).reportEdit(scene, 'playhead', at === 0 ? false : framesToSeconds(at, fps));+}+/*** 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 isdiff --git a/docs/reference/jsx/scene.md b/docs/reference/jsx/scene.mdindex 292771a3..cf21b776 100644--- a/docs/reference/jsx/scene.md+++ b/docs/reference/jsx/scene.md@@ -22,12 +22,13 @@ A scene is the **clipped, playable frame** a composition is made in, and the onl| `workarea` | `[in, out] \| null` | `null` | The stretch of the scene that plays and exports, in any [time format](./timing.md#time-formats). Without one the whole scene plays and exports, first frame to last || `selected` | `boolean` | absent | Whether the editor has the scene selected. || `timeline` | `[zoom, x, y]` | absent | Where the scene's timeline is looking: `zoom` in pixels per second of timeline, horizontal scroll in seconds, vertical scroll in pixels. Absent means the default zoom, at the beginning. |+| `playhead` | [time](./timing.md#time-formats) | absent | Where the playhead stands when the project is opened. Absent means the first frame. |A scene also takes paints as children, exactly as a `<rect>` does (see [paints.md](./paints.md)); `fill` is the shorthand for a solid one.## Editor state in the source-`active`, `selected`, `x`, `y` and `timeline` are editor concerns rather than part of the composition, but they live in the file for the same reason [`<stage>`](./stage.md)'s `camera` does: the source is the document, so a scene dragged or clicked on the canvas — or a timeline scrolled or zoomed — has nowhere else to be written back to. The editor writes them and removes them again; there is no need to author a `timeline`, and the first scroll or zoom overwrites one.+`active`, `selected`, `x`, `y`, `timeline` and `playhead` are editor concerns rather than part of the composition, but they live in the file for the same reason [`<stage>`](./stage.md)'s `camera` does: the source is the document, so a scene dragged or clicked on the canvas — or a timeline scrolled, zoomed or scrubbed — has nowhere else to be written back to. The editor writes them and removes them again; there is no need to author a `timeline` or a `playhead`, and the first scroll or zoom overwrites one. The playhead is written only by a scrub or a click on the ruler, never as playback moves it, so the file lags playback until the next scrub.Two rules the runtime holds for `active`: **at most one element is active**, and **only a root** — a direct child of `<stage>` — can be. A nested `active` is dropped, and when a file names more than one the last one rendered wins.diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.tsindex ec8d325d..4d8c4517 100644--- a/packages/jsx/src/types.ts+++ b/packages/jsx/src/types.ts@@ -457,6 +457,15 @@ export type SceneProps = IdentityProps & PositionProps & Required<Pick<SizeProps* an authored project: there is no need to write one.*/timeline?: TimelineView;+ /**+ * Where the playhead stands when the project is opened, in any time format.+ * Editor state carried by the source the way `timeline` is: nothing+ * rendered or exported depends on it, and the editor writes it when the+ * playhead is scrubbed or placed on the timeline — not as playback moves+ * it, so the file lags playback until the next scrub. Absent means the+ * first frame; there is no need to write one.+ */+ playhead?: Time;/*** Decibels on the scene's own bus, which everything in it mixes into: the* master fader. 0 = unity, negative attenuates (-6 = half as loud),diff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.tsindex 51c7a934..df3082d8 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, CAPTION_PRESET_FILLS, CAPTION_PRESET_STYLES, CaptionType, Chars, ClipHeight, ClipsContent, Computed, CornerRadius, createEntity, DEFAULT_BACKGROUND, Color, ColorStop, Delay, Effect, EffectType, Expanded, FontStyle, FramePromises, FrameRate, Generating, GenerationRequest, getActiveEntity, Loop, LoadRequest, Geometry, GeometryType, getEntityTree, getParentEntity, getParentNode, Hidden, Host, IsMask, isText, ItemIndex, KeepAspectRatio, Keyframe, KeyframeTrack, MixedCornerRadius, Mode, Muted, Name, Offset, Opacity, Paint, PaintType, parseColor, PendingSource, PendingSync, Playback, PlaybackRate, Position, removeChild, RenderSurface, resizeEntity, Scale, ScaleMode, ScaleModeType, secondsToFrames, getAsset, getEntityChildren, Group, Sequential, Shader, Size, Stage, Root, Rotation, Scene, Selected, Shadow, Source, SourceFrameRate, setCameraMatrix, setTimelineView, Stroke, StrokeCap, StrokeJoin, StrokeStyle, SyncRequest, TextAlign, TextBaseline, TextCase, TextRange, TextStyle, TranscriptionRequest, Transition, TransitionType, Trim, UniformScale, Volume, Workarea } from '@diffusionstudio/runtime';+import { Active, AdjustmentLayer, Animation, AnimationPhase, AnimationType, appendChild, AssetId, Audio, Background, bindAsset, BlendMode, BlendModeType, Blur, Caption, CaptionAlign, CAPTION_PRESET_FILLS, CAPTION_PRESET_STYLES, CaptionType, Chars, ClipHeight, ClipsContent, Computed, CornerRadius, createEntity, DEFAULT_BACKGROUND, Color, ColorStop, Delay, Effect, EffectType, Expanded, FontStyle, FramePromises, FrameRate, Generating, GenerationRequest, getActiveEntity, Loop, LoadRequest, Geometry, GeometryType, getEntityTree, getParentEntity, getParentNode, Hidden, Host, IsMask, isText, ItemIndex, KeepAspectRatio, Keyframe, KeyframeTrack, MixedCornerRadius, Mode, Muted, Name, Offset, Opacity, Paint, PaintType, parseColor, PendingSource, PendingSync, Playback, PlaybackRate, Position, removeChild, RenderSurface, resizeEntity, Scale, ScaleMode, ScaleModeType, secondsToFrames, getAsset, getEntityChildren, Group, Sequential, Shader, Size, Stage, Root, Rotation, Scene, Selected, Shadow, Source, SourceFrameRate, setCameraMatrix, setPlayhead, setTimelineView, Stroke, StrokeCap, StrokeJoin, StrokeStyle, SyncRequest, 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 { createSignal } from 'solid-js';import { SVGElements } from 'solid-js/web';@@ -834,6 +834,14 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {}return;}+ case 'playhead': {+ if (!entity.has(Scene)) return;+ const seconds = toSeconds(value);+ if (seconds !== undefined) {+ setPlayhead(this.world, entity, this.toFrames(seconds));+ }+ return;+ }case 'x':case 'y': {if (entity.has(Sequential)) return;