音频处理
介绍跟音频处理相关的方法和回调。
adjustAudioMixingPlayoutVolume
调节音乐文件在本地播放的音量。
public abstract int adjustAudioMixingPlayoutVolume(int volume);
详情
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);
详情
调用该方法设置音频在本地播放的音量后,如果你想重新调整音量,你可以再次调用该方法。
参数
- trackId
- 音频轨道 ID。将该参数设置为 createCustomAudioTrack 方法中返回的自定义音频轨道 ID。
- volume
- 自定义采集音频的播放音量,取值范围为 [0,100]。0 表示静音,100 表示原始音量。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
adjustCustomAudioPublishVolume
调节自定义音频采集轨道在远端播放的音量。
public abstract int adjustCustomAudioPublishVolume(int trackId, int volume);
详情
调用该方法设置音频在远端播放的音量后,如果你想重新调整音量,你可以再次调用该方法。
参数
- trackId
- 音频轨道 ID。将该参数设置为 createCustomAudioTrack 方法中返回的自定义音频轨道 ID。
- volume
- 自定义采集音频的播放音量,取值范围为 [0,100]。0 表示静音,100 表示原始音量。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
adjustAudioMixingVolume
调节音乐文件的播放音量。
public abstract int adjustAudioMixingVolume(int volume);
详情
该方法调节混音音乐文件在本端和远端的播放音量大小。
- 该方法需要在 startAudioMixing [2/2] 后调用。
- 调用该方法不影响调用 playEffect [2/2] 播放音效文件的音量。
参数
- volume
- 音乐文件音量范围为 0~100。100 (默认值)为原始文件音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustPlaybackSignalVolume
调节本地播放的所有远端用户信号音量。
public abstract int adjustPlaybackSignalVolume(int volume);
详情
- 该方法调节的是本地播放的所有远端用户混音后的音量。
- 该方法在加入频道前后都能调用。
参数
- volume
-
音量,取值范围为 [0,400]。
- 0: 静音。注: 如果你只需将音频信号静音,声网建议你使用 muteRecordingSignal。
- 100: (默认)原始音量。
- 400: 原始音量的 4 倍,自带溢出保护。
- 0: 静音。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustRecordingSignalVolume
调节音频采集信号音量。
public abstract int adjustRecordingSignalVolume(int volume);
详情
该方法在加入频道前后都能调用。
参数
- volume
-
音量,取值范围为 [0,400]。
- 0: 静音。注: 如果你只需将音频信号静音,声网建议你使用 muteRecordingSignal。
- 100: (默认)原始音量。
- 400: 原始音量的 4 倍,自带溢出保护。
- 0: 静音。
返回值
- 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
- 调用该方法创建音频轨道并获得音频轨道 ID。
- 在每个频道的 ChannelMediaOptions 中,将 publishCustomAudioTrackId 参数设置为你想要发布的音频轨道 ID,并将 publishCustomAudioTrack 设置为
true
。 - 调用 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();
详情
- 该方法设置内部引擎为禁用状态,在频道内和频道外均可调用。离开频道后仍然有效。
- 该方法重置整个引擎,响应时间较慢,因此声网建议使用如下方法来控制音频模块:
- enableLocalAudio: 是否启动麦克风采集并创建本地音频流。
- muteLocalAudioStream: 是否发布本地音频流。
- muteRemoteAudioStream: 是否接收并播放远端音频流。
- muteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
disableAudioSpectrumMonitor
关闭音频频谱监测。
public abstract int disableAudioSpectrumMonitor();
详情
调用 enableAudioSpectrumMonitor 后,如果你想关闭音频频谱监测,请调用该方法。
该方法在加入频道前后均可调用。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enableAudio
启用音频模块。
public abstract int enableAudio();
详情
启用音频模块(默认为开启状态)。
- 该方法设置音频模块为启用状态,在频道内和频道外均可调用。在离开频道后仍然有效。
- 调用该方法会重置整个引擎,响应时间较慢。你可以根据实际需求用以下方法来独立控制音频模块的某一项功能:
- enableLocalAudio: 是否启动麦克风采集并创建本地音频流。
- muteLocalAudioStream: 是否发布本地音频流。
- muteRemoteAudioStream: 是否接收并播放远端音频流。
- muteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。
- 在频道内调用该方法时,会重置 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)
适用于只听不发的用户场景。
- 该方法与 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();
详情
该接口可以方便开发者排查音量相关问题。
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);
详情
获取音乐文件的音轨数量后,你可以调用该方法指定任一音轨进行播放。例如,如果一个多音轨文件的不同音轨存放了不同语言的歌曲,则你可以调用该方法设置音乐文件的播放语言。
- 该方法支持的音频文件格式见 https://docs.agora.io/cn/faq/audio_format。
- 你需要在调用 startAudioMixing [2/2] 并收到
onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING)
回调后调用该方法。
参数
- audioIndex
- 指定的播放音轨。取值范围为 [0, getAudioTrackCount()]。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAdvancedAudioOptions
设置音频的高级选项。
public abstract int SetAdvancedAudioOptions(AdvancedAudioOptions options);
详情
如果你对音频处理有进阶需求,例如需要采集和发送立体声,可以调用该方法设置音频的高级选项。
参数
- options
- 音频的高级选项。详见 AdvancedAudioOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAINSMode
设置是否开启 AI 降噪功能并设置降噪模式。
public abstract int setAINSMode(boolean enabled, int mode);
详情
- 自从
- v4.2.0
- 电视机噪声
- 空调噪声
- 工厂机器噪声等
- 雷声
- 爆炸声
- 破裂声等
适用场景
在语音连麦、在线教育、在线会议等场景中,如果周围环境比较嘈杂,AI 降噪功能可以在保证语音质量的前提下,识别并降低周围的稳态噪声和非稳态噪声,提高语音质量和体验。
参数
- enabled
- 是否开启 AI 降噪功能:
true
:开启 AI 降噪功能。false
:(默认)关闭 AI 降噪功能。
- mode
-
降噪模式:
- 0:(默认)均衡降噪模式。如果你希望实现对噪声抑制和延时都较为均衡的降噪效果,可选择该模式。
- 1:强降噪模式;适用于对噪声抑制性能要求较高的场景,如户外直播。该模式可以更大程度地减少噪声,但同时可能会造成语音损伤。
- 2:低延时强降噪模式。该模式的降噪延时比弱降噪和强降噪模式大约低一半,适用于对降噪及低延时要求较高的场景,如实时合唱。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAudioMixingDualMonoMode
设置当前音频文件的声道模式。
public abstract int setAudioMixingDualMonoMode(Constants.AudioMixingDualMonoMode mode);
详情
在双声道音频文件中,左声道和右声道可以存储不同的音频数据。根据实际需要,你可以设置声道模式为原始模式、左声道模式、右声道模式或混合模式。例如,在 KTV 场景中,音频文件的左声道存储了伴奏,右声道存储了原唱的歌声。如果你只需听伴奏,调用该方法设置音频文件的声道模式为左声道模式;如果你需要同时听伴奏和原唱,调用该方法设置声道模式为混合模式。
- 你需要在调用 startAudioMixing [2/2] 并收到
onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING)
回调后调用该方法。 - 该方法仅适用于双声道的音频文件。
参数
- mode
- 声道模式。详见 AudioMixingDualMonoMode。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioMixingPitch
调整本地播放的音乐文件的音调。
public abstract int setAudioMixingPitch(int pitch);
详情
本地人声和播放的音乐文件混音时,调用该方法可以仅调节音乐文件的音调。
onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING)
回调后调用该方法。参数
- pitch
- 按半音音阶调整本地播放的音乐文件的音调,默认值为 0,即不调整音调。取值范围为 [-12,12],每相邻两个值的音高距离相差半音。取值的绝对值越大,音调升高或降低得越多。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioMixingPosition
设置音乐文件的播放位置。
public abstract int setAudioMixingPosition(int pos);
详情
该方法可以设置音频文件的播放位置,这样你可以根据实际情况播放文件,而非从头到尾播放整个文件。
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。
- DEFAULT (0):默认值
- 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。
- DEFAULT (0):默认值
返回值
- 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 回调,报告修改后的路由。
参数
- 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
。
- Android: 文件路径,需精确到文件名及后缀。支持在线文件的 URL 地址,本地文件的 URI 地址、绝对路径或以
- 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);
详情
.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);
详情
- 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 会持续监测音量最大的远端用户,并统计该用户被判断为音量最大者的次数。当前时间段内,该次数累积最多的远端用户为最活跃的用户。
- 如果远端最活跃用户一直是同一位用户,则 SDK 不会再次触发 onActiveSpeaker 回调。
- 如果远端最活跃用户有变化,则 SDK 会再次触发该回调并报告新的远端最活跃用户的 uid。
参数
- uid
- 远端最活跃用户的 ID。
onAudioMixingFinished
本地音乐文件播放已结束回调。
public void onAudioMixingFinished() {}
- 弃用:
- 请改用 onAudioMixingStateChanged。
当调用 startAudioMixing [2/2] 播放本地音乐文件结束后,会触发该回调。如果调用 startAudioMixing [2/2] 失败,会返回错误码 WARN_AUDIO_MIXING_OPEN_ERROR。
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) {}
- 开启本地音频的情况下,调用 joinChannel [2/2] 成功加入频道后。
- 调用
muteLocalAudioStream(
,再调用true
)muteLocalAudioStream(
后。false
) - 调用 disableAudio,再调用 enableAudio 后。
- 调用 pushExternalAudioFrame 成功向 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 。
- 远端用户首次上线后发送音频。
- 远端用户音频离线再上线发送音频。音频离线指本地在 15 秒内没有收到音频包,可能有如下原因:
- 远端用户离开频道
- 远端用户掉线
- 远端用户调用 muteLocalAudioStream 方法停止发送音频流
- 远端用户调用 disableAudio 方法关闭音频
参数
- uid
- 远端用户 ID。
- elapsed
- 从本地用户调用 joinChannel [2/2] 直至该回调触发的延迟,单位为毫秒。
onLocalAudioStateChanged
本地音频状态发生改变回调。
public void onLocalAudioStateChanged(int state, int error) {}
本地音频的状态发生改变时(包括本地麦克风采集状态和音频编码状态),SDK 会触发该回调报告当前的本地音频状态。在本地音频出现故障时,该回调可以帮助你了解当前音频的状态以及出现故障的原因,方便你排查问题。
参数
- 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、闹钟。
onLocalAudioStats
通话中本地音频流的统计信息回调。
public void onLocalAudioStats(LocalAudioStats stats) {}
SDK 每 2 秒触发该回调一次。
参数
- stats
- 本地音频统计数据。详见 LocalAudioStats。
onRemoteAudioStateChanged
远端音频流状态发生改变回调。
public void onRemoteAudioStateChanged(int uid, int state, int reason, int elapsed) {}
远端用户(通信场景)或主播(直播场景)的音频状态发生改变时,SDK 会触发该回调向本地用户报告当前的远端音频流状态。
参数
- 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 方法关闭或开启音频发送触发的。
参数
- uid
- 用户 ID。
- muted
- 该用户是否静音:
true
: 该用户已将音频静音。false
: 该用户取消了音频静音。