Skip to content
Back to search

hve-video-director

AI-powered video production pipeline for Claude Code, Github Copilot, Codex, Cursor, OpenCode and PI — 6 automated phases from design thinking to final render

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/nebrass/hve-video-director with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/nebrass/hve-video-director'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nebrass--hve-video-director/badge.svg)](/listings/nebrass--hve-video-director)

HTML

<a href="/listings/nebrass--hve-video-director"><img src="/api/listings/nebrass--hve-video-director/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The recommended install is the **[skills CLI](https://github.com/vercel-labs/skills)**. For a portable project install shared by multiple agents, use an `.agents/skills/` destination; global skill homes differ by agent.

Recommended: Skills CLI

# Project install — run from your project; writes to the agent's project skills home
npx skills add nebrass/hve-video-director

# Global install (Claude Code is the default agent)
npx skills add nebrass/hve-video-director --global

# Global install for GitHub Copilot CLI (~/.copilot/skills/)
npx skills add nebrass/hve-video-director --agent github-copilot --global

In Copilot CLI, run `/skills` to confirm the skill is loaded.

Fallback: manual git clone

If you can't run the CLI, clone the repo into your agent's skills home directly:

git clone https://github.com/nebrass/hve-video-director.git ~/.claude/skills/hve-video-director
# GitHub Copilot CLI: clone into ~/.copilot/skills/hve-video-director instead

OpenCode, Pi, Codex & Cursor (native discovery)

No plugin or manifest needed — these agents discover skills by directory convention and read the same Agent Skills `SKILL.md` format. The skills-CLI install above writes a `<name>/SKILL.md` subdir into a home each one scans, so they pick up hve-video-director natively:

npx skills add nebrass/hve-video-director            # project (.agents/skills/)
npx skills add nebrass/hve-video-director --global   # global

- **OpenCode** — `.claude/skills/`, `~/.claude/skills/`, `.agents/skills/`, `~/.agents/skills/`, `.opencode/skills/`, `~/.config/opencode/skills/`. Docs: <https://opencode.ai/docs/skills/>. - **Pi** — `~/.pi/agent/skills/`, `~/.agents/skills/` (global), `.pi/skills/`, `.agents/skills/` (project, after the project is *trusted*). Docs: <https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md>. - **Codex** — `$CWD/.agents/skills/`, `$REPO_ROOT/.agents/skills/`, `$HOME/.agents/skills/`, `/etc/codex/skills/`. Docs: <https://learn.chatgpt.com/docs/build-skills>. - **Cursor** — `.agents/skills/`, `.cursor/skills/`, `~/.agents/skills/`, `~/.cursor/skills/`, plus `.claude/skills/` and `.codex/skills/`. Docs: <https://cursor.com/docs/skills>.

Then ask for a video (for example, "use hve-video-director to make a showcase video of this app"). Skill loading follows each agent's documented convention. Loading is not proof that Chrome MCP, question prompts, companion skills, or the complete render pipeline work on that host.

Compatibility status

| Agent | Discovery / invocation | Pipeline status | |---|---|---| | Claude Code | Automatic or `/hve-video-director` | Phase 0→5 verified | | GitHub Copilot CLI | Automatic or `/hve-video-director`; inspect with `/skills info hve-video-director` | Phase 0→5 verified | | OpenCode | Automatic through the native skill loader | Discovery-compatible; Phase 0→5 unverified | | Pi | Automatic or `/skill:hve-video-director` | Discovery-compatible; requires suitable MCP extensions for web capture; Phase 0→5 unverified | | Codex | Automatic, `/skills`, or `$hve-video-director` | Discovery-compatible; Phase 0→5 unverified | | Cursor | Automatic or `/hve-video-director` | Discovery-compatible; Phase 0→5 unverified |

The workflows resolve question and Chrome DevTools capabilities at runtime; they do not assume Claude Code's literal MCP identifiers are available elsewhere.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 22 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "hve-video-director",
  3. "description": "AI-powered video production pipeline skill for Claude Code and GitHub Copilot CLI.",
  4. "owner": {
  5. "name": "Nebrass Lamouchi",
  6. "email": "lnibrass@gmail.com"
  7. },
  8. "plugins": [
  9. {
  10. "name": "hve-video-director",
  11. "source": "./",
  12. "description": "End-to-end video production pipeline with design thinking. A 6-phase orchestrator (Discovery → Storytelling → Capture → Design → Production → Audio & Render) that turns your app into a polished promo, showcase, or tutorial video, rendered with HyperFrames (HTML + GSAP). Runs on Claude Code and GitHub Copilot CLI.",
  13. "version": "0.4.2",
  14. "homepage": "https://github.com/nebrass/hve-video-director",
  15. "license": "MIT",
  16. "author": {
  17. "name": "Nebrass Lamouchi",
  18. "email": "lnibrass@gmail.com"
  19. }
  20. }
  21. ]
  22. }
