Booth

macOS 实时同声传译客户端，捕获系统音频并通过火山引擎 API 进行实时翻译。

功能

• 系统音频捕获：通过 BlackHole 虚拟声卡捕获任意应用的音频（YouTube、飞书、Zoom 等）
• 实时翻译：接入火山引擎 AST（音频语音翻译）API，延迟低
• 语音播放：翻译结果以语音形式从扬声器播出

前置依赖

系统要求

• macOS 11.0+
• Python 3.13+

系统级依赖（Homebrew）

brew install ffmpeg portaudio blackhole-2ch switchaudio-osx

火山引擎 API

前往 火山引擎控制台 开通 AST 服务，获取：

• app_key
• access_key
• resource_id

API 文档：https://www.volcengine.com/docs/6561/1756902

安装

git clone <repo-url>
cd booth
uv sync

配置

GUI 应用：首次启动会弹出引导界面，在设置页填入 API 凭据后自动保存。

CLI / 手动配置：直接创建 ~/.booth/config.json：

{
  "app_key": "your_app_key",
  "access_key": "your_access_key",
  "resource_id": "volc.service_type.10053",
  "source_language": "en",
  "target_language": "zh",
  "mode": "s2s"
}

GUI 与 CLI 共用同一份配置文件，无需重复填写。

使用

启动 GUI 应用

uv run python app.py

# 开启调试日志
uv run python app.py --debug

点击主窗口开始翻译，关闭窗口后 Booth 继续驻留 Dock，点击图标可唤起。

CLI 模式（无界面）

uv run python scripts/cli.py
uv run python scripts/cli.py --from en --to zh --debug

开发工具

# 测试 API 连通性
uv run python scripts/test_connection.py

# 调试音频捕获
uv run python scripts/debug_audio.py

开发

项目结构

booth/
├── app.py                      # GUI 入口
├── src/                        # 核心逻辑（无 GUI 依赖）
│   ├── config.py               # 配置加载与校验
│   ├── volcano_client.py       # 火山引擎 WebSocket 客户端
│   ├── translator.py           # 翻译流水线协调器
│   ├── audio_capture.py        # 系统音频捕获（BlackHole）
│   ├── audio_player.py         # 音频播放（Opus 解码）
│   ├── audio_device_manager.py # 音频设备检测与路由
│   └── python_protogen/        # Protobuf 生成代码
├── gui/                        # 界面层（PySide6 + qasync）
│   ├── controller.py           # 主控制器（BoothApp）
│   ├── state.py                # 状态管理（AppConfig、StateManager）
│   ├── translator_bridge.py    # 异步与 Qt 信号桥接
│   ├── popover.py              # 主控制面板
│   ├── floating_panel.py       # 浮动翻译面板
│   ├── settings_window.py      # 设置窗口
│   └── onboarding.py           # 首次使用引导
├── scripts/                    # 开发工具脚本
│   ├── cli.py                  # CLI 入口
│   ├── test_connection.py      # API 连接测试
│   └── debug_audio.py          # 音频调试
├── tests/                      # 测试套件
│   ├── gui/                    # GUI 组件测试
│   └── test_*.py               # 核心模块测试
└── docs/                       # 设计文档

运行测试

uv run pytest
uv run pytest --cov=src --cov-report=html

参考资料

• 火山引擎 AST 文档
• BlackHole 虚拟声卡