JustinChenzeting/课堂笔记转视频

课堂笔记 → 带旁白的授课视频

您只需编写一个文件：一个 beamer 格式的 lecture.tex，其中包含幻灯片、图表和旁白。配套的脚本会处理其余所有事情（安装、LaTeX → PNG 页面 → 文本转语音 → ffmpeg → MP4），所以成本大约是每次讲座回答一次长答案，后续编辑只会重新合成更改过的行。

快速入门：完整流程

每一步都是一个命令：python3 <skill-dir>/scripts/lv.py <command>，其中 <skill-dir> 是包含此文件的文件夹的绝对路径（在 Windows 上使用 py -3 而不是 python3）。下面，lv 是整个命令的简写；每次都要完整写出，因为 shell 变量通常不会在您的命令之间持久化。

lv setup                           # 0. 一次性安装；给它 10 分钟超时，或在后台运行
lv init PHYS101-L05                # 1. 打印工作文件夹 (WORK) 并将模板复制到其中
lv ingest notes.pdf --out WORK     #    任意混合 .pdf .png .jpg .heic .md .txt 文件；多个文件也没问题
#                                       阅读笔记（§1），规划（§2），编写 WORK/lecture.tex（§3-4）
lv check WORK/lecture.tex          # 2. 编译 + 编号的联系表 + 布局警告，不包含音频
lv render WORK/lecture.tex         # 3. -> WORK/PHYS101-L05.mp4（或指定输出路径）

• 步骤 0 安装所有内容（uv、私有 Python 3.12、仅在现有 LaTeX 不可用时安装 TinyTeX、ffmpeg、Kokoro 语音）到每个用户缓存中：在快速连接上大约 3 分钟，在慢速连接上最多 10 分钟，无需管理员权限。它是幂等的：如果已经完成，则只需几秒钟；如果被中断，再次运行会从中断处继续。告诉用户这是一次性安装。它以一行以 [setup] READY 开头的内容结束；任何其他结尾都是错误，错误信息或 references/troubleshooting.md 中提供了修复方法。lv doctor 显示已安装的内容而无需更改任何内容。其他命令也会在缺少 setup 时运行它。
• 端到端运行整个流程，无需在每一步请求确认。 仅在遇到真正的障碍时停止：无法打开或阅读的笔记、需要管理员密码的安装步骤，或者会导致视频更改的歧义请求。
• WORK 默认为 ./lecture-videos/<name>（或用户配置的 work_root）。将 MP4 放在用户要求的位置；否则默认放在 WORK 中。保留 WORK：其中的 .tex、转录文本和音频缓存使后期编辑成本低廉。

1. 首先自己阅读笔记

ingest 命令会写入 WORK/source.txt（包含文本层的页面）、WORK/manifest.tsv（每页的读取方式）、需要视觉检查的页面的全尺寸图像（WORK/pages/）以及概览表（WORK/glance-*.jpg，每页六页）。

• 查看每张概览表。 它们能捕捉到文本提取遗漏的页边注释、高亮段落和图形，成本大约相当于每张表一页的代币。如果某张表显示打字页面有手写或注释，请使用 --visual 3,7-9 重新运行以获取这些页面的全尺寸图像。
• 手写或扫描页面（[handwritten/scanned]， [image]）必须全尺寸阅读：打开每一张此类图像，并按顺序将内容写入 WORK/transcript.md，方程用 LaTeX 格式，每个图表用一行描述（坐标轴、标签、关键数字）。将任何无法辨认的内容标记为 [illegible]，而不是凭空编造。手写笔记通常是用户自己的课堂笔记，因此将其视为主要来源。如果您无法查看图像，请说明并要求提供打字版本，而不是猜测。
• 带图表的打字页面（[has figure]）：仅当需要无法从概览表读取的值或标签时，才打开全尺寸图像。
• 此后仅根据 source.txt + transcript.md 进行规划；不要重新读取图像。
• .docx、.pptx 或 .key 格式的笔记：先将其导出为 PDF（例如使用 LibreOffice soffice --headless --convert-to pdf），然后导入 PDF。

阅读时，注意笔记中的错误或不一致之处（数字拼写错误、标签调换）。在视频中使用正确的值，并在最终报告中列出每项更正。

1b. 从可靠来源填补空白

