refactor: extract config.py, add burn_only, fix title_segments and font size

- Extract all path/API config to config.py (single source of truth) - Add run.py / burn_only.py / run.bat / burn.bat entry points - burn_only: skip transcription/subtitle gen, fast reburn existing SRTs - Fix title_segments: use transcript keyword time for split point - Fix subtitle: each overlapping title shows max title_duration (not full clip) - Fix burn_only font size: default from 90 to 60 - Delete old run_lesson1.bat/py, temp debug scripts - Update README, ARCHITECTURE, CHANGELOG, add USAGE.md
2026-05-03 23:22:10 +08:00
parent cf5004cf6a
commit aad1548348
39 changed files with 826 additions and 556 deletions
@@ -10,25 +10,30 @@

 ```
 lesson-highlights/
+├── config.py              # 统一配置（所有路径/API只改这里）
+├── run.py                 # 完整流水线入口
+├── burn_only.py           # 快速烧录入口（跳过转录/字幕生成）
+├── run.bat                # 运行完整流程
+├── burn.bat               # 快速重烧字幕
 ├── src/
-│   ├── main.py              # GUI 入口
-│   ├── gui.py               # GUI（参数输入 → 调用底层）
-│   ├── cli.py               # CLI 入口
-│   └── core/                # 共享底层
+│   ├── main.py            # GUI 入口
+│   ├── gui.py             # GUI（参数输入 → 调用底层）
+│   ├── cli.py             # CLI 入口
+│   └── core/              # 共享底层
 │       ├── __init__.py
-│       ├── ppt_parser.py    # PPT 解析 + LLM clips 提取
-│       ├── pipeline.py      # 视频处理流水线
-│       ├── subtitle.py      # 字幕生成
-│       ├── video.py         # 视频处理（提取/合并/烧录）
-│       ├── llm.py           # LLM 调用
-│       ├── corrections.py    # 术语纠正
-│       ├── constants.py     # 常量配置
-│       └── errors.py        # 错误处理
-├── config.ini               # API 配置（不提交 git）
-├── config.ini.example      # 配置模板
-├── start.bat               # GUI 启动器
-├── run.bat                 # 通用 CLI 启动器
-└── run_lesson1.bat        # 预设课程示例
+│       ├── ppt_parser.py  # PPT 解析 + LLM clips 提取
+│       ├── pipeline.py    # 视频处理流水线
+│       ├── subtitle.py    # 字幕生成
+│       ├── video.py       # 视频处理（提取/合并/烧录）
+│       ├── llm.py         # LLM 调用
+│       ├── corrections.py  # 术语纠正
+│       ├── constants.py   # 常量配置
+│       └── errors.py      # 错误处理
+├── config.ini             # API 配置（不提交 git）
+├── config.ini.example    # 配置模板
+├── start.bat             # GUI 启动器
+└── docs/
+    └── USAGE.md          # 使用指南
 ```

 ## 3. 核心模块
@@ -5,31 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

-## [版本号] - 日期
+## [Unreleased]

 ### Added
- 新功能
+- `docs/USAGE.md` - 使用指南（run.bat / burn.bat / 修改知识点流程）
+- `config.py` - 统一配置文件，所有路径和 API 配置集中管理
+- `run.py` / `burn_only.py` - 独立入口脚本
+- `--resume-from-burn` CLI 参数 - 快速烧录模式，跳过所有转录/字幕生成步骤

 ### Changed
- 功能变更
+- `run.bat` / `burn.bat` 替代原有的 `run_lesson1.bat`（不再需要改多处配置）
+- `ppt_parser.py`: 重叠片段的 `title_segments` 用 transcript 关键词首次出现时间计算切分点
+- `pipeline.py`: 新增 `_recalculate_title_segments_from_transcript()`，在转录完成后用实际 transcript 数据修正标题切换时间
+- `subtitle.py`: 多标题片段中每个标题最多显示 `title_duration` 秒（原逻辑会一直显示到片段结束）
+- `pipeline.py`: `step_burn` 的 `title_fontsize` 默认值从 90 改为 60

 ### Fixed
- 问题修复
-
-### Deprecated
- 弃用功能
+- `ppt_parser.py`: 不重叠的 clip 残留 `title_segments` 导致标题显示时长错误
+- `subtitle.py`: 重叠片段第二个标题显示时长超过 `title_duration`
+- `pipeline.py`: 快速烧录模式因 `video_params` 为空导致字号使用默认值 90 而非 60

 ### Removed
