voicetranser

Voicetranser

完全本地化的 macOS 按住说话语音输入：按住全局快捷键，说话，松开后，转录文本会粘贴到光标所在位置。本地优先的 STT（Qwen3-ASR MLX / SenseVoice / mlx-whisper），不使用任何外部 API。此软件包提供用于安装、配置和排查该工具问题的代理技能。

目标 Profile

插件会安装到这里；不确定时保持 web。

npx -y @deepseek-ai/dsh plugin --profile web add github:Lumos-789/VoiceTranser#933bce3ebc911777b5751d369247d67f17abf5e5

兼容性与来源证明

Voicetranser 以 voicetranser 发布，当前版本为 1.0.2。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。

DSH 兼容范围: *
运行环境: any
发布来源: github
Registry 更新时间: 2026/11/4

版本

1.0.2stable

2026/11/4

1.0.0stable

2026/11/1

README

VoiceTranser

语音输入 → 转写 → 自动粘贴

按住全局热键说话，松开后自动完成语音转写并粘贴到当前应用。专为 AI 编程助手（Claude Code、Cursor 等）设计，完全本地运行，零外部 API 依赖。

✨ 特性

🎙️ 全局热键录音 — 通过外部快捷键工具（Karabiner-Elements/Raycast/Hammerspoon）触发 HTTP 端点，按住说话、松开出稿
🧠 本地 STT，三引擎 — 默认 Qwen3-ASR 0.6B 4bit（MLX/Metal GPU 推理，RTF 0.012-0.021，中文近完美自带标点、中英夹杂强）；SenseVoice Small int8（CPU fallback，RTF 0.03）；mlx-whisper large-v3（英文/小语种 fallback）。均离线推理，隐私安全
📋 自动粘贴 — 转写完自动粘贴到当前光标位置
🔧 误识纠正 — corrections.json 整词词表，发现新误识加一行重启即生效
🔔 系统通知 — 每个阶段 macOS 通知反馈，不盯终端也知道进度
🛡️ 自愈守护 — launchd KeepAlive + CoreAudio 死锁看门狗 + 8 项自检脚本
🍎 macOS 原生 — 菜单点击粘贴 + 系统通知，深度系统集成

架构

External Hotkey → HTTP /start|/stop → Recorder (sounddevice 16k mono)
  → Transcriber (Qwen3-ASR MLX 默认 / SenseVoice / mlx-whisper)
  → Corrector (corrections.json 整词纠正)
  → Output (clipboard + paste)

快速开始

前置要求

macOS Apple Silicon（MLX 引擎需要；Intel 机型走 SenseVoice CPU 引擎）
Python 3.11+
uv 包管理器

安装

git clone https://github.com/Lumos-789/VoiceTranser.git
cd VoiceTranser
uv sync   # PyPI 慢时: UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple uv sync
uv run python download_model.py   # 下 SenseVoice fallback 模型(228MB, hf-mirror 源)

Qwen3-ASR 主力模型（~500MB）首次运行自动从 hf-mirror 拉取，无需手动下载。

使用

# 守护模式（HTTP 服务器，默认引擎 qwen3-mlx）
uv run python -m voicetranser

# 临时切换引擎
STT_ENGINE=sensevoice uv run python -m voicetranser   # CPU fallback
STT_ENGINE=mlx-whisper uv run python -m voicetranser  # 英文/小语种

# 处理音频文件（不粘贴，对比引擎用）
uv run python -m voicetranser --file recording.wav --no-paste

# 8 项链路自检（音频检查有界，不会卡在系统授权框）
.venv/bin/python tests/diagnose.py
# 麦克风不能碰 / 不想弹权限框时跳过音频检查
.venv/bin/python tests/diagnose.py --skip-audio

诊断按实际运行的实例解析端口：--port > SERVER_PORT 环境变量 > 已安装 launchd plist 的 SERVER_PORT > 项目 .env > 默认端口（config.DEFAULT_SERVER_PORT，9877）；plist 与默认不一致时会打印 WARNING。麦克风不能碰时用 --skip-audio。

全局热键（推荐 Karabiner-Elements）

Karabiner complex_modifications 配置：right_option 按下 → curl localhost:9877/start，松开 → curl localhost:9877/stop。按住说话、松开自动转写粘贴。也可用 Raycast/Hammerspoon 触发 /toggle。

常驻后台（launchd）

uv run python install_launchd.py
curl -s localhost:9877/status

安装脚本会按当前 checkout 的绝对路径生成 ~/Library/LaunchAgents/com.voicetranser-sense.plist，再加载并启动服务；开机自启 + 崩溃自愈，服务启动时后台预热模型。需要换端口或引擎时用 --port / --engine，只生成不加载用 --no-load。

