文档中心
使用插件
Console 官网 社区 技术支持
简体中文
search-icon
文档中心  >  使用插件  >  API 参考  >  Android API Reference  >  音频处理
音频处理
Updated Time 2023/08/25 03:46

音频处理

介绍跟音频处理相关的方法和回调。

adjustAudioMixingPlayoutVolume

调节音乐文件在本地播放的音量。

public abstract int adjustAudioMixingPlayoutVolume(int volume);

详情

注意： 你需要在调用 startAudioMixing [2/2] 并收到 onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。

参数

volume
音乐文件音量。取值范围为 [0,100]，100 （默认值）为原始音量。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

adjustAudioMixingPublishVolume

调节音乐文件远端播放音量。

public abstract int adjustAudioMixingPublishVolume(int volume);

详情

该方法调节混音音乐文件在远端的播放音量大小。

注意：

你需要在调用 startAudioMixing [2/2] 并收到 onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。

参数

volume
音乐文件音量。取值范围为 [0,100]，100 （默认值）为原始音量。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

adjustCustomAudioPlayoutVolume

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

public abstract int adjustCustomAudioPlayoutVolume(int trackId, int volume);

详情

注意： 在调用该方法前，请确保你已经调用 createCustomAudioTrack 方法创建自定义音频采集轨道。

调用该方法设置音频在本地播放的音量后，如果你想重新调整音量，你可以再次调用该方法。

参数

trackId
音频轨道 ID。将该参数设置为 createCustomAudioTrack 方法中返回的自定义音频轨道 ID。
volume
自定义采集音频的播放音量，取值范围为 [0,100]。0 表示静音，100 表示原始音量。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。

adjustCustomAudioPublishVolume

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

public abstract int adjustCustomAudioPublishVolume(int trackId, int volume);

详情

注意： 在调用该方法前，请确保你已经调用 createCustomAudioTrack 方法创建自定义音频采集轨道。

调用该方法设置音频在远端播放的音量后，如果你想重新调整音量，你可以再次调用该方法。

参数

trackId
音频轨道 ID。将该参数设置为 createCustomAudioTrack 方法中返回的自定义音频轨道 ID。
volume
自定义采集音频的播放音量，取值范围为 [0,100]。0 表示静音，100 表示原始音量。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。

adjustAudioMixingVolume

调节音乐文件的播放音量。

public abstract int adjustAudioMixingVolume(int volume);

详情

该方法调节混音音乐文件在本端和远端的播放音量大小。

注意：

参数

volume
音乐文件音量范围为 0~100。100 （默认值）为原始文件音量。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

adjustPlaybackSignalVolume

调节本地播放的所有远端用户信号音量。

public abstract int adjustPlaybackSignalVolume(int volume);

详情

注意：
  • 该方法调节的是本地播放的所有远端用户混音后的音量。
  • 该方法在加入频道前后都能调用。

参数

volume
音量，取值范围为 [0,400]。
  • 0: 静音。
    注： 如果你只需将音频信号静音，声网建议你使用 muteRecordingSignal。
  • 100: （默认）原始音量。
  • 400: 原始音量的 4 倍，自带溢出保护。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

adjustRecordingSignalVolume

调节音频采集信号音量。

public abstract int adjustRecordingSignalVolume(int volume);

详情

注意：

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

参数

volume
音量，取值范围为 [0,400]。
  • 0: 静音。
    注： 如果你只需将音频信号静音，声网建议你使用 muteRecordingSignal。
  • 100: （默认）原始音量。
  • 400: 原始音量的 4 倍，自带溢出保护。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

adjustUserPlaybackSignalVolume

调节本地播放的指定远端用户信号音量。

public abstract int adjustUserPlaybackSignalVolume(int uid, int volume);

详情

你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量，则需多次调用该方法。

注意：
  • 该方法需要在加入频道后调用。
  • 该方法调节的是本地播放的指定远端用户混音后的音量。

参数

uid
远端用户 ID。
volume
音乐文件音量范围为 0~100。100 （默认值）为原始文件音量。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

configRhythmPlayer

配置虚拟节拍器。

public abstract int configRhythmPlayer(AgoraRhythmPlayerConfig config);

详情

调用 startRhythmPlayer 后，你可以调用该方法重新配置虚拟节拍器。

成功调用该方法后，SDK 会在本地触发 onRhythmPlayerStateChanged 回调，报告虚拟节拍器的状态。

注意：
  • 开启虚拟节拍器后，SDK 会从头开始播放指定的音频文件，并根据你在 AgoraRhythmPlayerConfig 中设置的 beatsPerMinute 控制每个文件的播放时长。例如，将 beatsPerMinute 设为 60，则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长，则 SDK 只播放节拍时长部分的音频。
  • 虚拟节拍器的声音默认会发布至远端，如果你不希望远端用户听到虚拟节拍器的声音，你可以将 ChannelMediaOptions 中的 publishRhythmPlayerTrack 设为 false。

参数

config
节拍器配置。详见 AgoraRhythmPlayerConfig。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

createCustomAudioTrack

创建一个自定义音频采集轨道。

public abstract int createCustomAudioTrack(
      Constants.AudioTrackType trackType, AudioTrackConfig config);

详情

自从
v4.2.0
如需在频道中发布多路自定义采集音频，可参考以下步骤：
  1. 调用该方法创建音频轨道并获得音频轨道 ID。
  2. 在每个频道的 ChannelMediaOptions 中，将 publishCustomAudioTrackId 参数设置为你想要发布的音频轨道 ID，并将 publishCustomAudioTrack 设置为 true。
  3. 调用 pushExternalAudioFrame 将 trackId 指定为步骤 2 中指定的音频轨道 ID，即可实现在多个频道中发布对应的自定义音频源。

参数

trackType
自定义音频轨道类型。详见 AudioTrackType。
注意： 如指定 AUDIO_TRACK_DIRECT，则必须在调用 joinChannel [2/2] 加入频道时，将 ChannelMediaOptions 中的 publishMicrophoneTrack 设为 false，否则加入频道失败并返回错误码 -2.
config
自定义音频轨道配置。详见 AudioTrackConfig。

返回值

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

destroyCustomAudioTrack

销毁指定的音频轨道。

public abstract int destroyCustomAudioTrack(int trackId);

详情

自从
v4.2.0

参数

trackId
调用 createCustomAudioTrack 方法返回的自定义音频轨道 ID。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

disableAudio

关闭音频模块。

public abstract int disableAudio();

详情

注意：
  • 该方法设置内部引擎为禁用状态，在频道内和频道外均可调用。离开频道后仍然有效。
  • 该方法重置整个引擎，响应时间较慢，因此声网建议使用如下方法来控制音频模块：

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

disableAudioSpectrumMonitor

关闭音频频谱监测。

public abstract int disableAudioSpectrumMonitor();

详情

调用 enableAudioSpectrumMonitor 后，如果你想关闭音频频谱监测，请调用该方法。

注意：

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

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

enableAudio

启用音频模块。

public abstract int enableAudio();

详情

启用音频模块（默认为开启状态）。

注意：
  • 该方法设置音频模块为启用状态，在频道内和频道外均可调用。在离开频道后仍然有效。
  • 调用该方法会重置整个引擎，响应时间较慢。你可以根据实际需求用以下方法来独立控制音频模块的某一项功能：
  • 在频道内调用该方法时，会重置 enableLocalAudio、muteRemoteAudioStream 和 muteAllRemoteAudioStreams 的设置，需谨慎使用。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

