Video Beat Board¶
Portability: one stdlib script. Input is JSON you can write by hand.
Scripts for short video fail on arithmetic, not ideas: 60 words of narration do not fit in 15 seconds, and a headline that leaves after one second was never read. Write the beats; let the tool do the clock.
Workflow¶
- Get a READY brief from
video-director(brief_gate.py). It carriesduration_s,aspect,laneandvo_word_budget. - Write
beats.json: one object per beat.
[{"vo": "Your release notes are a wall of text.", "on_screen": "Release notes nobody reads",
"visual": "dense changelog scrolling", "kind": "motion"},
{"vo": "Teams save over an hour per release.", "stat": {"to": 68, "suffix": " min"},
"on_screen": "saved per release", "kind": "motion"},
{"vo": "Version two turns them into a brief.", "visual": "engineer at a desk at night, laptop glow",
"kind": "upgrade"}]
kind: "upgrade" marks a candidate for generated footage; visual becomes
its plate prompt. Data beats take stat, chart ({"kind":"bar","data":[[label,value]]})
or csv.
3. Time it:
python3 ${CLAUDE_PLUGIN_ROOT}/skills/video-beat-board/scripts/beat_board.py \
--brief film/brief.json --beats film/beats.json --out film/scene.json
- FITS (exit 0):
scene.jsonis a greybox animatic; hand it tovideo-animatic. - DOES-NOT-FIT (exit 4): cut the number of words it names, or drop a beat. Do not raise the length unless the user agrees: the length came from the brief.
- A stretch above 1.6x is a warning that the film will drag: add a beat or shorten the brief.
Rules of thumb the tool encodes¶
| Rule | Value | Why |
|---|---|---|
| Narration pace | 150 wpm (2.5 words/s) | Clear read with breathing room |
| On-screen reading | 0.5 s + words ÷ 3 per s | Top of the 160-180 wpm subtitle guidance |
| Shortest shot | 1.5 s | Below that a beat registers as a flash |
| Stat or chart beat | +1.6 s | The number has to land after it animates |
Forcing questions¶
- What is the one line the viewer must remember? Recommended: make it the on-screen text of the strongest beat.
- Which beat can go? Recommended: the one that restates the previous beat.
- Which single shot would gain most from real footage? Recommended: one emotional or physical moment; keep data and text as motion graphics.
See beat_timing.md for the sources behind the numbers.