Skip to content

Developer Rendering and Playback

Vivek Sarin edited this page Nov 20, 2026 · 2 revisions

Rendering and playback

FlowMotion draws a diagram as SVG and plays it with a clock. The DOM player and static renderer use the same frame function. Animated SVG uses compiled SMIL tracks; compare it with live playback at matching timestamps when changing rendering behavior.

The clock

Playback uses one simulated clock, t, in milliseconds. Every visual is a function of t:

  • frameAt(model, t) in src/render/frame.ts returns the state of every node, flow, and row at time t.
  • renderSvg in src/render/svg.ts draws that state as SVG.

The player can pause, seek, and step by simulated time. Static frames at t = 1500 and live playback at 1.5 seconds use the same model state. Theme palettes, CSS transitions, fonts, and SVG-viewer behavior can affect the final pixels.

Layers

Module Role
render/frame.ts Computes the frame for a time. frameAt returns the state, and the module sets the fade time for rows (the previous rows stay under the new row until its fade completes)
render/svg.ts Writes the SVG. renderSvg(model, { idPrefix, theme?, at?, smil?, transparent? }). The prefix allows several diagrams on one page
render/rows.ts Stacks the rows in a storyboard card. This module is shared by layout and rendering, so both agree on the height of a card
render/theme.ts light, dark, and the CSS-variable obsidian theme. snapshotObsidianTheme resolves Obsidian's palette to literal colors for SMIL output
render/model.ts The Model type. It is JSON-serializable and has no Obsidian or ELK dependency
runtime/player.ts The Player class. It owns the clock and the playback state
runtime/mount.ts Builds the controls and mounts a diagram into a container
runtime/browser.ts The browser entry point. It exports mountModel
export/html.ts Standalone output. See Exporting diagrams

The Player

Player is constructed with an SVG element, a model, and options: loop, speed, and onUpdate. Its public methods are:

Method Effect
play() and pause() Start and stop the clock
playNext(instant?) Play to the next storyboard beat/event boundary, then stop; jump there if instant is true
stepForward() and stepBack() Move to the next or previous event boundary
seek(t) Set the clock, clamped between 0 and the total length
reset() Pause and go to 0
replay() Go to 0 and play
setSpeed(s) Change the speed
total The length of the timeline, in milliseconds

When the clock reaches the end, the player either wraps to 0 (loop) or stops at the end and marks itself as not playing.

An interval started by playNext stops at its target even when looping is enabled. Pausing retains that target for resume; seeking or resetting clears it.

Mounting in the page

mountModel(container, model, options) creates the controls and returns { player, destroy }. Call destroy when the diagram is removed from the page.

The controls are:

  • Play and pause, step back, step forward, reset, and replay.
  • A timeline slider and a time readout, in seconds.
  • A speed menu. The values are 0.25, 0.5, 1, 2, and 4.
  • The screen mode: Fit, Normal, and Full screen. Normal is not offered when the diagram is on a .reveal slide, because it may not fit.
  • The background: default, light, dark, or none. This applies to draw.io drawings.
  • SVG ↓ downloads the full animated timeline using a standalone palette.

With model.view.interactive === true, Next is visible outside the expandable controls. Continuous Play/Replay and diagram-click playback are unavailable. Interactive mode suppresses autoplay and stops after each interval.

Reduced motion

When the page sets prefers-reduced-motion: reduce, ordinary playback initially seeks to the end without autoplay. Interactive mode starts at zero and Next jumps to the target boundary. The SVG also disables box transitions under the same media query.

Fit and sizing

Diagrams are fitted to the container by default. The height and width options set a maximum size, and the unit is px, vh, vw, or %. A bare number is read as pixels. The options come from src/core/view.ts, which parses them for both diagrams and storyboards.

Testing the output

  • test/render.test.ts checks the layout, the escaping of labels, the namespacing of ids, and the declarative animation used for SVG export.
  • test/static.test.ts checks the shapes, line styles, and groups for both input formats. See Testing and examples.

Related pages

Clone this wiki locally