The Problem
Creating high‑quality educational math videos is labor‑intensive: it requires solving the problem, writing a script, coding precise animations, generating natural narration, and synchronizing everything. Teams that need many videos (e.g., online courses, tutoring platforms) spend weeks per topic.
What This Does
MathVizAI automates the entire pipeline. The core orchestrator lives in pipeline/orchestrator.py, which sequentially invokes:
Solver – pipeline/solver.py uses an LLM (via utils/llmclient.py) to produce a step‑by‑step proof. Evaluator – pipeline/evaluator.py validates the proof and, on failure, triggers a retry loop. Script Writer – pipeline/scriptwriter.py transforms the proof into a conversational narration script. Visual Developer – pipeline/videogenerator.py queries the vector store in VectorStore/ (FAISS indexes) and builds a Manim script (pipeline/videogenerator.py → pipeline/videorenderer.py). Audio & Sync – pipeline/ttsgenerator.py calls Microsoft VibeVoice; pipeline/videosynchronizer.py aligns audio with the rendered animation.
All assets (intro/outro clips, branding, sample videos) are stored under assets/. The “Golden Set” of curated Manim examples lives in goldenset/ and is indexed for retrieval‑augmented generation.
How To Use It
Install Python deps python -m venv .venv source .venv/bin/activate pip install -r requirements.txt Provide required keys cp .env.example .env edit .env to add: OPENAIAPIKEY, VIBEVOICEAPIKEY, TAVILYAPIKEY, etc. Run the pipeline python main.py --problem "Compute the Taylor series of e^x up to x^4"
main.py parses the CLI argument, builds a PipelineOrchestrator (imported from pipeline/orchestrator.py), and runs the full workflow. Output videos appear in the assets/branding/ directory or the current working folder.
Real‑World Use
A MOOC provider could script nightly batch jobs that read a CSV of problem statements, invoke main.py for each entry, and push the resulting MP4 files to a CDN. The provider only needs to maintain the environment variables and ensure the FAISS indexes in VectorStore/ stay up‑to‑date.
from pipeline.orchestrator import PipelineOrchestrator
orchestrator = PipelineOrchestrator() for prob in ["Pythagorean proof", "Fourier series of square wave"]: orchestrator.run(problem=prob, output_dir="videos/")
Code Health & Issues
Med – No unit or integration tests – repository lacks any tests/ folder; core functions in pipeline/.py are untested. Med – No CI/CD pipeline – no .github/workflows/ or similar; builds are not automatically verified. Low – No lockfile – requirements.txt pins versions loosely; reproducible environments depend on PyPI state. Low – Sparse documentation – only README.md and two prompt files; functions such as store.py lack docstrings, making onboarding slower. Low – Potential runtime failures – .env.example lists required keys but the code does not validate their presence before API calls, which could raise uncaught exceptions.
No obvious security secrets are committed; the license file is present.
The Bottom Line
MathVizAI delivers a complete, modular workflow for auto‑generating math explanation videos, with clear separation of solving, scripting, animation, and audio. However, the lack of tests, CI, and a lockfile means the codebase is not production‑ready without additional engineering effort. It is best suited for teams that can allocate resources to harden the pipeline and maintain the required API credentials.