实时语音转写 for Obsidian

中文 | English

同时支持本地 SenseVoice 与云端托管的实时语音转写插件，内置热词、易错词纠正、翻译、润色与摘要

---

功能特性

功能	说明
双识别引擎	可选择完全本地的 SenseVoice，或免配置 Python/模型的云端托管
本地实时转写	SenseVoice-Small + Silero VAD + sherpa-onnx，音频无需离开本机
云端实时转写	中国大陆默认使用腾讯云，海外默认使用 Deepgram Nova-3
多语言识别	中文 / 英文 / 日文 / 韩文 / 粤语
识别语言范围	可限定为纯中文、纯英文或中英混杂模式
实时预览模式	稳态档（更准）/ 极速档（更快）两档切换
识别热词	每行配置一个词或短语，提升专有名词、产品名和人名的识别率
易错词纠正	使用 错误词 => 正确词 规则，在显示和保存前自动替换
自动翻译	检测到非中文内容时，自动调用 OpenAI 兼容 API 翻译成中文
AI 文本润色	手动触发，将口语化转写润色为规范书面语
AI 自动摘要	按字数阈值自动生成摘要（默认每 500 字触发一次）
二次摘要（综合总结）	累积多个摘要后自动生成一份综合总结
多种 AI 后端	支持 OpenAI 兼容 API、Claude Code CLI、Codex CLI 和 OpenCode CLI
导出为笔记	一键导出为 Obsidian Markdown 笔记，支持时间戳/AI/手动三种命名方式
历史记录持久化	关闭 Obsidian 后转写记录不丢失
跨平台支持	macOS / Windows / Linux 全平台兼容

两种识别模式怎么选

模式	适合谁	需要准备	数据路径
云端托管	希望安装后立即使用、需要更强云端识别能力	注册并登录插件账户	音频发送到所选云端识别服务
本地 SenseVoice	重视离线与隐私、愿意配置本地环境	Python 3.10–3.12、约 240 MB 模型	音频只在本机处理

架构概览

Obsidian 插件 (TypeScript)
├── src/
│   ├── main.ts               # 插件主入口，协调所有服务
│   ├── settings.ts           # 设置面板 UI
│   ├── types.ts              # 类型定义
│   ├── services/
│   │   ├── BackendManager.ts     # Python 后端进程管理（启动/停止）
│   │   ├── WebSocketClient.ts    # 与后端的 WebSocket 通信
│   │   ├── TencentASRClient.ts   # 腾讯云实时 ASR
│   │   ├── DeepgramASRClient.ts  # Deepgram 实时 ASR
│   │   ├── AudioCapture.ts       # 麦克风音频采集（Web Audio API）
│   │   └── AgentBackendService.ts # 调用 API / 本机 AI CLI
│   ├── views/
│   │   ├── TranscriptionView.ts  # 右侧边栏主视图
│   │   └── TitleInputModal.ts    # 手动命名导出弹窗
│   └── utils/
│       ├── hotwords.ts           # 热词解析、云端格式适配与本地辅助纠正
│       └── textCorrections.ts    # 易错词确定性替换
│
└── backend/                  # Python 后端
    ├── server.py             # WebSocket 服务端（sherpa-onnx 推理）
    ├── download_model.py     # 模型自动下载脚本
    └── requirements.txt      # Python 依赖

数据流：
                          ┌→ 本地 WebSocket → SenseVoice
麦克风 → AudioCapture ────┤
                          └→ 云端 WebSocket → 腾讯云 / Deepgram
                                                ↓
                     partial/final → 稳定性处理 → 易错词纠正
                                                ↓
                              聚合 → 翻译/摘要/润色 → 视图与笔记

---

第一步：安装 Obsidian 插件

方式 A：从 Release 直接安装（推荐普通用户）

1. 前往 Releases 下载最新版本的 zip 文件

2. 解压后，将文件夹重命名为 realtime-transcription

3. 将该文件夹整体复制到你 Vault 的插件目录：

   • macOS / Linux：<你的Vault>/.obsidian/plugins/realtime-transcription/
   • Windows：<你的Vault>\.obsidian\plugins\realtime-transcription\

   不知道 Vault 在哪？打开 Obsidian → 左下角「管理库」→ 查看库的本地路径。

4. 打开 Obsidian → 设置 → 第三方插件 → 关闭安全模式 → 找到「实时语音转写」并启用