enableAudioQualityIndication

启用音频质量通知回调。

public abstract int enableAudioQualityIndication(boolean enabled);

详情

弃用：
从 v2.4.1 起废弃。

参数

enabled
是否启用音频质量通知回调。
  • true: 启用。
  • false: （默认）禁用。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

enableAudioSpectrumMonitor

开启音频频谱监测。

public abstract int enableAudioSpectrumMonitor(int intervalInMS);

详情

如果你想获取本地或远端用户的音频频谱数据，请注册音频频谱观测器并开启音频频谱监测。

注意：

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

参数

intervalInMS

SDK 触发 onLocalAudioSpectrum 和 onRemoteAudioSpectrum 回调的时间间隔（毫秒）。 默认值为 100 毫秒。取值不得少于 10 毫秒，否则该方法会调用失败。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。
    • -2: 参数设置错误。

enableAudioVolumeIndication

启用用户音量提示。

public abstract int enableAudioVolumeIndication(int interval, int smooth, boolean reportVad);

详情

该方法允许 SDK 定期向 app 报告本地发流用户和瞬时音量最高的远端用户（最多 3 位）的音量相关信息。启用该方法后，只要频道内有发流用户，SDK 会在加入频道后按设置的时间间隔触发 onAudioVolumeIndication 回调。

注意： 该方法在加入频道前后都能调用。

参数

interval
指定音量提示的时间间隔：
  • ≤ 0: 禁用音量提示功能。
  • > 0: 返回音量提示的间隔，单位为毫秒，最小取值为 50。
smooth
平滑系数，指定音量提示的灵敏度。取值范围为 [0,10]，建议值为 3。数字越大，波动越灵敏；数字越小，波动越平滑。
reportVad
  • true：开启本地人声检测功能。开启后，onAudioVolumeIndication 回调的 vad 参数会报告是否在本地检测到人声。
  • false：（默认）关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外，onAudioVolumeIndication 回调的 vad 参数不会报告是否在本地检测到人声。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。

enableInEarMonitoring [1/2]

开启耳返功能。

public abstract int enableInEarMonitoring(boolean enabled);

详情

该方法打开或关闭耳返功能。

注意：
  • 用户必须使用耳机（有线和蓝牙均可）才能听到耳返效果。
  • 该方法在加入频道前后都能调用。

参数

enabled
开启/关闭耳返功能:
  • true: 开启耳返功能。
  • false: （默认）关闭耳返功能。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。
    • - 8: 请确保当前的音频路由为蓝牙或耳机。

enableInEarMonitoring [2/2]

开启耳返功能。

public abstract int enableInEarMonitoring(boolean enabled, int includeAudioFilters);

详情

该方法打开或关闭耳返功能。

注意：
  • 用户必须使用耳机（有线和蓝牙均可）才能听到耳返效果。
  • 该方法在加入频道前后都能调用。

参数

enabled
开启/关闭耳返功能:
  • true: 开启耳返功能。
  • false: （默认）关闭耳返功能。
includeAudioFilters
耳返 audio filter 类型：
  • EAR_MONITORING_FILTER_NONE (1 << 0)：不在耳返中添加 audio filter。
  • EAR_MONITORING_FILTER_BUILT_IN_AUDIO_FILTERS (1 << 1): 在耳返中添加人声效果 audio filter。如果你实现了美声、音效等功能，用户可以在耳返中听到添加效果后的声音。
  • EAR_MONITORING_FILTER_NOISE_SUPPRESSION (1 <<2)：在耳返中添加降噪 audio filter。
    可使用按位或运算符 (|) 添加多个 audio filter。
    注意： 如果你将 enabled 参数设为 false，则无需设置 includeAudioFilters 参数。

返回值

  • >0: 方法调用成功。
  • < 0: 方法调用失败。
    • - 8: 请确保当前的音频路由为蓝牙或耳机。

enableLocalAudio

开关本地音频采集。

public abstract int enableLocalAudio(boolean enabled);

详情

当用户加入频道时，音频功能默认是开启的。该方法可以关闭或重新开启本地音频功能，即停止或重新开始本地音频采集。

该方法不影响接收远端音频流，enableLocalAudio(false) 适用于只听不发的用户场景。

音频功能关闭或重新开启后，会收到 onLocalAudioStateChanged 回调，并报告 LOCAL_AUDIO_STREAM_STATE_STOPPED(0) 或 LOCAL_AUDIO_STREAM_STATE_RECORDING(1)。
注意：
  • 该方法与 muteLocalAudioStream 的区别在于：
    • enableLocalAudio: 开启或关闭本地音频采集及处理。使用 enableLocalAudio 关闭或开启本地采集后，本地听远端播放会有短暂中断。
    • muteLocalAudioStream: 停止或继续发送本地音频流。
  • 该方法在加入频道前后均可调用。在加入频道前调用只能设置设备状态，在加入频道后才会立即生效。

参数

enabled
  • true: 重新开启本地音频功能，即开启本地音频采集（默认）；
  • false: 关闭本地音频功能，即停止本地音频采集。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

getAudioMixingCurrentPosition

获取音乐文件的播放进度。

public abstract int getAudioMixingCurrentPosition();

详情

该方法获取当前音乐文件播放进度，单位为毫秒。

注意：
  • 你需要在调用 startAudioMixing [2/2] 并收到 onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。
  • 如需多次调用 getAudioMixingCurrentPosition，请确保调用间隔大于 500 ms。

返回值

  • ≥ 0: 方法调用成功，返回当前音乐文件播放进度（ms）。0 表示当前音乐文件未开始播放。
  • < 0: 方法调用失败。

getAudioMixingDuration

获取音乐文件总时长。

public abstract int getAudioMixingDuration();

详情

该方法获取音乐文件总时长，单位为毫秒。

注意：

你需要在调用 startAudioMixing [2/2] 并收到 onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。

返回值

  • ≥ 0: 方法调用成功返回音乐文件时长。
  • < 0: 方法调用失败。

getAudioMixingPlayoutVolume

获取音乐文件的本地播放音量。

public abstract int getAudioMixingPlayoutVolume();

详情

该方法获取混音的音乐文件本地播放音量，方便排查音量相关问题。

注意：

你需要在调用 startAudioMixing [2/2] 并收到 onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。

返回值

  • ≥ 0: 方法调用成功则返回音量值，范围为 [0,100]。
  • < 0: 方法调用失败。

getAudioMixingPublishVolume

获取音乐文件的远端播放音量。

public abstract int getAudioMixingPublishVolume();

详情

该接口可以方便开发者排查音量相关问题。

注意： 你需要在调用 startAudioMixing [2/2] 并收到 onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。

返回值

  • ≥ 0: 方法调用成功则返回音量值，范围为 [0,100]。
  • < 0: 方法调用失败。

getAudioTrackCount

获取当前音乐文件的音轨索引。

public abstract int getAudioTrackCount();

详情

注：
  • 你需要在调用 startAudioMixing [2/2] 并收到 onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。

返回值

  • 方法调用成功时，返回当前音乐文件的音轨索引。
  • < 0: 方法调用失败。

muteRecordingSignal

是否将录音信号静音。

public abstract int muteRecordingSignal(boolean muted);

参数

muted
  • true: 静音。
  • false:（默认）原始音量。
