recursive-maths-animator

name

recursive-maths-animator

description

Recursive maths animator — Manim-based technical animations with optional voiceover (manim-voiceover), git scene versioning, pinned requirements, asset folders, GIF approval previews, and a vision verification loop (frame extract, multimodal review in Cursor/Claude Code, VERIFICATION_FEEDBACK.md, iterate). Brief-first workflow: pitch a digestible animation plan and design options, get user approval, then code; lock theme in DESIGN_THEME.md.

Recursive maths animator (Manim + voiceover + verification)

This skill ships helper code under references/ (palette, optional Gemini TTS adapter, manim_versioning.ManimProject) and utilities under scripts/. Agents should point users at those paths when generating projects.

Brief-first workflow (do this before any scene code)

Many users want something cool, shareable, and minimal — not a wall of technical detail. Do not jump straight to project.init() + a full scene unless the user explicitly says “just build it.”

1. Digestible pitch first — In chat, give a short animation brief: one-line takeaway, 3–5 beats (what appears, in order, rough seconds each), and why it fits Manim (motion, not static slides). Keep it skimmable; no long tables of API names unless they ask.

2. Offer choices — Present 2–3 palette options from the built-in design systems (see below). Use letter labels the user can reply with:

   • A — Swiss grid (Inter, clinical, data-forward)
   • B — Bauhaus primary (Space Grotesk, geometric, educational)
   • C — Braun minimal (Work Sans, warm gray, product)
   • D — Editorial bold (Playfair + Inter, dramatic, storytelling)
   • E — Apple precision (DM Sans, cool, tech)
   • F — Soft enterprise (Roboto, warm cream — existing default)

   Also offer aspect ratio (16:9, 1:1, 9:16) and tone (calm / punchy). Let the user pick or mix.

3. Wait for approval — Only after the user confirms (or says “use A + 1:1 + calm”) do you: write ANIMATION_BRIEF.md (filled) + DESIGN_THEME.md (locked), then implement the scene.

4. Use the maths engine — Prefer Manim-native motion: MathTex / Tex, NumberPlane, ParametricFunction, Transform / ReplacementTransform, Indicate, ShowPassingFlash, LaggedStart, updaters. Avoid “generic UI explainer” unless that is what they asked for. See references/manim_guide.md for patterns.

5. Shareable quality — MP4 at -qh / --quality h is the default deliverable for “looks good.” GIF is for layout checks only; re-encoding with aggressive ffmpeg crushes gradients and dark minimal palettes. If they need a small GIF, render a short clip, limit colors in the scene, or share MP4 / link instead.

ManimProject.init() seeds ANIMATION_BRIEF.md with a template; agents replace “DRAFT” content after approval.

Operating principles (do these every time)

1. Design theme + brief — After the user approves the pitch, record mood, light/dark, chosen design system (swiss / bauhaus / braun / editorial / apple / soft), typography, motion, deliverable size, and brand assets in DESIGN_THEME.md. Keep the approved story in ANIMATION_BRIEF.md.
2. Pinned dependencies — Every project keeps a root requirements.txt (seeded on init() from this skill’s template). When you add imports or optional stacks (e.g. Gemini), update requirements.txt and tell the user to pip install -r requirements.txt. For reproducible CI, suggest pip freeze > requirements.lock.txt after upgrades.
3. Assets live in assets/ — Put images, SVGs, and custom fonts under assets/images, assets/svgs, assets/fonts. Keep scenes/ for Python only so diffs stay readable.
4. Optional GIF before final MP4 — When stakeholders need a quick motion check in chat, produce a low-quality GIF (ManimProject.render_approval_gif("scene_1") or render(..., output_format="gif", export_approval_copy=True)). If the user prefers to go straight to MP4 (e.g. silent cut with voiceover added later), skip the GIF and render MP4 directly. After any GIF sign-off, render output_format="movie" (MP4; see Rendering — Manim uses --format mp4).
5. Verify with vision, then iterate — After each substantive render, run the verification loop below: slice frames, review with the host model’s vision, write VERIFICATION_FEEDBACK.md, fix Manim code, re-render. Prefer MP4 for final verification passes; GIF is acceptable for quick layout checks.

