# Piano Highlight Generator App - 技术设计

> 设计日期：2026-05-02
> 版本：1.0
> 状态：Draft

---

## 1. 技术栈

| 层级 | 技术 | 选型理由 |
|------|------|----------|
| GUI 框架 | PySide6 (Qt for Python) | LGPL 许可，功能完备，信号槽机制适合异步更新 |
| 打包工具 | Nuitka | 编译为 C，性能好，体积小 |
| 状态持久化 | JSON 文件 | 简单，无需数据库依赖 |
| 核心模块 | 复用现有脚本 | video.py, subtitle.py, llm.py, corrections.py |
| 配置格式 | YAML/JSON | 用户友好，可读性好 |

---

## 2. 项目结构

```
piano-highlight-app/
├── src/
│   ├── __init__.py
│   ├── main.py                 # 应用入口
│   ├── app.py                  # QMainWindow 主窗口
│   ├── gui/                    # GUI 组件
│   │   ├── __init__.py
│   │   ├── config_panel.py     # 配置面板
│   │   ├── progress_view.py    # 进度监控
│   │   ├── title_editor.py     # 标题编辑器
│   │   └── log_view.py         # 日志窗口
│   ├── logic/                  # 业务逻辑
│   │   ├── __init__.py
│   │   ├── config_manager.py   # 配置管理
│   │   ├── pipeline_controller.py  # 流水线控制
│   │   ├── state_manager.py    # 状态管理
│   │   └── worker.py           # 后台工作线程
│   └── core/                   # 核心模块（复用）
│       ├── __init__.py
│       ├── constants.py         # 常量
│       ├── utils.py            # 工具函数
│       ├── video.py            # 视频处理
│       ├── subtitle.py          # 字幕处理
│       ├── llm.py              # LLM 调用
│       └── corrections.py       # 纠错规则
├── assets/                     # 资源文件
│   └── icons/
├── requirements.txt             # 依赖
├── pyproject.toml              # 项目配置
├── nuitka_options.py           # Nuitka 打包配置
└── README.md
```

---

## 3. 核心类设计

### 3.1 StateManager（状态管理）

```python
class StateManager:
    """状态管理器 - 负责状态持久化"""

    def __init__(self, state_file: str):
        self.state_file = state_file
        self.state = self._load()

    def _load(self) -> dict:
        """从文件加载状态"""

    def save(self):
        """保存状态到文件"""

    def get_current_step(self) -> int:
        """获取当前步骤"""

    def set_step_status(self, step: str, status: str):
        """设置步骤状态 (pending/in_progress/completed/failed)"""

    def update_clip_status(self, clip_index: int, **kwargs):
        """更新 clip 状态"""

    def get_clip_titles(self) -> list:
        """获取所有 clip 的标题（含用户修改）"""
```

### 3.2 PipelineController（流水线控制）

```python
class PipelineController:
    """流水线控制器 - 管理处理流程"""

    # 步骤定义
    STEPS = [
        'ready',
        'extracting',
        'transcribing',
        'title_correcting',
        'generating_subtitles',
        'merging',
        'burning',
        'completed'
    ]

    def __init__(self, config: dict, state_manager: StateManager):
        self.config = config
        self.state = state_manager
        self.is_paused = False
        self.is_stopped = False

    def run(self, worker: Worker):
        """运行流水线"""

    def pause(self):
        """暂停流水线"""

    def resume(self):
        """恢复流水线"""

    def stop(self):
        """停止流水线"""

    def step_extracting(self):
        """Step 1: 提取片段"""

    def step_transcribing(self):
        """Step 2: 转录"""

    def step_title_correcting(self) -> list:
        """Step 3: 标题纠正 - 返回需要用户确认的标题"""
        # 返回标题列表，用户可以在此介入修改

    def step_generating_subtitles(self):
        """Step 4: 生成字幕"""

    def step_merging(self):
        """Step 5: 合并视频"""

    def step_burning(self):
        """Step 6: 烧录字幕"""
```

