ext/hyperframes
2
0
Fork 0
mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-04 16:42:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(skills): product-launch-video skill + consolidate motion knowledge into hyperframes-animation (#1745)

Browse Source 
* feat(skills): product-launch-video + consolidate motion knowledge into hyperframes-animation

- Add the product-launch-video skill: shot-sequence architecture where each
  visual frame is a time-coded shot sequence picked from a blueprint menu and
  paced to the voiceover (anti-PowerPoint). Includes the frame-worker sub-agent,
  story/visual/motion-design references, and audio/captions/transitions/
  stage-assets/assemble-index scripts.
- Consolidate motion knowledge in hyperframes-animation as the single source of
  truth: promote the updated atomic rules (31 -> 36) and rename product-launch-
  video's archetypes into hyperframes-animation blueprints (13 -> 15, replacing
  the old set). product-launch-video, faceless-explainer, and pr-to-video now
  reference them via ../hyperframes-animation/{rules-index,blueprints-index}.md
  and the rules/blueprints dirs. Fixes the discrete-text-sequence broken links;
  blueprints no longer ship per-id runnable examples, so example references in
  the consumers were dropped.
- Default HeyGen TTS voice to Marcia (deterministic; was the API's first English
  voice, which drifts on catalog re-sort). Override with --voice.
- assemble-index pre-assembly frame guards: auto-repair a sub-comp root missing
  canvas dims; hard-fail on <video>/<audio> inside a sub-comp; hard-fail on a
  timed non-root element missing class="clip" or overlapping same-track clips.
- Lint/CLI: lint media inside sub-compositions as an error; stop false-positive
  caption layout/lint findings; contrast/layout-audit skip elements hidden by an
  invisible ancestor.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(skills): clear CodeQL alerts in assemble-index.mjs

- script/style blanking regex now matches closing tags with trailing
  whitespace (</script >, </style >) — js/bad-tag-filter (high).
- drop the existsSync precheck before reading/repairing a frame file; read
  directly and handle ENOENT, removing the check->write TOCTOU window —
  js/file-system-race (high).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