注： 如果你已经调用 adjustRecordingSignalVolume 调节了音量，则调用该方法并设置为 true 时，SDK 会记录当前音量并将其静音。如需恢复之前的音量，再次调用该方法并设置为 false 即可。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

pauseAudioMixing

暂停播放音乐文件。

public abstract int pauseAudioMixing();

详情

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

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

pullPlaybackAudioFrame [1/2]

拉取远端音频数据。

public abstract int pullPlaybackAudioFrame(byte[] data, int lengthInByte);

详情

使用该方法前，你需要调用 setExternalAudioSink 通知 app 开启并设置外部渲染。

调用该方法后，app 会采取主动拉取的方式获取远端已解码和混音后的音频数据，用于音频播放。

注意：
  • 该方法仅支持拉取自采集的数据。如果你需要拉取 SDK 采集的数据，请不要调用该方法。
  • 该方法需要在加入频道后调用。
  • 开启外部音频渲染后，app 将无法从 onPlaybackAudioFrame 回调中获得数据。
  • 该方法和 onPlaybackAudioFrame 回调相比，区别在于：
    • SDK 通过 onPlaybackAudioFrame 回调将音频数据传输给 app。如果 app 处理延时，可能会导致音频播放抖动。
    • 调用该方法后 app 会主动拉取音频数据。通过设置音频数据，SDK 可以调整缓存，帮助 app 处理延时，从而有效避免音频播放抖动。

参数

data
待拉取的远端音频数据，数据类型为 byte[]。
lengthInByte
音频数据长度，单位为字节。该参数的值由音频数据时长、setExternalAudioSink 的 sampleRate 和 channels 参数确定。lengthInByte = sampleRate/1000 × 2 × channels × 音频数据时长 (ms)。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。

pullPlaybackAudioFrame [2/2]

拉取远端音频数据。

public abstract int pullPlaybackAudioFrame(ByteBuffer data, int lengthInByte);

详情

使用该方法前，你需要调用 setExternalAudioSink(enabled: true) 通知 app 开启并设置外部渲染。

调用该方法后，app 会采取主动拉取的方式获取远端已解码和混音后的音频数据，用于音频播放。

注意：
  • 该方法需要在加入频道后调用。
  • 该方法和 onPlaybackAudioFrame 回调相比，区别在于：
    • onPlaybackAudioFrame：SDK 通过该回调将音频数据传输给 app。如果 app 处理延时，可能会导致音频播放抖动。
    • pullPlaybackAudioFrame [1/2]：App 主动拉取音频数据。通过设置音频数据，SDK 可以调整缓存，帮助 app 处理延时，从而有效避免音频播放抖动。

参数

data
待拉取的远端音频数据，数据类型为 ByteBuffer。
lengthInByte
远端音频数据长度，单位为字节。 该参数的值由音频数据时长、setExternalAudioSink 的 sampleRate 和 channels 参数确定。lengthInByte = sampleRate/1000 × 2 × channels × 音频数据时长 (ms)。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。

pushExternalAudioFrame

推送外部音频数据。

public abstract int pushExternalAudioFrame(byte[] data, long timestamp, int sampleRate,
      int channels, Constants.BytesPerSample bytesPerSample, int trackId);

详情

注意：

调用该方法前，请将 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：方法调用失败。

resumeAudioMixing

恢复播放音乐文件。

public abstract int resumeAudioMixing();

详情

该方法恢复混音，继续播放音乐文件。请在频道内调用该方法。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

selectAudioTrack

指定当前音乐文件的播放音轨。

 public abstract int selectAudioTrack(int audioIndex);

详情

获取音乐文件的音轨数量后，你可以调用该方法指定任一音轨进行播放。例如，如果一个多音轨文件的不同音轨存放了不同语言的歌曲，则你可以调用该方法设置音乐文件的播放语言。

注：

参数

audioIndex
指定的播放音轨。取值范围为 [0, getAudioTrackCount()]。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

setAdvancedAudioOptions

设置音频的高级选项。

public abstract int SetAdvancedAudioOptions(AdvancedAudioOptions options);

详情

如果你对音频处理有进阶需求，例如需要采集和发送立体声，可以调用该方法设置音频的高级选项。

注意： 你需要在 joinChannel [2/2]、enableAudio 和 enableLocalAudio 前调用该方法。

参数

options
音频的高级选项。详见 AdvancedAudioOptions。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

setAINSMode

设置是否开启 AI 降噪功能并设置降噪模式。

public abstract int setAINSMode(boolean enabled, int mode);

详情

自从
v4.2.0
你可以调用开方法来开启 AI 降噪功能。该功能可以在保证语音质量的前提下，智能化检测并降低周围环境中多种稳态与非稳态噪声，使人声更加清晰。 稳态噪声指在任何时间点上都具有相同频率的噪声，常见的稳态噪声有：
  • 电视机噪声
  • 空调噪声
  • 工厂机器噪声等
非稳态噪声是指随时间而快速变化的噪声，常见的非稳态噪声有：
  • 雷声
  • 爆炸声
  • 破裂声等
注： 目前暂不推荐在 Android 6.0 及以下版本的设备上开启该功能。

适用场景

在语音连麦、在线教育、在线会议等场景中，如果周围环境比较嘈杂，AI 降噪功能可以在保证语音质量的前提下，识别并降低周围的稳态噪声和非稳态噪声，提高语音质量和体验。

参数

enabled
是否开启 AI 降噪功能：
  • true：开启 AI 降噪功能。
  • false：（默认）关闭 AI 降噪功能。
mode
降噪模式：
  • 0：（默认）均衡降噪模式。如果你希望实现对噪声抑制和延时都较为均衡的降噪效果，可选择该模式。
  • 1：强降噪模式；适用于对噪声抑制性能要求较高的场景，如户外直播。该模式可以更大程度地减少噪声，但同时可能会造成语音损伤。
  • 2：低延时强降噪模式。该模式的降噪延时比弱降噪和强降噪模式大约低一半，适用于对降噪及低延时要求较高的场景，如实时合唱。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

setAudioMixingDualMonoMode

设置当前音频文件的声道模式。

public abstract int setAudioMixingDualMonoMode(Constants.AudioMixingDualMonoMode mode);

详情

在双声道音频文件中，左声道和右声道可以存储不同的音频数据。根据实际需要，你可以设置声道模式为原始模式、左声道模式、右声道模式或混合模式。例如，在 KTV 场景中，音频文件的左声道存储了伴奏，右声道存储了原唱的歌声。如果你只需听伴奏，调用该方法设置音频文件的声道模式为左声道模式；如果你需要同时听伴奏和原唱，调用该方法设置声道模式为混合模式。

注意：

参数

mode
声道模式。详见 AudioMixingDualMonoMode。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

setAudioMixingPitch

调整本地播放的音乐文件的音调。

public abstract int setAudioMixingPitch(int pitch);

详情

本地人声和播放的音乐文件混音时，调用该方法可以仅调节音乐文件的音调。

注意： 你需要在调用 startAudioMixing [2/2] 并收到 onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。

参数

pitch
按半音音阶调整本地播放的音乐文件的音调，默认值为 0，即不调整音调。取值范围为 [-12,12]，每相邻两个值的音高距离相差半音。取值的绝对值越大，音调升高或降低得越多。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

setAudioMixingPosition

设置音乐文件的播放位置。

public abstract int setAudioMixingPosition(int pos);

详情

