Skip to content

Commit 4a78858

Browse files
vanceingallsclaude
andauthored
docs: guide and skill note for opt-in capture motion blur (#6049)
* docs: guide and skill note for opt-in capture motion blur Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * docs(motion-blur): scope the first-frame guarantee and the Chrome no-flag claim Co-Authored-By: Claude Sonnet 5.5 <[email protected]> --------- Co-authored-by: Claude Sonnet 5.5 <[email protected]>
1 parent 1cf4975 commit 4a78858

4 files changed

Lines changed: 90 additions & 1 deletion

File tree

‎docs/docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1001,6 +1001,7 @@
10011001
"concepts/frame-adapters",
10021002
"concepts/determinism",
10031003
"guides/html-in-canvas",
1004+
"guides/motion-blur",
10041005
"guides/vfx-chain",
10051006
"guides/figma"
10061007
]

‎docs/guides/motion-blur.mdx‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
title: "Motion Blur"
3+
description: "Smear fast-moving elements along their path, in Studio preview and in renders. Off until you turn it on."
4+
---
5+
6+
Capture motion blur gives fast-moving elements a real shutter smear. For each frame, HyperFrames reads where every mover was across the shutter interval and redraws it along that path. A box sliding across the frame leaves a streak instead of a sharp copy at one position.
7+
8+
It is **opt-in**. Nothing blurs until you add `data-motion-blur="on"` to the composition root.
9+
10+
## Turn it on
11+
12+
```html
13+
<div
14+
id="root"
15+
data-composition-id="main"
16+
data-width="1920"
17+
data-height="1080"
18+
data-duration="10"
19+
data-motion-blur="on"
20+
>
21+
...
22+
</div>
23+
```
24+
25+
That is all. The same attribute drives Studio preview and `hyperframes render`, so what you see is what you render.
26+
27+
| Attribute | Default | Meaning |
28+
| --- | --- | --- |
29+
| `data-motion-blur` | none | `on` enables blur. `off` opts out, on the root or on any subtree. |
30+
| `data-motion-blur-shutter` | `180` | Shutter angle in degrees, 0–720. Larger is a longer smear. |
31+
| `data-motion-blur-samples` | `16` | Sub-frame samples per frame, 2–64. More is smoother and slower. |
32+
| `data-motion-blur-events` | off | `on` also runs timeline callbacks (`onUpdate` and similar) at each sample. Use it when the motion is driven by callbacks, which blur cannot otherwise see. |
33+
34+
## What it blurs
35+
36+
Elements that move quickly in 2D: position, scale and rotation changes from GSAP, CSS animations and transitions, and the Web Animations API. Slow movers and static content are left sharp. A composition with nothing moving is never wrapped and does no per-frame blur work; the one-time discovery scan still runs on first play.
37+
38+
Blur is an image-space approximation. A mover's box and its contents move together, and glows or shadows outside its box stay sharp. 3D movers are skipped.
39+
40+
## Requirements
41+
42+
Blur draws through Chrome's [HTML in Canvas](/guides/html-in-canvas) API.
43+
44+
- **Renders** use the render browser, which HyperFrames launches with the API enabled.
45+
- **Studio preview** uses your own browser. We saw Chrome 157 and 158 expose the API without a flag, but only in headless and Chrome-for-Testing builds; whether it ships in stable Chrome is unverified. Chrome 155 and earlier need `chrome://flags/#html-in-canvas`. Preview detects the API and plays sharp when it is missing, so check your own browser rather than relying on a version number.
46+
47+
If Studio's browser cannot blur, Studio tells the render, and the render also skips blur so the output matches what you saw.
48+
49+
## When blur turns itself off
50+
51+
html-in-canvas captures a few things wrongly. A wrongly blurred frame is worse than a sharp one, so when HyperFrames finds one of these it turns blur off **for the whole composition, from the first frame**, instead of switching mid-render. This covers every defect the timeline scan can see. A defect the scan misses (a WebGL canvas added late, a root shake between scan samples, a face that flips hidden briefly) is caught per frame instead: that one frame renders sharp, blur resumes on the next, and the count is reported as `failedFrames`.
52+
53+
| Found in the composition | Why |
54+
| --- | --- |
55+
| A WebGL or WebGPU canvas anywhere in the document | Captured frozen. |
56+
| `backface-visibility: hidden` inside a 3D context (including from an animation) | Drawn mirrored. |
57+
| A transform on the root element | Ignored by the capture. |
58+
| Opacity below 1, or `mix-blend-mode`, on the root element | Not applied by the capture. |
59+
| An `iframe`, `object`, `embed` or custom element in the root | Not captured faithfully. |
60+
| A nested capture canvas, such as a VFX block | Hangs the renderer. |
61+
| An HDR render | The HDR compositor's layer mask does not reach the blur canvases. |
62+
| A distributed render | Chunks cannot share the single-page capture. |
63+
64+
Large see-through movers (a full-frame translucent sweep, say) are skipped too, because blurring them would drag the content underneath along. Their fast children still blur.
65+
66+
### Find out why it is off
67+
68+
```bash
69+
npx hyperframes check
70+
```
71+
72+
| Finding | Severity | Meaning |
73+
| --- | --- | --- |
74+
| `motion_blur_off` | warning | Blur is on but was switched off. The message names the cause and a fix. |
75+
| `motion_blur_no_movers` | info | Blur is on but nothing moves fast enough to blur. |
76+
| `motion_blur_unverified` | info | The check could not confirm blur in this browser. |
77+
78+
In the page, `window.__hfMotionBlur.report()` returns `state`, `reason`, `reasonCode` and `movers`. A render also logs one line per session saying whether blur ran and why not, plus a session-end line when any frames fell back to sharp (`failedFrames > 0`).
79+
80+
## Cost and limits
81+
82+
- **Render time.** About 1.7× for a blurred composition (median over 20 real compositions). Compositions where blur is off or nothing moves add only the one-time discovery scan (tens of milliseconds on a 25-mover composition).
83+
- **Editing.** The root is wrapped in the capture canvas only while playing or rendering. Paused, it is plain DOM, so click-to-select in Studio works as usual.
84+
- **Preview rate.** Blurred preview can run at half the frame rate on heavy compositions.
85+
- **Video.** A `<video>` drawn through the capture looks about 2–3% darker in Studio preview than in normal playback. Renders are not affected.
86+
- **Worker count.** Output is not bit-identical between worker counts (around 60 dB PSNR), about the size of the difference chunking already causes.
87+
- **Not handled.** Pose errors under CSS `zoom`, `position: fixed` and `foreignObject`; a very short Web Animations API animation that falls between scan samples; movers made see-through only by CSS backgrounds, masks or `clip-path`.