macOS 辅助功能权限

首次使用需要授予终端辅助功能权限：系统设置 → 隐私与安全性 → 辅助功能 → 勾选你的终端应用（自动粘贴所必需）。

测试与自检

.venv/bin/python -m unittest discover -s tests -v   # 单元测试
.venv/bin/python tests/diagnose.py --fix            # 8 项体检 + 自动重启修复

故障排查

先跑 tests/diagnose.py，它会把上面这些一次性查完，别凭现象猜。

转写成功但不自动粘贴 → 辅助功能权限没授。launchd 启动的实例要单独授一次（列表里会出现 python 条目）。
curl 连接被拒 → 服务没起来。tail -f ~/Library/Logs/VoiceTranser-sense.log；常见是端口被占（改 SERVER_PORT）或模型没下（跑 download_model.py）。
录到空白 → 麦克风权限没授。
launchd 反复崩 → 99% 是 plist 里路径写错。重跑 install_launchd.py 让它按当前 checkout 重新生成。
音频报错 -9986 / PortAudio 异常 → 休眠后音频子系统损坏或蓝牙耳机切换。看门狗会在 5s 超时后自杀重启，多数无感自愈；连续失败时 launchctl kickstart -k gui/$(id -u)/com.voicetranser-sense。

HTTP 端点

守护模式启动后监听 http://127.0.0.1:9877（默认；SERVER_PORT 可覆盖）：

端点	说明
`GET /toggle`	切换录音（idle → recording → processing）
`GET /start`	开始录音
`GET /stop`	停止录音并处理
`GET /status`	当前状态

性能实测（2026-11，Apple Silicon，16.5s 中文）

引擎	转写耗时	RTF	标点
Qwen3-ASR 0.6B 4bit MLX（默认）	0.25s	0.015	自带，规范
SenseVoice Small int8 CPU	0.53s	0.033	自带
mlx-whisper large-v3	~1.1s	~0.07	长句易丢

技术栈

组件	技术
STT 主力	mlx-audio + Qwen3-ASR 0.6B 4bit（MLX/Metal）
STT fallback	sherpa-onnx + SenseVoice / mlx-whisper
音频录制	sounddevice
包管理	uv

作为 DSH 插件使用

本仓同时是 DSH 插件（dsh.bundle 已声明）：安装后 agent 获得 voicetranser 技能，可代你完成安装、launchd 配置、Karabiner 热键配置与排障。

卸载

launchctl bootout gui/$(id -u)/com.voicetranser-sense
rm ~/Library/LaunchAgents/com.voicetranser-sense.plist
rm -rf ~/VoiceTranser                      # 项目目录
rm ~/Library/Logs/VoiceTranser-sense.log

再到系统设置里移除辅助功能 / 麦克风权限中的相关条目。

License

MIT

README

VoiceTranser

语音输入 → 转写 → 自动粘贴

按住全局热键说话，松开后自动完成语音转写并粘贴到当前应用。专为 AI 编程助手（Claude Code、Cursor 等）设计，完全本地运行，零外部 API 依赖。

✨ 特性

🎙️ 全局热键录音 — 通过外部快捷键工具（Karabiner-Elements/Raycast/Hammerspoon）触发 HTTP 端点，按住说话、松开出稿
🧠 本地 STT，三引擎 — 默认 Qwen3-ASR 0.6B 4bit（MLX/Metal GPU 推理，RTF 0.012-0.021，中文近完美自带标点、中英夹杂强）；SenseVoice Small int8（CPU fallback，RTF 0.03）；mlx-whisper large-v3（英文/小语种 fallback）。均离线推理，隐私安全
📋 自动粘贴 — 转写完自动粘贴到当前光标位置
🔧 误识纠正 — corrections.json 整词词表，发现新误识加一行重启即生效
🔔 系统通知 — 每个阶段 macOS 通知反馈，不盯终端也知道进度
🛡️ 自愈守护 — launchd KeepAlive + CoreAudio 死锁看门狗 + 8 项自检脚本
🍎 macOS 原生 — 菜单点击粘贴 + 系统通知，深度系统集成

架构

External Hotkey → HTTP /start|/stop → Recorder (sounddevice 16k mono)
  → Transcriber (Qwen3-ASR MLX 默认 / SenseVoice / mlx-whisper)
  → Corrector (corrections.json 整词纠正)
  → Output (clipboard + paste)

快速开始

前置要求

macOS Apple Silicon（MLX 引擎需要；Intel 机型走 SenseVoice CPU 引擎）
Python 3.11+
uv 包管理器

安装

git clone https://github.com/Lumos-789/VoiceTranser.git
cd VoiceTranser
uv sync   # PyPI 慢时: UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple uv sync
uv run python download_model.py   # 下 SenseVoice fallback 模型(228MB, hf-mirror 源)

