@lmliheng/lesson-video 0.0.0-stage → 0.3.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# lesson-video
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Narrated **vertical lesson videos** (1080×1920, Douyin / Reels ready) from a written script — plus the cover art and the publishing copy that goes with them.
+
+The whole thing rests on one idea: **the picture is a pure function of time `t`**. You write what is said, edge-tts speaks it and hands back word-level timings, and every frame is then *computed* from that timeline. Voice, subtitles and slides line up by construction, so there is nothing to edit afterwards.
+
+```
+script.json  ──tts.py──▶  narration.wav + lesson.json  ──render.mjs──▶  30fps JPEG frames  ──build.py──▶  mp4 + srt
+covers.json  ──cover.mjs──▶  1080×1920 video cover + 1080×1440 profile cover
+```
+
+## Why it exists
+
+- **Safe areas for real phones.** App buttons and status bars cover the edges of a portrait screen, so the layout keeps the sides and the top empty by design: content lives inside 745 × 1170 px, and the subtitle band starts at y = 1470.
+- **A pre-render self-check.** `render.mjs --check` fails *before* spending minutes on frames: content past the subtitle safe line, code lines clipped by the card, and titles left with a one-character orphan line.
+- **No editing software, no GPU.** Headless Chrome + `imageio-ffmpeg`; a three-minute episode renders in about five minutes on CPU, and re-rendering after a script fix is one command.
+- **No baked-in branding.** Watermark, brand mark, CTA and every caption come from the data files — the templates ship with nothing of anyone's hard-coded.
+
+## What's inside
+
+| Path | What it is |
+| --- | --- |
+| `skills/lesson-video/SKILL.md` | The skill: script schema, the three commands, the layout rules, the pitfalls |
+| `skills/lesson-video/kit/` | The toolkit — `tts.py`, `render.mjs`, `build.py`, `deck.html`, `cover.mjs`, `cover.html`; copy it into a project as `lib/` |
+| `skills/lesson-video/example/` | A skeleton `script.json` (four scene types) and `covers.json` |
+
+## Requirements
+
+| Need | Install |
+| --- | --- |
+| Python packages | `pip install edge-tts imageio-ffmpeg` (the ffmpeg binary comes with the second one) |
+| Playwright core | any usable `playwright-core`; point `PLAYWRIGHT_MODULE` at it |
+| A browser | any Chrome / Chromium; point `CHROME_PATH` at it |
+
+## Quick start
+
+```bash
+cp -r <skill>/kit/* <project>/lib/
+mkdir -p <project>/lessons/ep01
+
+# 1. write <project>/lessons/ep01/script.json   (see the skill for the schema)
+
+PYTHONUTF8=1 python lib/tts.py lessons/ep01
+node lib/render.mjs --dir lessons/ep01 --check          # 10s: safe area, clipped code, orphan titles
+PLAYWRIGHT_MODULE=… CHROME_PATH=… node lib/render.mjs --dir lessons/ep01
+PYTHONUTF8=1 python lib/build.py lessons/ep01           # out/ep01.mp4 + out/ep01.srt
+```
+
+## License
+
+Apache-2.0

