Skip to content
Back to search

whiteboard-teacher-video-motion

独立可用的手绘讲解视频 skill。在「代码逐笔绘制」的白板讲解片里,加入 GPT Image 2.6 Flare 生成的原生 SVG 矢量图解(由时间轴驱动逐笔生长)与 GIF 拆帧后的局部真实微动效,解决纯手绘图形质感粗糙、缺少真实动态的问题。自带完整运行时脚本、安装器、页面 API 手册与一个不联网不花钱的单页样板;保留分段缓存、确定性渲染、字幕与音画对齐。当用户要求「画面更精致」「矢量图解」「加一点真实动效」「动图解说法」「AI 生图接入讲解视频」时使用。触发词:矢量动效、精致图解、动效增强、SVG 讲解视频、GIF 微动效、vector motion explainer。

Safety scan

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

Badge for your README
findsafeskills safety rating

Markdown

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

HTML

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

Install

i

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 · 242 lines
  1. ---
  2. name: whiteboard-teacher-video-motion
  3. version: 1.0.0
  4. display_name: 矢量动效讲解视频
  5. display_name_en: Vector Motion Explainer Video
  6. description: 独立可用的手绘讲解视频 skill。在「代码逐笔绘制」的白板讲解片里,加入 GPT Image 2.6 Flare 生成的原生 SVG 矢量图解(由时间轴驱动逐笔生长)与 GIF 拆帧后的局部真实微动效,解决纯手绘图形质感粗糙、缺少真实动态的问题。自带完整运行时脚本、安装器、页面 API 手册与一个不联网不花钱的单页样板;保留分段缓存、确定性渲染、字幕与音画对齐。当用户要求「画面更精致」「矢量图解」「加一点真实动效」「动图解说法」「AI 生图接入讲解视频」时使用。触发词:矢量动效、精致图解、动效增强、SVG 讲解视频、GIF 微动效、vector motion explainer。
  7. description_zh: 独立的手绘讲解视频 skill:用 AI 生成的原生 SVG 做精致矢量图解、GIF 做局部微动效,两者都接进 frametell 的纯函数时间轴,不破坏音画对齐与确定性渲染。安装后即可离线跑通自带样板。
  8. description_en: A standalone whiteboard explainer-video skill: native AI-generated SVG diagrams drawn stroke by stroke on the timeline, plus GIF frame sequences as local micro-motion, both wired into frametell's pure-function timeline. Ships with its own runtime, installer, docs and an offline sample.
  9. license: MIT
  10. ---
  11. # 矢量动效讲解视频 · whiteboard-teacher-video-motion
  12. **这是一个完整、独立、可直接安装的 skill。** 仓库自带运行时脚本、安装器、页面 API 手册、
  13. 免费配音后端、单页离线样板。不需要先装别的项目(引擎由 `scripts/setup.py` 自动获取)。
  14. 它和上游 [`whiteboard-teacher-video`](https://github.com/liangdabiao/whiteboard-teacher-video)
  15. 同源:保留了「讲到哪画到哪」的确定性、可秒级重渲、分段缓存;只补上纯代码绘图最弱的一层——
  16. 图形质感与局部真实动态。
  17. | 需求 | 用什么 | 时间轴怎么驱动 |
  18. |---|---|---|
  19. | 精致的图解、图标、结构图 | GPT Image 2.6 Flare 的**原生 SVG** | 内联进 DOM,由 `P.vector()` 按 `lt` 驱动 `stroke-dashoffset` 逐笔生长 |
  20. | 局部「活起来」的微动效 | 同模型的 **GIF** | 拆成 `f000.jpg…` 帧序列,交给引擎自带的 `P.clip()` 按 `lt` 取帧 |
  21. | 文字、箭头、强调、相机 | **照旧手绘** | `P.text` / `P.arrow` / `P.mark` / `P.cam` |
  22. 文字仍由手绘 `P.text` 出(不让 AI 在 SVG 里写字):字体、术语、事实都要能人工核对。
  23. 用户已确认「AI 素材和手绘版面非常兼容」,黑白细线稿 + 彩色写实微动图是既定风格。
  24. ---
  25. ## 0. 安装(第一次必做)
  26. ```bash
  27. git clone https://github.com/liangdabiao/whiteboard-teacher-video-motion.git
  28. cd whiteboard-teacher-video-motion
  29. python scripts/setup.py # 拉 AGPL 引擎(约 16MB) + npm install(约 130MB)
  30. pip install Pillow edge-tts # GIF 拆帧 / 免费中文配音
  31. ```
  32. 需要 Python 3.9+、Node ≥ 22.19、Chrome 或 Edge、git。
  33. `setup.py` 会自检浏览器、ffmpeg、Node、Pillow、配音后端,并把缺失项打印出来。
  34. **`apiz` CLI 是可选的**:只有「生成新素材」时才需要(需账号、按量计费)。
  35. 仓库 `examples/sample/assets/raw/` 里已放好 1 个 SVG + 1 个 GIF,
  36. 不联网、不花钱就能跑通全流水线。**先跑离线样板,确认环境,再决定要不要接付费素材。**
  37. WorkBuddy 用户:把整个仓库目录放到 `<工作区>/.workbuddy/skills/whiteboard-teacher-video-motion/`
  38. 即可被识别;任何目录下的独立 clone 也能直接跑脚本。
  39. ---
  40. ## 1. 先搞清楚一件事(别把它当视频模型)
  41. 核实过官方规格与 apiz 的 `params_schema` 后:
  42. - **SVG 是静态矢量**:无脚本、无外部资源、无内嵌位图,`n=1`,编辑接口不返回。
  43. 它本身**不带任何动效** —— 动效是本 skill 的时间轴加的。
  44. - **GIF 是微动图**:官方 2–64 帧,**apiz 通道最多 9 帧**(`params_schema` 的 `maximum: 9`);
  45. 默认 9 帧 × 200ms ≈ 1.8 秒循环。
  46. - 两者只能用 generations 接口,**不能用 edit 接口做局部精修**,改一处只能重新抽卡。
  47. 所以能兑现的不是「动效更丰富」,而是**画面质感 + 局部真实动态**,
  48. 音画对齐仍由引擎保证。想整片变成 AI 生成画面,不要用这个 skill。
  49. ---
  50. ## 2. 引擎契约(红线)
  51. **整片是时间的纯函数**:`ENGINE.renderAt(t)` 渲染第 `t` 秒,与之前播放过什么无关。
  52. 由此才有分段缓存、并行渲染、任意跳转、确定性校验。
  53. | 红线 | 原因 |
  54. |---|---|
  55. | **不要把 `.gif` 直接塞 `P.img`** | 浏览器按自己的时钟播 GIF,与 `lt` 无关 → 同一 `t` 每次渲染结果不同 |
  56. | **SVG 里的 `<animate>` / SMIL / CSS animation / transition / 外链 / 位图必须剥掉** | 同上;`ftasset.py` 落盘前已自动清洗 |
  57. | **页面里禁止 `Math.random()` / `Date.now()` / `rAF`** | 契约;随机走 `PV.rng(seed)` |
  58. | **素材重新生成后,`extras/` 里的哈希必须跟着变** | 引擎分段缓存 digest **不 hash `assets/`**。`ftasset.py` 写的 `asset-manifest.js` 就是干这个的 |
  59. | **`META.extras` 顺序不能反** | `boot.js` 按序加载:`svg-assets.js` → `clips.js` → `asset-manifest.js` → `motion-svg.js` |
  60. **生成不确定,渲染确定** —— 素材是抽卡,但一旦落盘成文件,
  61. 后面每一帧渲染、每一页重渲、每一次确定性校验都与纯手绘版完全一样。
  62. ---
  63. ## 3. 工作流
  64. `<skill>` = 本仓库目录;`<项目>` 必须放在 **skill 目录之外**(`ftnew.py` 会建 engine 链接,
  65. 放在里面会形成目录环)。
  66. ```
  67. ① 读 references/storyboard-method.md → 写 storyboard.json
  68. ② ★★★ 停下来,把分镜念给用户确认 ★★★ ← 唯一强制闸门,不跳过
  69. ③ 写 script.js(口播 cue)+ 填 META.extras 四项
  70. ④ python <skill>/scripts/ftnew.py <项目> --title "..." --style whiteboard
  71. ⑤ python <skill>/scripts/ftasset.py <项目> --spec <项目>/assets.json ← 新增
  72. ⑥ python <skill>/scripts/ftvoice.py <项目>
  73. ⑦ 逐页写 pages/pNN.js(P.vector / P.clip / 手绘混排)
  74. ⑧ python <skill>/scripts/ftcheck.py <项目> → lint + 每页拼图,逐页看图
  75. ⑨ cd <项目> && node engine/tools/snap.mjs --only pNN <讲完时刻> --sheet pNN-final
  76. ⑩ cd <项目> && node <skill>/scripts/ftdeterminism.mjs ← 含 P.clip 必跑
  77. ⑪ python <skill>/scripts/ftrender.py <项目> --fps 24
  78. ⑫ ★ 交付给用户看 ★ → 等确认再改
  79. ```
  80. 第 ⑤ 步产出(全在项目目录内):
  81. ```
  82. assets/raw/<name>.svg|.gif 原始下载,断点续用;已存在就跳过 API(不重复花钱)
  83. assets/svg/<name>.svg 清洗后的 SVG
  84. assets/clips/<name>/f000.jpg… GIF 拆出的帧序列
  85. extras/svg-assets.js window.SVG_ASSETS(同步内联,build 阶段不 fetch)
  86. extras/clips.js window.CLIP_FRAMES(帧数注册)
  87. extras/asset-manifest.js 素材哈希,让缓存感知变化
  88. extras/motion-svg.js 从本仓库 lib/ 自动复制过去
  89. ```
  90. `ftasset.py` 还会修 AI 写坏的 SVG 数值属性(未求值算式就地求和、无法解析的 `d` 整条剔除);
  91. 每批新素材仍要看一次浏览器 console,别假定 AI 输出一定合法。见手册坑 ⑦。
  92. > **含 `P.clip` 的项目别用 `ftcheck.py --determinism` 下结论**:引擎那条校验
  93. > 不 await `__frameReady`,会对帧序列误报(实测 11 页误报 8 页)。
  94. > 用 ⑩ 的 `ftdeterminism.mjs`,它复刻同样比较但补上等待。见手册坑 ⑧。
  95. > **批量素材一次跑完,中途失败直接重跑全量**:`ftasset.py` 幂等,
  96. > 已有 `assets/raw/` 会跳过、不重复花钱。见手册坑 ⑥。
  97. > 若报 `HTTP 429 — API Key 额度不足`:`apiz account balance` 有钱也没用,
  98. > 那是 **API Key 自带独立额度**用尽(串行也照样报,不是并发问题),
  99. > 需到控制台提高/重置该 Key 额度。
  100. `assets.json` 清单格式:
  101. ```json
  102. {
  103. "defaults": { "quality":"low", "complexity":"low", "aspect_ratio":"1:1", "size":"1K" },
  104. "svg": [ { "name":"bulb-line", "prompt":"...clean native SVG vector paths..." } ],
  105. "gif": [ { "name":"bulb-pulse", "prompt":"...seamless loop...",
  106. "frame_count":9, "frame_duration_ms":200 } ]
  107. }
  108. ```
  109. 常用参数:`--only <name>` 只做一个、`--force` 重抽(会再花钱)、`--dry-run` 只看计划。
  110. ---
  111. ## 4. 页面 API
  112. ```js
  113. // 左:SVG 逐笔生长
  114. P.vector('bulb-line', 190, 260, 540, 540, {
  115. at: P.c(0), dur: 2.6, mode: 'draw', // 'draw' | 'fade' | 'instant'
  116. stagger: 0.55, fillDelay: 0.62, // 路径错开、填充延后
  117. stroke: 'blue', sw: 3, // 可选:只改显式描边色,不动 url(#gradient)
  118. });
  119. // 右:GIF 拆帧后的循环
  120. P.clip('bulb-pulse', 1100, 260, 540, 540, {
  121. at: P.c(2), fps: 5, loop: true, // 200ms/帧 → 5fps
  122. // 可用 pingpong / timeMap 对齐 P.cw(i,'词') / speed / from / to / start
  123. });
  124. ```
  125. `P.clip` 是引擎自带接口(`engine/runtime/media.js`),支持 `loop / pingpong / timeMap /
  126. fps / speed / from / to / start`;`__frameReady(t)` 会等帧解码完再重绘,
  127. 渲染、拼图、单帧三条路都 await 它。
  128. **可选手法,不是硬要求**:`pingpong` 能把 9 帧扩成 17 帧来回,缓解循环接缝;
  129. `timeMap` 能把动效卡在念到某个词的瞬间;`stroke:'ink'` 能让 AI 素材更贴白板风格。
  130. 用不用、用多少,看画面,不写死。
  131. ---
  132. ## 5. 硬纪律(每条都有实测依据)
  133. 1. **素材生成要幂等** —— `assets/raw/` 已有就跳过,生成是抽卡且计费。
  134. 2. **先看终态单帧** —— 动画最后才出现的元素,拼图最后一帧可能还没长完(实测只有 76%)。
  135. 3. **lint 全绿 ≠ 画面对** —— 构图、遮挡、文字被色块盖住只有看图能发现。
  136. **图不对题、旧素材串片 lint 也查不出**:必须逐页打开 `out/snap/pNN.jpg`,核对每页
  137. `P.vector` / `P.clip` 画的东西和当页口播是不是一回事。
  138. **素材必须按本片主题逐页生成**,禁止把上一部片子的 `assets/` 整库复制到新项目凑页数;
  139. `assets.json` 里每个素材都要能回答「它画的是本片第几页的哪句话」。
  140. 实测(2026-11-08 费曼片):11 页只新画 2 个素材、其余 9 页沿用相对论旧图,
  141. 讲电子反常磁矩却配 1919 日食三联证据图,用户当场发现。**逐页看图是内容核对,不是美学打磨,不可省。**
  142. 4. **字幕带 y > 900 不放内容**,文字底 = y + 字号×1.45。
  143. 5. **换素材后不必手清 `out/chunks`** —— manifest 会改 digest;但绕过 `ftasset.py`
  144. 手工换图就必须自己清缓存(引擎不 hash `assets/`)。
  145. 6. **组件方法叫 `P.vector()`,不能叫 `P.svg`** —— `Builder` 构造函数里
  146. `this.svg = s('svg', ...)` 是这一页的画布 SVG 元素,实例属性会遮蔽同名原型方法。
  147. 实测症状:组件挂载成功、`PV.Builder.prototype.svg` 是 function,但 `P.svg` 是 object,
  148. 页面 build 报「P.svg is not a function」。
  149. 7. **渲染长片用 `--workers 1`(已是默认值)** —— 引擎默认 12 个浏览器 worker,
  150. 11 页以上会 OOM;2026-11-08 实测 12 workers 两次崩、1 worker 一次成。
  151. ---
  152. ## 6. 能做 / 不能做
  153. **能**:知识科普、概念图解、流程推导、图标套组、产品结构图、四格分镜;五套风格;
  154. 横竖屏;中英配音;自动字幕;真实截图与 AI 素材混排;任意页单独重渲。
  155. **不能**:整片 AI 生成画面(会丢掉零成本、可精修、风格统一);写实照片级连续视频;
  156. 自动配乐;GIF 做不到长镜头或复杂运镜(最多 9 帧);用 edit 接口精修已生成的 SVG/GIF。
  157. > 判断信号:**这一页的 AI 素材如果没画出「手绘画不出的东西」,就不该用。**
  158. > 这是上游 3D 融合整片复盘换来的教训——技术图语言 ≠ 讲解语言。
  159. > 新题材建议先做一页样板给用户看,确认视觉融合度,再决定铺开多少页。
  160. ---
  161. ## 7. 文档索引(全部随包提供)
  162. | 什么时候读 | 读哪份 |
  163. |---|---|
  164. | 安装 / 快速开始 / 成本 / 许可 | `README.md` |
  165. | 第一次接素材 / 排错 | `references/vector-motion-guide.md`(完整实测、参数边界、8 个坑、已废规则清单、待实测项) |
  166. | 画任何一页之前 | `references/page-api.md` |
  167. | 定分镜 / 写口播 | `references/storyboard-method.md`、`references/script-format.md` |
  168. | 选风格 / 配色 | `references/style-packs.md` |
  169. | 配音报错 | `references/tts-backends.md` |
  170. | 引擎 / 依赖报错 | `references/troubleshooting.md` |
  171. | 第三方归属与许可 | `vendor/ATTRIBUTION.md` |
  172. ## 8. 依赖与许可
  173. - **自有代码 MIT**(`LICENSE`):本仓库的脚本、组件、文档。
  174. - **渲染引擎 Frametell 0.7.2 = AGPL-3.0-only**(Sitor Team):**不在仓库内**,
  175. `scripts/setup.py` 用 sparse checkout 从上游拉取、独立进程调用。
  176. ⚠ 不要把引擎源码拷进本仓库或闭源项目。详见 `vendor/ATTRIBUTION.md`。
  177. - **可选付费依赖**:`apiz` CLI + `apiz/gpt-image-2.6-flare`,只有生成新素材时需要。
  178. 实测单价:SVG ≈ ¥0.23、GIF ≈ ¥0.25;100 积分 = ¥1。11 页正片 21 个素材合计约 ¥2.75。
  179. - **免费配音**:`edge-tts`(默认,无需 key);`apiz` 是付费备选。
  180. - Python:Pillow(拆帧)、标准库 urllib(不使用 requests)。
  181. ## 9. 已完成度(发布前实测)
  182. | 验收项 | 结果 |
  183. |---|---|
  184. | 单页样板 `examples/sample` | 离线跑通,lint 0 错 0 提醒,终态单帧完整 |
  185. | 11 页正片 `pencil-craft-2026` | 121.9s / 33 句 / 11 SVG + 10 GIF,用户确认风格兼容 |
  186. | 确定性 | `ftdeterminism.mjs` 11/11 页 0.000% 差异 |
  187. | 成片 | 1920×1080 / 24fps / H.264+AAC / 33 条字幕,ffmpeg 全解码无错 |
  188. | 独立安装 | 从干净目录 clone + setup,不依赖任何本机既有路径(见 `README.md` 验收流程) |
README.md · README · 207 lines
  1. # whiteboard-teacher-video-motion · 矢量动效讲解视频
  2. > 一个**独立可用**的手绘讲解视频 skill:把 AI 生成的原生 SVG 矢量图解,
  3. > 和 GIF 拆帧后的局部真实微动效,接进「讲到哪画到哪」的确定性时间轴。
  4. ![单页样板:左侧 SVG 逐笔生长,右侧 GIF 循环微动效](docs/sample-frame.jpg)
  5. 它解决的是一个很具体的问题:纯代码画的白板讲解片,音画对齐和确定性都很好,
  6. **但图形质感粗糙、没有真实材质与光影的呼吸感**。这个 skill 只补这一层,
  7. 文字、箭头、强调、镜头仍然手绘。
  8. ![11 页正片《一支铅笔是怎样做出来的》终态一览](docs/pencil-craft-contact.jpg)
  9. 已完成并验收的正片:11 页 / 33 句 / 121.9 秒,11 个 SVG 逐笔生长 +
  10. 10 个 GIF 拆帧循环,混排手绘机械运动、配比条、计数器、相机推镜。
  11. 确定性校验 11/11 页像素一致。
  12. B站视频例子: https://www.bilibili.com/video/BV15SW76KEzJ/?vd_source=86926e418c83af75f6850b5546388a79
  13. ---
  14. ## 它和上游项目的关系
  15. 与 [`liangdabiao/whiteboard-teacher-video`](https://github.com/liangdabiao/whiteboard-teacher-video)
  16. 同源,但它**不是插件、不是补丁**:运行时脚本、安装器、页面 API 手册、免费配音后端、
  17. 离线样板全部随包提供。装了这一个就能跑,不需要先装上游项目。
  18. 引擎都是 [Frametell](https://github.com/sitor-ai/frametell)(`AGPL-3.0-only`),
  19. 由 `scripts/setup.py` 在安装时从上游 sparse checkout 拉取,**不进本仓库**。
  20. ---
  21. ## 快速开始(不联网、不花钱、不需要任何 API key)
  22. 仓库里 `examples/sample/` 已放好 1 个 SVG + 1 个 GIF 的原始素材。
  23. 先跑通这条离线链路,确认环境没问题,再考虑生成新素材。
  24. ```bash
  25. # 1) 安装
  26. git clone https://github.com/liangdabiao/whiteboard-teacher-video-motion.git
  27. cd whiteboard-teacher-video-motion
  28. python scripts/setup.py # 拉引擎 ~16MB + npm 依赖 ~130MB
  29. pip install Pillow edge-tts # GIF 拆帧 / 免费中文配音
  30. # 2) 复制样板到 skill 目录之外的项目位置(ftnew.py 会建引擎链接,项目不能放在 skill 里)
  31. cp -r examples/sample D:/films/my-sample # Windows;macOS/Linux 换成任意路径
  32. python scripts/ftnew.py D:/films/my-sample --title "矢量动效样板" --style whiteboard
  33. # 3) 素材 → 配音 → 质检 → 确定性 → 成片
  34. python scripts/ftasset.py D:/films/my-sample --spec D:/films/my-sample/assets.json
  35. python scripts/ftvoice.py D:/films/my-sample
  36. python scripts/ftcheck.py D:/films/my-sample
  37. cd D:/films/my-sample && node <skill>/scripts/ftdeterminism.mjs
  38. cd <skill> && python scripts/ftrender.py D:/films/my-sample --fps 24
  39. ```
  40. `ftasset.py` 看到 `assets/raw/` 已有素材会**直接复用、跳过 API**,因此第 3 步零费用。
  41. 成片在 `<项目>/out/`。
  42. > `ftnew.py` 检测到目录里已有 `script.js` 时会保留现有内容,只补 `engine` /
  43. > `engine_modules` 链接 —— 所以先复制样板、再跑它是正确顺序。
  44. 环境要求:Python 3.9+、Node ≥ 22.19、Chrome 或 Edge、git、ffmpeg(npm 依赖自带)。
  45. `setup.py` 会逐项自检并把缺失项打印出来。
  46. ---
  47. ## 生成自己的素材(可选的付费步骤)
  48. 只想用自带素材,可以整节跳过。
  49. 1. 安装 [`apiz` CLI](https://apiz.ai) 并配置好 API Key(`apiz auth` / `apiz account balance`)。
  50. 2. 在项目里写 `assets.json`:
  51. ```json
  52. {
  53. "defaults": { "quality":"low", "complexity":"low", "aspect_ratio":"1:1", "size":"1K" },
  54. "svg": [ { "name":"bulb-line", "prompt":"...clean native SVG vector paths..." } ],
  55. "gif": [ { "name":"bulb-pulse", "prompt":"...seamless loop...",
  56. "frame_count":9, "frame_duration_ms":200 } ]
  57. }
  58. ```
  59. 3. `python scripts/ftasset.py <项目> --spec <项目>/assets.json`
  60. 模型固定用 `apiz/gpt-image-2.6-flare`。实测单价 **SVG ≈ ¥0.23 / GIF ≈ ¥0.25**
  61. (100 积分 = ¥1);11 页正片的 21 个素材合计约 ¥2.75。
  62. 素材是抽卡,`assets/raw/` 会保留原始下载并作为断点续用的依据——
  63. 中断后重跑全量不会重复花钱。`--only <name>` 只做一个、`--force` 重抽、`--dry-run` 只看计划。
  64. ⚠ `HTTP 429 — API Key 额度不足`:这是 **API Key 自带的独立额度**,
  65. `apiz account balance` 显示有钱也一样会报(串行调用同样会报,不是并发问题)。
  66. 到控制台提高/重置该 Key 额度后重跑即可。详见 `references/vector-motion-guide.md` 坑 ⑥。
  67. ---
  68. ## 完整工作流
  69. | 步骤 | 命令 / 动作 | 说明 |
  70. |---|---|---|
  71. | ① 分镜 | 读 `references/storyboard-method.md`,写 `storyboard.json` | **停下来把分镜念给用户确认**,这是唯一强制闸门 |
  72. | ② 口播 | 写 `script.js`,`META.extras` 填四项 | 顺序不能反,见下 |
  73. | ③ 建项目 | `python scripts/ftnew.py <项目> --title "..." --style whiteboard` | 项目放在 skill 目录之外 |
  74. | ④ 素材 | `python scripts/ftasset.py <项目> --spec <项目>/assets.json` | 离线复用或付费生成;**素材必须本片主题专属,禁止整库复制上一部片子** |
  75. | ⑤ 配音 | `python scripts/ftvoice.py <项目>` | 默认 edge 免费;可选 apiz / 自备音频 |
  76. | ⑥ 画面 | 逐页写 `pages/pNN.js` | `P.vector` / `P.clip` + 手绘混排 |
  77. | ⑦ 质检 | `python scripts/ftcheck.py <项目>` | lint + 每页拼图,**逐页看图核对图文一致**(图不对题 lint 查不出) |
  78. | ⑧ 终态 | `cd <项目> && node engine/tools/snap.mjs --only pNN <讲完时刻> --sheet pNN-final` | 结尾才出现的元素拼图看不全 |
  79. | ⑨ 确定性 | `cd <项目> && node <skill>/scripts/ftdeterminism.mjs` | 含 `P.clip` 必跑 |
  80. | ⑩ 成片 | `python scripts/ftrender.py <项目> --fps 24` | 产出有/无字幕 mp4 + srt |
  81. `META.extras` 四项(顺序固定):
  82. ```js
  83. extras: ['extras/svg-assets.js', 'extras/clips.js',
  84. 'extras/asset-manifest.js', 'extras/motion-svg.js']
  85. ```
  86. 页面里两种素材的写法:
  87. ```js
  88. P.vector('bulb-line', 190, 260, 540, 540, {
  89. at: P.c(0), dur: 2.6, mode: 'draw', stagger: 0.55, fillDelay: 0.62,
  90. });
  91. P.clip('bulb-pulse', 1100, 260, 540, 540, {
  92. at: P.c(2), fps: 5, loop: true, // 9 帧 × 200ms → 5fps
  93. });
  94. ```
  95. 完整 API 见 `references/page-api.md`,实测边界与 8 个坑见
  96. `references/vector-motion-guide.md`,skill 入口是 `SKILL.md`。
  97. ---
  98. ## 三条不能破的契约
  99. 1. **整片是时间的纯函数**:`renderAt(t)` 与之前播放过什么无关。
  100. 所以 `.gif` 绝不能直接塞 `P.img`(浏览器按自己的时钟播),必须拆帧交给 `P.clip`。
  101. 2. **SVG 里的动画/脚本/外链/位图必须剥掉**,`ftasset.py` 落盘前自动处理;
  102. 页面里禁止 `Math.random()` / `Date.now()` / `rAF`。
  103. 3. **素材变了,`extras/` 的哈希要跟着变**:引擎分段缓存的 digest 不 hash `assets/`,
  104. `ftasset.py` 写的 `asset-manifest.js` 就是让缓存感知素材变化的。
  105. 生成不确定,**渲染确定**:素材抽卡是唯一不确定的环节,落盘后每一帧都可复现。
  106. ---
  107. ## 仓库结构
  108. ```
  109. SKILL.md skill 入口(AI 读这个)
  110. README.md 本文件
  111. LICENSE MIT(仅自有代码)
  112. package.json / package-lock.json 引擎所需的最小 npm 依赖
  113. scripts/
  114. setup.py / setup.ps1 安装:拉 AGPL 引擎 + npm install + 环境自检
  115. ftnew.py / ftvoice.py / ftcheck.py / ftrender.py / ftlib.py / edge_tts_speak.py
  116. ftasset.py ★ 素材链路:生成/下载/清洗/拆帧/写 extras
  117. ftdeterminism.mjs ★ 带帧解码等待的确定性校验
  118. lib/motion-svg.js ★ P.vector() 时间驱动 SVG 组件
  119. references/ 页面 API、分镜、口播格式、风格包、TTS、排错、实测手册
  120. examples/sample/ 离线单页样板(含 1 SVG + 1 GIF 原始素材)
  121. docs/ 示例画面
  122. vendor/ATTRIBUTION.md 第三方归属与许可说明
  123. ```
  124. `engine/` 与 `node_modules/` 不入库,由 `setup.py` 生成。
  125. ---
  126. ## 常见问题
  127. **`ftcheck.py --determinism` 报一堆 nondeterministic?**
  128. 引擎那条校验不等待 GIF 帧解码,会对帧序列误报(实测 11 页误报 8 页)。
  129. 真实渲染 / 拼图 / 单帧三条路径都等待。请用 `scripts/ftdeterminism.mjs` 判定,别改引擎源码。
  130. **渲染长片崩了,chunks 里只有 `.jobs-*.json`、0 个 mp4?**
  131. 引擎默认 12 个浏览器 worker,11 页以上会 OOM。本仓库的 `ftrender.py`
  132. 已把 `--workers` 默认设为 1,也可用 `--workers N` 调整。
  133. **AI 生成的 SVG 少了几笔?**
  134. 模型偶尔把未求值算式(`132+142.857…`)或英文单词写进数值属性,浏览器静默丢弃。
  135. `ftasset.py` 的清洗会就地求值 / 剔除坏路径;复用 `assets/raw/` 重跑不花钱。
  136. **`P.svg is not a function`?**
  137. 组件方法叫 `P.vector()`,不叫 `P.svg` —— `Builder` 实例属性 `svg` 是画布 SVG 元素,
  138. 会遮蔽同名原型方法。
  139. ---
  140. ## 许可
  141. | 部分 | 许可 | 说明 |
  142. |---|---|---|
  143. | 本仓库脚本 / 组件 / 文档 | **MIT** | `LICENSE`,Copyright © 2026 liangdabiao |
  144. | Frametell 引擎 | **AGPL-3.0-only**(Sitor Team) | 不在仓库内,`setup.py` 从上游拉取、独立进程调用 |
  145. | npm 依赖 | 各自许可 | 见 `package.json` |
  146. | `examples/sample/` 内的 AI 素材 | 随包提供,供离线验收使用 | 由 GPT Image 2.6 Flare 生成 |
  147. 第三方归属详见 `vendor/ATTRIBUTION.md`。
  148. **请不要把 AGPL 引擎源码拷进本仓库或闭源项目。**
  149. ---
  150. 作者:liangdabiao · <497070928@qq.com>
  151. 特别致谢: https://linux.do 社区支持

Ratings and comments

Sign in to rate this skill.

Sign in

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