Part 2: From Textbook Chapter to Sci-Fi Film

The North Star

Why Movie-Based Education?

Textbooks are precise but emotionally inert. The best YouTube educators — the ones we analyzed in Part 1 — succeed because they wrap ideas in narrative, character, and visual rhythm. The ideal end state isn't "AI-generated Khan Academy." It's production-quality films where the math is the plot.

🎬 The Core Idea

Take a textbook chapter — say, Complex Numbers from an intermediate mathematics syllabus — and transform it into a science-fiction short film. Three recurring characters navigate a real problem. When the story demands it, the film cuts to a precise Manim visualization of the concept. The viewer learns the chapter not by reading it, but by living inside it.

📚

Input: structured chapter text

Table of contents, sub-topic headings, page ranges — or the full chapter body. The pipeline doesn't need perfect prose; it needs topic boundaries and mathematical scope.

🎥

Output: a dubbed short film

One ~18-minute film per chapter, with cinematic story scenes, Manim concept inserts, voice performance, SFX, score — and eventually multilingual dubbing for Indian languages.

🔗

Bridge to Part 1

The creator DNA from Part 1 (narration rate, scene duration, visual richness) becomes the style target this pipeline learns to hit — Kurzgesagt pacing, OverSimplified narrative density, etc.

"M poses the real problem → Y and F work it out → F teaches Y via cinematic scenes → one high-level Manim insert per concept → back to story. The math is never explained before the viewer has a reason to need it."

— Pipeline design principle

The World

Three Characters, One Series

Every chapter shares the same cast and visual world. Characters are locked at series setup — reference photos, voice profiles, and visual grammar are built once and reused across all chapters.

M

The Mathematician

Poses the real-world problem. Reads the signals. Sets the stakes. M never lectures — M notices something wrong and hands the problem to the team.

F

The Friend

Works through the math with Y. Explains concepts only when Y (and the viewer) has a concrete reason to need them. The pedagogical voice of the series.

Y

You — The Viewer

Viewer POV character. Asks the questions the audience is thinking. Y's confusion drives the pacing — F never gets ahead of Y's understanding.

The Series Bible (Stage 3) locks everything: character descriptions, voice profiles, world premise, set designs, camera rules, color grade, and a multi-angle reference photo bank per character. Flux keyframe generation uses these references to keep identity consistent shot-to-shot, chapter-to-chapter.

Scene Architecture

Three Scene Types

Every scene in the screenplay is tagged with one of three types. This determines which generation path handles it downstream.

STORY

Cinematic scenes. Characters in the sci-fi world — control rooms, antenna arrays, data streams. Generated via Flux keyframes → LTX/WAN video animation. Dialogue-driven, visually rich, full production value.

CONCEPT

Manim inserts. One high-level visualization per math topic — locked at Stage 1 as core_visual_idea. No derivations, no scope creep. Shows the one thing the viewer must see to understand the concept.

HYBRID

Diegetic screen → Manim match-cut. A character looks at a holographic display or cracked monitor showing the math. Camera pushes in on the screen — match-cut into the Manim visualization. Pull back to story when the concept lands.

Architecture

The 7-Stage Pipeline

Text stages run first on Qwen via vLLM. GPU-heavy pixel generation runs only after all upstream text passes quality gates. Each stage writes to a dedicated output/ subdirectory — never mixing artifacts.

1

Math Bible

topics + equations

→

2

Screenplay

scenes + dialogue

→

3

Series Bible

cast + refs

→

4

Storyboard

shots + keyframes

→

5a

Cinematic

LTX video

+

5b

Manim

math inserts

→

6

Audio

voice + dub

→

7

Final Cut

ffmpeg assembly

Stages 5a (cinematic video) and 5b (Manim) run in parallel after the storyboard is locked. Stage 6 reconciles timing across all assets. Stage 7 assembles everything into the finished film.

Deep Dive

