音频基础功能
adjustUserPlaybackSignalVolume
调节本地播放的指定远端用户信号音量。
public abstract int adjustUserPlaybackSignalVolume(int uid, int volume);
你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量,则需多次调用该方法。
调用时机
该方法需要在加入频道后调用。
调用限制
无。
参数
- uid
- 远端用户 ID。
- volume
- 音量,取值范围为 [0,400]。
- 0: 静音。
- 100: (默认)原始音量。
- 400: 原始音量的 4 倍,自带溢出保护。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
adjustUserPlaybackSignalVolumeEx
调节本地播放的指定远端用户信号音量。
public abstract int adjustUserPlaybackSignalVolumeEx(
int uid, int volume, RtcConnection connection);
你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量,则需多次调用该方法。
调用时机
该方法需要在 joinChannelEx 之后调用。
调用限制
无。
参数
- uid
- 远端用户 ID。
- volume
- 音量,取值范围为 [0,400]。
- 0: 静音。
- 100: (默认)原始音量。
- 400: 原始音量的 4 倍,自带溢出保护。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
disableAudio
关闭音频模块。
public abstract int disableAudio();
音频模块默认开启,你可以调用该方法关闭音频模块。
调用时机
加入频道前后均可调用。离开频道后仍然有效。
调用限制
- enableLocalAudio:是否启动麦克风采集并创建本地音频流。
- muteLocalAudioStream:是否发布本地音频流。
- muteRemoteAudioStream:是否接收并播放远端音频流。
- muteAllRemoteAudioStreams:是否接收并播放所有远端音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
enableAudio
启用音频模块。
public abstract int enableAudio();
音频模块默认开启。如果你调用 disableAudio 关闭了音频模块,可调用该方法重新开启。
调用时机
加入频道前后均可调用。离开频道后仍然有效。
调用限制
- 调用该方法会重置整个引擎,响应时间较慢。你可以根据实际需求用以下方法来独立控制音频模块的某一项功能:
- enableLocalAudio: 是否启动麦克风采集并创建本地音频流。
- muteLocalAudioStream: 是否发布本地音频流。
- muteRemoteAudioStream: 是否接收并播放远端音频流。
- muteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。
- 在频道内调用该方法时,会重置 enableLocalAudio、muteRemoteAudioStream 和 muteAllRemoteAudioStreams 的设置,需谨慎使用。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
enableAudioVolumeIndication
启用用户音量提示。
public abstract int enableAudioVolumeIndication(int interval, int smooth, boolean reportVad);
该方法允许 SDK 定期向 App 报告本地发流用户和瞬时音量最高的远端用户(最多 3 位)的音量相关信息。
调用时机
加入频道前后均可调用。
调用限制
无。
相关回调
成功调用该方法、且频道内存在发流用户时,SDK 会按设置的时间间隔触发 onAudioVolumeIndication 回调。
参数
- interval
- 指定音量提示的时间间隔:
- ≤ 0: 禁用音量提示功能。
- > 0: 返回音量提示的间隔,单位为毫秒。建议设置到大于 100 毫秒,不得小于 10 毫秒,否则会收不到 onAudioVolumeIndication 回调。
- smooth
- 平滑系数,指定音量提示的灵敏度。取值范围为 [0,10],建议值为 3。数字越大,波动越灵敏;数字越小,波动越平滑。
- reportVad
true
:开启本地人声检测功能。开启后,onAudioVolumeIndication 回调的 vad 参数会报告是否在本地检测到人声。false
:(默认)关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外,onAudioVolumeIndication 回调的 vad 参数不会报告是否在本地检测到人声。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
enableAudioVolumeIndicationEx
启用用户音量提示。
public abstract int enableAudioVolumeIndicationEx(
int interval, int smooth, boolean reportVad, RtcConnection connection);
该方法允许 SDK 定期向 App 报告本地发流用户和瞬时音量最高的远端用户(最多 3 位)的音量相关信息。
调用时机
该方法需要在 joinChannelEx 之后调用。
调用限制
无。
相关回调
成功调用该方法、且频道内存在发流用户时,SDK 会按设置的时间间隔触发 onAudioVolumeIndication 回调。
参数
- interval
- 指定音量提示的时间间隔:
- ≤ 0: 禁用音量提示功能。
- > 0: 返回音量提示的间隔,单位为毫秒。建议设置到大于 100 毫秒,不得小于 10 毫秒,否则会收不到 onAudioVolumeIndication 回调。
- smooth
- 平滑系数,指定音量提示的灵敏度。取值范围为 [0,10],建议值为 3。数字越大,波动越灵敏;数字越小,波动越平滑。
- reportVad
true
:开启本地人声检测功能。开启后,onAudioVolumeIndication 回调的 vad 参数会报告是否在本地检测到人声。false
:(默认)关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外,onAudioVolumeIndication 回调的 vad 参数不会报告是否在本地检测到人声。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
setAudioProfile [1/2]
设置音频编码属性和音频场景。
public abstract int setAudioProfile(int profile, int scenario);
适用场景
该方法适用于各种音频场景,你可以按需选择。例如,在音乐教学等高音质需求的场景中,建议将 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)
如果你想设置音频应用场景,可以直接调用 setAudioScenario 方法进行设置,也可以调用 create [2/2] 并设置 RtcEngineConfig 结构体中的 mAudioScenario。
适用场景
该方法适用于各种音频场景,你可以按需选择。例如,在音乐教学等高音质需求的场景中,建议将 profile
设置为 MUSIC_HIGH_QUALITY
(4)。
调用时机
该方法在加入频道前后均可调用。
调用限制
无。
参数
- 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_GAME_STREAMING
(3)。
调用时机
该方法在加入频道前后均可调用。
调用限制
无。
参数
- 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: 方法调用失败。详见错误码了解详情和解决建议。
onActiveSpeaker
监测到远端最活跃用户回调。
public void onActiveSpeaker(int uid) {}
详情
成功调用 enableAudioVolumeIndication 后,SDK 会持续监测音量最大的远端用户,并统计该用户被判断为音量最大者的次数。当前时间段内,该次数累积最多的远端用户为最活跃的用户。
- 如果远端最活跃用户一直是同一位用户,则 SDK 不会再次触发 onActiveSpeaker 回调。
- 如果远端最活跃用户有变化,则 SDK 会再次触发该回调并报告新的远端最活跃用户的 uid。
参数
- uid
- 远端最活跃用户的 ID。
onAudioQuality
远端声音质量回调。
public void onAudioQuality(int uid, int quality, short delay, short lost) {}
详情
该回调描述远端用户在通话中的音频质量,针对每个远端用户/主播每 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):网络连接断开,完全无法沟通。
- QUALITY_DETECTING (8):网络质量检测进行中。
- delay
- 音频包从发送端到接收端的延迟(毫秒),包括声音采样前处理、网络传输、网络抖动缓冲引起的延迟。
- lost
- 音频包从发送端到接收端的丢包率 (%)。
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] 方法到触发该回调的时间间隔(毫秒)。
onFirstRemoteAudioDecoded
已解码远端音频首帧的回调。
public void onFirstRemoteAudioDecoded(int uid, int elapsed) {
}
详情
- 远端用户首次上线后发送音频。
- 远端用户音频离线再上线发送音频。音频离线指本地在 15 秒内没有收到音频包,可能有如下原因:
- 远端用户离开频道
- 远端用户掉线
- 远端用户调用 muteLocalAudioStream 方法停止发送音频流
- 远端用户调用 disableAudio 方法关闭音频
参数
- uid
- 远端用户 ID。
- elapsed
- 从本地用户调用 joinChannel [2/2] 直至该回调触发的延迟,单位为毫秒。
onFirstRemoteAudioFrame
onLocalAudioStateChanged
本地音频状态发生改变回调。
public void onLocalAudioStateChanged(int state, int reason) {}
详情
本地音频的状态发生改变时(包括本地麦克风采集状态和音频编码状态),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): 本地音频启动失败。
- reason
- 本地音频状态改变原因。
- LOCAL_AUDIO_STREAM_REASON_OK (0): 本地音频状态正常。
- LOCAL_AUDIO_STREAM_REASON_FAILURE (1): 本地音频出错原因不明确。建议提示用户尝试重新加入频道。
- LOCAL_AUDIO_STREAM_REASON_DEVICE_NO_PERMISSION (2): 没有权限启动本地音频采集设备。请提示用户开启权限。
- LOCAL_AUDIO_STREAM_REASON_DEVICE_BUSY (3): 本地音频采集设备已经在使用中。请提示用户检查麦克风是否被其他应用占用。麦克风空闲约 5 秒后本地音频采集会自动恢复,你也可以在麦克风空闲后尝试重新加入频道。
- LOCAL_AUDIO_STREAM_REASON_CAPTURE_FAILURE (4): 本地音频采集失败。
- LOCAL_AUDIO_STREAM_REASON_ENCODE_FAILURE (5): 本地音频编码失败。
- LOCAL_AUDIO_STREAM_REASON_INTERRUPTED (8): 本地音频采集被系统来电、智能助手、闹钟中断。如需恢复本地音频采集,请用户中止电话、智能助手、闹钟。
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) {}
详情
该回调描述远端用户通话中端到端的网络统计信息,通过音频包计算,用客观的数据,如丢包、 网络延迟等,展示当前网络状态。通话中,当用户收到远端用户/主播发送的音频数据包后 ,会每 2 秒触发一次该回调。
参数
- uid
- 用户 ID,指定是哪个用户/主播的音频包。
- delay
- 音频包从发送端到接收端的延时(毫秒)。
- lost
- 音频包从发送端到接收端的丢包率 (%)。
- rxKBitrate
- 远端音频包的接收码率(Kbps)。
onUserMuteAudio
远端用户(通信场景)/主播(直播场景)停止或恢复发送音频流回调。
public void onUserMuteAudio(int uid, boolean muted) {}
详情
该回调是由远端用户调用 muteLocalAudioStream 方法关闭或开启音频发送触发的。
参数
- uid
- 用户 ID。
- muted
- 该用户是否静音:
true
: 该用户已将音频静音。false
: 该用户取消了音频静音。