Skip to content
Back to search

whiteboard-teacher-video

图文讲解视频 skill:把知识讲解/科普/推导/开源项目介绍做成「手绘会动的画面」讲解视频——图形由代码逐笔绘出、文字逐字写出、讲到哪画到哪(音画对齐)。五套风格可选(白板/黑板/书卷/暖色插画/科技深色),29 个现成组件(图表、流程、仪表、终端、3D),本地 Chrome 渲染、零生图 API 成本、任何改动秒级重渲。当用户要做知识讲解视频、概念科普、图解动画、GitHub 项目介绍片,或要求「手绘动画」「讲动画」「图文视频」「explainer」「animación」时使用。触发词:讲解视频、科普视频、图解视频、手绘动画、讲动画、逐笔绘制、图文并茂的视频、项目介绍视频、开源项目介绍、skill 介绍片、GitHub 项目视频、explainer video、whiteboard teacher。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/liangdabiao--whiteboard-teacher-video/badge.svg)](/listings/liangdabiao--whiteboard-teacher-video)

HTML

<a href="/listings/liangdabiao--whiteboard-teacher-video"><img src="/api/listings/liangdabiao--whiteboard-teacher-video/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**前置要求**:

| 需要 | 说明 | |---|---| | **Node.js ≥ 22.19** | 渲染引擎依赖 | | **Git** | setup 用它从 GitHub 拉取引擎(无 git 可手动下载,见下) | | **Chrome 或 Edge** | 渲染时驱动它截图(**不会**替你下载 Chromium) | | Python 3.9+ | 跑 skill 的脚本 |

python scripts/setup.py                                     # 跨平台(macOS / Linux / Windows)
powershell -ExecutionPolicy Bypass -File scripts/setup.ps1   # Windows PowerShell

首次约 2–4 分钟:拉取引擎(约 16MB)+ 安装依赖(约 130MB)。**装一次即可**,之后所有渲染都复用。

setup 会打印每个环境项的检查结果,标 ✗ 的项会说明怎么修。

