如何修复macOS下使用Electron录制时蓝牙麦克风音频失真问题

问题根因 #

• 这是macOS蓝牙音频双工模式适配的典型问题：蓝牙设备默认音频播放时使用高音质的A2DP单向传输编码，当麦克风被调用时，macOS会强制将设备切换到支持双向音视频传输的HFP/HSP通话编码，两种模式的采样率、帧间隔差异极大，采集端未做适配时就会出现采样失配，产生爆音、语速异常、机械音等问题。
• 调用navigator.mediaDevices.getUserMedia接口时未指定固定音频参数，Electron内置的Chromium内核会自动匹配当前系统音频参数，模式切换瞬间参数发生跳变，采集逻辑没有动态适配就会触发异常。
• Windows系统的蓝牙驱动对模式切换的参数过渡处理更平滑，因此仅极少数Windows用户会遇到该问题。

可落地的解决思路 #

1. 应用代码适配（针对你开发的Electron录屏应用） #

• 调用getUserMedia时强制指定匹配蓝牙HFP模式的固定音频参数，避免内核动态适配出现参数跳变，参考配置如下：

const stream = await navigator.mediaDevices.getUserMedia({
  audio: {
    sampleRate: 48000, // 匹配macOS蓝牙HFP模式的通用采样率
    sampleSize: 16,
    channelCount: 1, // HFP模式下蓝牙麦克风默认是单声道，强行开启双声道会导致采样异常
    echoCancellation: true,
    noiseSuppression: true
  },
  video: true // 按需配置你的录屏相关参数
})

• 在Electron应用的权限配置文件entitlements.plist中添加com.apple.security.device.bluetooth权限，避免系统蓝牙权限请求打断音频采集流程。
• 监听音频流的onended、onmute异常事件，触发时自动重启音频采集流，做容灾处理。

2. 系统层面解决方案（可同步告知遇到问题的用户） #

• 启动录屏/会议工具前，先打开macOS「系统设置」-「声音」-「输入」，手动选择对应的蓝牙麦克风作为默认输入设备，避免使用过程中触发模式切换。
• 如果所用蓝牙设备支持自定义配置，可在厂商配套工具中强制固定HFP工作模式，避免动态切换。
• 升级macOS到13.4及以上版本，苹果在后续系统版本中修复了部分蓝牙音频模式切换的适配缺陷。

3. 排查验证方法 #

• 先用系统自带的QuickTime录屏工具测试蓝牙麦克风录制效果，如果同样出现异常，说明是系统蓝牙适配问题，优先走系统层面的解决方案。
• 如果QuickTime录制正常，说明是应用采集参数适配问题，优先调整getUserMedia的音频参数配置。

内容的提问来源于stack exchange，提问作者Damien Bertholet