自定义音频采集和渲染

adjustCustomAudioPlayoutVolume

调节本地播放的自定义音频轨道的音量。

C++

virtual int adjustCustomAudioPlayoutVolume(track_id_t trackId, int volume) = 0;

如果你想更改本地播放的音频音量，需要再次调用该方法。

信息

请确保在调用该方法前，已通过调用 createCustomAudioTrack 创建自定义音频轨道。

参数

trackId

音频轨道 ID，设置为 createCustomAudioTrack 返回的自定义音频轨道 ID。

volume

音频源的音量，取值范围为 0 到 100。

• 0：静音。
• 100：原始音量。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

adjustCustomAudioPublishVolume

调节远端播放的自定义音频轨道的音量。

C++

virtual int adjustCustomAudioPublishVolume(track_id_t trackId, int volume) = 0;

如果你想更改远端播放的音频音量，需要再次调用该方法。

信息

请确保在调用该方法前，已通过调用 createCustomAudioTrack 创建自定义音频轨道。

参数

trackId

音频轨道 ID，设置为 createCustomAudioTrack 返回的自定义音频轨道 ID。

volume

音频源的音量，取值范围为 0 到 100。

• 0：静音。
• 100：原始音量。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

createCustomAudioTrack

创建自定义音频轨道。

C++

virtual rtc::track_id_t createCustomAudioTrack(rtc::AUDIO_TRACK_TYPE trackType, const rtc::AudioTrackConfig& config) = 0;

要发布自定义音频源，请按照以下步骤操作：

1. 调用该方法创建一个自定义音频轨道，并获取音频轨道 ID。
2. 调用 joinChannel 加入频道。在 ChannelMediaOptions 中，将 publishCustomAudioTrackId 设置为你要发布的音频轨道 ID，并将 publishCustomAudioTrack 设置为 true。
3. 调用 pushAudioFrame，并将 trackId 设置为步骤 2 中设置的音频轨道 ID，即可在频道中发布对应的自定义音频源。

调用时机

该方法需要在加入频道前调用。

参数

trackType

自定义音频轨道的类型，详见 AUDIO_TRACK_TYPE。

信息

如果该参数设置为 AUDIO_TRACK_DIRECT，则在调用 joinChannel 加入频道时，必须将 ChannelMediaOptions 中的 publishMicrophoneTrack 设置为 false，否则加入频道会失败并返回错误码 -2。

config

自定义音频轨道的配置，详见 AudioTrackConfig。

返回值

• 方法调用成功，返回音频轨道 ID，作为该音频轨道的唯一标识符。
• 方法调用失败，返回 0xffffffff。

所属接口类

• IMediaEngine

destroyCustomAudioTrack

销毁指定的音频轨道。

C++

virtual int destroyCustomAudioTrack(rtc::track_id_t trackId) = 0;

参数

trackId

createCustomAudioTrack 返回的自定义音频轨道 ID。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IMediaEngine

enableCustomAudioLocalPlayback

设置是否启用外部音频源的本地播放。

C++

virtual int enableCustomAudioLocalPlayback(track_id_t trackId, bool enabled) = 0;

调用该方法可开启外部音频源的本地播放。如需停止播放，可再次调用该方法并将 enabled 设置为 false。你可以调用 adjustCustomAudioPlayoutVolume 方法调整自定义音频轨道的本地播放音量。

信息

请确保在调用该方法前，已通过 createCustomAudioTrack 创建自定义音频轨道。

参数

trackId

音频轨道 ID，设置为 createCustomAudioTrack 返回的自定义音频轨道 ID。

enabled

是否播放外部音频源：

• true：播放外部音频源。
• false：（默认）不播放外部音频源。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

pullAudioFrame

拉取远端混音后的音频数据。

C++

virtual int pullAudioFrame(IAudioFrameObserverBase::AudioFrame* frame) = 0;

调用该方法后，App 会拉取解码并混音后的音频数据用于播放。该方法需要在加入频道后调用。在调用该方法前，请先调用 setExternalAudioSink 启用并设置外部音频渲染。

信息

pullAudioFrame 和 onPlaybackAudioFrame 回调都可用于获取远端混音后的音频数据。启用外部音频渲染（调用 setExternalAudioSink）后，App 将无法再通过 onPlaybackAudioFrame 回调获取数据。请根据实际业务需求选择使用该方法或 onPlaybackAudioFrame 回调。两者的区别如下：

• 调用 pullAudioFrame 后，App 会自动从 SDK 拉取音频数据。通过设置音频数据参数，SDK 会调整帧缓冲区，帮助 App 处理延迟，有效避免音频播放抖动。
• 注册 onPlaybackAudioFrame 回调后，SDK 会通过回调将音频数据发送给 App。若 App 处理音频帧的过程存在延迟，可能会导致音频抖动。

该方法仅用于获取远端混音后的音频数据。如果你需要获取采集、播放等不同音频处理阶段的数据，可以通过调用 registerAudioFrameObserver 注册相应的回调。

调用时机

该方法需要在加入频道后调用。

参数

frame

输出参数，指向 AudioFrame 的指针。详见 AudioFrame。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IMediaEngine

pushAudioFrame

推送外部音频帧。

C++

virtual int pushAudioFrame(IAudioFrameObserverBase::AudioFrame* frame, rtc::track_id_t trackId = 0) = 0;

调用时机

在调用该方法推送外部音频数据前，请先完成以下操作：

1. 调用 createCustomAudioTrack 创建自定义音频轨道并获取音频轨道 ID。
2. 调用 joinChannel 加入频道。在 ChannelMediaOptions 中，将 publishCustomAudioTrackId 设置为你希望发布的音频轨道 ID，并将 publishCustomAudioTrack 设置为 true。

参数

frame

外部音频帧。详见 AudioFrame。

trackId

音频轨道 ID。如果你希望发布自定义音频源，请将该参数设置为对应的自定义音频轨道 ID。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IMediaEngine

setExternalAudioSink

设置外部音频渲染器。

C++

virtual int setExternalAudioSink(bool enabled, int sampleRate, int channels) = 0;

启用外部音频渲染器后，你可以调用 pullAudioFrame 方法拉取远端音频帧，处理后使用自定义音效进行播放，适用于需要使用外部音频数据播放的场景。

信息

启用外部音频渲染器后，应用将无法从 onPlaybackAudioFrame 回调中获取任何音频数据。

调用时机

请在加入频道前调用该方法。

参数

enabled

是否启用外部音频渲染器：

• true：启用外部音频渲染器。
• false：（默认）禁用外部音频渲染器。

sampleRate

外部音频渲染器的采样率（Hz），可设置为 16000、32000、44100 或 48000。

channels

外部音频渲染器的声道数：

• 1：单声道。
• 2：双声道。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IMediaEngine

setExternalAudioSource

设置外部音频源参数。

C++

virtual int setExternalAudioSource(bool enabled, int sampleRate, int channels, bool localPlayback = false, bool publish = true) __deprecated = 0;

废弃

该方法已废弃，请改用 createCustomAudioTrack。

调用时机

在加入频道前调用该方法。

参数

enabled

是否启用外部音频源：

• true：启用外部音频源。
• false：（默认）不启用外部音频源。

sampleRate

外部音频源的采样率（Hz），可设置为 8000、16000、32000、44100 或 48000。

channels

外部音频源的声道数，可设置为 1（单声道）或 2（立体声）。

localPlayback

是否播放外部音频源：

• true：播放外部音频源。
• false：（默认）不播放外部音频源。

publish

是否向远端用户发布音频：

• true：（默认）发布音频到远端用户。
• false：不发布音频到远端用户。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IMediaEngine