# Impress Voice Input — 产品需求文档 (PRD)

## 1. 项目概述

**项目名称**: Impress Voice Input
**项目类型**: 基于 ONNX 的实时语音转文本输入法
**技术栈**: C++ / ONNX Runtime / Qt (跨平台GUI)

### 1.1 项目目标

开发一款跨平台的实时语音输入法，利用 ONNX 推理引擎运行语音转文本 (STT) 模型，提供低延迟、高准确率的语音输入体验。应用集成前后端于一体，包含实时语音识别、音频文件转写和模型配置三大核心功能。

### 1.2 目标平台

- Windows 10/11
- macOS 12+
- Linux (Ubuntu 20.04+)

---

## 2. 技术架构

### 2.1 整体架构

```
┌─────────────────────────────────────────────────┐
│                  Qt GUI 前端                     │
│  ┌──────────┐  ┌──────────────┐  ┌───────────┐  │
│  │ STT测试页 │  │ 音频文件转写页 │  │  配置页面  │  │
│  └────┬─────┘  └──────┬───────┘  └─────┬─────┘  │
│       │               │                │         │
│  ┌────▼───────────────▼────────────────▼─────┐  │
│  │          统一事件总线 / 消息队列            │  │
│  └────────────────────┬──────────────────────┘  │
└───────────────────────┼─────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────┐
│                 C++ 后端服务层                    │
│  ┌────────────┐  ┌──────────────┐  ┌─────────┐  │
│  │ 音频采集模块 │  │ 音频文件解码  │  │ 配置管理 │  │
│  │ (PortAudio) │  │ (dr_libs)    │  │ (INI/JSON)│
│  └─────┬──────┘  └──────┬───────┘  └────┬────┘  │
│        │                │               │        │
│  ┌─────▼────────────────▼───────────────▼──────┐│
│  │          STT 推理引擎 (ONNX Runtime)         ││
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ││
│  │  │ 音频预处理│  │ ONNX推理 │  │ 后处理/CTC│  ││
│  │  └──────────┘  └──────────┘  └──────────┘  ││
│  └─────────────────────────────────────────────┘│
└─────────────────────────────────────────────────┘
```

### 2.2 技术选型

| 组件 | 选型 | 说明 |
|------|------|------|
| **GUI 框架** | Qt 6 | 成熟跨平台，原生性能，丰富的控件生态 |
| **STT 推理引擎** | ONNX Runtime (C++ API) | 跨平台推理，支持 CPU/GPU 加速 |
| **音频采集** | PortAudio | 轻量级跨平台音频 I/O 库 |
| **音频解码** | dr_libs (dr_wav/dr_mp3/dr_flac) | 单头文件，支持 WAV/MP3/FLAC |
| **模型格式** | Whisper / Paraformer ONNX | 主流开源 STT 模型导出格式 |
| **构建系统** | CMake 3.20+ | 跨平台标准构建工具 |
| **配置存储** | nlohmann/json | JSON 格式配置文件 |
| **线程模型** | Qt Concurrent + 独立工作线程 | UI 线程与推理线程分离 |

---

## 3. 功能需求

### 3.1 STT 测试页面（实时语音识别）

**功能描述**: 实时采集麦克风音频流，流式输出识别文本。

| 功能项 | 详细说明 | 优先级 |
|--------|----------|--------|
| 麦克风选择 | 下拉列表选择输入设备，显示采样率等信息 | P0 |
| 开始/停止录音 | 按钮控制录音状态，带明显视觉反馈 | P0 |
| 实时文本显示 | 滚动文本区域实时显示识别结果 | P0 |
| 流式/非流式切换 | 支持流式（逐字输出）和整句输出两种模式 | P0 |
| 置信度显示 | 显示每句识别的置信度分数 | P1 |
| 延迟指示 | 显示端到端识别延迟（毫秒） | P1 |
| 波形可视化 | 实时音频波形图展示 | P2 |
| 文本复制/导出 | 一键复制识别文本或导出为 TXT 文件 | P1 |
| 多语言切换 | 运行时切换识别语言 | P1 |

