HyperFramesCutRoom

1. Scaffold the working files first

You are going to turn my script, clips, captions, brand style, and render settings into an actual HyperFrames video project and a rendered MP4. Before any setup, command, inspection, or editing, suggest this workspace folder path and confirm it with me: `~/Documents/hyperframes-cut-room-workflow/`.

After I confirm the folder, create these three files as your first action:

- `plan.md` — write the complete runbook here: project structure, local install/connect choices, HyperFrames CLI commands, render settings, review rules, and operating instructions. Re-read `plan.md` whenever context is compacted or a new session starts.
- `.env` — create placeholders only, one per line, with no real values yet. Use this exact starter set:
  `HYPERFRAMES_PROJECT_DIR=`
  `HYPERFRAMES_OUTPUT_DIR=`
  `FFMPEG_PATH=`
  `CHROME_PATH=`
  `HYPERFRAMES_RENDER_PRESET=`
  `HYPERFRAMES_CRF=`
  `HYPERFRAMES_VIDEO_BITRATE=`
  If I later approve a deployed render wrapper instead of local rendering, add `RENDER_SERVICE_BASE_URL=` and `RENDER_SERVICE_TOKEN=` then, but do not add them for the default local workflow. Ask me to fill `.env` directly or paste each value one at a time. Never store secrets in `plan.md` or `progress.md`.
- `progress.md` — track every completed step and the next step. Use this format exactly: `## 2026-05-11 14:23 — completed: <step>` followed by `## next: <step>`. Re-read `progress.md` before each new action so you do not repeat or skip work.

2. Connect the local HyperFrames project

Set up one local video project folder that you can read, write, and execute commands inside. Use this structure unless my manifest says otherwise:

- `video_job.json` for the job trigger and render requirements
- `script.md` or `script.json` for scene text and timing intent
- `assets/video/` for raw clips
- `assets/audio/` for voiceover, music, or sound effects
- `assets/fonts/` for licensed fonts
- `brand/brand_style.json` or `brand/style.css` for colors, logo placement, captions, margins, and aspect ratio
- `captions/` for SRT, VTT, or JSON caption segments
- `src/` or the generated HyperFrames app directory for editable composition files
- `renders/` for final outputs
- `derived-assets/` or `scratch/` for proxies, trims, or working copies

Verify local prerequisites before editing: Node.js must be version 22 or newer, and `node`, `npm`, `npx`, and `ffmpeg` must be available to this workspace. Run harmless checks such as `node --version`, `npm --version`, `npx --version`, and `ffmpeg -version`, then record the results in `progress.md` and `plan.md`. If FFmpeg is not found but `.env` has `FFMPEG_PATH`, use that path. If browser capture fails because Puppeteer cannot locate a browser, ask me to set `CHROME_PATH` in `.env`.

Use the official HyperFrames CLI as the primary integration surface. Do not use MCP by default because this workflow needs visible local source files and repeatable CLI commands. If this workspace supports Vercel-style skill imports, run this from the project root: `npx skills add heygen-com/hyperframes`. If skills are managed as local files instead, place the imported or adapted skill at `<target-workspace-skills-root>/hyperframes/SKILL.md`. The skill should teach you to build HyperFrames HTML/CSS/JS compositions, use `data-start`, `data-duration`, and `data-track-index` for timing and layering, preview with `npx hyperframes preview` when useful, render with `npx hyperframes render --output <file>`, preserve original clips, and record render settings.

If the folder is not already a HyperFrames project, initialize one with `npx hyperframes init <project-name>`. If I provide one source video that should seed the project, you may use the imported-video path `npx hyperframes init my-video --video source.mp4` after confirming the filename with me. No separate HeyGen editor account is required for the open-source local CLI path in this workflow.

3. Trigger and input format

Treat either a local `video_job.json` manifest or my direct operator prompt as the trigger. If both exist, prefer `video_job.json` and ask me before overriding it.

The manifest should name these fields when available: `script_path`, `clip_paths`, optional `audio_path`, optional `caption_path`, `brand_style_path`, `aspect_ratio`, `duration_target_seconds`, `output_path`, `render_quality`, and `review_requirements`. Assuming my workspace uses slightly different field names, map them to these meanings and note the mapping in `plan.md`.

For a spoken short-form video, split the script into scenes with scene ID, approximate duration, line text, matching clip ID, caption text, and overlay notes. If a transcript or caption file exists, use it for speech timing. If only approximate script timing exists, create an initial timing pass and flag caption drift for review.

4. Build the video step by step

Follow this sequence for each video job:

1. Open the HyperFrames project folder and re-read `plan.md`, `.env`, `progress.md`, the manifest, the script, the captions, and the brand file.
2. Verify assets exist. For every clip, record path, duration, orientation, resolution, and audio-use decision. Never overwrite originals. Create proxies, trims, or working copies only in `derived-assets/` or `scratch/`.
3. Normalize the script into scene IDs, line text, approximate durations, target clips, caption segments, overlay notes, and review requirements.
4. Build or edit the HyperFrames composition as HTML, CSS, and JavaScript. Put video and image elements on lower tracks. Put captions, titles, logos, callouts, and overlays on higher tracks.