Repository navigation
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.
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).
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"]
-
Probe the source. One FFmpeg pass over
source.webmfinds 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. -
Map time. A frozen stretch of at least
idle.thresholdMsplays back inidle.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. -
Plan the camera. It zooms on the target of every
click,fillandselect:- 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
-
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
- 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.
-
Compose. FFmpeg composes the frames and encodes H.264
yuv420pwith faststart. The file goes torender/ffmpeg.mp4and is recorded inresult.jsonunderrenders[].
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 amarkerof kindcaption.- 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
pressstep, the key or chord in the caption's style, such asControl + 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.envis 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.
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.
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.
- 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.webmstays untouched. - The renderer never draws browser chrome.
- The
renderingstage does not decide the watermark. A failed earlier render never marks the next one as failed.
- Running Demos
- Run Artifacts
- Secrets and Masking
- Project Configuration
- Status and Roadmap
- ADR-0004, recording is separate from rendering: docs/adr/0004-recording-is-separate-from-rendering.md
- ADR-0005, renderer chosen by spike: docs/adr/0005-renderer-chosen-by-spike.md
- ADR-0010, source video at viewport size: docs/adr/0010-source-video-at-viewport-size.md
- Spec 24, FFmpeg-only renderer: docs/specs/24-renderer-ffmpeg-only.md
- Spec 19, clock sync mark: docs/specs/19-clock-sync-mark.md
- Spec 73, visual baselines: docs/specs/73-visual-baselines.md
- Spec 91,
pressstep: docs/specs/91-press-step.md - Spec 100, window frame and background: docs/specs/100-window-frame-background.md
DemoFlow · Issues · Decision records · Specs · MIT licensed
Start
Features
- Scenarios
- Recording Scenarios
- Running Demos
- Rendering and Effects
- Secrets and Masking
- Run Artifacts
- MCP Server
Operate
Reference