chore: point independent project metadata to unified root

Ariver

2026-07-13 2d1d4ad406228ef62ab078724cb7d1556e003d01

 README.md

old mode 100755
new mode 100644
@@ -1,165 +1,58 @@
# PrivateVoice

> 长按说话，松手即输 —— 离线 · 极速 · 跨平台
PrivateVoice 是一款离线语音转文字桌面 App：按住快捷键说话，松开后本地识别并输入到当前应用。当前源码位于 `C1.source/privatevoice.src`。

![PrivateVoice](screenshot.png)
![PrivateVoice](K3.运营与发布资料/screenshot.png)

PrivateVoice 是一款离线语音转文字工具。按住快捷键说话，松开即识别并输入文字到任意应用。无需联网，无需注册，开箱即用。
## 当前迁移基线

## 核心特性
- 分支：`codex/x-asr-experiment-2.1.29`
- Commit：`0ffbf1935c9d091cce22a5583275ac0902f7a693`
- Tag：`v2.2.0-build20260702.0303-real-user-test`
- 包类型：真实用户测试候选包，不是 notarized 官网正式发布包。
- 迁移后源码根：`C1.source/privatevoice.src`
- 最新候选包本地路径：`C2.builds/PrivateVoice-Dictation-2.2.0-build20260702.0303/`

- **完全离线** — SenseVoice 模型本地推理，无数据上传
- **DirectML GPU 加速** — 自动检测显卡，CPU 自动回退
- **两种输入模式** — 长按说话 + 短按自由说话
- **自定义快捷键** — 支持 Ctrl / Alt / Shift / 功能键 / 字母键
- **麦克风选择** — 下拉切换输入设备
- **录音音效** — 马林巴风格提示音（可关闭）
- **录音计时** — 指示器实时显示录音时长（0:00 → 0:03 → ...）
- **Escape 取消** — 录音中按 Esc 立即取消
- **剪贴板保护** — 粘贴后自动恢复原剪贴板内容
- **识别历史** — 自动保存最近 50 条，可复制、删除、设置保留时长
- **语气词过滤** — 自动去除"嗯、啊、呃"及 um/uh/hmm 等填充词
- **静音自动停止** — 自由说话模式下连续 3 秒无声自动结束并识别
- **中英混合优化** — 自动在中英文之间加空格，句首大写
- **DPI 自适应** — 指示器根据系统缩放自动调整大小
- **指示器可拖拽** — 拖动浮动指示器到任意位置，自动记忆
- **中英双语界面** — 自动跟随系统语言
- **应用内更新** — 自动检查新版本并提示下载
- **系统托盘常驻** — 关闭窗口不退出
- **开机自启** — 可选
## 核心能力

## 支持的输入语言
- 完全离线识别，模型本地推理。
- 长按说话与短按自由说话两种输入模式。
- 自定义快捷键、麦克风选择、录音音效、录音计时、Esc 取消。
- 剪贴板保护、识别历史、用户词库、语气词过滤和中英混合文本后处理。
- macOS 本地签名 DMG、Windows amd64 preview ZIP。
- 当前 Round 6 已新增独立 `粤语` 语言选项，默认模型为 `SenseVoice Yue 2025-09-09`。

当前 PrivateVoice 的产品语言版本为 **中文**、**English**、**French**、**German**、**Spanish**、**Italian**、**Portuguese**、**Japanese** 和 **Korean**。识别模型已经扩展到 SenseVoice、Moonshine English、Parakeet English、Parakeet TDT v3、日语 Zipformer、韩语 Zipformer、Qwen3-ASR 和 X-ASR zh-en 960ms；不同模型覆盖的输入语言和成熟度不同。
## 语言与模型状态