### 3.2 音频文件转写页面

**功能描述**: 导入音频文件，批量转写为文本。

| 功能项 | 详细说明 | 优先级 |
|--------|----------|--------|
| 文件选择 | 支持拖拽或文件选择器导入音频文件 | P0 |
| 支持的格式 | WAV, MP3, FLAC, OGG, AAC | P0 |
| 批量处理 | 支持添加多个文件到队列，按序处理 | P1 |
| 进度显示 | 文件转写进度条、百分比、预计剩余时间 | P0 |
| 结果展示 | 分段显示转写文本，带时间戳 | P0 |
| 结果导出 | 导出为 TXT / SRT (字幕) / JSON 格式 | P0 |
| 断点续传 | 中断后可从断点继续 | P2 |
| 文件信息 | 显示音频文件的时长、采样率、声道数 | P1 |

### 3.3 配置页面

**功能描述**: 管理模型路径、推理参数和应用设置。

| 功能项 | 详细说明 | 优先级 |
|--------|----------|--------|
| 模型路径配置 | 设置 ONNX 模型文件路径（支持相对/绝对路径） | P0 |
| 模型类型选择 | 选择 Whisper / Paraformer / 其他 | P0 |
| 推理设备选择 | CPU / GPU (CUDA / CoreML / DirectML) | P0 |
| 线程数配置 | 设置 ONNX 推理线程数 | P0 |
| 采样率配置 | 设置输入音频采样率（默认 16000Hz） | P0 |
| 语言设置 | 默认识别语言 | P0 |
| 音频输入设备 | 默认麦克风选择 | P1 |
| 快捷键设置 | 全局语音激活快捷键配置 | P1 |
| 配置文件导入/导出 | 备份和恢复配置 | P1 |
| 参数调优 | 温度、top-p、beam size 等高级参数 | P2 |
| 配置持久化 | 自动保存到配置文件 | P0 |

---

## 4. 非功能需求

### 4.1 性能指标

| 指标 | 目标值 |
|------|--------|
| 实时识别延迟 | < 300ms (端到端，从语音结束到文本输出) |
| 首字延迟 | < 150ms (流式模式) |
| CPU 占用 | < 30% (单核, Intel i5 级别 CPU) |
| 内存占用 | < 500MB (含模型加载) |
| 音频缓冲区延迟 | < 20ms |

### 4.2 兼容性

- ONNX Runtime ≥ 1.16
- Qt ≥ 6.5
- CMake ≥ 3.20
- 支持的模型: Whisper (small/medium), Paraformer, 其他兼容 CTC 的模型

### 4.3 安全与隐私

- 所有推理均在本地执行，不上传任何音频数据到云端
- 配置文件中敏感路径使用相对路径

---

## 5. 项目结构

