主题

树莓派实时变声复现 ​

本指南记录 Convbased 树莓派蓝牙通话设备的公开参考实现。在已验证的参考组合中，手机把树莓派识别为 Convbased Mic；本地用户通过 USB 耳机通话，远端收到转换后的声音。

复现边界 ​

本文公开树莓派客户端、USB 音频、PipeWire、BlueZ HFP 和系统服务的复现方法。云端推理、计费、内部端点与服务部署不在范围内。

复现需要有效的 Convbased API Key、可访问的模型和可用余额。客户端源码采用 MIT 许可证。

音频路径如下：

text
USB 耳机麦克风 -> 树莓派客户端 -> Convbased 实时服务 -> 手机通话上行
手机通话下行 -> 树莓派 -> USB 耳机播放

该参考配置只启用蓝牙通话音频链路，不配置普通媒体播放。

已验证平台 ​

以下组合于 2026-07-15 完成实机验证。其他组合需要独立记录结果。

层已验证值
计算机Raspberry Pi 4 Model B Rev 1.5
系统Debian 13，arm64
内核6.12.75+rpt-rpi-v8
Node.js / npm20.20.2 / 10.8.2
蓝牙BlueZ 5.82
音频PipeWire 1.4.2、WirePlumber 0.5.8
本地耳机USB Composite Device
手机OPPO Find X8，Android
网络有线局域网，可访问 Convbased HTTPS、WSS 与 TURN 端点

还需要稳定电源和一副同时提供录音、播放设备的 USB 耳机。参考验收使用有线网络；Pi 4 的蓝牙与 2.4 GHz Wi-Fi 共用无线资源，改用 Wi-Fi 时应另行记录网络条件与结果。

获取源码 ​

源码位于公开的 convbased-sdk 仓库。本页对应当前公开快照，复现时固定提交而不是分支名：

bash
git clone https://github.com/Convbased/convbased-sdk.git ~/convbased-sdk
cd ~/convbased-sdk
git checkout e24c99f1e44e863e4024407a026ea30336d339df
git rev-parse HEAD

复现报告必须写提交哈希；分支名会移动，不能作为证据。

安装 ​

安装脚本以已验证的 64 位 Debian 13 为参考；同代 Raspberry Pi OS 尚未纳入当前实机验证矩阵。先审阅脚本，再执行：

bash
cd ~/convbased-sdk/integrations/raspberry-pi/bluetooth-mic
less setup.sh
./setup.sh

脚本会使用 sudo 安装 ALSA、BlueZ、PipeWire、WirePlumber 和 Python D-Bus 依赖，安装 Node.js 20（缺少时），构建 SDK，并配置 systemd、udev、PipeWire 与 WirePlumber。脚本可重复执行，并保留已有凭据文件。

配置 ​

先确认 USB 麦克风的稳定 CARD= 名称：

bash
arecord -l

编辑安装脚本创建的私有配置文件：

bash
nano ~/convbased-bt/convbased-app.env
chmod 600 ~/convbased-bt/convbased-app.env

最小配置：

dotenv
OUTPUT=pipewire
PW_TARGET=convbased_out
MIC_DEVICE=plughw:CARD=Device,DEV=0
RATE=48000
PROFILE_POLL_MS=20000
WEBUI_PORT=0
API_KEY=replace_me
MODEL_ID=model_xxx

API_KEY 使用专属于该设备的 Key。MIC_DEVICE 必须与 arecord -l 一致。MODEL_ID 是控制台未绑定模型时的后备值。PROFILE_POLL_MS 必须大于零，设备才能在停止实时服务后继续接收重新开启指令。

本指南关闭本地状态页。开发时如需启用，只绑定本机并设置随机令牌：

dotenv
WEBUI_PORT=8080
WEBUI_HOST=127.0.0.1
WEBUI_TOKEN=replace_with_random_token

不要把真实凭据写入命令行、仓库、截图或工单。

启动服务 ​

bash
systemctl --user enable --now convbased-app.service
systemctl --user is-active convbased-app convbased-link convbased-btagent
sudo systemctl is-active convbased-btclass convbased-bt-recover

五项结果都应为 active。配置或凭据错误时，应用会停止重试；修正配置后手动重启：

bash
systemctl --user restart convbased-app.service

配对手机 ​

配对窗口默认开放五分钟：

bash
systemctl --user restart convbased-btagent.service

在手机上选择 Convbased Mic，启用“通话音频”或“电话”。该参考配置使用 Just Works；已验证组合未要求输入 PIN。

若手机提示 PIN 或配对密钥错误，先在手机端忽略设备，再清除树莓派上的旧记录并重试：

bash
bluetoothctl devices
bluetoothctl remove <PHONE_MAC>
systemctl --user restart convbased-btagent.service

只在可控环境中开放配对窗口。无 PIN 配对确认的是物理邻近，不是设备身份。

首次通话 ​

  1. 在 Convbased 控制台为该 API Key 选择模型，并打开“实时服务”。
  2. 等待设备连接；客户端默认每 20 秒轮询一次配置，实际同步时间还受网络与服务状态影响。
  3. 发起蜂窝通话或支持 HFP/HSP 的 VoIP 通话，选择 Convbased Mic。
  4. 对着 USB 耳机麦克风说话。USB 耳机播放本地通话声音；远端应只听到转换后的声音。

客户端在成功拉取新配置后处理变化：模型变化触发重连，参数变化发送在线更新。关闭“实时服务”后，设备在下一次成功轮询后开始断开并只保留配置轮询；实时连接清理时触发最终结算流程。

继续执行验证与排障，再把复现结果用于发布或兼容性声明。