| 输入语言 / 场景 | 当前支持状态 | 默认 / 可选模型 | 说明 |
|---|---|---|---|
| 中文（普通话、简体 / 繁体） | 正式支持 | 默认：SenseVoice；可选高级：Qwen3-ASR；实验：X-ASR zh-en 960ms | 中文语言版本默认使用 SenseVoice，适合中文听写和日常输入。 |
| English | 正式支持 | 默认：Moonshine English；可选高级：Parakeet English；实验：X-ASR zh-en 960ms | English 语言版本默认使用 Moonshine English，Parakeet 适合更高准确率的英文输入。 |
| French / German / Spanish / Italian / Portuguese | 正式支持 | 默认：Parakeet TDT v3 | 欧洲五语统一使用 NVIDIA / sherpa-onnx 的 Parakeet TDT v3 多语种离线模型。Portuguese 覆盖 `pt-PT` 和 `pt-BR` 的基础识别路径。 |
| 中英混输 | 正式支持场景 | SenseVoice、Qwen3-ASR、X-ASR zh-en 960ms | 适合中文句子中夹杂英文术语、产品名、代码词等场景。 |
| 粤语（Cantonese） | 模型支持，尚非独立语言版本 | SenseVoice、Qwen3-ASR、X-ASR zh-en 960ms | 底层模型包含粤语能力；当前建议在中文语言版本下使用。 |
| 日语（日本語） | 正式支持 | 默认：Zipformer Japanese | 日语语言版本默认使用 ReazonSpeech 日语专项 Zipformer 离线模型。 |
| 韩语（한국어） | 正式支持 | 默认：Zipformer Korean | 韩语语言版本默认使用韩语专项 Zipformer 离线模型。 |
| 欧洲其他语种 | 模型支持，尚非独立语言版本 | Parakeet TDT v3 | Parakeet TDT v3 支持 25 种欧洲语言；当前只把 French、German、Spanish、Italian、Portuguese 作为正式产品语言版本。 |
| 其他语言 | 暂未正式支持 | 无独立默认模型 | 系统语言不在当前正式语言范围内时，当前产品会回落到 English 语言版本。 |
| --- | --- | --- | --- |
| 中文 | 正式支持 | 默认 SenseVoice；可选 Qwen3-ASR；实验 X-ASR zh-en 960ms | 中文听写和中英混输主路径。 |
| 粤语 | 真实用户测试候选 | 默认 SenseVoice Yue 2025-09-09 | 独立语言 profile：`yue-HK`，engine 参数固定 `yue`。 |
| English | 正式支持 | 默认 Moonshine English；可选 Parakeet English；实验 X-ASR zh-en 960ms | 英文听写主路径。 |
| French / German / Spanish / Italian / Portuguese | 正式支持 | Parakeet TDT v3 | 欧洲五语离线识别。 |
| Japanese | 正式支持 | Zipformer Japanese | 日语专项模型。 |
| Korean | 正式支持 | Zipformer Korean | 韩语专项模型。 |
| Windows preview | 技术预览 | SenseVoice only | 非 SenseVoice 模型可见但禁用；Windows 包未签名。 |

| 识别模型 | 模型状态 | 覆盖的输入语言 / 场景 | 所属语言版本 | 说明 |
|---|---|---|---|---|
| SenseVoice | 默认轻量模型 | 中文、粤语、English、日语、韩语 | 中文默认 | 轻量模型，当前推荐用于中文和中英混输，也提供日语、韩语等底层识别能力。 |
| Qwen3-ASR | 高级模型 | 中文、简繁中文、粤语、中英混输 | 中文可选 | 体积更大，适合中文长句、技术词和更高准确率需求。 |
| Moonshine English | 默认轻量模型 | English | English 默认 | 轻量英文离线模型，适合英文日常听写。 |
| Parakeet English | 高级模型 | English | English 可选 | 当前接入的是 `parakeet-unified-en-0.6b` 英文模型，适合长句、技术词和更高准确率需求。 |
| Parakeet TDT v3 | 默认多语种模型 | French、German、Spanish、Italian、Portuguese | 欧洲五语默认 | 一个模型包覆盖欧洲五语，适合离线听写；发布前基准对比 Canary-1B-v2 和 Whisper large-v3-turbo。 |
| Zipformer Japanese | 默认专项模型 | Japanese | 日语默认 | 基于 ReazonSpeech 的日语专项离线模型。 |
| Zipformer Korean | 默认专项模型 | Korean | 韩语默认 | 韩语专项离线模型。 |
| X-ASR zh-en 960ms | 实验模型 | 中文、English、粤语、中英混输 | 中文 / English 可选实验项 | 实验性中英流式模型，用于评估更低延迟和未来“边说边出字”体验。 |

## 快速开始

### 用户

1. 从项目 Releases 页面下载最新版本
2. **Windows**：解压到任意目录，双击 `privatevoice.exe`
3. **macOS**：打开 `.dmg`，拖入 Applications，首次启动需授予辅助功能权限
4. 首次启动自动下载语音模型（~200 MB）
5. 就绪后，在任意输入框中按住 **右 Ctrl**（macOS: **右 Command**）说话，松开即输入

### 开发者
## 开发入口

