diff --git a/.env.example b/.env.example index b8d357843c..efba0b0130 100644 --- a/.env.example +++ b/.env.example @@ -1,5 +1,5 @@ # No environment variables required for basic usage. -# Run `pnpm dev` to start the studio, `npx hyperframes render` to render video. +# Run `bun run dev` to start the studio, `npx hyperframes render` to render video. # Optional integrations: -# ANTHROPIC_API_KEY= # For AI-assisted composition via MCP +# GEMINI_API_KEY= # AI image captioning during website capture (https://aistudio.google.com/apikey) diff --git a/.gitignore b/.gitignore index bb67eb18d1..a9a510179a 100644 --- a/.gitignore +++ b/.gitignore @@ -64,26 +64,11 @@ skills-lock.json skills/hyperframes-animation-map/ skills/hyperframes-contrast/ -# Capture outputs (new captures go to captures/ by default) +# Capture outputs captures/ -notion-promo/ -notion-com-capture/ - -# Existing test captures at repo root (legacy) -notion-demo/ -notion-ai-agents/ -stripe-launch/ -stripe-investor/ -stripe-website/ -linear-ad/ -soulscape-demo/ -soulscape-film/ -midjourney/ -vercel-tour/ -figma-ad/ -arc-browser/ -raycast-demo/ -rive-demo/ -lusion-brand/ -motion-zajno/ -notion/ +# Legacy test captures at repo root (use captures/ instead) +*-capture/ +*-demo/ +*-ad/ +*-tour/ +*-brand/ diff --git a/bun.lock b/bun.lock index b42ee406ae..cd06728118 100644 --- a/bun.lock +++ b/bun.lock @@ -4,10 +4,6 @@ "workspaces": { "": { "name": "hyperframes-monorepo", - "dependencies": { - "patchright": "^1.59.3", - "purgecss": "^8.0.0", - }, "devDependencies": { "@commitlint/cli": "^20.5.0", "@commitlint/config-conventional": "^20.5.0", @@ -30,7 +26,6 @@ "hyperframes": "./dist/cli.js", }, "dependencies": { - "@google/genai": "^1.50.0", "@hono/node-server": "^1.8.0", "@puppeteer/browsers": "^2.13.0", "adm-zip": "^0.5.16", @@ -41,7 +36,6 @@ "hono": "^4.0.0", "mime-types": "^3.0.2", "open": "^10.0.0", - "playwright": "^1.59.1", "postcss": "^8.5.8", "prettier": "^3.8.1", "puppeteer-core": "^24.39.1", @@ -62,6 +56,9 @@ "typescript": "^5.0.0", "vitest": "^3.2.4", }, + "optionalDependencies": { + "@google/genai": "^1.50.0", + }, }, "packages/core": { "name": "@hyperframes/core", @@ -1297,10 +1294,6 @@ "parse5": ["parse5@7.3.0", "", { "dependencies": { "entities": "6.0.1" } }, "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw=="], - "patchright": ["patchright@1.59.3", "", { "dependencies": { "patchright-core": "v1.59.3" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": { "patchright": "cli.js" } }, "sha512-0i/6bXgv0rGz5khInk8nHb2sX9RbAu/whRUJDL3zvP5j0ovX9ITHF+o/3XlBu0UJ092YvQjO+8pGPEOnzHeeBA=="], - - "patchright-core": ["patchright-core@1.59.3", "", { "bin": { "patchright-core": "cli.js" } }, "sha512-EXq8a3nOoiubBtM77W9vYJDP/nFBuGaQK5CAzkaCr9/PTU5DPT1PDW0mDLdeX0P7bzSUgXEHiogHlC4zK2qSzw=="], - "path-key": ["path-key@3.1.1", "", {}, "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q=="], "path-parse": ["path-parse@1.0.7", "", {}, "sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw=="], @@ -1323,10 +1316,6 @@ "pkg-types": ["pkg-types@1.3.1", "", { "dependencies": { "confbox": "0.1.8", "mlly": "1.8.2", "pathe": "2.0.3" } }, "sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ=="], - "playwright": ["playwright@1.59.1", "", { "dependencies": { "playwright-core": "1.59.1" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": { "playwright": "cli.js" } }, "sha512-C8oWjPR3F81yljW9o5OxcWzfh6avkVwDD2VYdwIGqTkl+OGFISgypqzfu7dOe4QNLL2aqcWBmI3PMtLIK233lw=="], - - "playwright-core": ["playwright-core@1.59.1", "", { "bin": { "playwright-core": "cli.js" } }, "sha512-HBV/RJg81z5BiiZ9yPzIiClYV/QMsDCKUyogwH9p3MCP6IYjUFu/MActgYAvK0oWyV9NlwM3GLBjADyWgydVyg=="], - "postcss": ["postcss@8.5.8", "", { "dependencies": { "nanoid": "3.3.11", "picocolors": "1.1.1", "source-map-js": "1.2.1" } }, "sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg=="], "postcss-import": ["postcss-import@15.1.0", "", { "dependencies": { "postcss-value-parser": "4.2.0", "read-cache": "1.0.0", "resolve": "1.22.11" }, "peerDependencies": { "postcss": "8.5.8" } }, "sha512-hpr+J05B2FVYUAXHeK1YyI267J/dDDhMU6B6civm8hSY1jYJnBXxzKDKDswzJmtLHryrjhnDjqqp/49t8FALew=="], @@ -1655,12 +1644,8 @@ "parse5/entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="], - "patchright/fsevents": ["fsevents@2.3.2", "", { "os": "darwin" }, "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA=="], - "path-scurry/lru-cache": ["lru-cache@10.4.3", "", {}, "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ=="], - "playwright/fsevents": ["fsevents@2.3.2", "", { "os": "darwin" }, "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA=="], - "postcss-load-config/jiti": ["jiti@1.21.7", "", { "bin": { "jiti": "bin/jiti.js" } }, "sha512-/imKNG4EbWNrVjoNC/1H5/9GFy+tqjGBHCaSsN+P2RnPqjsLmv6UD3Ej+Kj8nBWaRAwyk7kK5ZUc+OEatnTR3A=="], "postcss-nested/postcss-selector-parser": ["postcss-selector-parser@6.1.2", "", { "dependencies": { "cssesc": "3.0.0", "util-deprecate": "1.0.2" } }, "sha512-Q8qQfPiZ+THO/3ZrOrO0cJJKfpYCagtMUkXbnEfmgUjwXg6z/WBeOyS9APBBPCTSiDV+s4SwQGu8yFsiMRIudg=="], diff --git a/package.json b/package.json index a5329c0740..21c9beabe7 100644 --- a/package.json +++ b/package.json @@ -28,10 +28,6 @@ "generate:previews": "tsx scripts/generate-template-previews.ts", "prepare": "test -d .git && lefthook install || true" }, - "dependencies": { - "patchright": "^1.59.3", - "purgecss": "^8.0.0" - }, "devDependencies": { "@commitlint/cli": "^20.5.0", "@commitlint/config-conventional": "^20.5.0", diff --git a/packages/cli/package.json b/packages/cli/package.json index f26aa0129a..931fa8e160 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -25,7 +25,6 @@ "typecheck": "tsc --noEmit" }, "dependencies": { - "@google/genai": "^1.50.0", "@hono/node-server": "^1.8.0", "@puppeteer/browsers": "^2.13.0", "adm-zip": "^0.5.16", @@ -36,7 +35,6 @@ "hono": "^4.0.0", "mime-types": "^3.0.2", "open": "^10.0.0", - "playwright": "^1.59.1", "postcss": "^8.5.8", "prettier": "^3.8.1", "puppeteer-core": "^24.39.1", @@ -57,6 +55,9 @@ "typescript": "^5.0.0", "vitest": "^3.2.4" }, + "optionalDependencies": { + "@google/genai": "^1.50.0" + }, "engines": { "node": ">=22" } diff --git a/packages/cli/src/capture/agentPromptGenerator.ts b/packages/cli/src/capture/agentPromptGenerator.ts index 293d06964f..9df7f38ddf 100644 --- a/packages/cli/src/capture/agentPromptGenerator.ts +++ b/packages/cli/src/capture/agentPromptGenerator.ts @@ -48,7 +48,7 @@ function buildPrompt( const title = tokens.title || hostname; const cues = detectImplementationCues(tokens, animations); - const colorSummary = tokens.colors.slice(0, 6).join(", "); + const colorSummary = tokens.colors.slice(0, 10).join(", "); const fontSummary = tokens.fonts.join(", ") || "none detected"; const sectionCount = tokens.sections?.length ?? 0; const headingCount = tokens.headings?.length ?? 0; @@ -75,7 +75,7 @@ If you don't have the skill installed, run: \`npx skills add heygen-com/hyperfra | File | Contents | |------|----------| -${hasScreenshot ? "| `screenshots/full-page.png` | Full-page screenshot (very tall — hard to read details, use scroll screenshots instead) |\n| `screenshots/scroll-0.png` | Hero section at 1920x1080 — **VIEW THIS FIRST** to understand the site's look and feel |\n| `screenshots/scroll-25.png` | Page at 25% scroll — 1920x1080 readable viewport |\n| `screenshots/scroll-50.png` | Page at 50% scroll — 1920x1080 readable viewport |\n| `screenshots/scroll-75.png` | Page at 75% scroll — 1920x1080 readable viewport |\n| `screenshots/scroll-100.png` | Page bottom at 1920x1080 — footer and final sections |" : ""} +${hasScreenshot ? "| `screenshots/scroll-*.png` | Viewport screenshots covering the full page (1920x1080 each, 30% overlap). **View scroll-000.png FIRST** (hero section), then scan through the rest to understand the full page. |" : ""} | \`extracted/tokens.json\` | Design tokens: ${tokens.colors.length} colors, ${tokens.fonts.length} fonts, ${headingCount} headings, ${ctaCount} CTAs, ${sectionCount} sections | | \`extracted/visible-text.txt\` | All visible text content in DOM order — use exact strings, never paraphrase | | \`extracted/assets-catalog.json\` | Every asset URL (images, fonts, videos, icons) with HTML context | diff --git a/packages/cli/src/capture/assetDownloader.ts b/packages/cli/src/capture/assetDownloader.ts index 2fc7c8acf2..8571098eca 100644 --- a/packages/cli/src/capture/assetDownloader.ts +++ b/packages/cli/src/capture/assetDownloader.ts @@ -198,10 +198,39 @@ export async function downloadAndRewriteFonts(css: string, outputDir: string): P if (fontUrls.size === 0) return css; + // Limit font downloads to avoid bloat. Google Fonts serves 20+ unicode-range + // subsets per weight — we only need a few per family for video production. + const MAX_FONTS_PER_FAMILY = 6; + const MAX_TOTAL_FONTS = 30; + const familyCounts = new Map(); + + // Extract font-family from the @font-face rule containing each URL + const getFamilyForUrl = (url: string): string => { + const idx = css.indexOf(url); + if (idx === -1) return "_unknown"; + const blockStart = css.lastIndexOf("@font-face", idx); + if (blockStart === -1) return "_unknown"; + const blockSlice = css.slice(blockStart, idx); + const familyMatch = blockSlice.match(/font-family\s*:\s*['"]?([^'";}\n]+)/i); + return familyMatch?.[1] ? familyMatch[1].trim().toLowerCase() : "_unknown"; + }; + + // Prioritize Latin subsets over CJK/Arabic/etc unicode ranges + const sortedUrls = Array.from(fontUrls).sort((a, b) => { + const aLatin = /latin|[A-Za-z0-9]{10,}\.woff/.test(a) ? 0 : 1; + const bLatin = /latin|[A-Za-z0-9]{10,}\.woff/.test(b) ? 0 : 1; + return aLatin - bLatin; + }); + let rewritten = css; let count = 0; - for (const fontUrl of fontUrls) { + for (const fontUrl of sortedUrls) { + if (count >= MAX_TOTAL_FONTS) break; + const family = getFamilyForUrl(fontUrl); + const familyCount = familyCounts.get(family) || 0; + if (familyCount >= MAX_FONTS_PER_FAMILY) continue; + try { const urlObj = new URL(fontUrl); const filename = urlObj.pathname.split("/").pop() || `font-${count}.woff2`; @@ -212,6 +241,7 @@ export async function downloadAndRewriteFonts(css: string, outputDir: string): P if (buffer) { writeFileSync(localPath, buffer); rewritten = rewritten.split(fontUrl).join(relativePath); + familyCounts.set(family, familyCount + 1); count++; } } catch { diff --git a/packages/cli/src/capture/htmlExtractor.ts b/packages/cli/src/capture/htmlExtractor.ts index f204185006..ea662fe7ce 100644 --- a/packages/cli/src/capture/htmlExtractor.ts +++ b/packages/cli/src/capture/htmlExtractor.ts @@ -59,13 +59,16 @@ export async function extractHtml( }); // Add the CSS as a + +`; + const result = lintHyperframeHtml(html); + const conflicts = result.findings.filter((f) => f.code === "gsap_css_transform_conflict"); + expect(conflicts.length).toBeGreaterThanOrEqual(1); + }); + it("reports error when GSAP is used without a GSAP script tag", () => { const html = ` diff --git a/skills/website-to-hyperframes/SKILL.md b/skills/website-to-hyperframes/SKILL.md index 5be31630a9..8d73fefd50 100644 --- a/skills/website-to-hyperframes/SKILL.md +++ b/skills/website-to-hyperframes/SKILL.md @@ -119,5 +119,3 @@ Lint, validate, preview. Create a HANDOFF.md for multi-session continuity. | [step-6-build.md](references/step-6-build.md) | Step 6 — building compositions with self-review | | [step-7-validate.md](references/step-7-validate.md) | Step 7 — lint, validate, preview, handoff | | [techniques.md](references/techniques.md) | Steps 4 & 6 — 10 visual techniques with code patterns (SVG drawing, Canvas 2D, 3D, typography, Lottie, video, typing, variable fonts, MotionPath, transitions) | -| [asset-sourcing.md](references/asset-sourcing.md) | When you need logos, icons, or photos not in the capture | -| [video-recipes.md](references/video-recipes.md) | Scene patterns, 5-layer system, mid-scene activity | diff --git a/skills/website-to-hyperframes/references/asset-sourcing.md b/skills/website-to-hyperframes/references/asset-sourcing.md deleted file mode 100644 index c6559fe1d8..0000000000 --- a/skills/website-to-hyperframes/references/asset-sourcing.md +++ /dev/null @@ -1,141 +0,0 @@ -# Asset Sourcing Guide - -How to find and download free assets when the capture doesn't have what you need, or when there's no capture at all. - -**Rule:** Only source assets when the video plan references something that doesn't exist in `assets/`. Don't speculatively download 30 images "just in case." - -## Brand Logos (SVG) - -**Simple Icons** — 3000+ brand logos, SVG, CC0 license, no rate limit. - -```bash -# Download by brand name (lowercase, no spaces) -curl -o assets/svgs/stripe.svg "https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/stripe.svg" -curl -o assets/svgs/vercel.svg "https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/vercel.svg" -curl -o assets/svgs/github.svg "https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/github.svg" -``` - -Brand names: use the slug from [simpleicons.org](https://simpleicons.org). Common ones: `stripe`, `vercel`, `notion`, `figma`, `slack`, `discord`, `github`, `linear`, `openai`, `anthropic`, `google`, `apple`, `microsoft`, `amazon`, `netflix`, `spotify`, `airbnb`, `uber`, `coinbase`, `shopify`. - -These SVGs are monochrome (single path). To use with brand colors, set `fill` in CSS or inline: - -```html - - -``` - -## Company Logos (PNG) - -**Clearbit Logo API** — Any company's logo by domain. No API key. PNG format. - -```bash -curl -o assets/logo-stripe.png "https://logo.clearbit.com/stripe.com" -curl -o assets/logo-linear.png "https://logo.clearbit.com/linear.app" -curl -o assets/logo-notion.png "https://logo.clearbit.com/notion.so" -``` - -Returns the company's actual logo (usually with transparency). Size varies. Use when you need a full-color logo, not just the icon. - -## Icons (SVG) - -**Lucide** — 5000+ open-source icons, SVG, ISC license. Consistent 24x24 viewBox, 2px stroke. - -```bash -# Download by icon name (kebab-case) -curl -o assets/svgs/icon-chart.svg "https://cdn.jsdelivr.net/npm/lucide-static@latest/icons/bar-chart-3.svg" -curl -o assets/svgs/icon-shield.svg "https://cdn.jsdelivr.net/npm/lucide-static@latest/icons/shield-check.svg" -curl -o assets/svgs/icon-zap.svg "https://cdn.jsdelivr.net/npm/lucide-static@latest/icons/zap.svg" -curl -o assets/svgs/icon-globe.svg "https://cdn.jsdelivr.net/npm/lucide-static@latest/icons/globe.svg" -``` - -Common categories: - -- **Business:** `briefcase`, `building-2`, `users`, `trending-up`, `dollar-sign`, `credit-card` -- **Tech:** `code-2`, `terminal`, `database`, `server`, `cpu`, `wifi`, `smartphone` -- **UI:** `check-circle`, `x-circle`, `alert-triangle`, `info`, `search`, `settings`, `menu` -- **Media:** `play`, `pause`, `volume-2`, `camera`, `image`, `film`, `music` -- **Communication:** `mail`, `message-circle`, `phone`, `send`, `at-sign` -- **Data:** `bar-chart-3`, `pie-chart`, `activity`, `line-chart`, `table` -- **Security:** `shield-check`, `lock`, `key`, `fingerprint`, `eye`, `eye-off` -- **Arrows:** `arrow-right`, `arrow-up-right`, `chevron-right`, `move`, `maximize-2` - -Browse all at [lucide.dev/icons](https://lucide.dev/icons). - -Lucide SVGs use `stroke="currentColor"`. Style with CSS: - -```html - -``` - -Or for inline SVGs, set `stroke` directly. - -## Photos (Unsplash) - -**Unsplash** — Free high-quality photos. Direct image URLs work without an API key. - -For direct downloads (no API key needed), use the image CDN URL: - -```bash -# Download by photo ID (find IDs by browsing unsplash.com) -curl -L -o assets/photo-hero.jpg "https://images.unsplash.com/photo-{photo-id}?w=1920&q=80" - -# Example with a real photo ID -curl -L -o assets/photo-office.jpg "https://images.unsplash.com/photo-1497366216548-37526070297c?w=1920&q=80" -``` - -For search (needs UNSPLASH_ACCESS_KEY env var): - -```bash -# Search and get URLs -curl -s "https://api.unsplash.com/search/photos?query=fintech+dashboard&per_page=5" \ - -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}" | jq '.results[].urls.regular' -``` - -**If no API key is available**, browse unsplash.com manually for a photo ID, or use a CSS gradient / solid color background. Don't block the video on missing photos — a well-designed composition with no photo beats a bad photo. - -**Attribution:** Unsplash photos are free but appreciate attribution. Add a comment in the HTML: ``. - -## When to Source - -| Situation | Action | -| --------------------------------------------------- | -------------------------------------- | -| Video plan mentions "logo wall" or "customer logos" | Source brand SVGs from Simple Icons | -| Scene needs a specific company's logo | Source from Clearbit by domain | -| Scene references icons (features, benefits, stats) | Source from Lucide by keyword | -| Hero scene needs a photo and none exists | Source from Unsplash or use CSS art | -| Capture already has the asset in `assets/` | Use the local file — don't re-download | -| Asset is decorative and optional | Skip it — ship without and iterate | - -## Naming Convention - -``` -assets/ -├── svgs/ -│ ├── stripe.svg ← brand logos (name = brand slug) -│ ├── icon-chart.svg ← icons (prefix with icon-) -│ └── logo-company.svg ← company logos -├── photo-hero.jpg ← photos (prefix with photo-) -├── logo-stripe.png ← Clearbit logos (prefix with logo-) -└── ... -``` - -## In Compositions - -```html - - - - - - - - - - - -``` - -Always add `crossorigin="anonymous"` to external or downloaded assets. diff --git a/skills/website-to-hyperframes/references/step-1-capture.md b/skills/website-to-hyperframes/references/step-1-capture.md index d1eb9cd078..903ced73dc 100644 --- a/skills/website-to-hyperframes/references/step-1-capture.md +++ b/skills/website-to-hyperframes/references/step-1-capture.md @@ -22,14 +22,11 @@ Read each file below. After reading each one, **write a 1-2 sentence summary** o ### Must read (do not skip) -1. **View the scroll screenshots** (NOT the full-page.png — it's too tall and compressed to read). View these in order: - - `screenshots/scroll-0.png` — the hero section at full 1920x1080 resolution. This is the most important image. Describe: is the background light or dark? What's the dominant visual element? What colors jump out? - - `screenshots/scroll-25.png` — the page at 25% scroll depth - - `screenshots/scroll-50.png` — the page at 50% scroll depth - - `screenshots/scroll-75.png` — the page at 75% scroll depth - - `screenshots/scroll-100.png` — the footer area +1. **View the scroll screenshots** — viewport-sized captures covering the full page height (the number depends on the page length). Start with: + - `screenshots/scroll-000.png` — the hero section at full 1920x1080 resolution. This is the most important image. Describe: is the background light or dark? What's the dominant visual element? What colors jump out? + - Then scan through the rest to see the full page. Each screenshot overlaps the previous by ~30%. - After viewing all five, write 3-4 sentences describing the site's visual mood, layout patterns, color strategy, and overall feel. + After viewing them, write 3-4 sentences describing the site's visual mood, layout patterns, color strategy, and overall feel. 2. **`extracted/tokens.json`** — Note the top 5-7 colors (HEX), all font families, number of sections, and number of headings/CTAs. diff --git a/skills/website-to-hyperframes/references/step-5-vo.md b/skills/website-to-hyperframes/references/step-5-vo.md index c2ca12c81e..be656c6eb9 100644 --- a/skills/website-to-hyperframes/references/step-5-vo.md +++ b/skills/website-to-hyperframes/references/step-5-vo.md @@ -4,9 +4,9 @@ Never use the first voice you find. Audition 2-3 voices with the first sentence of SCRIPT.md: -- **ElevenLabs** (recommended — widest voice selection, most natural output) — `mcp__elevenlabs__search_voices` to browse, `mcp__elevenlabs__text_to_speech` to generate. Does not return timestamps — transcribe separately after. -- **HeyGen TTS** (alternative — returns word timestamps automatically) — `mcp__claude_ai_HeyGen__text_to_speech`. Use `mcp__claude_ai_HeyGen__list_audio_voices` to browse. Look for relaxed, confident voices. -- **Kokoro** (offline last resort — has Python dependency issues on many systems) — `npx hyperframes tts SCRIPT.md --voice af_nova --output narration.wav`. Only try this if ElevenLabs and HeyGen are unavailable. +- **Kokoro** (try first — free, no API key) — `npx hyperframes tts SCRIPT.md --voice af_nova --output narration.wav`. Runs locally on CPU. Requires Python 3.10+ (macOS system Python 3.9 won't work — if it fails with an onnxruntime error, move to the next option). +- **ElevenLabs** (best voice quality, widest selection) — `mcp__elevenlabs__search_voices` to browse, `mcp__elevenlabs__text_to_speech` to generate. Does not return timestamps — transcribe separately after. +- **HeyGen TTS** (returns word timestamps automatically — saves a transcribe step) — `mcp__claude_ai_HeyGen__text_to_speech`. Use when you want timestamps without a separate transcription pass. Pick the voice that sounds most natural and conversational. Listen for pacing — does it breathe between sentences? Does it sound like a person or a robot? diff --git a/skills/website-to-hyperframes/references/video-recipes.md b/skills/website-to-hyperframes/references/video-recipes.md deleted file mode 100644 index b70e085b1c..0000000000 --- a/skills/website-to-hyperframes/references/video-recipes.md +++ /dev/null @@ -1,348 +0,0 @@ -# Video Reference Patterns - -Technical patterns and creative tools for building compositions. These are building blocks — not templates. The video's structure should come from the creative director step (Step 4), driven by the brand and content. - -## Architecture - -**Every scene = a separate sub-composition file** in `compositions/`. Root `index.html` loads each scene on the same track with sequential `data-start` values. - -``` -project/ -├── index.html ← root: loads scenes + transitions + audio -└── compositions/ - ├── scene1.html - ├── scene2.html - ├── scene3.html - └── captions.html ← word-level captions overlay -``` - -## Scene Transitions - -### With Shader Transitions (recommended for 15s+ videos) - -When using shader transitions, scenes DON'T fade to/from black. The shader handles the visual blend between scenes. This means: - -- Each scene starts at **full opacity** (no fade-in from black) -- Each scene ends at **full opacity** (no fade-out to black) -- Scene GSAP timelines only handle entrances for internal elements + mid-scene activity -- No exit animations needed — the shader dissolves this scene into the next - -```javascript -// Scene with shader transitions — NO fade in/out of the background -var dur = 5; -var tl = gsap.timeline({ paused: true }); - -// Background is immediately visible (scene texture needs content to capture) -gsap.set("#scene-bg", { opacity: 1 }); - -// === ELEMENTS ENTER === -tl.fromTo( - "#headline", - { opacity: 0, y: 30 }, - { opacity: 1, y: 0, duration: 0.5, ease: "expo.out" }, - 0.1, -); -tl.fromTo( - "#hero-img", - { opacity: 0, scale: 1.1 }, - { opacity: 1, scale: 1, duration: 0.6, ease: "power3.out" }, - 0.2, -); - -// === MID-SCENE ACTIVITY (keep it alive — required) === -tl.to("#hero-img", { scale: 1.03, duration: dur, ease: "sine.inOut" }, 0); - -// === NO EXIT — shader transition handles the handoff to next scene === -``` - -The root `index.html` orchestrates transitions between scenes: - -1. Show scene 1 (via passthrough shader rendering scene texture) -2. At transition point: `beginTrans(shaderProg, "scene1", "scene2")` -3. GSAP tweens `trans.progress` from 0→1 over transition duration (0.3-0.8s) -4. `endTrans("scene2")` — now showing scene 2 - -Read `references/transitions/shader-setup.md` for the complete WebGL boilerplate and `references/transitions/shader-transitions.md` for the 14 available fragment shaders. - -### Without Shader Transitions (simple fade cuts) - -For very short videos (<10s) or when minimal simplicity is the creative intent, use the fade-to-black pattern: - -```javascript -var dur = 5; -var tl = gsap.timeline({ paused: true }); - -// === ENTRANCE (first 0.3s) === -tl.fromTo("#scene-bg", { opacity: 0 }, { opacity: 1, duration: 0.3, ease: "power2.out" }, 0); -tl.fromTo( - "#headline", - { opacity: 0, y: 30 }, - { opacity: 1, y: 0, duration: 0.5, ease: "expo.out" }, - 0.15, -); - -// === MAIN CONTENT (middle) === -// ... your animations here ... - -// === EXIT (last 0.3s) === -tl.to("#headline", { opacity: 0, duration: 0.2, ease: "power1.in" }, dur - 0.35); -tl.to("#scene-bg", { opacity: 0, duration: 0.3, ease: "power2.in" }, dur - 0.3); -``` - -Root `body { background: #000 }` ensures the gap between scenes is black. - -## Scene Composition: 5-Layer System - -Every scene should be composed in layers. This is the difference between a flat slide and a cinematic frame: - -| Layer | Purpose | Examples | -| ----------------- | ------------------------------------------- | ---------------------------------------------------------------------- | -| **L1 Background** | Sets the visual world | Solid color, gradient, texture, slow-moving particles, CSS noise | -| **L2 Hero** | The dominant visual — fills 50-70% of frame | Large headline, key stat, hero image with Ken Burns, Lottie animation | -| **L3 Supporting** | Context and depth | Secondary text, smaller stats, caption, sub-headline | -| **L4 Info bar** | Label, source, or accent | Bottom-third text, ticker, brand logo placement, category tag | -| **L5 Effects** | Energy and texture | Grain overlay, glitch artifact, scan lines, gradient sweep, light leak | - -**Every B-roll scene: aim for 4+ layers.** Every element in every layer must move. - -```html - - -
- -
- - -
- $1.9T -
- - -
- global transactions in 2024 -
- - -
- -
- - -
-``` - -```javascript -var tl = gsap.timeline({ paused: true }); - -// L1: Background is immediately visible -gsap.set("#bg", { opacity: 1 }); - -// Grain (L5): generate deterministic noise -(function () { - var canvas = document.getElementById("grain"); - var ctx = canvas.getContext("2d"); - canvas.width = 1920; - canvas.height = 1080; - // Seeded PRNG for deterministic noise (same frame = same grain pattern) - var seed = 42; - function rand() { - seed = (seed * 1664525 + 1013904223) & 0xffffffff; - return (seed >>> 0) / 0xffffffff; - } - var img = ctx.createImageData(1920, 1080); - for (var i = 0; i < img.data.length; i += 4) { - var v = Math.floor(rand() * 255); - img.data[i] = img.data[i + 1] = img.data[i + 2] = v; - img.data[i + 3] = 255; - } - ctx.putImageData(img, 0, 0); -})(); - -// L5 sweep: continuous slow pan across the frame -tl.to("#sweep", { left: "110%", duration: 3, ease: "none" }, 0); - -// L2: Hero stat slams in -tl.fromTo( - "#hero-stat", - { opacity: 0, scale: 0.8 }, - { opacity: 1, scale: 1, duration: 0.5, ease: "expo.out" }, - 0.2, -); - -// L3: Label fades + slides up -tl.fromTo( - "#label", - { opacity: 0, y: 12 }, - { opacity: 1, y: 0, duration: 0.4, ease: "power2.out" }, - 0.5, -); - -// L4: Brand mark fades in -tl.fromTo("#brand", { opacity: 0 }, { opacity: 0.7, duration: 0.4 }, 0.7); - -// L2: Mid-scene — stat breathes -tl.to("#hero-stat", { scale: 1.02, duration: 4, ease: "sine.inOut", yoyo: true, repeat: 1 }, 0.7); -``` - -## Caption Safe Zone - -**Bottom 120px is reserved for captions.** No scene content below y=960px. The captions sub-composition sits on track 2 as a full-duration overlay occupying this space. - -## Elements Must DO Something (Not Just Sit There) - -**The #1 difference between a video and a slideshow is continuous motion.** Every visible element should have mid-scene activity — not just an entrance and exit. - -### Mid-Scene Activity Ideas - -Every element MUST have at least one continuous animation during its hold phase: - -| Element type | Mid-scene activity | -| ---------------------- | --------------------------------------------------------------------------------- | -| Image / screenshot | Slow zoom (scale 1→1.03 over scene duration), or slow pan (x drift), or Ken Burns | -| Stat / number | Counter animates from 0 to target with `onUpdate` callback | -| Code block | Lines reveal one by one with stagger, cursor blinks | -| Chart / bars | Bars grow to target heights with elastic ease, values tick up alongside | -| Logo grid | Subtle shimmer sweep across each, or gentle scale pulse (1→1.02→1) | -| Progress / fill | Fills from 0% to target, percentage text updates live | -| Any persistent element | Subtle float (y ±4-6px, sine.inOut, yoyo) or glow pulse | - -### Counter Animation Pattern - -```javascript -var obj = { val: 0 }; -var statEl = document.querySelector("#stat-num"); -tl.to( - obj, - { - val: 135, - duration: 1.5, - ease: "power2.out", - onUpdate: function () { - statEl.textContent = Math.round(obj.val) + "+"; - }, - }, - 0.5, -); -``` - -### Floating/Breathing Pattern - -```javascript -// Subtle float — makes static elements feel alive -// Never use repeat: -1 — infinite loops break the capture engine. -// Calculate repeats from scene duration: -var sceneDur = 5; // match your data-duration -tl.to( - "#card", - { y: "-=6", duration: 2, ease: "sine.inOut", yoyo: true, repeat: Math.ceil(sceneDur / 2) - 1 }, - 0, -); -``` - -### Line-by-Line Reveal Pattern - -```javascript -tl.fromTo( - ".code-line", - { opacity: 0, y: 8 }, - { opacity: 1, y: 0, duration: 0.3, stagger: 0.4, ease: "power2.out" }, - 0.5, -); -// Blinking cursor — never use repeat: -1 -var cursorStart = 2.5; -var cursorCycle = 1; -tl.fromTo( - "#cursor", - { opacity: 1 }, - { - opacity: 0, - duration: 0.5, - repeat: Math.ceil((sceneDur - cursorStart) / cursorCycle) - 1, - yoyo: true, - }, - cursorStart, -); -``` - -## Visual Enhancement Tools - -These separate "AI-generated video" from "actually good video." Use 1-2 per composition. - -### Rough.js — Hand-Drawn Elements - -```html - - -``` - -```javascript -var rc = rough.svg(document.getElementById("rough-canvas")); -var node = rc.circle(960, 400, 200, { - stroke: "#635BFF", - strokeWidth: 3, - roughness: 1.2, - bowing: 2, - fill: "none", -}); -document.getElementById("rough-canvas").appendChild(node); - -var paths = node.querySelectorAll("path"); -paths.forEach(function (p) { - var len = p.getTotalLength(); - p.style.strokeDasharray = len; - p.style.strokeDashoffset = len; -}); -tl.to(paths, { strokeDashoffset: 0, duration: 0.8, ease: "power2.out", stagger: 0.1 }, 2.0); -``` - -Shapes: `rc.circle()`, `rc.rectangle()`, `rc.line()`, `rc.arc()`. Roughness: 0.8 = clean, 1.2 = hand-drawn, 2.0 = sketchy. - -### Marker-Highlight — Text Emphasis - -Five modes: `highlight` (marker sweep), `circle` (drawn around word), `burst` (radiating lines), `scribble` (cross-out), `sketchout` (rough rectangle). See `/hyperframes` skill's marker-highlight reference. - -```javascript -tl.call( - function () { - highlighter.clearMarks(); - highlighter.reanimateMark("stat-highlight"); - }, - null, - 3.0, -); -``` - -### SVG Stroke Animation — Path Drawing - -```javascript -var path = document.querySelector("#logo-path"); -var length = path.getTotalLength(); -path.style.strokeDasharray = length; -path.style.strokeDashoffset = length; -tl.to(path.style, { strokeDashoffset: 0, duration: 1.5, ease: "power2.out" }, 0.5); -``` - -## Using Captured Assets - -- **SVG logos** → embed inline, animate with GSAP (fill, stroke, scale, path drawing) -- **Images** → use as hero visuals, backgrounds (with slow zoom), or layered elements -- **Fonts** (`assets/fonts/`) → load via @font-face, match exact weights from DESIGN.md -- **Lottie** (`assets/lottie/`) → embed via lottie.loadAnimation, seekable -- **Remote URLs** from assets-catalog.json → product screenshots, hero images load directly in compositions