05 · Section Videos

← Docs home · Task: build a narrated, multi-scene section-opener video and embed it at the top of a section.

Source of truth: section-video-pipeline, plus manim / manim-textbook for scene patterns and manim-variant-runner / tts-bake-off for voices. Scenes live in manim-videos/<video-dir>/.

This is distinct from figure animations: section videos are voice-narrated, multi-scene explainers (Manim + TTS), not silent figure loops.

Editorial rule (memory): section-opener videos must name nothing — no terminal vocabulary, formulas, or panel labels. Naming belongs to a separate, paired reveal video.

Procedure

1. Write captions — edit the video’s captions.py, defining the ALL_CAPTIONS list (the narration script, scene by scene).
2. Pregen the voice cache — run the matching pregen_<backend>_cache.py to synthesize and hash-cache the narration MP3s:
   • Orpheus — local GPU venv.
   • CosyVoice 2 — local GPU venv.
   • Fish Audio — cloud REST; API key in <video-dir>/.fish_api_key; ~$0.50– $1.00 per full pregen.
3. Write the scene classes — author script.py as a VoiceoverScene, using manim-voiceover context managers that pull from the pre-generated cache.
4. Render & mux — run ./run.sh from the video dir (orchestrates pregen → Docker build → Docker render → mux audio).
5. Register the manifest — add an entry to projects/<Book>/section_videos.yaml (video_dir, variants, voice backend, docker_image, cache_buster).
6. Embed in the section HTML — add the <video> element at the target anchor in docs/<book>/<chapter>/<section>.html, with the ?v=<cache_buster> query.

Output

manim-videos/<video-dir>/final/<variant>.mp4, embedded in the published section page.

Staleness model (what triggers a re-build)

Two-stage, validated by preflight:

• captions.py changed → re-run the TTS pregen (cache is stale).
• MP3 cache changed → re-render the final MP4.

So edit captions → re-pregen → re-render → re-mux. Touch only the stage whose input changed.

Related skills

• manim-variant-runner — add another TTS voice variant to an existing script-driven video (cache pregen + render_variant_*.py service-swap pattern).
• tts-bake-off — evaluate / swap TTS backends; hash-keyed MP3 cache wiring.
• section-video-pipeline — the end-to-end orchestrator skill (captions → TTS → render → mux → manifest register).

For the longer narrated figure (single-scene) variant and the silent ping-pong loops, go back to 04 · Figures & Animations.