|
| 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`. |
0 commit comments