方式 B：从源码构建（推荐开发者）

git clone https://github.com/garetneda-gif/obsidian-realtime-transcription.git
cd obsidian-realtime-transcription
npm install
npm run build
# 构建产物：根目录的 main.js
# 将 manifest.json、main.js、styles.css、backend/ 复制到 Vault 插件目录

若你使用 remotely-save，可能在同步结束时被旧版 main.js 覆盖。可在同步完成后执行：

npm run post-sync-refresh -- --vault "/你的/Vault/路径" --vault-name "你的Vault名称"

该命令会再次复制插件文件，并通过 Obsidian CLI 执行 plugin:reload 强制重载。

---

第二步：选择识别模式

打开 Obsidian → 设置 → Realtime Transcription → 识别引擎。

云端托管（最快上手）

1. 将「ASR 提供方」设为「云端托管」
2. 打开账户中心完成注册或登录
3. 选择「中国大陆 / 海外」和识别语言，也可以保持自动选择
4. 返回转写面板开始录音

云端模式不需要安装 Python，也不需要下载本地模型。中国大陆线路默认使用腾讯云，海外线路默认使用 Deepgram。

本地 SenseVoice

选择「本地」后，继续完成下面的 Python、依赖和模型配置。

第三步：安装 Python

如果你已有 Python 3.10 ~ 3.12，可跳过此步。

检查是否已安装 Python：

# macOS / Linux
python3 --version

# Windows（命令提示符或 PowerShell）
python --version

输出类似 Python 3.11.x 则已安装，可继续。否则按下方系统安装：

系统	安装方式
macOS	推荐：brew install python@3.12（需先安装 Homebrew） 或：从 python.org 下载安装包
Windows	从 python.org 下载安装包，安装时务必勾选「Add Python to PATH」
Linux	sudo apt install python3.12 python3.12-pip（Ubuntu/Debian）

推荐版本：3.10 / 3.11 / 3.12。3.13 和 3.14 兼容性尚未充分测试，不建议使用。

---

第四步：安装 Python 依赖

在插件目录的 backend/ 文件夹中提供了一键安装脚本，运行一次即可，无需手动输入任何 pip 命令。

macOS / Linux

双击 backend/setup.command（macOS 可直接双击运行），或在终端中运行：

cd <你的Vault>/.obsidian/plugins/realtime-transcription/backend
bash setup.command

Windows

双击 backend\setup.bat，或在命令提示符中运行：

cd <你的Vault>\.obsidian\plugins\realtime-transcription\backend
setup.bat

脚本会自动完成：创建虚拟环境 → 安装所有依赖 → 验证安装 → 输出第六步需要填写的 Python 路径。

遇到报错？ 确认已安装 Python 3.10~3.12，且终端/PowerShell 有网络访问权限。

---

第五步：准备模型文件

模型文件需要存放在一个你自己创建的目录中（插件不会自动创建目录）。

先创建模型目录：

# macOS / Linux
mkdir -p ~/obsidian-models

# Windows（命令提示符）
mkdir C:\Users\你的用户名\obsidian-models

然后下载模型（二选一）：

方法一：插件内一键下载（推荐）

1. 打开 Obsidian → 设置 → 实时语音转写 → 模型设置
2. 在「模型目录」字段填入刚创建的目录路径：
   • macOS/Linux：/Users/你的用户名/obsidian-models
   • Windows：C:\Users\你的用户名\obsidian-models
3. 点击 下载模型 按钮（约 240 MB，需要网络，耐心等待）
4. 弹出「模型下载完成！」通知后即可

方法二：手动下载

将以下三个文件分别下载到同一目录（每个都是独立文件，无需解压）：

文件	下载链接（点击直接下载）	大小
model.int8.onnx	HuggingFace 下载 · 国内镜像	~229 MB
tokens.txt	HuggingFace 下载 · 国内镜像	<1 MB
silero_vad.onnx	GitHub 下载	~1.8 MB

提示：建议保持「使用 Int8 量化模型」为开启状态（默认已开启），可将模型体积从 895 MB 压缩至 229 MB，精度基本无损。

确认三个文件都在目录中：

ls ~/obsidian-models
# 应该看到：model.int8.onnx   tokens.txt   silero_vad.onnx

---

第六步：本地模式配置

打开 Obsidian → 设置 → Realtime Transcription，按以下顺序配置：

后端设置

