自定义音频采集/渲染
功能介绍
自定义音频采集/渲染用于“绕过系统默认麦克风/扬声器”,由业务侧自行提供或处理 PCM 数据:
- 自定义音频采集:业务侧从第三方设备、采集卡或音频文件获得 PCM 数据,通过 pushCustomAudioDat 送入 SDK,由 SDK 编码后推送到房间。
- 自定义音频渲染:业务侧通过 pullCustomAudioDat 从 SDK 拉取房间内已订阅的混音 PCM 数据,自行送入第三方播放设备或算法处理;开启后 SDK 不再向系统扬声器输出。
适用场景
- 使用第三方音频设备/采集卡(例如 USB 声卡、专业音频链路)
- 接入自研音频前处理(降噪/回声/混音/声纹/语音识别等)
- 文件播报/音频注入(将文件 PCM 作为麦克风输入送入房间)
- 自定义播放链路(将房间 PCM 送入自研播放器或硬件解码器)
相关 API
- 自定义采集:
- 自定义渲染:
- 配套接口/结构体:
- openMic / closeMic
- CRAudioFrame
- CRByteArray
- CRAudioCover(PCM 重采样/声道转换)
- setAudioSubscribeMode(影响自定义渲染拉取到的音频内容)
数据格式要求
- 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 的订阅章节)。