### 3.3 Worker（后台工作线程）

```python
class Worker(QThread):
    """后台工作线程 - 在独立线程中执行流水线"""

    progress_signal = pyqtSignal(str, int, str)  # step, percent, message
    clip_completed_signal = pyqtSignal(int)     # clip_index
    step_completed_signal = pyqtSignal(str)     # step_name
    titles_ready_signal = pyqtSignal(list)      # 标题列表，等待用户确认
    finished_signal = pyqtSignal(bool, str)    # success, message
    log_signal = pyqtSignal(str)               # 日志消息

    def __init__(self, controller: PipelineController):
        super().__init__()
        self.controller = controller

    def run(self):
        """执行流水线（可暂停）"""

    def request_pause(self):
        """请求暂停（由 UI 调用）"""
```

### 3.4 ConfigPanel（配置面板）

```python
class ConfigPanel(QWidget):
    """配置面板"""

    config_changed_signal = pyqtSignal(dict)

    def __init__(self):
        super().__init__()
        self._init_ui()

    def _init_ui(self):
        """初始化 UI"""
        # API 配置组
        # - API Host (QLineEdit)
        # - API Key (QLineEdit, 密码模式)
        # - 模型选择 (QComboBox)

        # 视频配置组
        # - 视频文件选择 (QLineEdit + QPushButton)
        # - 输出目录选择 (QLineEdit + QPushButton)

        # Whisper 配置组
        # - 模型选择 (QComboBox: base/small/medium/large)
        # - 模型路径 (QLineEdit)

    def load_config(self, config: dict):
        """加载配置到 UI"""

    def get_config(self) -> dict:
        """从 UI 获取配置"""

    def validate(self) -> tuple:
        """验证配置有效性"""
        # 返回 (is_valid, error_message)
```

### 3.5 ProgressView（进度视图）

```python
class ProgressView(QWidget):
    """进度监控视图"""

    def __init__(self):
        super().__init__()
        self._init_ui()

    def _init_ui(self):
        """初始化 UI"""
        # 当前步骤标签 (QLabel)
        # 整体进度条 (QProgressBar)
        # Clip 进度 (QLabel: "Clip 3/14")
        # 日志文本框 (QTextEdit, 只读)
        # 控制按钮 (开始/暂停/停止/继续)

    def update_progress(self, step: str, percent: int, message: str):
        """更新进度显示"""

    def append_log(self, message: str):
        """追加日志"""

    def set_clip_progress(self, current: int, total: int):
        """设置 Clip 进度"""

    def enable_controls(self, can_start: bool, can_pause: bool, can_stop: bool, can_resume: bool):
        """设置控制按钮状态"""
```

### 3.6 ContentEditor（内容编辑器 - 人工介入点）

```python
class ContentEditor(QWidget):
    """内容编辑器 - 用于人工介入修改标题和字幕内容"""

    content_confirmed_signal = pyqtSignal(dict)  # 用户确认的内容 {clip_index: {title, subtitles}}

    def __init__(self):
        super().__init__()
        self._init_ui()

    def _init_ui(self):
        """初始化 UI"""
        # 标签页：标题编辑 / 字幕编辑
        # 标题编辑：
        #   - Clip # | 原始标题 | LLM建议 | 用户修改 | 操作
        #   - 编辑按钮 (QPushButton)
        # 字幕编辑：
        #   - 按Clip分页，每个Clip显示其字幕内容
        #   - 每个字幕段可编辑（原始文本 → 纠正后文本 → 用户修改）
        # 确认按钮 (QPushButton)

    def set_content(self, clips_data: dict):
        """设置内容供用户编辑
        clips_data: {
            clip_index: {
                'title': {...},
                'subtitles': [...]
            }
        }
        """

    def get_user_content(self) -> dict:
        """获取用户修改后的内容"""

    def edit_clip_title(self, clip_index: int):
        """编辑单个Clip的标题 - 弹出对话框"""

    def edit_clip_subtitle(self, clip_index: int, subtitle_index: int):
        """编辑单个字幕段 - 弹出对话框"""
```