```
impress_voice_input/
├── PRD.md                          # 产品需求文档
├── CMakeLists.txt                  # 顶层 CMake 配置
├── README.md                       # 项目说明
├── cmake/                          # CMake 模块
│   ├── FindPortAudio.cmake
│   ├── FindOnnxRuntime.cmake
│   └── dependencies.cmake
├── src/
│   ├── main.cpp                    # 入口
│   ├── app/
│   │   ├── application.h/cpp       # QApplication 封装
│   │   └── config_manager.h/cpp    # 配置管理
│   ├── core/
│   │   ├── stt_engine.h/cpp        # STT 推理引擎 (ONNX)
│   │   ├── audio_processor.h/cpp   # 音频预处理 (重采样/归一化)
│   │   ├── decoder.h/cpp           # CTC/自回归解码器
│   │   └── tokenizer.h/cpp         # Tokenizer (BPE/Char)
│   ├── audio/
│   │   ├── audio_capture.h/cpp     # 麦克风采集 (PortAudio)
│   │   ├── audio_decoder.h/cpp     # 文件解码 (dr_libs)
│   │   └── audio_ring_buffer.h/cpp # 环形缓冲区
│   ├── ui/
│   │   ├── main_window.h/cpp       # 主窗口 (Tab/侧边栏导航)
│   │   ├── stt_test_page.h/cpp     # STT 测试页面
│   │   ├── file_transcribe_page.h/cpp  # 文件转写页面
│   │   ├── settings_page.h/cpp     # 配置页面
│   │   ├── widgets/
│   │   │   ├── audio_waveform.h/cpp    # 波形控件
│   │   │   ├── text_output.h/cpp       # 文本输出控件
│   │   │   └── progress_panel.h/cpp    # 进度面板
│   │   ├── resources/
│   │   │   ├── icons/
│   │   │   └── styles/
│   │   │       └── main.qss
│   │   └── main_window.ui          # Qt Designer UI
│   └── utils/
│       ├── logger.h/cpp
│       ├── timer.h/cpp
│       └── string_utils.h/cpp
├── models/                         # 模型存放目录 (gitignore)
│   └── .gitkeep
├── configs/
│   └── default_config.json         # 默认配置
├── tests/
│   ├── test_stt_engine.cpp
│   ├── test_audio_processor.cpp
│   └── test_config_manager.cpp
└── third_party/                    # 第三方依赖
    ├── onnxruntime/
    ├── portaudio/
    ├── dr_libs/
    └── nlohmann_json/
```

---

## 6. 开发里程碑

### Phase 1: 基础框架 (Week 1-2)
- [ ] CMake 项目搭建，依赖集成
- [ ] Qt 主窗口框架，三页面导航
- [ ] 配置管理模块
- [ ] 配置页面 UI 开发

### Phase 2: 音频与推理核心 (Week 3-4)
- [ ] ONNX Runtime 集成，模型加载与推理
- [ ] 音频预处理模块（重采样、归一化、分帧）
- [ ] PortAudio 麦克风采集
- [ ] 音频文件解码模块

### Phase 3: STT 测试页面 (Week 5-6)
- [ ] 实时音频流接入推理引擎
- [ ] 流式识别与文本输出
- [ ] UI 交互完善

### Phase 4: 文件转写页面 (Week 7)
- [ ] 文件选择与批量队列
- [ ] 转写进度管理
- [ ] 结果导出 (TXT/SRT)

### Phase 5: 优化与测试 (Week 8)
- [ ] 性能优化（延迟、内存）
- [ ] 跨平台兼容性测试
- [ ] Bug 修复与 UI 打磨
- [ ] 打包发布

---

## 7. 风险与缓解

| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| ONNX 模型兼容性问题 | 无法加载模型 | 明确支持的模型列表，提供模型转换工具说明 |
| GPU 加速驱动依赖 | 部分用户无法使用 GPU | CPU 推理作为降级方案，确保 CPU 性能可接受 |
| Qt 跨平台差异 | 各平台表现不一致 | 早期进行三平台测试，使用 Qt 抽象层 |
| 大模型内存占用高 | 低端设备运行困难 | 提供 small 模型默认选项，支持模型卸载 |

---

## 8. 附录

### 8.1 参考项目
- whisper.cpp (GGML 实现，参考模型结构)
- faster-whisper (CTranslate2 实现，参考优化策略)
- onnxruntime examples (ONNX 推理示例)

### 8.2 术语表
| 术语 | 说明 |
|------|------|
| STT | Speech-to-Text，语音转文本 |
| ONNX | Open Neural Network Exchange，开放神经网络交换格式 |
| CTC | Connectionist Temporal Classification，连接时序分类 |
| 流式识别 | 边说话边输出文本，而非说完后一次性输出 |
| BPE | Byte Pair Encoding，字节对编码分词方法 |