From 231543476b2f222551a527eeeeb3ff4eec802aa8 Mon Sep 17 00:00:00 2001 From: impressionyang Date: Fri, 12 Jun 2026 10:49:21 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=20README=20=E4=BD=BF?= =?UTF-8?q?=E7=94=A8=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 添加下载安装、快速开始、使用说明、快捷键、CapsLock 工作模式 - 补充语音输入和文件转写详细流程 - 添加系统托盘、状态栏说明和常见问题 - 更新 License 为 GPLv3 - 完善项目结构、技术栈、编译指南和命令行参数 Co-Authored-By: Claude Opus 4.7 --- README.md | 184 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 135 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index c384086..06604b4 100644 --- a/README.md +++ b/README.md @@ -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. 状态栏右侧显示 **模型已就绪** 即可开始使用 + +## 使用说明 + +### 快捷键 + +| 功能 | 快捷键 | +|------|--------| +| 语音输入 | 长按 CapsLock 超过 1 秒（可自定义） | +| 使用说明 | F1 | +| 重启应用 | Ctrl+R | +| 退出应用 | Ctrl+Q | + +### CapsLock 工作模式 + +- **短按（< 1 秒）**：正常切换大小写锁定 +- **长按（> 1 秒）**：触发语音输入模式，开始录音 +- **松开快捷键**：停止录音 → 自动识别 → 文字注入目标应用 + +### 语音输入流程 + +1. 在 **配置** 页面中设置正确的 STT 模型路径并保存 +2. 设置语音输入快捷键（默认长按 CapsLock） +3. 将光标定位到需要输入文字的目标应用（如微信、Word、浏览器等） +4. 长按快捷键开始说话，说完后松开 +5. 识别的文字将自动输入到目标应用中 + +### 文件转写流程 + +1. 切换到 **音频文件转写** 标签页 +2. 点击 **选择文件** 选择音频文件，支持拖放 +3. 点击 **开始转写**，等待处理完成 +4. 点击 **复制结果** 复制到剪贴板，或 **导出结果** 保存为文件 + +### 系统托盘 + +关闭主窗口时程序最小化到系统托盘，托盘图标菜单支持： + +- **显示主窗口**：恢复主窗口显示 +- **重启**：重启应用程序 +- **退出**：完全退出程序 +- 双击托盘图标可快速显示主窗口 + +### 状态栏 + +底部状态栏右侧显示 STT 模型加载状态： + +- **模型已就绪** — 模型加载成功，可以正常使用 +- **模型路径未设置** — 请在配置页面设置模型路径 +- **模型加载失败** — 模型文件路径错误或文件损坏 ## 项目结构 ``` 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) 文件。