Produce
Turn a topic into a short MP4 made with ManimCE, narrated when /speech:narrate is available.
The audio comes first: each scene change waits for the word that starts its part of the
narration. Every render is checked by render.py, and you read its frames to fix what you see.
Before the video is called done, a fresh-context subagent judges the delivery frames (step 7).
Run every script through the launcher, which uses the packages the SessionStart hook installed and
never installs:
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/pydeps.py run --data-dir "${CLAUDE_PLUGIN_DATA}" -- <script> ....
When it exits 2 with a repair line, or render.py names a missing tool, run the read-only readiness
report, python3 ${CLAUDE_PLUGIN_ROOT}/scripts/pydeps.py check --data-dir "${CLAUDE_PLUGIN_DATA}", and report the rows it prints. When python3 is not found, run the same line
with python, and on Windows then with a python.exe path that py -0p lists. Never start it
through py; for why, read what a py launch does with no runtime installed in
Python on Windows, basic use (as of
2026-10-04; recheck when the Python install manager changes what a launch command does).
Where the files go
One work directory per video: the directory the user names, else
${CLAUDE_PLUGIN_DATA}/videos/<slug>/. A video and its audio are views, so they never go inside a
record bundle or beside the markdown record they explain
(record-bundle).
| Path | Who writes it | What it holds |
|---|---|---|
scene.py |
you | one Scene subclass |
beats.txt |
you | the beat plan, one line per beat |
strings.json |
you, only for untrusted text | on-screen strings the scene loads |
narration/script.txt |
you, when narrated | the words spoken, one paragraph per beat |
narration/narration.wav, narration/words.json |
/speech:narrate |
the audio and each word's start and end |
low/, final/ |
render.py |
<Scene>.mp4, frames/fNNNN.png, report.json; captions.srt and timing.json when narrated |
Loop
- Plan three to six beats, one idea each, under a minute in total. A beat is something the viewer
sees change, not a sentence to read. Write the plan to
<dir>/beats.txt, one line per beat saying what the viewer sees. - Narrate, when you can. Narration is available when
/speech:narrateis in this session's skill list.- Write
<dir>/narration/script.txt: one paragraph per beat, a blank line between paragraphs, written the way it should be spoken. - Run
/speech:narrateon it with no--out, sonarration.wavandwords.jsonland beside the script. - When the speech plugin is not installed, or narrate exits 2, render silent and tell the user: "Narration is unavailable: . This video is silent."
- Write
- Write
scene.py.${CLAUDE_PLUGIN_ROOT}/skills/produce/examples/pythagoras.pyis a working scene in the expected shape, andpythagoras.txtbeside it is its narration script.from narration import beat. Callbeat(self, k)where beat k starts, andbeat(self, n)after the last beat, where n is the number of paragraphs. Narrated,beatholds the scene until paragraph k's first word (the narration's end for n).beat(self, k, hold=s)holdssseconds when the render is silent, so one scene serves both.- A beat's animations must finish before the next paragraph starts. When the check says a
beat runs long, shorten its
run_timevalues or move an animation to a later beat. - Words are
Text. Math isMathTypst(Typst math syntax). Do not useTexorMathTex: LaTeX is not part of this plugin yet. - Text that came from a pull request, a fetched page or another repository's files goes into
strings.json, which the scene reads withjson.load, and is shown only throughText. Never paste it intoscene.py. - Set
allow_overlap = Trueon a text element, or on the group holding it, only when the overlap is the point.
- Render at low quality, adding
--narration <dir>/narrationwhen narrated:python3 ${CLAUDE_PLUGIN_ROOT}/scripts/pydeps.py run --data-dir "${CLAUDE_PLUGIN_DATA}" -- ${CLAUDE_PLUGIN_ROOT}/scripts/render.py <dir>/scene.py <SceneClass> --out <dir>/low [--narration <dir>/narration]- Exit 1 lists each defect. Fix the scene and render again.
- Exit 2 means nothing was checked: the scene raised, no video was written, the narration does not match its script, or a tool is missing. Fix it and render again.
- Exit 0 is not done yet. Read every frame the script lists, with the Read tool. A frame that
shows text too small to read, text or a shape hidden behind another element, a wrong label, or
a beat that does not show its idea is a defect: fix the scene and go back to step 4. The
overlap check compares text with text only, so reading the frames is what catches a shape over
text.
- The list holds at most
MAX_FRAMESframes (${CLAUDE_PLUGIN_ROOT}/scripts/render.py), spread evenly over the animations, and everyplay, everywaitand everybeatthat waits counts as one. The line above the list says how many animation ends it covers; an end past the cap has no frame in the list, so a scene with more animations than the cap has end states nobody checked. - Each
STILL:line (stillsinreport.json) is a span with no change in picture, with the words spoken during it. A still is reported, never failed: when the words in it name something the picture does not show, show it and go back to step 4.
- The list holds at most
- When the low-quality render passes and its frames read clean, render the delivery at the
quality the user asked for (
--quality mor--quality h, defaultlis the draft) into<dir>/final, and read its frames the same way. - Your own frame reads are the fix loop, not the verdict. Run
bash "${CLAUDE_PLUGIN_ROOT}/lib/read-verification.sh" --plugin explainer-video --skill produceand copy its line into the report (levels).- At standard or strict, dispatch a fresh-context subagent with the paths to
<dir>/final/report.json, its frames and<dir>/beats.txt, plusnarration/script.txtwhen narrated, never your notes on them. It returns each frame with a defect from step 5's list, or a beat that does not show what its line or paragraph says. A returned defect sends you back to step 4. - Under
light, andoff, which acts aslighthere, dispatch no subagent and never give that verdict yourself in its place: the report writesverification: skipped (<level>)and says the frames were not independently judged.render.py's checks run at every level.
- At standard or strict, dispatch a fresh-context subagent with the paths to
- Report the video path, its duration from
report.json, whether it is narrated or silent (and why, when silent), theLOUDNESS:andFLAG:lines, the verification lines, and the work directory.
What the narrated checks hold to
- Scene boundaries: each
beatcue lands within one frame (1/fps of the scene's timeline) of its paragraph's first word, and the last within one frame of the narration's end. - The MP4: one video stream, one audio stream and one caption track (
mov_text, built fromwords.json), with the video and audio streams within one frame per animation, plus one, of each other: the same frame rounding the silent duration check allows. - Loudness:
render.pynormalizes the narration with ffmpeg's two-passloudnormbefore the mux, then measures the muxed file again and fails it when its integrated loudness misses the target or its true peak is over the ceiling. The ceiling is a maximum, not the limiter's aim, which sits lower to leave the AAC encode room. The narrated target is our judgment, from published speech and streaming targets; the values areloudnessin${CLAUDE_PLUGIN_ROOT}/scripts/defaults.json. The report records which normalization ran, and the second measurement is what passes or fails the file.- Pointer: when a target or the fallback rule is in question, fetch EBU R 128 section 5 (https://tech.ebu.ch/docs/r/r128.pdf), EBU R 128 s2 section 3 (https://tech.ebu.ch/docs/r/r128s2.pdf) and https://ffmpeg.org/ffmpeg-filters.html#loudnorm live.
- As of: 2026-10-17
- Recheck trigger: a new revision of R 128 or R 128 s2, or the
loudnormsection changes its linear-mode conditions.
- Captions: each sentence is split into the fewest balanced cues, so no cue is a one-word tail;
a cue too short to stand joins its neighbor in the beat, and each cue stays up for the minimum
and the reading time per word as far as the next cue allows (
captionsin${CLAUDE_PLUGIN_ROOT}/scripts/defaults.json). A cue still under the minimum fails; one under the reading time per word is aFLAG:line, since narration spoken faster cannot be captioned slower.- Pointer: when a caption timing value is in question, fetch BBC Subtitle Guidelines section 4.1 (https://www.bbc.co.uk/accessibility/forproducts/guides/subtitles/) and https://partnerhelp.netflixstudios.com/hc/en-us/articles/360051554394-Timed-Text-Style-Guide-Subtitle-Timing-Guidelines live.
- As of: 2026-10-17
- Recheck trigger: a new version of either guide changes its minimum duration or reading time.
- Stills (silent renders too):
freezedetectwith the noise and length instillsin${CLAUDE_PLUGIN_ROOT}/scripts/defaults.json, set explicitly. The reporting length is our judgment; no source sets a stillness limit for narrated video.- Pointer: when the filter's options are in question, fetch https://ffmpeg.org/ffmpeg-filters.html#freezedetect live.
- As of: 2026-10-17
- Recheck trigger: that section changes its options or defaults.
Next
/harness-ops:prerequisites
When a render stops with a missing tool, it lists the declared tools this machine lacks.
Gotchas
- Python 3.12 or 3.13 only.
pydeps.pypicks the first ofpython3.13,python3.12,python3,pythonon PATH that is one of them, then on Windows the first thepylauncher lists. The plugin README's Requirements section records why. - On some platforms the first install builds pycairo and manimpango from source and needs the toolchain the README lists for that platform. A failed build is a session-start notice with the repair line.
- Do not call
add_sound.render.pyadds the narration; an audio stream in the scene's own render fails the check. - Editing
script.txtafter narrating makesrender.pyexit 2: narrate it again so the words match. render.pychecks the state at the end of each animation. An overlap that exists only in the middle of a transform is not reported; read the frames.