Qwen3-ASR 主力模型（~500MB）首次运行自动从 hf-mirror 拉取，无需手动下载。

使用

# 守护模式（HTTP 服务器，默认引擎 qwen3-mlx）
uv run python -m voicetranser

# 临时切换引擎
STT_ENGINE=sensevoice uv run python -m voicetranser   # CPU fallback
STT_ENGINE=mlx-whisper uv run python -m voicetranser  # 英文/小语种

# 处理音频文件（不粘贴，对比引擎用）
uv run python -m voicetranser --file recording.wav --no-paste

# 8 项链路自检（音频检查有界，不会卡在系统授权框）
.venv/bin/python tests/diagnose.py
# 麦克风不能碰 / 不想弹权限框时跳过音频检查
.venv/bin/python tests/diagnose.py --skip-audio

全局热键（推荐 Karabiner-Elements）

常驻后台（launchd）

uv run python install_launchd.py
curl -s localhost:9877/status

macOS 辅助功能权限

首次使用需要授予终端辅助功能权限：系统设置 → 隐私与安全性 → 辅助功能 → 勾选你的终端应用（自动粘贴所必需）。

测试与自检

.venv/bin/python -m unittest discover -s tests -v   # 单元测试
.venv/bin/python tests/diagnose.py --fix            # 8 项体检 + 自动重启修复

故障排查

先跑 tests/diagnose.py，它会把上面这些一次性查完，别凭现象猜。

转写成功但不自动粘贴 → 辅助功能权限没授。launchd 启动的实例要单独授一次（列表里会出现 python 条目）。
curl 连接被拒 → 服务没起来。tail -f ~/Library/Logs/VoiceTranser-sense.log；常见是端口被占（改 SERVER_PORT）或模型没下（跑 download_model.py）。
录到空白 → 麦克风权限没授。
launchd 反复崩 → 99% 是 plist 里路径写错。重跑 install_launchd.py 让它按当前 checkout 重新生成。
音频报错 -9986 / PortAudio 异常 → 休眠后音频子系统损坏或蓝牙耳机切换。看门狗会在 5s 超时后自杀重启，多数无感自愈；连续失败时 launchctl kickstart -k gui/$(id -u)/com.voicetranser-sense。

HTTP 端点

守护模式启动后监听 http://127.0.0.1:9877（默认；SERVER_PORT 可覆盖）：

端点	说明
`GET /toggle`	切换录音（idle → recording → processing）
`GET /start`	开始录音
`GET /stop`	停止录音并处理
`GET /status`	当前状态

性能实测（2026-11，Apple Silicon，16.5s 中文）

引擎	转写耗时	RTF	标点
Qwen3-ASR 0.6B 4bit MLX（默认）	0.25s	0.015	自带，规范
SenseVoice Small int8 CPU	0.53s	0.033	自带
mlx-whisper large-v3	~1.1s	~0.07	长句易丢

技术栈

组件	技术
STT 主力	mlx-audio + Qwen3-ASR 0.6B 4bit（MLX/Metal）
STT fallback	sherpa-onnx + SenseVoice / mlx-whisper
音频录制	sounddevice
包管理	uv

作为 DSH 插件使用

本仓同时是 DSH 插件（dsh.bundle 已声明）：安装后 agent 获得 voicetranser 技能，可代你完成安装、launchd 配置、Karabiner 热键配置与排障。

卸载

launchctl bootout gui/$(id -u)/com.voicetranser-sense
rm ~/Library/LaunchAgents/com.voicetranser-sense.plist
rm -rf ~/VoiceTranser                      # 项目目录
rm ~/Library/Logs/VoiceTranser-sense.log

再到系统设置里移除辅助功能 / 麦克风权限中的相关条目。

License

MIT

Voicetranser

兼容性与来源证明

版本

相关插件

Voicetranser

README

VoiceTranser

✨ 特性

架构

快速开始

前置要求

安装

使用

全局热键（推荐 Karabiner-Elements）

常驻后台（launchd）

macOS 辅助功能权限

测试与自检

故障排查

HTTP 端点

性能实测（2026-11，Apple Silicon，16.5s 中文）

技术栈

作为 DSH 插件使用

卸载

License

兼容性与来源证明

版本

相关插件

相关插件

相关插件

README

VoiceTranser

✨ 特性

架构

快速开始

前置要求

安装

使用

全局热键（推荐 Karabiner-Elements）

常驻后台（launchd）

macOS 辅助功能权限

测试与自检

故障排查

HTTP 端点

性能实测（2026-11，Apple Silicon，16.5s 中文）

技术栈

作为 DSH 插件使用

卸载

License