• Python 路径：填写 Python 的路径

  • macOS / Linux：填 python3（大多数情况下直接可用）
  • Windows：填 python（插件会自动设置此默认值）

  如果默认值不工作，需要获取 Python 完整路径：

  • macOS/Linux：在终端运行 which python3
  • Windows：在命令提示符运行 where python，复制第一行结果

  各平台路径示例：

  系统	Python 路径示例
  macOS（系统 Python）	python3 或 /usr/local/bin/python3
  macOS（虚拟环境，推荐）	/Users/你的用户名/.../backend/venv/bin/python
  Windows	C:\Users\yourname\AppData\Local\Programs\Python\Python312\python.exe
  Linux	python3 或 /usr/bin/python3

• 后端端口：默认 18888，一般无需修改

• 点击 检测环境 按钮验证配置：

  • 成功：弹出通知「环境检测通过：Python + sherpa-onnx 可用」→ 可继续
  • 失败：见下方环境检测失败排查

模型设置

• 模型目录：填入第五步中创建的目录完整路径

• 识别语言范围：中英混杂（默认）/ 纯中文 / 纯英文

  说中文时识别出日语或韩语？将此项改为「纯中文」。

热词与易错词

入口位于 识别引擎 → 热词与易错词。

识别热词使用逐条输入，适合产品名、人名、缩写和专业术语。点击「新增热词」可以继续添加：

Obsidian
Claude Code
SenseVoice

纠正规则使用成对输入：左侧填写识别错误的词，右侧填写要替换成的正确词。点击「新增规则」可以继续添加：

错误词：克劳德扣的    纠正为：Claude Code
错误词：欧布西迪安    纠正为：Obsidian
错误词：深思为死      纠正为：DeepSeek

• 云端热词用于识别加权；本地 SenseVoice 会在识别后按中文拼音、英文大小写/空格及极小拼写差异进行保守纠正
• 本地热词不是 SenseVoice 原生解码加权；未匹配到的专有词可继续使用下方的一对一纠正规则
• 纠正规则对本地和云端结果都生效
• 替换发生在识别稳定性判断之后，不会干扰实时文本稳定
• 规则按原文直接匹配，不使用正则表达式
• 插件仍以 错误词 => 正确词 格式保存规则，升级后原有规则会自动显示为成对输入

AI 模型配置（可选）

翻译、润色、AI 命名和摘要可分别使用「快速模型」与「智能模型」。每一档都可以选择：

• OpenAI 兼容 API：DeepSeek、通义千问、OpenAI、本地 Ollama 等
• 本机 CLI：Claude Code、Codex 或 OpenCode

使用 API 时：

字段	填写说明
API 端点	完整 URL，例如 https://api.deepseek.com/v1/chat/completions
API Key	对应服务的密钥，以 sk- 开头
模型名称	例如 deepseek-chat、qwen-turbo、gpt-4o-mini

使用本机 CLI 时，先确认对应命令能在终端运行，再选择调用方式并点击「自动检测」和「测试」。快速模型用于翻译、润色和 AI 命名；智能模型用于摘要和二次摘要，两档配置互不影响。

如果暂时不需要 AI 功能，直接保持关闭即可。

高级设置（可选，默认值已够用）

参数	说明	推荐值
实时模式预设	稳态档更准，极速档更快	稳态档
实时预览	边说边显示识别中的文字	开启
VAD 静音阈值	越大分句越少	1.0 s
聚合输出窗口	越大段落越长（延迟也越大）	4 s
单段最大字数	超过此长度自动换段	320 字

---

使用方法

1. 点击左侧 Ribbon 栏的麦克风图标，打开转写面板
2. 点击面板中的开始录制按钮
3. 对着麦克风说话，右侧面板实时显示转写文字
4. 说完后点击停止录制
5. 可选：点击任意条目上的润色按钮，用 AI 整理为书面语
6. 点击导出笔记，将转写内容保存为 Obsidian 笔记文件

---

常见问题排查

环境检测失败排查

提示内容	可能原因	解决方案
「环境检测失败，请执行 pip install...」	sherpa-onnx 依赖未安装	按第四步说明安装依赖后重试
「环境检测失败」但依赖已安装	使用了虚拟环境，但 Python 路径仍指向系统 Python	将「Python 路径」改为虚拟环境路径，例如 /path/to/backend/venv/bin/python
检测无反应，按钮灰色	Python 路径字段为空	macOS/Linux 填 python3；Windows 填 python
「No such file or directory」	Python 路径不存在	macOS/Linux 运行 which python3；Windows 运行 where python 获取正确路径
Windows 上找不到 python	Python 未加入系统 PATH	重新安装 Python，安装时勾选「Add Python to PATH」

