mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-06 02:41:48 +00:00
docs(skill): sync hyperframes skill with upstream changes
Pulls the hyperframes skill up to the latest state of heygen-com/hyperframes skill content. Opened 2026-04-17; upstream has shipped CLI, layout, and path changes since. - SKILL.md: promote the visual-style check to a proper HARD-GATE (DESIGN.md > named style > ask 3 questions, with the #333/#3b82f6/Roboto tells); expand Step 6 to cover audio-reactive (mandatory per-frame tl.call() sampling loop — a single long tween does NOT react to audio), caption exit guarantee (hard tl.set kill after group.end), marker highlighting, and scene transitions; add the animation-map script to Verification; link the new features.md. - references/cli.md: add capture and validate (both shipped commands, both referenced from the workflow but missing from the reference). Add --lang to tts with the voice-prefix auto-inference table and espeak-ng dependency note (heygen-com/hyperframes#351, 2026-04-20 — after this PR opened). - references/website-to-video.md: update all paths to the capture/ subfolder layout introduced in heygen-com/hyperframes#345 (capture/screenshots/, capture/assets/, capture/extracted/tokens.json). Old captured/ prefix was broken — agents following the skill were looking for files in wrong locations. - references/features.md (new): distilled coverage for captions (language rule, tone table, word grouping, fitTextFontSize, exit guarantee), TTS (multilingual phonemization, speed tuning), audio-reactive (data format, mapping table, sampling pattern), marker highlighting (highlight/circle/burst/scribble/sketchout), and transitions (energy/ mood tables, presets, shader-compatible CSS rules). Five topics the original PR didn't cover.
This commit is contained in:
James
kshitij
parent
50aabb9eb2
commit
20859cc408
4 changed files with 360 additions and 24 deletions
|
|
@ -75,7 +75,16 @@ Before touching code, articulate at a high level:
|
|||
- **Visual identity** — colors, fonts, motion character (explosive / cinematic / fluid / technical)
|
||||
- **Hero frame** — for each scene, the moment when the most elements are simultaneously visible. This is the static layout you'll build first.
|
||||
|
||||
If the user hasn't specified a visual style, ask three questions before writing HTML: mood, light/dark, any brand colors/fonts/references. Write a short `DESIGN.md` at the project root capturing the answers.
|
||||
**Visual Identity Gate (HARD-GATE).** Before writing ANY composition HTML, a visual identity must be defined. Do NOT write compositions with default or generic colors (`#333`, `#3b82f6`, `Roboto` are tells that this step was skipped). Check in order:
|
||||
|
||||
1. **`DESIGN.md` at project root?** → Use its exact colors, fonts, motion rules, and "What NOT to Do" constraints.
|
||||
2. **User named a style** (e.g. "Swiss Pulse", "dark and techy", "luxury brand")? → Generate a minimal `DESIGN.md` with `## Style Prompt`, `## Colors` (3-5 hex with roles), `## Typography` (1-2 families), `## What NOT to Do` (3-5 anti-patterns).
|
||||
3. **None of the above?** → Ask 3 questions before writing any HTML:
|
||||
- Mood? (explosive / cinematic / fluid / technical / chaotic / warm)
|
||||
- Light or dark canvas?
|
||||
- Any brand colors, fonts, or visual references?
|
||||
|
||||
Then generate a `DESIGN.md` from the answers. Every composition must trace its palette and typography back to `DESIGN.md` or explicit user direction.
|
||||
|
||||
### 2. Scaffold
|
||||
|
||||
|
|
@ -114,11 +123,14 @@ Multi-scene compositions require transitions. Rules:
|
|||
|
||||
Use `npx hyperframes add <transition-name>` to install shader transitions (`flash-through-white`, `liquid-wipe`, etc.). Full list: `npx hyperframes add --list`.
|
||||
|
||||
### 6. Audio, captions, TTS
|
||||
### 6. Audio, captions, TTS, audio-reactive, highlighting
|
||||
|
||||
- **Audio:** always a separate `<audio>` element (video is `muted playsinline`).
|
||||
- **Captions:** run `npx hyperframes transcribe audio.mp3` to get word-level timings, then render with the captions component. See `references/composition.md` for the captions data attributes.
|
||||
- **TTS:** `npx hyperframes tts "Script text" --voice af_nova --output narration.wav`. List voices with `--list`.
|
||||
- **TTS:** `npx hyperframes tts "Script text" --voice af_nova --output narration.wav`. List voices with `--list`. Voice ID first letter encodes language (`a`/`b`=English, `e`=Spanish, `f`=French, `j`=Japanese, `z`=Mandarin, etc.) — the CLI auto-infers the phonemizer locale; pass `--lang` only to override. Non-English phonemization requires `espeak-ng` installed system-wide.
|
||||
- **Captions:** `npx hyperframes transcribe narration.wav` → word-level transcript. Pick style from the transcript tone (hype / corporate / tutorial / storytelling / social — see the table in `references/features.md`). **Language rule:** never use `.en` whisper models unless the audio is confirmed English — `.en` translates non-English audio instead of transcribing it. Every caption group MUST have a hard `tl.set(el, { opacity: 0, visibility: "hidden" }, group.end)` kill after its exit tween — otherwise groups leak visible into later ones.
|
||||
- **Audio-reactive visuals:** pre-extract audio bands (bass / mid / treble) and sample per-frame inside the timeline with a `for` loop of `tl.call(draw, [], f / fps)` — a single long tween does NOT react to audio. Map bass → `scale` (pulse), treble → `textShadow`/`boxShadow` (glow), overall amplitude → `opacity`/`y`/`backgroundColor`. Avoid equalizer-bar clichés — let content guide the visual, audio drive its behavior.
|
||||
- **Marker-style highlighting:** highlight, circle, burst, scribble, sketchout effects for text emphasis are deterministic CSS+GSAP — see `references/features.md#marker-highlighting`. Fully seekable, no animated SVG filters.
|
||||
- **Scene transitions:** every multi-scene composition MUST use transitions (no jump cuts). Pick from CSS primitives (push slide, blur crossfade, zoom through, staggered blocks) or shader transitions (`flash-through-white`, `liquid-wipe`, `cross-warp-morph`, `chromatic-split`, etc.) via `npx hyperframes add`. Mood and energy tables live in `references/features.md#transitions`. Do not mix CSS and shader transitions in the same composition.
|
||||
|
||||
### 7. Lint, preview, render
|
||||
|
||||
|
|
@ -150,19 +162,27 @@ Use the 7-step capture-to-video workflow in [references/website-to-video.md](ref
|
|||
|
||||
## Verification
|
||||
|
||||
After `render` completes, verify:
|
||||
Before and after rendering:
|
||||
|
||||
1. `final.mp4` exists and has non-zero size: `ls -lh final.mp4`
|
||||
2. Duration matches the composition's `data-duration`: `ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4`
|
||||
3. Visual check: open with a media player, or extract a mid-composition frame: `ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png`
|
||||
4. Audio present if expected: `ffprobe -v error -show_streams -select_streams a -of default=nw=1:nk=1 final.mp4 | head -1`
|
||||
1. **Lint + validate pass:** `npx hyperframes lint --strict && npx hyperframes validate` (WCAG contrast audit at 5 timestamps — see troubleshooting.md if warnings appear).
|
||||
2. **Animation choreography** — for new compositions or significant animation changes, run the animation map. `npx hyperframes init` copies the skill scripts into the project, so the path is project-local:
|
||||
```bash
|
||||
node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
|
||||
--out <composition-dir>/.hyperframes/anim-map
|
||||
```
|
||||
Outputs a single `animation-map.json` with per-tween summaries, ASCII Gantt timeline, stagger detection, dead zones (>1s with no animation), element lifecycles, and flags (`offscreen`, `collision`, `invisible`, `paced-fast` <0.2s, `paced-slow` >2s). Scan summaries and flags — fix or justify each. Skip on small edits.
|
||||
3. **File exists + non-zero:** `ls -lh final.mp4`.
|
||||
4. **Duration matches `data-duration`:** `ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4`.
|
||||
5. **Visual check:** extract a mid-composition frame: `ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png`.
|
||||
6. **Audio present if expected:** `ffprobe -v error -show_streams -select_streams a -of default=nw=1:nk=1 final.mp4 | head -1`.
|
||||
|
||||
If `hyperframes render` fails, run `npx hyperframes doctor` and attach its output when reporting.
|
||||
|
||||
## References
|
||||
|
||||
- [composition.md](references/composition.md) — data attributes, timeline contract, non-negotiable rules, typography/asset rules
|
||||
- [cli.md](references/cli.md) — every CLI command (init, lint, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark)
|
||||
- [cli.md](references/cli.md) — every CLI command (init, capture, lint, validate, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark)
|
||||
- [gsap.md](references/gsap.md) — GSAP core API for HyperFrames (tweens, eases, stagger, timelines, matchMedia)
|
||||
- [features.md](references/features.md) — captions, TTS, audio-reactive, marker highlighting, transitions (load on demand)
|
||||
- [website-to-video.md](references/website-to-video.md) — 7-step capture-to-video workflow
|
||||
- [troubleshooting.md](references/troubleshooting.md) — OpenClaw fix, env vars, common render errors
|
||||
|
|
|
|||
|
|
@ -4,11 +4,12 @@ Everything runs through `npx hyperframes` (or the globally-installed `hyperframe
|
|||
|
||||
## Workflow
|
||||
|
||||
1. **Scaffold** — `npx hyperframes init my-video`
|
||||
1. **Scaffold** — `npx hyperframes init my-video` (or `npx hyperframes capture <url>` if starting from a website)
|
||||
2. **Write** — author HTML composition (see `composition.md`)
|
||||
3. **Lint** — `npx hyperframes lint`
|
||||
4. **Preview** — `npx hyperframes preview`
|
||||
5. **Render** — `npx hyperframes render`
|
||||
4. **Validate** — `npx hyperframes validate` (WCAG contrast audit)
|
||||
5. **Preview** — `npx hyperframes preview`
|
||||
6. **Render** — `npx hyperframes render`
|
||||
|
||||
Always lint before preview/render — catches missing `data-composition-id`, overlapping tracks, and unregistered timelines.
|
||||
|
||||
|
|
@ -26,6 +27,19 @@ Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decisi
|
|||
|
||||
`init` creates the correct file structure, copies media, transcribes audio with Whisper, and installs authoring skills. Use it instead of creating files by hand.
|
||||
|
||||
## capture — Website → Editable Components
|
||||
|
||||
```bash
|
||||
npx hyperframes capture https://example.com # → captures/example.com/
|
||||
npx hyperframes capture https://stripe.com -o stripe-video # custom output dir
|
||||
npx hyperframes capture https://example.com --json # machine-readable output
|
||||
npx hyperframes capture https://example.com --skip-assets # skip images/SVGs
|
||||
```
|
||||
|
||||
Captures the site into `captures/<hostname>/capture/` by default, producing `capture/screenshots/`, `capture/assets/`, `capture/extracted/` (tokens.json, visible-text.txt, fonts.json), and a self-contained snapshot.
|
||||
|
||||
All downstream steps (DESIGN.md, SCRIPT.md, STORYBOARD, composition) read from the `capture/` subfolder — see `website-to-video.md`.
|
||||
|
||||
## lint
|
||||
|
||||
```bash
|
||||
|
|
@ -37,6 +51,15 @@ npx hyperframes lint --json # machine-readable output
|
|||
|
||||
Lints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (only with `--verbose`).
|
||||
|
||||
## validate
|
||||
|
||||
```bash
|
||||
npx hyperframes validate # WCAG contrast audit at 5 timestamps
|
||||
npx hyperframes validate --no-contrast # skip while iterating
|
||||
```
|
||||
|
||||
Seeks to 5 timestamps, screenshots the page, samples background pixels behind every text element, and warns on contrast ratios below 4.5:1 (normal text) or 3:1 (large text — 24px+, or 19px+ bold). Run before final render.
|
||||
|
||||
## preview
|
||||
|
||||
```bash
|
||||
|
|
@ -88,10 +111,12 @@ Produces word-level timings suitable for caption components. First run downloads
|
|||
```bash
|
||||
npx hyperframes tts "Text here" --voice af_nova --output narration.wav
|
||||
npx hyperframes tts script.txt --voice bf_emma
|
||||
npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
|
||||
npx hyperframes tts "Hello there" --voice af_heart --lang fr-fr --output accented.wav
|
||||
npx hyperframes tts --list # show all voices
|
||||
```
|
||||
|
||||
Uses Kokoro (local, no API key). Voice prefixes: `af_` (American female), `am_` (American male), `bf_` (British female), `bm_` (British male).
|
||||
Uses Kokoro (local, no API key). Voice ID first letter encodes language: `a` American English, `b` British English, `e` Spanish, `f` French, `h` Hindi, `i` Italian, `j` Japanese, `p` Brazilian Portuguese, `z` Mandarin. The CLI auto-infers the phonemizer locale from that prefix — pass `--lang` only to override (e.g. stylized accents). Valid `--lang` codes: `en-us`, `en-gb`, `es`, `fr-fr`, `hi`, `it`, `pt-br`, `ja`, `zh`. Non-English phonemization requires `espeak-ng` installed system-wide (`apt-get install espeak-ng` / `brew install espeak-ng`).
|
||||
|
||||
## doctor
|
||||
|
||||
|
|
|
|||
289
optional-skills/creative/hyperframes/references/features.md
Normal file
289
optional-skills/creative/hyperframes/references/features.md
Normal file
|
|
@ -0,0 +1,289 @@
|
|||
# HyperFrames Feature Reference
|
||||
|
||||
Load this file when a composition needs captions, TTS narration, audio-reactive visuals, marker-style text highlighting, or scene transitions. All patterns here are deterministic (no `Math.random()`, no `Date.now()`, no runtime audio analysis) and live on the same GSAP timeline as the rest of the composition.
|
||||
|
||||
## Captions
|
||||
|
||||
### Language Rule (Non-Negotiable)
|
||||
|
||||
**Never use `.en` whisper models unless the audio is confirmed English.** `.en` models TRANSLATE non-English audio into English instead of transcribing it.
|
||||
|
||||
- User says the language → `npx hyperframes transcribe audio.mp3 --model small --language <code>` (no `.en`)
|
||||
- User confirms English → `--model small.en`
|
||||
- Language unknown → `--model small` (auto-detects)
|
||||
|
||||
### Style Detection
|
||||
|
||||
If the user doesn't specify a caption style, detect it from the transcript tone:
|
||||
|
||||
| Tone | Font mood | Animation | Color | Size |
|
||||
| ------------ | ------------------------ | ---------------------------------- | --------------------------- | ------- |
|
||||
| Hype / launch | Heavy condensed, 800-900 | Scale-pop, `back.out(1.7)`, 0.1-0.2s | Bright on dark | 72-96px |
|
||||
| Corporate | Clean sans, 600-700 | Fade+slide, `power3.out`, 0.3s | White / neutral + muted accent | 56-72px |
|
||||
| Tutorial | Mono / clean sans, 500-600 | Typewriter or fade, 0.4-0.5s | High contrast, minimal | 48-64px |
|
||||
| Storytelling | Serif / elegant, 400-500 | Slow fade, `power2.out`, 0.5-0.6s | Warm muted tones | 44-56px |
|
||||
| Social | Rounded sans, 700-800 | Bounce, `elastic.out`, word-by-word | Playful, colored pills | 56-80px |
|
||||
|
||||
### Word Grouping
|
||||
|
||||
- High energy: 2-3 words, quick turnover.
|
||||
- Conversational: 3-5 words, natural phrases.
|
||||
- Measured / calm: 4-6 words.
|
||||
|
||||
Break on sentence boundaries, 150ms+ pauses, or a max word count.
|
||||
|
||||
### Positioning
|
||||
|
||||
- Landscape (1920x1080): bottom 80-120px, centered.
|
||||
- Portrait (1080x1920): ~600-700px from bottom, centered.
|
||||
- Never cover the subject's face. `position: absolute` (never relative). One caption group visible at a time.
|
||||
|
||||
### Text Overflow Prevention
|
||||
|
||||
Use the runtime helper so captions never overflow:
|
||||
|
||||
```js
|
||||
const result = window.__hyperframes.fitTextFontSize(group.text.toUpperCase(), {
|
||||
fontFamily: "Outfit",
|
||||
fontWeight: 900,
|
||||
maxWidth: 1600, // 1600 landscape, 900 portrait
|
||||
});
|
||||
el.style.fontSize = result.fontSize + "px";
|
||||
```
|
||||
|
||||
When per-word styling uses `scale > 1.0`, compute `maxWidth = safeWidth / maxScale` to leave headroom. Container needs `overflow: visible` (not `hidden` — hidden clips scaled emphasis words and glow).
|
||||
|
||||
### Caption Exit Guarantee
|
||||
|
||||
Every group MUST have a hard kill after its exit tween — otherwise groups leak into later ones:
|
||||
|
||||
```js
|
||||
tl.to(groupEl, { opacity: 0, scale: 0.95, duration: 0.12, ease: "power2.in" }, group.end - 0.12);
|
||||
tl.set(groupEl, { opacity: 0, visibility: "hidden" }, group.end); // deterministic kill
|
||||
```
|
||||
|
||||
### Per-Word Styling
|
||||
|
||||
Scan the transcript for words that deserve distinct treatment:
|
||||
|
||||
- Brand / product names — larger, unique color.
|
||||
- ALL CAPS — scale boost, flash, accent color.
|
||||
- Numbers / statistics — bold weight, accent color.
|
||||
- Emotional keywords — exaggerated animation (overshoot, bounce).
|
||||
- Call-to-action — highlight, underline, color pop.
|
||||
|
||||
## TTS (Kokoro-82M)
|
||||
|
||||
Local, no API key. Runs on CPU. Model downloads on first use (~311 MB + ~27 MB voices, cached in `~/.cache/hyperframes/tts/`).
|
||||
|
||||
### Voice Selection
|
||||
|
||||
| Content type | Voice | Why |
|
||||
| ------------- | ----------------------- | --------------------------- |
|
||||
| Product demo | `af_heart` / `af_nova` | Warm, professional |
|
||||
| Tutorial | `am_adam` / `bf_emma` | Neutral, easy to follow |
|
||||
| Marketing | `af_sky` / `am_michael` | Energetic or authoritative |
|
||||
| Documentation | `bf_emma` / `bm_george` | Clear British English |
|
||||
| Casual | `af_heart` / `af_sky` | Approachable, natural |
|
||||
|
||||
Run `npx hyperframes tts --list` for all 54 voices across 8 languages.
|
||||
|
||||
### Multilingual Phonemization
|
||||
|
||||
Voice ID first letter encodes language: `a`=American English, `b`=British English, `e`=Spanish, `f`=French, `h`=Hindi, `i`=Italian, `j`=Japanese, `p`=Brazilian Portuguese, `z`=Mandarin. The CLI auto-infers the phonemizer locale from that prefix — you don't need `--lang` when voice and text match.
|
||||
|
||||
```bash
|
||||
npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
|
||||
npx hyperframes tts "今日はいい天気ですね" --voice jf_alpha --output ja.wav
|
||||
```
|
||||
|
||||
Pass `--lang` only to override auto-detection (e.g. stylized accents):
|
||||
|
||||
```bash
|
||||
npx hyperframes tts "Hello there" --voice af_heart --lang fr-fr --output accented.wav
|
||||
```
|
||||
|
||||
Valid `--lang` codes: `en-us`, `en-gb`, `es`, `fr-fr`, `hi`, `it`, `pt-br`, `ja`, `zh`. Non-English phonemization requires `espeak-ng` installed system-wide (`apt-get install espeak-ng` / `brew install espeak-ng`).
|
||||
|
||||
### Speed
|
||||
|
||||
- `0.7-0.8` — tutorial, complex content
|
||||
- `1.0` — natural (default)
|
||||
- `1.1-1.2` — intros, upbeat content
|
||||
- `1.5+` — rarely appropriate
|
||||
|
||||
### TTS + Captions Workflow
|
||||
|
||||
```bash
|
||||
npx hyperframes tts script.txt --voice af_heart --output narration.wav
|
||||
npx hyperframes transcribe narration.wav # → transcript.json (word-level)
|
||||
```
|
||||
|
||||
## Audio-Reactive Visuals
|
||||
|
||||
Drive visuals from music, voice, or sound. Any GSAP-tweenable property can respond to pre-extracted audio data.
|
||||
|
||||
### Data format
|
||||
|
||||
```js
|
||||
const AUDIO_DATA = {
|
||||
fps: 30,
|
||||
totalFrames: 900,
|
||||
frames: [{ bands: [0.82, 0.45, 0.31, /* ... */] }, /* ... */],
|
||||
};
|
||||
```
|
||||
|
||||
`frames[i].bands[]` are frequency band amplitudes, 0-1. Index 0 = bass, higher indices = treble. Each band is normalized independently across the full track.
|
||||
|
||||
### Mapping audio to visuals
|
||||
|
||||
| Audio signal | Visual property | Effect |
|
||||
| ---------------------- | --------------------------------- | -------------------------- |
|
||||
| Bass (`bands[0]`) | `scale` | Pulse on beat |
|
||||
| Treble (`bands[12-14]`)| `textShadow`, `boxShadow` | Glow intensity |
|
||||
| Overall amplitude | `opacity`, `y`, `backgroundColor` | Breathe, lift, color shift |
|
||||
| Mid-range (`bands[4-8]`)| `borderRadius`, `width` | Shape morphing |
|
||||
|
||||
Any GSAP-tweenable property works — `clipPath`, `filter`, SVG attributes, CSS custom properties. Let content guide the visual and let audio drive its behavior. **Never add** equalizer bars, spectrum analyzers, waveform displays, rainbow cycling, or generic particle systems — they look cheap.
|
||||
|
||||
### Sampling pattern (required)
|
||||
|
||||
Audio reactivity needs per-frame sampling via a `for` loop of `tl.call()`, NOT a single tween. A single long tween does NOT react to audio:
|
||||
|
||||
```js
|
||||
for (let f = 0; f < AUDIO_DATA.totalFrames; f++) {
|
||||
tl.call(
|
||||
((frame) => () => draw(frame))(AUDIO_DATA.frames[f]),
|
||||
[],
|
||||
f / AUDIO_DATA.fps,
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Gotchas
|
||||
|
||||
- **textShadow on a container** with semi-transparent children (e.g. inactive caption words at `rgba(255,255,255,0.3)`) renders a visible glow rectangle behind every child. Apply the glow to active words individually, not to the container.
|
||||
- **Subtlety for text** — 3-6% scale variation, soft glow. Heavy pulsing makes text unreadable.
|
||||
- **Go bigger on non-text** — backgrounds and shapes can handle 10-30% swings.
|
||||
- **Deterministic only** — pre-extracted audio data, no Web Audio API, no runtime analysis.
|
||||
|
||||
## Marker-Style Highlighting
|
||||
|
||||
Deterministic CSS + GSAP implementations of the classic "highlight / circle / burst / scribble / sketchout" drawing modes for emphasizing text. Fully seekable — no animated SVG filters, no JS timers.
|
||||
|
||||
### Highlight (yellow marker sweep)
|
||||
|
||||
```html
|
||||
<span class="mh-highlight-wrap">
|
||||
<span class="mh-highlight-bar" id="hl-1"></span>
|
||||
<span class="mh-highlight-text">highlighted text</span>
|
||||
</span>
|
||||
```
|
||||
|
||||
```css
|
||||
.mh-highlight-wrap { position: relative; display: inline; }
|
||||
.mh-highlight-bar {
|
||||
position: absolute; inset: 0 -6px;
|
||||
background: #fdd835; opacity: 0.35;
|
||||
transform: scaleX(0); transform-origin: left center;
|
||||
border-radius: 3px; z-index: 0;
|
||||
}
|
||||
.mh-highlight-text { position: relative; z-index: 1; }
|
||||
```
|
||||
|
||||
```js
|
||||
tl.to("#hl-1", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.6);
|
||||
```
|
||||
|
||||
Multi-line: apply to `.mh-highlight-bar` with `stagger: 0.3`.
|
||||
|
||||
### Circle
|
||||
|
||||
Hand-drawn ellipse around a word. Use a positioned `::before` with `border-radius: 50%`, slight rotation, and `clip-path` to avoid covering the letters. Animate `clip-path` or `stroke-dashoffset` on an inline SVG circle.
|
||||
|
||||
### Burst
|
||||
|
||||
Short radiating lines around a word. Render 6-12 small `<span>` elements positioned in a radial pattern; animate `scaleY` from 0.
|
||||
|
||||
### Scribble
|
||||
|
||||
A chaotic overlay created by animating `stroke-dashoffset` on an inline SVG `<path>` with a `d` attribute describing a zig-zag. Seed values, never `Math.random()`.
|
||||
|
||||
### Sketchout
|
||||
|
||||
A rough rectangle outline. Two `<rect>`s with slight `transform` offsets, animated via `stroke-dashoffset`.
|
||||
|
||||
All five modes tween CSS transforms or `stroke-dashoffset` only — both tween cleanly, are deterministic, and seek correctly.
|
||||
|
||||
## Scene Transitions
|
||||
|
||||
Every multi-scene composition MUST use transitions. No jump cuts.
|
||||
|
||||
### Energy → primary transition
|
||||
|
||||
| Energy | CSS primary | Shader primary | Accent | Duration | Easing |
|
||||
| ------------------------------------ | ---------------------------- | ------------------------------------ | ------------------------------ | --------- | ------------------------ |
|
||||
| **Calm** (wellness, brand, luxury) | Blur crossfade, focus pull | Cross-warp morph, thermal distortion | Light leak, circle iris | 0.5-0.8s | `sine.inOut`, `power1` |
|
||||
| **Medium** (corporate, SaaS) | Push slide, staggered blocks | Whip pan, cinematic zoom | Squeeze, vertical push | 0.3-0.5s | `power2`, `power3` |
|
||||
| **High** (promos, sports, launch) | Zoom through, overexposure | Ridged burn, glitch, chromatic split | Staggered blocks, gravity drop | 0.15-0.3s | `power4`, `expo` |
|
||||
|
||||
Pick ONE primary (60-70% of scene changes) plus 1-2 accents. Never use a different transition for every scene.
|
||||
|
||||
### Mood → transition type
|
||||
|
||||
| Mood | Transitions |
|
||||
| ------------------------ | --------------------------------------------------------------------------- |
|
||||
| Warm / inviting | Light leak, blur crossfade, focus pull, film burn · _Shader:_ thermal distortion, cross-warp morph |
|
||||
| Cold / clinical | Squeeze, zoom out, blinds, shutter, grid dissolve · _Shader:_ gravitational lens |
|
||||
| Editorial / magazine | Push slide, vertical push, diagonal split, shutter · _Shader:_ whip pan |
|
||||
| Tech / futuristic | Grid dissolve, staggered blocks, blinds · _Shader:_ glitch, chromatic split |
|
||||
| Tense / edgy | Glitch, VHS, chromatic aberration, ripple · _Shader:_ ridged burn, domain warp |
|
||||
| Playful / fun | Elastic push, 3D flip, circle iris, morph circle · _Shader:_ swirl vortex, ripple waves |
|
||||
| Dramatic / cinematic | Zoom through, gravity drop, overexposure · _Shader:_ cinematic zoom, gravitational lens |
|
||||
| Premium / luxury | Focus pull, blur crossfade, color dip to black · _Shader:_ cross-warp morph |
|
||||
| Retro / analog | Film burn, light leak, VHS, clock wipe · _Shader:_ light leak |
|
||||
|
||||
### Presets
|
||||
|
||||
| Preset | Duration | Easing |
|
||||
| ---------- | -------- | ----------------- |
|
||||
| `snappy` | 0.2s | `power4.inOut` |
|
||||
| `smooth` | 0.4s | `power2.inOut` |
|
||||
| `gentle` | 0.6s | `sine.inOut` |
|
||||
| `dramatic` | 0.5s | `power3.in` → out |
|
||||
| `instant` | 0.15s | `expo.inOut` |
|
||||
| `luxe` | 0.7s | `power1.inOut` |
|
||||
|
||||
### Install a shader transition
|
||||
|
||||
```bash
|
||||
npx hyperframes add flash-through-white
|
||||
npx hyperframes add --list
|
||||
```
|
||||
|
||||
### CSS vs shader
|
||||
|
||||
- **CSS transitions** animate scene containers with opacity, transforms, `clip-path`, and filters. Simpler to set up.
|
||||
- **Shader transitions** composite both scene textures per-pixel on a WebGL canvas — can warp, dissolve, and morph in ways CSS cannot. Import from `@hyperframes/shader-transitions` instead of writing raw GLSL.
|
||||
|
||||
Don't mix CSS and shader transitions in the same composition — once a composition uses shader transitions, the WebGL canvas replaces DOM-based scene switching for every transition.
|
||||
|
||||
### Shader-compatible CSS rules
|
||||
|
||||
Shader transitions capture DOM scenes to WebGL textures via html2canvas. The canvas 2D pipeline doesn't match CSS exactly:
|
||||
|
||||
1. No `transparent` keyword in gradients — use the target color at zero alpha: `rgba(200,117,51,0)` not `transparent`. (Canvas interpolates `transparent` as `rgba(0,0,0,0)` creating dark fringes.)
|
||||
2. No gradient backgrounds on elements thinner than 4px. Use solid `background-color` on thin accent lines.
|
||||
3. No CSS variables (`var()`) on elements visible during capture — html2canvas doesn't reliably resolve custom properties. Use literal color values.
|
||||
4. Mark uncapturable decoratives with `data-no-capture` — they stay on the live DOM but are absent from the shader texture.
|
||||
5. No gradient opacity below 0.15 — renders differently in canvas vs CSS.
|
||||
6. Every `.scene` div must have explicit `background-color`, AND pass the same color as `bgColor` in the `init()` config. Without either, the texture renders as black.
|
||||
|
||||
These rules only apply to shader transition compositions. CSS-only compositions have no restrictions.
|
||||
|
||||
### Don't
|
||||
|
||||
- Mix CSS and shader transitions in one composition.
|
||||
- Use exit animations on any scene except the final scene — the transition IS the exit.
|
||||
- Introduce a new transition type every scene — pick one primary + 1-2 accents.
|
||||
- Use transitions that create visible geometric repetition (grids, hex cells, uniform dots) — they look artificial regardless of the math behind them. Prefer organic noise (FBM, domain warping).
|
||||
|
|
@ -7,16 +7,18 @@ The workflow has 7 steps. Each produces an artifact that gates the next. **Do no
|
|||
## Step 1: Capture & Understand
|
||||
|
||||
```bash
|
||||
npx hyperframes capture https://example.com --out captured/
|
||||
npx hyperframes capture https://example.com -o example-video
|
||||
```
|
||||
|
||||
Produces:
|
||||
- `captured/snapshot.html` — self-contained page
|
||||
- `captured/screenshot.png` — above-the-fold visual
|
||||
- `captured/assets/` — logos, hero images, background video (if any)
|
||||
- `captured/palette.json` — extracted colors (sorted by pixel coverage)
|
||||
- `captured/text.md` — extracted headings, paragraphs, CTAs
|
||||
- `captured/fonts.json` — font families and stacks detected in computed styles
|
||||
Produces `example-video/capture/` with:
|
||||
- `capture/screenshots/` — above-the-fold + section screenshots (up to `--max-screenshots`)
|
||||
- `capture/assets/` — logos, hero images, background video (if any)
|
||||
- `capture/extracted/tokens.json` — colors, fonts, and spacing tokens
|
||||
- `capture/extracted/visible-text.txt` — extracted headings, paragraphs, CTAs
|
||||
- `capture/extracted/fonts.json` — font families and stacks detected in computed styles
|
||||
- `capture/asset-descriptions.md` — auto-generated asset catalog
|
||||
|
||||
All subsequent steps read from the `capture/` subfolder — `capture/extracted/tokens.json`, `capture/assets/hero.png`, etc. Never strip the `capture/` prefix when referencing these files.
|
||||
|
||||
**Gate:** Print a site summary — name, top 3 colors, primary + display fonts, hero asset path, one-sentence vibe. Keep it in your context — don't re-capture.
|
||||
|
||||
|
|
@ -46,8 +48,8 @@ Small brand reference at the project root. 6 sections, ~90 lines. This is the ch
|
|||
- Eases: `power3.out` for entrances, `expo.in` for exits
|
||||
|
||||
## Assets
|
||||
- Logo: `captured/assets/logo.svg`
|
||||
- Hero image: `captured/assets/hero.png`
|
||||
- Logo: `capture/assets/logo.svg`
|
||||
- Hero image: `capture/assets/hero.png`
|
||||
|
||||
## What NOT to Do
|
||||
- No purple, no pastels, no serif body
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue