课程生成器:手绘讲解视频 是做什么的?
输出:一个或多个 1920×1080 30fps H.264+AAC MP4(带嵌入式字幕)以及 .srt 文件,风格类似于有人在黑色 iPad 上用霓虹荧光笔教学(Caleb Eom 风格)。每个讲座写成一个紧凑的 spec.js(旁白与视觉元素一体);引擎负责布局、将每个绘图动作与语音同步,并进行渲染。
research → spec.js per lecture → build.sh (extract → TTS → scenes.js) → qa.sh (stills) → fix → render_lecture.sh → zip + deliver
风格规则(不可协商)
- 语速 ≈ 1.2倍,绝不更快。 API 语音:先修剪静音,然后对表现力强的声音使用
ATEMPO=1.05,对语速慢的声音使用ATEMPO=1.12。节拍之间留 0.2 秒间隙。1.25 倍以上会显得匆忙。 - 手工质感。 使用 Reenie Beanie 字体并添加逐字母抖动;rough.js 线条(粗糙度 ≥1.4)加上 SVG 湍流抖动。只有“打印”的证据卡片(表格、真实数字)才使用干净的无衬线字体。
- 黑色背景,霓虹角色:
w主色,g好/有效,p问题/警告,v概念,o动作/类比,y高亮/数字,b次要,gr引用/旁白。
教学结构(每个讲座)
- 钩子(20–40秒): 一个 relatable 的情景,然后一个令人惊讶的事实,再提出一个问题。接着是一个标题节拍,预览整个框架。
- 框架(
LAYERS,3–7项): 脊柱。每节在右上角显示一个带有其层编号的小抄。 - 各节: 每个节 1–3 个节拍。每个节拍只有一个想法和一个视觉元素。在旁白中说出来源名称,并在屏幕上以灰色显示。
- 直觉: 每节至少为一个抽象概念提供一个
analogy(“像烟雾报警器,而不是消防队”)。立即用通俗语言解释专业术语。 - 回顾与下集预告: 框架,已勾选的行,然后下一讲的标题,使整个课程连贯起来。
声音:就像同事边喝咖啡边解释。短句,“所以,”,“事情是这样的。”,“还记得 X 吗?”。按照口语方式写数字(“二零二六”,“一点七秒”)。避免在 say 中使用符号。
初学者友好模式(当要求让新手也能理解时):用自己的网络研究补充来源,为每个概念添加一个类比,并降低想法密度(每 3–4 分钟讲座约 500–650 词)。
准确性
对每个数字、日期和名称进行网络搜索。优先使用一手来源。将同一实验的数字保持在一起。标注供应商的说法(“供应商数据:请验证”)。切勿虚构书中未给出的示例;引用书中的原话。提供来源列表。
设置
在 ~/course 目录下工作,该目录是本技能 engine/ 文件夹的一份副本,这样音频和视频文件就不会存放在技能文件夹中。如果 ~/course 已存在,则跳过复制。
cp -r <this skill's folder>/engine ~/course && cd ~/course # 例如 ~/.claude/skills/course-generator-handwritten/engine
npm i && npm run browsers # Playwright + Chromium(需要 Node 20+)
pip install --break-system-packages soundfile numpy
cp .env.example .env # 在 .env 中填写 TTS_*(切勿提交它)
必须安装 ffmpeg。讲座文件夹(~/course/L02_Architecture/spec.js)与脚本位于同一目录;可以从任何目录调用脚本。
TTS 可插拔(tts.py):任何兼容 OpenAI 的 POST /audio/speech,且返回 response_format: "pcm"(24 kHz s16le)。通过环境变量或 .env 配置 TTS_URL、TTS_API_KEY、TTS_MODEL 和 TTS_VOICE。选择声音时,请用 2–3 种声音测试同一个节拍,挑选最有表现力的(音高方差最大),而不是第一个。每个节拍的音频会附带文本 sidecar 进行缓存,因此只有编辑过的节拍才会重新生成语音。切勿在已提交的文件中硬编码密钥或模型名称。
编写讲座:<Dir>/spec.js
const LECT = { label: '讲座 2 · 幕后', title: '七层架构' };
const LAYERS = ['通道与触发器', '网关', '持久协调器', '代理循环'];
say({ hook: "…", title: "…", recap: "…", outro: "接下来,…" }); // 注册介绍/回顾节拍
intro('S01_Intro', 'hook', 'title', [ items… ]);
section('S02_Gateway', 1 /*层索引*/, 'v' /*颜色*/, [
{ b: 'ga1', t: '前门', cite: '来源,2026', say: "旁白…", v: [ items… ] },
]);
recap('S06_Recap', 'recap', 'outro', ['行', '行'], '下一讲标题');
每个节拍都有自己独立的面板,相机在不同面板之间平移。布局会自动缩放以适应内容。
Items [type, ...args, opts?]:
| 类型 | 参数 |
|---|---|
big / text | str, colour, size |
note | str, colour(带箭头前缀的旁白) |
analogy | null, str, 'o'(带框的“可以这样理解…”) |
list | `[lines], colour, {num |
col | title, colour, [lines](在 row 内部使用) |
row | [[item],[item]…], {vs, gap}(并排) |
flow | [labels], [colours](带箭头的框) |
stack | [labels], {rh,size,w,cols,step} |
tokens | [words], colour, {step, cols}(自动换行) |
bars / hbars | `[[label, value, colour, valueLabel]…], {h |
eq | str, colour(带下划线的标题数字) |
card | title, rows[][], {w, hi:[rowIdx], hit:[time]}(打印的表格;第 0 行是表头) |
chart | [[[x,y]…], colour, label]…], {h, xl, yl} |
timeline / grid / gpus / people / down | 参见 dsl.js |
Timing opts(最后一个对象):at: 'word' 使该元素在该单词被说出时开始(occ: 2 表示第二次出现);times: [[beat, frac, 'f'], …] 设置每个部分的时序为节拍的一部分;step 使各部分交错开始。起始时间会被限制,确保绘制在节拍结束前至少 2.6 秒完成。允许的 opt 键在 dsl.js(OPTK)中白名单;未知键会被视为数据,因此需要在那里添加新键。
构建、质量检查、渲染
./build.sh L02_Architecture # beats.json, TTS, scenes.js;输出语音分钟数
./qa.sh L02_Architecture # 节拍结束时定格画面平铺到 L02_Architecture/qa/sheet*.jpg
./render_lecture.sh L02_Architecture "02 - 七层架构" # 2 条并行通道 → out/*.mp4 + .srt
在每个讲座渲染之前运行 QA 并检查每个画面。修复:
- 标签溢出框(引擎会缩小字体,但长标签仍需缩短);
- 卡片高亮显示在错误行(将表头计为第 0 行);
- 内容超出画面;
at单词不存在(日志中出现WORDMISS)。
对于多讲座,使用队列:每个目录一个 READY 标志,一次渲染一个,当 scenes.js 比 MP4 新时重新渲染。在云端,完成一个讲座大约需要 3–4 分钟渲染。后台作业必须通过 harness 跟踪(不要在可能休眠的 VM 上使用 nohup)。
交付
压缩 out/*.mp4 + *.srt,使用带编号和标签的文件名(“00 - Title.mp4”)。在回复中提供运行时表格、一行方法说明以及来源。
示例
examples/agents-L00-spec.js(概念讲座)和 examples/inference-B4-spec.js(证据密集型讲座)是完整的、已渲染的 spec 文件,可供复制参考。