MathLens
专业的数学老师辅导技能,用于深入浅出的解答数学题,生成HTML讲解文档和带配音的Manim动画视频, 解答细致,深入浅出,浅显易懂,比较适合一般学情的学生。 核心工作流:数学分析 → HTML可视化 → 分镜脚本 → TTS音频 → 验证更新 → 脚手架 → Manim代码 → 渲染验证 触发条件:学生粘贴数学题图片、需要教学视频、需要HTML讲解资料
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/shuyicc--mathlens)HTML
<a href="/listings/shuyicc--mathlens"><img src="/api/listings/shuyicc--mathlens/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Prerequisites
pip install uv manim edge-tts
Initialize a project
python init.py ./my_math_problem
Trigger the Skill
In Cursor, paste a problem image or description:
(paste math problem screenshot) Please explain this problem and generate a teaching video.
The AI will automatically run the full 8-step pipeline.
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 940 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- ---
- name: MathLens
- description: |
- 专业的数学老师辅导技能,用于深入浅出的解答数学题,生成HTML讲解文档和带配音的Manim动画视频, 解答细致,深入浅出,浅显易懂,比较适合一般学情的学生。
- 核心工作流:数学分析 → HTML可视化 → 分镜脚本 → TTS音频 → 验证更新 → 脚手架 → Manim代码 → 渲染验证
- 触发条件:学生粘贴数学题图片、需要教学视频、需要HTML讲解资料
- ---
- # 数学分析
- ## 核心工作流
- ```python
- WORKFLOW = [
- # 步骤1: 数学建模
- {
- "step": 1,
- "name": "analyze_problem",
- "input": "题目图片/文本",
- "output": "math_analysis.md",
- "tasks": ["推导数学事实", "建立几何模型", "确定图形构建方法"]
- },
- # 步骤2: HTML可视化
- {
- "step": 2,
- "name": "html_visualization",
- "input": "math_analysis.md",
- "output": "数学_{日期}_{题目}.html",
- "tasks": ["SVG画图形", "展示画图过程", "标注关键要素"]
- },
- # 步骤3: 分镜脚本
- {
- "step": 3,
- "name": "storyboard",
- "input": "HTML内容",
- "output": "{日期}_{题目}_分镜.md",
- "tasks": ["定义幕结构(不限制幕数)", "设计画面/字幕/读白", "音频清单(时长留空)"]
- },
- # 步骤4: TTS生成(含句级同步点)
- {
- "step": 4,
- "name": "generate_tts",
- "input": "分镜脚本",
- "output": "audio/audio_{三位幕号}_{幕名}.wav + audio_info.json(含sync_points)",
- "command": "python scripts/generate_tts.py audio_list.csv ./audio --voice xiaoxiao"
- },
- # 步骤5: 验证更新(含同步点摘要)
- {
- "step": 5,
- "name": "validate_audio",
- "input": "分镜.md + audio/",
- "output": "更新后的分镜.md(填充时长) + 同步点摘要(供步骤7参考)",
- "command": "python scripts/validate_audio.py 分镜.md ./audio",
- "check": ["音频存在性", "时长>0", "数量匹配", "sync_points完整性"]
- },
- # 步骤6: 脚手架
- {
- "step": 6,
- "name": "scaffold",
- "input": "分镜.md + audio_info.json(含sync_points)",
- "output": "script.py (伪代码框架)",
- "template": "templates/script_scaffold.py",
- "must_include": [
- "calculate_geometry() - 几何建模",
- "assert_geometry() - 几何验证(题目条件+精度) + 画布范围检查(边界+中心)",
- "COLORS - 颜色定义",
- "SCENES[] - 幕信息数组(从audio_info.json加载时长)",
- "start_scene_with_audio(scene_num) - 每幕起点(播放音频+记录起始时间)",
- "end_scene_with_audio(expected_duration, safety_margin=0.2) - 每幕收尾(自动补齐等待)",
- "wait_for_narration(keyword) - 等到读白说出关键词时刻再触发动画",
- "wait_until_scene_time(seconds) - 等到幕内指定时刻",
- ]
- },
- # 步骤7: 生成代码
- {
- "step": 7,
- "name": "implement",
- "input": "script.py脚手架 + 分镜.md + audio_info.json(含sync_points)",
- "output": "完整的script.py",
- "rules": [
- "根据分镜实现每幕动画",
- "使用 wait_for_narration(keyword) 对齐读白和高亮",
- "禁止 self.wait(max(..., duration - N)) 手动兜底",
- "画面时长由 end_scene_with_audio() 自动补齐",
- "calculate_geometry()必须完整实现"
- ]
- },
- # 步骤8: 检查与渲染
- {
- "step": 8,
- "name": "check_and_render",
- "input": "script.py",
- "output": "视频文件 + 关键帧截图",
- "command": "python scripts/render.py",
- "check": ["代码结构检查(check.py)", "几何正确性", "高亮同步", "字幕清晰", "动画流畅"],
- "on_fail": "回到步骤7修改代码"
- }
- ]
- # 工作流状态转换
- # step1 → step2 → step3 → step4 → step5 → step6 → step7 → step8
- # ↑____________↓ (失败时循环)
- ```
- ---
- ## 步骤1:分析题目,推导数学事实
- **目标**:建立正确的数学计算方法和流程,形成画出符合数学的图形的方法。
- ### 输出格式
- ```markdown
- ## 数学事实分析
- ### 已知条件
- - 条件1:...
- - 条件2:...
- ### 推导的事实
- 1. **事实名称**: 描述
- - 计算过程: ...
- - 数学表达: ...
- ### 图形构建方法
- - 点的坐标: ...
- - 边的关系: ...
- - 圆/弧的定义: ...
- ### 需要证明的结论
- - 结论1: ...
- ```
- **注意**:所有证明题需要证明的结论,在分镜中都可以作为已确立的**事实**来使用。
- ---
- ## 步骤2:HTML + SVG 可视化
- **目标**:用 HTML + SVG 画出图形,展示画图过程和解答流程,为分镜做规划。
- **补充**:如果用户已经提供了准确的HTML文件,描述了画图过程,可以按文件名要求复制一份,跳过生成文件。
- ### 输出要求
- - 文件命名:`数学_{日期}_{题目简述}.html`
- - 包含:题目陈述、SVG 图形、分步解答、关键要素标注
- - SVG 需要展示**画图过程**(如:先画三角形 → 再画圆 → 标注点)
- ---
- ## 步骤3:生成分镜脚本
- **目标**:定义视频结构,不限制幕数,结尾预留音频文件名(时长为空)。
- ### 文件命名
- `{日期}_{题目}_分镜.md`
- ### 分镜脚本结构
- ```markdown
- # 分镜脚本 - {题目名称}
- ## 分镜设计
- ### 第1幕:{幕名}
- **画面**: ...
- **字幕**: ...(简洁,≤20字)
- **读白**: ...(详细,口语化,容易理解,适合普通学情的学生)
- **动画**: ...
- **目的**: ...
- ---
- ## 音频生成清单(步骤4填写)
- | 幕号 | 文件名 | 读白文本 | 时长 | 说话人 | 情感 |
- |------|--------|----------|------|--------|------|
- | 1 | audio_001_{幕名}.wav | "读白文本" | | xiaoxiao | 热情 |
- | 2 | audio_002_{幕名}.wav | "读白文本" | | xiaoxiao | 平和 |
- ```
- ### 关键规范
- - 幕号从1开始连续编号
- - 文件名格式:`audio_{三位幕号}_{幕名}.wav`
- - **时长列为空**,由步骤5填充
- - 不限制幕数,根据内容需要决定
- - 每幕读白建议 1~3 句,每句 8~20 字,避免单幕文本过长导致动画拥挤
- - 动作节奏采用「句子拍点」:每句读白对应 1~2 个核心动画,不要一口气堆叠大量 Create/Transform
- ### 动画描述:使用读白关键词锚点(重要)
- 分镜的**动画**部分使用 `@[关键词]` 锚定读白中的句子,步骤4 TTS 生成后会自动产生每句话的精确时间戳(sync_points),步骤7中代码通过 `wait_for_narration("关键词")` 精确对齐。
- **不要写硬编码秒数**(如 `0.0s`, `3.0s`),因为 TTS 生成前无法预知准确时刻。
- ```markdown
- **动画**:
- - @[勾股定理]: 字幕"勾股定理"淡入
- - @[正方形]: 正方形高亮 → 字幕退场
- - @[所以]: 结论公式淡入,持续到幕末
- ```
- **`@[关键词]` 规则**:
- 1. 关键词取自**读白文本**中某句话的特征词(2~6字)
- 2. 同一幕内关键词不要重复
- 3. 步骤5验证后,可在同步点摘要中确认每个关键词的实际时间
- 4. 如果某动画不需要对齐读白(如幕首淡入),可以省略锚点
- ### 字幕退场约定
- 为了避免动画中文字忘记退场,在**动画**部分使用退场标记:
- **退场标记方式**(三选一):
- 1. `→` 箭头符号表示退场(推荐,最简洁)
- 2. `退场:` 或 `淡出:` 显式标记
- 3. `持续X秒` 指定显示时长
- **示例**:
- ```markdown
- **动画**:
- - @[正方形性质]: 字幕淡入,持续3秒 → 自动退场
- - @[勾股定理]: 标题淡入 → @[所以] 时退场
- - 幕末:所有文字退场
- ```
- ### 参考示例
- 见 `references/storyboard_sample.md` - 第九十九题:证明四点共圆
- ### 音画节奏预算(必填)
- 每一幕必须包含节奏预算(写在分镜的**动画**末尾):
- ```markdown
- **节奏预算**:
- - 音频时长 D: ___s(步骤5回填)
- - 读白句数: 3 句
- - 核心动画数: 3 个(每句读白对应 1~2 个动画)
- - 关键同步词: "三角形ABC", "内切圆", "切点"
- ```
- **执行原则**:
- - 单幕内重动画(Create/Transform 大对象)连续不超过 3 个
- - 每个关键结论后至少留 `0.2~0.4s` 的视觉停顿
- - 幕末收尾由 `end_scene_with_audio()` 自动补齐,不需要手动兜底
- - **禁止** `self.wait(max(..., duration - N))` 模式
- ---
- ## 步骤4:TTS 生成语音文件(含句级同步点)
- **使用脚本**:`scripts/generate_tts.py`(Edge TTS)
- 脚本通过 Edge TTS 的 `WordBoundary` 事件自动捕获每句话的起始时间,生成 `sync_points`。
- ### 执行命令
- ```bash
- python scripts/generate_tts.py audio_list.csv ./audio --voice xiaoxiao
- ```
- ### 输出文件
- ```
- audio/
- ├── audio_001_开场.wav
- ├── audio_002_展示图形.wav
- ├── audio_003_定理证明.wav
- ├── ...
- └── audio_info.json ← 含 sync_points
- ```
- ### audio_info.json 格式(含 sync_points)
- ```json
- {
- "files": [
- {
- "scene": 1,
- "file": "audio_001_开场.wav",
- "duration": 8.5,
- "sync_points": [
- {"idx": 0, "text": "大家好,今天我们来讲解一道经典的平面几何问题", "time": 0.0},
- {"idx": 1, "text": "证明四点共圆", "time": 3.2},
- {"idx": 2, "text": "这道题综合运用了切线长定理和双曲线的性质", "time": 4.8}
- ]
- },
- {
- "scene": 2,
- "file": "audio_002_展示图形.wav",
- "duration": 15.2,
- "sync_points": [
- {"idx": 0, "text": "首先,我们来看题目给出的图形", "time": 0.0},
- {"idx": 1, "text": "三角形 ABC 的内切圆 I", "time": 2.1},
- {"idx": 2, "text": "三角形内一点 K", "time": 7.4}
- ]
- }
- ]
- }
- ```
- **sync_points 说明**:
- - `idx`:句子在本幕中的序号(从 0 开始)
- - `text`:句子前 40 字(用于关键词匹配)
- - `time`:该句话在音频中的起始秒数(由 TTS WordBoundary 精确计算)
- - 在步骤7中通过 `self.wait_for_narration("关键词")` 查找 text 包含关键词的条目
- ---
- ## 步骤5:验证音频并查看同步点
- **使用脚本**:`scripts/validate_audio.py`
- ### 功能
- 1. 读取 `audio/audio_info.json` 获取音频时长
- 2. 验证所有音频文件存在且时长正常(>0秒)
- 3. 更新分镜脚本的"音频生成清单"中的时长列
- 4. **打印同步点摘要**:列出每幕的句级同步点及其时间戳
- 5. 如果缺少音频或时长异常,报错提醒
- ### 执行命令
- ```bash
- python scripts/validate_audio.py 分镜.md ./audio
- ```
- ### 输出示例(含同步点摘要)
- ```
- 🎯 同步点摘要(用于 wait_for_narration)
- ==================================================
- 第1幕 (8.5s):
- 0.00s │ "大家好,今天我们来讲解一道经典的平面几何问题"
- 3.20s │ "证明四点共圆"
- 4.80s │ "这道题综合运用了切线长定理和双曲线的性质"
- 第2幕 (15.2s):
- 0.00s │ "首先,我们来看题目给出的图形"
- 2.10s │ "三角形 ABC 的内切圆 I"
- 7.40s │ "三角形内一点 K"
- ```
- **此摘要是步骤7中选择 `wait_for_narration()` 关键词的依据。**
- ### 验证失败情况
- - 缺少音频文件 → 报错:"缺少第X幕音频文件"
- - 时长为0或异常 → 报错:"第X幕音频时长异常,请检查格式"
- - 分镜与音频数量不匹配 → 报错:"分镜X幕,音频Y个,数量不匹配"
- ---
- ## 步骤6:生成 script.py 脚手架
- **使用模板**:`templates/script_scaffold.py`
- **输出**:`script.py`(伪代码框架,由 AI 在步骤7完善)
- ### 脚手架核心方法一览
- | 方法 | 作用 | 调用位置 |
- |------|------|---------|
- | `calculate_geometry()` | 几何建模 | construct() |
- | `assert_geometry()` | 几何验证 + 画布范围 | construct() |
- | `define_elements()` | 定义 Manim 图形对象 | construct() |
- | `start_scene_with_audio(n)` | 播放音频 + 记录起始时间 | construct() 循环 |
- | `end_scene_with_audio(d)` | 自动补齐等待 | construct() 循环 |
- | `wait_for_narration(keyword)` | **等到读白说出关键词** | play_scene_X() |
- | `wait_until_scene_time(sec)` | 等到幕内指定时刻 | play_scene_X() |
- | `get_sync_time(keyword)` | 查找关键词时间(不等待) | play_scene_X() |
- ### 脚手架必须包含的部分
- ```python
- from manim import *
- import json
- import os
- class MathScene(Scene):
- """
- 数学教学视频场景 - 脚手架
- 根据分镜脚本和音频信息生成完整动画
- """
- # ========== 1. 颜色定义 ==========
- COLORS = {
- 'background': '#1a1a2e', # 深蓝背景
- 'primary': '#4ecca3', # 主色(青色)
- 'secondary': '#e94560', # 辅助色(红色)
- 'highlight': '#ffc107', # 高亮色(黄色)
- 'text': '#ffffff', # 文字白色
- 'grid': '#2a2a4e', # 网格线
- }
- # ========== 1b. 画布分区(防遮挡核心) ==========
- # 默认分区,可根据题目图形大小微调坐标,但必须保证各区互不重叠
- ZONES = {
- 'title': {'y_min': 3.0, 'y_max': 3.8, 'x_min': -6.5, 'x_max': 6.5, 'desc': '标题区(顶部)'},
- 'geometry': {'y_min': -2.2, 'y_max': 2.8, 'x_min': -5.0, 'x_max': 3.0, 'desc': '几何图形主区域(中偏左)'},
- 'subtitle': {'y_min': -3.8, 'y_max': -2.8, 'x_min': -6.5, 'x_max': 6.5, 'desc': '字幕区(底部)'},
- 'formula': {'y_min': -2.2, 'y_max': 2.8, 'x_min': 3.5, 'x_max': 6.5, 'desc': '公式/结论区(右侧)'},
- }
- # ========== 1c. z_index 层级定义(防遮挡核心) ==========
- # 数值越大越靠前(遮挡数值小的)
- Z_LAYERS = {
- 'bg_grid': 0, # 背景辅助线、网格
- 'fill': 1, # 填充色块(如三角形内部着色)
- 'geometry': 2, # 几何图形(线段、圆、多边形边框)
- 'label': 3, # 点标签、角标注(必须在图形之上)
- 'highlight': 4, # 高亮效果(闪烁、变色)
- 'subtitle': 5, # 字幕文字
- 'formula': 5, # 公式、推导步骤
- 'title': 6, # 标题
- }
- # ========== 2. 幕信息数组(供AI参考) ==========
- # 格式: (幕号, 幕名, 音频文件名, 时长秒数)
- # 注意:时长从 audio_info.json 读取,确保画面等待音频原则
- SCENES = [
- (1, "开场", "audio_001_开场.wav", None),
- (2, "展示图形", "audio_002_展示图形.wav", None),
- # ... 根据分镜动态生成
- ]
- def __init__(self, **kwargs):
- super().__init__(**kwargs)
- # 加载音频时长信息
- self.audio_timings = self._load_audio_timings()
- def _load_audio_timings(self):
- """从 audio_info.json 加载音频时长"""
- # TODO: AI实现 - 读取JSON并填充 SCENES 的时长
- pass
- # ========== 3. 几何计算函数 ==========
- def calculate_geometry(self):
- """
- 计算所有几何元素的位置和属性
- 从步骤2的HTML画图中提取信息,建立数学模型:
- - 所有点的坐标 (x, y) - ⚠️ 始终使用2D,z坐标始终为0
- - 边的长度和方程
- - 圆/弧的圆心和半径
- - 交点计算
- - 切线、法线等辅助线
- 返回: dict 包含所有几何对象的数据
- """
- # TODO: AI根据题目几何关系实现
- geometry = {
- 'points': {}, # {'A': (x, y), 'B': (x, y), ...}
- 'lines': {}, # {'AB': {'start': A, 'end': B, 'length': L}, ...}
- 'circles': {}, # {'circle1': {'center': O, 'radius': r}, ...}
- 'arcs': {}, # 圆弧定义
- }
- return geometry
- # ========== 4. 几何验证函数 ==========
- def assert_geometry(self, geometry):
- """
- 验证几何计算的正确性(最小验证原则)
- 验证内容:
- 1. 题目给定的事实(如:两条边相等,谁是谁的一半)
- 2. 精度问题:使用相对误差比较,而非绝对相等
- 3. 画布范围检查:确保图形在可视区域内
- 4. 错误提示:所有assert必须用中文描述问题,包含具体数值和修复建议
- === 几何条件验证 ===
- 基于题目给定的条件,编写最小但关键的验证:
- - 如果题目说 AB = BC,验证 |AB - BC| < epsilon
- - 如果题目说 E 是中点,验证 AE = EB(考虑浮点误差)
- - 如果题目说某角是直角,验证向量点积接近0
- - 如果题目给具体数值(如边长为5),验证计算结果匹配
- 精度建议:
- - 相对误差:1e-6 或绝对误差 1e-4
- - 示例:assert abs(len_AB - len_BC) < 1e-4, "中文错误提示:AB长度不等于BC长度"
- === 画布范围验证算法 ===
- 目标:确保整个图形在画布内,且位于视觉中心区域
- 算法步骤(AI需要根据几何数据实现):
- 1. 计算所有几何元素的外接矩形 bounding_box
- - 遍历所有点、线、圆的边界点
- - 取最小x, 最大x, 最小y, 最大y
- 2. 验证矩形在画布范围内(考虑边距)
- - 画布默认范围:FRAME_WIDTH=14.2, FRAME_HEIGHT=8
- - 建议边距:四周各留 0.5-1.0 单位
- - 验证:min_x > -7+margin 且 max_x < 7-margin
- min_y > -4+margin 且 max_y < 4-margin
- 3. 验证矩形中心在视觉中心区域
- - 画布中心:(0, 0)
- - 视觉中心区域:中心 ±20%(即 x∈[-1.4, 1.4], y∈[-0.8, 0.8])
- - 计算矩形中心:(center_x, center_y) = ((min_x+max_x)/2, (min_y+max_y)/2)
- - 验证:center_x ∈ [-1.4, 1.4] 且 center_y ∈ [-0.8, 0.8]
- 4. 如果图形超出范围,AI需要调整几何计算的缩放或平移
- """
- # === TODO: AI实现 - 基于题目条件的验证(失败时用中文报错)===
- # 示例代码(根据实际题目修改):
- # epsilon = 1e-4
- # len_ab = geometry['lines']['AB']['length']
- # len_bc = geometry['lines']['BC']['length']
- # assert abs(len_ab - len_bc) < epsilon, f"几何验证失败:AB长度({len_ab:.4f})不等于BC长度({len_bc:.4f}),题目要求两边相等"
- #
- # len_ae = geometry['lines']['AE']['length']
- # len_ab = geometry['lines']['AB']['length']
- # assert abs(len_ae * 2 - len_ab) < epsilon, f"几何验证失败:E不是AB中点,AE({len_ae:.4f})*2={len_ae*2:.4f} != AB({len_ab:.4f})"
- # === TODO: AI实现 - 画布范围检查(失败时用中文报错)===
- # 1. 计算bounding_box
- # all_points = list(geometry['points'].values())
- # min_x = min(p[0] for p in all_points)
- # max_x = max(p[0] for p in all_points)
- # min_y = min(p[1] for p in all_points)
- # max_y = max(p[1] for p in all_points)
- #
- # 2. 验证画布边界(失败时报具体数值)
- # margin = 0.5
- # assert min_x > -7 + margin, f"画布验证失败:图形左边界(min_x={min_x:.2f})超出安全区域(>{-7+margin}),需要向右平移或缩小"
- # assert max_x < 7 - margin, f"画布验证失败:图形右边界(max_x={max_x:.2f})超出安全区域(<{7-margin}),需要向左平移或缩小"
- # assert min_y > -4 + margin, f"画布验证失败:图形下边界(min_y={min_y:.2f})超出安全区域(>{-4+margin}),需要向上平移或缩小"
- # assert max_y < 4 - margin, f"画布验证失败:图形上边界(max_y={max_y:.2f})超出安全区域(<{4-margin}),需要向下平移或缩小"
- #
- # 3. 验证视觉中心(失败时报具体偏移)
- # center_x = (min_x + max_x) / 2
- # center_y = (min_y + max_y) / 2
- # assert -1.4 <= center_x <= 1.4, f"视觉中心验证失败:图形中心X={center_x:.2f}超出视觉中心区域[-1.4, 1.4],建议调整几何计算使图形居中"
- # assert -0.8 <= center_y <= 0.8, f"视觉中心验证失败:图形中心Y={center_y:.2f}超出视觉中心区域[-0.8, 0.8],建议调整几何计算使图形居中"
- pass
- # ========== 5. 图形元素定义 ==========
- def define_elements(self, geometry):
- """
- 定义 Manim 图形对象(但不创建动画)
- ⚠️ 必须遵守步骤7「防遮挡规范」:z_index层级、标签偏移、分区放置
- """
- # TODO: AI根据分镜需求定义
- elements = {
- 'points': {}, # Mobject 点对象
- 'lines': {}, # Mobject 线对象
- 'circles': {}, # Mobject 圆对象
- 'labels': {}, # 标签文字
- }
- return elements
- # ========== 6. 构造主流程 ==========
- def construct(self):
- """主构造流程"""
- # 计算几何
- geometry = self.calculate_geometry()
- self.assert_geometry(geometry)
- elements = self.define_elements(geometry)
- # 设置背景
- self.camera.background_color = self.COLORS['background']
- # 按幕执行
- for scene_num, scene_name, audio_file, duration in self.SCENES:
- self.play_scene(scene_num, scene_name, audio_file, duration, elements, geometry)
- def play_scene(self, scene_num, scene_name, audio_file, duration, elements, geometry):
- """
- 播放单幕动画 - 必须与统一时间轴护栏配合
- ========== 音频集成(强制要求) ==========
- 每幕必须添加对应的音频文件,否则视频将没有声音。
- 但推荐在 construct() 中统一调用 start_scene_with_audio(scene_num),
- 不要在每个 play_scene_X() 里重复散落 add_sound 逻辑。
- 统一入口:
- expected_duration = self.start_scene_with_audio(scene_num)
- self.play_scene_X(...)
- self.end_scene_with_audio(expected_duration, safety_margin=0.2)
- 注意:
- - audio_file 参数已经包含文件名(如 "audio_001_开场.wav")
- - 音频文件位于 audio/ 目录下
- - 不要手工估算“本幕动画共几秒”,以 self.time 实际耗时为准
- ========== 画面等待音频原则 ==========
- - 动画总时长由 end_scene_with_audio 自动兜底到 >= 音频时长
- - 可以画面多等待(多出静音部分,后期可剪辑)
- - 不能画面比音频短(会导致音频被截断)
- ========== 高亮规范(必须在读白提到时同步) ==========
- - 提到某个边等于某个边 → 用动画高亮两条边
- - 提到某个点/圆 → 闪烁或放大高亮
- - 提到证明结论 → 用框或颜色强调
- ========== 绘制策略 ==========
- - 简单图形:直接显示,然后高亮关键部分
- - 复杂图形:逐步绘制,边画边讲解
- """
- # TODO: AI实现 - 只写本幕视觉动作,音频起止由统一护栏方法负责
- pass
- # ========== 7. 同步对齐工具(核心新增) ==========
- def wait_until_scene_time(self, target_time):
- """等待到当前幕内指定时刻(相对于幕开始的秒数)"""
- # 脚手架已实现,见 templates/script_scaffold.py
- pass
- def wait_for_narration(self, keyword):
- """
- 等到读白说出包含 keyword 的那句话时刻。
- 从 audio_info.json 的 sync_points 中查找匹配。
- 用法示例:
- self.wait_for_narration("内切圆")
- self.play(FadeIn(incircle))
- """
- # 脚手架已实现,见 templates/script_scaffold.py
- pass
- def get_sync_time(self, keyword):
- """查找关键词的时间戳(不等待),返回 float 或 None"""
- pass
- ```
- ---
- ## 步骤7:AI 生成最终代码
- **输入**:
- - 分镜脚本(已更新时长)
- - `audio/audio_info.json`(含 sync_points)
- - `script.py` 脚手架
- - 步骤5输出的同步点摘要
- **输出**:完整的 `script.py`
- **AI 生成指导**:
- 1. 根据分镜的"动画"描述实现具体动画代码
- 2. **使用 `wait_for_narration("关键词")` 对齐读白和高亮**(参考步骤5的同步点摘要选择关键词)
- 3. 实现 `calculate_geometry()` 的具体计算
- 4. 实现 `assert_geometry()` 的验证逻辑
- 5. 为每幕实现 `play_scene_X()` 方法
- 6. **音频集成(必须,防重叠)**:
- - 在 `construct()` 的每幕循环中统一执行:
- - `expected_duration = self.start_scene_with_audio(scene_num)`
- - `play_scene_X(...)`
- - `self.end_scene_with_audio(expected_duration, safety_margin=0.2)`
- - `play_scene_X()` 内专注视觉动作,不手工累计总时长
- 7. 验证音频文件路径正确:`audio/audio_001_XXX.wav`
- 8. **字幕显示与退场(关键)**:
- - 使用 `show_subtitle_timed(text, duration)` 或 `show_subtitle_with_audio(text, audio_duration)`
- - 分镜中的 `→` 或 `退场:` 标记表示文字退场
- - **必须确保所有文字元素都有退场动画**
- ### 禁止事项(步骤7)
- | 禁止 | 替代方案 |
- |------|---------|
- | `self.wait(max(..., duration - N))` | 删除手动兜底,由 `end_scene_with_audio()` 自动补齐 |
- | 硬编码 `self.wait(3.7)` 对齐读白 | 使用 `self.wait_for_narration("关键词")` |
- | 在 `play_scene_X()` 中调用 `add_sound()` | 由 `start_scene_with_audio()` 统一管理 |
- | 手动估算 `animation_time` 判断切幕 | 由 `end_scene_with_audio()` 自动处理 |
- ### 防遮挡规范(步骤7必须遵守)
- 动画元素相互遮挡是最常见的视觉问题。以下规则**必须严格执行**。
- #### 规则1:画布分区 — 不同类型元素各归其位
- 脚手架中的 `ZONES` 定义了默认分区(可根据题目微调坐标,但**必须保证各区互不重叠**):
- | 区域 | 放置内容 | 核心约束 |
- |------|---------|---------|
- | **标题区**(顶部) | 幕标题 | 幕切换时替换旧标题 |
- | **几何区**(中偏左) | 图形、点、线、圆、标签 | 主图形区,偏左留出右侧公式空间 |
- | **字幕区**(底部) | 字幕文字 | 字幕**必须**在底部(y ≈ -3.3),**禁止**放画布中央 |
- | **公式区**(右侧) | 公式、推导、结论 | **禁止**与几何图形重叠;图形偏右时可将公式区换到左侧 |
- #### 规则2:z_index 层级 — 每个 Mobject 必须设置
- 使用脚手架 `Z_LAYERS` 常量,创建后**立即**调用 `set_z_index()`:
- ```python
- line_AB = Line(A, B, color=WHITE)
- line_AB.set_z_index(self.Z_LAYERS['geometry']) # 层级2
- label_A = Text("A", font_size=28).next_to(dot_A, UR, buff=0.15)
- label_A.set_z_index(self.Z_LAYERS['label']) # 层级3,在线段之上
- # ❌ 忘记 set_z_index → 标签可能被后绘制的线段遮挡
- ```
- **层级从后到前**:背景(0) → 填充(1) → 几何(2) → 标签(3) → 高亮(4) → 字幕/公式(5) → 标题(6)
- #### 规则3:点标签防碰撞
- 1. **方向偏移**:`next_to(dot, 方向, buff=0.15~0.25)`,**禁止**把标签放在点的精确坐标
- 2. **方向选择**:标签朝远离密集线段/元素的方向(如三角形内角处标签朝外)
- 3. **背景衬底**:标签可能与线段接近时,加 `label.add_background_rectangle(color=bg_color, opacity=0.85, buff=0.06)`
- 4. **间距检查**:两标签间距 < 0.3 时,调整方向或增大 buff
- #### 规则4:元素生命周期 — 及时退场防堆叠
- ```python
- # 字幕:必须配对退场
- self.play(FadeIn(subtitle))
- self.wait_for_narration("关键词")
- self.play(FadeOut(subtitle)) # ❌ 漏掉这行 → 字幕堆叠
- # 公式替换:先退旧再入新
- self.play(FadeOut(old_formula), FadeIn(new_formula))
- # 高亮:不再需要时恢复原色(如果需要持续高亮则可保留,但确保不遮挡后续元素)
- self.play(line_AB.animate.set_color(YELLOW))
- # ...讲解完毕后...
- self.play(line_AB.animate.set_color(WHITE))
- ```
- **幕末清理**:每幕结束前,将不需要带入下一幕的元素统一 FadeOut。
- #### 规则5:同区域冲突预防
- 1. **多公式纵向排列**:`VGroup(...).arrange(DOWN, buff=0.3)`
- 2. **字幕排队**:多条字幕**依次显示**(先退场再入场),禁止同时可见
- 3. **同一位置禁止堆叠** 2 个及以上可见文字元素
- ---
- ## 步骤8:代码检查与渲染
- ### 8.1 代码结构检查(必须)
- **使用脚本**:`scripts/check.py`
- 在渲染之前,必须先检查代码是否包含必要的函数和结构:
- ```bash
- # 检查 script.py(默认)
- python scripts/check.py
- # 检查指定文件
- python scripts/check.py my_script.py
- ```
- **检查内容**:
- 1. ✅ `calculate_geometry()` - 几何计算函数是否存在
- 2. ✅ `assert_geometry()` - 几何验证函数是否存在
- 3. ✅ `define_elements()` - 图形元素定义函数是否存在
- 4. ✅ 字幕类 `Subtitle` / `TitleSubtitle` 是否存在
- 5. ✅ 是否有 `add_sound()` 调用(音频集成)
- 6. ✅ 是否有继承 `Scene` 的类
- 7. ✅ 是否使用了 `wait_for_narration()` 或 `wait_until_scene_time()` 同步方法
- 8. ✅ 是否存在 `self.wait(max(..., duration - N))` 反模式
- 9. ⚠️ 防遮挡(需人工审查代码):Mobject 是否设置了 `set_z_index()`、字幕是否在底部、字幕是否配对 FadeOut、标签是否用 `next_to()` 偏移
- **检查结果**:
- - ❌ 错误:必须修复,否则无法渲染
- - ⚠️ 警告:建议修复,但不会阻止渲染
- ### 8.2 渲染视频
- #### 方式1:使用渲染脚本(推荐,包含检查)
- ```bash
- # 完整流程:检查 -> 渲染 -> 拷贝到根目录
- python scripts/render.py
- # 指定文件和场景
- python scripts/render.py -f script.py -s MathScene
- # 指定渲染质量
- python scripts/render.py -q h # 1080p60 (默认)
- python scripts/render.py -q k # 4K
- python scripts/render.py -q m # 720p30
- # 跳过检查(不推荐,仅用于快速测试)
- python scripts/render.py --no-check
- ```
- #### 方式2:直接使用 manim(跳过检查,不推荐)
- ```bash
- manim -pqh script.py MathScene
- ```
- ### 提取关键帧验证
- ```bash
- python scripts/extract_frames.py media/videos/script/1080p60/MathScene.mp4 --interval 5
- ```
- ### 验证内容
- 1. 几何图形是否正确(点、线、圆位置)
- 2. 高亮是否与讲解同步
- 3. 字幕是否清晰可读
- 4. 动画是否流畅
- 5. **防遮挡检查**(关键帧逐帧确认):
- - 点标签是否被线段/圆弧遮挡?
- - 字幕是否与几何图形重叠?
- - 多个文字元素是否堆叠在同一位置?
- - 公式/结论是否侵入几何区域?
- 5. **音频是否正确添加**:
- - 每幕都有声音(没有静音幕)
- - 音频与分镜中的读白内容一致
- - 每幕末 `elapsed >= audio_duration + safety_margin`(没有抢跑切幕)
- - 没有出现上一幕音频未结束就进入下一幕的重叠
- ### 渲染后必须执行
- ```python
- # 在construct()最后添加:拷贝视频到根目录
- import shutil
- import os
- from pathlib import Path
- # 渲染完成后拷贝到根目录
- video_src = Path("media/videos/script/1920p60/SquareTriangleProblem.mp4")
- video_dst = Path("最终视频.mp4")
- if video_src.exists():
- shutil.copy2(video_src, video_dst)
- print(f"✓ 视频已拷贝到: {video_dst}")
- ```
- **规则:渲染完成后必须将视频拷贝到项目根目录**,不要留在media/深处。
- ### 如果发现问题
- - 回到步骤7修改代码
- - 重新渲染验证
- ---
- ## 数学解题原则(绝对重要)
- ### ❌ 禁止使用坐标系
- **绝不用坐标系来求解**,应该用各种定义和推理。
- **错误示例**(坐标法):
- ```
- 设B=(0,0), C=(5,0), A=(1.8, 2.4)...
- 面积 = ½ × 底 × 高
- ```
- **正确示例**(几何推理):
- ```
- 1. 由勾股定理:BC = √(AB² + AC²) = 5
- 2. 正方形性质:BE = BC = 5
- 3. 等积变换:S△ABE = S△ABC × (EB/BC) × sin(∠ABE)/sin(∠ABC)
- 4. 或用向量叉积、海伦公式等纯几何方法
- ```
- **允许的可视化辅助**:
- - 为了动画展示可以显示坐标,但解题过程不能用坐标计算
- - 可以用几何画板的思路:旋转、平移、对称等变换
- ### 推荐的几何推理方法
- 1. **等积变换** - 同底等高、等底同高
- 2. **相似三角形** - 比例关系
- 3. **勾股定理** - 边长关系
- 4. **向量/叉积** - 纯几何意义的运算
- 5. **旋转/对称** - 几何变换
- ---
- ## 文件结构
- ```
- tutor/
- ├── SKILL.md # 本文件 - 工作流程定义
- ├── requirements.txt # Python 依赖
- ├── references/
- │ └── storyboard_sample.md # 分镜脚本示例(参考)
- ├── templates/
- │ └── script_scaffold.py # Manim 脚手架模板(含字幕类)
- ├── scripts/
- │ ├── generate_tts.py # TTS 生成脚本
- │ ├── validate_audio.py # 音频验证脚本
- │ ├── check.py # 代码结构检查脚本(渲染前必执行)
- │ └── render.py # 渲染流水线脚本(检查+渲染+拷贝)
- └── sample/ # 示例项目(保留参考)
- └── geometry_proof/
- ```
- ---
- ## 依赖管理
- 使用 `uv` 管理依赖:
- ```bash
- # 创建虚拟环境
- uv venv .venv
- # 安装依赖
- uv pip install -r requirements.txt
- # 激活环境
- source .venv/bin/activate
- ```
- ---
- ## 绕过LaTeX依赖(重要)
- Manim默认需要LaTeX来渲染数学公式。如果不想安装LaTeX,**全部使用Text替代MathTex**:
- ```python
- # ❌ 需要LaTeX
- MathTex(r"BC^2 = AB^2 + AC^2")
- MathTex(r"\frac{1}{2} \times 5")
- MathTex("A") # 甚至连字母都需要LaTeX
- # ✅ 不需要LaTeX
- Text("BC² = AB² + AC²", font_size=36)
- Text("½ × 5", font_size=30)
- Text("A", font_size=32) # 用Text直接显示字母
- ```
- **常用替换对照表**:
- | 数学符号 | LaTeX写法 | 无LaTeX写法 |
- |---------|----------|------------|
- | 上标 | `x^2` | `x²` (直接输入Unicode) |
- | 分数 | `\frac{1}{2}` | `½` 或 `1/2` |
- | 度数 | `90^\circ` | `90°` |
- | 平方厘米 | `\text{cm}^2` | `cm²` |
- | 根号 | `\sqrt{25}` | `√25` |
- | 角度 | `\angle A` | `∠A` |
- **脚手架默认不使用MathTex**,如需数学公式请直接输入Unicode字符。
- ---
- ## 关键原则总结
- | 原则 | 说明 |
- |------|------|
- | **数学先行** | 先建立正确的数学模型,再画图 |
- | **音频必填** | 每幕必须调用 `self.add_sound()`,否则视频无声音 |
- | **句级同步** | 使用 `wait_for_narration("关键词")` 精确对齐读白和高亮(精度 ±0.3s) |
- | **高亮对应** | 配音提到什么,画面高亮什么 |
- | **自动补齐** | 幕末由 `end_scene_with_audio()` 自动补齐,禁止 `duration - N` 手动兜底 |
- | **最小验证** | `assert_geometry` 验证题目条件(带精度) + 画布范围(边界+中心) |
- | **防遮挡** | 画布分区(标题/几何/字幕/公式) + z_index层级 + 标签偏移 + 及时退场 |
- | **逐步抽象** | 从 HTML 可视化 → 分镜脚本 → Manim 代码 |
README.md · README · 279 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # MathLens
- <div align="right">
- <a href="#chinese">中文</a> | <a href="#english">English</a>
- </div>
- ---
- <a id="chinese"></a>
- # MathLens — AI 数学教学视频制作
- > 将一道数学题,变成一支有声有画的教学视频。
- MathLens 是一个运行在 Cursor AI 中的 **Agent Skill**。你只需粘贴一道数学题(图片或文字),它就能自动完成从题目分析、可视化讲解、配音脚本到 Manim 动画视频的全流程制作。
- ---
- ## 演示
- ### 输入:一道数学题截图
- 
- ### 输出:带配音的 Manim 教学动画
- <video src="resource/output.mp4" controls width="100%"></video>
- > 提示:如视频无法预览,可直接下载 [output.mp4](resource/output.mp4) 观看。
- ---
- ## 亮点
- - **全自动流水线**:8 步工作流一气呵成,无需手动拼接工具
- - **深入浅出**:AI 以一对一家教的方式拆解题目,适合普通学情的学生
- - **SVG 可视化讲解**:自动生成带几何标注的 HTML 文档,随时预览
- - **真人感配音**:基于 edge-tts 生成自然语音,支持选择音色(默认晓晓)
- - **画面音频精准同步**:`wait_for_narration(keyword)` 机制让动画在读白说出关键词时精准触发
- - **几何自校验**:内置 `assert_geometry()` 验证坐标正确性,防止画出错误图形
- - **Manim 动画视频**:渲染输出专业级数学教学视频
- ---
- ## 核心工作流
- ```
- 题目输入
- │
- ▼
- ① 数学分析 → 推导已知/结论,建立几何模型
- │
- ▼
- ② HTML 可视化 → SVG 绘图 + 步骤标注,生成讲解页面
- │
- ▼
- ③ 分镜脚本 → 定义幕结构,设计画面 / 字幕 / 读白
- │
- ▼
- ④ TTS 生成 → 生成每幕 .wav 音频 + 同步点索引
- │
- ▼
- ⑤ 音频验证 → 校验时长,回写分镜脚本
- │
- ▼
- ⑥ 代码脚手架 → 生成 Manim 框架(几何建模 + 场景结构)
- │
- ▼
- ⑦ 动画实现 → 按分镜逐幕实现动画,对齐读白同步点
- │
- ▼
- ⑧ 渲染验证 → 输出视频 + 关键帧截图,失败自动修复
- ```
- ---
- ## 快速开始
- ### 前置依赖
- ```bash
- pip install uv manim edge-tts
- ```
- ### 初始化项目
- ```bash
- python init.py ./my_math_problem
- ```
- ### 触发 Skill
- 在 Cursor 对话中,直接粘贴题目图片或描述即可:
- ```
- (粘贴数学题截图)
- 帮我讲解这道题,生成教学视频。
- ```
- AI 会自动按 8 步工作流完成制作。
- ---
- ## 手动运行脚本
- ```bash
- # 生成 TTS 音频
- python scripts/generate_tts.py audio_list.csv ./audio --voice xiaoxiao
- # 验证音频并回写分镜时长
- python scripts/validate_audio.py 分镜.md ./audio
- # 检查 Manim 代码结构
- python scripts/check.py
- # 渲染视频
- python scripts/render.py
- ```
- ---
- ## 目录结构
- ```
- MathLens/
- ├── README.md # 本文档
- ├── SKILL.md # Agent Skill 主文件(给 Cursor AI 读的)
- ├── init.py # 项目初始化脚本
- ├── resource/ # 演示素材
- │ ├── input.png # 示例输入题目
- │ └── output.mp4 # 示例输出视频
- ├── scripts/
- │ ├── generate_tts.py # TTS 音频生成
- │ ├── validate_audio.py # 音频验证 & 分镜回写
- │ ├── check.py # Manim 代码结构检查
- │ └── render.py # 视频渲染
- ├── templates/
- │ └── script_scaffold.py # Manim 脚手架模板
- ├── references/ # 分镜脚本示例
- └── sample/ # 早期风格探索参考
- ```
- ---
- ## 开源协议
- 本项目采用 **CC BY-NC 4.0(署名—非商业性使用 4.0 国际)** 协议。
- - **个人学习 / 教育用途**:免费使用,欢迎分享
- - **商业用途**:须获得作者书面授权,未经授权不得用于商业目的
- > [Creative Commons Attribution-NonCommercial 4.0 International](https://creativecommons.org/licenses/by-nc/4.0/)
- ---
- ---
- <a id="english"></a>
- # MathLens — AI Math Teaching Video Generator
- > Turn a math problem into a narrated, animated teaching video.
- MathLens is a **Cursor Agent Skill**. Just paste a math problem (image or text), and it automatically handles the full pipeline: problem analysis → visual explanation → voiceover scripting → Manim animation video.
- ---
- ## Demo
- ### Input: A math problem screenshot
- 
- ### Output: Narrated Manim animation
- <video src="resource/output.mp4" controls width="100%"></video>
- > If the video doesn't preview, download [output.mp4](resource/output.mp4) directly.
- ---
- ## Highlights
- - **Fully automated pipeline**: 8-step workflow from image to video, no manual glue needed
- - **Student-friendly explanations**: AI tutors step-by-step like a 1-on-1 teacher
- - **SVG visual explanations**: Auto-generates annotated HTML documents for instant preview
- - **Natural-sounding voiceover**: Powered by edge-tts with selectable voices (default: Xiaoxiao)
- - **Frame-accurate audio sync**: `wait_for_narration(keyword)` triggers animations exactly when the narration says the keyword
- - **Geometry self-validation**: Built-in `assert_geometry()` verifies coordinates to prevent incorrect diagrams
- - **Professional Manim video output**: Renders polished math teaching videos
- ---
- ## Core Workflow
- ```
- Problem Input
- │
- ▼
- ① Math Analysis → Derive facts, build geometric model
- │
- ▼
- ② HTML Visual → SVG diagram + step annotations
- │
- ▼
- ③ Storyboard → Define scenes, design visuals / subtitles / narration
- │
- ▼
- ④ TTS Audio → Generate per-scene .wav + sync point index
- │
- ▼
- ⑤ Audio Validate → Verify durations, write back to storyboard
- │
- ▼
- ⑥ Scaffold → Generate Manim framework (geometry + scene structure)
- │
- ▼
- ⑦ Animation Code → Implement scene-by-scene, aligned to narration sync points
- │
- ▼
- ⑧ Render & Check → Output video + keyframes; auto-retry on failure
- ```
- ---
- ## Quick Start
- ### Prerequisites
- ```bash
- pip install uv manim edge-tts
- ```
- ### Initialize a project
- ```bash
- python init.py ./my_math_problem
- ```
- ### Trigger the Skill
- In Cursor, paste a problem image or description:
- ```
- (paste math problem screenshot)
- Please explain this problem and generate a teaching video.
- ```
- The AI will automatically run the full 8-step pipeline.
- ---
- ## Run Scripts Manually
- ```bash
- # Generate TTS audio
- python scripts/generate_tts.py audio_list.csv ./audio --voice xiaoxiao
- # Validate audio and write durations back to storyboard
- python scripts/validate_audio.py storyboard.md ./audio
- # Check Manim code structure
- python scripts/check.py
- # Render video
- python scripts/render.py
- ```
- ---
- ## License
- This project is licensed under **CC BY-NC 4.0 (Attribution-NonCommercial 4.0 International)**.
- - **Personal / educational use**: Free to use and share
- - **Commercial use**: Requires written permission from the author
- > [Creative Commons Attribution-NonCommercial 4.0 International](https://creativecommons.org/licenses/by-nc/4.0/)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.