‎skills-manifest.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
"files": 2
77
},
88
"hyperframes": {
9-
"hash": "bf9e65d52f3ffdd6",
9+
"hash": "66d328f5c449b403",
1010
"files": 77
1111
},
1212
"hyperframes-cli": {

‎skills/hyperframes/references/motion.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
Measured frame by frame from the official HyperFrames launch films. These are defaults: a reference the person gave, or a Moment that does otherwise on purpose, wins for its own beat.
66

77
- **Moves**: a fast move takes 0.3–0.6 s and carries motion blur on its own ease, peaking at its fastest frame: 6–12 px on text-sized elements, 15–20 px full-frame, horizontal-only on a horizontal move. One move is one tween.
8+
- **Render-time blur**: for fast 2D movers, `data-motion-blur="on"` on the composition root smears them along their real path in preview and render (opt-in; also `data-motion-blur-shutter`, `-samples`, `-events="on"` for callback-driven motion). Suggest it when the person asks for blur or a filmic look and the piece moves fast; skip it when the composition has a WebGL canvas, a 3D flip with `backface-visibility`, a root transform or opacity, or an HDR render, because blur turns itself off there. After adding it run `hyperframes check`: `motion_blur_off` names the cause. About 1.7x render time. Guide: /guides/motion-blur.
89
- **Arrive slow, leave clean**: long-tailed ease-outs on arrivals; landing takes longer than leaving. An exit is one smooth motion, never slide, stop, then leave. Entrances that are too snappy read as glitches; slowing the whole video by about a second often fixes it.
910
- **Ease by role**: an arrival lands on a long tail (`expo.out`, `power4.out`), a camera move or a colour flood eases both ways (`power2.inOut`), a zoom through or an exit accelerates (`power3.in`). The same `power2.out` at 0.5 s on everything is the flat default that makes a film feel generated. Linear only for rotation, progress and constant speed that is the point.
1011
- **Springs** are named by damping ratio: 1.0 never bounces, 0.7-0.85 reads premium, 0.4-0.6 playful, under 0.3 a cartoon. Position and size may bounce; opacity and colour never do. GSAP's `elastic.out(1, 0.5)` and `back.out(1.4)` are the nearest built-ins; a closed-form spring of `t` keeps any frame renderable on its own.

0 commit comments

Comments
 (0)