hmo/lesson-highlights

Fork 0

Files

T

hmo 9e62247a60 Initial commit: lesson-highlights generator

2026-05-03 03:07:22 +08:00

10 KiB

Raw Permalink Blame History

Piano Highlight Generator App - 需求提案

提案日期：2026-05-02 提案人：AI Dev Team 状态：Draft

1. 问题描述

1.1 现状

当前钢琴课精华视频生成器是 Python CLI 脚本集合：

generate_highlights.py - 命令行程序，一次性执行完整流程
无图形界面，需要手动编辑 YAML 配置文件
无状态保持，程序中断只能从头开始
无人工介入点，无法在处理过程中修改标题

1.2 用户需求

用户希望将其重构为可分发的桌面应用，具备：

需求	说明
配置界面	图形化配置 API 大模型参数，无需编辑 YAML
全过程监控	实时显示每个处理步骤的状态
状态保持	可在任意步骤暂停，然后继续往下进行
人工介入	暂停时可手动修改标题，然后再最后烧制

2. 用户故事

2.1 作为用户，我想要...

Story 1: 配置管理

打开应用后，能看到清晰的配置界面
可以选择/切换不同的 LLM API（当前是火山方舟，可扩展）
可以选择 Whisper 模型（用于音频转录）
配置可以保存和加载

Story 2: 全过程监控

启动处理后，能看到每个步骤的实时状态
看到当前正在处理哪个片段（Clip 3/14）
看到预估剩余时间
能看到每个步骤的日志输出

Story 3: 暂停与恢复

点击"暂停"按钮，处理立即停止
关闭应用后，下次打开能从暂停点继续
恢复后从最近的检查点继续，不丢失进度

Story 4: 人工介入

在标题纠正步骤，可以预览每个片段的标题
可以手动修改标题
可以跳过某些片段
所有修改会被保存

Story 5: 打包分发

生成一个 .exe 文件，双击即可运行
无需安装 Python 环境
可以在其他电脑上使用

3. 验收标准

3.1 配置界面

应用启动后显示配置面板
可以输入/编辑 API Key 和 API Host
可以选择 Whisper 模型（base/small/medium/large）
可以选择输入视频文件（文件选择对话框）
可以选择输出目录
配置可以保存到文件（JSON/YAML）
配置可以从文件加载

3.2 全过程监控

显示当前步骤：准备 → 提取片段 → 转录 → 标题纠正 → 合并 → 烧录
每一步显示进度条（百分比）
显示当前片段序号（如 "Clip 3/14"）
实时显示处理日志
处理完成后显示最终视频路径

3.3 暂停与恢复

有"暂停"按钮，点击后处理停止
暂停时状态持久化到文件
重新打开应用后，自动检测到未完成的任务
可以选择"继续"从暂停点恢复
也可以选择"重新开始"

3.4 人工介入

在标题纠正步骤，显示所有片段的标题列表
每个标题可以点击编辑
编辑后自动保存
可以预览修改后的字幕效果
确认后继续后续步骤

3.5 打包分发

生成 Windows 可执行文件（.exe）
双击运行，无须安装 Python
界面美观，与现代桌面应用一致

4. 技术选型

4.1 GUI 框架

选择：PySide6 (Qt for Python)

因素	结论
许可证	LGPL - 可闭源商用，无需购买
功能	成熟完备，适合复杂桌面应用
状态管理	传统保留模式，天然支持暂停/恢复
多线程	信号槽机制完善，支持多线程安全更新 UI
社区	文档丰富，社区活跃
打包	Nuitka 打包体积小（~10MB），启动快

4.2 打包方案

开发阶段：PyInstaller（调试方便） 正式发布：Nuitka（体积小，性能好）

4.3 状态持久化

使用 JSON 文件存储处理进度
每个项目独立的状态文件
包含：当前步骤、已完成片段、用户修改的标题等

5. 架构设计（预览）

