@videoflow/renderer-dom

(host: HTMLElement): DomRenderer

(layerJSON: LayerJSON, index?: number): Promise<void>

Insert a new layer into the video at the given index (defaults to end). The new layer is constructed, initialized, and mounted into the existing `$canvas` — other layers' DOM elements are left untouched.

(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, layer: RuntimeBaseLayer, frame?: number): Promise<void>

Rasterize a single layer (cached when possible), pipe it through the WebGL effect compositor if it declares effects, and `drawImage` the result onto `ctx`. Used by `RuntimeGroupLayer.renderFrame` to flatten each child onto the group's canvas. The child's `blendMode` is honoured here via `globalCompositeOperation` so children inside a group blend identically in live preview and export. Without this, group-children blend modes would silently no-op in DomRenderer because the children render on the off-screen `virtualRoot` (their CSS `mix-blend-mode` never has a chance to take effect) — only the group's own composited canvas is on-screen.

(layerJSON: LayerJSON): RuntimeBaseLayer

Instantiate the runtime layer registered for `layerJSON.type`, wired to this renderer and the active project's fps / dimensions. Used for top-level layers and — via `ILayerRenderer` — by groups for their descendants. Throws for a type that isn't registered on this renderer.

(clearShadow: boolean): void

Tear down the renderer: stop playback (also exits smooth-playback mode on every video layer), destroy every runtime layer (releases media elements, decoders, and `requestVideoFrameCallback` subscriptions), clear the per-layer effect canvases, dispose the rasterizer's per-layer surfaces and the WebGL effect compositor's GL context, and finally empty the shadow DOM. Pending queued mutations registered before destroy resolve to no-ops via the `destroyed` guard.

(type: string): LayerTypeDescriptor | undefined

The descriptor registered for `type` on this renderer, if any.

(layerType: string): Record<string, PropertyDefinition> | undefined

Return the full propertiesDefinition for a layer type, or a single property's definition. Resolved through this renderer's layer-type registry, so an overridden type gets its overriding property definitions too.

(layerType: string, prop: string): PropertyDefinition | undefined

Return the full propertiesDefinition for a layer type, or a single property's definition. Resolved through this renderer's layer-type registry, so an overridden type gets its overriding property definitions too.

(): Node

Where group layers should park their hidden child host. We use the shadow root so renderer CSS (which is shadow-scoped) still applies to the group's children — without this, descendants would lose their `--vw` / `--project-*` context and render at the wrong scale.

(): string[]

Every layer type registered on this renderer, built-ins included.

(fontName: string): Promise<void>

Load a Google Font and make it available to the document (and shadow DOM).

(videoJSON: VideoJSON): Promise<void>

Load a compiled VideoJSON into the renderer. Sets up the shadow DOM, creates runtime layers, initialises media, and renders frame 0. Closes the registerLayerType window — synchronously on entry, so the cutoff doesn't depend on when the mutation queue gets around to the actual load.

(options: { fpsCallback?: (fps: number) => void }): Promise<void>

Start real-time playback from the current frame with audio sync. Renders audio to WAV, creates an `Audio` element, and advances frames inside a `requestAnimationFrame` loop while nudging the audio `playbackRate` to keep video and audio in sync. Frame dropping -------------- Targets are computed from wall-clock time (`Date.now() - startTime`) and each `renderFrame` call is fired-and-forget — playback never waits for a render to finish. If the renderer can't keep up (a single frame takes longer than one tick), renderFrame's internal `pendingFrame` slot supersedes the in-flight target with the latest one, so intermediates are skipped rather than serialized. Wall-clock time and audio stay live; the picture catches up to the most recent frame the renderer can produce. Each layer is switched into its smooth-playback path via RuntimeBaseLayer.enterSmoothPlayback at the start of the loop — for video layers this trades the per-frame `currentTime` seek for a native `<video>.play()` plus drift correction, eliminating the seek cost that otherwise dominates live-preview frame budget. The path is reverted on `stop()` / `seek()` so scrubbing stays frame-accurate.

(type: string, descriptor: LayerTypeDescriptor): void

