GSAP explainer videos
One HTML page (DOM + SVG, plus one small background canvas) is animated by a single paused GSAP 3.15 timeline.
Every tween sits at a line's time from the voice (L.p3.voiceAt, L.p3.at('each flight')), never at a
hard-coded second, and the timeline is padded to exactly TIMING.total. window.renderFrame(t) seeks the
timeline, so capture.mjs can draw any frame on any worker and screenshot it into an MP4. The starter film
(assets/template/) is a complete 71 s explainer built from a reusable kit: a persistent graph in a world that
the camera frames, an input decoder whose values fly into the graph, chapter slabs and a lower third, question
cards, comic bursts and stamps, a code panel, a dry-run table, a complexity ladder and a result card. GSAP, its
plugins and the fonts are vendored from npm into source/vendor/, so nothing loads from a CDN at render time.
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 GSAP.
$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 gsap --slug <short-name> --format dsa-5part # or --format general
python3 $S/vstate.py set min_minutes=3 max_minutes=4 # only if the person asked for a length (default 2 to 8)
init uses the current folder as the project; every later command takes --project <project> or runs there.
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
cp -r $SKILL/assets/template source && (cd source && npm ci --no-audit --no-fund && npm run vendor) # ~5 s
python3 $S/voice.py --project . --emit source/timing.js
python3 $S/vstate.py advance
npm ci installs the pinned GSAP, fonts and playwright-core (no browser download); npm run vendor copies GSAP,
its plugins and the woff2 fonts into source/vendor/, which is what the page loads. 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 source/timing.js 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.js; the demo there implements examples/mini line by line and is the
pattern to copy. Keep the kit (source/kit/) and change the look in source/tokens.js. If the brief names a theme
(references/themes.md), emit it with python3 $S/theme.py emit <id> --format global --out source/theme.js
(gsap-guide.md section 9 has the role mapping). The guide
(references/gsap-guide.md) has the kit catalogue and recipes (decode an input, trace a route, reject a route,
think countdown, DP row update, code walkthrough, camera moves, monotonic stack).
- Plan on paper first: for every line id, what changes on screen and where the camera looks. One persistent
subject stays in the world for the whole film; panels come and go around it. The kit has two subjects:
K.graph(graphs, routes) andK.barRow+K.stackCol(arrays, monotonic stacks, two pointers). For any other shape (grid, tree, linked list, intervals), write a new component insource/kit/<name>.jsin the same style (world-space SVG inK.layer.*, every change aK.toat a line time,K.channelfor values that change often), load it with a<script>tag afterkit/array.js, and add its classes tostyles.css. Budget for this: the LC 739 test film's array subject was about 350 lines, the most work in the film. Lay the subject out for the busiest chapter first (it must share the frame with the ladder or the code panel), then check the others. - Place every tween at a line time:
L.<id>.voiceAt,.at('phrase'),.p(0.5),.vEnd,.end. Use the kit (K.to/K.fromTo/K.set, never rawgsap.to), so tween fights are detected. - Preview while you work (optional): from the project folder run
python3 -m http.server 8765 --bind 127.0.0.1, openhttp://127.0.0.1:8765/source/index.html(space plays with the narration, arrow keys step one frame, shift+arrow 5 s,?t=40opens at 40 s). Stop the server when done. - Lint until it prints
okwith no warning you have not judged:
node $S/gsap_check.mjs --page source/index.html
It fails on page errors, a missing font or file, or a broken build; it warns on overlapping tweens (the
flicker cause), a timeline longer than the voice, and, at every line and every comic burst or stamp, text
off-frame or outside the 96 px safe area, text in the caption band, world text the camera shrinks below
26 px, and blocks overlapping; and at every chapter card, anything in screen space (panels, notes, bursts,
the caption, the lower third) visible under the slab. Then legibility.py (below) measures every text in
the stills: 26 px and 4.5:1 at least.
5. Shoot stills (one per chapter and one per line, JPEG, about 30 s for the demo):
node $S/capture.mjs --page source/index.html --prime 0.25 --stills chapters --timing timing.json --stills-dir stills
node $S/capture.mjs --page source/index.html --prime 0.25 --stills lines --timing timing.json --stills-dir stills
Add exact times for every burst and busy moment: gsap_check prints the burst and stamp times as a ready
list (bursts/stamps at full size (for capture.mjs --stills): 34.33,37.60,...); pass it as
--stills 34.33,37.60,... --stills-dir stills (line stills are taken 65% into each line and can miss a
burst that lives for one second).
Then open every still (Read the images). 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
node $S/capture.mjs --page source/index.html --prime 0.25 --bench 3 # fps per worker and the film's ETA
mkdir -p build
node $S/capture.mjs --page source/index.html --out build/silent.mp4 --prime 0.25 --workers 4 --max-minutes 100 > build/render.log 2>&1
Run the render in the background (it takes longer than a tool call) and poll tail -n 3 build/render.log.
Use --workers 2 --segment 10 on a machine shared with other jobs (smaller segments lose less if the job is
killed). Speed measured here (4 CPUs, no GPU): --bench gave about 7 frames/s per
worker on a nearly idle machine and 3-5 under heavy load; with eight other renders sharing it, the demo's earlier 62 s cut
(1867 frames) rendered with 2 workers in 4.7-6.2 minutes (6.6-5.2 frames/s at load averages 20-36). A 6-minute
film with 4 workers on a quiet machine needs roughly 10-20 minutes. The render is
split into 20 s segments in build/segments/; exit code 3 means the --max-minutes budget ran out: run the
same command again and only unfinished segments are drawn. Editing anything in source/ invalidates the
segments (the page is stamped), so finish the visuals first. Done when the log says wrote build/silent.mp4.
Check its bit rate (ffprobe -v error -show_entries format=bit_rate -of default=nw=1 build/silent.mp4): the
demo is 3-5 Mbit/s; tens of Mbit/s means something noisy changes every frame (see the gotchas).
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, and grab the frame at each comic burst from the final MP4 (ffmpeg -ss <t> -i out/<slug>.mp4 -frames:v 1 burst.jpg): the sheet samples every couple of seconds and misses a burst that lives for one. 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.
GSAP gotchas
- Single-frame flicker comes from two tweens on the same element and property whose time ranges overlap
(the frame then depends on seek order), and from
from()/fromTo()tweens that render their start state at build time. The kit'sK.fromTosetsimmediateRender: false,K.initsets the pre-film state, andgsap_check.mjslists every overlap. Render with--prime 0.25so each worker plays up to its segment the way a viewer would. - Never read the clock. No
Date.now(),requestAnimationFrameor CSS animations/transitions: anything that moves must be a tween onK.tlor a pure function oftregistered withK.everyFrame(fn). - Fonts: the page waits for
document.fonts.load(...)before building, because text widths are measured. JetBrains Mono needs ligatures off (font-feature-settings: "calt" 0, "liga" 0, already in.mono), or!=,->,<=turn into single glyphs. Google Fonts are blocked here; the woff2 files come from npm. - SVG filters (blur, drop-shadow) are slow in a screenshot capture and some blur differently per frame. Glow and depth come from radial gradients, stacked strokes and one half-resolution background canvas.
- Animated grain or noise bloats the file. Re-randomising grain every frame made the MP4 7x bigger (37
vs 5 Mbit/s); the template keeps its grain still (that also
halved render time). Check
ffprobeon the render: a film like the demo should be a few Mbit/s. - Full-screen layers cost time. Every full-screen DOM layer (grain, vignette, light) is composited for every frame: those layers cost about 75 ms a frame here. The template draws all atmosphere into one half-resolution canvas instead (about 25 ms).
- A phrase that is not in the line's
saymakesL.x.at('...')throw with the line's text, and an unknown line id throws listing the real ids: after editingsay, re-voice before fixing the scenes. - Numbers in display fonts: Bangers' 7 reads as a 1 and it has capitals only, so
K.calloutsets digits and lowercase letters in Inter Black (write comic words in CAPITALS); keep any number that matters in Inter or JetBrains Mono. - Text in world space shrinks with the camera. The graph's weights and SRC/DST flags are 36 px and its
badges 32 px in world space: keep the camera scale at 0.8 or more (they land at 26-29 px) by giving the
subject a big enough screen box, and narrow the panel beside it rather than shrinking the graph.
gsap_checkwarns below 26 px;legibility.pyfails it. - Chapter cards cover the left 900 px from
K.cardIn(n)(about 0.8 s before the chapter) toK.cardClear(n)(about 0.56 s into it). Hide the last chapter's left-side panels so they are gone byK.cardIn(n)and bring the new chapter's in atK.cardClear(n)or later; question cards and the first caption wait by themselves. The graph too: when it stands in the left half at a chapter change, fade it out before the card and back in after it (G.fade(K.cardIn(n) - 0.35, 0, 0.3); G.fade(K.cardClear(n), 1, 0.45)) and reframe the camera while it is hidden. In the LC 739 test film the chapter 4 card swept out over the ladder that chapter was already building and over its first caption. - Dimmed text must stay readable. Code lines outside the focus dim to opacity 0.75 (still at least 4.5:1) and question words not yet spoken to 0.5: mark the focus with the bar, colour or weight, never by making the rest near-invisible. Something still fading in when a still is taken is a timing problem: land it earlier.
- GSAP version: 3.13+ made every plugin free (DrawSVG, MotionPath, MorphSVG, SplitText); the template pins
3.15.0 and vendors it. Do not swap in a CDN
<script>: renders must work offline.
References
| File | Read when |
|---|---|
references/gsap-guide.md |
Building scenes and rendering with GSAP: 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 |