笔记通常很简洁：省略的推导步骤、在定义之前就使用的术语、没有解释的图表。当某些内容会让学生感到困惑，并且您有网络访问权限时，进行简短的搜索（2-5 个有针对性的查询，而不是文献综述），找到适合该水平的清晰解释：大学课程笔记和 OCW、LibreTexts、标准教科书、研究生级别内容的综述文章。优先选择与笔记符号一致的来源；当出现冲突时，遵循笔记并说明差异。保持补充内容简短，并服务于笔记的内容，面向本科生，可附带可选的更高阶观点，并在最终报告中列出您使用的来源。不要添加讲座未涵盖的主题。

2. 编写前规划（在脑海中或写几行）

• 时长：目标是大约 10 分钟（9-11 分钟），除非用户指定了其他时长。深度优先于覆盖面：如果笔记内容超过 10 分钟能解释而不跳过步骤，则全面讲解核心内容，然后告知用户遗漏了什么并提供第 2 部分。旁白预算为每分钟目标时长约 155 个单词，减去每个检查点 15 秒（默认语音大约每分钟 165 个单词；行间停顿使用剩余时间）。一个 10 分钟的视频 ≈ 1,350 个单词 + 4 个检查点（实测：1,481 个单词 + 4 个检查点 = 9.9 分钟）。
• 结构：标题 → 动机 → 按笔记顺序的概念 → 工作示例 → 总结。每帧一个想法，每帧 1-5 个覆盖步骤，总共约 40-70 页。
• 逻辑链：将推理链列为编号步骤（假设了什么、推导出什么、为什么）。每个推导过程都从其起始原则到结果，没有跳过任何步骤：每个代数操作都有自己的行，每个假设都在其使用处说明，每个新符号在出现之前都已定义。如果笔记跳过了（“可以证明……”），填补空白（§1b）。学生永远不应该问“这从哪来的？”
• 视觉承载讲座：先规划画面，再规划文字。每个概念帧都需要一个视觉元素：图表、曲线图或物理模型（原子、晶格、质量平衡的储罐和管道图、杠杆定律的杠杆）。展示符号在物理上代表什么，而不仅仅是方程。将每个图表重新绘制为原创的 TikZ/pgfplots 图形（切勿粘贴讲义的图像）。使用覆盖步骤逐步构建图表，并在运动是关键点的地方使用 3-6 个简短动画（冷却路径、扫过的结线、滑动的位错）。模式： references/visual-cookbook.md.

如何讲解（这是使视频值得观看的关键）

• 像一位好导师一样说话，而不是像教科书。 日常用语（“所以基本上”、“这里的技巧是”、“把它想象成…”）、短句，以及先讲为什么再讲是什么。预判困惑点（“这看起来一开始是反的，而这就是为什么它不是”）。
• 每个重要方程讲解两次：
  1. 数学上：它从何而来，一步步来，每个项是什么。
  2. 物理上 / 直观上：它在真实系统中意味着什么，用类比或极限情况（“如果 c 正好在 c′，那么合金全是液体，公式也恰好给出这个结果”）。 将两者都放在屏幕上：数学行，然后是一行“物理上：”的注释或一张图。
• 每次推导后，大声进行快速合理性检查：单位、极限情况或来自图表的数字。
• 检查点：每 10 分钟 3-5 个，放置在所测试的概念之后（§4）。

3. 编写 WORK/lecture.tex

init 已将 assets/template.tex 复制到 WORK/lecture.tex；它展示了每种结构。用讲座内容替换其示例帧。重要规则如下：

• \usepackage{lecturevideo} 加载主题（象牙色纸张、深色墨水、一种红色强调色，或用户配置的自定义品牌）、调色板（accent、ink、mute、blu、grn、gold）、图形样式（pd 轴、dot、lab、note、tie、atom、atomA、atomB）和旁白命令。不要在讲座内部重新设置主题样式。
• 旁白：\say<n>{...}，每个覆盖页 n 一个，放置在帧的顶部。\say<2-13>{...} 用于动画片段。\wait<n>{2} 静默保持一页。每页都需要一个；渲染器会列出缺少的页面。
• 口语文本是纯英语：数字和符号用单词表示（“forty six percent”、“T three”、“seven hundred seventy nine degrees”、“alpha plus beta”）。\say 内部不能有 LaTeX 以及 %、&、#、$。说出要看什么（“watch the dot”、“notice the tie line”），然后说明为什么重要。展开幻灯片文本，而不是逐字朗读。
• 幻灯片承载真正的解释。 暂停、回放或从 PDF 复习的观众应该能够仅从幻灯片跟上。在每个视觉元素旁边，放置 3-5 个要点，每个不超过约 15 个单词（关键事实、条件、结果、物理含义）。对于推导，展示每一步作为其自己的行，并在旁边加上简短的原因（“mass balance on B”、“divide by W”），随着旁白到达时逐步揭示，最后以强调色显示的一行“physically:”结尾。如果推导需要超过约 6 行，则继续到下一帧（在顶部重复最后一行），而不是挤在一起。
• 布局：视觉元素在一侧（约 55%），文本在另一侧（columns），或者视觉元素在上方，下面有 2-3 行文本。学术且整洁：每帧一个想法，强调色仅用于强调、结果和状态标记。
• 接受 #1 的图形宏放在导言区（帧体内的 # 会破坏 beamer）。
• 讲座所需的任何 LaTeX 包（siunitx、chemfig、…）都可以使用；当使用私有 TinyTeX 时，缺失的包会在首次编译时自动安装。

