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
HyperFrames Video Director is a creative-direction skill for coding agents that make videos with HyperFrames. 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.
- 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.
git clone https://github.com/artificialguybr/hyperframes-video-director.gitFor 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.
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:
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.
Start with SKILL.md and the matching directing/ guide. Load craft references when they change a decision; do not stuff every guide into every run.
| Goal | Directing guide |
|---|---|
| Social ads and vertical promotional videos | Social ad |
| Product launches and feature reveals | Product launch |
| Explanations and causal stories | Explainer |
| Animated text and kinetic typography | Kinetic type |
| Logo animations and brand stings | Logo sting |
| Animated charts and data storytelling | Data visualization |
| Observational and human-centered stories | Documentary |
| Trailers and suspense-driven teasers | Trailer |
| Music-led edits and rhythmic motion | Music beat |
| Product walkthroughs and interface demos | UI demo |
| Character and vector animation | 2D vector |
| Portfolio montages and reels | Showreel |
| Procedural animation and 3D product heroes | Procedural 3D |
| Vocal-synchronized animated lyrics | Lyric video |
| News graphics and lower thirds | Broadcast |
| Step-by-step instructional videos | Tutorial |
| Comic shorts and reaction-driven edits | Meme short |
Each guide describes intent, tempo hypotheses, preferences, avoidances, and technique options. None supplies a finished layout or a mandatory scene sequence.
Brief → direction → implementation → rendered review → focused revision.
- Choose the viewer change. What should become clear, desirable, or emotionally different?
- Commit to a visual idea. Name the final feeling, one bold choice, and one deliberate omission.
- Build with HyperFrames. Use its official composition and deterministic animation contracts.
- Review the encoded output. Inspect realistic display-size frames, watch the motion, and listen to the mix when those capabilities are available.
- 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 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.
These optional helpers measure or surface problems; they do not generate your video.
Requirements: Python 3, Pillow, 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:
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install PillowRun from the repository root, using your own project and output paths:
# 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-videoFor browser observations, inject scripts/sample_layout.js into the loaded composition document, not the Studio shell. Choose in-duration times and call:
await collectDirectorObservations([0.1, 2, 4]);Save the returned JSON, then pass --observations observations.json to amateur_check.py. Consult the tooling guide 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.
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
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, historical tool verification, and the controlled evaluation protocol.
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.
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.
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 to examine meaningful variation.
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.
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.
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.
Focused improvements are welcome: clearer decision guidance, corrected source attributions, or reproducible diagnostic fixes. See CONTRIBUTING.md. Please do not add a universal visual preset or promote an unmeasured heuristic to a proven rule.
MIT · Maintained by artificialguybr.
Independent community skill, not affiliated with or endorsed by HyperFrames or HeyGen. External sources are cited in SOURCES.md; their original material remains subject to its own rights.