## 目录

- Windows: `bridges/windows/bridge_windows.py`
- macOS: `bridges/macos/bridge_macos.py`
- 依赖：`bridges/requirements.txt`

## 公共能力

两套桥接程序都实现：

- `GET /health`
- `POST /process-audio`（兼容 `docs/ai-bridge-api.md`）

请求中的 `audioBase64`（来自 ESP32 上传）会被解码为 PCM16。桥接程序尝试采集电脑系统输出（loopback）并返回 `audioBase64`。
如果系统 loopback 采集失败，则回退为“原音回声”返回，保证链路不中断。

## 1) Windows 桥接程序

### 运行依赖

- Python 3.10+
- `ffmpeg` 与 `ffplay`（加入 PATH）
- 推荐使用 dshow 的 `virtual-audio-capturer` 作为系统回采设备

### 安装与启动

```bash
cd bridges
pip install -r requirements.txt
uvicorn windows.bridge_windows:app --host 0.0.0.0 --port 9091
```

### 环境变量

- `WINDOWS_LOOPBACK_DEVICE`：默认 `virtual-audio-capturer`
- `RESPONSE_CAPTURE_MS`：默认 `350`
- `PLAY_INPUT_AUDIO`：默认 `0`（设为 `1` 时会先本地播放输入音频）
- `FFMPEG_BIN`、`FFPLAY_BIN`：可覆盖可执行路径

## 2) macOS 桥接程序

### 运行依赖

- Python 3.10+
- `ffmpeg` 与 `ffplay`（建议 `brew install ffmpeg`）
- 建议安装 BlackHole 或 Loopback 作为虚拟声卡

### 安装与启动

```bash
cd bridges
pip install -r requirements.txt
uvicorn macos.bridge_macos:app --host 0.0.0.0 --port 9092
```

### 环境变量

- `MACOS_AVFOUNDATION_INPUT`：默认 `:0`（请改为你的虚拟回采输入）
- `RESPONSE_CAPTURE_MS`：默认 `350`
- `PLAY_INPUT_AUDIO`：默认 `0`
- `FFMPEG_BIN`、`FFPLAY_BIN`：可覆盖可执行路径

## 3) 服务端接入

你的主服务端通过 `AI_BRIDGE_ENDPOINT` 指向对应桥接程序：

- Windows 机器上运行时：`AI_BRIDGE_ENDPOINT=http://127.0.0.1:9091/process-audio`
- macOS 机器上运行时：`AI_BRIDGE_ENDPOINT=http://127.0.0.1:9092/process-audio`

## 4) 常见排错

- `UNSUPPORTED_CODEC`：确认上游发送 `pcm16`。
- 无声音回传：检查 loopback 设备名是否正确。
- ffmpeg 找不到设备：先执行设备枚举命令核对索引/名称：
  - Windows: `ffmpeg -list_devices true -f dshow -i dummy`
  - macOS: `ffmpeg -f avfoundation -list_devices true -i ""`