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)
Phase 2: 音频与推理核心 (Week 3-4)
Phase 3: STT 测试页面 (Week 5-6)
Phase 4: 文件转写页面 (Week 7)
Phase 5: 优化与测试 (Week 8)
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，字节对编码分词方法 |
impressionyang
02e100b318