该方法可以设置音频文件的播放位置，这样你可以根据实际情况播放文件，而非从头到尾播放整个文件。

注意： 你需要在调用 startAudioMixing [2/2] 并收到 onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。

参数

pos
整数。进度条位置，单位为毫秒。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

setAudioProfile [1/2]

设置音频编码属性和音频场景。

public abstract int setAudioProfile(int profile, int scenario);

详情

弃用：
此方法已废弃，如需设置音频编码属性，请改用 setAudioProfile [2/2]；如需设置音频场景，请改用 setAudioScenario。
注意：
  • 该方法在加入频道前后均可调用。
  • 在有高音质需求的场景（例如音乐教学场景）中，建议将 profile 设置为 MUSIC_HIGH_QUALITY(4)，scenario 设置为 AUDIO_SCENARIO_GAME_STREAMING(3)。

参数

profile
音频编码属性，包含采样率、码率、编码模式和声道数。
  • DEFAULT (0)：默认值
    • 直播场景下：48 kHz 采样率，音乐编码，单声道，编码码率最大值为 64 Kbps。
    • 通信场景下：32 kHz 采样率，语音编码，单声道，编码码率最大值为 18 Kbps。
  • SPEECH_STANDARD (1)：指定 32 kHz 采样率，语音编码，单声道，编码码率最大值为 18 Kbps。
  • MUSIC_STANDARD (2)：指定 48 kHz 采样率，音乐编码，单声道，编码码率最大值为 64 Kbps。
  • MUSIC_STANDARD_STEREO (3)：指定 48 kHz 采样率，音乐编码，双声道，编码码率最大值为 80 Kbps。
  • MUSIC_HIGH_QUALITY (4)：指定 48 kHz 采样率，音乐编码，单声道，编码码率最大值为 96 Kbps。
  • MUSIC_HIGH_QUALITY_STEREO (5)：指定 48 kHz 采样率，音乐编码，双声道，编码码率最大值为 128 Kbps。
scenario
音频场景。不同的音频场景下，设备的音量类型是不同的。
  • AUDIO_SCENARIO_DEFAULT (0): （默认）自动场景，根据用户角色和音频路由自动匹配合适的音质。
  • AUDIO_SCENARIO_GAME_STREAMING (3): 高音质场景，适用于音乐为主的场景。
  • AUDIO_SCENARIO_CHATROOM (5): 聊天室场景，适用于用户需要频繁上下麦的场景。该场景下，观众会收到申请麦克风权限的弹窗提示。
  • AUDIO_SCENARIO_CHORUS (7): 合唱场景。适用于网络条件良好，要求极低延时的实时合唱场景。
    注意： 使用该枚举前，你需要调用 getAudioDeviceInfo 获取音频设备是否支持极低延时采集和播放。只有在支持极低延时（isLowLatencyAudioSupported = true）的音频设备上，才能够体验到极低延时。
  • AUDIO_SCENARIO_MEETING (8): 会议场景，适用于人声为主的多人会议。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

setAudioProfile [2/2]

设置音频编码属性。

public synchronized int setAudioProfile(int profile)

详情

注意：
  • 该方法在加入频道前后均可调用。
  • 在有高音质需求的场景（例如音乐教学场景）中，建议将 profile 设置为 MUSIC_HIGH_QUALITY (4)。
  • 如果你想设置音频应用场景，可以直接调用 setAudioScenario 方法进行设置，也可以调用 create [2/2] 并设置 RtcEngineConfig 结构体中的 mAudioScenario。

参数

profile
音频编码属性，包含采样率、码率、编码模式和声道数。
  • DEFAULT (0)：默认值
    • 直播场景下：48 kHz 采样率，音乐编码，单声道，编码码率最大值为 64 Kbps。
    • 通信场景下：32 kHz 采样率，语音编码，单声道，编码码率最大值为 18 Kbps。
  • SPEECH_STANDARD (1)：指定 32 kHz 采样率，语音编码，单声道，编码码率最大值为 18 Kbps。
  • MUSIC_STANDARD (2)：指定 48 kHz 采样率，音乐编码，单声道，编码码率最大值为 64 Kbps。
  • MUSIC_STANDARD_STEREO (3)：指定 48 kHz 采样率，音乐编码，双声道，编码码率最大值为 80 Kbps。
  • MUSIC_HIGH_QUALITY (4)：指定 48 kHz 采样率，音乐编码，单声道，编码码率最大值为 96 Kbps。
  • MUSIC_HIGH_QUALITY_STEREO (5)：指定 48 kHz 采样率，音乐编码，双声道，编码码率最大值为 128 Kbps。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

setAudioScenario

设置音频场景。

public abstract int setAudioScenario(int scenario);

详情

注： 该方法在加入频道前后均可调用。

参数

scenario
音频场景：
  • AUDIO_SCENARIO_DEFAULT (0):（默认）自动场景，根据用户角色和音频路由自动匹配合适的音质。
  • AUDIO_SCENARIO_GAME_STREAMING (3): 高音质场景，适用于音乐为主的场景。
  • AUDIO_SCENARIO_CHATROOM (5): 聊天室场景，适用于用户需要频繁上下麦的场景。该场景下，观众会收到申请麦克风权限的弹窗提示。
  • AUDIO_SCENARIO_CHORUS(7): 合唱场景。适用于网络条件良好，要求极低延时的实时合唱场景。
    注： 使用该枚举前，你需要调用 getAudioDeviceInfo 获取音频设备是否支持极低延时采集和播放。只有在支持极低延时（isLowLatencyAudioSupported = true）的音频设备上，才能够体验到极低延时。
  • AUDIO_SCENARIO_MEETING(8): 会议场景，适用于人声为主的多人会议。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

setDefaultAudioRouteToSpeakerphone

设置默认的音频路由。

public abstract int setDefaultAudioRoutetoSpeakerphone(boolean defaultToSpeaker);

详情

注：
  • 该方法需要在加入频道前调用。如需在加入频道后切换音频路由，请调用 setEnableSpeakerphone。

手机设备一般有两个音频路由，一个是位于顶部的听筒，播放声音偏小；一个是位于底部的扬声器，播放声音偏大。设置默认的音频路由，就是在没有外接设备的前提下，设置系统使用听筒还是扬声器播放音频。

不同场景下，系统默认的音频路由也不同。具体如下：
  • 语音通话：听筒
  • 语音直播：扬声器
  • 视频通话：扬声器
  • 视频直播：扬声器

调用该 API 可以改变上述默认音频路由。成功改变音频路由后，SDK 会触发 onAudioRouteChanged 回调。

注：

当手机插入外接设备，如蓝牙设备或耳机时，系统的音频路由会发生改变。详细的路由变化规律请参考 音频路由。

参数

defaultToSpeaker
是否使用扬声器作为默认的音频路由：
  • true: 设置默认音频路由为扬声器。
  • false: 设置默认音频路由为听筒。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

setEarMonitoringAudioFrameParameters

设置耳返的音频数据格式。

public abstract int setEarMonitoringAudioFrameParameters(
    int sampleRate, int channel, int mode, int samplesPerCall);

详情

该方法用于设置 onEarMonitoringAudioFrame 回调的耳返音频数据格式。