Requirements

• Python 3.9+
• manim — pip install manim (versions pinned in project requirements.txt)
• manim-voiceover with a TTS backend — e.g. pip install "manim-voiceover[gtts]" (uses network for gTTS unless you switch engine)
• ffmpeg and ffprobe — with libx264 and libass if you burn subtitles (see scripts/run_pipeline.py); ffprobe is required for extract_verification_frames.py
• git — for ManimProject versioning commands

Optional:

• google-genai — only if using references/gemini_tts_service.py (set GEMINI_API_KEY); uncomment in requirements.txt when used.

Using references/ from your project

The installable skill is the directory that contains SKILL.md (often .../recursive-maths-animator/ inside a Git clone), not the repository root above it. If the host says “unknown skill,” confirm that path ends with recursive-maths-animator/SKILL.md.

The Quick Start imports ManimProject from manim_versioning. Add this skill’s references directory to sys.path (or copy the files into your repo).

from pathlib import Path
import sys

# Path to the installed skill’s references/ folder (adjust if you symlink or copy the skill).
# Cursor (user-wide): ~/.cursor/skills/recursive-maths-animator/references
# Claude Code (user-wide): ~/.claude/skills/recursive-maths-animator/references
SKILL_REF = Path.home() / ".cursor/skills/recursive-maths-animator/references"
# SKILL_REF = Path("path/to/recursive-maths-animator/references")

sys.path.insert(0, str(SKILL_REF.resolve()))
from manim_versioning import ManimProject

Scene files should use the same pattern so soft_enterprise_palette and optional gemini_tts_service resolve:

import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "references"))

(Adjust the relative path if your layout differs.)

Quick Start

from pathlib import Path
import sys

REF = Path("/path/to/recursive-maths-animator/references").resolve()
sys.path.insert(0, str(REF))
from manim_versioning import ManimProject

project = ManimProject("my_animation")
project.init()  # Creates git repo, scenes/ folder, structure

# Create Scene 1
project.create_scene("scene_1", """
class Scene1(Scene):
    def construct(self):
        # Your animation code
        pass
""")

# Render and commit
project.render("scene_1")  # Auto-commits as "scene_1 v1"

# Make changes, create new version
project.update_scene("scene_1", "# updated code...")
project.render("scene_1")  # Auto-commits as "scene_1 v2"

# Rollback if needed
project.rollback("scene_1", version=1)  # Restores v1

# Create provisional branch for review
project.branch("scene_1", "review-alice")  # Creates branch, doesn't affect main

Project structure

After ManimProject.init(), the layout includes dependency and theme files plus asset and approval folders:

my_animation/
├── .git/
├── requirements.txt       # Pinned Manim / voiceover; extend when you add packages
├── ANIMATION_BRIEF.md     # Short pitch + beats + approved choices (before / while coding)
├── DESIGN_THEME.md        # User’s theme answers — fill after approval, before heavy code
├── assets/
│   ├── README.md
│   ├── images/
│   ├── svgs/
│   └── fonts/
├── VERIFICATION_FEEDBACK.md   # Latest multimodal review output (agent-written; optional until first review)
├── exports/
│   ├── approvals/         # GIF (or other) previews for sign-off
│   └── verification/    # Frame slices + manifest.json per run (see extract script)
├── scenes/
│   ├── scene_1/
│   │   ├── scene_1.py
│   │   ├── versions/
│   │   │   ├── v1.py
│   │   │   └── v2.py
│   │   └── branches/
│   │       └── review-alice/
│   ├── scene_2/
│   └── shared/
│       ├── palette.py
│       └── utils.py
├── media/
│   ├── scene_1_v2.mp4
│   └── scene_1_v2.gif     # when you render GIF previews
└── project.json

Versioning commands

Action	Command	Result
Initialize project	project.init()	Git repo + folder structure
Create scene	project.create_scene(name, code)	Scene file + initial commit
Update scene	project.update_scene(name, code)	New version committed
Render	project.render(name)	Video + auto-commit
List versions	project.versions(name)	Shows v1, v2, v3...
Rollback	project.rollback(name, version)	Restores code to version
Create branch	project.branch(name, branch_name)	Provisional copy
Merge branch	project.merge(name, branch_name)	Merges into main
Compare	project.diff(name, v1, v2)	Shows code differences
Tag approved	project.tag(name, version, "approved")	Marks final version

