Math and Science Tutorials
Turn a math or science problem into a step-by-step Mandarin video tutorial. For an interactive page instead of a video, use the interactive workflow linked below. Teaching components — equations, diagrams, solution steps — are rendered as realistic objects: solid opaque panels (glass-look via borders + layered shadow, NO backdrop-filter, NO translucency), 3D metallic cards, animated SVG constructions, on themed backgrounds with animated gradient orbs and smooth ambient effects. The default theme is "Aurora Scholar" (blue wave texture + indigo/violet/cyan orbs); 4 alternative light themes are available (清雅湖蓝, 柔紫轻盈, 薄荷清新, 暖黄纸感) for visual variety across different problem types — see the Background Theme Catalog in design-system.md.
Prerequisites (环境准备 — 开工前必查)
This is a skill-only capability (no MCP server), so its runtime dependencies are NOT auto-installed by uvx. Verify ALL of the following before Step 0 — a missing one silently breaks a later step:
| Dependency | Needed for | Install / check |
|---|---|---|
| Node.js + npm/npx | scaffold + render (npx hyperframes) | node -v (≥18) |
| hyperframes CLI | init / lint / validate / render | pulled on demand via npx hyperframes (needs npm-registry access at scaffold time; the project then pins a version in dist/package.json) |
| Headless Chromium + OS libs | npx hyperframes render (puppeteer) + post-render QA gates (postcheck.py / precheck.py drive headless Chrome) | the browser itself is auto-downloaded by puppeteer on first npx hyperframes; on minimal Linux you must also apt install libnss3 libatk-bridge2.0-0 libgbm1 libasound2 libxkbcommon0 libgtk-3-0 fonts-noto-cjk (else Chrome fails to launch, or CJK/formulas render as tofu boxes). Reuse a system Chrome via export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium. |
| Python 3 + pip | TTS script | python3 -m pip --version |
dashscope soundfile numpy requests | Step 3 TTS synthesis + assembly | python3 -m pip install dashscope soundfile numpy requests |
| ffmpeg | loudness normalization (loudnorm) + frame extraction for self-check | brew install ffmpeg / apt install ffmpeg |
DASHSCOPE_API_KEY | Qwen-TTS (qwen3-tts-flash) | export DASHSCOPE_API_KEY="sk-xxx", or put DASHSCOPE_API_KEY=sk-xxx in ~/.qwen-mm-plugins/config for GUI-launched setups that don't inherit shell exports. $EDU_SKILL_ROOT/scripts/generate_voice.py reads it at runtime — never cat/paste the key into the conversation. |
Network boundary:
npx hyperframes initand the TTS calls need internet. The render itself is air-gapped — that is why fonts / KaTeX / GSAP must be self-hosted intodist/(see Step 5 Prerequisites). DashScope TTS may rate-limit under high concurrency; if you hitThrottling.RateQuota, lower the thread-pool worker count and add backoff (see step-3).
Before Step 0, resolve EDU_SKILL_ROOT to the absolute directory containing this SKILL.md. All
shipped scripts and assets must be addressed through that root; they are not in the user's project.
Shell tool calls do not necessarily share state, so set it in every command block that uses it (or
substitute the resolved absolute path directly); never rely on an earlier shell invocation:
EDU_SKILL_ROOT="<absolute directory containing qwen-mm-plugins-edu-agent/SKILL.md>"
test -f "$EDU_SKILL_ROOT/scripts/precheck.py" || { echo "invalid EDU_SKILL_ROOT"; exit 1; }
Pipeline Overview
| Step | Name | Artifact | Reference |
|---|---|---|---|
| 0 | Image Input & Problem Extraction | PROBLEM.md | step-0-image-input.md |
| 1 | Problem Analysis | ANALYSIS.md | step-1-problem-analysis.md |
| 2 | Teaching Script | SCRIPT.md | step-2-teaching-script.md |
| 3 | Voice Generation | narration.wav + transcript.json + captions.json (sentence-by-sentence TTS, no Whisper) | step-3-voice-generation.md |
| 4 | Storyboard | STORYBOARD.md | step-4-storyboard.md |
| 5 | Build Components | compositions/*.html | step-5-build-components.md |
| 6 | Compose & Render | index.html + MP4 | step-6-compose-render.md |
Step 0: Image Input & Problem Extraction
Read references/step-0-image-input.md.
Read all images from the image_assets/ folder using the Read tool (Claude's multimodal vision directly interprets image content). Extract the complete problem text, convert all math expressions to LaTeX, and describe any figures or diagrams. If JSONL metadata is available (subject, sub_subject, question_type, stepwise_explanation), use it as context hints but treat the image as ground truth.