注意：
  • 调用该方法前，你需要先调用 enableInEarMonitoring [2/2]，将 includeAudioFilters 设置为 EAR_MONITORING_FILTER_BUILT_IN_AUDIO_FILTERS 或 EAR_MONITORING_FILTER_NOISE_SUPPRESSION。
  • SDK 会通过该方法中的 samplesPerCall、sampleRate 和 channel 参数计算出采样间隔，计算公式为采样间隔 = samplesPerCall/(sampleRate × channel)。请确保采样间隔不小于 0.01 秒。SDK 会根据该采样间隔触发 onEarMonitoringAudioFrame 回调。

参数

sampleRate
onEarMonitoringAudioFrame 中报告音频的采样率 (Hz)，可设置为 8000、 16000、 32000、44100 或 48000。
channel
onEarMonitoringAudioFrame 中报告音频的声道数，可设置为 1 或 2:
  • 1: 单声道。
  • 2: 双声道。
mode
音频帧的使用模式：
  • RAW_AUDIO_FRAME_OP_MODE_READ_ONLY (0): (默认) 只读模式。例如: 若用户通过 SDK 采集数据，自己进行 RTMP 推流，则可以选择该模式。
  • RAW_AUDIO_FRAME_OP_MODE_READ_WRITE (2): 读写模式。例如：若用户自己有音效处理模块，且想要根据实际需要对数据进行前处理 (例如变声)，则可以选择该模式。
samplesPerCall
onEarMonitoringAudioFrame 中报告的音频的采样点数，如旁路推流应用中通常为 1024。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。

setEnableSpeakerphone

开启或关闭扬声器播放。

public abstract int setEnableSpeakerphone(boolean enabled);

详情

如果 SDK 默认的音频路由（见音频路由）或 setDefaultAudioRouteToSpeakerphone 的设置无法满足你的需求，你可以调用 setEnableSpeakerphone 切换当前的音频路由。成功改变音频路由后，SDK 会触发 onAudioRouteChanged 回调。

该方法只设置用户在当前频道内使用的音频路由，不会影响 SDK 默认的音频路由。如果用户离开当前频道并加入新的频道，则用户还是会使用 SDK 默认的音频路由。

注意：
  • 该方法需要在加入频道后调用。
  • 如果用户使用了蓝牙耳机、有线耳机等外接音频播放设备，则该方法的设置无效，音频只会通过外接设备播放。当有多个外接设备时，音频会通过最后一个接入的设备播放。

参数

enabled
设置是否开启扬声器播放：
  • true: 开启。音频路由为扬声器。
  • false: 关闭。音频路由为听筒。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

setExternalAudioSink

设置外部音频渲染。

public abstract int setExternalAudioSink(boolean enabled, int sampleRate, int channels);

详情

该方法适用于需要自行渲染音频的场景。开启外部音频渲染后，你可以调用 pullPlaybackAudioFrame [1/2] 拉取远端音频数据。App 可以对拉取到的原始音频数据进行处理后再渲染，获取想要的音频效果。

参数

enabled
设置是否开启外部音频渲染：
  • true：开启外部音频渲染。
  • false：（默认）关闭外部音频渲染。
sampleRate

外部音频渲染的采样率 (Hz)，可设置为 16000，32000，44100 或 48000。

channels
外部音频渲染的声道数:
  • 1: 单声道
  • 2: 双声道

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

setExternalAudioSource [1/2]

设置外部音频采集参数。

public abstract int setExternalAudioSource(boolean enabled, int sampleRate, int channels);

详情

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

请在 joinChannel [1/2] 和 startPreview [1/2] 前调用该方法。

参数

enabled
  • true: 开启使用外部音频源的功能。
  • false: （默认）关闭使用外部音频源的功能。
sampleRate
外部音频源的采样率 (Hz)，可设置为 8000，16000，32000，44100 或 48000。
channels
外部音频源的通道数，可设置为 1 或 2:
  • 1: 单声道
  • 2: 双声道

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。

setExternalAudioSource [2/2]

设置外部音频采集参数。

public abstract int setExternalAudioSource(boolean enabled, int sampleRate, int channels, boolean localPlayback, boolean publish);

详情

弃用：
该方法已废弃，请改用 createCustomAudioTrack。
注意： 请在加入频道前调用该方法。

参数

enabled
是否开启使用外部音频源的功能：
  • true：开启外部音频源。
  • false：（默认）关闭外部音频源。
sampleRate
外部音频源的采样率 (Hz)，可设置为 8000，16000，32000，44100 或 48000。
channels
外部音频源的声道数，可设置为 1（单声道）或 2（双声道）。
localPlayback
是否在本地播放外部音频源：
  • true：在本地播放。
  • false：（默认）不在本地播放。
publish
是否将音频发布到远端：
  • true：（默认）发布到远端。
  • false：不发布到远端。

返回值

  • 0：方法调用成功。
  • < 0: 方法调用失败。

setInEarMonitoringVolume

设置耳返音量。

public abstract int setInEarMonitoringVolume(int volume);

详情

注意：
  • 用户必须使用有线耳机才能听到耳返效果。
  • 该方法在加入频道前后都能调用。

参数

volume
设置耳返音量，取值范围在 [0,100]。默认值为 100。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

setMixedAudioFrameParameters

设置 onMixedAudioFrame 报告的音频数据格式。

public abstract int setMixedAudioFrameParameters(int sampleRate, int channel, int samplesPerCall);

参数

sampleRate

音频数据采样率 (Hz)，可设置为 8000、 16000、32000、 44100 或 48000。

channel

音频数据声道数，可设置为 1（单声道） 或 2（双声道）。

samplesPerCall

音频数据采样点数。旁路推流场景下通常设为 1024。

注：

SDK 会根据该方法设置的采样间隔（秒）定期触发 onMixedAudioFrame 回调。 采样间隔 = samplesPerCall/(sampleRate x channel)。请确保你的取值能满足采样间隔大于或等于 0.01 秒。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

setRouteInCommunicationMode

选择通话音量模式下的音频路由。

public abstract int setRouteInCommunicationMode(int route);

详情

自从
v4.2.2

该方法用于在通话音量模式（MODE_IN_COMMUNICATION）下，将音频路由从蓝牙耳机切换为听筒、有线耳机或扬声器。该方法调用成功后，SDK 会触发 onAudioRouteChanged 回调，报告修改后的路由。

注意： 该方法与 setEnableSpeakerphone 同时使用时可能引起冲突。声网建议你单独使用 setRouteInCommunicationMode。

参数

route
期望使用的音频路由:
  • -1：系统默认的音频路由。
  • 0：带麦克风的耳机。
  • 1：听筒。
  • 2：不带麦克风的耳机。
  • 3：设备自带的扬声器。
  • 4：（暂不支持）外接的扬声器。
  • 5：蓝牙耳机。
  • 6：USB 设备。

返回值

无实际意义。

startAudioMixing [1/2]

开始播放音乐文件。

public abstract int startAudioMixing(String filePath, boolean loopback, int cycle);

详情

弃用：
请改用 startAudioMixing [2/2]。

该方法支持将本地或在线音乐文件和麦克风采集的音频进行混音或替换。成功播放音乐文件后，本地会触发 onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) 回调。播放结束后，本地会触发 onAudioMixingStateChanged (AUDIO_MIXING_STATE_STOPPED) 回调。

