| name | math-video-tutor |
| description | Generate teaching video explanations for elementary math problems. Takes a math problem (with answer and solution steps) and produces a 2-3 minute MP4 video with dark-themed slides and TTS narration, suitable for 5th graders. Use when asked to create math teaching videos, explain math problems to kids, or generate video tutorials for math exercises. Supports batch processing for multiple questions. |
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
python3 $SKILL_DIR/gen_slides.py content/q1_slides.json slides/q1_slides.html
node $SKILL_DIR/screenshot_slides.js slides/q1_slides.html slides/q1/
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
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
| Script | Purpose |
|---|
scripts/gen_slides.py | JSON → HTML slide deck |
scripts/screenshot_slides.js | HTML → PNG screenshots (Playwright) |
scripts/compose_video.sh | PNGs + audio → MP4 (ffmpeg) |
scripts/batch_process.sh | Full pipeline for a range of questions |
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:
- Copy the CSS from an existing generated slide deck (dark theme, 1920×1080)
- Create slides with inline
<svg> elements in the slide content
- Use the same color scheme:
#38bdf8 (blue), #34d399 (green), #fb7185 (rose), #a78bfa (purple), #fbbf24 (amber)
- 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>
- 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
