自定义音频采集/渲染
功能介绍
自定义音频采集/渲染用于“绕过系统默认麦克风/扬声器”,由业务侧自行提供或处理 PCM 数据:
- 自定义音频采集:业务侧从第三方设备、采集卡或音频文件获得 PCM 数据,通过 pushCustomAudioDat 送入 SDK,由 SDK 编码后推送到房间。
- 自定义音频渲染:业务侧通过 pullCustomAudioDat 从 SDK 拉取房间内已订阅的混音 PCM 数据,自行送入第三方播放设备或算法处理;开启后 SDK 不再向系统扬声器输出。
适用场景
- 使用第三方音频设备/采集卡(例如 USB 声卡、专业音频链路)
- 接入自研音频前处理(降噪/回声/混音/声纹/语音识别等)
- 文件播报/音频注入(将文件 PCM 作为麦克风输入送入房间)
- 自定义播放链路(将房间 PCM 送入自研播放器或硬件解码器)
相关 API
- 自定义采集:
- 自定义渲染:
- 配套接口/结构体:
- openMic / closeMic
- AudioFrame
- setAudioSubscribeMode(影响自定义渲染拉取到的音频内容)
数据格式要求
- pushCustomAudioDat 送入 SDK 的音频帧要求为:48kHz / 16bit / 单声道(MONO)PCM。
- pullCustomAudioDat 从 SDK 拉取到的音频帧也为:48kHz / 16bit / 单声道(MONO)PCM。
音频帧使用 AudioFrame 承载,主要字段包括 _format、_sampleRate、_channel、_timestamp、_data。
自定义音频采集
1. 开启/关闭自定义音频采集
RTCMeeting *meeting = [RTCMeeting shareInstance];
// 开启自定义音频采集(由 pushCustomAudioDat 送入 PCM)
CRVIDEOSDK_ERR_DEF errCode = [meeting setCustomAudioCapture:YES param:@""];
// 关闭自定义音频采集(恢复 SDK 默认从系统麦克风采集)
CRVIDEOSDK_ERR_DEF errCode2 = [meeting setCustomAudioCapture:NO param:@""];
如果希望 SDK 自动从网络摄像头(IPCam)获取音频,可使用 param 扩展参数(JSON):
// 示例:从视频设备 ID=3 获取音频(此时无需再调用 pushCustomAudioDat)
RTCMeeting *meeting = [RTCMeeting shareInstance];
NSString *param = @"{\"fromIPCam\":3}";
CRVIDEOSDK_ERR_DEF errCode = [meeting setCustomAudioCapture:YES param:param];
注意:从 IPCam 获取时,请确保对应摄像头已被打开,否则将采集到静音数据。
2. 送入 PCM 数据(pushCustomAudioDat)
自定义采集本质上是“提供麦克风输入源”,通常仍需在房间内开麦后才能让他人听到(参见 openMic)。
// 业务侧准备 48kHz/16bit/mono PCM 数据(pcmPtr 指向字节数组,pcmBytes 为字节数)
RTCMeeting *meeting = [RTCMeeting shareInstance];
// PCM 数据
const void *pcmPtr = pcmData.bytes;
int pcmBytes = pcmData.length;
uint64_t tsMs = 0; // 时间戳,不方便提供时可填 0
AudioFrame *frm = [[AudioFrame alloc] init];
frm.format = AFMT_PCM16BIT; // 对应 CRVSDK_AFMT_PCM16BIT
frm.sampleRate = 48000;
frm.chLayout = ACHL_MONO; // 对应 CRVSDK_ACHL_MONO
frm.timestamp = tsMs;
frm.data = (uint8_t *)pcmPtr;
frm.datLen = pcmBytes;
// 推送自定义音频数据
CRVIDEOSDK_ERR_DEF err = [meeting pushCustomAudioDat:frm];
建议以稳定的节奏持续送入音频帧(例如每 10ms/20ms 一帧),避免因送入不连续导致声音卡顿。
自定义音频渲染
1. 开启/关闭自定义音频渲染
RTCMeeting *meeting = [RTCMeeting shareInstance];
// 开启自定义音频渲染(开启后 SDK 不再向系统扬声器播放)
CRVIDEOSDK_ERR_DEF errCode = [meeting setCustomAudioPlayback:YES param:@""];
// 关闭自定义音频渲染(恢复 SDK 默认向系统扬声器播放)
CRVIDEOSDK_ERR_DEF errCode2 = [meeting setCustomAudioPlayback:NO param:@""];
2. 从 SDK 拉取 PCM 并播放(pullCustomAudioDat)
开启自定义渲染后,需要 定期拉取 音频帧。SDK 内部缓冲区有限,拉取不及时可能导致前面的数据丢失。
RTCMeeting *meeting = [RTCMeeting shareInstance];
AudioFrame *frm = [[AudioFrame alloc] init];
// 拉取自渲染音频数据
CRVIDEOSDK_ERR_DEF errCode = [meeting pullCustomAudioDat:frm];
if (errCode == CRVSDKERR_NOERR) {
// frm._data 内为 48kHz/16bit/mono PCM
// 业务侧将 frm._data 送入第三方播放设备或算法处理
}
注意事项与常见问题
- 无声音排查(采集侧):
- 是否已进入房间并成功开麦(openMic);
- 是否持续调用 pushCustomAudioDat 送入数据;
- 无声音排查(渲染侧):
- 开启自定义渲染后 SDK 不再向系统扬声器出声,这是正常现象;
- 是否以足够频率调用 pullCustomAudioDat 拉取;
- 音频订阅模式会影响拉取到的音频内容,详见 setAudioSubscribeMode(也可参考 audioRecv.md 的订阅章节)。