后端启动失败：错误信息对照表

错误提示	原因	解决方案
模型文件缺失: model.int8.onnx	模型未下完或目录填错	检查模型目录路径，重新点击「下载模型」
模型文件缺失: tokens.txt	同上	同上
模型文件缺失: silero_vad.onnx	同上	同上
后端启动超时（30秒）	模型首次加载慢，或 Python 环境有问题	关闭其他占用内存的程序后重试；确认依赖已安装
[Errno 2] No such file or directory	Python 路径填错	重新检查 Python 路径配置

查看详细错误日志：

• macOS：Cmd + Option + I → Console 标签
• Windows：Ctrl + Shift + I → Console 标签

将红色报错信息复制后可在 Issues 提问。

翻译返回 404 错误

检查 API URL 是否多写了 /v1：

# 错误
https://api.example.com/v1v1/chat/completions

# 正确
https://api.example.com/v1/chat/completions

频繁出现 429 限流

• 换用速率更高的模型或提升 API 套餐额度
• 关闭自动翻译，改为手动触发
• 调大「聚合输出窗口」（减少 API 调用频率）

识别结果分句太碎

在高级设置中调大：

• VAD 静音阈值（建议从 1.0 调到 1.5~2.0）
• 聚合输出窗口（建议从 4 调到 6~8）

Windows 后端启动报 NotImplementedError

如果在 v1.0.2 或更早版本遇到 NotImplementedError: add_signal_handler 错误，请升级至 v1.0.3+。此问题已在新版本中修复。

Claude Code CLI 提示 spawn EINVAL

请升级到 v1.5.2 或更高版本。新版使用跨平台进程启动实现，并会自动检测 PATH、Homebrew、npm、nvm、asdf 和 volta 中的 CLI 路径。升级后在「AI 模型配置」中重新点击「自动检测」和「测试」。

macOS 首次运行弹出安全警告

macOS 可能拦截未经公证的 Python 脚本，出现「无法验证开发者」提示：

1. 打开「系统设置」→「隐私与安全性」
2. 找到相关提示，点击「仍要打开」或「允许」
3. 返回 Obsidian，重新点击开始录制

---

安全提示

• 本地模式的麦克风音频只在本机处理
• 云端模式会把音频发送到所选识别服务，请根据自己的隐私要求选择模式
• data.json 可能包含 API Key 或登录令牌，不要提交到 Git 或分享给他人
• 换新设备时建议手动在插件设置中重新填写 API Key

云端收费服务

云端托管模式使用 billing-server/：中国大陆默认走腾讯云，其他地区默认走 Deepgram Nova-3，也可在插件设置中手动选择。服务端预扣余额；腾讯云按会话时长结算，海外线路通过同域 WebSocket 代理转发，并由服务端回查请求记录与真实用量。

最小启动配置：

export BS_SECRET_KEY="至少 32 位随机字符串"
export TENCENT_APP_ID="腾讯云 AppID"
export TENCENT_SECRET_ID="腾讯云 SecretID"
export TENCENT_SECRET_KEY="腾讯云 SecretKey"
export DEEPGRAM_API_KEY="Deepgram Member 权限的生产 API Key"
export DEEPGRAM_PROJECT_ID="Deepgram Project ID"
export AP_XUNHU_APPID="虎皮椒 AppID"
export AP_XUNHU_APPSECRET="虎皮椒 AppSecret"
export AP_XUNHU_NOTIFY_URL="https://你的域名/api/billing/callback/xunhu"
export BS_PRICE_PER_HOUR_CENTS=200

cd billing-server
pip install -r requirements.txt
python app.py

不要将 Deepgram API Key 写入插件或仓库。该 Key 只配置在 Vercel 服务端，用于 WebSocket 代理和读取项目请求用量。

上线后把插件设置里的「服务器地址」填成你的 HTTPS API 域名。

---

Contributing

Pull requests and issues are welcome! Please:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit your changes following Conventional Commits
4. Open a Pull Request

本地检查：

npm test
npm run build

---

许可证

MIT License — 详见 LICENSE。