自定义音频采集和渲染
adjustCustomAudioPlayoutVolume
调节自定义音频采集轨道在本地播放的音量。
Java
public abstract int adjustCustomAudioPlayoutVolume(int trackId, int volume);
详情
注意
在调用该方法前，请确保你已经调用 createCustomAudioTrack 方法创建自定义音频采集轨道。
调用该方法设置音频在本地播放的音量后，如果你想重新调整音量，你可以再次调用该方法。
参数
- trackId
- 音频轨道 ID。将该参数设置为调用 createCustomAudioTrack 方法返回的自定义音频轨道 ID。
- volume
- 自定义采集音频的播放音量，取值范围为 [0,100]。0 表示静音，100 表示原始音量。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
adjustCustomAudioPublishVolume
调节自定义音频采集轨道在远端播放的音量。
Java
public abstract int adjustCustomAudioPublishVolume(int trackId, int volume);
详情
注意
在调用该方法前，请确保你已经调用 createCustomAudioTrack 方法创建自定义音频采集轨道。
调用该方法设置音频在远端播放的音量后，如果你想重新调整音量，你可以再次调用该方法。
参数
- trackId
- 音频轨道 ID。将该参数设置为调用 createCustomAudioTrack 方法返回的自定义音频轨道 ID。
- volume
- 自定义采集音频的播放音量，取值范围为 [0,100]。0 表示静音，100 表示原始音量。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
createCustomAudioTrack
创建一个自定义音频采集轨道。
Java
public abstract int createCustomAudioTrack(
Constants.AudioTrackType trackType, AudioTrackConfig config);
详情
自从
v4.2.0
注意
该方法需要在加入频道前调用。
如需在频道中发布自定义采集音频，可参考以下步骤：
- 调用该方法创建音频轨道并获得音频轨道 ID。
- 调用 joinChannel [2/2] 加入频道时，将 ChannelMediaOptions 中的 publishCustomAudioTrackId 设置为你想要发布的音频轨道 ID，并将 publishCustomAudioTrack 设置为
true。 - 调用 pushExternalAudioFrame 将 trackId 指定为步骤 2 中指定的音频轨道 ID，即可实现在频道内发布对应的自定义音频源。
参数
- trackType
- 自定义音频轨道类型。详见 AudioTrackType。注意如指定 AUDIO_TRACK_DIRECT，则必须在调用 joinChannel [2/2] 加入频道时，将 ChannelMediaOptions 中的
publishMicrophoneTrack设为false，否则加入频道失败并返回错误码 -2. - config
- 自定义音频轨道配置。详见 AudioTrackConfig。
返回值
- 方法调用成功，返回音频轨道 ID 作为该音频轨道的唯一标识。
- 方法调用失败，返回 0xffffffff。详见错误码了解详情和解决建议。
destroyCustomAudioTrack
enableCustomAudioLocalPlayback
设置是否在本地播放外部音频源。
Java
public abstract int enableCustomAudioLocalPlayback(int trackId, boolean enabled);
详情
注意
在调用该方法前，请确保你已经调用 createCustomAudioTrack 方法创建自定义音频采集轨道。
调用该方法设置在本地播放外部采集的音频源后，如需停止本地播放，可以再次调用该方法并设置 enabled 为 false。
你可以调用 adjustCustomAudioPlayoutVolume 调节自定义音频采集轨道在本地播放的音量。
参数
- trackId
- 音频轨道 ID。将该参数设置为调用 createCustomAudioTrack 方法返回的自定义音频轨道 ID。
- enabled
- 是否在本地播放外部音频源：
true：在本地播放。false：（默认）不在本地播放。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setExternalAudioSource [1/2]
设置外部音频采集参数。
Java
public abstract int setExternalAudioSource(boolean enabled, int sampleRate, int channels);
废弃
调用时机
该方法需要在加入频道前调用。
调用限制
无。
参数
- enabled
- 是否开启使用外部音频源的功能：
true：开启外部音频源。false：（默认）关闭外部音频源。
- sampleRate
- 外部音频源的采样率 (Hz)，可设置为
8000，16000，32000，44100或48000。 - channels
- 外部音频源的声道数，可设置为
1（单声道）或2（双声道）。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
setExternalAudioSource [2/2]
设置外部音频采集参数。
Java
public abstract int setExternalAudioSource(boolean enabled, int sampleRate, int channels, boolean localPlayback, boolean publish);
废弃
调用时机
该方法需要在加入频道前调用。
调用限制
无。
参数
- enabled
- 是否开启使用外部音频源的功能：
true：开启外部音频源。false：（默认）关闭外部音频源。
- sampleRate
- 外部音频源的采样率 (Hz)，可设置为
8000，16000，32000，44100或48000。 - channels
- 外部音频源的声道数，可设置为
1（单声道）或2（双声道）。 - localPlayback
- 是否在本地播放外部音频源：
true：在本地播放。false：（默认）不在本地播放。
- publish
- 是否将音频发布到远端：
true：（默认）发布到远端。false：不发布到远端。
返回值
- 0：方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
pullPlaybackAudioFrame [1/2]
拉取远端音频数据。
Java
public abstract int pullPlaybackAudioFrame(byte[] data, int lengthInByte);
调用该方法后，App 会采取主动拉取的方式获取远端已解码和混音后的音频数据，用于音频播放。
调用限制
该方法和 onPlaybackAudioFrame 回调均可用于获取远端混音后的音频播放数据。在调用 setExternalAudioSink 开启外部音频渲染后，App 将无法从 onPlaybackAudioFrame 回调中获得数据。因此，请根据实际的业务需求在该方法和 onPlaybackAudioFrame 回调之间进行选择。二者的处理机制不同，具体区别如下：
- 调用该方法后，App 会主动拉取音频数据。通过设置音频数据，SDK 可以调整缓存，帮助 App 处理延时，从而有效避免音频播放抖动。
- 注册 onPlaybackAudioFrame 回调后，SDK 通过该回调将音频数据传输给 App。App 在处理音频帧的延迟时，可能会导致音频播放抖动。
该方法仅用于拉取远端混音后的音频播放数据，如需获取采集的原始音频数据、混音前每条拉流单独的原始音频播放数据等，可以通过调用 registerAudioFrameObserver 注册相应的回调。
参数
- data
- 待拉取的远端音频数据，数据类型为
byte[]。 - lengthInByte
- 音频数据长度，单位为字节。该参数的值由音频数据时长、setExternalAudioSink 的
sampleRate和channels参数确定。lengthInByte=sampleRate/1000 × 2 ×channels× 音频数据时长 (ms)。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
pullPlaybackAudioFrame [2/2]
拉取远端音频数据。
Java
public abstract int pullPlaybackAudioFrame(ByteBuffer data, int lengthInByte);
调用该方法后，App 会采取主动拉取的方式获取远端已解码和混音后的音频数据，用于音频播放。
调用限制
该方法和 onPlaybackAudioFrame 回调均可用于获取远端混音后的音频播放数据。在调用 setExternalAudioSink 开启外部音频渲染后，App 将无法从 onPlaybackAudioFrame 回调中获得数据。因此，请根据实际的业务需求在该方法和 onPlaybackAudioFrame 回调之间进行选择。二者的处理机制不同，具体区别如下：
- 调用该方法后，App 会主动拉取音频数据。通过设置音频数据，SDK 可以调整缓存，帮助 App 处理延时，从而有效避免音频播放抖动。
- 注册 onPlaybackAudioFrame 回调后，SDK 通过该回调将音频数据传输给 App。App 在处理音频帧的延迟时，可能会导致音频播放抖动。
该方法仅用于拉取远端混音后的音频播放数据，如需获取采集的原始音频数据、混音前每条拉流单独的原始音频播放数据等，可以通过调用 registerAudioFrameObserver 注册相应的回调。
参数
- data
- 待拉取的远端音频数据，数据类型为
ByteBuffer。 - lengthInByte
- 音频数据长度，单位为字节。该参数的值由音频数据时长、setExternalAudioSink 的
sampleRate和channels参数确定。lengthInByte=sampleRate/1000 × 2 ×channels× 音频数据时长 (ms)。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
pushExternalAudioFrame
推送外部音频数据。
Java
public abstract int pushExternalAudioFrame(byte[] data, long timestamp, int sampleRate,
int channels, Constants.BytesPerSample bytesPerSample, int trackId);
调用该方法通过音频轨道推送外部音频帧。
调用时机
调用该方法推送外部音频数据前，请先进行以下操作：
- 调用 createCustomAudioTrack 创建音频轨道并获得音频轨道 ID。
- 调用 joinChannel [2/2] 加入频道时，将 ChannelMediaOptions 中的 publishCustomAudioTrackId 设置为你想要发布的音频轨道 ID，并将 publishCustomAudioTrack 设置为
true。
调用限制
无。
参数
- data
- 外部音频数据。
- timestamp
- 外部音频帧的时间戳（毫秒）。该参数为必填。你可以使用该时间戳还原音频帧顺序；在有视频的场景中（包含使用外部视频源的场景），该参数可以帮助实现音视频同步。
- sampleRate
- 外部音频源的采样率 (Hz)，可设置为
8000，16000，32000，44100或48000。 - channels
- 外部音频源的声道数，可设置为
1（单声道）或2（双声道）。 - bytesPerSample
- 每个采样点的字节数。对于 PCM 来说，一般使用 16 bit，即两个字节。
- trackId
- 音频轨道 ID。将该参数设置为 createCustomAudioTrack 方法中返回的自定义音频轨道 ID。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
setExternalAudioSink
设置外部音频渲染。
Java
public abstract int setExternalAudioSink(boolean enabled, int sampleRate, int channels);
调用该方法开启外部音频渲染后，你可以调用 pullPlaybackAudioFrame [1/2] 拉取远端音频数据。App 可以对拉取到的原始音频数据进行处理后再渲染，获取想要的音频效果。
适用场景
该方法适用于需要自行渲染音频的场景。
调用时机
该方法需要在加入频道前调用。
调用限制
调用该方法开启外部音频渲染后，App 将无法从 onPlaybackAudioFrame 回调中获得数据。
参数
- enabled
- 设置是否开启外部音频渲染：
true：开启外部音频渲染。false：（默认）关闭外部音频渲染。
- sampleRate
- 外部音频渲染的采样率 (Hz)，可设置为 16000，32000，44100 或 48000。
- channels
- 外部音频渲染的声道数:
- 1: 单声道
- 2: 双声道
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。