Stage-by-Stage Breakdown

Each stage has a dedicated script, prompt template, quality gate, and output directory. The orchestrator (run_pipeline.py) chains them with gate checks.

1

Mathematician Agent

Math Bible

Reads the raw chapter text and extracts every sub-topic. For each topic, it invents a load-bearing real-world problem, locks the core equation, defines prerequisites, and specifies exactly one core_visual_idea for the Manim insert. Explicitly marks what to exclude — no scope creep downstream.

Qwen 3.5 output/math_bible/ Equation verification gate

      # Input: textbook ToC or full chapter

      python3 scripts/generate_math_bible.py \

        --input scripts/samples/input_docs.md

2

Screenwriter Agent

Screenplay

Transforms the math bible into a real screenplay — scene headers, action lines, character dialogue, intentions. Every math topic gets covered. F never explains before Y has a reason to need it. Scenes are tagged STORY, CONCEPT, or HYBRID. Target runtime: ~18 minutes with rising tension, not flat lectures.

Qwen 3.5 output/screenplay/ Topic coverage + dialogue WPM

python3 scripts/generate_screenplay.py

3

Character & Series Bible Agent

Series Bible + Reference Bank

Locks M, F, Y identity — descriptions, voice profiles, world premise, set designs, visual grammar, camera rules. Builds a multi-angle reference photo bank per character (front, three-quarter, profile, close-up, full-body). Built once, reused forever. Extended only when a new angle is genuinely needed.

Qwen 3.5 + Flux output/series_bible/ Manual reference review

      python3 scripts/generate_series_bible.py

      python3 scripts/build_reference_bank.py --copy-only

4

Storyboard / Image Agent

Storyboard + Keyframes

Breaks each screenplay scene into fully specified shots — lens, subject scale, camera move, blocking, dialogue, duration. Generates keyframe stills via FLUX.2-dev with multi-reference compositing from the character bank. Coverage rule: every scene gets at least one WIDE before any close-up. Gemma 4 runs visual QC with mask-based retry on failures.

Qwen + Flux + Gemma 4 output/storyboard/ Wide-shot coverage + QC

      python3 scripts/generate_storyboard.py

      python3 scripts/generate_storyboard_keyframes.py --skip-existing

5a

Cinematic Video Agent

Cinematic Videos

Animates every STORY and HYBRID shot from its keyframe using LTX/WAN-class video models. Motion continues from the previous shot's implied end state. One speaking character per shot. Stage 5a audio is lip-sync reference only — final voice comes from Stage 6.

LTX / WAN 2.2 output/cinematic_videos/ Motion continuity check

python3 scripts/generate_cinematic_videos.py --skip-existing

5b

Math Insert Agent

Manim Visualizations

One Manim animation per math topic — visualizing only the core_visual_idea locked at Stage 1. Qwen writes Manim code → render → Gemma 4 reviews visuals and code → fix loop until pass. Hard rule: if scope creeps here, it's a Stage 1 problem, not a Manim problem.

Qwen + Manim + Gemma 4 output/manim_videos/ Visual + code review loop

python3 scripts/generate_manim_videos.py --skip-existing

6

Audio Agent

Voice, SFX, Score & Dubbing

Four sub-steps: (1) timing pass — reconcile dialogue duration across screenplay, storyboard, and video; (2) voice performance — one voice clone per character, reused across the series; (3) sound design and score — ambience beds, foley, recurring sonic motif; (4) multilingual dubbing — Gemma 4 localizes dialogue while preserving voice identity per language.

TTS + Gemma 4 output/audio/ Dialogue fits shot duration

python3 scripts/generate_audio.py

7

Editor Agent

Final Cut Assembly

Concatenates all shots in storyboard order. Applies the shared LUT from the series bible. Match-cuts Manim inserts via planned push-in/pull-back HYBRID shots. Muxes locked voice, SFX bed, and score. Repeats per language. Writes an EDL for manual tweaks without re-generation.

