内容
# Banshee
Banshee 是一款适用于 macOS 的离线、常驻语音守护进程。它支持本地语音转文本的听写和文本转语音，并通过 JSON-RPC API 和 MCP 服务器提供所有功能，以便您喜欢的 LLM 主机可以通过它进行语音交流。Banshee 完全由 Rust 编写，并且所有数据都不会离开您的机器。
您只需按住一个热键，说出您的想法，Banshee 就会使用 Whisper 在本地进行转录。它可以直接将文本输入到您正在使用的应用程序中，或者交给 LLM。无需云服务，无需 API 密钥，也不会有音频数据离开您的笔记本电脑。
> **注意：Banshee 仍在开发中。** 目前它仅在 **macOS 上运行**。Windows 和 Linux 支持正在开发中，未来版本中将会提供，请保持关注！
## 功能
- **本地听写。** 按住热键，讲话，释放，文本就会出现在您当前聚焦的应用程序中。
- **离线语音转文本。** Whisper（`whisper-rs`）通过 Silero 语音活动检测。无需网络，无需 API 密钥。
- **文本转语音。** 让 Banshee 大声朗读状态更新（目前通过 macOS 的 `say` 命令）。
- **音频提示。** 短暂的音调确认录音开始/停止，成功转录和错误，这样您无需查看屏幕就能知道发生了什么。
- **JSON-RPC API** 通过 Unix 套接字，因此您可以轻松地从命令行或任何您喜欢的客户端进行脚本编写。
- **MCP 服务器**，为 LLM 主机（如 Claude Desktop）提供语音和听写工具，以便助手可以通过 Banshee 进行语音交流。
## 要求
- **macOS**（Apple Silicon 或 Intel）。TTS 使用 macOS `say` 命令，捕获和热键目前仅限于 macOS。
- **Rust**（稳定版，2024 年版）。从 [rustup](https://rustup.rs) 获取。
- **大约 1.5 GB** 的空闲磁盘空间用于默认的 Whisper 模型。
## 安装
将 Banshee 安装到您的 `PATH` 中，以便您可以从任何地方使用 `banshee` 命令：
```bash
git clone https://github.com/yamanahlawat/banshee.git
cd banshee
cargo install --path bansheed --features apple # 安装 `banshee` 命令
cargo install --path banshee-mcp-shim # 安装 MCP shim（可选）
```
`apple` 功能启用了 Whisper 的 Metal 和 CoreML 加速。两个二进制文件都位于 `~/.cargo/bin` 中，因此从现在开始，您可以直接运行 `banshee`。
如果 `banshee` 返回“找不到命令”，则 `~/.cargo/bin` 尚未在您的 `PATH` 中（如果您通过 Homebrew 而不是 rustup 安装了 Rust，则常见）。将其添加并重新加载您的 shell：
```bash
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```
更喜欢在不安装的情况下构建？`cargo build --release --features apple` 会将二进制文件放在 `target/release/` 中。
## 设置
**1. 下载模型**（Whisper 和 Silero VAD）到 `~/.banshee/models/`：
```bash
banshee setup
```
**2. 授予 macOS 权限。** Banshee 需要其中两个，否则它会悄悄地无法录音或输入：
- **麦克风**，以便它可以捕获音频。
- **辅助功能**，以便它可以监听全局热键并输入您的转录文本。
您将在 **系统设置 > 隐私和安全** 下找到两者。 将您的终端（或 `banshee` 二进制文件）添加到 *麦克风* 和 *辅助功能* 列表中。
## 用法
启动守护进程：
```bash
banshee serve
```
在守护进程运行的情况下，全局热键是：
- **按住 `F5`** 进行录音。释放后，转录内容将被保存，您可以稍后使用 `banshee listen` 获取。
- **按住 `Shift + F5`** 进行录音。释放后，转录内容将直接输入到您当前聚焦的应用程序中（这是听写模式）。
CLI 命令都通过套接字与正在运行的守护进程通信：
| 命令 | 执行操作 |
| --- | --- |
| `banshee serve` | 启动后台守护进程 |
| `banshee setup` | 下载所需模型 |
| `banshee status` | 显示守护进程健康状况和状态 |
| `banshee listen` | 打印最近的转录内容 |
| `banshee speak "<text>"` | 大声朗读一些文本 |
| `banshee history` | 列出所有已保存的转录内容 |
| `banshee clear-history` | 清除已保存的转录内容 |
## 配置
配置是可选的。如果您想覆盖默认值，请创建 `~/.banshee/config.toml`（此处显示默认值）：
```toml
[daemon]
save_history = true # 在 ~/.banshee/banshee.db 中保存转录内容
[stt]
preset = "balanced" # fast | balanced | quality（见下文）
vad_threshold = 0.5 # 0.0 至 1.0；值越高，语音检测越严格
[audio.cues]
enabled = true # 录音开始/停止、成功和错误时的提示音
```
您还可以通过 `banshee.configure` RPC 在运行时更改 `vad_threshold`，无需重启。
### 选择 Whisper 模型
`preset` 选择 Banshee 使用的 Whisper 模型：
| 预设 | 模型 | 权衡 |
| --- | --- | --- |
| `fast` | `ggml-base.en.bin` | 最快且最轻量，仅限英语 |
| `balanced` | `ggml-large-v3-turbo-q5_0.bin` | 默认；准确且速度合理 |
| `quality` | `ggml-large-v3-q5_0.bin` | 最准确，但最重量级 |
更改预设后，运行 `banshee setup` 以将匹配的模型下载到 `~/.banshee/models/`。
## MCP 集成
`banshee-mcp-shim` 是一个 MCP stdio 服务器，它将 LLM 主机桥接到守护进程，并提供语音和听写工具。它需要 `banshee serve` 正在运行。
如果您使用上述 `cargo install` 安装了它，那么 shim 位于 `~/.cargo/bin/banshee-mcp-shim`。它与任何支持 MCP 的工具（如 Claude Code、OpenCode、Cursor 等）一起工作。它们大多数使用相同的 `mcpServers` 配置形状：
```json
{
"mcpServers": {
"banshee": {
"command": "banshee-mcp-shim"
}
}
}
```
每个工具在其自己的位置保存此配置（例如，Cursor 使用 `~/.cursor/mcp.json`，而 Claude Code 允许您使用 `claude mcp add` 添加），因此请查看您工具的文档，了解 MCP 配置的位置。如果您的工具无法从您的 `PATH` 中获取二进制文件，请使用完整路径（`~/.cargo/bin/banshee-mcp-shim`）代替。重启工具后，语音和听写工具就会出现。
## 架构
| 仓库 | 角色 |
| --- | --- |
| `bansheed` | 守护进程：音频捕获、VAD、STT、热键、JSON-RPC API |
| `banshee-mcp-shim` | MCP stdio 到守护进程的桥梁 |
| `banshee-common` | 共享协议类型（JSON-RPC、错误、配置） |
守护进程通过 Unix 套接字在 `~/.banshee/banshee.sock` 处公开 JSON-RPC 2.0 API。CLI 和 MCP shim 都是它的客户端。
## 许可证
在 [MIT License](LICENSE) 下许可。