Provisional branch workflow

project.update_scene("scene_1", "# version 1 code")
project.render("scene_1")

project.branch("scene_1", "alt-animation")
project.update_scene("scene_1", "# alternative code", branch="alt-animation")
project.render("scene_1", branch="alt-animation")

# Review outputs, then merge or delete_branch as needed
project.merge("scene_1", "alt-animation")

Scene templates

Using a built-in design system (recommended)

"""
SCENE {N}: {TITLE}
{Description}
~{duration}s, {orientation}
Design system: {scheme}
"""

import sys
sys.path.insert(0, '{project_path}/references')

from manim import *
from manim_voiceover import VoiceoverScene
from manim_voiceover.services.gtts import GTTSService

# Import the chosen design system (example: swiss)
from design_systems.swiss_international import SwissScene, SwissColors, EASE_SWISS_SNAP


class Scene{N}_{Title}(SwissScene):
    """{Description}"""

    def __init__(self, **kwargs):
        config.pixel_width = {width}
        config.pixel_height = {height}
        config.frame_width = {frame_w}
        config.frame_height = {frame_h}
        config.frame_rate = 60

        super().__init__(**kwargs)

        self.set_speech_service(GTTSService(lang='en', slow=True))

    def construct(self):
        self.setup_swiss_background()

        section_title = self.make_heading("{SECTION_TITLE}")
        section_title.to_edge(UP, buff=0.5)
        self.add(section_title)

        with self.voiceover(
            text="{VOICEOVER_LINE_1}"
        ) as tracker:
            pass

        self.wait(0.5)


if __name__ == "__main__":
    config.quality = "high_quality"
    scene = Scene{N}_{Title}()
    scene.render()

Legacy: voiceover + soft palette (no design system)

"""
SCENE {N}: {TITLE}
{Description}
~{duration}s, {orientation}
"""

import sys
sys.path.insert(0, '{project_path}/references')

from manim import *
from manim_voiceover import VoiceoverScene
from manim_voiceover.services.gtts import GTTSService
from default_typography import DEFAULT_FONT
from soft_enterprise_palette import SoftColors, EASE_GAS_SPRING


class Scene{N}_{Title}(VoiceoverScene):
    """{Description}"""

    def __init__(self, **kwargs):
        config.pixel_width = {width}
        config.pixel_height = {height}
        config.frame_width = {frame_w}
        config.frame_height = {frame_h}
        config.frame_rate = 60

        super().__init__(**kwargs)

        self.set_speech_service(GTTSService(lang='en', slow=True))

    def construct(self):
        bg = Rectangle(
            width=config.frame_width,
            height=config.frame_height,
            fill_color=SoftColors.BACKGROUND,
            fill_opacity=1
        )
        self.add(bg)

        section_title = Text(
            "{SECTION_TITLE}",
            font=DEFAULT_FONT,
            font_size=14,
            color=SoftColors.TEXT_SECONDARY
        )
        section_title.to_edge(UP, buff=0.5)
        self.add(section_title)

        with self.voiceover(
            text="{VOICEOVER_LINE_1}"
        ) as tracker:
            pass

        self.wait(0.5)

    def create_token(self, text, is_active=False):
        token = Text(
            text,
            font=DEFAULT_FONT,
            font_size=24,
            color=SoftColors.TEXT_PRIMARY if is_active else SoftColors.TEXT_SECONDARY,
            weight=MEDIUM
        )

        if is_active:
            bg = RoundedRectangle(
                corner_radius=0.12,
                width=token.width + 0.35,
                height=token.height + 0.25,
                fill_color=SoftColors.CONTAINER,
                fill_opacity=0.85,
                stroke_color=SoftColors.BORDER,
                stroke_width=1
            )
            bg.move_to(token.get_center())
            token = VGroup(bg, token)

        return token


if __name__ == "__main__":
    config.quality = "high_quality"
    scene = Scene{N}_{Title}()
    scene.render()

Design systems