注意：
  • 该方法在加入频道前后均可调用。如需多次调用 startAudioMixing [1/2]，请确保调用间隔大于 500 ms。
  • 如果本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL，则 SDK 会报告警告码 701。
  • 在 Android 平台上调用该方法时，请注意如下事项：
    • 请确保使用 Android 4.2 或以上设备，且 API Level 不低于 16。
    • 如果播放的是在线音乐文件，建议不要使用重定向地址。重定向地址在某些机型上可能无法打开。
    • 如果在模拟器上调用该方法，则请确保音乐文件在 /sdcard/ 目录下，且格式为 MP3。

参数

filePath

播放文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如 content://com.android.providers.media.documents/document/audio%203A14441。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见支持的媒体格式。

loopback
是否只在本地播放音乐文件：
  • true: 只在本地播放音乐文件，只有本地用户能听到音乐。
  • false: 将本地播放的音乐文件发布至远端，本地用户和远端用户都能听到音乐。
cycle
音乐文件的播放次数。
  • ≥ 0: 播放次数。例如，0 表示不播放；1 表示播放 1 次。
  • -1: 无限循环播放。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

startAudioMixing [2/2]

开始播放音乐文件。

public abstract int startAudioMixing(String filePath, boolean loopback, int cycle, int startPos);

详情

该方法支持将本地或在线音乐文件和麦克风采集的音频进行混音或替换。成功播放音乐文件后，本地会触发 onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) 回调。播放结束后，本地会触发 onAudioMixingStateChanged(AUDIO_MIXING_STATE_STOPPED) 回调。

该方法支持播放以 content:// 开头的 URI 文件。

注意：
  • 该方法在加入频道前后均可调用。如需多次调用 startAudioMixing [2/2]，请确保调用间隔大于 500 ms。
  • 如果本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL，则 SDK 会报告警告码 701。
  • 该方法支持的音频文件格式见 RTC SDK 支持播放哪些格式的音频文件。
  • 在 Android 平台上调用该方法时，请注意如下事项：
    • 请确保使用 Android 4.2 或以上设备，且 API Level 不低于 16。
    • 如果播放的是在线音乐文件，建议不要使用重定向地址。重定向地址在某些机型上可能无法打开。
    • 如果在模拟器上调用该方法，则请确保音乐文件在 /sdcard/ 目录下，且格式为 MP3。

参数

filePath
文件路径：
  • Android: 文件路径，需精确到文件名及后缀。支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。通过绝对路径访问本地文件可能会遇到权限问题，建议使用 URI 地址访问本地文件。例如 content://com.android.providers.media.documents/document/audio%3A14441。
loopback
是否只在本地播放音乐文件：
  • true: 只在本地播放音乐文件，只有本地用户能听到音乐。
  • false: 将本地播放的音乐文件发布至远端，本地用户和远端用户都能听到音乐。
cycle
音乐文件的播放次数。
  • ≥ 0: 播放次数。例如，0 表示不播放；1 表示播放 1 次。
  • -1: 无限循环播放。
startPos
音乐文件的播放位置，单位为毫秒。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败
    • -1: 一般性的错误（未明确归类）。
    • -2: 设置了无效的参数。
    • -3：SDK 尚未准备好：
      • 请检查是否已开启音频模块。
      • 请检查程序集完整性。
      • RtcEngine 初始化失败。请重新初始化 RtcEngine。

startAudioRecording [1/2]

开始客户端录音。

public abstract int startAudioRecording(String filePath, int quality);

详情

注意： 调用该方法时，默认的录音采样率为 32 kHz，不可修改。
SDK 支持通话过程中在客户端进行录音。该方法录制频道内所有用户的音频，并生成一个包含所有用户声音的录音文件，录音文件格式可以为:
  • .wav: 文件大，音质保真度高；
  • .aac: 文件小，有一定的音质保真度损失。

请确保 App 里指定的目录存在且可写。该接口需在 joinChannel [2/2] 之后调用。如果调用 leaveChannel [2/2] 时还在录音，录音会自动停止。

参数

filePath
录音文件在本地保存的绝对路径，需精确到文件名及格式。例如：content://com.android.providers.media.documents/document/audio%203A14441。
注意：

请确保你指定的路径存在并且可写。

quality
录音质量。
  • 0: 低音质。采样率为 32 kHz，录制 10 分钟的文件大小为 1.2 M 左右。
  • 1: 中音质。采样率为 32 kHz，录制 10 分钟的文件大小为 2 M 左右。
  • 2: 高音质。采样率为 32 kHz，录制 10 分钟的文件大小为 3.75 M 左右。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

startAudioRecording [2/2]

开始客户端录音并进行录音配置。

public abstract int startAudioRecording(AudioFileRecordingConfig config);

详情

SDK 支持通话过程中在客户端进行录音。调用该方法后，你可以录制频道内用户的音频，并得到一个录音文件。录音文件格式可以为:
  • WAV: 音质保真度较高，文件较大。例如，采样率为 32000 Hz，录音时长为 10 分钟的文件大小约为 73 M。
  • AAC: 音质保真度较低，文件较小。例如，采样率为 32000 Hz，录音音质为 AUDIO_RECORDING_QUALITY_MEDIUM，录音时长为 10 分钟的文件大小约为 2 M。

用户离开频道后，录音会自动停止。

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

参数

config
录音配置。详见 AudioRecordingConfiguration。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

startRhythmPlayer

开启虚拟节拍器。

public abstract int startRhythmPlayer(
    String sound1, String sound2, AgoraRhythmPlayerConfig config);

详情

在音乐教学、体育教学等场景中，老师通常需要使用节拍器，让学生跟着正确的节拍练习。节拍由强拍和弱拍组成，每小节的第一拍称为强拍，其余称为弱拍。

你需要在该方法中设置强拍和弱拍的文件路径、每小节的拍数、节拍速度以及是否将节拍器的声音发送至远端。

成功调用该方法后，SDK 会在本地触发 onRhythmPlayerStateChanged 回调，报告虚拟节拍器的状态。

注意：
  • 开启虚拟节拍器后，SDK 会从头开始播放指定的音频文件，并根据你在 AgoraRhythmPlayerConfig 中设置的 beatsPerMinute 控制每个文件的播放时长。例如，将 beatsPerMinute 设为 60，则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长，则 SDK 只播放节拍时长部分的音频。
  • 虚拟节拍器的声音默认会发布至远端，如果你不希望远端用户听到虚拟节拍器的声音，你可以将 ChannelMediaOptions 中的 publishRhythmPlayerTrack 设为 false。

参数

sound1
强拍文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如 content://com.android.providers.media.documents/document/audio%203A14441。支持的音频文件格式见 RTC SDK 支持播放哪些格式的音频文件。
sound2
弱拍文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如 content://com.android.providers.media.documents/document/audio%203A14441。支持的音频文件格式见 RTC SDK 支持播放哪些格式的音频文件。
config
节拍器配置。详见 AgoraRhythmPlayerConfig。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败
    • -22: 无法找到音频文件。请填写正确的 sound1 和 sound2。

stopAudioMixing

停止播放音乐文件。

public abstract int stopAudioMixing();

详情

该方法停止播放音乐文件。请在频道内调用该方法。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

stopAudioRecording

停止客户端录音。

public abstract int stopAudioRecording();

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

stopRhythmPlayer

关闭虚拟节拍器。

public abstract int stopRhythmPlayer();

详情

调用 startRhythmPlayer 后，你可以调用该方法关闭虚拟节拍器。

返回值

  • 0: 方法调用成功
  • < 0: 方法调用失败

onActiveSpeaker