```bash
# 环境要求
# - Go 1.22+
# - Node.js 20+
# - CGO 编译器 (Windows: LLVM MinGW UCRT, macOS: Xcode Command Line Tools)

# 克隆
git clone <PrivateVoice 仓库地址>
cd PrivateVoice/privatevoice.src

# 安装前端依赖
cd frontend && npm install && cd ..

# 开发模式
wails3 dev

# 生产构建 (Windows)
windres privatevoice.rc -o privatevoice.syso
CGO_ENABLED=1 go build -ldflags "-H windowsgui -s -w" -o privatevoice.exe .

# 生产构建 (macOS)
CGO_ENABLED=1 go build -o privatevoice .
cd /Users/ar/Projects/PrivateVoice/03-O/C1.source/privatevoice.src
npm --prefix frontend run build
go test ./...
```

## 使用方法
常用打包和 QA 命令见 `CODEGRAPH.md`、`K2.项目管理/QA地图.md` 和 `K2.项目管理/发布地图.md`。

1. 系统托盘出现 PrivateVoice 图标，引擎加载完成后就绪
2. **长按模式**：按住快捷键说话，松开即识别并粘贴
3. **自由说话**：短按一下开始，连续说话，再短按一下停止
4. **取消录音**：录音中按 Esc
5. 右键托盘图标可打开设置或退出
## 目录

## 运行文件

**Windows:**

| 文件 | 大小 | 说明 |
|---|---|---|
| `privatevoice.exe` | ~15 MB | 主程序 |
| `onnxruntime.dll` | ~15 MB | ONNX Runtime |
| `sherpa-onnx-c-api.dll` | ~4 MB | sherpa-onnx C API |
| `sherpa-onnx-cxx-api.dll` | ~248 KB | sherpa-onnx C++ API |
| `models/sensevoice/` | ~200 MB | 语音模型（首次自动下载） |

**macOS:**

| 文件 | 大小 | 说明 |
|---|---|---|
| `PrivateVoice Dictation.app` | ~15 MB | 应用包（含 dylib） |
| `models/sensevoice/` | ~200 MB | 语音模型（首次自动下载） |

## 项目结构

```text
03-O/
├── C1.source/privatevoice.src/   源码根
├── C2.builds/                    本地迁移的最新候选包，二进制包不纳入 Git 提交
├── C3.tools/                     工具索引
├── K1.业务知识/                  成果地图和长期业务/技术知识
├── K2.项目管理/                  QA、发布、迁移、handoff、legacy 资料
├── K3.运营与发布资料/            当前运营资料索引和本地素材
└── CODEGRAPH.md                  人工工程地图
```
privatevoice.src/
├── main.go               # 入口：单实例 + Wails 启动
├── app.go                # 编排：热键 → 录音 → 识别 → 粘贴
├── internal/
│   ├── audio/            # malgo 录音 + 设备枚举
│   ├── engine/           # sherpa-onnx 推理
│   ├── hotkey/           # 全局热键轮询
│   ├── input/            # 剪贴板 + 粘贴 + 剪贴板保护
│   ├── config/           # JSON 配置
│   ├── history/          # 识别历史（JSON 持久化）
│   ├── textproc/         # 中英混合文本后处理
│   ├── sound/            # 录音音效（合成 WAV）
│   ├── overlay/          # 浮动指示器（Win32 GDI+ / macOS AppKit）
│   └── ...
├── services/             # Wails 服务（前端绑定）
└── frontend/             # Svelte + Vite
    ├── src/components/   # 设置窗口 + 指示器
    └── src/lib/          # stores + i18n
```

## 技术栈

| 组件 | 技术 |
|---|---|
| 桌面框架 | [Wails v3](https://wails.io/) |
| 前端 | [Svelte 5](https://svelte.dev/) + Vite + TypeScript |
| 音频录制 | [malgo](https://github.com/gen2brain/malgo) (miniaudio) |
| 语音识别 | [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx) (SenseVoice) |
| 全局热键 | Windows: GetAsyncKeyState 轮询 / macOS: NSEvent + CGEventSource |
| 文字输入 | Windows: 剪贴板 + SendInput / macOS: 剪贴板 + CGEvent |
| 浮动指示器 | Windows: GDI+ Layered Window / macOS: AppKit + CoreGraphics |
| 音效 | 程序合成 WAV + 平台原生播放 |

## 许可证

MIT License

## 致谢

- [SherpaOnnx](https://github.com/k2-fsa/sherpa-onnx) — 语音识别引擎
- [Wails](https://wails.io/) — Go 桌面应用框架
- [SenseVoice](https://github.com/FunAudioLLM/SenseVoice) — 语音模型