Research Method Video

research-method-video

A sub-capability of weekly-research-slides. It turns a method semantic model into a concise visual explainer rendered with Manim Community Edition.

Primary use case:

researcher reads a paper
    -> method semantic model
    -> concise visual explainer
    -> play the clip in a lab meeting, or reuse frames in PowerPoint

The video is a silent visual explanation (the researcher narrates live). It is not an animated slide deck, a zooming paper figure, or a narrated slideshow.

Core rule: transform objects, not slides

Never do FadeOut(scene); FadeIn(scene) when the same scientific object continues. Maintain object identity and move/morph it:

a feature appears -> moves through the model -> is cached -> goes stale
-> a predictor appears next to it -> the predicted feature moves to the next step

Use Transform, ReplacementTransform, TransformMatchingShapes, TransformFromCopy, MoveToTarget, animate.shift/move_to/scale over repeated fade-out/fade-in.

Workflow

1. Understand the method. Read the actual paper/notes with your document tools. Do not build a PDF parser. Write method_model.yaml (schema in schemas/method_model.schema.json): problem, baseline, key observation, assumption/failure of previous methods, motivation, mechanism, components, equations, training, inference, claims, assumptions, limitations, relation_to_our_work. This model is shared with the slide pipeline.

2. Storyboard before code. Write storyboard.md: for each scene give the scientific purpose, the question answered, actors, start state, animation beats, end state, speaker intent, and transition. Pick only the stages the method needs (problem -> why previous fails -> key observation -> new idea -> mechanism -> why it works -> assumption/weakness). Do not follow paper section order.

3. Scene spec + narration. Write scene_spec.yaml (schema in schemas/scene_spec.schema.json): scenes, persistent actors with stable ids, explanation beats with a motion pattern, start/end state, and one keyframe per scene for the PowerPoint bridge. Write the narration script at the same time, linked to the beats (transcript/transcript.yaml). Review the words and the visuals together before animating. See references/narration-writing.md.

4. Build the transcript. Derive deterministic timings and all transcript artifacts from the authored script:

   python scripts/build_transcript.py --project examples/lesa --audience adjacent-researcher
   python scripts/qa_transcript.py --project examples/lesa
   

   Produces narration.md, transcript.json, transcript.srt, transcript.vtt, word_times.json and speaker_notes.yaml.

5. Implement scenes. One Manim scene per file under src/scenes/, registered in src/main.py from scene_spec.yaml. Reuse src/theme.py, src/actors.py and src/patterns.py (the shared visual grammar). Scenes read transcript-derived dwell through src/timing.py (timing.tail, timing.beat_dwell) so silent pacing follows the script.

6. Render, inspect, revise. Draft render is cheap; render one scene while iterating. Always extract frames and look at them before a final render.

   python skills/research-method-video/scripts/video_doctor.py
   python skills/research-method-video/scripts/render_scene.py --project examples/lesa --scene lesa_03_stage_dynamics --quality draft
   python skills/research-method-video/scripts/render_scene.py --project examples/lesa --quality draft --concat examples/lesa/renders/draft/lesa-method-explainer.mp4
   python skills/research-method-video/scripts/qa_video.py --input examples/lesa/renders/draft/lesa-method-explainer.mp4 --output examples/lesa/qa
   python skills/research-method-video/scripts/lint_scenes.py --project examples/lesa
   

7. Export for PowerPoint.

   python skills/research-method-video/scripts/export_keyframes.py --project examples/lesa --quality final
   

   Writes qa/keyframes/<scene>.png and qa/keyframes.yaml. The slide pipeline can use a keyframe as a method-summary slide, or insert the MP4.

Transcript and narration modes

• silent (default): no audio; the script sets per-beat dwell and scene holds. Best for weekly meetings where the researcher narrates live.
• tts: local synthesis (macOS say, or pyttsx3). No cloud account required.
• recorded: align a recorded reading to the canonical text with WhisperX when installed, else a clearly-labelled estimate. The text is never replaced by ASR output.

python scripts/render_scene.py --project examples/lesa --timing transcript
python scripts/export_subtitles.py --project examples/lesa
python scripts/tts_narration.py --project examples/lesa --voice Samantha
python scripts/align_recording.py --project examples/lesa --audio narration.wav
python scripts/mux_narration.py --project examples/lesa --quality final
python scripts/export_speaker_notes.py --project examples/lesa

Animation vocabulary

ESTABLISH, TRACE, BUILD, MORPH, FOCUS, COMPARE, TRAJECTORY, STAGE-SPLIT, ACCUMULATION, CORRECTION, REPLAY, REVEAL, ZOOM, RECAP. Each communicates a scientific meaning; do not animate decoratively. See references/manim-visual-grammar.md.

When NOT to make a video

If movement adds no explanatory value, use a static diagram. A video is worth it when a representation changes through time, when an algorithm iterates, or when the ordering of a multi-stage process is the point.

Read next

• references/video-explainer.md — the end-to-end pipeline and file formats.
• references/narration-writing.md — writing for listening.
• references/transcript-schema.md — transcript artifacts and structure.
• references/video-pacing.md — script-derived pacing and dwell.
• references/audio-alignment.md — TTS and forced alignment.
• references/video-storytelling.md — act structure, aha moment, camera, text.
• references/manim-visual-grammar.md — actors, patterns, shared palette.
• references/video-qa.md — animation lint, frame QA, the render loop.

Requirements

Python 3.11-3.13, Manim Community Edition, ffmpeg. LaTeX is optional (v0.1 uses Pango Text with composed sub/superscripts). requirements.txt pins the rest.