README.md · README · 827 lines · 3 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # hve-video-director
  2. **AI-powered video production pipeline verified on Claude Code and GitHub Copilot CLI.**
  3. OpenCode, Pi, Codex, and Cursor can discover the same Agent Skill; their full Phase 0→5
  4. pipeline remains unverified.
  5. ```
  6. /hve-video-director Demonstrate feature XYZ in a typical end-to-end scenario, showing every option and the final results.
  7. ```
  8. Start in the source project and describe the video you want. The request drives the subject,
  9. scenario, depth, and result; the skill confirms a separate output location before creating it.
  10. Bare invocation still works and asks what video to make.
  11. > **Renamed in v0.1.0** — this skill was previously `hve-spielberg`. `npx skills update` does
  12. > **not** complete the rename: it installs the new skill *alongside* the old one and leaves the
  13. > stale `hve-spielberg` behind. Remove the old install explicitly. See
  14. > [`MIGRATION.md`](MIGRATION.md).
  15. ## Reference build
  16. **[`example/`](example/) is the committed reference build** — regenerated in v0.2.0 against the
  17. HyperFrames-first pipeline. It is a **60-second promo the skill made about itself**, which makes it
  18. the honest test: with `product_surface: none` there was no product UI to lean on, so the reasoning
  19. layer had to decide how to show an *idea*.
  20. | | |
  21. |---|---|
  22. | Frames | 8, in the official storyboard shape, each carrying its director keys |
  23. | Identity | `design-system: stripe`, dark theme, 1920×1080 |
  24. | Seams | 4 z-axis rows in [`ledger.json`](example/ledger.json), stamped and numerically verified |
  25. | Hero budget | `visual_ceiling: derived` imposed no ceiling, and derivation still spent Three.js on exactly **one** frame of eight |
  26. The source artifacts are committed (`context.md`, `storyboard.md`, `DESIGN.md`, `scenes/*.html`,
  27. `ledger.json`, `index.html`). Media is **not** committed — it is regenerable from what is here, and
  28. a rendered MP4 is attached to a Release when one is produced. No render of *this* build is
  29. published yet; the films below are separate projects.
  30. It is a **record, not a fixture**, and it is only worth anything while every byte is what the
  31. pipeline actually emitted. Producing one is a **human-in-the-loop run**: every phase ends at a
  32. user-approval checkpoint that no agent may grant on your behalf (ADR-001), and it needs real
  33. text-to-speech, a licensed music track, and a headless-Chromium render. That is a production run
  34. someone sits through, not a build step. `example/.hve/brief-state.json` is the consent record that
  35. makes the claim checkable — `validate_brief.py --project-dir example status` reports it complete,
  36. confirmed and unstale.
  37. ### Watch it work
  38. [![hve-video-director — this promo was made by the tool it describes](https://img.youtube.com/vi/KhV-peeXqsE/maxresdefault.jpg)](https://www.youtube.com/watch?v=KhV-peeXqsE)
  39. ▶ **[Watch the 90-second v0.2.0 promo](https://www.youtube.com/watch?v=KhV-peeXqsE)** — or
  40. [download the MP4](https://github.com/nebrass/hve-video-director/releases/download/v0.2.0/hve-video-director-promo-v0.2.0.mp4)
  41. (1920×1080, H.264 + AAC, 6.2 MB) from the
  42. [v0.2.0 release](https://github.com/nebrass/hve-video-director/releases/tag/v0.2.0).
  43. Produced end-to-end by hve-video-director v0.2.0 itself, with a human granting all six phase
  44. approvals. A **separate project from `example/`**, not a render of it: 8 scenes on the vendored
  45. **Vercel** preset in light theme, velocity-matched cuts verified by the seam gate, ElevenLabs
  46. narration over a CC BY 4.0 bed, and reviewed captions bound to the final mix. Its terminal shot is
  47. a real `asciinema` recording of this repository's own test suite — 233 tests, exit 0 — not a
  48. mock-up.
  49. ### Earlier renders
  50. One hosted film from the v0.1.0 era. **It is not `example/`** — a different project, kept because
  51. it is real output, and it predates the HyperFrames rebase.
  52. ▶ **[Download the 53-second v0.1.0 reference render](https://github.com/nebrass/hve-video-director/releases/download/v0.1.0/hve-video-director-example-v0.1.0.mp4)**
  53. (1920×1080, H.264 + AAC, 18 MB) — a promo for [blog.nebrass.fr](https://blog.nebrass.fr) using four
  54. real Chrome DevTools captures as the product spine, built on the vendored **Vercel** design system
  55. ([`design-systems/vercel/DESIGN.md`](design-systems/vercel/DESIGN.md)) and attached to the
  56. [v0.1.0 release](https://github.com/nebrass/hve-video-director/releases/tag/v0.1.0).
  57. ## What It Does
  58. hve-video-director is an Agent Skill that orchestrates end-to-end video production:
  59. 1. **Understands your product** through design thinking (empathize, define, ideate)
  60. 2. **Builds a narrative** with scene storyboarding and emotional arc
  61. 3. **Captures your app** automatically via Chrome DevTools, including an explicitly selected already-authenticated Chrome tab
  62. 4. **Builds one HTML scene per storyboard frame**, matching your brand DNA — pick from [10 curated design systems](design-systems/) (Stripe, Linear, Apple, Notion, Vercel, Airbnb, GitHub, Cal, Arc, Bento), 8 HyperFrames named styles, or derive from screenshots. Shipped HyperFrames registry blocks are installed before anything is hand-authored, and each scene is built from that one frame's brief rather than from the whole film
  63. 5. **Produces the video** in HyperFrames (HTML + GSAP, headless-Chromium rendered)
  64. 6. **Adds voiceover, music, SFX, and reviewed closed captions** using the `media-use` mechanisms — delegated ElevenLabs or explicitly chosen local Kokoro narration, a music bed whose exact track you confirm before any mix, caption timing from source-language transcription over the assembled voiceover, and language/audio-bound SRT/VTT delivery
  65. ### Three Modes
  66. | Mode | Structure | Best For |
  67. |------|-----------|----------|
  68. | **Promo** | Hook → Pain → Solution → Features → CTA | Marketing, launches, ads |
  69. | **Showcase** | Intro → Walkthrough → Highlights → Closer | Portfolio, demos, case studies |
  70. | **Tutorial** | Cold Open → Step-by-Step Chapters → Recap | Walkthroughs, how-tos, onboarding |
  71. ## Pipeline
  72. ```
  73. Phase 0: DISCOVERY Phase 1: STORYTELLING Phase 2: CAPTURE
  74. ├ Design thinking ├ Narrative structure ├ Web / terminal / supplied
  75. ├ Codebase/feature scan ├ Scene storyboard ├ Auto-navigate app
  76. ├ Product context Q&A ├ Emotional arc ├ Screenshots + clips
  77. └ Goal/audience analysis └ Script outline └ Bound capture artifacts
  78. Phase 3: DESIGN Phase 4: PRODUCTION Phase 5: AUDIO & RENDER
  79. ├ DESIGN.md (brand+motion) ├ HyperFrames root index ├ media-use audio engine
  80. ├ Registry blocks first ├ Sub-composition wiring ├ Reviewed captions
  81. ├ One brief per frame ├ GSAP transitions ├ Confirmed track + mix
  82. └ Scene HTML built └ lint + check gates └ npx hyperframes render
  83. ```
  84. Each phase has a user-approval checkpoint before proceeding to the next. Preview and the
  85. mechanical gates run in Phase 4, once the scenes are assembled into one composition.
  86. ## Prerequisites
  87. > **Quick check:** run `./scripts/check_requirements.sh`. The default report, `--json`, and
  88. > `--plan` never install or download anything. `--plan` prints exact actions; use
  89. > `--fix=<id,id>` only after choosing safe user-scoped fixes. Bare `--fix` retains the
  90. > all-safe behavior. System/sudo commands and environment-variable exports are always printed,
  91. > never run.
  92. | Checker flag | Purpose |
  93. |---|---|
  94. | *(none)* | Human readiness report with required exit status |
  95. | `--json` | JSON-only report with stable check IDs, tiers, states, affected phases, and fixes |
  96. | `--plan` | Side-effect-free human plan for every non-ready check |
  97. | `--fix=<id,id>` | Run only selected safe fixes (`chrome-shell`, `hyperframes-skill`, `whisper`) |
  98. | `--fix` | Run all currently missing safe fixes; never system/sudo/environment actions |
  99. **No local checkout?** The doctor is self-contained — run it straight from GitHub:
  100. Stdin and standalone copies use an offline Node capability probe when no language
  101. helper is available. An installed copy under a skill root containing `SKILL.md`
  102. still requires its sibling `scripts/language_tools.mjs`; a missing helper blocks
  103. readiness and recommends reinstalling the skill, not Node.
  104. ```bash
  105. # report only
  106. curl -fsSL https://raw.githubusercontent.com/nebrass/hve-video-director/main/scripts/check_requirements.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 137 on GitHub
  107. # inspect the exact plan without making changes
  108. curl -fsSL https://raw.githubusercontent.com/nebrass/hve-video-director/main/scripts/check_requirements.sh | bash -s -- --plan
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 140 on GitHub
  109. # apply only explicitly selected safe fixes
  110. curl -fsSL https://raw.githubusercontent.com/nebrass/hve-video-director/main/scripts/check_requirements.sh | bash -s -- --fix=chrome-shell,hyperframes-skill
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 143 on GitHub
  111. ```
  112. Prefer to read the script before running it (recommended for any `curl … | bash`)? Download, inspect, then execute:
  113. ```bash
  114. curl -fsSL https://raw.githubusercontent.com/nebrass/hve-video-director/main/scripts/check_requirements.sh -o check_requirements.sh
  115. less check_requirements.sh && bash check_requirements.sh --plan
  116. ```
  117. | Tool | Required | Installation |
  118. |------|----------|-------------|
  119. | Node.js 22.12+ with full ICU | Yes | [nodejs.org](https://nodejs.org) — the existing platform dependency also runs `scripts/language_tools.mjs` for canonical locales and Unicode word/grapheme segmentation; no extra package |
  120. | Python 3.10+ | Yes | [python.org](https://python.org) |
  121. | ffmpeg | Yes | `brew install ffmpeg` / `apt install ffmpeg` |
  122. | HyperFrames CLI | Yes | `npm install --global hyperframes` (the checker never fetches it during report modes) |
  123. | HyperFrames companion skills | Phases 3–5 | `npx skills add heygen-com/hyperframes` — installs the `hyperframes` router *and* the domain family it dispatches to |
  124. | `chrome-headless-shell` | Yes | Used by `npx hyperframes render` for frame capture. System Chrome causes 120s render hangs. Install once: `npx puppeteer browsers install chrome-headless-shell` (one-time, ~170MB, cached). Verify with `npx hyperframes doctor`. |
  125. | Chrome DevTools MCP | For web capture | Required only when the storyboard requests web screenshots/screencasts — including replaying a user-recorded browse flow. Configure it in the active agent; capability names are resolved per runtime. For an already-authenticated tab, use Chrome 144+ remote debugging plus MCP `--autoConnect` (preferred), or the documented dedicated-profile `--browser-url` fallback. |
  126. | HeyGen credential | Recommended | `heygen auth login --oauth` (or `HEYGEN_API_KEY`) — lets the `media-use` engine retrieve catalog sound effects and a catalog music bed instead of generating them or falling back to its bundled library; either route is recorded in the brief as `music_strategy: delegated` with a provenance URI (see [Music Strategy](#music-strategy)). It does **not** change the voice: the brief's `voice` vocabulary is `elevenlabs:…` or `kokoro:…` only (enforced by [`scripts/validate_brief.py`](scripts/validate_brief.py)), so the engine's HeyGen voice route is not selectable through this skill's vocabulary. The checker reports it as `heygen-credential` and degrades gracefully without it; Phase 5 never prompts for sign-in and never substitutes a confirmed provider. |
  127. | `ELEVENLABS_API_KEY` | For an ElevenLabs voice | [elevenlabs.io](https://elevenlabs.io) — required when the confirmed voice uses ElevenLabs. It is consumed by the `media-use` engine's ElevenLabs route, the only path that reads it. Choose Kokoro explicitly for no-key local TTS; providers are never substituted automatically. |
  128. | Whisper | Recommended | `pip install openai-whisper` — voiceover timing verification when `npx hyperframes transcribe` is unavailable. The engine's per-line word timings never substitute for it: they are relative to each line's own audio, while captions need composition-absolute times over the assembled voiceover. |
  129. | `espeak-ng` | When the selected local backend requires it | `brew install espeak-ng` / `apt install espeak-ng` — check the selected language's requirements through TTS_LOCAL; one installed phonemizer is not proof that every language/backend is ready |
  130. | `--experimentalScreencast` (chrome-devtools MCP) | No | Enables `screencast` web-clip capture; without it, web scenes fall back to screenshots, and recorded-flow clip frames degrade to stills at each range's end. |
  131. | `asciinema` + `agg` | No | Optional true terminal-clip recording for CLI scenes; without them, CLI scenes use the authored-terminal path. Install: `brew install asciinema agg` (macOS) · `apt install asciinema && cargo install --git https://github.com/asciinema/agg` (Debian/Ubuntu). See [`patterns/cli-terminal-capture.md`](patterns/cli-terminal-capture.md) for the full recording workflow. |
  132. | `wf-recorder` | Wayland native capture only | Feature-detected by `scripts/capture_screen.py`. Without it, use the desktop recorder and normalize the result with `scripts/stitch_clip.py`; generic FFmpeg PipeWire capture is not assumed. |
  133. ### Already-authenticated browser capture
  134. Phase 2 can capture an SSO/MFA app from an already-open Chrome tab without navigating away. The
  135. preferred setup is Chrome 144+ with remote debugging enabled at
  136. `chrome://inspect/#remote-debugging` and `--autoConnect` added to the Chrome DevTools MCP server
  137. arguments. Phase 2 then lists the connected profile's tabs, asks the user to select the exact tab,
  138. and leaves its URL/history unchanged — with one consented exception: replaying a browse flow you
  139. recorded yourself (next section) performs exactly your recorded steps and ends at the flow's
  140. disclosed final state.
  141. The MCP can inspect and control every open window in the connected profile. Close unrelated
  142. sensitive tabs first, never expose a remote-debugging port to the network, and use a dedicated
  143. profile when appropriate. See
  144. [`patterns/authenticated-browser-capture.md`](patterns/authenticated-browser-capture.md) for the
  145. manual `--browser-url` fallback, privacy contract, viewport restoration, and failure handling.
  146. ### Record-and-replay browse capture
  147. For navigation too complex to describe — a Power BI report's drill path, a deep SaaS wizard —
  148. record the flow yourself and let Phase 2 replay it with human pacing instead of guessing. Chrome
  149. and Edge ship the recorder natively (DevTools → **Recorder** → record → Export → **JSON**); the
  150. companion [HVE Flow Recorder](https://github.com/nebrass/hve-flow-recorder) extension records
  151. the same format on Chrome, Edge, **and Firefox** with real per-step timing, typing rhythm,
  152. drag/wheel/upload capture, and capture-time secret redaction (consent-first: it holds no site
  153. access at install — the browser asks once, at the first Start, and capture code exists on pages
  154. only during a recording session). Drop
  155. the export under the project's `recordings/` and bind storyboard frames to it (`recording:` plus
  156. an optional `recording_steps: A-B` range — several frames can take different ranges of one
  157. recording). Phase 2 shows you a sanitized step brief and asks for one whole-flow approval, then
  158. replays the steps once — pointer travel, settle, read dwells, chunked typing, eased scrolls —
  159. while filming a single master take, and cuts each frame's clip from it. The replayed clicks are
  160. your own recorded steps, never improvised: a selector that no longer resolves aborts the take
  161. rather than guessing.
  162. ```bash
  163. # Validate a recording, see the step brief, origins, and any secret warnings
  164. python3 scripts/replay_flow.py plan --recording recordings/drill.json --storyboard storyboard.md
  165. # Verify a cut clip is complete and fresh (resume predicate)
  166. python3 scripts/replay_flow.py check --recording recordings/drill.json \
  167. --steps 3-6 -o public/clips/scene-01-drill.mp4
  168. ```
  169. Replay needs the Chrome DevTools MCP; filming additionally needs its experimental screencast
  170. (without it, replay still runs and clip frames degrade to stills at each range's end). Cuts
  171. publish atomically with fingerprinted `<clip>.replay.json` sidecars — re-recording the flow
  172. stales every clip cut from it, and an interrupted take reads as incomplete, never as done. Mind
  173. that **recorder exports are plaintext**: record *after* logging in (pair with the
  174. authenticated-tab setup above) so no credential is ever in the file, and never commit a recording
  175. that holds one. Full contract:
  176. [`patterns/recorded-flow-capture.md`](patterns/recorded-flow-capture.md).
  177. ### Native screen capture and clip normalization
  178. The pure-stdlib helpers record no audio and publish the Phase-2 clip contract: fixed requested
  179. duration, CFR30 H.264 High, `yuv420p`, even dimensions, and `+faststart`.
  180. ```bash
  181. # Fixed-duration native desktop capture (macOS, Windows, X11, or detected Wayland)
  182. python3 scripts/capture_screen.py --duration 6 \
  183. -o public/clips/scene-02-dashboard.mp4
  184. # Native region capture; source dimensions may be odd
  185. python3 scripts/capture_screen.py --duration 4 --region 100,80,1281,721 \
  186. -o public/clips/scene-03-flow.mp4
  187. # Verify clip + completion sidecar against the storyboard duration/region
  188. python3 scripts/capture_screen.py --check --duration 4 --region 100,80,1281,721 \
  189. -o public/clips/scene-03-flow.mp4
  190. # Normalize, trim, or stitch existing recordings
  191. python3 scripts/stitch_clip.py raw.mov::1.5::6 second.mkv \
  192. --width 1920 --height 1080 -o public/clips/scene-04-result.mp4
  193. ```
  194. `capture_screen.py` uses built-in `screencapture` on macOS, ffmpeg `gdigrab` on Windows,
  195. ffmpeg `x11grab` on X11, and `wf-recorder` only when detected on Wayland. WSL exits with a
  196. Windows-host recording handoff. Before each attempt it writes `<clip>.capture.pending`; success
  197. atomically publishes `<clip>.capture.json` with requested parameters, validated media properties,
  198. and a SHA-256 fingerprint before clearing pending. Existing clip/metadata are preserved on every
  199. failure, while retained pending prevents a failed retake from counting as complete. Raw capture is
  200. kept on failure (or with `--keep-raw`) and `stitch_clip.py` remains the canonical normalizer.
  201. ### Reviewed closed-caption delivery
  202. After the final soundtrack is mixed, Phase 5 creates ASR drafts plus a review manifest. The user
  203. corrects speech, reviews speaker identity and meaningful music/SFX, then explicitly approves the
  204. cue list. Finalization writes same-basename sidecars beside the video and fingerprints the audio,
  205. manifest, and outputs:
  206. ```bash
  207. # NARRATION_LANGUAGE comes from the checked language profile, not the on-screen text locale.
  208. python3 scripts/caption_gen.py draft --audio voiceover-with-music.mp3 --language "$NARRATION_LANGUAGE"
  209. # Review captions-review.json; set speech_review/speaker_review/sound_review.
  210. python3 scripts/caption_gen.py approve --expected-language "$NARRATION_LANGUAGE" # after user approval
  211. python3 scripts/caption_gen.py finalize --expected-language "$NARRATION_LANGUAGE"
  212. python3 scripts/caption_gen.py validate --expected-language "$NARRATION_LANGUAGE"
  213. ```
  214. Final delivery is `out/final.mp4` + `out/final.srt` + `out/final.vtt`. Any soundtrack, manifest,
  215. state, or sidecar edit makes validation fail and routes back to Phase 5. Editing a cue after
  216. approval also invalidates its content-bound approval fingerprint.
  217. The helper canonicalizes new draft locales and compares expected locales without rewriting
  218. reviewed cues or their language label. A mismatch fails before approval or delivery writes.
  219. ICU segmentation preserves combining marks/emoji clusters and avoids invented spaces in CJK/Thai
  220. captions. Width and rate ceilings count graphemes, not code points; they do **not** certify
  221. readability for every language. Human language, speaker/sound, timing and line-break review remains
  222. mandatory. The optional expected-language flag preserves legacy standalone inspection; new
  223. workflow calls always supply it.
  224. ### Required Skills
  225. hve-video-director depends on the **HyperFrames companion agent skills** plus the **`hyperframes` npm package** (these are separate — the skills provide authoring prompts; the npm package provides the `hyperframes` CLI). A single `npx skills add heygen-com/hyperframes` offers the whole family — select all of them, or pass `--all` (see [Installation](#installation)). The command auto-detects your agent and resolves the correct skills home for you:
  226. | Dependency | Type | Purpose | Install |
  227. |-----------|------|---------|---------|
  228. | `hyperframes` skill | Agent skill | The intent **router**: it dispatches to whichever domain skill owns the topic. Load it first; it is no longer a monolith that carries the authoring rules itself. | `npx skills add heygen-com/hyperframes` |
  229. | `hyperframes-core`, `hyperframes-animation`, `hyperframes-creative`, `hyperframes-cli`, `hyperframes-registry` | Agent skills | The domain family the router points at — composition contract and `data-*` timing (core), GSAP choreography such as eases, timelines, stagger and the transition catalog (animation), visual style/typography/data-in-motion (creative), gates and render commands (cli), catalog blocks (registry). Loaded on demand across Phases 3–5, never wholesale. | Installed by the same `npx skills add heygen-com/hyperframes` |
  230. | `media-use`, `motion-doctrine` | Agent skills | **`media-use` owns the audio generation mechanisms** — its engine handles ElevenLabs narration and delegated music/SFX; confirmed Kokoro narration uses its TTS_LOCAL route directly with the selected native language. This skill retains exact-track confirmation, caption review, the verified mix, and render approval. `motion-doctrine` owns the seam/transition law that supersedes local transition guidance where the two disagree (Phase 4). | Installed by the same `npx skills add heygen-com/hyperframes` |
  231. | `hyperframes` npm package | CLI | `init`, `add` (pull catalog blocks — scenes in Phase 3, seams and furniture in Phase 4), `lint` (fast iteration), `preview`, `check` (the required final gate — `inspect`, `validate` and `layout` are deprecated aliases it subsumes), `render`, `doctor` (render diagnostics), `transcribe` (Phase 5's preferred timing verifier, with standalone Whisper as fallback), `tts` (confirmed local Kokoro voices) | `npx hyperframes <command>` (auto-fetches; package: [`hyperframes`](https://www.npmjs.com/package/hyperframes), repo: [github.com/heygen-com/hyperframes](https://github.com/heygen-com/hyperframes)) |
  232. Skill *names* are the ecosystem's stable API; the file paths *inside* them churn, so every path this
  233. skill relies on is registered once in [`compat/ecosystem.md`](compat/ecosystem.md) and cited
  234. everywhere else by capability symbol.
  235. ## Installation
  236. The recommended install is the **[skills CLI](https://github.com/vercel-labs/skills)**. For a
  237. portable project install shared by multiple agents, use an `.agents/skills/` destination; global
  238. skill homes differ by agent.
  239. ### Recommended: Skills CLI
  240. ```bash
  241. # Project install — run from your project; writes to the agent's project skills home
  242. npx skills add nebrass/hve-video-director
  243. # Global install (Claude Code is the default agent)
  244. npx skills add nebrass/hve-video-director --global
  245. # Global install for GitHub Copilot CLI (~/.copilot/skills/)
  246. npx skills add nebrass/hve-video-director --agent github-copilot --global
  247. ```
  248. In Copilot CLI, run `/skills` to confirm the skill is loaded.
  249. ### Fallback: manual git clone
  250. If you can't run the CLI, clone the repo into your agent's skills home directly:
  251. ```bash
  252. git clone https://github.com/nebrass/hve-video-director.git ~/.claude/skills/hve-video-director
  253. # GitHub Copilot CLI: clone into ~/.copilot/skills/hve-video-director instead
  254. ```
  255. ### OpenCode, Pi, Codex & Cursor (native discovery)
  256. No plugin or manifest needed — these agents discover skills by directory convention and read the same Agent Skills `SKILL.md` format. The skills-CLI install above writes a `<name>/SKILL.md` subdir into a home each one scans, so they pick up hve-video-director natively:
  257. ```bash
  258. npx skills add nebrass/hve-video-director # project (.agents/skills/)
  259. npx skills add nebrass/hve-video-director --global # global
  260. ```
  261. - **OpenCode** — `.claude/skills/`, `~/.claude/skills/`, `.agents/skills/`, `~/.agents/skills/`, `.opencode/skills/`, `~/.config/opencode/skills/`. Docs: <https://opencode.ai/docs/skills/>.
  262. - **Pi** — `~/.pi/agent/skills/`, `~/.agents/skills/` (global), `.pi/skills/`, `.agents/skills/` (project, after the project is *trusted*). Docs: <https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md>.
  263. - **Codex** — `$CWD/.agents/skills/`, `$REPO_ROOT/.agents/skills/`, `$HOME/.agents/skills/`, `/etc/codex/skills/`. Docs: <https://learn.chatgpt.com/docs/build-skills>.
  264. - **Cursor** — `.agents/skills/`, `.cursor/skills/`, `~/.agents/skills/`, `~/.cursor/skills/`, plus `.claude/skills/` and `.codex/skills/`. Docs: <https://cursor.com/docs/skills>.
  265. Then ask for a video (for example, "use hve-video-director to make a showcase video of this app").
  266. Skill loading follows each agent's documented convention. Loading is not proof that Chrome MCP,
  267. question prompts, companion skills, or the complete render pipeline work on that host.
  268. ### Compatibility status
  269. | Agent | Discovery / invocation | Pipeline status |
  270. |---|---|---|
  271. | Claude Code | Automatic or `/hve-video-director` | Phase 0→5 verified |
  272. | GitHub Copilot CLI | Automatic or `/hve-video-director`; inspect with `/skills info hve-video-director` | Phase 0→5 verified |
  273. | OpenCode | Automatic through the native skill loader | Discovery-compatible; Phase 0→5 unverified |
  274. | Pi | Automatic or `/skill:hve-video-director` | Discovery-compatible; requires suitable MCP extensions for web capture; Phase 0→5 unverified |
  275. | Codex | Automatic, `/skills`, or `$hve-video-director` | Discovery-compatible; Phase 0→5 unverified |
  276. | Cursor | Automatic or `/hve-video-director` | Discovery-compatible; Phase 0→5 unverified |
  277. The workflows resolve question and Chrome DevTools capabilities at runtime; they do not assume
  278. Claude Code's literal MCP identifiers are available elsewhere.
  279. ## Updating
  280. Already installed an older version? Update to the latest `main`:
  281. ```bash
  282. npx skills update hve-video-director # alias: upgrade · -g global · -p project · -y skip the scope prompt
  283. ```
  284. Installed via a manual git clone instead? `cd` into the skills home you cloned to and run `git pull`.
  285. Reload according to the active agent. Copilot CLI supports `/skills reload`; Claude Code watches
  286. existing skill directories for `SKILL.md` changes; other agents may require a restart. Run
  287. `npx skills list` to see what's installed and where.
  288. ## Quick Start
  289. 1. **Set API keys** as needed:
  290. ```bash
  291. export ELEVENLABS_API_KEY=your_key_here # required only if you confirm an ElevenLabs voice
  292. ```
  293. That is the only API key this skill requires. A music bed needs none either — except the
  294. optional catalog-retrieval route below.
  295. Optional, and never done for you: sign in to HeyGen (`heygen auth login --oauth`, or set
  296. `HEYGEN_API_KEY`). It lets the `media-use` engine retrieve a catalog music bed and sound
  297. effects; it does not change the confirmed voice (see § Voices).
  298. `./scripts/check_requirements.sh` reports it as `heygen-credential` and degrades without it.
  299. 2. **Start the skill:**
  300. ```
  301. /hve-video-director Show feature XYZ in a typical end-to-end scenario, covering its granular options and final results.
  302. ```
  303. This slash form works on Claude Code, GitHub Copilot CLI, and Cursor. Pi uses
  304. `/skill:hve-video-director`; Codex uses `/skills` or `$hve-video-director`; OpenCode loads the skill
  305. by intent. The current directory supplies source context; a directory argument is not required.
  306. A different request produces a different scope, for example:
  307. ```
  308. /hve-video-director Create a 30-second promo focused on the benefit of feature XYZ.
  309. ```
  310. A granular demo stays a scenario walkthrough; a short promo does not automatically become a
  311. tutorial. The word "demo" alone does not select a mode. Required brief confirmations and phase
  312. approvals still apply, including when a duration or other choice was stated in the request.
  313. 3. **Complete guided setup on the first `new` run.** Before creating `project-plan.md`, Phase -1
  314. reads the checker's JSON report, explains what is ready/degraded/blocked and which phases are
  315. affected, asks consent for only available safe fix IDs, re-checks, and blocks only on required
  316. gaps. Manual system/sudo/environment actions remain yours to run. `continue` and `jump` skip
  317. this onboarding.
  318. 4. **Follow the prompts.** Phase 0 → 5 is interactive; each phase has a user-approval checkpoint before advancing. The user-owned choices include:
  319. - **Mode**: Promo, Showcase, or Tutorial
  320. - **Duration + theme + aspect ratio**: 30s/60s/90s, light/dark, 16:9/9:16/1:1/4:5
  321. - **Visual identity strategy**: pick a [vendored brand](design-systems/), pick a HyperFrames named style, derive from screenshots, or provide a custom identity
  322. - **Languages**: choose from the actual provider/model's capabilities, explicitly confirm using it for both on-screen text and narration, or choose a separate spoken language
  323. - **Voice provider + exact voice**: Matilda / Rachel / Daniel / Josh (ElevenLabs), or a verified Kokoro voice from the current catalog; the confirmed provider is never replaced automatically
  324. - **Transitions + music strategy**: explicitly chosen before storyboarding
  325. - **Complete story-brief confirmation** before `storyboard.md` is created
  326. - **Exact music-track confirmation** (title/path/source/license, or explicit no music) before mixing/render
  327. - **Storyboard review** before Phase 2 capture
  328. - **Design review** after Phase 3 scene templates
  329. - **Composition preview** after Phase 4 root index.html
  330. These creative-brief choices belong to the user. The agent may label a recommendation with a
  331. reason, but never infers or preselects an answer from codebase research.
  332. Curated-system theme support is enforced before confirmation: Linear is dark-only; Vercel,
  333. Airbnb, Cal, and Bento are light-only; Stripe, Apple, Notion, GitHub, and Arc support either.
  334. 5. **Get your video:**
  335. ```
  336. out/final.mp4 — chosen aspect (16:9 / 9:16 / 1:1 / 4:5), voiceover + music, H.264 + AAC
  337. out/final.srt — reviewed SubRip closed captions
  338. out/final.vtt — reviewed WebVTT closed captions
  339. ```
  340. ## Entry Modes
  341. | Mode | Command | When |
  342. |------|---------|------|
  343. | `new` (default) | `hve-video-director <video request>` | Collect the request, run guided setup, and create a confirmed output workspace |
  344. | `continue` | `hve-video-director --mode continue --output-dir "./my-video"` | Resume that generated workspace |
  345. | `jump` | `hve-video-director --mode jump --phase 3 --output-dir "./my-video"` | Request a phase (0–5); existing prerequisites and freshness checks still apply |
  346. Use the invocation syntax from the compatibility table above.
  347. Optional `--source-dir` and `--output-dir` distinguish the product source from generated video
  348. artifacts. Controls must lead the request; `--` ends them explicitly:
  349. ```text
  350. /hve-video-director --source-dir "../product" --output-dir "./XYZ demo" -- Show XYZ end to end.
  351. ```
  352. Everything after the start of the description remains request text, including quoted paths and
  353. flag examples. Bare `new` asks for the description. Ambiguous legacy directory-first input asks
  354. for clarification; its directory still means output, never source. Continue/jump without an
  355. unambiguous workspace ask which one to resume, rather than choosing the latest folder.
  356. ## Prompt-driven scenarios
  357. For a scenario request, discovery focuses on the named feature and grounds its steps/options and
  358. expected result in code, documentation, or your explanation. You approve the proposed scenario.
  359. Storytelling then maps every approved requirement to frames and planned evidence in the
  360. storyboard's **Scenario Coverage** section; capture and composition review fill in what was
  361. actually shown. An unresolved option is not complete coverage, and a duration conflict requires
  362. your choice rather than silently dropping details.
  363. The original request is stored as a lossless JSON string in `project-plan.md` outside the Creative
  364. Brief. `context.md` holds the researched interpretation and approved scenario, not an inferred set
  365. of creative choices. Existing projects without this metadata remain resumable; an artifact-only
  366. late-phase resume does not require the source unless source-dependent work is needed.
  367. ## Languages
  368. Language choices come from the **actual generation provider/model's current capabilities**, not
  369. an English/French shortlist or a frozen marketing count. Phase 1 imports native model/voice data,
  370. presents the supported choices, and asks whether to use the selected language for both text and
  371. speech or to override the spoken language. The Creative Brief records separate `text_language`
  372. and `narration_language` values; `.hve/language-profile.json` binds those canonical locales to the
  373. verified voice/model and their native TTS and ASR codes. Catalog access or an authoritative export
  374. is a runtime prerequisite: unavailable data is an explicit setup issue, never an English fallback.
  375. Authored text follows the text locale; narration and captions follow the spoken locale. Captured
  376. UI, code and literal product names are not automatically translated. There is no separate
  377. translated-subtitle or batch-localization mode. Script/font shaping, direction, actual speech and
  378. ASR readiness still need review: provider support is not end-to-end pronunciation/render
  379. qualification, and the English `vo-budget` heuristic reports non-English timing as unmeasurable.
  380. Changing either language stales the affected phases without deleting prior artifacts.
  381. Historical schema-1 projects remain inspectable under their original consent; new generation
  382. requires an explicitly approved language upgrade, never an inferred English answer. Synthesis
  383. reuse binds the exact lines and settings to the profile's **speech** fingerprint, so a text-only
  384. locale edit does not force new narration. Language/voice/model/settings changes require a full
  385. prepare/synthesis/seal round; subset retries cannot carry old takes into a new speech identity.
  386. ## Voices
  387. | Voice | Style | Voice ID |
  388. |-------|-------|----------|
  389. | Matilda | Warm, confident female | `XrExE9yKIg1WjnnlVkGX` |
  390. | Rachel | Calm, clear female | `21m00Tcm4TlvDq8ikWAM` |
  391. | Daniel | Authoritative male | `onwK4e9ZLuTAKqWW03F9` |
  392. | Josh | Friendly, conversational male | `TxGEqnHWrfWFTfGW9XjX` |
  393. These four ElevenLabs voices remain the user-facing voice contract. Phase 5 synthesizes them
  394. through the `media-use` audio engine's ElevenLabs route; without that engine installed, the
  395. key-free local Kokoro route below is the available option, on your explicit confirmation.
  396. Caption timing does not come from the voice route at all, on any provider:
  397. Phase 5 transcribes the *assembled* `voiceover.mp3` with `npx hyperframes transcribe`, because
  398. that is the only place the times are composition-absolute.
  399. **Local option (Kokoro):** choose a verified voice during Phase 1 for no-key local TTS
  400. (e.g. `af_nova`, `af_heart`). `npx hyperframes tts --list --json` is a curated voice list,
  401. **not the full language set**. TTS_LOCAL and TTS_LANGUAGE_DISCOVERY, resolved through
  402. [`compat/ecosystem.md`](compat/ecosystem.md), own current model/language discovery and native
  403. prerequisites. Phase 5 calls the existing local TTS CLI directly with the checked native language,
  404. accepts only an applied-language result, and transcribes the assembled audio with the separate ASR
  405. code. A missing ElevenLabs key never changes a confirmed provider — and neither does a HeyGen
  406. sign-in. Local and user-supplied takes still need request/profile/preparation proofs in
  407. language-aware projects; an origin attestation cannot waive freshness.
  408. ## Music Strategy
  409. No bundled audio files. Four confirmable strategies — `music_strategy` in the Creative Brief:
  410. 1. **`freesound`** — a Creative Commons track you pick yourself on
  411. [freesound.org](https://freesound.org): browse by mood or genre, check the license on the track's
  412. page, download it, and give Phase 5 the file — or let Phase 5 search for you with
  413. `scripts/search_music.py` (needs a free `FREESOUND_API_KEY`), which prints ranked candidates with
  414. duration, licence and track URL. Attribute CC-BY tracks in `CREDITS.md`. The
  415. recorded `source` is the exact `freesound.org` track URL carrying its numeric sound ID, which is
  416. what keeps the choice checkable later.
  417. 2. **`delegated`** — a bed the `media-use` audio engine retrieved from a provider catalog. Phase 5
  418. offers retrieval only: local *generation* is a valid value the validator still accepts, but the
  419. workflow stopped offering it after a real run stalled two hours on an unauthenticated model
  420. download and produced nothing, and because a generated bed has no author, no stable page and no
  421. independently auditable licence. There is no public page to link and a presigned download URL expires, so the recorded
  422. `source` is a provenance URI instead:
  423. `<skill-name>:<capability>?mode=<retrieve|generate>&query=<url-encoded request>#sha256=<64 hex>`
  424. — who produced it, by which route *actually* taken, from which request, and which bytes came
  425. out. `prompt=` replaces `query=` for a full generation prompt; exactly one of the two is
  426. required. The digest is the SHA-256 of the file at `path`, so the record stays checkable offline
  427. years later with `shasum -a 256 background-music.mp3`. `license` is still required and still
  428. yours to state — a generated bed is not automatically unencumbered.
  429. 3. **`user-provided`** — bring your own MP3 or URL; the recorded `source` is the literal
  430. `user-provided`.
  431. 4. **`none`** — voiceover only.
  432. Never record a delegated track as `user-provided`: that repurposes a Phase-1 answer you gave before
  433. any candidate existed, and erases the only machine-checked provenance the brief carries.
  434. The strategy is confirmed with the story brief. Whatever produced the candidate — catalog retrieval,
  435. local generation, Freesound, or your own file — Phase 5 separately confirms the exact track (title,
  436. project path, source, and license) or explicit `none`; no track is mixed or rendered before that
  437. confirmation, on **every** strategy including `delegated`. A generated or retrieved suggestion is a
  438. candidate, never the answer.
  439. ## Creative Brief validation
  440. Generated projects keep the stable Creative Brief table in `project-plan.md` and output-adjacent
  441. confirmation/freshness state in `.hve/brief-state.json`. The pure-stdlib validator writes state
  442. atomically, never deletes artifacts, and reports the earliest phase made stale by an edited choice.
  443. ```bash
  444. python3 /path/to/hve-video-director/scripts/validate_brief.py \
  445. --project-dir ./my-video status --json
  446. # Legacy plans only, after explicit user consent: insert an empty table without inferring values
  447. python3 /path/to/hve-video-director/scripts/validate_brief.py \
  448. --project-dir ./my-video migrate
  449. python3 /path/to/hve-video-director/scripts/validate_brief.py \
  450. --project-dir ./my-video confirm-story
  451. python3 /path/to/hve-video-director/scripts/validate_brief.py \
  452. --project-dir ./my-video confirm-audio
  453. python3 /path/to/hve-video-director/scripts/validate_brief.py \
  454. --project-dir ./my-video stamp phase-1
  455. python3 /path/to/hve-video-director/scripts/validate_brief.py \
  456. --project-dir ./my-video require phase-1
  457. ```
  458. Story-field changes stale Phase 1–5. Changing only `final_music_track` stales Phase 5.
  459. For pre-schema projects, `status --json` reports `migration_required: true`; migration preserves
  460. the old plan, inserts placeholders atomically, and returns to the user-owned Phase-1 prompts.
  461. ## Storyboard format
  462. Phase 1 writes `storyboard.md` in the **official HyperFrames storyboard format**: YAML frontmatter,
  463. one `## Frame N — Title` section per frame, `- key: value` metadata bullets, free prose below them.
  464. Frames are numbered 1-based the way the finished video labels them, while scene *files* stay 0-based
  465. (`scenes/00-…`). Adopting that shape is what makes the plan reviewable with the ecosystem's own
  466. tooling — the upstream storyboard parser, the Studio contact-sheet board, and the structured
  467. per-frame comment sidecar `.hyperframes/frame-comments.json` that a review round writes on submit
  468. and the next round deletes.
  469. Everything the official key set has no home for rides along as ordinary bullets: the director keys
  470. (Phase 1's recorded per-frame reasoning), the capture bindings, and this skill's own film-level
  471. fields such as `content_mode` and `emotional_journey`. The parser preserves unknown keys verbatim
  472. under a frame's `extra`, which is the only reason they survive. That guarantee is load-bearing
  473. enough to be tested rather than trusted: `test/unit/test_storyboard_extra_keys.py` round-trips every
  474. director key through an upstream parser and fails if one is dropped, altered, or captured by a newly
  475. official key — see the `STORYBOARD_EXTRA_KEYS` probe in
  476. [`compat/ecosystem.md`](compat/ecosystem.md).
  477. **Older projects keep working.** Nothing in the pipeline is gated on the storyboard's shape, so a
  478. project created before this format still resumes untouched. Ask the validator which shape a project
  479. is in, and convert only if you want to:
  480. ```bash
  481. python3 /path/to/hve-video-director/scripts/validate_brief.py \
  482. --project-dir ./my-video storyboard --json
  483. # Converts a pre-adoption storyboard — only when you ask. The original is preserved
  484. # alongside the converted file, and a legacy line with no official home becomes an
  485. # extra bullet rather than a guessed value.
  486. python3 /path/to/hve-video-director/scripts/validate_brief.py \
  487. --project-dir ./my-video migrate-storyboard
  488. ```
  489. ### Why `BRIEF.md` is deliberately *not* adopted
  490. The ecosystem also publishes a brief format and, with it, a brief **contract**: a run-shape
  491. derivation that decides how collaborative or autonomous a run should be, and that explicitly *skips
  492. questions the request already answers*. This skill does the opposite — it recommends but never
  493. preselects, and never infers an answer you did not give. Adopting the official brief would import a
  494. contract that contradicts that promise, so `project-plan.md` stays the Creative Brief and the single
  495. record of the levers you own, and the validator is never re-pointed at `BRIEF.md`.
  496. The storyboard was adopted precisely because it is not that kind of document: it *describes the
  497. film*, it does not record consent. One visible consequence — the storyboard's frontmatter never
  498. carries `mode`, which upstream reserves for that interaction mode; this skill's promo / showcase /
  499. tutorial choice lives in `content_mode`. The full reasoning sits on the `BRIEF_FORMAT` and
  500. `BRIEF_CONTRACT` rows of [`compat/ecosystem.md`](compat/ecosystem.md); read it before "finishing the
  501. job", because completing the adoption would quietly replace the consent model.
  502. ## Project Structure
  503. When hve-video-director creates a video project, it generates:
  504. ```
  505. my-video-project/
  506. ├── project-plan.md # Stable Creative Brief + phase tracker + decision log
  507. ├── .hve/
  508. │ ├── brief-state.json # Atomic confirmation fingerprints + phase freshness stamps
  509. │ ├── language-profile.json # Checked text/narration locales + opaque speech identity
  510. │ ├── vo-sections.json # Settings/line/media seal; pending marker exists during synthesis
  511. │ └── captions-state.json # Final-audio/review/output caption fingerprints
  512. ├── context.md # Product context from Phase 0
  513. ├── storyboard.md # Frame-by-frame plan from Phase 1, in the official
  514. # HyperFrames storyboard format (see § Storyboard format)
  515. ├── .hyperframes/
  516. │ └── frame-comments.json # Only while a Studio frame-review round is open
  517. ├── DESIGN.md # Design contract from Phase 3 (palette, type, motion)
  518. ├── recordings/ # Your DevTools Recorder JSON exports (replayed by Phase 2)
  519. ├── .hve/replay/ # Step→timecode ledgers from replay takes
  520. ├── public/
  521. │ ├── screenshots/ # App captures from Phase 2
  522. │ └── clips/ # Filmed clips: screencast takes, native recordings, replay cuts
  523. ├── scenes/ # Phase 3 HyperFrames scene templates
  524. │ ├── 00-title-card.html
  525. │ ├── 01-pain-point.html
  526. │ └── ...
  527. ├── index.html # Phase 4 root HyperFrames composition
  528. ├── voiceover.mp3 # narration, assembled from the per-section takes at their exact times
  529. ├── transcript.json # word timings for captions
  530. # (or voiceover.json if you used standalone whisper)
  531. ├── background-music.mp3 # the confirmed music bed (engine, Freesound, or user-provided)
  532. ├── voiceover-with-music.mp3 # Mixed track wired into index.html
  533. ├── captions-review.json # Human-reviewed speech/speaker/sound cue source
  534. └── out/
  535. ├── final.mp4 # `npx hyperframes render` output
  536. ├── final.srt # Reviewed SubRip closed-caption sidecar
  537. └── final.vtt # Reviewed WebVTT closed-caption sidecar
  538. ```
  539. ## Skill File Structure
  540. ```
  541. hve-video-director/
  542. ├── SKILL.md # Orchestrator entry point (read first)
  543. ├── CLAUDE.md # Codebase guide for agent sessions (Claude Code / Copilot CLI) editing this repo
  544. ├── workflows/ # The 6-phase pipeline, one file per phase
  545. │ ├── phase-0-discovery.md
  546. │ ├── phase-1-storytelling.md
  547. │ ├── phase-2-capture.md
  548. │ ├── phase-3-design.md
  549. │ ├── phase-4-production.md
  550. │ └── phase-5-audio.md
  551. ├── reasoning/ # How a scene is analysed and a runtime chosen
  552. │ ├── scene-analysis.md # Per-scene communication analysis + the cognitive-load budgets
  553. │ └── capability-catalog.md # The capability-tag vocabulary → runtime selection
  554. ├── grammar/ # Visual grammars the reasoning layer draws on
  555. │ ├── camera.md
  556. │ ├── motion.md
  557. │ ├── metaphors.md
  558. │ └── three-taxonomy.md
  559. ├── compat/
  560. │ └── ecosystem.md # The only file holding upstream file paths (capability registry)
  561. ├── templates/ # Copied into each generated video project
  562. │ ├── project-plan.md
  563. │ ├── context.md
  564. │ ├── storyboard.md
  565. │ └── scene-*.html # Scene skeletons — a frame packet's starting point
  566. ├── patterns/ # What the ecosystem does not own: craft, budgets, capture
  567. │ ├── INDEX.md # The local map; delegation lives in compat/ecosystem.md
  568. │ ├── visual-patterns.md # Camera on stills, legibility floor, DON'Ts, stagger trap
  569. │ ├── marker-highlight.md # Mode → promo-arc mapping + the editorial caps
  570. │ ├── transition-catalog.md # Mood-mapped transition choice + energy budget
  571. │ ├── cli-terminal-capture.md # asciinema + agg real-terminal clip workflow
  572. │ ├── authenticated-browser-capture.md # safe SSO/MFA live-tab attachment
  573. │ └── anti-slop.md # Cardinal sins + AI Tool Promo specifics
  574. ├── design-systems/ # 10 vendored brand presets (Phase 1 Path A)
  575. │ ├── README.md # Catalog + how to use
  576. │ ├── CONTRIBUTING.md # Quality bar for adding more brands
  577. │ ├── stripe/DESIGN.md
  578. │ ├── linear-app/DESIGN.md
  579. │ ├── apple/DESIGN.md
  580. │ └── … # notion, vercel, airbnb, github, cal, arc, bento
  581. ├── sub-agents/
  582. │ └── scene-builder-delta.md # the builder role shipped inside every frame packet
  583. ├── scripts/ # stdlib/platform-tool helpers, no Python packages
  584. │ ├── generate_voiceover.py # voiceover-section assembly (used by both audio paths)
  585. │ ├── verify_vo_sections.py # exact-request preparation + settings/profile/media seal
  586. │ ├── caption_gen.py # ASR drafts → reviewed, audio-bound final caption sidecars
  587. │ ├── language_tools.mjs # existing Node/ICU locale, grapheme and word operations
  588. │ ├── capture_screen.py # native screen/region capture orchestrator (silent)
  589. │ ├── stitch_clip.py # normalize/stitch captures to the CFR30 clip contract
  590. │ ├── mix_clip_audio.py # mix one clip's own audio into the soundtrack + duck the VO
  591. │ ├── validate_brief.py # Creative Brief validation, fingerprint state, storyboard read
  592. │ └── check_requirements.sh # JSON/plan preflight + consent-scoped safe fixes
  593. ├── test/
  594. │ ├── run.sh # stdlib unit/integration test entrypoint
  595. │ ├── check_shell_portability.py # native Bash smoke checks, with real Node/Python and stub installers
  596. │ └── unit/ # caption, capture, requirements, onboarding, brief and resolver tests, plus:
  597. │ ├── test_compat_pointers.py # pointer validity — compat/ecosystem.md is the only holder of upstream paths
  598. │ ├── test_director_keys.py # docs-as-contract — director keys + the capability-tag vocabulary
  599. │ └── test_storyboard_extra_keys.py # behavior probe — director keys survive the official storyboard format
  600. └── .github/
  601. └── copilot-instructions.md # Guide for Copilot reviewers
  602. ```
  603. ## Development checks
  604. Run the existing helper suite with `bash test/run.sh`. The
  605. [`native shell verification`](.github/workflows/shell-portability.yml) workflow also runs
  606. on macOS using `/bin/bash` **3.2**, and on Windows using **Git Bash with native Windows
  607. Node and Python**, not WSL. It runs on pushes and pull requests touching scripts, tests,
  608. shell-recipe workflows/patterns, `SKILL.md`, the CI workflow or Git attributes.
  609. Once the workflow is on the default branch, it can also
  610. be started manually from Actions.
  611. Each native job runs [`test/check_shell_portability.py`](test/check_shell_portability.py)
  612. and the existing full suite independently, then uploads `native-shell-macOS` or
  613. `native-shell-Windows` logs even when a check fails. The smoke checks exercise file,
  614. stdin and standalone-download invocation, real Node/ICU checks, isolated `--fix` calls
  615. with installer stubs, and Windows `core.autocrlf=true` checkouts. They do not install
  616. dependencies through `--fix`, rewrite checked-out files, suppress failures or
  617. turn a skipped test into platform verification.
  618. Git attributes preserve LF bytes for text files even with `core.autocrlf=true`, so
  619. Windows checkouts do not change the recorded example or its pinned hashes. The test
  620. fixtures resolve native shell executables and convert MSYS paths at the Python/shell
  621. boundary. Tests for filenames Windows cannot represent remain explicitly POSIX-only.
  622. Voiceover manifest publication fsyncs the file before atomic replacement on all platforms.
  623. POSIX also fsyncs the parent directory; Windows does not support opening that directory
  624. through Python's `os.open`, so no directory-fsync guarantee is made there.
  625. To check macOS locally with the same interpreter:
  626. ```bash
  627. python3 test/check_shell_portability.py --bash /bin/bash \
  628. --expected-platform darwin --expected-bash 3.2
  629. ```
  630. On Windows, run from Git Bash with native Node and Python on PATH:
  631. ```bash
  632. python test/check_shell_portability.py --bash "$BASH" --expected-platform win32
  633. ```
  634. Push the verification changes to start both jobs; their results and uploaded logs are
  635. the evidence, not the presence of this workflow. Known portability failures remain
  636. visible until repaired, and optional integrations skipped by the full suite remain
  637. unverified.
  638. ## FAQ
  639. **Q: Can I use this without ElevenLabs?**
  640. A: Yes — explicitly choose a Kokoro voice in Phase 1. Phase 5 then uses `npx hyperframes tts`
  641. locally with no API key, even if an ElevenLabs key exists. For non-English narration, install
  642. the language/backend prerequisites identified through TTS_LOCAL (including `espeak-ng` when
  643. required). The skill never silently switches providers or assumes a curated voice list is the
  644. full language catalog.
  645. **Q: Can I skip the screenshot capture phase?**
  646. A: Yes, when the confirmed product surface is `none` and the storyboard requests no capture.
  647. Phase 2 records and stamps that intentional skip before Phase 3. A jump cannot bypass a stale or
  648. unconfirmed brief merely because files exist.
  649. **Q: What video resolution/format does it output?**
  650. A: 30fps MP4 (H.264 video + AAC audio) via `npx hyperframes render`. The canvas size is chosen in Phase 1:
  651. - 16:9 → 1920×1080 (recommended for horizontal promos, web, and embeds)
  652. - 9:16 → 1080×1920 (vertical — TikTok, Reels, Shorts)
  653. - 1:1 → 1080×1080 (square — IG feed, LinkedIn)
  654. - 4:5 → 1080×1350 (portrait IG feed)
  655. **Q: Can I edit the video after generation?**
  656. A: Yes — the project is plain HTML + CSS + GSAP. Edit `index.html` or any `scenes/*.html` file
  657. directly. Run `npx hyperframes preview --background` for a scrubbable timeline UI, then run
  658. `npx hyperframes preview --stop` when review ends before using `npx hyperframes render` to
  659. re-render. Closing the Studio browser does not stop its preview server.
  660. **Q: Is Freesound music free to use commercially?**
  661. A: It depends on the track. Freesound hosts a mix of CC0 (public domain — no attribution, commercial OK), CC-BY (commercial OK with attribution), and other Creative Commons variants. You pick the track yourself and record its license in the Creative Brief, so check that license on the track's Freesound page before commercial use — prefer CC0 or CC-BY. For a license that requires attribution, the workflow writes a `CREDITS.md`.
  662. ## Credits
  663. Fork of [promo-video](https://github.com/buildatscale-tv/claude-code-plugins/tree/main/plugins/promo-video) by buildatscale-tv, extended with design thinking, Chrome DevTools capture, HyperFrames composition (HTML + GSAP), and confirmed-track music sourcing.
  664. ## Trademarks and attribution
  665. All product names, brands, and trademarks referenced by this skill — including the ten
  666. [`design-systems/`](design-systems/) presets — are the property of their respective owners and
  667. are used nominatively, to identify those products. The design-system presets are original
  668. written descriptions of publicly observable visual conventions; this project ships no
  669. third-party logos, fonts, or brand assets.
  670. See [`TRADEMARKS.md`](TRADEMARKS.md) for full attribution and for the licensing of generated
  671. output (Freesound music, ElevenLabs voiceover, your own captures).
  672. ## License
  673. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.