User context: not every team has GEMINI_API_KEY set. Without it, the asset-descriptions.md fallback previously degraded to near-useless lines like `svgs/svg-54ea56cd.svg — icon: 54ea56cd` — just the content-hash slug, no signal for finding the real logo. This commit makes the no-Gemini path materially more useful by surfacing the new structural LOGO signals (committed in02f95f95) into the asset-descriptions output. contentExtractor.ts changes: 1. Downloaded-image branch (lines 350-393): compute `isLikelyLogo` from catalog signals (inBanner / inHomeLink / matchesTitleBrand + the existing alt/heading/section substring patterns). When true, prepend a literal `LOGO` token to the description line. Applied to BOTH the Gemini-captioned path (so the LOGO tag rides alongside the rich Vision caption) and the catalog-fallback path. Single grep target for agents: `grep "LOGO" capture/extracted/asset-descriptions.md`. 2. Inline-SVG branch: bumped the case-sensitive prefix to `LOGO:` to match the new convention. Filename-based check now leads with `file.startsWith("logo-")` because the broadened isLogo detection in02f95f95makes that prefix the most reliable signal — the logo-<hash>.svg naming is owned by the capture pipeline and is trustworthy by construction. index.ts (asset-descriptions.md writer) changes: 3. The file header is now branched by Gemini-key presence: - With key: brief instruction + "search for the brand name here BEFORE composing a logo" pointer. - Without key: explicit ⚠️ banner naming the degraded mode, listing what the catalog-fallback signals catch, AND a fallback- of-the-fallback instruction: "open the LOGO-tagged SVGs in a previewer or sharp-render them to PNG before referencing — the alternative (composing a fake logo) ships off-brand in the final video." This is the same brand-fidelity rule the doc landmine (commite6aa7fed) lays down, repeated here so it's discoverable from inside the no-Gemini-mode file itself. 4. progress() message also reports the catalog-fallback mode when no Gemini key, so users running capture interactively see a status hint. Net: teams without a Gemini key now get: - LOGO-tagged lines they can grep for (catches the heygen wordmark and the huly favicon via the structural signals). - A header that names the degraded mode + tells agents to fall back to opening / rasterizing SVGs when descriptions are too weak. - Stable contract: the LOGO token works identically with or without Gemini, so the skill's discovery rule (e6aa7fed) is honored in both modes. Final piece of the bundle: capture/video-manifest already lists every <video> URL but doesn't download. Followup commit adds an on-demand download path so the heygen "Orb" hero (or any other captured video) is one CLI invocation away rather than a manual curl.
hyperframes
CLI for creating, previewing, and rendering HTML video compositions.
Install
npm install -g hyperframes
Or use directly with npx:
npx hyperframes <command>
Requirements: Node.js >= 22, FFmpeg
Commands
init
Scaffold a new Hyperframes project from a template:
npx hyperframes init my-video
cd my-video
preview
Start the live preview studio in your browser:
npx hyperframes preview
# Studio running at http://localhost:3002
npx hyperframes preview --port 4567
render
Render a composition to MP4:
npx hyperframes render ./my-composition.html -o output.mp4
lint
Validate your Hyperframes HTML:
npx hyperframes lint ./my-composition
npx hyperframes lint ./my-composition --json # JSON output for CI/tooling
npx hyperframes lint ./my-composition --verbose # Include info-level findings
By default only errors and warnings are shown. Use --verbose to also display informational findings (e.g., external script dependency notices). Use --json for machine-readable output with errorCount, warningCount, infoCount, and a findings array.
compositions
List compositions found in the current project:
npx hyperframes compositions
benchmark
Run rendering benchmarks:
npx hyperframes benchmark ./my-composition.html
doctor
Check your environment for required dependencies (Chrome, FFmpeg, Node.js):
npx hyperframes doctor
browser
Manage the bundled Chrome/Chromium installation:
npx hyperframes browser
info
Print version and environment info:
npx hyperframes info
docs
Open the documentation in your browser:
npx hyperframes docs
upgrade
Check for updates and show upgrade instructions:
npx hyperframes upgrade
npx hyperframes upgrade --check --json # machine-readable for agents
Documentation
Full documentation: hyperframes.heygen.com/packages/cli
Related packages
@hyperframes/core— types, parsers, frame adapters@hyperframes/engine— rendering engine@hyperframes/producer— render pipeline@hyperframes/studio— composition editor UI