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