HyperFrames Video Director: a directing skill for AI-made video

TL;DR

• It is a creative-direction skill for coding agents that build videos with HyperFrames — the agent still authors and renders; this repository only decides the idea, pacing, typography, motion and sound.
• v4 ships 17 purpose-specific directing guides, from social ads and product launches to kinetic type, data visualization, lyric video and meme shorts — no shared recipe between them.
• The loop is brief → direction → implementation → rendered review → focused revision, with at least two render and review passes and a rubric that has no validated numeric threshold.
• Five optional diagnostic scripts measure or surface problems: contact sheet, amateur check, audio measurement, scene timings derived from word timestamps, and the official HyperFrames project checks.

What it is and who it is for

HyperFrames Video Director is an English-language agent skill for HyperFrames, the tool that renders HTML compositions to video. The README is careful about the division of labor: this repository is the directing layer, while HyperFrames and its official skills (hyperframes-core, hyperframes-animation, hyperframes-cli) stay responsible for authoring, animation APIs, validation and rendering.

It is for the person whose agent can already produce a technically correct video and keeps producing a forgettable one. The skill supplies the decision layer — what the video is, what changes for the viewer, which visual idea carries it — and deliberately ships no composition template, no fixed fonts, no preset palette and no mandatory camera moves.

What it does

• A concept before effects. The agent must decide what changes for the viewer and which visual idea carries that change, before choosing any effect.
• 17 purpose-specific guides. An ad, a tutorial, a title sequence and a data story do not share one recipe; each guide describes intent, tempo hypotheses, preferences, avoidances and technique options, but never a finished layout or a mandatory scene sequence.
• A vocabulary of visual results. Techniques are chosen by meaning, not by effect count.
• Review grounded in the output. The rubric scores specificity, clarity, typography, rhythm, continuity, composition, sound, identity and delivery — with the caveat that there is no validated numeric threshold for professional quality.
• Transparent evidence. Source-backed specifications, practitioner advice and creative heuristics are labeled as different kinds of claim.

How to use it

Clone the repository and point your agent at SKILL.md:

git clone https://github.com/artificialguybr/hyperframes-video-director.git

For file-based use, point the agent at hyperframes-video-director/SKILL.md; for automatic discovery, put the folder in the skill directory your agent supports. The README warns to enable only one copy at a time. Reading the guidance needs no Python dependencies.

Then supply the brief and the implementation skills. The example the README gives asks for a 20-second, 9:16 launch ad for an offline notes app, using supplied UI and verified features, with the agent inventing the visual concept, typography, palette, framing and motion language — and stating before building the viewer change, the final-frame feeling, one bold choice and what it will avoid.

Start with SKILL.md and the matching guide under directing/, and load craft references only when they change a decision.

The optional diagnostics need Python 3, Pillow and FFmpeg:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install Pillow

python3 scripts/contact_sheet.py output.mp4 -o contact-sheet.png
python3 scripts/amateur_check.py output.mp4 --genre social-ad --project ./my-video
python3 scripts/measure_audio.py output.mp4 --script narration.txt
python3 scripts/derive_scene_timings.py words.json --anchors "The problem" "The result" -o timings.json
bash scripts/validate_project.sh ./my-video

The browser sampler is different: inject scripts/sample_layout.js into the loaded composition document rather than the Studio shell, choose in-duration times, and call collectDirectorObservations([0.1, 2, 4]). Save the JSON and pass it to amateur_check.py with --observations. Exit code 0 means no observed technical error within the checks that ran — the README is explicit that it does not certify taste, flash safety, complete pixel determinism or intelligible sound.

The review loop is the point

The README calls for at least two render and review passes, then revision of the highest-impact problems, and it warns against turning revision into an unbounded polish loop. It also insists on honesty in what was reviewed: if a run is constrained to one-shot or text-only work, the agent should disclose the omitted review instead of claiming it happened, and it should not treat a contact sheet as continuous playback or a technical pass as an aesthetic endorsement.

Evidence, not promises

The guidance records 71 research queries and links source IDs to their access and confidence levels. The diagnostic helpers received limited fixture and encoded-video checks, and the skill was used in informal local Qwen 27B generation runs that the README explicitly calls not a controlled benchmark. No win rate, quality improvement or diversity guarantee is claimed.

When to use it, when not to

Use it when a working pipeline keeps producing technically fine videos with no point of view, and when you want the agent to commit to one bold choice and one deliberate omission before it touches a composition.

Do not use it as a renderer, a generator or a replacement for the official HyperFrames skills — the README says it complements them. And do not use it as a certificate: a passing exit code is a measurement within a stated scope, not a statement that the video is good.

The repository is MIT-licensed. External assets, fonts, music and rendering software keep their own terms, and the skill does not clear generated video for commercial distribution.

Sources

1. HyperFrames Video Director — repository — 17 directing guides, workflow, rubric, diagnostic tools, evidence notes and limits quoted above.
2. README.md — quick start, example brief, script commands, license and attribution.

Project page: HyperFrames Video Director

For a longer video pipeline assembled end to end, see the ComfyUI film production pipeline.

FAQ

Does this repository render video? No. HyperFrames renders; the skill decides the concept, pacing, typography, motion and sound. It is not a hosted generation service either.

How many video types does it cover? Seventeen directing guides, from social ads and product launches to data visualization, lyric video, broadcast and meme shorts.

Does a passing check mean the video is good? No. Exit code 0 means no observed technical error within the checks performed; the README says the scripts do not certify taste or intelligibility.

Is there a numeric quality threshold? No. The README states there is no validated numeric threshold for professional quality; the rubric is for judgment, not a score to pass.