┌─────────────────────────────────────────────────────────────┐
│                      GUI Layer (PySide6)                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │
│  │ ConfigPanel │  │ ProgressView│  │ TitleEditor     │   │
│  └─────────────┘  └─────────────┘  └─────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Business Logic Layer                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │
│  │ ConfigManager│ │PipelineCtrl │  │ StateManager    │   │
│  └─────────────┘  └─────────────┘  └─────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Core Modules (Legacy)                      │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐     │
│  │ video.py│  │subtitle │  │  llm.py │  │correction│     │
│  │         │  │  .py    │  │         │  │s.py     │     │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘     │
└─────────────────────────────────────────────────────────────┘

模块职责

模块	职责
ConfigPanel	配置界面（API、视频路径、模型选择）
ProgressView	进度监控（步骤、百分比、日志）
TitleEditor	标题编辑器（预览、编辑用户修改）
ConfigManager	配置加载/保存
PipelineController	流水线控制（启动/暂停/恢复/停止）
StateManager	状态持久化（保存/恢复进度）

6. 流水线步骤

与应用UI对应的处理步骤：

Step 0: 准备 (Ready)
    └─ 检查配置、初始化环境

Step 1: 提取片段 (Extracting)
    └─ 从视频提取 clips -> intermediates/clip{N}_fade.mp4

Step 2: 转录 (Transcribing)
    └─ Whisper 转录 -> intermediates/clip{N}.json

Step 3: 标题纠正 (Title Correcting)
    └─ LLM 分析 + 用户修改 -> intermediates/corrected_titles.json
    [人工介入点] 用户可在此步骤暂停并修改标题

Step 4: 生成字幕 (Generating Subtitles)
    └─ 生成双轨字幕 -> subs/v{N}_title.srt, v{N}_content.srt

Step 5: 合并视频 (Merging)
    └─ FFmpeg concat -> concat_merged.mp4

Step 6: 烧录字幕 (Burning)
    └─ FFmpeg burn -> v{N}_final.mp4

Step 7: 完成 (Completed)
    └─ 显示结果，清理临时文件（可选）

暂停点

用户可以在以下步骤暂停：

Step 1 完成后（片段已提取）
Step 2 完成后（转录已完成）
Step 3 完成后（标题已确认）- 推荐暂停点
Step 4 完成后（字幕已生成）
Step 5 完成后（视频已合并）

7. 状态数据结构

{
  "version": 1,
  "project_name": "福田夜校-03月18日",
  "config": {
    "video_src": "D:/path/to/video.mp4",
    "output_dir": "D:/path/to/output",
    "api_key": "xxx",
    "api_host": "https://...",
    "whisper_model": "large"
  },
  "current_step": 3,
  "clips": [
    {
      "index": 1,
      "title_original": "弹奏",
      "title_corrected": "弹奏",
      "title_user_modified": null,
      "start": 412,
      "end": 442,
      "status": "completed",
      "clip_path": "intermediates/clip1_fade.mp4",
      "json_path": "intermediates/clip1.json"
    }
  ],
  "step_status": {
    "extracting": "completed",
    "transcribing": "completed",
    "title_correcting": "in_progress",
    "generating_subtitles": "pending",
    "merging": "pending",
    "burning": "pending"
  },
  "created_at": "2026-05-02T10:00:00",
  "updated_at": "2026-05-02T10:30:00"
}

8. 边界情况

情况	处理方式
API Key 无效	显示错误提示，不开始处理
视频文件不存在	配置检查时发现，提示用户
处理到一半崩溃	状态已持久化，重启后可恢复
用户取消处理	保存当前进度，可选择重新开始或继续
Whisper 模型未下载	显示下载链接，或使用默认模型
输出目录磁盘空间不足	处理前检查，提示用户

9. 非功能性需求

需求	标准
启动时间	< 3 秒（使用 Nuitka 打包后）
UI 响应性	所有操作在 100ms 内响应
内存占用	< 500MB（不含视频处理）
打包后体积	< 50MB
兼容性	Windows 10/11 64-bit

10. 后续步骤

Phase 2: 技术设计 - 详细架构设计、数据库选型、接口定义
Phase 3: 任务编排 - 拆分并行任务、创建 git worktree
Phase 4: 并行开发 - 各模块实现
Phase 5: 质量交付 - 审查、测试、打包

10 KiB Raw Permalink Blame History Unescape Escape