Phase 2 实施文档

📋 实施概览

版本: v2.0.0 实施日期: 2025-01-01 状态: ✅ 开发完成，待测试

实施目标

实现双向实时翻译系统（耳机模式），包括：

Channel 1: 中文 → 英文语音翻译
Channel 2: 英文 → 中文文本字幕
耳机物理隔离，无回声问题
双通道独立并发架构

🏗️ 已完成组件

1. 系统音频捕获模块 ✅

文件: core/system_audio_capture.py

功能:

捕获系统播放的音频（立体声混音/CABLE Output）
智能设备查找和降级策略
设备可用性测试
线程安全的音频队列

关键特性:

主设备: 立体声混音（Windows 默认）
降级设备: VB-CABLE Output
采样率: 16kHz（火山引擎要求）
块大小: 1600 samples (100ms)

2. 悬浮字幕窗口模块 ✅

文件: gui/subtitle_window.py

功能:

半透明悬浮窗口显示字幕
支持多行历史记录（最近10条）
交互功能：拖动、字体切换、隐藏/显示
线程安全的异步更新

关键特性:

竖向布局: 400x800（适合侧边显示）
字体: Microsoft YaHei, 20pt
不透明度: 85%
位置: 右上角（可配置）
时间戳: 可选显示

3. 双通道翻译主程序 ✅

文件: main_v2.py

功能:

双通道独立并发执行
Channel 1: 麦克风 → 英文语音
Channel 2: 系统音频 → 中文字幕
UI 事件循环处理
完整的统计信息

架构特点:

两个独立的 WebSocket 连接
异步并发架构（asyncio.gather）
线程安全的字幕更新
优雅的资源管理和错误处理

4. 配置文件 ✅

文件: config_v2.yaml

配置项:

火山引擎 API 配置
麦克风设备配置
系统音频设备配置（双方案）
VB-CABLE 输出配置
翻译通道配置（可独立启用/禁用）
字幕窗口配置（尺寸、字体、位置等）
日志和性能配置

双方案支持:

方案A: 立体声混音（推荐，简单）
方案B: VB-CABLE + 监听（支持蓝牙）

🧪 测试脚本

1. 完整组件测试 ✅

文件: test_phase2_components.py

测试内容:

配置文件加载验证
系统音频捕获功能
字幕窗口显示和更新
组件集成测试

运行方式:

python test_phase2_components.py

2. 字幕窗口快速测试 ✅

文件: test_subtitle_quick.py

测试内容:

字幕窗口创建和显示
多行历史记录
交互功能测试
时间戳显示

运行方式:

python test_subtitle_quick.py

📊 技术架构

系统架构图

┌─────────────────────────────────────────────────────┐
│      Realtime Translator v2.0 (耳机模式)             │
├─────────────────────────────────────────────────────┤
│                                                     │
│  ┌──────────────┐              ┌─────────────────┐ │
│  │  Channel 1   │              │   Channel 2     │ │
│  │  麦克风捕获   │              │  系统音频捕获   │ │
│  │  (中文输入)  │              │  (英文输入)     │ │
│  └──────┬───────┘              └────────┬────────┘ │
│         │ PCM 16kHz Mono                │          │
│         ↓                                ↓          │
│  ┌─────────────┐              ┌──────────────────┐ │
│  │ 火山引擎     │              │  火山引擎         │ │
│  │ s2s 翻译    │              │  s2t 翻译        │ │
│  │ zh → en     │              │  en → zh         │ │
│  └──────┬──────┘              └────────┬─────────┘ │
│         │ Ogg Opus 24kHz                │ Text     │
│         ↓                                ↓          │
│  ┌─────────────┐              ┌──────────────────┐ │
│  │ VB-CABLE    │              │  悬浮字幕窗口     │ │
│  │ Input       │              │  (Tkinter)       │ │
│  │ (给Zoom)    │              │  + 半透明        │ │
│  │             │              │  + 可拖动        │ │
│  │             │              │  + 置顶显示      │ │
│  └─────────────┘              └──────────────────┘ │
│                                                     │
│  🎧 用户使用耳机 → 物理隔离 → 无回声问题             │
└─────────────────────────────────────────────────────┘

核心特性

✅ 双通道独立并发

两个 WebSocket 连接完全独立
无需相互协调或冲突检测
一个通道故障不影响另一个

✅ 简化架构

无需状态机管理
无需音频缓冲协调
无需 VAD 或音量检测
无需冲突检测算法

✅ 物理隔离优势

耳机提供 100% 音频隔离
零延迟（相比软件检测）
零误检率
零配置成本

🚀 使用指南

前置准备

硬件要求
- 耳机/耳麦（必需！）
- 麦克风（可以是耳麦的麦克风）
- 稳定的网络连接
软件依赖
- Python 3.8+
- 火山引擎 API 访问权限
- FFmpeg（用于音频解码）
- VB-CABLE（可选，用于 Zoom 集成）

配置步骤

方案A: 立体声混音（推荐）

启用立体声混音

1. 右键音量图标 → 声音
2. 录制标签 → 右键空白处 → 显示已禁用的设备
3. 右键"立体声混音" → 启用
4. 设为默认录制设备

Zoom 配置
- 麦克风: CABLE Output (VB-Audio Virtual Cable)
- 扬声器: Speakers (Realtek HD Audio output)
使用有线耳机
- 连接到 Realtek 声卡接口

方案B: VB-CABLE + 监听

修改配置文件

audio:
  system_audio:
    device: "CABLE Output"  # 改为 VB-CABLE Output

Zoom 配置
- 麦克风: CABLE Output (VB-Audio Virtual Cable)
- 扬声器: CABLE Input

设置 Windows 监听