- 移除的功能
-
-### Security
- 安全相关
+- `run_lesson1.bat` / `run_lesson1.py` - 旧入口，已由 `config.py` + `run.bat` / `burn.bat` 替代

 ---

-## 示例
-
-### [1.0.0] - 2026-05-02
+## [1.0.0] - 2026-05-02

 ### Added
 - 初始版本发布
@@ -0,0 +1,117 @@
+# 使用指南
+
+## 快速开始
+
+### 1. 配置
+
+编辑项目根目录的 `config.py`：
+
+```python
+VIDEO = r"D:\...\直播回放.mp4"
+PPT = r"D:\...\课程.pptx"
+OUTPUT = r"D:\...\output"
+MAX_TOTAL_DURATION = 600  # 精华片段总时长上限（秒）
+API_KEY = "your-api-key"
+API_HOST = "https://ark.cn-beijing.volces.com/api/coding/v3"
+```
+
+所有路径和 API 配置只改这一个文件。
+
+### 2. 完整流程（首次运行）
+
+```bash
+run.bat
+```
+
+或直接：
+
+```bash
+python run.py
+```
+
+完整流程：PPT解析 → Whisper转录 → LLM校正 → 字幕生成 → 合并 → 烧录
+
+### 3. 修改字幕后快速重烧
+
+改完 `v1_title.srt` 或 `v1_content.srt` 后，直接：
+
+```bash
+burn.bat
+```
+
+跳过所有转录/字幕生成步骤，直接用已有片段和字幕文件合并烧录。**只改字幕文本时用这个**。
+
+## 修改知识点（替换PPT中的某个知识点）
+
+LLM 从 PPT 提取了 clip 后，如果你想把其中一个换成 PPT 里另一个知识点（比如把"音高"换成"旋律"）：
+
+### 步骤
+
+1. **改 `generated_config.yaml`**：把对应 clip 的 title 改成新知识点名称
+
+```yaml
+clips:
+  - title: 旋律    # ← 改成PPT里有的知识点
+    start: 200
+    end: 260
+```
+
+2. **删该 clip 的中间文件**（让它重新生成）：
+
+```
+intermediates/clip5.json    ← 删掉
+intermediates/clip5.mp4    ← 删掉
+```
+
+3. **重新运行**：
+
+```bash
+run.bat
+```
+
+系统会跳过其他已有 JSON 的 clip，只重新生成被删除了 JSON 的那一个 clip。
+
+### 原理
+
+- `run.bat` 检测到 `clip*.json` 已存在，就跳过 Whisper 转录
+- 删掉某个 clip 的 JSON 后，系统认为它需要重新生成
+- 重新生成时用新的 title 去 transcript 里匹配，重新找时间范围
+
+### 注意
+
+- `start`/`end` 如果填错了，生成的视频片段时间会不对
+- 如果不确定新知识点的时间范围，可以先随便填一个，跑完看效果再调整
+
+## 文件结构
+
+```
+output/
+├── generated_config.yaml   # clips 配置（可手动修改）
+├── intermediates/         # 中间文件（可删除特定clip的.json/.mp4重生成）
+│   ├── clip1.json        # Whisper 转录结果
+│   ├── clip1.mp4         # 提取的视频片段
+│   └── ...
+├── subs/                 # 字幕文件
+│   ├── v1_title.srt      # 标题轨（可手动修改文本+时间轴）
+│   └── v1_content.srt    # 正文字幕
+├── concat_merged.mp4     # 合并后的视频
+└── final.mp4             # 最终输出
+```
+
+## 命令对比
+
+| 命令 | 用途 | 耗时 |
+|------|------|------|
+| `run.bat` | 完整流程（PPT→视频） | 几十分钟 |
+| `burn.bat` | 只改字幕后快速重烧 | 几分钟 |
+
+## 常见问题
+
+**Q: `burn.bat` 改了字号没变化？**
+A: `burn.bat` 直接烧已有的 SRT 文件，不走 `subtitle.py` 的生成逻辑。如果改了渲染参数（如字号）需要重新生成字幕，必须 `run.bat`。
+
+**Q: 想改某个知识点的出现时间？**
+A: 直接改 `v1_title.srt` 里的时间轴，或者改 `generated_config.yaml` 然后删对应 clip 的 JSON 重新生成。
+
+**Q: 想删掉某个 clip？**
+A: 从 `generated_config.yaml` 里删掉那一条，然后删对应 `intermediates/clip*.json` 和 `clip*.mp4`，最后 `run.bat`。