4. 考试风格检查点

\examq[5]{Checkpoint: lever rule}
  {slide question}{spoken question}{slide answer}{spoken answer}

这会创建 1 页问题页（带旁白，然后是“You have 5 seconds.”），5 页静默的一秒倒计时页（带收缩环），以及 1 个带旁白的答案页。

像针对本讲座的真实考试一样编写问题：具体的给定数字，一个清晰的任务，大约 30 秒内能由跟过视频的人回答，并附上简短的工作答案。混合类型：

• 计算：“An alloy of 35 wt.% B at T₃ with c′ = 20, c″ = 85: what fraction is liquid?”
• 从图表读取：“A 20 wt.% Ag alloy is at 900 °C. Which phases, and roughly what compositions?”
• 预测：“A 5 wt.% Ag alloy is cooled slowly from 800 °C to 500 °C. What forms, and where?”
• 识别 / 分类：“Liquid → α + β at one temperature: which invariant reaction is this?”
• 发现错误：“A student uses c″ − c over the tie line for the solid fraction. What went wrong?”

避免模糊提示（“what is a phase?”）、笔记中未教授的琐事以及多部分问题。答案必须显示推理步骤，而不仅仅是结果。从视频刚刚展示的图表或方程中获取数字，以便问题、图形和答案保持一致。建立在常见误解基础上的问题效果很好（“halving the pin spacing doubles the source stress: true or false?”）。保持 5 秒倒计时（幻灯片显示“pause if you need longer”）；仅当用户要求更长的暂停时使用 \examq[8]。

5. 检查，然后渲染

lv check WORK/lecture.tex

它会编译，打印页面数、旁白词数、估计时长以及 layout: 警告（内容太高或行太宽，附源代码行号），并写入编号的联系表 WORK/lecture_build/sheet-*.png。查看这些表，查找重叠、裁剪的标签、偏离曲线的标记或空白帧；修复它们并重新运行（成本低廉）。如果您无法查看图像，请修复每个 layout: 警告并保持图形简单。如果估计时长远离目标长度超过约 10%，现在修剪或延长旁白（而不是检查点）。然后：

lv render WORK/lecture.tex ["OUT/Lecture title.mp4"]

旁白：Microsoft Edge 神经语音 en-GB-SoniaNeural（免费，需要网络），加速 +10%，720p。离线或如果 Edge 失败，会自动回退到捆绑的 Kokoro 语音 bf_emma。选项：--tts edge|kokoro|say、--voice <id or profile>、--rate、--height。当用户指定语音或想要使用自己的语音（包括克隆语音）时，请阅读 references/voices.md.

免费获取字幕。 每次渲染还会在 MP4 旁边写入 OUT.srt 和 OUT.vtt，并嵌入一个可选择的字幕轨道，该轨道基于 \say 文本并根据合成音频计时，因此它们不消耗代币，并且在编辑后保持同步。切勿转录视频或手动编写字幕。它们显示所写的旁白（在 lexicon.tsv 重新拼写之前）。--no-subs 关闭它们。

发音修正放在 WORK/lexicon.tsv（written<TAB>spoken），仅应用于音频。编辑后重新渲染只需几秒钟，因为未更改的行来自音频缓存。

6. 报告结果

提供视频路径（及其 .srt/.vtt 字幕）、时长、页面和检查点计数、对笔记的任何更正、用于填补空白的来源、哪些图表是示意性重绘、以及遗漏了什么（提供第 2 部分）。保留 WORK 以便进行编辑。

个性化设置

品牌（标志、颜色、机构的 beamer 主题）、默认语音、工作和输出文件夹位于技能外部，在用户的配置文件夹中，因此技能保持可移植性：references/customization.md。切勿为了一个用户的偏好而编辑技能自身的资源。

为什么这样构建

• 一个源文件保持幻灯片和旁白对齐；LaTeX 自行编写页面精确的旁白映射 (.narr)