WaterrrForever
2026-06-27 02:51:35 +08:00
committed by GitHub
co-authored by Claude Opus 4.8
parent 413d8187fd
commit 05af482f22
67 changed files with 3838 additions and 3006 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/hyperframes-animation/rules/motion-blur-streak.md
+328
View File
@@ -0,0 +1,328 @@
---
name: motion-blur-streak
description: Fake directional velocity blur on a fast entrance or camera push-through — blur peaks at max speed and resolves to 0 at the settle, so the element streaks in then snaps sharp. Two paths — SVG feGaussianBlur on the motion axis, or an echo/ghost trail that collapses into the lead.
metadata:
tags: motion-blur, velocity, streak, entrance, fly-in, ghost, echo, svg-filter, kinetic, camera, snap
---
# Motion-Blur Streak
Real per-frame motion blur isn't available to a seeked renderer (it integrates over shutter time, which a paused timeline has no concept of), so this rule **fakes** it for a fast element fly-in or a hard camera push-through. The blur **peaks at maximum velocity and resolves to 0 at the settle** — the element reads as streaking in then snapping sharp on arrival. The whole point is the _coupling_: the blur envelope rides the same ease and window as the position tween, so peak-blur lands exactly on peak-speed, and the element is razor-sharp the instant it stops.
Two implementation paths, both finite, deterministic, and seek-safe:
- **(A) Directional SVG blur** — an inline `<filter>` with `<feGaussianBlur stdDeviation="X 0">` (X on the axis of motion, 0 across it). GSAP tweens `X` from high → 0 through a proxy that calls `setAttribute` each frame. Cleanest, one element, true directional smear.
- **(B) Echo / ghost trail** — 2–4 duplicate copies at decreasing opacity, offset backward along the motion vector, collapsing into the lead element as it settles. No filter cost; reads as a "speed-line" stutter trail. Better when you want the streak _colored_ or _stylized_ rather than a literal optical blur.
This is for **entrances and mid-shot moves only** — a fast arrival, a beat that zooms past camera, a card slamming into a grid slot, a logo punching through into a lockup. **Never an exit on a non-final frame** (a blurred element fleeing off-frame mid-composition reads as a glitch, and a hard exit between scenes is the transition's job, not a per-element blur).
## How It Works
A fast move has a velocity profile: it accelerates off the start, peaks, then decelerates into the settle. An `out` ease (`expo.out`, `power4.out`) front-loads that — velocity is highest right at the start and bleeds to zero at the end. The fake works by mapping a **blur (or echo) envelope onto that same curve**:
1. **Position tween** — the element travels from an off-frame / pushed-back start to its resting transform (`x`/`y` for a fly-in, `scale` for a push-through) on a fast `out` ease over `MOVE_DUR`.
2. **Blur envelope** — in lockstep over the **same window and ease**, the smear goes from `PEAK_BLUR` → `0`. Because the ease front-loads velocity and the envelope shares it, max blur coincides with max speed, and blur hits exactly `0` as the element lands.
3. **Settle is sharp** — by `MOVE_START + MOVE_DUR` the element is at its resting transform with blur `0` (path A) or all echoes collapsed onto the lead (path B). It then holds, fully crisp, for the climax dwell.
Path A tweens the filter's `stdDeviation` attribute (a non-DOM-style numeric attribute) via a **proxy object** — GSAP can't tween an SVG attribute directly, so you tween a plain `{ v: PEAK_BLUR }` and write it back with `setAttribute` in `onUpdate`. Path B places the ghosts at deterministic backward offsets (`i * ECHO_STEP_PX`) and fades/collapses them on the same envelope.
## HTML
### Path A — directional SVG blur (recommended default)
```html
<div
class="scene"
id="streak-scene"
data-composition-id="streak-scene"
data-start="0"
data-duration="DURATION"
data-track-index="0"
>
<!-- Inline filter: blur on the X axis only (stdDeviation="X 0"); 0 on Y keeps it a clean horizontal smear. -->
<svg width="0" height="0" aria-hidden="true" style="position: absolute">
<defs>
<filter id="streak" x="-50%" y="-50%" width="200%" height="200%">
<feGaussianBlur id="streak-blur" in="SourceGraphic" stdDeviation="0 0" />
</filter>
</defs>
</svg>
<div class="streak-stage">
<div class="streak-el" id="streak-el">{phrase}</div>
</div>
</div>
```
### Path B — echo / ghost trail
```html
<div
class="scene"
id="streak-scene"
data-composition-id="streak-scene"
data-start="0"
data-duration="DURATION"
data-track-index="0"
>
<div class="streak-stage">
<!-- N-1 ghosts BEHIND the lead, then the lead on top. Ghosts are aria-hidden duplicates. -->
<div class="streak-ghost" data-i="3" aria-hidden="true">{phrase}</div>
<div class="streak-ghost" data-i="2" aria-hidden="true">{phrase}</div>
<div class="streak-ghost" data-i="1" aria-hidden="true">{phrase}</div>
<div class="streak-el" id="streak-el">{phrase}</div>
</div>
</div>
```
## CSS
```css
.scene {
position: relative;
width: 100%;
height: 100%;
display: grid;
place-items: center;
background: {sceneBg};
font-family: {font};
overflow: hidden; /* the smear/echo extends past the resting position before settling */
}
.streak-stage {
position: relative;
display: grid;
place-items: center;
}
.streak-el {
position: relative;
z-index: 2;
font-size: EL_FONT_SIZE;
font-weight: 900;
letter-spacing: EL_TRACKING;
color: {textColor};
/* Path A only — reference the directional filter. (Omit for Path B.) */
filter: url(#streak);
will-change: transform, filter;
}
/* Path B ghosts — identical glyphs behind the lead, decreasing opacity */
.streak-ghost {
position: absolute;
inset: 0;
display: grid;
place-items: center;
z-index: 1;
font-size: EL_FONT_SIZE;
font-weight: 900;
letter-spacing: EL_TRACKING;
color: {textColor};
opacity: 0;
will-change: transform, opacity;
pointer-events: none;
}
```
## GSAP Timeline
### Path A — directional SVG blur
```html
<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
// GSAP can't tween an SVG attribute directly — tween a proxy and write it back each frame.
const blurNode = document.getElementById("streak-blur");
const blurProxy = { v: PEAK_BLUR };
const writeBlur = () => blurNode.setAttribute("stdDeviation", `${blurProxy.v} 0`); // X-axis only
writeBlur(); // seed frame 0 so a seek to t=0 shows the streaked start, not a sharp pre-frame
// Position: travel from off-frame to rest on a fast `out` ease (velocity front-loaded).
tl.fromTo(
"#streak-el",
{ x: ENTER_FROM_X, opacity: 0 },
{ x: 0, opacity: 1, duration: MOVE_DUR, ease: MOVE_EASE },
MOVE_START,
);
// Blur envelope: SAME window + SAME ease so peak-blur == peak-speed, resolving to 0 at the settle.
tl.to(blurProxy, { v: 0, duration: MOVE_DUR, ease: MOVE_EASE, onUpdate: writeBlur }, MOVE_START);
window.__timelines["streak-scene"] = tl;
</script>
```
### Path B — echo / ghost trail
```html
<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
// Lead element: same fast `out` move as Path A.
tl.fromTo(
"#streak-el",
{ x: ENTER_FROM_X, opacity: 0 },
{ x: 0, opacity: 1, duration: MOVE_DUR, ease: MOVE_EASE },
MOVE_START,
);
// Ghosts: each starts FURTHER back along the motion vector (deterministic, by index),
// dimmer, and collapses onto the lead — all on the SAME ease/window so they vanish at the settle.
const ghosts = gsap.utils.toArray(".streak-ghost");
ghosts.forEach((g) => {
const i = Number(g.dataset.i); // 1..N-1, set in HTML (no Math.random)
tl.fromTo(
g,
{ x: ENTER_FROM_X - i * ECHO_STEP_PX, opacity: GHOST_BASE_OPACITY / i },
{ x: 0, opacity: 0, duration: MOVE_DUR, ease: MOVE_EASE },
MOVE_START,
);
});
window.__timelines["streak-scene"] = tl;
</script>
```
## Variations
### Vertical streak (rise / drop-in)
Swap the motion axis: use `y` instead of `x` for the position tween, `stdDeviation="0 Y"` for Path A (blur on Y, 0 on X), and `ENTER_FROM_Y` / vertical echo offsets for Path B. A phrase that streaks _up_ into place pairs with `kinetic-type-beats`' rise-rotate beat.
### Camera push-through (scale streak into a lockup)
Instead of translating, the element rushes the camera: `scale: SCALE_FROM → 1` on the fast `out` ease, with a **radial / zoom blur** feel approximated by a symmetric `stdDeviation="B B"` envelope (blur on both axes since the smear is depth-wise, not directional). This is the `logo-assemble-lockup` push-through — the wordmark punches forward out of soft focus and snaps crisp at the lock.
```js
tl.fromTo(
"#streak-el",
{ scale: SCALE_FROM, opacity: 0 },
{ scale: 1, opacity: 1, duration: MOVE_DUR, ease: MOVE_EASE },
MOVE_START,
);
tl.to(
blurProxy,
{
v: 0,
duration: MOVE_DUR,
ease: MOVE_EASE,
onUpdate: () => blurNode.setAttribute("stdDeviation", `${blurProxy.v} ${blurProxy.v}`),
},
MOVE_START,
);
```
### Staggered grid streak-in (cards assemble)
For `grid-card-assemble`: each card streaks into its slot from its own backward offset, staggered. Drive every card off the same ease/window with a per-index delay; derive the entrance offset and start time from the card's index (no `Math.random`). Each card is sharp the instant it lands in its slot.
```js
gsap.utils.toArray(".grid-card").forEach((card, i) => {
const at = MOVE_START + i * CARD_STAGGER;
tl.fromTo(
card,
{ x: ENTER_FROM_X, opacity: 0 },
{ x: 0, opacity: 1, duration: MOVE_DUR, ease: MOVE_EASE },
at,
);
// + a per-card blur proxy tween at the same `at` (Path A), or per-card ghosts (Path B)
});
```
### Hold-the-streak (whip emphasis on a single beat)
For a single kinetic phrase that "zooms past," keep the streak slightly visible a frame or two longer by easing the blur on a marginally _slower_ curve than the position (e.g. position `expo.out`, blur `power3.out`) — the element arrives, then the last wisp of smear resolves. Use sparingly; the default is locked envelopes.
## How to Choose Values
### Motion
- **MOVE_EASE** — shared ease for position and blur/echo.
- Range: `expo.out` (hardest snap), `power4.out` (hard slam, default), `power3.out` (firm but softer)
- Effects: harder `out` → velocity more front-loaded → blur reads as a sharper streak that resolves later in the window
- Constraints: must be an `out`-family ease (velocity front-loaded). An `inOut` or `in` ease puts peak speed mid/late and the blur-speed coupling breaks. **Position and blur must use the SAME ease** (except the deliberate Hold-the-streak variation).
- **MOVE_DUR** — travel + blur-resolve duration.
- Range: 0.25–0.6 s
- Effects: shorter → more violent whip; longer → a glide, the streak loses punch
- Constraints: a streak is _fast_ — over ~0.7 s it stops reading as velocity blur and looks like a focus pull
- **MOVE_START** — timeline position of the entrance.
- Constraints: leave **≥1 s of dwell** after `MOVE_START + MOVE_DUR` before the composition ends (climax dwell — a streak that lands at `t = DURATION − 0.2 s` reads as "flashed and gone")
- **ENTER_FROM_X / ENTER_FROM_Y** — off-frame start offset along the motion axis.
- Range: 40–120% of the element's own dimension on that axis (far enough to read as "came from off-frame")
- Effects: larger → longer travel → the streak has more runway to read; too small and there's no sense of speed
### Path A — SVG blur
- **PEAK_BLUR** — `stdDeviation` at maximum velocity (start of the window).
- Range: 8 (subtle) → 18 (default) → 30 (extreme whip)
- Effects: higher → heavier smear at peak speed; too high erases the glyph entirely at the start frame
- Constraints: ≤ ~30 — beyond that the element is unreadable for the first several frames and reads as "missing then appearing"; the filter region (`x/y/width/height` on `<filter>`) must be large enough (≥`-50% … 200%`) or the smear clips at the box edge
- **SCALE_FROM** (push-through variation) — starting scale for a camera push.
- Range: 1.3 (gentle push) → 2.5 (aggressive punch-through)
### Path B — echo trail
- **N (ghost count)** — number of ghosts behind the lead (set by how many `.streak-ghost` you author).
- Range: 2–4
- Effects: more ghosts → a longer, smoother smear; >4 reads as a stutter / strobe rather than a streak
- **ECHO_STEP_PX** — backward offset per ghost along the motion vector.
- Range: 12–40 px
- Effects: larger → a more spread-out, visible trail; smaller → a tight blur-like cluster
- Constraints: `(N) × ECHO_STEP_PX` should be ≲ `ENTER_FROM_X` so the furthest ghost still starts within the travel runway
- **GHOST_BASE_OPACITY** — opacity of the nearest ghost (`i = 1`); falls off as `BASE / i`.
- Range: 0.3 (faint) → 0.6 (pronounced)
- Constraints: ≤ ~0.6 — opaque ghosts read as duplicate elements, not a trail
### Layout & type
- **EL_FONT_SIZE / EL_TRACKING** — the streaking element's type weight (when it's a phrase).
- Constraints: heavy display weight (≥120 px at 1080p, ≥800 weight) so the smear has mass to streak; thin type smears into invisibility
- **CARD_STAGGER** (grid variation) — delay between consecutive cards.
- Range: 0.05–0.12 s — tight enough to read as one assembling wave, not separate arrivals
### Tokens
- **{sceneBg}** — background; a streak reads best against a solid / low-detail field (a busy bg fights the smear)
- **{font}** — typographic stack (embedded display face if the streaking element is text — see typography reference)
- **{textColor}** — element color; for Path B the ghosts inherit this, so a slightly desaturated trail can be had by tinting `.streak-ghost` separately
- **{phrase}** — the word / glyph / wordmark that streaks in
## Key Principles
- **Blur peaks at peak speed, resolves to 0 at the settle** — this is the whole rule. Share the ease and window between the position tween and the blur/echo envelope so they're locked. A blur that lingers after the element stops, or peaks after it's already slow, reads as a focus pull, not velocity.
- **`out`-family ease, always** — velocity must be front-loaded (fast off the start, decelerating in). `expo.out` / `power4.out` / `power3.out`. An `in` or `inOut` ease puts peak speed in the wrong place and the coupling falls apart.
- **Directional blur on the motion axis** (Path A) — `stdDeviation="X 0"` for horizontal, `"0 Y"` for vertical, `"B B"` only for a depth/scale push. A symmetric blur on a sideways move looks like defocus, not speed.
- **Tween a proxy, write the attribute** (Path A) — GSAP tweens the plain `{ v }` object; `onUpdate` calls `setAttribute("stdDeviation", …)`. You cannot tween the SVG attribute directly, and you must **seed it once at setup** so a seek to `t=0` shows the streaked start.
- **Ghosts are deterministic, by index** (Path B) — offset `i * ECHO_STEP_PX`, opacity `BASE / i`. Never `Math.random` for the trail; index drives all per-ghost variation so every seek is identical.
- **Entrances only, never a mid-composition exit** — a streak is an _arrival_. A blurred element leaving on a non-final frame reads as a glitch; scene-to-scene exits are the transition's job (see `../../transitions/overview.md`).
- **Earn the sharp hold** — after the snap, the crisp element must dwell ≥1 s. The contrast between the violent streak and the still, sharp settle _is_ the effect.
- **Heavy element, solid background** — thin type or a busy backdrop both swallow the smear. Big bold mass on a clean field reads.
## Critical Constraints
- **Timeline must be paused**: `gsap.timeline({ paused: true })`. Never `tl.play()`.
- **Registry key = `data-composition-id`** on the root.
- **No CSS `transition`** on the streaking element (or ghosts) — it interpolates independently of HF seek and causes flicker. Only GSAP drives the move and the blur.
- **No `repeat` / `yoyo` / infinite** — a streak is a single finite arrival. Finite tweens only.
- **No `Math.random` / `Date.now`** — ghost offsets/opacities and any stagger derive from the element index; deterministic every seek.
- **GSAP transform aliases only**: `x`, `y`, `scale`, `rotation`. Never tween `width` / `height` / `left` / `top`. Tweening `filter` (the proxy → `stdDeviation`) and `opacity` is seek-safe and fine.
- **Seed the SVG `stdDeviation` at setup** (Path A) — write it once before play so a seek to the first frame renders the streaked start, not a momentarily-sharp pre-frame.
- **Filter region must be generous** (Path A) — `<filter x="-50%" y="-50%" width="200%" height="200%">` so the smear doesn't clip at the element's box edge.
- **`overflow: hidden` on the scene** — the smear / furthest ghost extends past the resting position during travel; contain it so it doesn't bleed outside the frame.
## Combinations
- [kinetic-beat-slam.md](kinetic-beat-slam.md) — use this streak as the entrance for one phrase in a beat sequence (the scale-slam beat _is_ a motion-blur fly-in); reads its onset from the shared `BEATS[]` array
- [center-outward-expansion.md](center-outward-expansion.md) — the grid streak-in is center-expansion with a velocity-blur envelope on each element's travel
- [3d-text-depth-layers.md](3d-text-depth-layers.md) — extruded depth on the phrase that streaks in (depth layers ride the lead's transform)
- [scale-swap-transition.md](scale-swap-transition.md) — alternative for a SAME-footprint state swap (this rule is for a fast ARRIVAL from off-frame / depth, not a morph)
## Pairs with HF skills
- `/hyperframes-animation` — `out`-family easing, proxy-driven `onUpdate` attribute tweens, and locked-envelope coordination (`../../adapters/gsap-easing-and-stagger.md`)
- `/hyperframes-creative` — `references/typography.md` (embedded display face for a text streak), `references/video-composition.md` (solid field behind the smear)
- `/hyperframes-core` — composition wiring, determinism (finite tweens, no `Math.random`)
- `/hyperframes-cli` — `hyperframes lint` / `hyperframes validate` (validate catches a missing `#streak-blur` node or an unreferenced filter)