Communitygithub.com

textbook-to-animation

Video and animation skill. 把教材、技术书、课程讲义的章节改编成 Motion Canvas + Manim 动画讲解视频的完整流程——分级要点清单、教学设计、旁白先行的分镜(beat sheet)、MC/Manim 分工、音频驱动的场景实现、无头渲染与拼接混音,以及以原文为准的多轮“生成 → 审查(忠实 / 反查原文 / 语义 / 观感)→ 修改”迭代(每轮产物单独保留便于对比)和静态 lint。只要用户要把书或论文的某一章、某一节做成动画或讲解视频,要为这类视频写脚本、分镜、场景代码,或要对这类视频做质量 review,或在提到 Motion Canvas、Manim 的同时提到书、章节、教材、知识点,就使用本 skill,即使用户没提“流程”或“skill”。Turns textbook chapters into animated explainer videos with Motion Canvas and Manim.

What is textbook-to-animation?

textbook-to-animation is a Claude Code agent skill that video and animation skill. 把教材、技术书、课程讲义的章节改编成 Motion Canvas + Manim 动画讲解视频的完整流程——分级要点清单、教学设计、旁白先行的分镜(beat sheet)、MC/Manim 分工、音频驱动的场景实现、无头渲染与拼接混音,以及以原文为准的多轮“生成 → 审查(忠实 / 反查原文 / 语义 / 观感)→ 修改”迭代(每轮产物单独保留便于对比)和静态 lint。只要用户要把书或论文的某一章、某一节做成动画或讲解视频,要为这类视频写脚本、分镜、场景代码,或要对这类视频做质量 review,或在提到 Motion Canvas、Manim 的同时提到书、章节、教材、知识点,就使用本 skill,即使用户没提“流程”或“skill”。Turns textbook chapters into animated explainer videos with Motion Canvas and Manim.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/hustnn/cs_book_animation_code/tree/HEAD/skills/textbook-to-animation

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

教材 → 动画讲解视频

目标:通俗易懂,同时不丢深度和完整性。 这三者之间的张力,靠三种载体分工来解决:

载体负责什么不该负责什么
画面(动画)机制、结构、因果、数量级、“为什么”——观众看得见的东西长句、定义全文、清单
旁白(TTS 配音)论证、定义、例子、证据、限定条件——要点覆盖的主要载体只有画面才能讲清的过程
屏幕文字锚点:术语、关键数字、一句结论(同屏 ≤ 3 行)代替旁白

为什么这样分:如果把“每条要点都要以画面文字出现”当作验收标准,视频就会退化成会动的 PPT—— 大半时长是文字卡,动画播完就静止,观众一边读字一边看图,两样都顾不上; 而且只核对文字的审查,会漏掉“画面和文字意思相反”这类错误。 这些失败模式和对应规则的来由,见 references/failure-modes.md。

贯穿全程的两条原则

  1. 原文是唯一的权威,其余都是 outline。 inventory、design、beats 都是对原文的有损压缩。 只照着它们生成,它们漏掉的东西动画里就不会有;审查时再拿同一份清单去对,也查不出来。 所以写分镜、写场景代码、做审查时,都要回到对应的原文页(含图、图注、侧栏、脚注)。 发现原文里有、清单里没有的内容,先补进清单(标注“rN 补”),再往下改。
  2. 多轮迭代,每轮完整保留。 “生成 → 审查 → 修改”按轮次循环,每轮的产物存进 rounds/<unit>/rN/, 存好后不再改动,修改一律进入下一轮,这样任意两轮都能直接对比。 自动审查清零后交给用户看,用户确认满意才算定稿。

每章的产物

<chapter>/
├── inventory.md      # 1. 分级要点清单(原文 → 要点,带页码、类型、优先级);每轮可补充,后补的条目标注“rN 补”
├── design.md         # 2. 教学设计(学习单元、钩子、误区、核心画面、深度演示、要点 → 载体映射)
├── beats.md          # 3. 分镜:旁白先行,一拍一行(当前工作版本)
├── beats.json        # 3'. 从 beats.md 抽出的旁白文本(喂给 TTS)
├── audio/<unit>/     # 5. 每拍一个音频文件
├── timeline/<unit>.json  # 5'. audio_timeline.py 生成:每拍时长,场景代码据此定时
├── subs/<unit>.srt   # 5'. 同一份时间轴生成的字幕
└── rounds/<unit>/    # 7. 每轮一个快照目录,存好后只读
    ├── r1/
    │   ├── beats.md        # 本轮所用分镜的副本
    │   ├── timeline.json   # 本轮所用时间轴的副本
    │   ├── <unit>.mp4      # 本轮成片
    │   ├── sheet.png       # 每拍抽一帧的联系表
    │   ├── lint.txt        # lint_scenes.py 的输出
    │   └── review.md       # 本轮审查、与上一轮的对比、用户反馈
    ├── r2/ …
    └── FINAL           # 定稿时写入:定稿轮次(如 r3)、日期、用户确认的原话
