docs: add GUI edit design spec

2026-05-03 23:49:14 +08:00
parent aad1548348
commit 088db28a77
1 changed files with 112 additions and 0 deletions
@@ -0,0 +1,112 @@
+# Piano Highlight Generator - GUI 修正功能设计
+
+## 背景
+
+现有 GUI 仅有"选文件+开始处理"的功能，跑完后用户无法对结果进行修正。本设计在跑完之后提供知识点编辑和字幕编辑能力，支持增删改，并自动判断如何应用修改。
+
+## 名词定义
+
+- **clip**：底层实现细节，表示一个视频片段（start/end/title_segments）
+- **知识点**：用户感知的单位，即 clip 的 title
+- **标题**：v1_title.srt，知识点名称的大字叠加层
+- **字幕**：v1_content.srt，实际转录文本的小字叠加层
+
+## 用户流程
+
+```
+PPT解析 → 跑流程 → GUI显示结果
+                        ↓
+              ┌─────────┴─────────┐
+         编辑知识点             编辑字幕
+         （改/删/增标题）         （改/删文本）
+              ↓                      ↓
+    系统自动判断如何重生成      直接应用用户修改
+    （删json/重新匹配/处理重叠）  （跳过LLM校正）
+              ↓                      ↓
+              └──────┬─────────────┘
+                     ↓
+                  自动重烧
+                     ↓
+               用户用播放器查看
+```
+
+## 知识点编辑
+
+### 用户操作
+
+- **改标题**：直接编辑文字
+- **删 clip**：删除该 clip
+- **新增知识点**：输入新标题（PPT 里没有的也行）
+
+### 系统行为
+
+| 操作 | 底层动作 |
+|------|---------|
+| 改 clip N 标题 | 删 `clipN.json` → 用新标题在 transcript 里重新匹配 start/end → 处理重叠 → 重烧 |
+| 删 clip N | 从 generated_config.yaml 删掉该 clip → 删 `clipN.json` + `clipN.mp4` → 重烧 |
+| 新增知识点 | 用新标题在 transcript 里匹配 start/end → 判断是否合并到相邻 clip（重叠处理）→ 重烧 |
+
+### 重叠处理
+
+新增/修改后如果与现有 clip 重叠，系统自动：
+1. 合并重叠片段
+2. 生成 title_segments（按 transcript 关键词首次出现时间切分）
+3. 每个标题最多显示 title_duration 秒
+
+## 字幕编辑
+
+### 用户操作
+
+直接编辑字幕文件中的文本（v1_content.srt）。
+
+### 系统行为
+
+- **改字幕文本**：以用户修改为准，跳过 LLM 校正，直接重烧
+- **删字幕条目**：用户删除某条，系统保留，其他正常重烧
+- **改时间轴**：不支持（时间轴由底层逻辑决定）
+
+## 底层原子化支撑
+
+底层需要提供以下能力，供 GUI 调用：
+
+```
+reextract_clip_title(clip_index, new_title)
+  → 删 clipN.json → 重新匹配 → 更新 generated_config.yaml
+
+delete_clip(clip_index)
+  → 从 config 删 → 删 json/mp4
+
+add_clip_by_title(new_title)
+  → 在 transcript 里匹配 → 判断合并/新增 → 更新 config
+
+reburn_titles()
+  → 只重烧标题轨（已有 json）
+
+reburn_subtitles(user_texts)
+  → 直接用用户文本烧录字幕，跳过 LLM 校正
+```
+
+CLI 的 `burn_only.py` 已经部分支撑"直接重烧"的能力，需要增强以支持按原子操作重烧。
+
+## 数据流
+
+```
+generated_config.yaml  ← 唯一的 clips 配置源（用户编辑后同步更新）
+intermediates/clip*.json  ← 转录缓存（按需删除重生成）
+subs/v1_title.srt     ← 标题轨（可手动编辑后重烧）
+subs/v1_content.srt   ← 字幕轨（用户直接改文本）
+```
+
+## 架构原则
+
+1. **CLI/GUI 底层复用**：所有原子操作在 core/ 里，CLI 和 GUI 都调用同一套
+2. **config 是唯一真源**：`generated_config.yaml` 是 clips 事实，GUI 编辑后写回此文件
+3. **按需重生成**：只删除/重生成受影响的 clip，不动其他
+4. **字幕以用户为准**：字幕文本修改跳过 LLM 校正
+
+## 实施步骤
+
+1. 底层原子化：core/ 增加 `reextract_clip`, `delete_clip`, `add_clip_by_title` 函数
+2. CLI burn_only 支持部分重烧（支持只烧标题或只烧字幕）
+3. GUI 增加编辑界面：clip 列表 + 字幕列表
+4. 集成测试