ffmpeg output/final_cut/ End-to-end intent review

python3 scripts/assemble_final_cut.py --chapter-slug complex_numbers

Infrastructure

Model Routing

Qwen plans and judges. Gemma looks at pixels. GPU generation runs last. The rule keeps expensive compute off bad upstream text.

Task	Model	When
Orchestration, math bible, screenplay, storyboard, Manim code, audio planning	Qwen 3.5 via vLLM	Stages 0–4, 5b code gen, 6 planning
Keyframe QC, Manim visual review, dubbing / localization	Gemma 4	Stages 4b, 5b review, 6.4 dub
Keyframe stills (multi-reference)	FLUX.2-dev	Stage 4b
Cinematic video animation	LTX / WAN 2.2	Stage 5a
Math visualization render	Manim	Stage 5b
Voice / TTS performance	Voice clone model	Stage 6.2
Final assembly	ffmpeg	Stage 7

⚡ Running the Full Pipeline

Start Qwen vLLM once, set environment variables, then orchestrate:

      # Preview all stages and I/O paths

      python3 scripts/run_pipeline.py --dry-run

      # Text stages (1 → 4)

      python3 scripts/run_pipeline.py --from-stage 1 --to-stage 4

      # GPU pixel stages + audio + assembly

      python3 scripts/generate_storyboard_keyframes.py --skip-existing

      python3 scripts/generate_cinematic_videos.py --skip-existing

      python3 scripts/generate_manim_videos.py --skip-existing

      python3 scripts/generate_audio.py

      python3 scripts/assemble_final_cut.py --chapter-slug complex_numbers

Quality Control

Gates Between Every Stage

The pipeline doesn't blindly chain LLM outputs. Each stage has a gate — automated review, manual sign-off, or both — before the next stage is allowed to run.

🔬

Automated text gates

Stage 1 re-verifies every equation with a second Qwen call. Stage 2 checks topic coverage and dialogue WPM plausibility. Failed items get targeted fixes, not full regeneration.

👁

Visual QC gates

Gemma 4 reviews keyframe stills and Manim renders. Mask-based inpaint retry fixes localized failures (face, wardrobe) without regenerating the entire frame.

✋

Manual gates

Reference photo bank review (Stage 3), director contact-sheet per scene (Stage 4), and end-to-end intent review against the math bible (Stage 7).

🚫

Hard blocks

run_pipeline.py reads gate results from output/pipeline/gates/ and refuses to proceed on failure. Use --force only for development.

The Full Picture

How Part 1 and Part 2 Connect

Part 1 measured what great educational video looks like. Part 2 is the factory that builds it. The DNA dimensions become concrete generation targets:

Part 1 → Stage 2 (Screenplay)

Narrative DNA — sentence length, information density, curiosity-gap patterns — trains the script adapter that transforms math topics into creator-voice dialogue.

Part 1 → Stage 6 (Audio)

Vocal DNA — speech rate, pause distribution, prosody — sets TTS performance targets for each character's delivery cadence.

Part 1 → Stage 4 (Storyboard)

Visual DNA — scene duration, visual richness, shot tempo — constrains storyboard shot counts, keyframe detail level, and cut rhythm.

Part 1 → Stage 7 (Final Cut)

Structural DNA — shot budgets, scene-type sequences, video length distributions — guides the editor's assembly pattern toward creator-authentic pacing.

Part 3: First Chapter Render

With the pipeline architecture defined, Part 3 will walk through the first full chapter render — Complex Numbers — from raw textbook input to finished film, with intermediate artifacts, gate failures, and the lessons learned from the first end-to-end run.

Coming Soon → Part 3

From Textbook Chapterto Sci-Fi Film

🎬 The Core Idea

⚡ Running the Full Pipeline

Part 3: First Chapter Render

From Textbook Chapter
to Sci-Fi Film