impressionyang/impress_voice_input
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

docs: 完善 README 使用说明

Browse Source 
- 添加下载安装、快速开始、使用说明、快捷键、CapsLock 工作模式
- 补充语音输入和文件转写详细流程
- 添加系统托盘、状态栏说明和常见问题
- 更新 License 为 GPLv3
- 完善项目结构、技术栈、编译指南和命令行参数

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
impressionyang 2026-06-12 10:49:21 +08:00
parent ab3064eb4e
commit 231543476b
1 changed files with 135 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

184
README.md
View File

@ -4,24 +4,99 @@
## 功能特性
- **实时语音识别** — 麦克风采集，流式输出识别结果
- **音频文件转写** — 支持 WAV/MP3/FLAC，批量处理，导出 TXT/SRT
- **跨平台 GUI** — Qt 6 构建，支持 Windows / macOS / Linux
- **本地推理** — ONNX Runtime，支持 CPU/GPU 加速
- **实时语音识别** — 长按快捷键开始录音，松开自动识别并注入文字
- **音频文件转写** — 支持 WAV/MP3/FLAC/OGG，批量处理，导出 TXT/SRT
- **跨平台 GUI** — Qt 6 构建，支持 Windows / Linux
- **本地推理** — SenseVoice ONNX 模型，支持 CPU/GPU 加速
- **可配置** — 模型路径、推理参数、快捷键均可自定义
- **系统托盘** — 最小化后台运行，双击快速唤出
## 快速开始
### 下载安装
| 平台 | 文件 | 大小 |
|------|------|------|
| Windows | `impress_voice_input_windows.zip` | ~47MB |
| Linux | `impress_voice_input_linux.tar.gz` | ~34MB |
- **Windows**：解压后进入 `dist_win/` 目录，双击 `impress_voice_input.exe`
- **Linux**：解压后运行 `./run.sh`
### 首次使用
1. 获取 SenseVoice ONNX 模型（`.onnx` 格式）
2. 打开应用 → 切换到 **配置** 标签页
3. 设置 **模型路径** 指向 `.onnx` 文件
4. 设置 **词表路径** 指向 `tokens.txt` 文件
5. 点击 **保存配置**
6. 设置语音快捷键（默认长按 CapsLock）
7. 状态栏右侧显示 <span style="color:#27ae60">**模型已就绪**</span> 即可开始使用
## 使用说明
### 快捷键
| 功能 | 快捷键 |
|------|--------|
| 语音输入 | 长按 CapsLock 超过 1 秒（可自定义） |
| 使用说明 | F1 |
| 重启应用 | Ctrl+R |
| 退出应用 | Ctrl+Q |
### CapsLock 工作模式
- **短按（< 1 秒）**：正常切换大小写锁定
- **长按（> 1 秒）**：触发语音输入模式，开始录音
- **松开快捷键**：停止录音 → 自动识别 → 文字注入目标应用
### 语音输入流程
1. 在 **配置** 页面中设置正确的 STT 模型路径并保存
2. 设置语音输入快捷键（默认长按 CapsLock）
3. 将光标定位到需要输入文字的目标应用（如微信、Word、浏览器等）
4. 长按快捷键开始说话，说完后松开
5. 识别的文字将自动输入到目标应用中
### 文件转写流程
1. 切换到 **音频文件转写** 标签页
2. 点击 **选择文件** 选择音频文件，支持拖放
3. 点击 **开始转写**，等待处理完成
4. 点击 **复制结果** 复制到剪贴板，或 **导出结果** 保存为文件
### 系统托盘
关闭主窗口时程序最小化到系统托盘，托盘图标菜单支持：
- **显示主窗口**：恢复主窗口显示
- **重启**：重启应用程序
- **退出**：完全退出程序
- 双击托盘图标可快速显示主窗口
### 状态栏
底部状态栏右侧显示 STT 模型加载状态：
- <span style="color:#27ae60">**模型已就绪**</span> — 模型加载成功，可以正常使用
- <span style="color:#e74c3c">**模型路径未设置**</span> — 请在配置页面设置模型路径
- <span style="color:#e67e22">**模型加载失败**</span> — 模型文件路径错误或文件损坏
## 项目结构
```
impress_voice_input/
├── CMakeLists.txt # 构建配置
├── PRD.md # 产品需求文档
├── LICENSE # GNU GPLv3 授权文件
├── README.md # 项目说明
├── build-linux.sh # Linux 构建脚本
├── build-win.sh # Windows 交叉编译 + 打包脚本
├── cmake/ # CMake 模块
│ └── dependencies.cmake # 依赖查找
├── src/
│ ├── main.cpp # 入口
│ ├── app/ # 应用层 (Application, ConfigManager)
│ ├── core/ # 核心 (STTEngine, AudioProcessor, Decoder, Tokenizer)
│ ├── core/ # 核心 (SenseVoiceEngine, AudioProcessor, VoiceInputService)
│ ├── audio/ # 音频 (AudioCapture, AudioDecoder, RingBuffer)
│ ├── ui/ # GUI 页面与控件
│ │ ├── main_window.cpp # 主窗口
@ -39,8 +114,9 @@ impress_voice_input/
| 组件 | 选型 |
|------|------|
| GUI | Qt 6 |
| GUI | Qt 6 (Fusion / Windows 原生风格) |
| 推理引擎 | ONNX Runtime (C++ API) |
| 语音模型 | SenseVoice Small |
| 音频采集 | PortAudio |
| 音频解码 | dr_libs (dr_wav, dr_mp3, dr_flac) |
| 构建系统 | CMake 3.20+ |
@ -61,21 +137,33 @@ impress_voice_input/
```bash
# 放入 third_party/ 目录
third_party/
├── onnxruntime/
│ ├── include/
│ └── lib/
├── onnxruntime/ (Linux)
├── onnxruntime-win-x64/ (Windows 交叉编译)
├── portaudio/
│ ├── include/
│ └── lib/
├── dr_libs/
│ ├── dr_wav.h
│ ├── dr_mp3.h
│ └── dr_flac.h
└── nlohmann_json/
└── json.hpp
└── dr_libs/
├── dr_wav.h
├── dr_mp3.h
└── dr_flac.h
```
### 编译
### Linux 编译
```bash
./build-linux.sh --release
# 可执行文件: build_linux/impress_voice_input
```
### Windows 交叉编译
```bash
./build-win.sh --release
# 输出: build_win/dist_win/ (可直接运行的目录)
# dist/impress_voice_input_windows.zip (发布压缩包)
```
### 手动编译
```bash
mkdir build && cd build
@ -83,15 +171,7 @@ cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . -j$(nproc)
```
### 带测试编译
```bash
cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
cmake --build . -j$(nproc)
ctest
```
## 运行
### 命令行参数
```bash
# 默认启动
@ -102,39 +182,45 @@ ctest
# 指定模型
./impress_voice_input --model /path/to/model.onnx
# 指定日志目录
./impress_voice_input --log-dir /path/to/logs
```
## 模型准备
## 常见问题
支持以下 ONNX 格式模型：
- **Whisper** (small/medium) — 多语言，高质量
- **Paraformer** — 中文优化
- 其他兼容 CTC 的 ASR 模型
**Q: 语音输入没有反应？**
A: 请确认：① 模型已加载（状态栏显示"模型已就绪"）；② 已设置语音快捷键；③ 麦克风正常工作。
将 `.onnx` 模型文件放入 `models/` 目录，然后在配置页面设置路径。
**Q: 识别文字没有输入到目标应用？**
A: 某些应用可能拦截模拟按键输入，请尝试在管理员权限下运行本程序。
**Q: 识别速度慢？**
A: 在配置中增大 ONNX 线程数，或使用 GPU 版本的 ONNX Runtime。
**Q: CapsLock 短按不起作用？**
A: 请确保按键时间小于 1 秒，超过 1 秒会触发语音输入模式。
## 当前状态
项目处于 **核心推理实现阶段**：
- [x] 项目结构与 CMake 配置
- [x] 配置管理模块 (线程安全，自动持久化)
- [x] STT 推理引擎 (ONNX Runtime 集成，异步模型加载)
- [x] Mel 频谱图提取 (Hann 窗 + FFT + Mel 滤波器组)
- [x] Whisper Tokenizer (BPE 分词)
- [x] 音频采集/解码框架 (PortAudio/dr_libs)
- [x] 三个 GUI 页面 (实时识别 / 文件转写 / 配置)
- [x] 日志系统 (控制台 + 文件输出)
- [x] 批量文件转写 (支持 WAV/MP3/FLAC)
- [x] 结果导出 (TXT / SRT 字幕 / JSON 结构化数据)
- [x] 音频重采样 (非 16kHz 音频自动重采样)
- [x] 语音活动检测 (VAD — 短时能量 + 过零率)
- [x] 音频文件信息 (时长/采样率/声道数)
- [x] 单元测试框架 (Catch2, 39 个测试用例)
- [x] 完整 Whisper 推理 (自回归解码 + 流式识别)
- [x] SenseVoice 完整推理 (Fbank → LFR → CMVN → ONNX → CTC 解码)
- [ ] 跨平台打包
- [x] Mel 频谱图提取 (Hann 窗 + FFT + Mel 滤波器组)
- [x] Whisper 推理 (自回归解码 + 流式识别)
- [x] 音频采集/解码 (PortAudio/dr_libs)
- [x] 音频重采样 (非 16kHz 自动处理)
- [x] 语音活动检测 (VAD)
- [x] 三个 GUI 页面 (实时识别 / 文件转写 / 配置)
- [x] 批量文件转写 + 结果导出 (TXT / SRT / JSON)
- [x] 日志系统 (控制台 + 文件)
- [x] Windows 全局快捷键 (CapsLock 长按)
- [x] Linux Wayland/X11 快捷键 + 文本注入
- [x] 系统托盘 + 主题切换 (深色/浅色)
- [x] 跨平台打包
- [ ] 单元测试完善
- [ ] macOS 支持
## License
MIT
GNU General Public License v3.0 — 详见 [LICENSE](LICENSE) 文件。