监测到远端最活跃用户回调。

public void onActiveSpeaker(int uid) {}

成功调用 enableAudioVolumeIndication 后，SDK 会持续监测音量最大的远端用户，并统计该用户被判断为音量最大者的次数。当前时间段内，该次数累积最多的远端用户为最活跃的用户。

当频道内用户数量大于或等于 2 且有远端活跃用户时，SDK 会触发该回调并报告远端最活跃用户的 uid。
  • 如果远端最活跃用户一直是同一位用户，则 SDK 不会再次触发 onActiveSpeaker 回调。
  • 如果远端最活跃用户有变化，则 SDK 会再次触发该回调并报告新的远端最活跃用户的 uid。

参数

uid
远端最活跃用户的 ID。

onAudioMixingPositionChanged

音乐文件播放进度回调。

public void onAudioMixingPositionChanged(long position) {}

详情

自从
v4.2.0

当你调用 startAudioMixing [2/2] 方法播放音乐文件后，SDK 会每隔一秒触发一次该回调，报告音乐文件当前的播放进度。

参数

position
音乐文件当前的播放进度，单位为 ms。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

onAudioMixingStateChanged

音乐文件的播放状态已改变回调。

public void onAudioMixingStateChanged(int state, int reasonCode);

该回调在音乐文件播放状态发生改变时触发，并报告当前的播放状态和错误码。

参数

state
音乐文件播放状态。
  • AUDIO_MIXING_STATE_PLAYING (710): 音乐文件正常播放。
  • AUDIO_MIXING_STATE_PAUSED (711): 音乐文件暂停播放。
  • AUDIO_MIXING_STATE_STOPPED (713): 音乐文件停止播放。
  • AUDIO_MIXING_STATE_FAILED (714): 音乐文件报错。SDK 会在 reasonCode 参数中返回具体的报错原因。
reasonCode
错误码。
  • AUDIO_MIXING_REASON_OK(0): 正常。
  • AUDIO_MIXING_REASON_CAN_NOT_OPEN (701): 音乐文件打开出错。
  • AUDIO_MIXING_REASON_TOO_FREQUENT_CALL (702): 音乐文件打开太频繁。
  • AUDIO_MIXING_REASON_INTERRUPTED_EOF (703): 音乐文件播放异常中断。
  • AUDIO_MIXING_REASON_ONE_LOOP_COMPLETED(721): 音乐文件完成一次循环播放。
  • AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED(723): 音乐文件完成所有循环播放。
  • AUDIO_MIXING_REASON_STOPPED_BY_USER(724): 成功调用 pauseAudioMixing 暂停播放音乐文件。

onAudioPublishStateChanged

音频发布状态改变回调。

public void onAudioPublishStateChanged(String channel, STREAM_PUBLISH_STATE oldState,
      STREAM_PUBLISH_STATE newState, int elapseSinceLastState) {}

参数

channel
频道名。
oldState
之前的发布状态，详见 STREAM_PUBLISH_STATE。
newState
当前的发布状态，详见 STREAM_PUBLISH_STATE。
elapseSinceLastState
两次状态变化时间间隔（毫秒）。

onAudioQuality

远端声音质量回调。

public void onAudioQuality(int uid, int quality, short delay, short lost) {}
弃用：
请改用 onRemoteAudioStats。

该回调描述远端用户在通话中的音频质量，针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播，该回调每 2 秒会被触发多次。

参数

uid
用户 ID，指定是谁发的音频流。
quality
语音质量。
  • QUALITY_UNKNOWN (0)：质量未知。
  • QUALITY_EXCELLENT (1)：质量极好。
  • QUALITY_GOOD (2)：用户主观感觉和极好差不多，但码率可能略低于极好。
  • QUALITY_POOR (3)：用户主观感受有瑕疵但不影响沟通。
  • QUALITY_BAD (4)：勉强能沟通但不顺畅。
  • QUALITY_VBAD (5)：网络质量非常差，基本不能沟通。
  • QUALITY_DOWN (6)：网络连接断开，完全无法沟通。
delay
音频包从发送端到接收端的延迟（毫秒），包括声音采样前处理、网络传输、网络抖动缓冲引起的延迟。
lost
音频包从发送端到接收端的丢包率 (%)。

onAudioRouteChanged

音频路由已发生变化回调。

public void onAudioRouteChanged(int routing) {}

参数

routing
当前的音频路由：
  • AUDIO_ROUTE_DEFAULT (-1)：使用默认的音频路由。
  • AUDIO_ROUTE_HEADSET (0)：音频路由为带麦克风的耳机。
  • AUDIO_ROUTE_EARPIECE (1)：音频路由为听筒。
  • AUDIO_ROUTE_HEADSETNOMIC (2)：音频路由为不带麦克风的耳机。
  • AUDIO_ROUTE_SPEAKERPHONE (3)：音频路由为设备自带的扬声器。
  • AUDIO_ROUTE_LOUDSPEAKER (4)：（暂不支持）音频路由为外接的扬声器。
  • AUDIO_ROUTE_BLUETOOTH (5)：音频路由为蓝牙耳机。

onAudioVolumeIndication

用户音量提示回调。

public void onAudioVolumeIndication(AudioVolumeInfo[] speakers, int totalVolume) {}

该回调默认禁用，你可以通过 enableAudioVolumeIndication 开启。 开启后，只要频道内有发流用户，SDK 会在加入频道后按 enableAudioVolumeIndication 中设置的时间间隔触发 onAudioVolumeIndication 回调。每次会触发两个 onAudioVolumeIndication 回调，一个报告本地发流用户的音量相关信息，另一个报告瞬时音量最高的远端用户（最多 3 位）的音量相关信息。

注意：

启用该功能后，如果有用户将自己静音（调用了 muteLocalAudioStream），SDK 会继续报告本地用户的音量提示回调。

瞬时音量最高的远端用户静音后 20 秒，远端的音量提示回调中将不再包含该用户；如果远端所有用户都将自己静音，20 秒后 SDK 停止报告远端用户的音量提示回调。

参数

speakers
用户音量信息，详见 AudioVolumeInfo 数组。如果 speakers 为空，则表示远端用户不发流或没有远端用户。
totalVolume
混音后的总音量，取值范围为 [0,255]。
  • 在本地用户的回调中，totalVolume 为本地发流用户的音量。
  • 在远端用户的回调中，totalVolume 为瞬时音量最高的远端用户（最多 3 位）混音后的总音量。 如果用户调用了 startAudioMixing [2/2]，则 totalVolume 为音乐文件和用户声音的总音量。

onFirstLocalAudioFramePublished

已发布本地音频首帧回调。 

public void onFirstLocalAudioFramePublished(int elapsed) {}
SDK 会在以下时机触发该回调：

参数

elapsed
从调用 joinChannel [2/2] 方法到触发该回调的时间间隔（毫秒）。

onFirstRemoteAudioFrame

已接收远端音频首帧回调。

public void onFirstRemoteAudioFrame(int uid, int elapsed) {
    }
弃用：
请改用 onRemoteAudioStateChanged 。

参数

uid
发送音频帧的远端用户的用户 ID。
elapsed
从本地用户调用 joinChannel [2/2] 直至该回调触发的延迟，单位为毫秒。

onFirstRemoteAudioDecoded

已解码远端音频首帧的回调。

public void onFirstRemoteAudioDecoded(int uid, int elapsed) {
    }
