中文 | English

一个面向会议场景的实时同传桌面应用，当前主链路是 Tauri + React 桌面壳层配合 Python sidecar 翻译引擎，提供：

• CH1：你说中文，对方听英文语音
• CH2：对方说英文，你看中英双行字幕

当前分支已经从“单脚本 + Tk 字幕窗口”为主，演进到“桌面端主控 + sidecar 服务化 + 独立字幕浮窗”的形态；CLI 模式仍保留，主要用于兼容和调试。

• 桌面端配置页支持火山引擎凭据、音频设备、字幕样式和通道开关配置。
• Tauri 主进程负责拉起 Python sidecar，并通过本地 WebSocket 与前端通信。
• CH1 默认支持 PCM 48kHz 直出到虚拟音频设备，也保留 ogg_opus + FFmpeg 回退链路。
• CH2 基于火山引擎字幕生命周期事件输出 start / streaming / end，桌面浮窗可稳定显示中英双行。
• 日志页支持实时日志查看、筛选、搜索和导出，方便定位设备、连接和播放问题。
• 配置文件在开发模式下存放于项目根目录，在打包模式下存放于应用数据目录，升级时不丢配置。

┌────────────────────────────┐
│ Tauri / React 桌面前端     │
│ - 配置页                   │
│ - 日志页                   │
│ - 字幕浮窗                 │
└────────────┬───────────────┘
             │ invoke + event
┌────────────▼───────────────┐
│ Tauri Rust 宿主            │
│ - 启动/停止 sidecar        │
│ - 管理主窗口/字幕浮窗      │
└────────────┬───────────────┘
             │ stdout 返回端口
┌────────────▼───────────────┐
│ Python sidecar             │
│ - /ws/control              │
│ - /ws/logs                 │
│ - /ws/subtitle             │
└────────────┬───────────────┘
             │
┌────────────▼───────────────┐
│ DualChannelTranslator      │
│ - CH1 麦克风 -> 英文语音   │
│ - CH2 系统音频 -> 中文字幕 │
└────────────────────────────┘

麦克风 -> AudioCapturer -> VolcengineTranslator(s2s)
      -> PcmStreamPlayer / OggOpusPlayer
      -> VB-CABLE Input -> 会议软件麦克风

系统音频 -> SystemAudioCapturer -> VolcengineTranslator(s2t)
        -> main.py 字幕状态机 -> /ws/subtitle
        -> React SubtitleOverlay

Python 依赖：

pip install -r requirements.txt

前端依赖：

pnpm install

cp config.yaml.example config.yaml

然后在 config.yaml 中填写：

• volcengine.app_key
• volcengine.access_key
• audio.microphone.device
• audio.system_audio.device
• audio.vbcable_output.device

可用设备可通过下面命令查看：

python scripts/list_devices.py

桌面开发模式：

pnpm tauri dev

这会启动 React 前端、Tauri 宿主和 Python sidecar。

CLI 兼容模式：

python main.py
python main.py my_config.yaml

CLI 模式下如果未注入桌面字幕回调，会回退到 Tk 字幕窗口实现。

• 服务地址默认是 wss://openspeech.bytedance.com/api/v4/ast/v2/translate
• 当前需要同时配置 app_key、access_key、resource_id
• 桌面配置页支持“测试连接”，会使用真实认证头发起握手

当前桌面默认值已经调整为：

audio:
  vbcable_output:
    device: "CABLE Input"
    sample_rate: 48000
    target_format: "pcm"
    use_ffmpeg: true

说明：

• target_format: pcm 是当前默认推荐路径，能直接配合 PcmStreamPlayer 做流式播放。
• sample_rate: 48000 适合虚拟声卡和会议软件链路。
• 如果需要兼容旧链路，可改回 ogg_opus 并启用 FFmpeg 解码。

• 左侧是配置页，包含凭据、音频设备、通道和字幕设置。
• 右侧是日志页，展示 SYS / CH1 / CH2 三类实时日志。
• 顶部状态栏支持启动、停止、显示/隐藏字幕窗口。

• 独立 WebView 窗口，不依赖主窗口持续可见。
• 支持中英双行显示、滚动追加、静默态降显。
• 支持展开/收起和隐藏窗口。
• 样式由 subtitle_window.font_size / opacity / text_color 控制，并通过 /ws/subtitle 实时下发。

优先检查：

• Python 依赖是否安装完整
• desktop_backend/sidecar.py 能否单独启动
• Tauri 是否成功读取到 sidecar stdout 输出的端口信息

优先检查：

• audio.vbcable_output.device 是否指向正确的虚拟输出设备
• 会议软件麦克风是否选择了 CABLE Output
• 当前是否使用 pcm / 48000Hz，以及虚拟声卡是否支持对应采样率
• 日志页里 CH1播放诊断 是否出现连续 underflow / rebuffer

优先检查：

• 字幕窗口是否已显示
• /ws/subtitle 是否已连接
• main.py 是否输出了 start / streaming / end 生命周期事件
• 配置页保存后字幕配置是否正常广播

realtime_translator/
├── core/                    # Python 核心音频与火山引擎能力
├── desktop_backend/         # sidecar、服务层、桌面后端协议
├── src/                     # React 前端
├── src-tauri/               # Tauri Rust 宿主
├── docs/                    # 架构、模块规格、经验沉淀
├── main.py                  # CLI / 桌面共用翻译主控
├── config.yaml.example      # 配置模板
└── README.md

• docs 总览
• 模块规格目录
• 系统整体架构
• 运行链路架构说明

• 当前仓库主路径已经切到桌面端交互优先。
• 基础启停、日志、字幕、配置读写和火山连接测试已经打通。
• 分支内最近一次重点优化是 CH1 PCM 直出 + 缓冲诊断，以及 CH2 字幕事件流 对齐桌面浮窗。

本项目采用仓库当前约定的自定义授权方式。涉及商业使用时，请先联系作者确认授权边界。