Five built-in designer-inspired aesthetic systems live under references/design_systems/. Each is a complete module (colors, typography, motion, containers, background, base scene) following the same API as soft_enterprise_palette.SoftEnterpriseScene.

Key	Name	Designer / Movement	Primary Font	Mood
swiss	Swiss International	Josef Müller-Brockmann	Inter	Strict grid, clinical precision, black/white + restrained red
bauhaus	Bauhaus Modern	Herbert Bayer	Space Grotesk	Geometric, primary colors, functional art
braun	Braun Minimal	Dieter Rams	Work Sans	Warm light grays, systematic, "less but better"
editorial	Editorial Bold	Paula Scher / Pentagram	Playfair Display + Inter	Dramatic scale contrast, deep navy + warm cream
apple	Apple Precision	Jony Ive	DM Sans	Cool neutrals, generous whitespace, sleek motion
soft	Soft Enterprise	Skill default	Roboto	Warm cream, dot grid, gas-spring easing

Import a system directly:

import sys
sys.path.insert(0, 'path/to/references')
from design_systems.swiss_international import SwissScene, SwissColors, EASE_SWISS_SNAP

Or use the registry:

from design_systems import get_scheme, get_scene_class
SceneClass = get_scene_class("swiss")   # -> SwissScene

Fonts are downloaded on demand:

from design_systems.font_catalog import install_fonts
install_fonts("swiss", target_dir="assets/fonts")

All fonts are SIL Open Font License (OFL) 1.1 and freely redistributable. ManimProject.init(scheme="swiss", install_fonts=True) can download fonts automatically at project creation.

Soft enterprise palette

Defined in references/soft_enterprise_palette.py — import SoftColors and EASE_GAS_SPRING after adding references to sys.path.

Default font: references/default_typography.py defines DEFAULT_FONT (Roboto) for all Text() unless the user overrides in DESIGN_THEME.md.

Rendering

Manim Community expects --format mp4 (or gif, webm, etc.), not movie. The word “movie” in docs means “video file”; ManimProject.render(..., output_format="movie") maps to --format mp4 internally.

For shareable, high-quality output, prefer --quality h (or -qh) MP4. Post-processing GIF with heavy palette reduction often looks worse than the source MP4 — especially dark or gradient minimal styles.

# Draft MP4
manim -ql scene.py SceneClass --format mp4 --disable_caching

# Stakeholder approval GIF (small, easy to share)
manim -ql scene.py SceneClass --format gif --disable_caching

# High quality final MP4
manim -qh scene.py SceneClass --format mp4 --disable_caching

# Versioning helper — final pass (still uses output_format="movie" in Python = MP4 on CLI)
project.render("scene_1", quality="high", output_format="movie")

# Versioning helper — approval GIF into exports/approvals/ (no auto-commit)
project.render_approval_gif("scene_1")

If your Manim build errors on --format, upgrade Manim (Community ≥ 0.18) or use a two-step pipeline: render draft MP4, then ffmpeg to GIF (document in project README if needed).

Verification loop (required after substantive renders)

This skill does not call cloud LLM APIs from Python. Cursor or Claude Code performs multimodal review using extracted stills.

When to run

• After any render that changes layout, copy, colors, or story beats (including a new GIF approval cut).
• Final checks should use a full-quality MP4 when possible; GIFs are fine for early layout passes.

Step 1 — Extract frames

From the animation project root (or pass --cwd), run:

python3 path/to/recursive-maths-animator/scripts/extract_verification_frames.py path/to/render.mp4

Optional: --count 10, --format png, --output-dir exports/verification/my_run.

This writes a timestamped folder under exports/verification/ with JPEG/PNG frames and manifest.json (t_seconds, pct, filename per frame).

Step 2 — Multimodal review (host agent)

1. Read manifest.json and open every extracted frame (vision).
2. Read DESIGN_THEME.md and the agreed storyboard / scene plan (what each beat must prove).
3. Apply references/video_verification_rubric.md: padding and safe margins, typography (including font vs DESIGN_THEME.md), text alignment and overlap, theme colors, logical progression vs plan, motion hints between samples, glitches.

Step 3 — Write VERIFICATION_FEEDBACK.md (project root)

Use this structure:

