Skip to content

Rendering and Effects

Archi edited this page Oct 18, 2026 · 1 revision

Rendering and Effects

The renderer turns a raw recording and its timeline into the finished demo video. It draws a smooth cursor, click rings, camera zoom, captions, key badges and secret masks, puts the page in a rounded window on a background, and speeds through idle stretches. The result is an H.264 MP4.

Overview

Rendering is a separate step from recording (ADR-0004). The engine records the page at the viewport size, with no effects, and writes timeline.json. The renderer then reads source.webm, timeline.json and result.json from the run directory. From them it builds a JSON render plan: every keyframe, overlay and time mapping. A pure FFmpeg compositor draws that plan into render/ffmpeg.mp4 (ADR-0005, spec 24). Because the plan is data, the same run can be rendered again with different settings.

Every effect below has a committed reference image in packages/renderer/test/baselines/, and CI compares renders against them (spec 73).

How it works

flowchart LR
  A["source.webm"] --> P["buildRenderPlan"]
  B["timeline.json"] --> P
  C["result.json"] --> P
  D["render.* in<br/>demoflow.config.json"] --> P
  P --> Q["Render plan<br/>(time map, camera, cursor,<br/>rings, masks, captions,<br/>badges, frame, failure)"]
  Q --> F["FFmpeg compositor"]
  F --> O["render/ffmpeg.mp4"]
Loading
  1. Probe the source. One FFmpeg pass over source.webm finds its size, frame rate and frozen stretches. It also finds the clock sync mark, a full-frame magenta flash the engine paints before step 0. The renderer measures the offset between the video and the engine's clock from where the mark clears. Without a mark it falls back to a fixed −100 ms offset. The output starts on the first frame after the mark, so the flash never shows.
  2. Map time. A frozen stretch of at least idle.thresholdMs plays back in idle.compressToMs. This happens only when no active step is running (navigate, click, hover, press, fill, select, scroll). Waits and assertions on a still page get shorter; actions keep their real speed.
  3. Plan the camera. It zooms on the target of every click, fill and select:
    • in over 500 ms before the action, out over 400 ms after
    • the target fills at most 90% of the zoomed view
    • when the next target is within 400 px, or its zoom-in would start before the previous zoom-out ends, the camera keeps the zoom and pans instead
    • zoom is capped at 1.25 on a 1× source (the only kind the engine records today, ADR-0010) and at 1.6 on a 2× or larger source
  4. Plan the overlays:
    • the cursor glides along the real pointer path with ease-in-out
    • a 300 ms ring expands at each click point
    • captions and key badges are timed from the events
    • mask boxes come from each masked field's visibility intervals
  5. Plan failure. If readiness, execution, verification or recording failed, every frame gets a FAILED watermark, and a 3 s end card follows the last frame.
  6. Compose. FFmpeg composes the frames and encodes H.264 yuv420p with faststart. The file goes to render/ffmpeg.mp4 and is recorded in result.json under renders[].

Using it

Rendering runs as part of every demoflow run that recorded a video, including a run whose verification failed. There is no separate render command. To change the look, edit render in demoflow.config.json and run again.

What the video shows:

  • Cursor. A drawn cursor that moves from where the pointer was to where it went.

  • Click rings. A white ring that grows at each click for 300 ms.

  • Camera zoom. Zoom and pan on the element being clicked, filled or selected.

  • Captions. A lower-third with the step's caption, or the title of a marker of kind caption.

    • It shows from the step's start until 800 ms after its end.
    • A later caption cuts an earlier one.
    • It is set in the bundled Inter font (spec 25).
  • Key badges. For a press step, the key or chord in the caption's style, such as Control + a, below the target (or the pointer when there is no target). It stays until 600 ms after the step.

  • Masks. Every field filled from valueFrom.env is blurred while it is on the page:

    • a 4 px margin around the field
    • a 200 ms lead and trail (one source frame when the offset was measured)
    • the box follows the field through scrolls

    See Secrets and Masking.

  • Failure. A FAILED watermark on every frame and a 3 s end card reading <Stage> failed at step N: <message>, or <Stage> failed: <message> when no step is known. There is no end card on a successful run.

Note

Key badges (and the press step) are on develop, not in the npm release 0.1.0. They arrive in the next npm release after 0.1.0.

Window frame and background

By default the page sits in a centred window with rounded corners and a soft drop shadow, on a gradient background. There is no browser chrome: no title bar, no URL bar.

  • At zoom 1 the whole window and its margin are visible. When the camera zooms in, the background may leave the frame.
  • The cursor, rings and masks are drawn in the window's coordinates, so they move and scale with it.
  • Captions and the end card stay in output space.

Built-in background presets. Each is a two-stop gradient from the top left to the bottom right (135°):

Preset From To
ocean (default) #0b2e4f #2b86c5
sunset #f7a35c #d6457a
forest #0d3b2e #3a9a68
dusk #28215a #a24e8e
graphite #1c1f24 #4a515c
paper #f4f0e8 #d8d2c5
{
  "baseUrl": "http://localhost:3000",
  "render": {
    "frame": { "marginRatio": 0.08, "radius": 16 },
    "background": { "gradient": { "from": "#1e3a5f", "to": "#0f172a", "angle": 90 } }
  }
}

Warning

The window frame and background are on develop and are not in the npm release 0.1.0, which always renders the page full-bleed.

Settings

All keys live under render in demoflow.config.json and are optional.

Key Default Meaning
width 1920 Output width in px.
height 1080 Output height in px.
fps 30 Output frame rate.
idle.thresholdMs 1000 Shortest frozen stretch that counts as idle.
idle.compressToMs 400 How long an idle stretch plays in the output.
frame.enabled true false renders the page full-bleed, as before the frame existed.
frame.marginRatio 0.06 Margin on every side, as a share of the output height (0 to under 0.25).
frame.radius 12 Corner radius in output px at 1080p, scaled with the output height.
frame.shadow true Drop shadow under the window.
background { "preset": "ocean" } One of { "preset": … }, { "color": "#rrggbb" }, or { "gradient": { "from", "to", "angle" } }.

The gradient angle is in degrees (0–360), with the same meaning as in CSS linear-gradient: 0 points to the top, and angles go clockwise (90 points to the right). Colours must be #rrggbb. An unknown preset or a malformed colour is rejected when the config is loaded.

FFmpeg. The renderer uses ffmpeg on PATH if it has the libx264 encoder, and otherwise the bundled ffmpeg-static binary. A system FFmpeg without libx264, such as Fedora's ffmpeg-free, is skipped.

Limits / what it never does

  • The output format is MP4 only. GIF, WebM and 9:16 vertical export are not built yet (roadmap Phase 4).
  • Intro, scene and outro cards and transitions between scenes are not built yet.
  • Backgrounds are presets, solid colours or two-stop gradients. Images are not supported.
  • The renderer never adds effects to the source video: source.webm stays untouched.
  • The renderer never draws browser chrome.
  • The rendering stage does not decide the watermark. A failed earlier render never marks the next one as failed.

See also

Clone this wiki locally