Creative direction for AI-generated video. No preset look.
An English-language AI agent skill for HyperFrames, motion design, and purposeful visual storytelling.
Quick start · Video types · Workflow · Tools · FAQ
## What is HyperFrames Video Director? **HyperFrames Video Director is a creative-direction skill for coding agents that make videos with [HyperFrames](https://hyperframes.heygen.com/).** It helps an agent choose a specific visual idea, meaningful pacing, readable typography, coherent motion, and appropriate sound—without supplying a composition template. Version 4 is the directing layer. **HyperFrames and its official implementation skills remain responsible for authoring, animation APIs, validation, and rendering.** This repository is not a video renderer, a hosted generation service, or an official HyperFrames product. ### Direction, not a default aesthetic - **A concept before effects.** Decide what changes for the viewer and which visual idea carries it. - **17 purpose-specific guides.** An ad, tutorial, title sequence, and data story should not share one recipe. - **A vocabulary of visual results.** Choose techniques by meaning, not by effect count. - **Contextual craft guidance.** Timing and density ranges are starting points, not creative quotas. - **Review grounded in the output.** Check what viewers can actually see, read, and hear. - **Transparent evidence.** Source-backed specifications, practitioner advice, and creative heuristics are distinguished. No bundled composition code, scene templates, fixed fonts, preset palettes, mandatory camera moves, or automatic sound-effect recipes. Clean, dense, quiet, and expressive work are all valid when the brief justifies them. ## Quick start ### 1. Get the skill ```bash git clone https://github.com/artificialguybr/hyperframes-video-director.git ``` For file-based use, point your agent at `hyperframes-video-director/SKILL.md`. For automatic discovery, put the repository folder in the skill directory supported by your agent. Enable only one copy of `hyperframes-video-director` at a time. **Reading the directing guidance does not require installing Python dependencies.** The optional diagnostic scripts have their own requirements below. ### 2. Provide the brief and implementation tools Make the official HyperFrames skills available, especially `hyperframes-core`, `hyperframes-animation`, and `hyperframes-cli`. Supply the destination, duration, product facts, and assets the agent may use. There is no universal aspect ratio or color scheme. Example prompt: ```text Read hyperframes-video-director/SKILL.md and the matching directing guide. Use the official HyperFrames skills for implementation. Create a 20-second, 9:16 launch ad for my offline notes app. Use the supplied UI and verified features; do not invent product evidence. Invent the visual concept, typography, palette, framing, and motion language. Make the offline benefit understandable on a phone. Before building, state the viewer change, final-frame feeling, one bold choice, and what you will deliberately avoid. Follow the skill's review workflow. Report the actual checks, review coverage, and remaining limitations. ``` This is an example brief, **not a scene plan or a reusable composition**. ### 3. Read selectively Start with [SKILL.md](SKILL.md) and the matching `directing/` guide. Load craft references when they change a decision; do not stuff every guide into every run. ## 17 video types | Goal | Directing guide | |---|---| | Social ads and vertical promotional videos | [Social ad](directing/social-ad.md) | | Product launches and feature reveals | [Product launch](directing/product-launch.md) | | Explanations and causal stories | [Explainer](directing/explainer.md) | | Animated text and kinetic typography | [Kinetic type](directing/kinetic-type.md) | | Logo animations and brand stings | [Logo sting](directing/logo-sting.md) | | Animated charts and data storytelling | [Data visualization](directing/data-viz.md) | | Observational and human-centered stories | [Documentary](directing/documentary.md) | | Trailers and suspense-driven teasers | [Trailer](directing/trailer.md) | | Music-led edits and rhythmic motion | [Music beat](directing/music-beat.md) | | Product walkthroughs and interface demos | [UI demo](directing/ui-demo.md) | | Character and vector animation | [2D vector](directing/vector-2d.md) | | Portfolio montages and reels | [Showreel](directing/showreel.md) | | Procedural animation and 3D product heroes | [Procedural 3D](directing/procedural-3d.md) | | Vocal-synchronized animated lyrics | [Lyric video](directing/lyric-video.md) | | News graphics and lower thirds | [Broadcast](directing/broadcast.md) | | Step-by-step instructional videos | [Tutorial](directing/tutorial.md) | | Comic shorts and reaction-driven edits | [Meme short](directing/meme-short.md) | Each guide describes intent, tempo hypotheses, preferences, avoidances, and technique options. None supplies a finished layout or a mandatory scene sequence. ## How it works **Brief → direction → implementation → rendered review → focused revision.** 1. **Choose the viewer change.** What should become clear, desirable, or emotionally different? 2. **Commit to a visual idea.** Name the final feeling, one bold choice, and one deliberate omission. 3. **Build with HyperFrames.** Use its official composition and deterministic animation contracts. 4. **Review the encoded output.** Inspect realistic display-size frames, watch the motion, and listen to the mix when those capabilities are available. 5. **Revise the highest-impact problems.** The skill's default workflow calls for at least two render/review passes. Do not turn revision into an unbounded polish loop. Use [the review rubric](rubric.md) to evaluate specificity, clarity, typography, rhythm, continuity, composition, sound, identity, and delivery. There is **no validated numeric threshold for professional quality**. If a run is explicitly constrained to one-shot or text-only work, disclose the omitted review rather than claiming it happened. A contact sheet is not continuous playback; a technical pass is not an aesthetic endorsement. ## Diagnostic tools These optional helpers **measure or surface problems; they do not generate your video**. Requirements: Python 3, [Pillow](https://pillow.readthedocs.io/), FFmpeg/ffprobe. The browser sampler needs a loaded HyperFrames composition; the official gate wrapper needs the HyperFrames CLI. Node is useful for JavaScript syntax checks. Install Pillow in a virtual environment: ```bash python3 -m venv .venv source .venv/bin/activate python3 -m pip install Pillow ``` Run from the repository root, using your own project and output paths: ```bash # Sample the encoded video, including detected cuts. python3 scripts/contact_sheet.py output.mp4 -o contact-sheet.png # Report observed technical problems, heuristic warnings, and skipped checks. python3 scripts/amateur_check.py output.mp4 --genre social-ad --project ./my-video # Measure duration, loudness, true peak, and optional whole-file narration rate. python3 scripts/measure_audio.py output.mp4 --script narration.txt # Derive timings from word timestamps and anchor phrases YOU select. python3 scripts/derive_scene_timings.py words.json \ --anchors "The problem" "The result" -o timings.json # Run the official HyperFrames technical checks. bash scripts/validate_project.sh ./my-video ``` For browser observations, inject [`scripts/sample_layout.js`](scripts/sample_layout.js) into the **loaded composition document**, not the Studio shell. Choose in-duration times and call: ```javascript await collectDirectorObservations([0.1, 2, 4]); ``` Save the returned JSON, then pass `--observations observations.json` to `amateur_check.py`. Consult [the tooling guide](docs/TOOLING.md) for coverage and interpretation. **Exit 0 means no observed technical error within the checks performed.** Read warnings and skipped coverage. These tools do not certify taste, flash safety, complete pixel determinism, or intelligible sound. ## Repository map ```text SKILL.md Agent entry point README.md Human-facing overview and quick start directing/ 17 purpose-specific directing guides craft/ Contextual rules and technique vocabulary rubric.md Rendered-output review criteria references/ Accessibility and delivery guidance scripts/ Optional measurement and diagnostic helpers tests/ Reproducible technical smoke check docs/ Architecture, tooling, and evidence notes eval/ Evaluation briefs, protocol, and historical tool checks research/ Research synthesis and 71 recorded query strings SOURCES.md Source IDs, access status, and confidence labels CHANGELOG.md Edition history llms.txt Concise public documentation index .github/workflows/ Technical smoke checks on pushes and pull requests LICENSE MIT license for this repository ``` ## Evidence, not promises The guidance records **71 research queries** and links source IDs to their access and confidence levels. Research informs judgment; it does not prove better videos. Diagnostic helpers received limited fixture and encoded-video checks. The skill was also used in informal local Qwen 27B generation/comparison runs. Those runs are **not a controlled benchmark**: render engines, review opportunities, briefs, and other conditions differed. No universal win rate, quality improvement, or diversity guarantee is claimed. Read [the evidence notes](docs/EVIDENCE.md), [historical tool verification](eval/TESTS.md), and [the controlled evaluation protocol](eval/PROTOCOL.md). ## Frequently asked questions ### Is this a HyperFrames video generator? No. It is an AI agent skill for creative direction. Your coding agent authors the project; HyperFrames renders it. The included scripts diagnose or measure existing outputs. ### Does it support Claude, Codex, Cursor, or other coding agents? It is a plain `SKILL.md` package with Markdown references, so an agent that can read local files can use it explicitly. Automatic discovery depends on the agent's skill-directory conventions. Local usage included Qwen 27B through Pi; there is no certified compatibility matrix or IDE extension bundled here. ### Will different prompts produce different visual styles? The skill avoids bundled visual presets, but variety is not guaranteed. The brief, model, assets, context, and generation process still influence the result. Use the anti-homogeneity questions in [rubric.md](rubric.md) to examine meaningful variation. ### Is it only for minimalist SaaS videos? No. The 17 guides cover ads, typography, explainers, data, character animation, trailers, music, and more. Sparse and dense compositions are both legitimate. A familiar layout should be chosen for a reason, not inherited as a default. ### Does it replace the official HyperFrames skills? No. It complements them. The official skills own composition structure, runtime APIs, assets, rendering, and implementation constraints; this skill focuses on directing decisions and review. ### Can I use it commercially? This repository is MIT-licensed. External assets, fonts, music, services, and rendering software retain their own terms. The skill does not grant those rights or clear generated video for commercial distribution. ## Contributing Focused improvements are welcome: clearer decision guidance, corrected source attributions, or reproducible diagnostic fixes. See [CONTRIBUTING.md](CONTRIBUTING.md). Please do not add a universal visual preset or promote an unmeasured heuristic to a proven rule. ## License and attribution [MIT](LICENSE) · Maintained by [artificialguybr](https://github.com/artificialguybr). Independent community skill, not affiliated with or endorsed by HyperFrames or HeyGen. External sources are cited in [SOURCES.md](SOURCES.md); their original material remains subject to its own rights.