### 3.7 SubtitleSegmentEditor（字幕段编辑器）

```python
class SubtitleSegmentEditor(QWidget):
    """单个字幕片段的编辑器"""

    def __init__(self, segment_data: dict, parent=None):
        super().__init__(parent)
        # 显示：时间范围、原始文本、规则纠正后、LLM纠正后、用户可编辑

    def get_corrected_text(self) -> str:
        """获取用户修改后的文本"""
```

---

## 4. 流水线状态机

```
                    ┌─────────┐
         ┌─────────►│  Ready  │◄────────┐
         │          └────┬────┘          │
         │               │ start()        │ reset()
         │               ▼                │
         │          ┌─────────┐            │
         │   ┌─────│Extracting│─────┐     │
         │   │     └────┬────┘     │     │
         │   │ pause    │ completed │     │
         │   │          ▼          │     │
         │   │   ┌───────────┐     │     │
         │   └──►│Transcribing│◄────┘     │
         │        └─────┬─────┘           │
         │        pause │ │ completed      │
         │              ▼                 │
         │     ┌─────────────────┐        │
         │     │Title Correcting │◄──┐   │ 人工介入点
         │     └────────┬────────┘   │   │ 用户可暂停
         │              │ completed  │   │ 修改标题
         │              ▼            │   │
         │   ┌──────────────────┐   │   │
         │   │Generating Subtitles│───┘   │
         │   └─────────┬────────┘        │
         │        pause │ │ completed     │
         │             ▼                 │
         │     ┌──────────────┐           │
         │     │   Merging    │◄──┘      │
         │     └──────┬───────┘           │
         │       pause│ │ completed       │
         │           ▼                    │
         │    ┌───────────┐               │
         │    │  Burning  │◄─────────────┘
         │    └─────┬─────┘
         │     pause│ │ completed
         │          ▼
         │    ┌───────────┐
         └────│ Completed │
              └───────────┘
```

---

## 5. 信号流设计

```
┌─────────────────────────────────────────────────────────────────┐
│                         UI Layer                                 │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ ConfigPanel  │  │ ProgressView │  │ TitleEditor  │          │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘          │
│         │                  │                  │                  │
│         │  config_changed  │  titles_ready   │ titles_confirmed │
└─────────┼──────────────────┼──────────────────┼──────────────────┘
          │                  │                  │
          ▼                  ▼                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Controller Layer                               │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              PipelineController                            │   │
│  │  - manage_workflow()                                      │   │
│  │  - handle_pause() / handle_resume()                       │   │
│  │  - collect_user_titles()                                  │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Worker Thread                                │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ Worker (QThread)                                          │   │
│  │  - runs pipeline steps                                     │   │
│  │  - emits progress/titles signals                          │   │
│  │  - respects pause/stop flags                               │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
```

### 信号定义

| 信号 | 方向 | 参数 | 说明 |
|------|------|------|------|
| `config_changed` | UI → Controller | dict | 配置变更 |
| `start_pipeline` | Controller → Worker | dict, StateManager | 启动流水线 |
| `progress_signal` | Worker → UI | step, percent, message | 进度更新 |
| `titles_ready_signal` | Worker → UI | list | 标题列表准备好，等待确认 |
| `titles_confirmed_signal` | UI → Controller | list | 用户确认的标题 |
| `pause_pipeline` | UI → Worker | - | 请求暂停 |
| `resume_pipeline` | UI → Worker | - | 请求恢复 |
| `stop_pipeline` | UI → Worker | - | 请求停止 |

---

## 6. 状态文件格式