**没装 Git?** 手动下载 https://github.com/sitor-ai/frametell ,把 `packages/engine` 整个目录复制到 skill 根目录下的 `engine/`,再跑一次 `scripts/setup.py`(它会跳过引擎那步,只装依赖)。

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 · 201 lines
  1. ---
  2. name: whiteboard-teacher-video
  3. version: 1.0.0
  4. display_name: 手绘讲解视频
  5. display_name_en: Whiteboard Teacher Video
  6. description: 图文讲解视频 skill:把知识讲解/科普/推导/开源项目介绍做成「手绘会动的画面」讲解视频——图形由代码逐笔绘出、文字逐字写出、讲到哪画到哪(音画对齐)。五套风格可选(白板/黑板/书卷/暖色插画/科技深色),29 个现成组件(图表、流程、仪表、终端、3D),本地 Chrome 渲染、零生图 API 成本、任何改动秒级重渲。当用户要做知识讲解视频、概念科普、图解动画、GitHub 项目介绍片,或要求「手绘动画」「讲动画」「图文视频」「explainer」「animación」时使用。触发词:讲解视频、科普视频、图解视频、手绘动画、讲动画、逐笔绘制、图文并茂的视频、项目介绍视频、开源项目介绍、skill 介绍片、GitHub 项目视频、explainer video、whiteboard teacher。
  7. description_zh: 把讲解稿变成「手绘会动的画面」讲解视频。图形由代码逐笔绘出、文字逐字写出、讲到哪画到哪,五套风格可选,本地 Chrome 渲染,零生图 API 成本,改动秒级重渲。适合知识讲解、概念科普、图解动画与课程视频。
  8. description_en: Turn a script into a whiteboard-style explainer video where every shape is drawn by code, word by word, exactly when it is spoken. Five visual styles, 29 built-in components, rendered locally in Chrome with zero image-generation API cost, and re-renders in seconds after any edit. Best for concept explainers, science communication, animated diagrams, and course videos.
  9. ---
  10. # Whiteboard Teacher Video · 图文讲解视频
  11. 把讲解稿变成一支会「自己画出来」的讲解视频。画面不是生成图片,而是**代码逐笔绘制**——所以可重渲、可精修、零生图成本。
  12. ## 引擎契约(先理解这一条)
  13. **整片是时间的纯函数。** `ENGINE.renderAt(t)` 渲染第 `t` 秒的画面,与之前播放过什么无关。
  14. 由此得到四个能力,也是你必须遵守纪律的**根本原因**:
  15. | 能力 | 靠什么 |
  16. |---|---|
  17. | 改一页只重渲受影响片段 | 分段缓存 key = sha1(引擎 + 该页代码) |
  18. | 12 个浏览器并行渲染 | 各段互不依赖 |
  19. | 预览可瞬移到任意时刻 | 无需从头播放 |
  20. | 确定性校验 | 同一时刻渲染两次比对像素 |
  21. **红线:页面代码禁止 `Math.random()` / `Date.now()` / CSS transition / rAF。** 随机必须走 `PV.rng(seed)`,时间一律用 `P.c(i)` / `P.cw(i,'词')`。破坏这条,上面四个能力全部失效。
  22. ## 工作流(照着走,不要跳步)
  23. ```
  24. 用户:"做一个讲相对论的 90 秒视频"
  25. ↓
  26. ① 读 references/storyboard-method.md → 写 storyboard.json
  27. ② ★★★ 停下来,把分镜念给用户确认 ★★★ ← 唯一强制人类闸门
  28. ③ 写 script.js(口播,按分镜填 cue)
  29. ④ python scripts/ftnew.py <项目> --title "..." --style whiteboard
  30. ⑤ python scripts/ftvoice.py <项目> → voice.js + 字幕.srt
  31. ⑥ 逐页写 pages/pNN.js ← 主要创作量
  32. ⑦ python scripts/ftcheck.py <项目> → lint + 每页拼图
  33. ⑧ 用 Read 打开 out/snap/pNN.jpg 逐页看图 → 定点修,**别超过 2 轮**
  34. ⑨ python scripts/ftrender.py --fps 24 --skip-subs → **先出一个能看的粗片**
  35. ⑩ ★ 交付粗片给用户 ★ ← 不要攒着不交付
  36. ⑪ 看图修一轮 → ftrender.py → 交付正式版
  37. ```
  38. **第 ② 步不可跳过。** 分镜错了,后面画得再好看也是一份幻灯片。原项目把这条做成 promise 闸门是有原因的。
  39. ### 配音后端
  40. 默认 `edge`(免费、无需 API key);付费备选用 `apiz`:
  41. ```bash
  42. python scripts/ftvoice.py <项目> --backend edge --voice mature --speed 1.15
  43. ```
  44. edge 的旧域名(`speech.platform.bing.com`)在 2026 年起很多地区 403;
  45. `scripts/edge_tts_speak.py` 已自动改走 `api.msedgeservices.com`,失败再回退旧域名。
  46. 不需要 `edge-tts` CLI。先跑 `--probe`,细节见 `references/tts-backends.md`。
  47. ### ★★ 第 ⑩ 步同样重要:先出片,再打磨
  48. **用户要的是视频,不是完美的视频。** 交付节奏比成品精度更重要。
  49. - **第 ⑧ 步的质检修到「不出现明显错误」就够**(lint 无 error、文字没被盖住、NaN 为 0),**不要追求构图完美**
  50. - 第一次渲染用 `--fps 24 --skip-subs`(快 40%),先给用户一个能看的版本
  51. - **不要把所有轮次修完再交付**。用户看到粗片才能给出真正的反馈
  52. - 想改风格、加页、调内容?**改完重渲就行**,分段缓存会让第二轮很快(实测改单页 1 分钟)
  53. > **实测教训**:做那条 95 秒 8 页的片子时,我在「lint 报的问题值不值得改」上反复纠结了两轮才交付,用户等得不耐烦。
  54. > **正确做法**:lint error 修掉、明显 bug 修掉,粗片先出去,剩下的一轮里改。
  55. ### ★ lint 全绿 ≠ 画面是对的
  56. `lint` 是机器检查,只能查出界/重叠/字号这类硬错误;**构图好不好、元素挤不挤、文字有没有被色块盖住,只有看图才知道**。
  57. > **实测教训**:p07 那一页 lint 报 0 错误、质检显示全绿,但看拼图发现「7 微秒」的"微秒"被荧光笔完全盖住,只剩红色的「7」——观众完全读不出单位。
  58. ## 硬纪律
  59. ### ★ 节奏(最重要的一条)
  60. - **用户要的是视频,不是完美的视频。** 粗片也是片,攒着不交付等于没做
  61. - **质检修到「不出明显错误」就停**,不要追求构图完美
  62. - **第一次渲染用 `--fps 24 --skip-subs`**(快 40%),先把能看的版本交出去
  63. - 改一轮再交正式版。分段缓存让第二轮很快(实测改单页 1 分钟)
  64. ### 画面
  65. - **内容区**:x 140–1780,y 180–880。y > 900 是字幕带,**不许放内容**
  66. - **★ 文字居中必须给 `w` + `align:'c'`** —— 不给 `w` 时 `x` 是**左边缘**不是中心,这是最高频的错
  67. - **★ 有 `P.push()` 的页面,元素往画面中间放** —— 推镜放大后边缘文字会溢出画布(lint 报 off-canvas)
  68. - **正文字号 ≥ 32px**(< 24px 会被 lint 判失败)
  69. - **每屏中文字 ≤ 8 个字**
  70. - **配色只写语义名**:`ink` `soft` `muted` `faint` `blue` `orange` `red` `green` `purple` `yellow`,加 `F` 是浅填充(`blueF`)。**不许硬编码 hex**——写错名字引擎会记下来由质检报告
  71. - **一页一观点**,2–3 句口播,2–4 秒要有新东西出现
  72. ### 动画
  73. - `P.c(i, dt)` = 第 i 句开始 + dt 秒
  74. - `P.cw(i, '词', dt)` = 第 i 句**念到某词** + dt 秒(关键数字用这个:数字刚好被念到就出现)
  75. - `P.ce(i)` = 该句结束;`P.endT` = 本页讲完
  76. - 强调用笔法(`ring` 圈 / `underline` 下划线 / `mark` 荧光笔 / `cross` 叉 / `check` 勾),不靠特效
  77. - 翻页瞬间页面上**必须有东西**,不能空白
  78. ## 迭代
  79. - 改单页 → 只重渲那页(`ftcheck.py --only pNN`),不要全量
  80. - **lint 有 error 就别渲染**,先修
  81. - **lint 过了也要看拼图** —— lint 只管硬错误,好不好看、盖没盖住它不管
  82. - `ftcheck.py` 会报 **NaN** —— 那是 lint 查不到的致命伤(图形静默消失)
  83. - 修不完就标「需要关注」并继续,**不要卡死**(**最多 2 轮就该出片**)
  84. ### 参考耗时(本机实测,8 页 87 秒片子)
  85. | 阶段 | 耗时 |
  86. |---|---|
  87. | 建项目 + 写 8 页画面代码 | 约 10 分钟(人的创作时间) |
  88. | 配音 26 句 | 约 1.5 分钟 |
  89. | 质检(lint + 8 页拼图) | 约 1 分钟 |
  90. | 渲染(首次,12 worker) | 约 2 分 45 秒 |
  91. | 渲染(改单页后,缓存命中) | **约 1 分钟** |
  92. | 渲染(`--fps 24 --skip-subs` 快版) | 约 1 分 40 秒 |
  93. **所以从建项目到出第一条片,全程约 15 分钟。** 迭代单页一分钟——所以不必攒着改完再交付。
  94. ### 引擎 API 的三个高频坑
  95. ```js
  96. // ① 文字居中:不给 w 时 x 是左边缘,不是中心
  97. P.text('站台', { x: 420, y: 640, w: 280, align: 'c', size: 46 }); // ✓ 中心在 420
  98. // ② check/cross 的第三参数是「尺寸」,不是配置对象(传错只刷 NaN,不报错)
  99. P.cross(970, 716, 64, { color: 'red', at: t }); // ✓
  100. P.cross(970, 716, { color: 'red', at: t }); // ✗ sz = [object Object]
  101. // ③ liveRough 的回调参数别叫 R;且 R 只有 box/circle/line/path 四个方法
  102. const R = 1400; // ← 会被回调参数覆盖
  103. P.liveRough((lt, R) => (xL + R) / 2); // ✗ NaN
  104. P.liveRough((lt, rough) => [rough.box(x, y, w, h, { color: 'ink' })]); // ✓
  105. ```
  106. **渲染时留意控制台的 `NaN`** —— 它不抛异常、lint 也不一定报,但对应图形就是画不出来。
  107. 完整清单见 `references/page-api.md`。
  108. ## 能做 / 不能做
  109. **能**:知识科普、概念解释、流程推导、数据图表讲解、产品演示(可嵌真实截图)、GitHub 项目讲解;五套风格;横屏/竖屏;中英配音;自动字幕;20 秒到 10 分钟。
  110. > **做 GitHub 项目 / skill 介绍片时,先读 `references/github-project-intro.md`。**
  111. > 这类片子有硬要求:**最后一页必须是仓库地址页**(仓库名大字 + 完整 URL + owner + 怎么找),
  112. > 否则观众看完不知道项目叫什么、去哪找 —— 片子等于白做。仓库名要从原文原样复制,
  113. > **不能按文件名 slug 推断**(实测 `ai-data-hub.md` 的仓库其实是 `AI_data_hub`)。
  114. **不能**:
  115. - 写实照片/三维实拍风格(要那种质感请用生图工具)
  116. - 自动配乐与音效床(`page.sfx` 能做,但要自己准备音频文件)
  117. - 生图式的手绘插画(组件都是代码画的矢量图)
  118. - 一次生成几十页(每页都要写代码,建议 ≤ 12 页)
  119. ## 与 whiteboard-explainer 的区别
  120. | | whiteboard-explainer | **frametell-video(本 skill)** |
  121. |---|---|---|
  122. | 画面 | 像素级笔画生长 | rough.js 风格化绘制 |
  123. | 风格 | 单一(白板,底色硬编码) | **五套,含深色** |
  124. | 组件 | 全部手写 | **29 个现成** |
  125. | 质检 | 归属检查 | lint + 拼图 + 确定性 |
  126. | 适合 | 数学推导、强手绘感 | 科普讲解、图表密集、多风格 |
  127. 需要「真手绘感 / 逐元素生长」→ 用 whiteboard-explainer。需要「多风格 / 复杂图表 / 组件复用 / 强质检」→ 用本 skill。
  128. ## 文档索引
  129. | 什么时候读 | 读哪份 |
  130. |---|---|
  131. | **做开源项目 / skill 介绍片** | `references/github-project-intro.md`(**8 页骨架 + 仓库地址页铁律 + 十七个坑**)· 样例 `assets/example-github-intro/` |
  132. | **批量做一批项目介绍片** | 先跑 `python scripts/progress.py` 生成进度表(哪些做完 / 待做 / 缺仓库地址) |
  133. | **第一次用** | `assets/example-relativity/`(一条真实成片的完整源码:8 页,看完就懂) |
  134. | 画任何一页之前 | `references/page-api.md`(绘图 API 速查 + 三个高频坑) |
  135. | 定分镜 / 写口播 | `references/storyboard-method.md`(五段式 + 禁忌) |
  136. | 选风格 / 拿不准配色 | `references/style-packs.md`(五套风格 + 语法卡摘要) |
  137. | `script.js` 字段不清 | `references/script-format.md` |
  138. | 配音报错 / 想换 TTS | `references/tts-backends.md`(edge 已改走新域名,含回退说明) |
  139. | 看不懂引擎报错 | `references/troubleshooting.md`(按症状索引) |
  140. ## 首次使用
  141. 如果 `scripts/` 报「引擎未就位」或依赖缺失,先跑 setup:
  142. ```bash
  143. python scripts/setup.py # 跨平台
  144. powershell -ExecutionPolicy Bypass -File scripts/setup.ps1 # Windows
  145. ```
  146. **需要**:Node.js ≥ 22.19、Git、本机的 Chrome/Edge、Python 3.9+
  147. 首次约 2–4 分钟:从 GitHub 拉取引擎(约 16MB,sparse checkout 只取 `packages/engine`)+ `npm install` 依赖(约 130MB)。
  148. **没装 Git**:手动下载 https://github.com/sitor-ai/frametell ,把 `packages/engine` 复制到 skill 根目录的 `engine/`,再跑一次 setup。
  149. 依赖清单与体积见 `README.md`;授权信息见 `vendor/ATTRIBUTION.md`。
