音视频通话

自定义音频采集/渲染

功能介绍

自定义音频采集/渲染用于“绕过系统默认麦克风/扬声器”,由业务侧自行提供或处理 PCM 数据:

  • 自定义音频采集:业务侧从第三方设备、采集卡或音频文件获得 PCM 数据,通过 pushCustomAudioDat 送入 SDK,由 SDK 编码后推送到房间。
  • 自定义音频渲染:业务侧通过 pullCustomAudioDat 从 SDK 拉取房间内已订阅的混音 PCM 数据,自行送入第三方播放设备或算法处理;开启后 SDK 不再向系统扬声器输出。

适用场景

  • 使用第三方音频设备/采集卡(例如 USB 声卡、专业音频链路)
  • 接入自研音频前处理(降噪/回声/混音/声纹/语音识别等)
  • 文件播报/音频注入(将文件 PCM 作为麦克风输入送入房间)
  • 自定义播放链路(将房间 PCM 送入自研播放器或硬件解码器)

相关 API

数据格式要求

  • pushCustomAudioDat 送入 SDK 的音频帧要求为:48kHz / 16bit / 单声道(MONO)PCM。
  • pullCustomAudioDat 从 SDK 拉取到的音频帧也为:48kHz / 16bit / 单声道(MONO)PCM。
  • 若你的数据格式与上述不一致(例如 44.1kHz、双声道、8bit 等),可使用 CRAudioCover 进行转换。

音频帧使用 CRAudioFrame 承载,主要字段包括 _format、_sampleRate、_channel、_timestamp、_data。

自定义音频采集

1. 开启/关闭自定义音频采集

// 开启自定义音频采集(由 pushCustomAudioDat 送入 PCM)
CRVSDK_ERR_DEF errCode = g_sdkMain->getSDKMeeting().setCustomAudioCapture(true, "");

// 关闭自定义音频采集(恢复 SDK 默认从系统麦克风采集)
CRVSDK_ERR_DEF errCode2 = g_sdkMain->getSDKMeeting().setCustomAudioCapture(false, "");

如果希望 SDK 自动从网络摄像头(IPCam)获取音频,可使用 param 扩展参数(JSON):

// 示例:从视频设备 ID=3 获取音频(此时无需再调用 pushCustomAudioDat)
const char* param = R"({"fromIPCam":3})";
CRVSDK_ERR_DEF errCode = g_sdkMain->getSDKMeeting().setCustomAudioCapture(true, param);

注意:从 IPCam 获取时,请确保对应摄像头已被打开,否则将采集到静音数据。

2. 送入 PCM 数据(pushCustomAudioDat)

自定义采集本质上是“提供麦克风输入源”,通常仍需在房间内开麦后才能让他人听到(参见 openMic)。

// 业务侧准备 48kHz/16bit/mono PCM 数据(pcmPtr 指向字节数组,pcmBytes 为字节数)
const char* pcmPtr = (const char*)pcmData;
int pcmBytes = pcmLen;

CRAudioFrame frm;
frm._format = CRVSDK_AFMT_PCM16BIT;
frm._sampleRate = 48000;
frm._channel = CRVSDK_ACHL_MONO;
frm._timestamp = tsMs; // 时间戳(ms),不方便提供时可填 0
frm._data = CRByteArray(pcmPtr, pcmBytes);

CRVSDK_ERR_DEF err = g_sdkMain->getSDKMeeting().pushCustomAudioDat(frm);

建议以稳定的节奏持续送入音频帧(例如每 10ms/20ms 一帧),避免因送入不连续导致声音卡顿。

自定义音频渲染

1. 开启/关闭自定义音频渲染

// 开启自定义音频渲染(开启后 SDK 不再向系统扬声器播放)
CRVSDK_ERR_DEF errCode = g_sdkMain->getSDKMeeting().setCustomAudioPlayback(true, "");

// 关闭自定义音频渲染(恢复 SDK 默认向系统扬声器播放)
CRVSDK_ERR_DEF errCode2 = g_sdkMain->getSDKMeeting().setCustomAudioPlayback(false, "");

2. 从 SDK 拉取 PCM 并播放(pullCustomAudioDat)

开启自定义渲染后,需要 定期拉取 音频帧。SDK 内部缓冲区有限,拉取不及时可能导致前面的数据丢失。

CRAudioFrame frm;
CRVSDK_ERR_DEF errCode = g_sdkMain->getSDKMeeting().pullCustomAudioDat(frm);
if (errCode == CRVSDKERR_NOERR) {
    // frm._data 内为 48kHz/16bit/mono PCM
    // 业务侧将 frm._data 送入第三方播放设备或算法处理
}

注意事项与常见问题

  • 开关与线程:
    • setCustomAudioCapture / pushCustomAudioDat / setCustomAudioPlayback / pullCustomAudioDat 为线程安全,可在任意线程调用(更适合在音频线程中推送/拉取)。
    • openMic / closeMic 为非线程安全,只能在 SDK 主线程调用。
  • 无声音排查(采集侧):
    • 是否已进入房间并成功开麦(openMic);
    • 是否持续调用 pushCustomAudioDat 送入数据;
    • 数据格式是否为 48kHz/16bit/mono(不匹配请用 CRAudioCover 转换)。
  • 无声音排查(渲染侧):
    • 开启自定义渲染后 SDK 不再向系统扬声器出声,这是正常现象;
    • 是否以足够频率调用 pullCustomAudioDat 拉取;
    • 音频订阅模式会影响拉取到的音频内容,详见 setAudioSubscribeMode(也可参考 audioRecv.md 的订阅章节)。