Realtime Transcription

中文 | English

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

功能特性

两种识别模式怎么选

架构概览

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 则已安装，可继续。否则按下方系统安装：

推荐版本：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. 弹出「模型下载完成！」通知后即可

方法二：手动下载

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

提示：建议保持「使用 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 时：

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

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

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

使用方法

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

常见问题排查

环境检测失败排查

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

查看详细错误日志：

• 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。