Skip to content

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.ts
index 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. Edits
diff --git a/apps/web/src/engine/timeline/render/ruler.ts b/apps/web/src/engine/timeline/render/ruler.ts
index 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.ts
index 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 is
diff --git a/docs/reference/jsx/scene.md b/docs/reference/jsx/scene.md
index 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.ts
index 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.ts
index 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;