Courseware Studio

把讲稿转换为音频驱动的单页 HTML 课件：旁白音频的 currentTime 是唯一时钟， 画面、字幕、章节与门禁全部由它派生；也可以导出线性 MP4 与标准字幕。

讲稿 ──► 逐句旁白 ──► 音频 + 逐句时间轴 ──► 单页 HTML ──►（可选）MP4 / SRT / VTT

成品是静态目录，播放不需要服务器、构建流程或账号，双击 index.html 即可。

本仓库是一个 Claude Code / Agent 环境的 skill：SKILL.md 是给模型读的契约， 本 README 面向使用者，说明输入、产物、命令与配置。

1. 产物

1.1 页面结构

左栏自上而下为章节头、SVG 舞台、画布内字幕与播放器行；右栏只放可查询的参考资料。 窄屏退化为单栏。

1.2 能力

• 逐句同步：一句旁白对应一个视觉步；换场与句间空档保留上一句画面与字幕。
• 画布内字幕：文本只来自时间轴，位置与字号固定；多人对话显示说话人标签； 已念过的字满墨、未念到的字压暗（跟读点亮）。
• 词拍：旁白念到哪个词，画面上那件东西就套上四角括号（词窗由字数与标点现算， 几何贴住目标实时测量）；标记累积到句末，导出成片也读得到"这一句点过谁"。
• 对照窗：两个版本同窗叠放、互补裁切，接缝随句间步进擦过，版本标签与画面同步； 导出帧与减动效直接落在该句声明的对照档位。
• 章节进度条：每节起点一根刻度，悬停显示段名与时间，可点击、可拖动； 支持 0.75×–2× 倍速、全屏与键盘操作。
• 门禁：在认知转折点插入 choice / hotspot / bucket / sequence / recall 五种交互，答对后放行。
• 导出：逐句截帧生成 MP4（无需录屏），或从同一时间轴导出 SRT / WebVTT。
• 机器可读检查：check_gates.py --json 输出 verdict / static / browser / note / exit_code，供 CI 与 agent 消费。

1.3 不负责的范围

掌握度、学习进度、复习排期与题库系统属于平台层，不在本 skill 范围内。门禁放行 只表示"这堂课可以继续"，不表示"已掌握"；页面不会出现"已通关"之类的表述。

播放位置同样不保存：关闭页面后从头播放，中途回看依赖进度条上的章节刻度。

2. 输入与输出

2.1 输入类型

使用内置 TTS 时，讲稿需整理为旁白脚本 JSON；字段定义与多人对话写法见 references/script.md §1。最小结构如下：

{
  "title": "主题",
  "segments": [
    {"id": "seg-1", "title": "第一段", "text": "第一句。第二句。"}
  ]
}

text 同时是朗读正文与字幕后唯一文本来源。可选字段包括 opening / closing、 段级 hl（结论句）、beat（句级停顿与语速）以及 speakers + dialogue （多人对话）。

2.2 可指定的参数

• 音色与语速：默认「冰糖」1.0×；内置八种音色（冰糖、茉莉、苏打、白桦、Mia、 Chloe、Milo、Dean）。查看完整列表：

  python scripts/narration.py --list-voices
  

• 门禁数量：默认按内容在认知转折点安排 1–2 道，长课最多 3 道；可要求增加或关闭。

• 导出格式：默认只生成网页；MP4 与字幕需显式指定。

• 讲稿结构：分段方式、每段内容与开场问题由作者决定，也可完全交给 agent 起草。

开场问题是影响课件质量的关键判断：它应当针对学习者大概率会答错的点，而不是讲师 自己关心的问题。这个判断无法由工具替代。

2.3 输出目录

lesson/
├── index.html                 # 成品页面，可双击打开
├── interactive_runtime.js     # 交互手势与门禁 runtime
└── audio/
    ├── combined.wav           # 完整旁白音轨
    └── narration_timing.json  # 逐句起止时间

3. 工作流与命令

完整命令行流程：

# 2. 旁白：逐句合成并拼接，输出音频与时间轴
python scripts/narration.py --source narration-source.json -o audio/

# 3. 时间轴：压成可内联的  片段
python scripts/build_timeline.py \
  --timing audio/narration_timing.json \