1. 右键"CABLE Output" → 属性
2. 侦听标签 → 勾选"侦听此设备"
3. 通过此设备播放 → 选择蓝牙音箱

运行程序

测试组件
```
python test_phase2_components.py
```
启动双向翻译
```
python main_v2.py
```
操作说明
- 开始说中文，对方会听到英文
- 对方说英文，你会看到中文字幕
- 字幕窗口可拖动、双击放大、ESC 隐藏
- 按 Ctrl+C 停止并查看统计

📝 配置参考

完整配置示例

# 火山引擎配置
volcengine:
  ws_url: "wss://openspeech.bytedance.com/api/v4/ast/v2/translate"
  app_key: "你的app_key"
  access_key: "你的access_key"
  resource_id: "volc.service_type.10053"

# 音频配置
audio:
  microphone:
    device: "麦克风"
    sample_rate: 16000
    channels: 1
    chunk_size: 1600

  system_audio:
    device: "立体声混音"
    fallback_device: "CABLE Output"
    sample_rate: 16000
    channels: 1
    chunk_size: 1600

  vbcable_output:
    device: "CABLE Input"
    sample_rate: 24000
    use_ffmpeg: true
    monitor_device: null
    enable_monitor: false

# 翻译通道配置
channels:
  zh_to_en:
    mode: "s2s"
    source_language: "zh"
    target_language: "en"
    enabled: true

  en_to_zh:
    mode: "s2t"
    source_language: "en"
    target_language: "zh"
    enabled: true

# 字幕窗口配置
subtitle_window:
  enabled: true
  width: 400
  height: 800
  font_size: 20
  bg_color: "#000000"
  text_color: "#FFFFFF"
  opacity: 0.85
  position: "top_right"
  max_history: 10
  show_timestamp: false

🐛 常见问题

1. 找不到立体声混音

问题: 系统音频设备查找失败

解决:

右键音量图标 → 声音
录制标签 → 显示已禁用的设备
启用"立体声混音"

2. 字幕窗口不显示

问题: 字幕窗口创建失败

解决:

检查 Tkinter 是否安装
检查显示器配置
尝试修改 position 配置

3. 音频有回声

问题: 听到自己的声音回传

解决:

确保使用耳机（必需！）
检查 Zoom 扬声器设置
降低扬声器音量

4. Channel 2 无法接收音频

问题: 系统音频捕获失败

解决:

检查立体声混音是否启用
尝试方案 B（VB-CABLE）
运行测试脚本诊断

📊 性能指标

目标指标

指标	目标值	实际值
CPU 占用	<25%	待测
内存使用	<500MB	待测
端到端延迟	<6秒	待测
字幕刷新延迟	<200ms	待测
稳定运行时间	>2小时	待测

待验证功能

📚 下一步计划

Phase 2.1: 优化和完善

添加字幕历史导出功能
优化字幕显示效果（渐变、动画）
添加翻译质量反馈机制
实现配置热重载

Phase 3: GUI 控制面板

可视化配置编辑器
实时状态监控面板
音频设备选择器
翻译历史记录浏览

Phase 4: 扬声器模式

WebRTC VAD 集成
智能冲突检测
音量检测和自适应
回声抑制算法

🎉 总结

Phase 2 的核心功能已经完成实施，包括：

✅ 完整的双向翻译架构

双通道独立并发执行
耳机物理隔离，零回声
简化架构，高可靠性

✅ 所有核心组件

系统音频捕获模块
悬浮字幕窗口
双通道翻译主程序
完整配置系统

✅ 测试和文档

组件测试脚本
快速测试工具
详细使用文档
配置参考指南

下一步: 运行测试脚本验证功能，然后进行实际场景测试！

文档版本: 1.0 最后更新: 2025-01-01 维护者: Claude Code + 用户协作

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Phase 2 实施文档

📋 实施概览

实施目标

🏗️ 已完成组件

1. 系统音频捕获模块 ✅

2. 悬浮字幕窗口模块 ✅

3. 双通道翻译主程序 ✅

4. 配置文件 ✅

🧪 测试脚本

1. 完整组件测试 ✅

2. 字幕窗口快速测试 ✅

📊 技术架构

系统架构图

核心特性

🚀 使用指南

前置准备

配置步骤

方案A: 立体声混音（推荐）

方案B: VB-CABLE + 监听

运行程序

📝 配置参考

完整配置示例

🐛 常见问题

1. 找不到立体声混音

2. 字幕窗口不显示

3. 音频有回声

4. Channel 2 无法接收音频

📊 性能指标

目标指标

待验证功能

📚 下一步计划

Phase 2.1: 优化和完善

Phase 3: GUI 控制面板

Phase 4: 扬声器模式

🎉 总结

FilesExpand file tree

PHASE2_IMPLEMENTATION.md

Latest commit

History

PHASE2_IMPLEMENTATION.md

File metadata and controls

Phase 2 实施文档

📋 实施概览

实施目标

🏗️ 已完成组件

1. 系统音频捕获模块 ✅

2. 悬浮字幕窗口模块 ✅

3. 双通道翻译主程序 ✅

4. 配置文件 ✅

🧪 测试脚本

1. 完整组件测试 ✅

2. 字幕窗口快速测试 ✅

📊 技术架构

系统架构图

核心特性

🚀 使用指南

前置准备

配置步骤

方案A: 立体声混音（推荐）

方案B: VB-CABLE + 监听

运行程序

📝 配置参考

完整配置示例

🐛 常见问题

1. 找不到立体声混音

2. 字幕窗口不显示

3. 音频有回声

4. Channel 2 无法接收音频

📊 性能指标

目标指标

待验证功能

📚 下一步计划

Phase 2.1: 优化和完善

Phase 3: GUI 控制面板

Phase 4: 扬声器模式

🎉 总结