Register (or replace) a layer type on **this** renderer. ```ts const renderer = new DomRenderer(host); renderer.registerLayerType('custom', { runtime: RuntimeCustomLayer, propertiesDefinition: CustomLayer.propertiesDefinition, }); await renderer.loadVideo(videoJSON); ``` Lifecycle: register after construction and **before** the first `loadVideo()`. Registrations stay attached to this instance, so every later `loadVideo()` / `addLayer()` uses them without re-registering. Registering after a video has been loaded throws rather than silently rebuilding the live runtime layers (which would drop their loaded media and mounted DOM) — construct a new DomRenderer instead. Registering a type that already exists (including a built-in) replaces the previous descriptor rather than throwing. The registry belongs to this instance: other renderers are unaffected.

(id: string): Promise<void>

Remove a layer from the video. Destroys the layer (releasing its media ref) and detaches its DOM element. Other layers are untouched.

(): Promise<AudioBuffer | null>

Render the full audio track as an AudioBuffer. Recurses through groups via the shared mixer — each group renders into its own intermediate buffer so the group's own `volume` / `pan` / `pitch` / `mute` / transitions apply to the whole sub-mix.

(frame: number, force: boolean): Promise<void>

Render a specific frame to the DOM. Skips if already at that frame (unless forced), queues if a render is already in progress.

(orderedIds: string[]): Promise<void>

Reorder layers to match the given id sequence. The runtime layers and the backing `videoJSON.layers` array are reordered, and the layers' `$element`s are re-appended to `$canvas` in the new order. For layers without a `track`, DOM order drives paint order. Layers with a `track` carry an explicit z-index (`track + 1`) written in `applyProperties`, so reordering them in the array without changing their `track` only changes DOM order, not visual stacking. No media is touched.

(frame: number): Promise<void>

Seek to a frame. If playback is active, stops it (which exits smooth mode), renders the target frame deterministically through the seek path, then restarts playback (re-entering smooth mode). When playback is not active, the frame is decoded by the seek path directly — pixel-deterministic, the same path used by export.

(): void

Stop playback. Bumps the play-token (so any loop suspended in `await renderAudio()` / `requestAnimationFrame` exits without running its cleanup), tears down the `Audio` element, and reverts every layer's smooth-playback hook so the next `renderFrame` (typically from `seek()` or `currentTime =`) decodes the exact requested timestamp instead of whatever the smooth decoder happened to be presenting.

(id: string, patch: { animations?: Animation[]; effects?: any[]; properties?: Record<string, any>; settings?: Partial<LayerSettingsJSON>; track?: number | null; transitionIn?: any; transitionOut?: any }): Promise<void>

Apply a property / settings / animations patch to a single layer. - `settings` is shallow-merged into `layer.json.settings`. - `properties` replaces `layer.json.properties` wholesale so keys removed by the editor (e.g. via a reset-to-default) are actually cleared. Callers should pass the full post-mutation properties object. - `animations` replaces the array wholesale (same rationale — callers hold the diffing logic because per-keyframe reconciliation is cheap to do in editor state). If `settings.source` changed, the layer's media is re-initialized via `layer.initialize()` — callers should debounce rapid source swaps. If a text layer's `fontFamily` is among the patched properties, the font is loaded into the shadow DOM before the frame is re-rendered.

(patch: { backgroundColor?: string; duration?: number; height?: number; name?: string; width?: number }): Promise<void>

Patch top-level video properties (width, height, backgroundColor, name, duration). `fps` changes are not supported here — they invalidate frame numbers across the pipeline and require a full `loadVideo()`. `duration` is safe to update incrementally: it's only used as the loop bound in `play()` and the divisor in the `totalFrames` getter; layer frame numbers depend on `fps`, not `duration`. An in-flight `play()` call captures `durationSec` at start, so the new bound takes effect on the next `play()` invocation.

(name: string, glsl: string, params: Record<string, EffectParamDefinition>): void

Register a GLSL effect. Shares its registry with `BrowserRenderer`.

(name: string, fn: TransitionFn): void

Register a transition preset. The registry is shared with `BrowserRenderer` so a transition registered on either renderer is available in both live preview and export.