package/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Lesson video">
+  <rect x="20" y="5" width="24" height="54" rx="6" fill="#2f6fed"/>
+  <rect x="24.5" y="10" width="15" height="44" rx="3.5" fill="#0b1220"/>
+  <path d="M30 25.5v13l10-6.5z" fill="#eaf1ff"/>
+  <rect x="27.5" y="43" width="9" height="2.6" rx="1.3" fill="#7aa7f7"/>
+  <rect x="27.5" y="47.5" width="6" height="2.6" rx="1.3" fill="#5f8ff0"/>
+</svg>

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@lmliheng/lesson-video",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.1",
+  "description": "Narrated vertical lesson videos (1080x1920) from a script: an HTML slide deck driven by time, edge-tts voice-over with word-level timing, Playwright frame capture, ffmpeg mux, cover art and publishing copy.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lmliheng/Adelie.git",
+    "directory": "plugins/lesson-video"
+  },
+  "keywords": [
+    "adelie-plugin",
+    "penguin-harness",
+    "video",
+    "1080x1920",
+    "vertical",
+    "tts",
+    "edge-tts",
+    "playwright",
+    "ffmpeg",
+    "slides"
+  ],
+  "files": [
+    "plugin.json",
+    "icon.svg",
+    "README.md",
+    "skills",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/plugin.json

@@ -0,0 +1,9 @@
+{
+  "description": "Produce a narrated vertical lesson video (1080x1920) and its cover art from a written script: an HTML slide deck driven purely by time, edge-tts voice-over with word-level timing, Playwright frame capture, and an ffmpeg mux with edge safe areas left empty for mobile app buttons — plus a pre-render self-check for text overflow, and publishing copy with at most five tags.",
+  "description_zh": "把写好的讲稿做成竖屏教学视频（1080×1920）与配套封面：HTML 课件按时间轴定格、edge-tts 逐词对齐配音、Playwright 逐帧截图、ffmpeg 合成，两侧与上部按手机 App 按钮留出安全区，渲染前先自检越界与裁切，并给出标签不超过五个的发布文案。",
+  "short_description": "Narrated 1080x1920 lesson video from a script: HTML deck + edge-tts + ffmpeg.",
+  "short_description_zh": "讲稿一键成竖屏教学视频（1080×1920）：HTML 课件 + edge-tts + ffmpeg，含封面与发布文案。",
+  "version": "2026.10.06.1",
+  "category": "office-productivity",
+  "preinstall": false
+}

package/skills/lesson-video/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: lesson-video
+description: Turn a narration script into a narrated vertical lesson video (1080x1920, Douyin/Reels ready) plus matching cover art — an HTML slide deck driven purely by time, edge-tts voice-over with word-level timing, Playwright frame capture, and an ffmpeg mux with burned-out safe areas. Use whenever the task is to produce a short portrait teaching or explainer video, a narrated slide video, or its cover and publishing copy, from a written script or from source material such as a notebook, dataset or paper.
+---
+
+# 竖屏教学视频：讲稿 → 配音 → 逐帧渲染 → 成片 + 封面
+
+## Before you start
+
+如果消息只是点名这个技能（比如「用 lesson-video」）而没有具体要讲的内容，先问清楚讲什么、给谁看、
+一集多长——**先有话，再有画面**，没有讲稿就没有可渲染的东西。有内容时先自检三样东西在不在：Python
+包（`edge-tts`、`imageio-ffmpeg`）、一个可用的 `playwright-core`、一个 Chrome/Chromium 可执行文件；
+缺哪个按第一节的表装哪个，别急着渲染。渲染是最后一步，不是第一步：`render.mjs --check` 先过一遍，
+再花那几分钟出帧。
+
+## 结论先行
+
+一句话：**画面是时间 t 的纯函数**。先用话把内容说清楚，把每一句话写成脚本，配音合成后拿到逐词时间，画面按这个时间去定格 —— 于是配音、字幕、画面天然咬合，不需要剪辑。
+
+| 你要的东西 | 用哪一步 | 产物 |
+| --- | --- | --- |
+| 一份讲稿 | 手写 `lessons/<集>/script.json` | 分镜 + 旁白 + 出现时机（`cue`） |
+| 配音 + 时间轴 | `python lib/tts.py lessons/<集>` | `audio/narration.wav`、`lesson.json` |
+| 逐帧画面 | `node lib/render.mjs --dir lessons/<集>` | `frames/f_00000.jpg…` (30fps) |
+| 成片 + 字幕 | `python lib/build.py lessons/<集>` | `out/<id>.mp4`、`<id>.srt` |
+| 封面 | `node lib/cover.mjs --data covers/covers.json --out covers/out --sizes 1920,1440` | 1080×1920 与 1080×1440 两张 PNG |
+
+写成一条链（GPU 无关，纯 CPU，3 分钟的片子约 5 分钟出片）：
+
+```bash
+python lib/tts.py lessons/ep01          && \
+node   lib/render.mjs --dir lessons/ep01 && \
+python lib/build.py lessons/ep01
+```
+
+**动手前先跑自检**（10 秒，不出帧）：
+
+```bash
+node lib/render.mjs --dir lessons/ep01 --check
+```
+
+它报三件事：内容有没有越过 y=1470 的字幕安全线、代码行有没有被卡片裁掉、标题折行有没有剩下孤字。三项全过再花几分钟渲染。
+
+## 一、把工具包放进项目
+
+技能目录里的 `kit/` 就是全部工具，复制到项目下当 `lib/` 用：
+
+```bash
+mkdir -p <项目>/lessons/<集名> <项目>/covers
+cp -r <技能目录>/kit/* <项目>/lib/
+```
+
+`kit/` 六个文件，各管一件事：
+
+| 文件 | 作用 |
+| --- | --- |
+| `tts.py` | edge-tts 逐幕配音，拿逐词边界，写出 `lesson.json`（时间轴 + 字幕）+ `narration.wav` |
+| `render.mjs` | Playwright 逐帧截图；`--check` 只自检；`--scale 0.5` 低清预览 |
+| `build.py` | ffmpeg 合成 H.264/AAC、响度归一、`+faststart`，顺带写 SRT |
+| `deck.html` | 课件本体，一种 1080×1920 版式，幕类型见第三节 |
+| `cover.mjs` / `cover.html` | 封面图（9:16 视频首图 + 3:4 主页封面） |
+
+**依赖**（缺哪个装哪个）：
+
+| 依赖 | 装法 | 备注 |
+| --- | --- | --- |
+| Python 包 | `pip install edge-tts imageio-ffmpeg` | `imageio-ffmpeg` 自带 ffmpeg 二进制，不用单独装 ffmpeg |
+| Node 包 | 任意可用的 `playwright-core` | 用 `PLAYWRIGHT_MODULE` 指到它的路径即可，不必装进本项目 |
+| 浏览器 | 任意 Chrome / Chromium 可执行文件 | 用 `CHROME_PATH` 指过去 |
+
+两个环境变量（Windows / Linux 都一样，`render.mjs` 与 `cover.mjs` 都认）：
+
+```bash
+PLAYWRIGHT_MODULE=/path/to/node_modules/playwright-core \
+CHROME_PATH=/path/to/chrome.exe \
+  node lib/render.mjs --dir lessons/ep01
+```
+
+## 二、脚本 `script.json` 怎么写
+
+顶层字段：
+
+| 字段 | 含义 |
+| --- | --- |
+| `id` | 集目录名与成片名（`out/<id>.mp4`），如 `ep01-regression` |
+| `series` / `episode` / `brand` | 系列名 / 集标题（只在日志里用）/ **画面左上台标文字** |
+| `wm` | 画面右上角水印文字；不给就整块隐藏（模板里没有任何固定文案） |
+| `mark` | 台标方块的字母；不给就取 `brand` 的首字 |
+| `voice` / `rate` | edge-tts 音色与语速，如 `zh-CN-YunxiNeural` / `+18%` |
+| `gap` | 每幕之间的静音秒数，默认 0.35；一口气讲完的系列用 0.3 |
+| `scenes` | 幕数组，见下 |
+
+每一幕：`id`（幕内短名，用来命名音频）、`type`（版式）、`narration`（**这一集真正要讲的话**），其余字段按 `type` 取。
+
+| `type` | 特有字段 | 用途 |
+| --- | --- | --- |
+| `title` | `kicker` `title` `sub` `tags[]` | 开场：大标题 + 一句副标题 + 三两个标签 |
+| `points` | `kicker` `title` `items[]` | 要点幕，`<em>` 标蓝关键词 |
+| `math` | `kicker` `title` `steps[{label,formula,hi}]` | 公式卡，`hi: true` 把某张卡高亮；≥4 张自动切紧凑版式 |
+| `code` | `kicker` `title` `file` `code` `code_reveal` | 代码卡，`code` 用 `\n` 分行，逐行出现 |
+| `source` | 同 `code`，另加 `notes[]` | 代码 + 下方 2–3 条注记（读库源码时用） |
+| `outro` | `kicker` `title` `sub` `cta` | 结尾 + CTA 按钮 |
+
+### 出现时机：写 `cue`，不写秒数
+
+任何元素上写 `"cue": "关键词"`，`tts.py` 会在**配音的逐词时间**里找这个关键词，把元素出现的时刻标成 `at`（相对本幕秒数，比人声早 0.15s）。
+
+- 关键词必须**真的出现在同一幕的 `narration` 里**（`cue_time` 按去掉空白的字符流做子串匹配），否则静默失败、元素永不出现；
+- 想要 CTA 晚点出，就写 `"cta_cue": "关注"` —— 任何 `<名>_cue` 都会解析成 `<名>_at`；
+- 已经手写了 `at` 的不会被覆盖，两种写法可以混用；
+- 中文数字按念法写关键词：旁白念「负二点三四」，cue 就写 `负二点三四`，别写 `-2.34`。
+
+### 字数与节奏（实测）
+
+中文旁白约 **5.9 字/秒**（`rate` 为 `+18%`、`zh-CN-YunxiNeural`）——**3 分钟 ≈ 1070 字**，按这个数分配每一幕。写完先估一遍，别等合成完才发现超时。
+
+## 三、画面规矩（都在 `kit/deck.html` 里，改一处全片生效）
+
+**安全区**：抖音等 App 的按钮、状态栏会压住画面边缘，所以两侧和上部必须留白。当前版式：
+
+| 位置 | 数值 |
+| --- | --- |
+| 场景内边距 | `padding: 300px 185px 450px 150px`（上 / 右 / 下 / 左） |
+| 内容可用区 | 宽 **745px**、高 **1170px**（y=300 → y=1470） |
+| 左上台标 | `left:150px; top:172px` |
+| 右上水印 | `right:178px; top:180px` |
+| 字幕带 | y=1470 起，两行 46px/36px，居中 860px 宽 |
+
+由此推出两条硬约束：
+
+1. **内容底边 < 1470**（否则盖住字幕）；
+2. **代码行 ≤ 约 55 个西文字符**（卡片内宽 697px ÷ 等宽字体 12.65px/字；实测 51 字符安全）。代码里长行放不下就换行、或把变量名缩短，别指望它自己折 —— `.card-bd` 是 `overflow:hidden`，超了会被**悄悄裁掉**。
+
+另外两点：
+
+- `kicker` 会被 CSS `text-transform:uppercase`，**别在 kicker 里写希腊字母或中文以外的敏感字形**；
+- 标题用了 `text-wrap:balance`，折行时左右均衡，避免最后一行只剩一两个字。
+
+## 四、封面 `covers.json` + `covers/out/`
+
+```bash
+PLAYWRIGHT_MODULE=… CHROME_PATH=… \
+  node lib/cover.mjs --data covers/covers.json --out covers/out --sizes 1920,1440
+```
+
+每条封面一个对象：`id`（文件名前缀）`no`（集号，右上角大数字）`brand` `wm` `cta` `titleLines[]`（**自己写好断行**，最后一行自动标蓝）`subLines[]`（每行别超过约 20 字，多了会折成三行）`pills[]`（三个标签）`tag`（可选，接在「第 N 集」后面）`foot`（左下角一行）。
+
+一次出两张：`<id>-9x16.png`（1080×1920，视频首图）和 `<id>-1080x1440.png`（1080×1440，主页封面）。
+
+## 五、发布物料
+
+写进项目的 `covers/copy.md`，一集一段：**标题**（一句话，最好带一个真实数字）、**文案**（三行要点 + 每行一句解释）、**标签**。
+
+- 抖音描述**标签最多 5 个**（如 `#Kaggle #机器学习 #分类 #逻辑回归 #Python`），多了不显示；
+- 文案里的数字**必须是片子里真跑出来的**，不要编——这一条比排版重要得多。
+
+## 六、踩过的坑
+
+1. **Python 找不到 stdout 编码（Windows）**：控制台是 GBK，任何 `print` 中文或 `python -c` 都会 `UnicodeEncodeError`。所有 Python 调用前加 `PYTHONUTF8=1`。
+2. **`edge-tts` 偶尔空手而归**（`NoAudioReceived`）：`tts.py` 里已带 4 次重试，别自己再包一层；真的是网络断了再排查。
+3. **必须显式要 `boundary="WordBoundary"`**：edge-tts 7.x 默认按句返回边界，拿不到逐词时间，字幕就贴不上人声。
+4. **Python 写回的 JSON 是 CRLF**：要改已经生成过的 `lesson.json`，别用文本替换，改用 Python 脚本读写。
+5. **帧序列很占地方**：3 分钟的片子约 1.5 GB（5511 张 JPEG）。确认成片没问题后可以删 `lessons/<集>/frames/`，要重渲再跑一次 `render.mjs`。
+6. **渲染前千万别跳过 `--check`**：内容越线、代码被裁、标题孤字，这三类问题在成片里很难发现，在自检里一眼就能看到。
+7. **帧数与时间轴不符**：`build.py` 会比对帧数与 `duration × fps`，差超过 2 帧就报警 —— 那通常说明渲染中途被打断了，重渲。
+8. **`PLAYWRIGHT_MODULE` 指的必须是 playwright-core 的目录**（含 `package.json` 的那层），不是 `playwright`。
+
+## 七、边界
+
+- 画面是**时间 t 的纯函数**，没有 CSS 过渡、没有随机数：同一份 `script.json` 每次渲染结果一致，改一句话重渲即可，不需要剪辑软件。
+- 这套版式只做 1080×1920 竖屏；横屏或方形要另做版式（`deck.html` 的 `html,body` 宽高与场景内边距是硬编码的）。
+- 配音只走 edge-tts（免费、无需密钥）。要换别的 TTS，替换 `tts.py` 里的 `synth()` 即可，其余步骤不用动。

package/skills/lesson-video/example/covers.json

@@ -0,0 +1,14 @@
+[
+  {
+    "id": "demo-gap",
+    "no": "1",
+    "brand": "示例教程 · 1 集",
+    "wm": "@GitHub/your-handle",
+    "cta": "关注抖音号 your-handle",
+    "titleLines": ["一句话", "讲一件事"],
+    "subLines": ["两行副标题，每行别超过二十来个字", "第二行放一个真实数字"],
+    "pills": ["标签一", "标签二", "标签三"],
+    "tag": "示例",
+    "foot": "示例系列 · 第 1 集"
+  }
+]

package/skills/lesson-video/example/script.json

@@ -0,0 +1,53 @@
+{
+  "id": "demo-gap",
+  "series": "示例系列",
+  "episode": "第 1 集 · 示例",
+  "brand": "示例教程 · 1 集",
+  "wm": "@GitHub/your-handle",
+  "voice": "zh-CN-YunxiNeural",
+  "rate": "+18%",
+  "gap": 0.3,
+  "scenes": [
+    {
+      "id": "s1",
+      "type": "title",
+      "kicker": "第 1 集 · 示例",
+      "title": "一集三分钟，讲清一件事",
+      "sub": "标题、要点、代码，三幕都要有",
+      "tags": ["示例", "竖屏", "课件"],
+      "narration": "这一集是模板示例。三分钟讲一件事，画面由时间轴驱动，配音和字幕都是从同一份脚本里长出来的。"
+    },
+    {
+      "id": "s2",
+      "type": "points",
+      "kicker": "01 · 要点",
+      "title": "要点幕：三行字就够",
+      "items": [
+        "每行一句话，<em>关键词</em>用 em 标蓝",
+        "cue 写在 content 上，配音念到就出现",
+        "整幕内容不能越过 y=1470 的字幕安全线"
+      ],
+      "narration": "要点幕放三行就够。关键词用 em 标出来，配音念到哪个词，哪一行就跟着出现，不用手算时间。"
+    },
+    {
+      "id": "s3",
+      "type": "code",
+      "kicker": "02 · 代码",
+      "title": "代码幕：行宽是关键",
+      "file": "demo.py",
+      "code": "def hello(name):\n    return f\"hi {name}\"",
+      "code_reveal": 3,
+      "narration": "代码幕要注意行宽，太长的行会被卡片裁掉，渲染前的自检会告你哪一行越界。"
+    },
+    {
+      "id": "s4",
+      "type": "outro",
+      "kicker": "下一集",
+      "title": "把标题写在这里",
+      "sub": "副标题写一句就够了",
+      "cta": "关注抖音号 your-handle",
+      "cta_cue": "关注",
+      "narration": "好，这一集就到这。关注我，下一集见。"
+    }
+  ]
+}

package/skills/lesson-video/kit/build.py

@@ -0,0 +1,78 @@
+"""把帧序列 + 配音轨 + 字幕合成成竖屏 MP4（1080x1920，H.264/AAC，抖音可直传）。
+
+用法: python lib/build.py lessons/ep00-pilot [--out out/pilot.mp4]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+from pathlib import Path
+
+import imageio_ffmpeg
+
+FFMPEG = imageio_ffmpeg.get_ffmpeg_exe()
+
+
+def srt_time(sec: float) -> str:
+    ms = int(round(sec * 1000))
+    h, ms = divmod(ms, 3600_000)
+    m, ms = divmod(ms, 60_000)
+    s, ms = divmod(ms, 1000)
+    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
+
+
+def write_srt(subs: list[dict], path: Path) -> None:
+    lines = []
+    for i, s in enumerate(subs, 1):
+        lines += [str(i), f"{srt_time(s['start'])} --> {srt_time(s['end'])}", s["text"], ""]
+    path.write_text("\n".join(lines), encoding="utf-8")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("dir")
+    ap.add_argument("--out")
+    ap.add_argument("--crf", type=int, default=18)
+    args = ap.parse_args()
+
+    d = Path(args.dir).resolve()
+    lesson = json.loads((d / "lesson.json").read_text(encoding="utf-8"))
+    frames = sorted((d / "frames").glob("f_*.jpg"))
+    if not frames:
+        raise SystemExit(f"没有帧，先跑 render.mjs：{d / 'frames'}")
+    audio = d / "audio" / "narration.wav"
+    out = Path(args.out) if args.out else d / "out" / f"{lesson['meta']['id']}.mp4"
+    if not out.is_absolute():
+        out = d / out
+    out.parent.mkdir(parents=True, exist_ok=True)
+
+    fps = lesson["fps"]
+    expect = round(lesson["duration"] * fps)
+    if abs(len(frames) - expect) > 2:
+        print(f"⚠ 帧数与时间轴不符：{len(frames)} vs {expect}")
+
+    write_srt(lesson["subtitles"], out.with_suffix(".srt"))
+
+    cmd = [
+        FFMPEG, "-y", "-hide_banner", "-loglevel", "error",
+        "-framerate", str(fps), "-start_number", "0", "-i", str(d / "frames" / "f_%05d.jpg"),
+        "-i", str(audio),
+        # JPEG 帧是全范围，转成广播标准的 limited range + bt709，避免平台转码后发灰
+        "-vf", "scale=in_range=full:out_range=tv,format=yuv420p",
+        "-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709",
+        "-c:v", "libx264", "-preset", "slow", "-crf", str(args.crf),
+        "-profile:v", "high", "-level", "4.2",
+        # 社媒响度：-14 LUFS / 真峰值 -1.5 dBTP
+        "-af", "loudnorm=I=-14:TP=-1.5:LRA=11",
+        "-c:a", "aac", "-b:a", "192k", "-ar", "48000", "-ac", "1",
+        "-shortest", "-movflags", "+faststart",
+        str(out),
+    ]
+    subprocess.run(cmd, check=True)
+    print(f"OK {out}  {out.stat().st_size / 1024**2:.1f} MB  "
+          f"{lesson['duration']:.1f}s @ {fps}fps  字幕 {out.with_suffix('.srt').name}")
+
+
+if __name__ == "__main__":
+    main()