README.md · README · 414 lines
  1. # whiteboard-teacher-video
  2. <img width="1672" height="941" alt="image" src="https://github.com/user-attachments/assets/25f8ce97-1407-4167-a53a-4149c195a6a8" />
  3. **图文讲解视频 skill** —— 把讲解稿变成「手绘会动的画面」讲解视频。
  4. 图形由代码逐笔绘出、文字逐字写出、讲到哪画到哪。五套风格可选,本地 Chrome 渲染,**零生图 API 成本**,任何改动秒级重渲。
  5. B站效果:
  6. 《GPS是怎么工作的》
  7. https://www.bilibili.com/video/BV1mpn96UE7B/?vd_source=86926e418c83af75f6850b5546388a79
  8. 《勾股定理证明》
  9. https://www.bilibili.com/video/BV1yYJ46PE5R/?vd_source=86926e418c83af75f6850b5546388a79
  10. 《九宫格数学》
  11. https://www.bilibili.com/video/BV1SFxg6VEZP/?vd_source=86926e418c83af75f6850b5546388a79
  12. 《财务报表解释》
  13. https://www.bilibili.com/video/BV1U2xY6gEto/?vd_source=86926e418c83af75f6850b5546388a79
  14. 《自己介绍自己》
  15. https://www.bilibili.com/video/BV1nHxY6tEwe/?vd_source=86926e418c83af75f6850b5546388a79
  16. 安装方法,直接给链接给你的ai就可以。 本项目不需要依赖其他api;edge-tts 已改走新域名(见 `references/tts-backends.md`),也可以装 https://apiz.ai 的 apiz-cli 作为备用语音后端。
  17. 重大升级版(利用了最新的动效绘图技术): https://github.com/liangdabiao/whiteboard-teacher-video-motion
  18. 如果需要更简洁的版本: https://github.com/liangdabiao/whiteboard-explainer
  19. ---
  20. ## 它和普通 AI 生视频工具的区别
  21. | | AI 生视频工具 | 本 skill |
  22. |---|---|---|
  23. | 画面怎么来 | 模型生成像素 | **代码逐笔绘制**(rough.js) |
  24. | 改一句话 | 整段重生成 | 只重渲受影响片段(**几秒**) |
  25. | 画面质量 | 随机,有抖动 | 确定性,同一时刻渲染两次像素一致 |
  26. | API 成本 | 按次付费 | **零**(只付 TTS 的钱) |
  27. | 能嵌真实数据 | 难 | 任意数字/图表/代码/真实网页截图 |
  28. **核心原理**:整片是「时间的纯函数」——`renderAt(t)` 渲染第 t 秒的画面,与之前播放过什么无关。由此才能分段缓存、并行渲染、任意跳转、确定性校验。
  29. ---
  30. ## 依赖到底要下载什么
  31. **是的,要下载。** 但只有**两步**,都很轻。
  32. ### 第一步:取得引擎(约 16MB)
  33. 引擎**不在 skill 包里** —— 它有 16MB / 38 万个文件(主要是展开的 three.js),打进来会让分发变得很重。
  34. setup 自动从 GitHub 拉取,用 **sparse checkout 只取引擎那一个目录**(不会下载上游几百 MB 的 electron 和桌面端):
  35. ```bash
  36. git clone --filter=blob:none --no-checkout --depth 1 https://github.com/sitor-ai/frametell
  37. git -C frametell sparse-checkout init --cone
  38. git -C frametell sparse-checkout set packages/engine
  39. git -C frametell checkout
  40. ```
  41. 没装 git 也可以:手动下载仓库,把 `packages/engine` 整个目录复制到 skill 根目录下的 `engine/`。
  42. ### 第二步:第三方依赖(约 130MB)
  43. `npm install` 自动获取,共 10 个包:
  44. | 包 | 体积 | 作用 | 必须? |
  45. |---|---|---|---|
  46. | `ffmpeg-static` | 80 MB | 音视频编码(自带 ffmpeg 二进制) | ✅ |
  47. | `lxgw-wenkai-webfont` | 30 MB | **中文字体**(缺了中文变豆腐块) | ✅ |
  48. | `playwright-core` | 13 MB | 驱动本机 Chrome/Edge 截图 | ✅ |
  49. | `katex` | 4.4 MB | 公式排版(`P.tex`) | 可选 |
  50. | `@iconify-json/logos` + `simple-icons` | ~4 MB | 品牌 logo(`P.logo`) | 可选 |
  51. | `roughjs` | 275 KB | **手绘线条引擎** | ✅ |
  52. | `@fontsource/*`(3 个字体) | 少量 | 英文手写体 / 圆体 / 等宽体 | 可选 |
  53. **两点说明**:
  54. - `playwright-core` **不含浏览器**,它只驱动你**本机已装**的 Chrome/Edge —— 不会额外下载几百 MB 的 Chromium
  55. - 依赖**一律真实安装**在 `<skill>/node_modules`,不做任何复用链接。复用必须建 junction,而那会形成目录环(详见 `references/troubleshooting.md`)——130MB 换来的代价是几十万文件和删不掉的目录,不值得
  56. ### 对照:上游 frametell 原版要 1.3GB
  57. https://github.com/sitor-ai/frametell , frametell 是优秀的项目,推荐给大家! 而本项目利用了frametell的绘图引擎!
  58. | | 上游 monorepo | 本 skill |
  59. |---|---|---|
  60. | 依赖包数 | 590 个 | **10 个** |
  61. | 安装体积 | 1.3 GB | **约 130 MB** |
  62. | 安装耗时 | **24 分钟** | 1–3 分钟 |
  63. | 多余内容 | electron、React 面板、模型层、桌面端 | 全砍掉 |
  64. 省掉 90% 体积和 90% 时间,因为 skill 不需要桌面 App、图形面板、模型接入 —— **干活的就是当前这个 agent**。
  65. ### 许可提醒
  66. 引擎是 **AGPL-3.0-only**(Sitor Team)。它作为独立进程被调用,**用本 skill 产出的视频不构成衍生作品**;但**不要把引擎源码复制进你自己的闭源项目**。详见 `vendor/ATTRIBUTION.md`。
  67. ---
  68. ## 快速开始
  69. ### 0. 克隆
  70. ```bash
  71. git clone https://github.com/liangdabiao/whiteboard-teacher-video.git
  72. cd whiteboard-teacher-video
  73. ```
  74. ### 1. 安装
  75. **前置要求**:
  76. | 需要 | 说明 |
  77. |---|---|
  78. | **Node.js ≥ 22.19** | 渲染引擎依赖 |
  79. | **Git** | setup 用它从 GitHub 拉取引擎(无 git 可手动下载,见下) |
  80. | **Chrome 或 Edge** | 渲染时驱动它截图(**不会**替你下载 Chromium) |
  81. | Python 3.9+ | 跑 skill 的脚本 |
  82. ```bash
  83. python scripts/setup.py # 跨平台(macOS / Linux / Windows)
  84. powershell -ExecutionPolicy Bypass -File scripts/setup.ps1 # Windows PowerShell
  85. ```
  86. 首次约 2–4 分钟:拉取引擎(约 16MB)+ 安装依赖(约 130MB)。**装一次即可**,之后所有渲染都复用。
  87. setup 会打印每个环境项的检查结果,标 ✗ 的项会说明怎么修。
  88. **没装 Git?** 手动下载 https://github.com/sitor-ai/frametell ,把 `packages/engine` 整个目录复制到 skill 根目录下的 `engine/`,再跑一次 `scripts/setup.py`(它会跳过引擎那步,只装依赖)。
  89. ### 2. 五步做一支视频
  90. ```bash
  91. # ① 建项目
  92. python scripts/ftnew.py D:/films/relativity --title "相对论入门" --style whiteboard
  93. # ② 写口播 → 编辑 D:/films/relativity/script.js(每页 2-3 句)
  94. # 画画面 → 编辑 D:/films/relativity/pages/p01.js … pNN.js
  95. # ③ 配音(逐句合成,自动缓存)
  96. python scripts/ftvoice.py D:/films/relativity
  97. # ④ 质检(lint + 每页拼图)—— 修到「没明显错误」即可,别追求完美
  98. python scripts/ftcheck.py D:/films/relativity
  99. # ★ 然后用 Read 工具打开 out/snap/pNN.jpg 逐页看
  100. # ⑤ 先出一个快版粗片给你看
  101. python scripts/ftrender.py D:/films/relativity --fps 24 --skip-subs
  102. ```
  103. 产物在 `D:/films/relativity/out/`:成片 mp4(有/无字幕两版)+ `字幕.srt` + 每页拼图。
  104. ### 3. 看一个真实成品
  105. 《总统的证明:一块梯形证出勾股定理》—— **103.5 秒 / 8 页 / 黑板粉笔风**,讲加尔菲尔德 1876 年的那个证明。
  106. https://www.bilibili.com/video/BV1yYJ46PE5R/?vd_source=86926e418c83af75f6850b5546388a79
  107. 它的价值在于示范了**一条贯穿全片的意象**(那块梯形)怎么用:
  108. | 页 | 手法 |
  109. |---|---|
  110. | p03 | 纸堆打叉收成一块梯形 —— **主角在这里登场** |
  111. | p04 | 梯形放大,标出三个直角标记与 a / b / c |
  112. | p05 p06 p07 | **复用同一套归一化坐标**,只换高亮的边和填色,观众一眼认出是同一块 |
  113. | p08 | 划掉 ab,绿字 a²+b²=c² 落在梯形正中收束 |
  114. 对应的分镜在 `assets/storyboard-总统的证明.json`。
  115. ### 4. 节奏建议:先出片,再打磨
  116. **这是用好这个 skill 最重要的一条。**
  117. 用户要的是视频,不是完美的视频。建议这样推进:
  118. | 阶段 | 做什么 | 耗时 |
  119. |---|---|---|
  120. | **粗片** | lint 无 error + 看一眼拼图没明显 bug → `--fps 24 --skip-subs` 渲染 → **交付** | 约 15 分钟 |
  121. | **正式版** | 看用户反馈 + 自己再修一轮 → 正常渲染 → 交付 | 改单页约 1 分钟 |
  122. 因为引擎有**分段缓存**,改一页只重渲受影响的片段(一分钟),所以「先交付再迭代」几乎零成本——**攒着改完再交付反而让用户多等。**
  123. ### 5. 配音可选后端
  124. ```bash
  125. python scripts/ftvoice.py <项目> --backend edge --voice mature # 默认:edge(免费)
  126. python scripts/ftvoice.py <项目> --backend apiz --voice mature # 付费备选
  127. python scripts/ftvoice.py <项目> --backend edge --voice mature # 免费:走新域名
  128. python scripts/ftvoice.py <项目> --backend user --user-audio D:/my-audios
  129. python scripts/ftvoice.py <项目> --backend edge --probe # 只测可用性
  130. ```
  131. > **edge 免费可用**(2026-10-22 实测):旧域名 `speech.platform.bing.com` 在部分地区 403,
  132. > 但 skill 的 helper 已改走 `api.msedgeservices.com` —— 同一个服务、同一套 token,无需 API key。
  133. > 不用 `edge-tts` CLI,`ftvoice.py --backend edge` 直接调 Python 包。详见 `references/tts-backends.md`。
  134. ---
  135. ## 五套风格
  136. 在 `script.js` 的 `META.style` 改一个词即可,页面代码不动。
  137. | 风格 | 气质 | 适合 |
  138. |---|---|---|
  139. | `study`(默认) | 安静书卷、暖纸底 | 通用,拿不准就用它 |
  140. | `whiteboard` | 白板马克笔、逐笔画出 | 数学推导、流程、逐步讲解 |
  141. | `chalkboard` | 深绿板岩、粉笔颗粒 | 公式、课堂板书感 |
  142. | `warm-story` | 暖色扁平插画 | 比喻叙事(理财、成长、心理) |
  143. | `tech-dark` | 石墨深色、青色强调 | 软件、架构、终端、代码 |
  144. **换的不只是配色,构图节奏和动画语法一起换** —— 每个风格包都带一份 `GRAMMAR.md`(做什么/不做什么)。
  145. ---
  146. ## 内置能力
  147. - **29 个可复用组件**:图表(柱/线/雷达/仪表/矩阵)、流程图、终端、卡片、对话框、3D 点云
  148. - **真实素材**:可嵌截图、视频片段、**真实网页截图窗口**(适合讲开源项目/产品)
  149. - **公式**:KaTeX 排版
  150. - **品牌 logo**:内置 simple-icons + iconify
  151. - **竖屏**:加 `--portrait`(1080×1920)
  152. - **字幕**:自动生成 SRT,可选烧录进画面
  153. - **音画对齐**:关键数字用 `P.cw(i, '词')` 卡在「念到这个词的瞬间」
  154. ---
  155. ## 工作目录结构
  156. 一个视频 = 一个普通文件夹,纯文本代码 + 音频,没有任何二进制格式:
  157. ```
  158. <项目>/
  159. ├── script.js 唯一事实来源:风格 + 口播 + 分页
  160. ├── voice.js 配音真实时间戳(ftvoice.py 自动生成)
  161. ├── audio/ 每句一个音频切片
  162. ├── pages/pNN.js 每页画面(独立文件,可单独重渲)
  163. ├── storyboard.json 分镜
  164. ├── out/ 成片、字幕、拼图、质检报告
  165. └── engine → 引擎链接(junction,引擎自己建的)
  166. ```
  167. > ⚠ **删项目目录前,先摘掉这个 `engine` 链接**(`rm <项目>/engine`,不要加 `-r`)。
  168. > 带 `-r` 的递归删除会顺链接钻进 skill 的引擎里把它删掉。
  169. ---
  170. ## 脚本一览
  171. | 脚本 | 作用 |
  172. |---|---|
  173. | `scripts/ftnew.py` | 建项目(铺骨架 + 建链接 + 写模板) |
  174. | `scripts/ftvoice.py` | 配音 → audio/ + voice.js + 字幕.srt(多后端 + 缓存) |
  175. | `scripts/ftcheck.py` | 质检(lint + 每页拼图 + 结构化报告) |
  176. | `scripts/ftrender.py` | 渲染 + 成片校验 |
  177. | `scripts/ftlib.py` | 公共库(路径、Windows 适配、音频探测) |
  178. 常用参数:
  179. ```bash
  180. ftcheck.py <项目> --only p03 # 只查一页
  181. ftcheck.py <项目> --no-sheets # 只跑 lint 不出图
  182. ftcheck.py <项目> --determinism # 加确定性检查
  183. ftrender.py <项目> --fps 24 --skip-subs # 快速预览
  184. ftrender.py <项目> --portrait # 竖屏
  185. ftvoice.py <项目> --from 5 # 从第 5 条重配(前缀不动)
  186. ```
  187. ---
  188. ## 常用环境变量
  189. 多数情况**不需要设任何环境变量**。这些是特殊情况下的出口:
  190. | 变量 | 用途 |
  191. |---|---|
  192. | `FRAMETELL_ENGINE` | 引擎装在别处时指定它(如你想共用一份引擎) |
  193. | `CHROME_PATH` | 指定浏览器可执行文件(默认自动探测系统 Chrome/Edge) |
  194. | `FFMPEG_PATH` | 指定 ffmpeg(默认用 `ffmpeg-static` 内置的) |
  195. ---
  196. ## 性能参考(本机实测)
  197. 做一条 8 页 / 87 秒的片子(示例源码见 `assets/example-relativity/`):
  198. | 阶段 | 耗时 |
  199. |---|---|
  200. | 首次安装(引擎 + 依赖) | 约 2–4 分钟(16MB + 130MB) |
  201. | 配音 26 句 | 约 1.5 分钟 |
  202. | 质检(lint + 8 页拼图) | 约 1 分钟 |
  203. | 渲染(首次,12 worker 并行) | 约 2 分 45 秒 |
  204. | 渲染(改单页后,缓存命中) | **约 1 分钟** |
  205. | 渲染(`--fps 24 --skip-subs` 快版) | 约 1 分 40 秒 |
  206. **从建项目到第一条成片约 15 分钟**,其中大头是写页面代码的人力。
  207. 迭代单页一分钟——所以**「先交付粗片再改」几乎没有成本**。
  208. > 示例:相对论那条片子(87.6 秒 / 8 页 / 1920×1080)的**源码**在 `assets/example-relativity/`,
  209. > 分镜在 `assets/storyboard-相对论.json`——可以照着做自己的第一支片子。
  210. ---
  211. ## 许可与归属
  212. **本 skill 分发时不含引擎源码** —— 引擎在用户 `setup` 时从上游 GitHub 获取(与 `whiteboard-explainer` 的 vendor 策略一致)。
  213. - **引擎**:Frametell · Sitor Team · **AGPL-3.0-only** · https://github.com/sitor-ai/frametell
  214. - **本 skill 自有部分**:`SKILL.md`、`scripts/`、`references/`、`setup.*`、`assets/` 均为原创
  215. - **npm 依赖**:10 个包,各自宽松许可(详见 `vendor/ATTRIBUTION.md`)
  216. - **字体**:霞鹜文楷 LXGW WenKai · SIL OFL-1.1(允许商用与再分发)
  217. **AGPL 影响**:
  218. - 引擎作为**独立进程**被调用,用本 skill 产出的视频**不构成衍生作品**
  219. - ⚠️ **不要把引擎源码复制进你自己的闭源项目** —— 那会让你的项目整体变成 AGPL
  220. - 需要非 AGPL 方案请另寻渲染引擎,或联系 Sitor Team 取得商业授权
  221. 完整归属与授权详见 `vendor/ATTRIBUTION.md`。
  222. ---
  223. ## 文档
  224. | 读什么 | 打开 |
  225. |---|---|
  226. | **第一次用(强烈建议)** | `assets/example-relativity/` —— 一条真实成片的完整源码(8 页,含可复用写法) |
  227. | 画页面前必读 | `references/page-api.md`(绘图 API + 三个高频坑 + 自检清单) |
  228. | 定分镜、写口播 | `references/storyboard-method.md`(五段式 + 分镜 lint + 禁忌) |
  229. | 选风格、配色 | `references/style-packs.md` |
  230. | `script.js` 字段 | `references/script-format.md` |
  231. | 配音报错、换 TTS | `references/tts-backends.md` |
  232. | 报错查这里 | `references/troubleshooting.md`(按症状索引) |
  233. ---
  234. ## ★ 两件最重要的事
  235. **一、lint 全绿 ≠ 画面是对的**
  236. `lint` 只管机器能判的硬错误(出界/重叠/字号/密度),这些它**一律不管**:
  237. - 构图好不好、元素挤不挤
  238. - 文字有没有被色块盖住
  239. - 图形符不符合本意(画出来像不像地球)
  240. - NaN 导致的图形静默消失
  241. 所以 `ftcheck.py` 出拼图后,**必须用 Read 工具打开 `out/snap/pNN.jpg` 看一眼**。
  242. > 实测:p07 那一页 lint 报 **0 错误**,但看拼图才发现「7 微秒」的「微秒」被荧光笔完全盖住,只剩一个红色的「7」——观众根本读不出单位。
  243. **二、先出片,再打磨**
  244. 用户要的是视频,不是完美的视频。粗片也是片。
  245. 因为引擎有分段缓存,**改一页只重渲受影响片段(约 1 分钟)**,所以「先交付粗片 → 收反馈 → 再迭代」几乎没有成本;而**攒着改完再交付,只会让用户干等**。
  246. ---
  247. ## 三个高频坑(新手必看)
  248. 都来自实测制作一条 8 页影片的过程,**都不会报错,但会让画面不对**:
  249. ```js
  250. // ① 文字居中:不给 w 时 x 是左边缘,不是中心
  251. P.text('站台', { x: 420, y: 640, w: 280, align: 'c', size: 46 }); // ✓ 中心在 420
  252. P.text('站台', { x: 420, y: 640, size: 46 }); // ✗ 从 420 向右铺开
  253. // ② check/cross 的第三参数是「尺寸」,不是配置对象
  254. P.cross(970, 716, 64, { color: 'red', at: t }); // ✓
  255. P.cross(970, 716, { color: 'red', at: t }); // ✗ sz = [object Object] → NaN
  256. // ③ liveRough 的回调参数别叫 R;且 R 只有 box/circle/line/path
  257. const R = 1400; // ← 会被回调参数覆盖
  258. P.liveRough((lt, R) => (xL + R) / 2); // ✗ NaN
  259. P.liveRough((lt, rough) => [rough.box(x, y, w, h, { color: 'ink' })]); // ✓
  260. ```
  261. 另外两条不算坑但会翻车:
  262. - **lint 报 off-canvas / 压字幕带,而坐标看着没问题** → 是相机 `P.push` 放大造成的,换成 `P.pan` 即可
  263. - **`P.mark()` 荧光笔会盖住文字** → 荧光笔高度给到字号的 0.4 倍、放在基线下方。实测 p07 的「微秒」被完全盖住,lint 却全绿
  264. ---
  265. ## ★ lint 全绿 ≠ 画面是对的
  266. `lint` 只管机器能判的硬错误(出界/重叠/字号/密度),**下面这些它一律不管**:
  267. - 构图好不好、元素挤不挤
  268. - 文字有没有被色块盖住
  269. - 图形符不符合本意(画出来像不像地球)
  270. - NaN 导致的图形静默消失
  271. 所以 `ftcheck.py` 出拼图后,**必须用 Read 工具逐页打开 `out/snap/pNN.jpg` 看一眼**。这是整个流程里最不能省的一步。
  272. ---
  273. ## 已知限制
  274. - 不做写实照片/三维实拍风格(那是生图工具的领域)
  275. - 不自动配乐(`page.sfx` 能做,但要自己准备音频文件)
  276. - 逐句合成配音 → 整页语调略不连贯(要连贯需用火山/ElevenLabs 的字级时间戳方案)
  277. - 建议 ≤ 12 页(每页都要写代码)
  278. ## 特别致谢
  279. https://linux.do 社区支持

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.