Give it a finished cut, its word timings, its cut times and the visual events to react
to; get back the cut with titles that sit in the set and react to it, rendered frame-exact
by hn4a-compositor. The effects are layers and keyframes in the ordinary compose spec
(hn4a-compositor has the format, the command line, the live-spec gate and --into
revisions); a small helper module writes them from cues so a build script stays a list
of calls. For overlay layouts beside the footage (slides, lists, a presenter
bubble), use hn4a-compositor-motion-graphics alone.
Inputs
- The cut, and its speech-to-text (
elevenlabs-speech-to-text, read withpython-read-word-timings) for word cues. - Its shot boundaries at the finished-cut threshold (
ffmpeg-scene-cuts, Which threshold for which job), so dissolves are found too. - Visual events (a face tearing, a phone picked up, a screen glitching) from a 2 fps contact sheet of the shot, then frame-stepped in the preview.
- A cutout for every shot where type goes behind people (
birefnet-matte, snapped to that shot's cut times). - The brand's fonts and colours (here Brand Sans and Globex Lime #B8E62E).
Run it
- Write
references/titles-fx.md's module into the job'sscripts/astitles_fx.py, as is. - Write
scripts/build_titles.pybeside it: the cues as constants, then the layers bottom first (the cut, then the type, then the cutout over the same span), dumped as JSON.references/worked-example.mdis a complete one. - Build and look:
exec python scripts/build_titles.py --out titles/quiz_titles.json
exec hn4a-compositor page titles/quiz_titles.json
exec hn4a-compositor still titles/quiz_titles.json titles/s_3.20.png --at 3.2
exec hn4a-compositor render titles/quiz_titles.json
(cwd the job folder.) Make a still at every effect, nudge boxes in the build script
and rebuild. Then the live spec (hn4a-compositor, Live spec, then render) with the
stills at every effect; only then render. A real job's script was a list of calls
writing 81 layers; it rendered at 52 fps.
The effects
- Type behind people. The cut, then the type, then
cutout(src, start, end): the people and the furniture in front of the back wall cover the type. BiRefNet "General Use (Heavy)" keeps the podium and the chair, which is right when the type sits on the back wall. Place the type so a head or shoulder covers one letter or part of one, never a whole word: check the still and nudge the box. - One layout, many layers (
line_html(parts, show)). Every layer carries the whole line in the same box, with the other wordsvisibility:hidden, so the words line up exactly while each animates on its own. SettransformOriginper layer to that word's centre. Words land on their cue withpop_keys, or pulse on beats withpulse_keysplus aspill(light on the set, under the cutout) driven byflash_keys. - Glitch (
glitchplushidden_duringon the clean copy): three clip-path bands, each with a random x offset every frame onholdkeys, plus red and cyan copies (screen blend) during each (start, duration) burst. Time the bursts to the picture's own glitch. - Typing (
typing): one layer per prefix with uneven keystrokes, a solid caret while typing, then a blinking caret until the end. Pass the caret colour. - Ring (
ring_keyson x, or on rotate withscale=0.25), drop (drop_keys, a receiver put down), focus pull (focus_keys, sharp on the word), a screen powering on (flicker_keysplusscan_bar). - Type on a surface at an angle: a wall seen from the side, a floor, a tabletop, a
title that recedes into the set. Lay the type flat in a plane group pinned to the
surface's corners (
hn4a-compositor-perspective-planes), with the cutout over it as above; keyed per frame when the camera moves. The helpers here draw upright type, right only on a wall that faces the camera square-on. - Floor reflection (
reflection(layer, floor_y)): the layer mirrored about where the wall meets a glossy floor, blurred and fading away from the wall. If the reflection lands off-frame, lower the type on the wall. It mirrors about a level line, so it suits a square-on wall. On an angled wall, extend the wall's plane group below its floor edge and put the mirrored copy there, about that edge, inside the group: a wall's reflection in the floor lies in the wall's own plane. - Captions (
captions(words, box, mode=)on the STT words), three modes:karaoke(each phrase builds word by word, the spoken word on apillthat bounces; two layers a word),calm(each word rises in as it is said, no pill; one layer a word) andchunks(2–3 words at a time for a split-screen seam). Every word layer carries the whole phrase, so the words never shift. Pass the brand colour aspill;emphasisstyles chosen words,strokeoutlines them,upperandshownfix what a transcript spells,skipleaves out spans where a full-screen title says the same words, anddirection="rtl"builds Hebrew or Arabic phrases right to left. Which mode, and the sizes and phrase lengths that worked:guide-caption-a-video. - A camera (
camera(id, start, moves)): agrouplayer whose children (parent: id) zoom and pan as one, such as a product screen rebuilt as layers. Each move puts a point of the screen at the frame centre at a scale.hn4a-compositor(references/spec-format.md, A camera over a group) has the mechanics; the pace ishn4a-compositor-fast-ad-camera(ads) orhn4a-compositor-calm-explainer-camera(explainers).within=keeps every framing inside the screen's box.
Tips and traps
- Your own
animreplaces the preset (hn4a-compositor):hidden_during(..., end_at=)writes the whole curve, fades included. - Mirrors and glow: a reflection's
scaleY(-1)goes on an inner div of the html, and glow istext-shadow, because the runtime owns each layer'stransformandfilter. - Name the font on the layer:
text_layer(..., font=)sets the family the runtime checks. - Cutouts are per shot. A cutout's frame k is comp frame start × fps + k, so give it the
same start as its shot and
trim0. - Pass the brand colour everywhere it shows (caret, spill, scan bar); the helpers default to white.
Check it
- Stills at every cue, effect and cut, looked at: no whole word hidden by a head, the reflection in frame, the glitch only during the picture's glitch.
- Play the preview through at full speed once; then render and run the checks in
hn4a-compositor.