弃用：
请改用 onRemoteAudioStateChanged 。
SDK 会在以下时机触发该回调：
  • 远端用户首次上线后发送音频。
  • 远端用户音频离线再上线发送音频。音频离线指本地在 15 秒内没有收到音频包，可能有如下原因：
    • 远端用户离开频道
    • 远端用户掉线
    • 远端用户调用 muteLocalAudioStream 方法停止发送音频流
    • 远端用户调用 disableAudio 方法关闭音频

参数

uid
远端用户 ID。
elapsed
从本地用户调用 joinChannel [2/2] 直至该回调触发的延迟，单位为毫秒。

onLocalAudioStateChanged

本地音频状态发生改变回调。 

public void onLocalAudioStateChanged(int state, int error) {}

本地音频的状态发生改变时（包括本地麦克风采集状态和音频编码状态），SDK 会触发该回调报告当前的本地音频状态。在本地音频出现故障时，该回调可以帮助你了解当前音频的状态以及出现故障的原因，方便你排查问题。

注意： 当状态为 LOCAL_AUDIO_STREAM_STATE_FAILED (3) 时， 你可以在 error 参数中查看返回的错误信息。

参数

state
当前的本地音频状态。
  • LOCAL_AUDIO_STREAM_STATE_STOPPED (0): 本地音频默认初始状态。
  • LOCAL_AUDIO_STREAM_STATE_RECORDING (1): 本地音频采集设备启动成功。
  • LOCAL_AUDIO_STREAM_STATE_ENCODING (2): 本地音频首帧编码成功。
  • LOCAL_AUDIO_STREAM_STATE_FAILED (3): 本地音频启动失败。
error
本地音频出错原因。
  • LOCAL_AUDIO_STREAM_ERROR_OK 0: 本地音频状态正常。
  • LOCAL_AUDIO_STREAM_ERROR_FAILURE 1: 本地音频出错原因不明确。建议提示用户尝试重新加入频道。
  • LOCAL_AUDIO_STREAM_ERROR_DEVICE_NO_PERMISSION 2: 没有权限启动本地音频采集设备。请提示用户开启权限。
  • LOCAL_AUDIO_STREAM_ERROR_DEVICE_BUSY 3: 本地音频采集设备已经在使用中。请提示用户检查麦克风是否被其他应用占用。麦克风空闲约 5 秒后本地音频采集会自动恢复，你也可以在麦克风空闲后尝试重新加入频道。
  • LOCAL_AUDIO_STREAM_ERROR_RECORD_FAILURE 4: 本地音频采集失败。
  • LOCAL_AUDIO_STREAM_ERROR_ENCODE_FAILURE 5: 本地音频编码失败。
  • LOCAL_AUDIO_STREAM_ERROR_INTERRUPTED 8: 本地音频采集被系统来电、Siri、闹钟中断。如需恢复本地音频采集，请用户中止电话、Siri、闹钟。

onRemoteAudioStateChanged

远端音频流状态发生改变回调。 

public void onRemoteAudioStateChanged(int uid, int state, int reason, int elapsed) {}

远端用户（通信场景）或主播（直播场景）的音频状态发生改变时，SDK 会触发该回调向本地用户报告当前的远端音频流状态。

注意： 频道内的用户（通信场景）或主播（直播场景）人数超过 17 人时，该回调可能不准确。

参数

uid
发生音频状态改变的远端用户 ID。
state
远端音频流状态。
  • REMOTE_AUDIO_STATE_STOPPED (0): 远端音频默认初始状态。在 REMOTE_AUDIO_REASON_LOCAL_MUTED、REMOTE_AUDIO_REASON_REMOTE_MUTED 或 REMOTE_AUDIO_REASON_REMOTE_OFFLINE 的情况下，会报告该状态。
  • REMOTE_AUDIO_STATE_STARTING (1): 本地用户已接收远端音频首包。
  • REMOTE_AUDIO_STATE_DECODING (2): 远端音频流正在解码，正常播放。在 REMOTE_VIDEO_STATE_REASON_NETWORK_RECOVERY、REMOTE_AUDIO_REASON_LOCAL_UNMUTED 或 REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED 的情况下， 会报告该状态。
  • REMOTE_AUDIO_STATE_FROZEN (3): 远端音频流卡顿。在 REMOTE_AUDIO_REASON_NETWORK_CONGESTION的情况下，会报告该状态。
  • REMOTE_AUDIO_STATE_FAILED (4): 远端音频流播放失败。在 REMOTE_VIDEO_STATE_REASON_INTERNAL 的情况下，会报告该状态。
reason
远端音频流状态改变的具体原因。
  • REMOTE_AUDIO_REASON_INTERNAL (0): 音频状态发生改变时，会报告该原因。
  • REMOTE_AUDIO_REASON_NETWORK_CONGESTION (1): 网络阻塞。
  • REMOTE_AUDIO_REASON_NETWORK_RECOVERY (2): 网络恢复正常。
  • REMOTE_AUDIO_REASON_LOCAL_MUTED (3): 本地用户停止接收远端音频流或本地用户禁用音频模块。
  • REMOTE_AUDIO_REASON_LOCAL_UNMUTED (4): 本地用户恢复接收远端音频流或本地用户启动音频模块。
  • REMOTE_AUDIO_REASON_REMOTE_MUTED (5): 远端用户停止发送音频流或远端用户禁用音频模块。
  • REMOTE_AUDIO_REASON_REMOTE_UNMUTED (6): 远端用户恢复发送音频流或远端用户启用音频模块。
  • REMOTE_AUDIO_REASON_REMOTE_OFFLINE (7): 远端用户离开频道。
elapsed
从本地用户调用 joinChannel [2/2] 方法到发生本事件经历的时间，单位为毫秒。

onRemoteAudioStats

通话中远端音频流的统计信息回调。

public void onRemoteAudioStats(RemoteAudioStats stats) {}

该回调针对每个发送音频流的远端用户/主播每 2 秒触发一次。如果远端有多个用户/主播发送音频流，该回调每 2 秒会被触发多次。

参数

stats
接收到的远端音频统计数据，详见 RemoteAudioStats。

onRemoteAudioTransportStats

通话中远端音频流传输的统计信息回调。

public void onRemoteAudioTransportStats(int uid, int delay, int lost, int rxKBitRate) {}
弃用：
请改用 onRemoteAudioStats。

该回调描述远端用户通话中端到端的网络统计信息，通过音频包计算，用客观的数据，如丢包、 网络延迟等，展示当前网络状态。通话中，当用户收到远端用户/主播发送的音频数据包后 ，会每 2 秒触发一次该回调。

参数

uid
用户 ID，指定是哪个用户/主播的音频包。
delay
音频包从发送端到接收端的延时（毫秒）。
lost
音频包从发送端到接收端的丢包率 (%)。
rxKBitrate
远端音频包的接收码率（Kbps）。

onUserMuteAudio

远端用户（通信场景）/主播（直播场景）停止或恢复发送音频流回调。 

public void onUserMuteAudio(int uid, boolean muted) {}

该回调是由远端用户调用 muteLocalAudioStream 方法关闭或开启音频发送触发的。

注意： 频道内的用户（通信场景）或主播（直播场景）人数超过 17 人时，该回调可能不准确。

参数

uid
用户 ID。
muted
该用户是否静音：
  • true: 该用户已将音频静音。
  • false: 该用户取消了音频静音。