HyperFrames explainer videos
HyperFrames (npm hyperframes, pinned 0.8.137) renders an HTML page to MP4: it opens index.html in headless
Chrome, seeks the GSAP timeline registered as window.__timelines["main"] frame by frame and encodes with ffmpeg.
The starter project (assets/template/, copied to <project>/source/) is a complete 71 s film built from a reusable
kit: one paused GSAP 3.15 timeline whose every tween sits at a line time from the voice (KIT.L.p3.voiceAt,
KIT.cue(L.p4, 'the answer')), never a hard-coded second; a persistent graph in a tilted, drifting world; coloured
chapter light, a perspective floor, bokeh and grain; chapter stings, captions, question cards, a code panel, tables, a
complexity ladder and comic bursts. A new film replaces two files (scenes/subject.js, scenes/film.js).
scripts/render_hyperframes.mjs wraps the CLI for stills, layout checks, benchmarks and a segmented, resumable render.
Every skill in this family makes the same thing: a finished, narrated MP4 with a natural voice, music and effects baked in, built through a state machine that survives interruptions and refuses to deliver anything that has not passed its checks. Only the drawing and rendering steps are specific to HyperFrames.
$SKILL below means this skill's base directory (the folder this file is in). $S is $SKILL/scripts.
Non-negotiables (and why)
- A video is an MP4 with the voice in it. Not an interactive page, not slides, not a silent render with "add your own narration". A person once had to ask three times for a video and kept getting click-through pages. Extras (a page, a GIF) come after the MP4, never instead of it.
- Natural voice, always tried. Kokoro runs offline everywhere (
$S/voice.pyinstalls it). Never tell the person a voice, or any capability, is impossible until the alternatives are tried and recorded withvstate.py limit ... --tried ... --tried .... A person was once told TTS was impossible when it was not, and read it as being treated as less deserving. Say plainly which limits come from the environment. - The picture follows the voice. Voice first, then animate against
timing.json. Never stretch audio to fit. - Hit the quality bar on the first attempt (
references/quality-bar.md): one persistent subject, every line changes something on screen, eased motion with camera movement, depth and light, music and effects. A second attempt costs the person a day and their trust. - Look at your frames. The visuals and QA phases need a written attestation of what you looked at. Open the stills and the contact sheet with the Read tool; describe what you saw and what you fixed.
- For a coding problem, use the five-part format (
references/dsa-five-part-format.md): decode the problem and every example, brute force, intuition through timed questions, every approach with time and space, final C++ with a dry run. Compile and run the code before writing a word of script.
Start or resume
python3 $S/vstate.py --project <project> status # always first; prints the next command
New project (keep it on local disk, not a synced folder, while rendering):
mkdir -p <project> && cd <project>
python3 $S/vstate.py init --tool hyperframes --slug <short-name> --format dsa-5part # or --format general
After an interruption (crash, context reset, the 2-hour job cap), run status and continue from the phase it
names. Finished work is never redone unless its inputs changed; the gates detect that by hash.
references/state-machine.md explains every phase and gate.
Phase 1: brief
Ask the person only what you cannot reasonably default (topic, and anything that changes the goal). Default
the rest and say which defaults you picked. Write brief.md with these sections, then vstate.py advance:
- Topic, Audience, Format (dsa-5part or general; target length), Persistent subject (the one thing every chapter acts on), Style (a recipe from quality-bar.md with colours and fonts), Facts (for code: the solution, the compile command, the program's real output for every example), Output (resolution, fps, where to deliver).
$SKILL/assets/examples/lc787/brief.md is a complete example.
Phase 2: script
Write script.json (references/script-format.md): chapters, and per line an id, chapter, scene, cap
(on screen, symbols welcome) and say (spoken, words only), think pauses after questions, optional sfx.
vstate.py advance checks it. Example: $SKILL/assets/examples/lc787/script.json (40 lines, ~6 min).
Phase 3: voice
test -d source || cp -r $SKILL/assets/template source
(cd source && test -d node_modules || npm ci --no-audit --no-fund) # ~10 s; postinstall copies GSAP + fonts into vendor/
python3 $S/voice.py --project . --emit source/timing.js
python3 $S/vstate.py advance
Kokoro af_heart by default (meta.voice/meta.speed in the script; references/voice-and-audio.md lists
voices, including Hindi ones). Changing a say re-voices only that line. The emitted timing file is stamped
with a hash; the visuals gate checks your scene code reads the current one.
Phase 4: visuals
Write the film in source/scenes/subject.js (graph layout, camera shots, input text, the exact compiled code) and
source/scenes/film.js (choreography); the demo implements examples/mini line by line and is the pattern to copy.
Keep source/kit/; change the look in source/kit/tokens.js, or pick a registry theme (source/theme.js, guide section "Themes"). The guide (references/hyperframes-guide.md) has the
timing API, the kit catalogue and recipes (decode an input, trace a route, reject a route, think countdown, DP row
update, code walkthrough, camera moves).
- Plan first: for every line id, what changes on screen and where the camera looks. The graph stays in the world the whole film; panels come and go around it (move the camera to make room instead of hiding the subject).
- Place every tween at a line time (
L.<id>.voiceAt,.voiceEnd,.thinkEnd,K.cue(L.<id>, 'phrase'),K.chapter(n).start), onKIT.tl, entrances with the kit helpers (they set the hidden state at build time). - Lint, then shoot one still per line (about 1.5 s each; the folder is cleared first,
stills/sheet.jpgis a contact sheet), then the event moments you care about (bursts, stamps, arrows) with--keep:
node $S/render_hyperframes.mjs --project . --lint
node $S/render_hyperframes.mjs --project . --stills lines
node $S/render_hyperframes.mjs --project . --stills 16.4,38.3,48.4 --keep
- Run the layout check (lint + JS errors + overlapping text, text under a panel, overflow, text in the caption band, contrast, sampled at every line; about 2 minutes for 14 lines on an idle machine, run it in the background on a long film):
node $S/render_hyperframes.mjs --project . --check
Each finding names the time, the line id and the element. Open that line's still, fix real overlaps (move a tag to
another side, change the shot), and mark a deliberate one on the text element with data-layout-allow-overlap.
It does not replace looking: it found a tag hidden under the input panel that a contact-sheet glance missed.
5. Preview motion when timing matters: node $S/render_hyperframes.mjs --project . --range 30,36 writes a draft
build/preview.mp4 of that range in about 30 s.
Then open every still (Read the PNGs). Check each against references/quality-bar.md ("The review pass"): text
inside the safe area, nothing overlapping or cut off, code glyphs correct, the frame shows what its line says,
and it would sit comfortably next to the reference films. Then measure every text in the stills:
python3 $S/legibility.py --project . # size and contrast of every text; marked copies in stills/legibility/
It fails any text under 26 px or under 4.5:1 contrast, at every size, with no 3:1 large-text exception; the visuals gate needs 0 failing texts. Fix and re-render stills until both the review and the measurement pass, then:
python3 $S/vstate.py attest visuals "Looked at N stills: <what you checked, what you fixed>"
python3 $S/vstate.py advance
Phase 5: render
Benchmark first (renders 6 s from the middle, prints frames/s and the ETA for the whole film), then render in the
background and poll. Segments of 20 s are rendered one hyperframes render call each, recorded in
build/segments/manifest.json, and joined into build/silent.mp4 (H.264, yuv420p, exactly TIMING.total). Use
--workers 2 on a shared 4-CPU machine, 4 or more on a laptop.
node $S/render_hyperframes.mjs --project . --bench 6
mkdir -p build && nohup node $S/render_hyperframes.mjs --project . --workers 2 --max-minutes 100 > build/render.log 2>&1 &
tail -n 3 build/render.log # poll until it prints "wrote .../build/silent.mp4"
If it stops at the budget (exit 3, "stopped at the 100-minute budget") or the job is killed, run the same command
again: finished segments are skipped. A change to the source, the timing or the settings starts the segments over
(--force does it on purpose). Measured here with 2 workers at -q high: about 4 frames/s on a quiet 4-CPU machine
(8 minutes per minute of film) and 1.7 frames/s when eight jobs shared it (the smoke film's earlier 62 s cut took 18.5 minutes), so
budget up to an hour per 3 minutes of film here and trust the --bench ETA.
python3 $S/vstate.py advance # checks codec, size, fps, duration against the voice timing, segments
Phase 6: mix
python3 $S/music.py --project . # --mood calm|piano|pulse|none (default: script meta.music)
python3 $S/mix.py --project . # voice + ducked music + effects, loudness -16 LUFS, yuv420p
python3 $S/vstate.py advance
Phase 7: QA
python3 $S/qa.py --project .
It checks format, duration, loudness, voice sync for every line, black frames, frozen shots and single-frame
flicker, and writes qa/report.md, qa/contact-sheet.png and qa/stills/. Open the contact sheet and the
stills. If anything is wrong, vstate.py reopen visuals --reason "...", fix, and come back through render and
mix. When it is right:
python3 $S/vstate.py attest qa "Contact sheet and N stills: <what you saw>; report: <pass/warnings>"
python3 $S/vstate.py advance
Phase 8: deliver
python3 $S/vstate.py notes-md > NOTES.md # fill every (fill in): tool versions, style, re-render commands
python3 $S/package.py --project . --to <deliver folder> # a new or empty folder; it never empties one it did not make
python3 $S/vstate.py advance
python3 $S/vstate.py report # use this for the final message
The final message leads with the video (attach or link the MP4), then in a few lines: length, voice used, the
style, any limit and which part of it came from the environment, any warning, and that edge_voice_swap.py
re-voices it on a laptop (for example with en-IN-NeerjaNeural). Do not claim anything the report does not show.
HyperFrames gotchas
- Keep the inline registration block in
index.html. Lint (gsap_timeline_not_registered) wantswindow.__timelines["main"] = ...in the same inline script that callsgsap.timeline, and segment rendering depends on itssegFrom/segTowrapper. - No static
data-durationon#rootor the layers. It fixes the composition length, so a 20 s segment would render the whole film. The inline script stampsdata-start/data-durationfrom the range; lint and render accept it. - No
../in asset paths (lintinvalid_parent_traversal_in_asset_path); everything the page loads lives undersource/(vendor/is generated bysetup.mjs). - Fonts are local. Google Fonts is blocked:
@fontsourceInter, JetBrains Mono and Bangers woff2 are copied intovendor/fonts/withfont-display: block. The kit never measures text at build time, so layout does not depend on when fonts arrive. JetBrains Mono ligatures are off (!=,<=,++stay as typed): keep code in.mono. - GSAP plugins are free since 3.13 and ship in the plain
gsapnpm package (DrawSVG, MotionPath, SplitText, Text, CustomEase);kit/core.jsregisters them. Ignore advice about Club plugins or private registries. - Seek-safe only. Every motion goes on
KIT.tlat an absolute time; no CSS animations,requestAnimationFrame,Date.now()orMath.random()(K.rand(seed)); values change throughK.stack(...).to(t, html)orK.count, never throughonUpdatewrites. Each segment starts from a fresh page seeked to its first frame. - Expensive paint halves the speed. A CSS 3D plane with an animated background cost about half the render time;
the floor is now a canvas drawn per frame. Avoid
backdrop-filterand full-frame blur filters. - Unknown line ids throw (
KIT.L.x9: no line "x9") andK.cuethrows when the phrase is not insay; the error lists what exists. That is deliberate: a silentNaNtime would drop a whole beat.
References
| File | Read when |
|---|---|
references/hyperframes-guide.md |
Building scenes and rendering with HyperFrames: setup, component catalogue, timing API, recipes |
references/quality-bar.md |
Before designing the style, and at every review |
references/dsa-five-part-format.md |
Any coding-problem explainer |
references/script-format.md |
Writing script.json; reading timing in scene code |
references/voice-and-audio.md |
Voices, languages, music moods, mix levels, blocked TTS |
references/state-machine.md |
Gates, resume, reopening a phase, long renders |
references/environment.md |
Paths, fonts, render speeds, the 2-hour cap, laptop differences |
references/lessons-learned.md |
Once per project: why each rule exists |