场景代码:motion-canvas/src/scenes/<chapter>/*.tsx、manim/<chapter>/*.py

场景代码用版本库管理,每轮在 review.md 里记下当时的 commit;没有版本库时,把本轮改过的场景文件也复制进快照目录。

原文全文只放本地临时目录(如 /tmp/<chapter>-fulltext.txt),不进版本库(版权),但在 inventory.md 头部写清楚 怎么重新抽取(pdftotext -layout -f A -l B book.pdf,以及书页和 PDF 页的换算)。

第一次在项目里使用:搭建

本 skill 自带全部模板和辅助代码,在 assets/ 下。新项目按下表复制(已有项目缺哪个补哪个):

skill 里的文件复制到作用
assets/motion-canvas/theme.tsmotion-canvas/src/lib/theme.ts配色、颜色语义、字体、字号、安全区
assets/motion-canvas/beats.tsmotion-canvas/src/lib/beats.tsbeat():动画时长由旁白音频决定
assets/motion-canvas/card.tsxmotion-canvas/src/lib/card.tsx文字卡(≤ 3 行,旁白驱动),只用于引言和小结
assets/motion-canvas/render/headless.tsmotion-canvas/src/headless.ts无头渲染入口
assets/motion-canvas/render/headless.htmlmotion-canvas/public/headless.html加载上面的入口
assets/motion-canvas/render/render.mjsmotion-canvas/scripts/render.mjs渲染驱动(在 motion-canvas/ 下运行)
assets/motion-canvas/render/vite.config.tsmotion-canvas/vite.config.tsVite 插件配置,文件头写了依赖清单
assets/manim/theme.py、assets/manim/beats.pymanim/Manim 版的 theme 和 Beats

scripts/ 下的两个脚本直接从 skill 目录运行,不用复制。

流程

按顺序走,每一步过了门槛再进下一步。整章不要一口气做完:先做一个学习单元的样片,跑完全部审查,定型后再铺开。 第 1、2 步每章做一次;第 3–7 步对每个学习单元按轮次循环(r1 → 审查 → r2 → …),直到定稿。

0. 全书一次性准备

视觉规范(配色、颜色语义、字体、分辨率、安全边距)定在 theme 里;搭好上面的渲染管线; 选定 TTS 引擎和音色;把反复出现的视觉元素做成组件。工程细节见 references/motion-canvas.md、references/manim.md。

1. 通读 → 分级要点清单(inventory.md)

逐节读原文全文,包括图注、侧栏、脚注,不要只看标题。每条要点一行:

ID | 要点(自己的话转述)| 类型 | 优先级 | 书页 | 图/表 | 可视化潜力

  • 类型: 定义 / 论断 / 机制 / 数字 / 例子 / 图 / 限定条件 / 交叉引用 / 花絮
  • 优先级(决定载体,也决定审查力度):
    • P0 核心概念、定义、主论断:必须讲透,必须有画面动作
    • P1 支撑证据、关键数字、主例子:必须准确,旁白讲到即可
    • P2 出处、花絮、长清单的细项:可选,可只在旁白里一句带过,或放进视频简介
  • 数字 原样记下单位和语境(“平均”“峰值”“某年数据”):语境丢了,数字就会被误读。
  • 另起一节记**“原文没有、但我们想加的”**(示意模型、类比、引申),每条注明理由;成片里出现时必须标注“示意”或“引申”。

门槛: 每个小节都读过全文;P0 条目一般占 20–30%;所有数字都核对过原文。

2. 教学设计(design.md)

按概念切学习单元,不按目录标题切段。 一个单元 3–6 分钟,讲透一个问题,可以跨几个小节,也可以只是一个小节的一半。 每个单元写清楚:

  1. 钩子问题:观众为什么要关心?用一个具体场景提问(如“写进去的数据,多久才能被读到?”)。
  2. 学习目标:看完能回答的 2–3 个问题(之后也用作“新手测试”的题目)。
  3. 常见误区:要主动拆掉的错误直觉(如“均值能代表用户体验”)。
  4. 核心画面:贯穿整个单元的一个视觉隐喻或主线例子,尽量延续到下一个单元。
  5. 深度演示:书里一句话带过、但动画能让人“看见”的点(概率放大、分布排序、排队、相关故障……), 每单元至少一个。模式库见 references/pedagogy.md。
  6. 要点 → 载体映射:每条 P0/P1 要点落到哪一拍、由画面还是旁白承载。
  7. 叙事顺序:默认跟原书的论证顺序;要调整就写明理由。新增内容要编织进叙事,不要追加成补丁段。

门槛: 每条 P0 都有画面动作,每条 P1 都有承载的拍;单元之间没有重复的结论句。

3. 分镜(beats.md)——旁白先行

动笔前先重读原文。 打开这个单元覆盖的原文页(含图、图注、侧栏、脚注),和 inventory、design 对照着写。 inventory 和 design 只是 outline,内容以原文为准:例子的细节、数字的语境、图的读法、论证的先后,都从原文取。 原文里有、清单里没有的要点,先补进 inventory(标注“rN 补”)并定好优先级,再写进分镜。

先写旁白,再为每一拍设计画面。一拍一行:

拍号 | 旁白(1–2 句,口语)| 画面动作(动词开头:出现/移动/变色/排序/放大…)| 屏幕文字(≤ 15 字)| 要点 ID | 工具

  • 每拍 3–8 秒,每一拍画面都要有变化;超过 6 秒没有变化,就是该加动作或该拆拍的信号。
  • 旁白像讲给同事听:短句,先结论后细节,术语第一次出现时给中英对照。
  • 数字放在画面里,并让它“有感觉”:换算成日常尺度,或和另一个数字对比。
  • 结尾一拍回扣钩子问题;需要时加一拍“停下来想一想”。
  • 写完之后,只读旁白检查一遍:要点全吗、逻辑顺吗;只读画面列再检查一遍:能看出机制吗。

空白模板见 references/templates.md;一个从要点清单到两个单元完整分镜的示例见 references/example-unit.md。

4. 工具路由

内容工具
节点、消息、请求流、拓扑、状态变化、时序、表格和数据结构变换Motion Canvas
坐标系、函数曲线、概率和分布、公式推导、几何和集合论证Manim
机制 + 定量结论(如“扇出 N 个后端” → “1−0.99ᴺ 曲线”)MC 演机制,切到 Manim 出曲线,两段共用同一组配色和数字
纯文字尽量不用。引言、小结可以用 card.tsx,每单元最多 1 张,并配旁白

细节见 references/tool-routing.md。

5. 配音与时间轴

  1. 把 beats.md 的旁白抽成 beats.json([{id, text}]),用 TTS 生成每拍一个音频,放进 audio/<unit>/<拍号>.wav。 TTS 引擎随环境选(云端 TTS、本地开源模型都可以),要求只有两条:全书同一个音色;输出同采样率的 PCM wav。 第一次用某个引擎前,先合成一两拍试听:多音字、英文术语、数字(“p99”“1.2 秒”)的读法要单独检查。
  2. 运行 python <skill>/scripts/audio_timeline.py audio/<unit> --beats beats.json -o timeline/<unit>.json --srt subs/<unit>.srt --concat-list audio/<unit>.txt, 得到每拍时长、字幕和音频拼接清单。
  3. 场景代码用 beat(id, 动画):先跑动画,再补等到该拍音频的时长(MC 用 lib/beats.ts,Manim 用 beats.py)。 不要手写 waitFor(23.1) 这样的魔法数字。 还没有音频时,beat() 会按旁白字数估算时长,可以先把节奏搭起来。
  4. 视频静音渲染,拼接时用 ffmpeg 把音频混进去(命令见 references/motion-canvas.md 的“拼接与混音”一节)。

6. 实现与渲染

  • 先读 references/motion-canvas.md 或 references/manim.md 里的“坑”一节。
  • 写每个场景前,再对照一遍这些拍对应的原文段落和图。 标签、数字、图表的坐标和读法以原文为准, 不凭分镜里的转述;分镜和原文对不上时,以原文为准,并回头改分镜。
  • 颜色、字体从 theme 引用;文字一律设 maxWidth + textWrap(Manim 用 theme.py 的 txt(),会自动缩到安全区内)。
  • 渲染前:MC 跑 npx tsc --noEmit,再跑 python <skill>/scripts/lint_scenes.py <场景目录> --manim <manim 目录>。
  • 渲染:MC 在 motion-canvas/ 下 node scripts/render.mjs <场景名>;Manim manim -qm <文件> <场景类>。
  • 渲染后:ffprobe 核对时长;每拍抽一帧拼成联系表(contact sheet),审查时用。

7. 审查与多轮迭代(rounds//rN/)

完整清单、每轮流程和报告模板见 references/review-rubric.md。每轮做四道审查,缺一不可:

  1. 忠实审(正向):拿 inventory 对成片,P0/P1 要点逐条打勾;数字、例子、图的读法和原文一致; 没有原文之外的论断(引申必须标注)。
  2. 反查原文(反向):反过来拿原文对成片,逐段读这个单元覆盖的原文页(含图、图注、侧栏、脚注), 找成片里没有、清单里也没有的内容。正向审只能查出“清单有、成片没有”,清单本身的遗漏只有这一道能发现。 查到的先补进 inventory(标注“rN 补”)并定级,再按级别处理。
  3. 语义审:逐拍对照“画面在说什么”和“旁白在说什么”——静音只看画面会得出什么结论?会不会和旁白相反? 标签、颜色、箭头方向是否和概念一致?新手会不会学错?
  4. 观感审:lint 门槛(见下表)、节奏、叙事顺序、有没有重复的收尾句;最后做一次新手测试: 让没读过这一章的人(或者另开一个没有上下文的 agent 会话,只给它旁白和抽帧)回答设计阶段写的学习目标问题。

问题分级:P0 讲错或误导(必须修)、P1 缺漏或明显影响理解(应修)、P2 观感瑕疵(顺手修)。

每一轮怎么走:

  1. 建快照目录 rounds/<unit>/rN/,放入本轮的 beats.md、timeline.json、成片、联系表、lint 输出。
  2. 做四道审查,写 review.md。从 r2 起,开头先写与上一轮的对比:改了什么;上一轮的问题哪些修掉了、哪些还在;有没有新冒出来的问题。 修改不能引入新问题,所以上一轮已经通过的检查项也要重跑。
  3. 还有 P0 或 P1:修改 inventory、分镜、代码,生成 r(N+1),回到第 1 步。
  4. 没有 P0 和 P1:把本轮成片、联系表、review 摘要和“与上一轮的差异”交给用户看。 用户的反馈原样记进 review.md 的“用户反馈”一节,逐条分级(用户明确要求改的至少算 P1)、写好修法, 按反馈修改后生成 r(N+1),回到第 1 步。
  5. 用户确认满意、不再要求修改:写 rounds/<unit>/FINAL(定稿轮次、日期、用户确认的原话),这个单元定稿。

已经存好的轮次目录不再修改,任何修改都进入下一轮;需要回退时,从对应轮次的快照恢复。

质量门槛(lint_scenes.py 检查前五项)

指标门槛
文字卡时长占比≤ 15%
非卡片场景静止占比(空拍或字面量等待 / 场景时长)≤ 40%
单次静止≤ 6s
文字宽度不超出安全区(1280 宽画布左右各留 60px)
文字卡行数≤ 3 行
P0 要点100% 有画面动作
单元长度3–6 分钟,每个单元能独立看懂

不要做的事

  • 不要为了“覆盖”加文字卡:缺了一条要点,先问它该进旁白还是该进画面。
  • 不要追加补丁段:要么重写这个单元的叙事,要么把内容编织进已有的拍。
  • 不要按模板给固定时长:时长由旁白决定。
  • 不要把工作备注、页码指引放上画面。
  • 不要把原书没有的数字或公式当作书的内容;示意模型也不要用错数学术语(例如说 1/(1−ρ) 有“拐点”)。
  • 不要在一张图里混用两种坐标语义;要变换,就用动画把变换演出来。
  • 不要只照着清单或分镜生成,也不要只拿清单审查:生成和审查都要回到原文。
  • 不要覆盖或修改已经存好的轮次产物;不要在用户确认之前宣布定稿。

文件索引

文件什么时候读 / 用
references/failure-modes.md第一次用本 skill 时;或想知道某条规则为什么存在时
references/pedagogy.md第 2、3 步:钩子、误区、深度演示模式库、通俗化手法
references/tool-routing.md第 4 步拿不准用哪个工具时
references/motion-canvas.md写 MC 场景、组件、渲染、拼接混音
references/manim.md写 Manim 场景(无 LaTeX 环境、确定性数据、计时)
references/review-rubric.md第 7 步:四道审查的完整清单、每轮流程、轮次对比和报告模板
references/templates.mdinventory / design / beats / timeline / 轮次快照的空白模板
references/example-unit.md完整示例:一节内容 → 要点清单 → 两个学习单元的设计和分镜
scripts/lint_scenes.py渲染前的静态检查
scripts/audio_timeline.py音频 → timeline.json + SRT + 拼接清单
assets/theme、beat、文字卡、无头渲染管线(复制位置见“搭建”一节)

Related Skills