# Verification feedback

## Verdict
PASS | PASS_WITH_ISSUES | FAIL

## Summary
2–4 sentences. Must include at least one sentence on **text alignment** (e.g. columns, baselines, multi-line blocks) and one on **overlap / clutter** (text vs arrows/shapes, cramped `buff=`).

## Layout (alignment & overlap)
- Alignment: …
- Overlap / clutter: …

## Issues
### P0 — (title)
- Evidence: frame `frame_03_...jpg` — t=…s, pct=…%
- Expected: …
- Observed: …
- Suggested fix: … (Manim: e.g. `buff=`, `to_edge`, `shift`, color constant, reorder `play`)

### P1 — …

## Next iteration
Ordered list of edits to the scene file(s), then re-render and re-run extraction.

Step 4 — Iterate

1. Implement P0 then P1 (then P2) in Manim source.
2. Re-render the same deliverable type you are validating.
3. Re-run extract_verification_frames.py on the new file (new output folder preserves history).
4. Repeat until Verdict is PASS or PASS_WITH_ISSUES with only acceptable P2 items.

Round cap: default 3 full verify cycles unless the user explicitly asks for more.

Pipeline helper (optional)

scripts/run_pipeline.py wraps render + optional subtitle burn-in. scripts/check_environment.py verifies common dependencies.

Output locations

• Draft: media/videos/scene_1/480p15/Scene1.mp4
• Final: media/videos/scene_1/1080p60/Scene1.mp4
• Versioned: media/scene_1_v{N}.mp4 (when using ManimProject; see implementation)

Best practices

1. Theme in writing — DESIGN_THEME.md should reflect what the user agreed to; link palette choices to the chosen design system (e.g. SwissColors, BauhausColors) or a project palette module under scenes/shared/.
2. Requirements drift — Any new pip dependency must appear in requirements.txt the same change set.
3. Version deliberately: use commits per meaningful final render; GIF previews may skip auto-commit (see render_approval_gif).
4. Use branches for experiments before merging to main line.
5. Tag approvals when a cut is final (project.tag(...)).
6. Keep scenes independently renderable.
7. Shared utilities live under scenes/shared/; binaries only under assets/.
8. Keep voiceover text TTS-friendly (plain punctuation, avoid noisy symbols).
9. Target ~10–15s per scene for short-form vertical if that is the deliverable.
10. Close the verification loop — Do not treat a render as done until frames are extracted and VERIFICATION_FEEDBACK.md records a PASS (or user accepts PASS_WITH_ISSUES).
11. Pitch before pixels — For creative or “explainer” requests, use the Brief-first workflow so palette and story match what the user considers “cool” before you invest in a long scene file.

Automated sandbox reports (VirusTotal Zenbox, etc.)

If a dynamic scan of the skill zip shows subprocesses, python.exe, cmd.exe, non-standard ports, or URLs such as http://192.168.x.x:…/v1/…, treat the overall verdict and score first: this package is documentation + optional Manim helpers; it does not embed a C2 server or obfuscated payloads. Strings like /v1/chat/completions in memory usually come from the analyzer environment (local model proxy), not from files in this skill. Heuristic “injection” or “non-standard port” flags are common for any stack that runs subprocess + Python + optional HTTP clients (e.g. gTTS). Compare the zip to this repository when in doubt.

Troubleshooting

Issue	Solution
Git not initialized	Run project.init() first
Import errors for helpers	Add this skill’s references/ to sys.path or copy files into your project
Branch merge conflict	Resolve in scene file, then commit via project helpers
Cache issues	Use --disable_caching
TTS / API limits	Fall back to gTTS or another SpeechService
ffprobe / frame extract fails	Install full ffmpeg package; ensure ffprobe is on PATH
Empty or black frames	Re-sample with higher --count or inspect source video; check -ss timing
GIF looks muddy / banded after ffmpeg	Deliver MP4 for final share; shorten the clip, simplify palette in Manim, or use gentler GIF settings — do not treat crushed GIF as the only artifact

Optional follow-on

• Remotion or other compositors for captions, UI chrome, or multi-track polish.
• General video editing (FFmpeg, DaVinci, etc.) for final assembly.