mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-11 14:50:02 +00:00
ukimsanov
969d6a334b
`hyperframes capture <url>` (no -o) used to dump into `./captures/<hostname>/`, which buries the project two levels deep and silently merges re-runs into the previous dir — file-by-file, so leftover screenshots / assets from the prior run stay mixed in and any later `glob` sees both. Switch the default to `./capture/`. When it already exists, auto-suffix to `./capture-2/`, `./capture-3/`, … (up to -99). Each capture is its own clean directory — no crud, no friction, no clobber. The CLI prints a one-line note when the suffix kicks in so the user sees which dir actually got written. Explicit `-o <name>` is unaffected (still overwrite-tolerant).
56 lines
4.0 KiB
Markdown
56 lines
4.0 KiB
Markdown
# Step 0: Capture
|
||
|
||
The capture pipeline downloads the site and extracts structured data for the rest of the workflow to read. Step 0 is a single command plus a sanity check. **All analysis (reading files, viewing contact sheets, deriving brand voice, picking assets) happens in Steps 1–3, not here.**
|
||
|
||
## Run the capture
|
||
|
||
No API keys required for the base capture. However, before running, ask the user:
|
||
|
||
> "For the best results, it is recommended to set a Gemini API key — it gives me AI-powered descriptions of every captured image, which helps me choose the right assets for each scene. It costs about $0.001 per image. You can skip this if you want, but the video quality will be better with it. To set it up: add `GEMINI_API_KEY=your-key` to a `.env` file in the project root. You can get a free key at ai.google.dev."
|
||
|
||
If the user provides the key or already has one set, proceed. If they skip it, proceed anyway — the capture works without it, but `asset-descriptions.md` will have DOM-context descriptions only (position, size, alt text) instead of AI vision descriptions.
|
||
|
||
Create a project directory for your video if it doesn't exist yet, then capture the website into a `capture/` subfolder within it:
|
||
|
||
```bash
|
||
npx hyperframes capture <URL> -o <project-dir>/capture
|
||
```
|
||
|
||
Example: `npx hyperframes capture https://stripe.com -o videos/stripe-launch/capture`
|
||
|
||
Keeping capture artifacts (`screenshots/`, `assets/`, `extracted/`, `AGENTS.md`, `CLAUDE.md`) in a dedicated `capture/` subfolder keeps them isolated from later build files (`SCRIPT.md`, `STORYBOARD.md`, `DESIGN.md`, `compositions/`, `index.html`, `narration.wav`, `transcript.json`, `renders/`, `snapshots/`), which all live at `<project-dir>/` root.
|
||
|
||
For exploratory captures that aren't becoming a video yet, the default `./capture/` (or any `-o <name>` you pick) is fine — the isolation convention only matters when you're building a video on top of the capture.
|
||
|
||
## Confirm it succeeded
|
||
|
||
Wait for the capture to complete. Print one line summarizing what was captured:
|
||
|
||
> "Captured N screenshots, M assets, K SVGs, F fonts. Ready for Step 1."
|
||
|
||
If the command exited non-zero, the counts are all zero, or required directories (`extracted/`, `assets/`, `screenshots/`) are missing, surface the error and stop — don't advance to Step 1 with a broken capture.
|
||
|
||
## What lives in `capture/` (reference table — DO NOT read these here)
|
||
|
||
Each downstream step reads only what it needs. Don't pre-fetch everything in Step 0; that bloats context and produces summaries that get stale by the time they're used.
|
||
|
||
| Path | First read in |
|
||
| ----------------------------------------- | --------------------------------------------- |
|
||
| `capture/extracted/tokens.json` | Step 1 (DESIGN.md — colors / fonts) |
|
||
| `capture/extracted/design-styles.json` | Step 1 (DESIGN.md — typography / components) |
|
||
| `capture/extracted/fonts-manifest.json` | Step 1 (font identification) |
|
||
| `capture/extracted/asset-descriptions.md` | Step 2 (brief grounding) and Step 3 (assets) |
|
||
| `capture/extracted/visible-text.txt` | Step 2 (brief) and Step 3 (script) |
|
||
| `capture/assets/contact-sheet-*.jpg` | Step 3 (asset picking) |
|
||
| `capture/assets/svgs/contact-sheet-*.jpg` | Step 3 (SVG / logo picking) |
|
||
| `capture/screenshots/contact-sheet-*.jpg` | Step 3 (visual mood reference) |
|
||
| `capture/extracted/animations.json` | Step 3 / Step 5 (only if site has animations) |
|
||
| `capture/extracted/lottie-manifest.json` | Step 3 (only if site uses Lottie) |
|
||
| `capture/extracted/video-manifest.json` | Step 3 (only if site embeds video) |
|
||
| `capture/extracted/shaders.json` | Step 3 / Step 5 (only if site has WebGL) |
|
||
| `capture/assets/<individual files>` | Step 5 (only when placing a specific asset) |
|
||
|
||
## Gate
|
||
|
||
Capture exits 0. Asset / screenshot / font counts non-zero. Proceed to Step 1.
|