impressionyang
02e100b318
基于 ONNX 的实时语音转文本输入法，C++ 跨平台实现。 核心组件： - Qt 6 跨平台 GUI（实时识别 / 文件转写 / 配置页面） - ONNX Runtime 推理引擎（异步模型加载） - PortAudio 音频采集 - dr_libs 音频文件解码 - JSON 配置管理（线程安全，自动持久化） - 日志系统（控制台 + 文件输出） Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
265 lines
11 KiB
Markdown
265 lines
11 KiB
Markdown
# 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，字节对编码分词方法 |
|