Math Video Tutor

Math Video Tutor

Generate teaching videos from math problems: dark-themed animated slides + TTS voice narration → MP4.

Pipeline

Math problem → [Claude generates content] → JSON + narration.txt
  → gen_slides.py → HTML slides
  → screenshot_slides.js → PNG sequence (1920×1080)
  → tts-generate.py (charon voice) → OGG audio
  → compose_video.sh (ffmpeg) → MP4 video
  → gcloud storage cp → CC Pages URL

Step-by-Step Workflow

Step 1: Generate Content (Claude)

For each math problem, generate two files:

1a. Narration script (content/q{N}_narration.txt)

Write a 500-1500 character teaching script as if speaking to a 5th grader:

• Start with "同学们，我们来看第N题"
• Read the problem aloud with natural phrasing
• Walk through each step, explaining WHY not just WHAT
• State the answer clearly
• End with a method summary

1b. Slides JSON (content/q{N}_slides.json)

See references/slides-schema.md for the full schema.

Key fields: q_num, topic, problem_text, answer, steps[] (3-5 steps with badge, title, content_html), summary_when, summary_how, tip.

Use highlight classes in content_html: hl-blue (given values), hl-green (intermediate), hl-amber (key quantities), hl-rose (answers), hl-purple (totals). Wrap math in <div class="math-block">.

Step 2: Run the Pipeline

Single question:

SKILL_DIR=~/.claude/skills/math-video-tutor/scripts
WORKDIR=/tmp/math-video

# Generate HTML slides
python3 $SKILL_DIR/gen_slides.py content/q1_slides.json slides/q1_slides.html

# Screenshot
node $SKILL_DIR/screenshot_slides.js slides/q1_slides.html slides/q1/

# TTS
NARRATION=$(cat content/q1_narration.txt | tr '\n' ' ')
OGG=$(~/.claude/skills/tts-generator/scripts/tts-generate.py \
  --voice charon "[温和亲切，像老师给小学生讲题] $NARRATION")
cp "$OGG" audio/q1_narration.ogg

# Compose video
bash $SKILL_DIR/compose_video.sh slides/q1/ audio/q1_narration.ogg videos/q01_explanation.mp4

Batch (all questions):

bash $SKILL_DIR/batch_process.sh /tmp/math-video 1 25

Step 3: Upload to CC Pages

gcloud storage cp videos/q01_explanation.mp4 \
  gs://chris-pgp-host-asia/cc-pages/assets/video-name.mp4

URL: https://cc.higcp.com/assets/video-name.mp4

Step 4: Embed in HTML (optional)

<div class="video-player">
  <div class="video-label">🎬 視頻講解</div>
  <video controls preload="none">
    <source src="https://cc.higcp.com/assets/video-name.mp4" type="video/mp4">
  </video>
</div>

Parallelization

For batch content generation, use the Agent tool to spawn 4 agents, each handling a range of questions (e.g., Q1-6, Q7-12, Q13-18, Q19-25). Each agent writes content/q{N}_slides.json + content/q{N}_narration.txt.

Then run batch_process.sh which handles TTS and video composition with 4-way parallelism internally.

Dependencies

• playwright (npm) + chromium — slide screenshots
• ffmpeg — video composition
• tts-generator skill — TTS audio (Gemini Flash, charon voice)
• gcloud CLI — upload to GCS/CC Pages
• Noto Sans SC font — loaded via Google Fonts CDN in slide HTML

Scripts

Slide Design

• Dark theme: #0f172a base, gradient backgrounds per slide type
• 1920×1080 resolution, Noto Sans SC font
• 5 slide types: title, problem, step (N), answer, summary
• Color-coded math highlights, bottom gradient bar
• Step icons cycle through blue/purple/amber/green/rose

Visual Diagrams (CRITICAL)

When a problem involves visual/spatial concepts, the slides MUST include actual SVG diagrams — text descriptions alone are NOT sufficient. Students cannot understand these problems without seeing the figures.

When to include diagrams

• Venn diagrams (韦恩图/容斥原理): Draw overlapping circles with labeled regions and values
• Geometric figures: Draw shapes, angles, auxiliary lines
• Adjacency/coloring problems: Draw the regions/blocks showing which areas share borders
• Number lines, tables, grids: Render as SVG, not text
• Tree diagrams, flowcharts: For counting/probability problems

How to implement

For problems requiring diagrams, bypass gen_slides.py and write custom HTML directly:

1. Copy the CSS from an existing generated slide deck (dark theme, 1920×1080)
2. Create slides with inline <svg> elements in the slide content
3. Use the same color scheme: #38bdf8 (blue), #34d399 (green), #fb7185 (rose), #a78bfa (purple), #fbbf24 (amber)
4. Use .two-col layout for diagram + text side-by-side:

   <div class="two-col">
     <div class="col-diagram"><svg>...</svg></div>
     <div class="col-text"><div class="step-body">...</div></div>
   </div>
   

5. Include the diagram on multiple slides: first as a blank/partial version (with unknowns), then as a completed version (with answer filled in)

Example: Venn diagram slide

<svg viewBox="0 0 800 550" width="900" height="620">
  <circle cx="320" cy="240" r="190" fill="rgba(56,189,248,0.12)" stroke="#38bdf8" stroke-width="3"/>
  <circle cx="480" cy="240" r="190" fill="rgba(52,211,153,0.12)" stroke="#34d399" stroke-width="3"/>
  <circle cx="400" cy="380" r="190" fill="rgba(251,113,133,0.12)" stroke="#fb7185" stroke-width="3"/>
  <text x="400" y="290" font-size="42" fill="#fbbf24" font-weight="900" text-anchor="middle">x = ?</text>
</svg>

Quality Checklist

• Narration uses natural spoken Chinese, not written style
• Numbers read aloud (两百零一, not 201)
• Each step explains reasoning, not just calculation
• problem_text fits on one slide (abbreviate if needed)
• 3-5 steps per problem (not too many, not too few)
• Tip uses memorable phrasing (rhyme or mnemonic)
• Visual problems MUST have SVG diagrams — never describe a figure with text only