```json
{
  "version": 1,
  "app_version": "1.0.0",
  "project_name": "福田夜校-03月18日",
  "created_at": "2026-05-02T10:00:00",
  "updated_at": "2026-05-02T10:30:00",

  "config": {
    "video_src": "D:/path/to/video.mp4",
    "output_dir": "D:/path/to/output",
    "api_key": "xxx",
    "api_host": "https://ark.cn-beijing.volces.com/api/coding/v3",
    "whisper_model": "large",
    "whisper_model_path": "D:/AI/LM-Models/faster-whisper/large-v3",
    "video_params": {
      "fade_duration": 1,
      "title_fontsize": 90,
      "title_color": "FFFF00",
      "subtitle_fontsize": 24,
      "subtitle_color": "FFFFFF"
    }
  },

  "pipeline": {
    "current_step": 3,
    "steps": {
      "extracting": {"status": "completed", "started_at": "...", "completed_at": "..."},
      "transcribing": {"status": "completed", "started_at": "...", "completed_at": "..."},
      "title_correcting": {"status": "in_progress", "started_at": "...", "completed_at": null},
      "generating_subtitles": {"status": "pending", "started_at": null, "completed_at": null},
      "merging": {"status": "pending", "started_at": null, "completed_at": null},
      "burning": {"status": "pending", "started_at": null, "completed_at": null}
    }
  },

  "clips": [
    {
      "index": 1,
      "title_original": "弹奏",
      "title_llm": "弹奏",
      "title_user": null,
      "title_final": "弹奏",
      "start": 412,
      "end": 442,
      "status": "completed",
      "clip_path": "intermediates/clip1_fade.mp4",
      "json_path": "intermediates/clip1.json",
      "transcription_completed_at": "..."
    }
  ],

  "outputs": {
    "subtitle_title_path": "subs/v1_title.srt",
    "subtitle_content_path": "subs/v1_content.srt",
    "merged_video_path": "concat_merged.mp4",
    "final_video_path": "v1_final.mp4"
  }
}
```

---

## 7. 错误处理策略

| 错误类型 | 处理方式 |
|----------|----------|
| 配置无效 | 阻止开始，提示用户修正 |
| API 调用失败 | 重试 3 次，仍失败则暂停流水线，等待用户处理 |
| 视频文件不存在 | 暂停，提示用户选择其他文件 |
| 磁盘空间不足 | 暂停，提示用户清理空间 |
| 处理异常崩溃 | 状态已持久化，重启后可恢复 |
| 用户取消 | 保存当前进度，清理临时文件（可选） |

---

## 8. 打包配置 (Nuitka)

```python
# nuitka_options.py
import nuitka

nuitka.compile(
    script="src/main.py",
    mode="standalone",
    output_dir="dist",
    windows_icon="assets/icon.ico",
    include_qt_plugins=["qt_plugins/styles", "qt_plugins/imageformats"],
    data_files=[
        ("assets/icons", "assets/icons"),
    ],
    remove_output_dir=True,
    onefile=True,  # 打包成单个 exe
    company_name="Piano Tools",
    product_name="Piano Highlight Generator",
    product_version="1.0.0",
)
```

---

## 9. 依赖清单

```
PySide6>=6.6.0
pyyaml>=6.0
requests>=2.31.0
pypinyin>=0.50.0
faster-whisper>=1.0.0  # 可选，如需本地转录
```

---

## 10. 开发优先级

| 优先级 | 模块 | 工期估计 |
|--------|------|----------|
| P0 | 项目骨架 + ConfigPanel + StateManager | 2h |
| P0 | ProgressView + Worker 集成 | 2h |
| P0 | PipelineController 核心逻辑 | 2h |
| P1 | TitleEditor 标题编辑器 | 1.5h |
| P2 | 完善错误处理和边界情况 | 1h |
| P2 | 打包配置 + 测试 | 1.5h |
| P3 | README 和用户文档 | 0.5h |

**总工期估计：约 10 小时**