Remotion 数学讲解视频生成器 (remotion-math-explainer)
概述
将任何数学推导、定理、证明或幻灯片转化为沉浸式的、帧同步的 1920×1080 30fps MP4 Remotion 讲解视频,格式为 单面板 Log2Base2 工作室格式。
绝不将屏幕分割为并排面板或堆叠的文本卡片墙。每个视频只使用 一个统一的视觉舞台 (<SinglePaneStage>) ,确保观众的全部注意力始终锁定在视觉故事上:
- 极简顶部栏(
44px,内置于SinglePaneStage):- 左侧显示主题标题 + 当前活跃章节标签;右侧显示微妙的步骤计数器 + 细进度条。
- 一个统一的 Log2Base2 舞台(
SinglePaneStage— 100% 宽度):- 聚焦的单行聚光灯头部:仅显示 当前步骤标题 和 单条活跃的方程行(使用
borderBottom: "2px solid #FACC15"内联高亮当前口语词汇,不添加任何水平内边距),外加 一个 紧凑的活跃令牌标注胶囊(符号→通俗含义),在triggerFrame时刻弹入。 - 全宽沉浸式 SVG 画布(
viewBox="0 0 1600 680"):宽敞、连续的运动图形——实时坐标网格带彩色数据点伸缩变化、数字从矩阵中物理滑出形成次要模块、扫射激光划线、带符号的量值条,以及 3D 单位立方体扭曲回单位矩阵——所有这些都直接集成在同一个开放画布上。
- 聚焦的单行聚光灯头部:仅显示 当前步骤标题 和 单条活跃的方程行(使用
- 极简底部字幕栏(
VoiceoverCaptionBar—68px):- 干净的居中卡拉 OK 逐词高亮字幕,由精确的 TTS
WordBoundary毫秒时间戳驱动。
- 干净的居中卡拉 OK 逐词高亮字幕,由精确的 TTS
依赖
remotion-best-practices(~/.gemini/skills/remotion/SKILL.md):必须遵循所有 Remotion 动画规则(useCurrentFrame()、interpolate()、spring()、<Sequence premountFor>、<Audio>、@remotion/google-fonts,以及零 CSS 过渡)。uv(~/.gemini/config/plugins/science/skills/uv/SKILL.md):用于运行神经语音合成(uv run --with edge-tts)。
快速开始
# 1. 搭建 Remotion 数学讲解项目
uv run python3 \
~/.gemini/config/skills/remotion-math-explainer/scripts/explainer_cli.py \
scaffold \
--project-dir "/path/to/project" \
--output "/path/to/project/scaffold-status.json"
# 2. 合成自然神经语音旁白 + 精确的词边界和时间戳
uv run --with edge-tts python3 \
~/.gemini/config/skills/remotion-math-explainer/scripts/explainer_cli.py \
synthesize-voiceover \
--project-dir "/path/to/project" \
--beats-json "/path/to/project/beats.json" \
--voice "en-US-AndrewNeural" \
--rate "+2%" \
--pause-sec 0.40 \
--output "/path/to/project/public/voiceover/manifest.json"
# 3. 通过快速 8 工作线程键帧去重渲染器输出最终 1080p 30fps MP4
uv run python3 \
~/.gemini/config/skills/remotion-math-explainer/scripts/explainer_cli.py \
render-mp4 \
--project-dir "/path/to/project" \
--composition-id "MathExplainer" \
--out-name "MathExplainer.mp4" \
--concurrency 8 \
--output "/path/to/project/render-report.json"
沉浸式叙事与工作流程
- 设计动态节拍(
beats.json):- 编写对话式、以钩子开头的叙述(避免枯燥的教科书式表述),使即便是缺乏动力的学生也能保持兴趣。
- 保持
snippet为 2-4 行简洁文字,其中每个token逐字出现在一行中,并与text中干净的小写triggerWord匹配。 - 对于包含连续曲线、向量、网格或飞行元素动画的节拍,设置
"motionStepFrames": 2。
- 搭建项目与合成语音旁白:
- 运行
scaffold(复制SinglePaneStage.tsx、VoiceoverCaptionBar.tsx和render_full_mp4.mjs)和synthesize-voiceover(通过scripts/explainer_cli.py)。
- 运行
- 编写全画布运动图形(
viewBox="0 0 1600 680"):- 将您的沉浸式 SVG 舞台作为
children传递给<SinglePaneStage>。 - 展示,而非讲述:用物理动画替代静态文本/卡片——粒子/点随坐标扭曲运动、元素在位置间飞入、扫射激光线、实时仪表盘,以及在同一 开放画布 中的并排实时图。
- 始终将扭曲/扩展的网格线包裹在
<clipPath>内,使动画不会溢出到标签或胶囊上。
- 将您的沉浸式 SVG 舞台作为
- 验证单帧并渲染最终 MP4:
- 运行
npm run lint并使用read_file检查代表性单帧(npx remotion still),然后再运行render-mp4。 - 将最终的
.mp4文件复制到out/目录、项目根目录以及工作区根目录。
- 运行
速率限制与常见错误
scripts/explainer_cli.py强制执行/tmp/remotion_edge_tts.lock(间隔0.35s,3 次重试,退避时间为1s/2s/4s)。- 绝不 使用多面板分屏布局或堆叠带边框的子卡片——始终使用
<SinglePaneStage>,确保屏幕上严格 只有一个 主面板。 - 绝不 一次性将完整的多步骤证明全部显示在屏幕上;一次只高亮一条活跃的方程行和一个活跃的标注胶囊。
- 绝不 对高亮的内联令牌添加水平
padding(仅使用borderBottom: "2px solid #FACC15"和backgroundColor)。