音频基础功能
adjustPlaybackSignalVolume
调节所有远端用户的本地播放音量。
public abstract int adjustPlaybackSignalVolume(int volume);
如果你需要调节某个指定远端用户在本地播放的音量,建议调用 adjustUserPlaybackSignalVolume。
调用时机
该方法可以在加入频道前或加入频道后调用。
参数
- volume
- 用户的音量,取值范围为 [0,400]。
- 0:静音。
- 100:(默认)原始音量。
- 400:原始音量的四倍(将音频信号放大四倍)。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
adjustUserPlaybackSignalVolume
调节指定远端用户的播放音量。
public abstract int adjustUserPlaybackSignalVolume(int uid, int volume);
你可以调用该方法调节指定远端用户的播放音量。若需调节多个远端用户的播放音量,请分别多次调用该方法,每次针对一个远端用户。
调用时机
请在加入频道后调用该方法。
参数
- uid
- 远端用户的用户 ID。
- volume
- 用户的音量,取值范围为 [0, 400]。
- 0:静音。
- 100:(默认)原始音量。
- 400:原始音量的四倍(将音频信号放大四倍)。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
adjustUserPlaybackSignalVolumeEx
调整指定远端用户的播放音量。
public abstract int adjustUserPlaybackSignalVolumeEx(int uid, int volume, RtcConnection connection);
你可以调用此方法调整指定远端用户的播放音量。若需调整多个远端用户的播放音量,请分别多次调用此方法,每次针对一个远端用户。
适用场景
该方法适用于多频道场景。
调用时机
请在调用 joinChannelEx 后调用此方法。
参数
- uid
- 远端用户的用户 ID。
- volume
- 用户的音量,取值范围为 [0, 400]。
- 0:静音。
- 100:(默认)原始音量。
- 400:原始音量的四倍(将音频信号放大四倍)。
- connection
- 连接信息,详见 RtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
disableAudio
禁用音频模块。
public abstract int disableAudio();
音频模块默认启用。你可以调用该方法来禁用。
- enableLocalAudio:是否启用麦克风以创建本地音频流。
- muteLocalAudioStream:是否发布本地音频流。
- muteRemoteAudioStream:是否订阅并播放远端音频流。
- muteAllRemoteAudioStreams:是否订阅并播放所有远端音频流。
调用时机
该方法可以在加入频道前或加入频道后调用。离开频道后仍然有效。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
enableAudio
启用音频模块。
public abstract int enableAudio();
调用 disableAudio 方法禁用音频模块后,可以调用 enableAudio 方法重新启用。
- 调用此方法会重置整个引擎,可能导致响应时间变慢。你可以根据实际需求,使用以下方法分别控制音频模块的具体功能:
- enableLocalAudio:是否启用麦克风以创建本地音频流。
- muteLocalAudioStream:是否发布本地音频流。
- muteRemoteAudioStream:是否订阅并播放远端音频流。
- muteAllRemoteAudioStreams:是否订阅并播放所有远端音频流。
- 成功调用此方法会重置 enableLocalAudio、muteRemoteAudioStream 和 muteAllRemoteAudioStreams 的状态,请谨慎使用。
调用时机
该方法可以在加入频道前或加入频道后调用,离开频道后仍然有效。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
enableAudioVolumeIndication
启用用户音量提示上报功能。
public abstract int enableAudioVolumeIndication(int interval, int smooth, boolean reportVad);
该方法用于启用 SDK 定期向应用上报本地发送流的用户和音量瞬时值最高的最多三位远端用户的音量信息。
调用时机
该方法可以在加入频道前或加入频道后调用。
相关回调
成功调用该方法后,若频道中有用户正在发布流,SDK 会根据设置的时间间隔触发 onAudioVolumeIndication 回调。
参数
- interval
- 设置两次音量提示之间的时间间隔(毫秒):
- ≤ 0:关闭音量提示。
- > 0:两次音量提示之间的时间间隔(毫秒)。该值需大于 10,否则无法收到 onAudioVolumeIndication 回调。建议设置为大于 100。
- smooth
- 设置音量提示的灵敏度平滑系数。取值范围为 0 到 10,推荐值为 3。数值越大,提示越灵敏。
- reportVad
- true:启用本地用户的语音活动检测。启用后,onAudioVolumeIndication 回调中的
vad参数会报告本地用户的语音活动状态。 - false:(默认)关闭本地用户的语音活动检测。关闭后,onAudioVolumeIndication 回调中的
vad参数不会报告本地用户的语音活动状态,除非引擎自动检测到语音活动。
- true:启用本地用户的语音活动检测。启用后,onAudioVolumeIndication 回调中的
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
enableAudioVolumeIndicationEx
启用用户音量提示的上报功能。
public abstract int enableAudioVolumeIndicationEx(int interval, int smooth, boolean reportVad, RtcConnection connection);
该方法使 SDK 能够定期向应用上报本地发送音频流的用户和音量瞬时值最高的最多三位远端用户的音量信息。
适用场景
该方法适用于多频道场景。
调用时机
请在调用 joinChannelEx 之后调用该方法。
相关回调
如果该方法调用成功且频道中有用户发布音频流,SDK 会根据设置的时间间隔触发 onAudioVolumeIndication 回调。
参数
- interval
- 设置两次音量提示之间的时间间隔(单位为毫秒):
- ≤ 0:关闭音量提示功能。
- > 0:两次音量提示之间的时间间隔。该值需大于 10,否则无法收到 onAudioVolumeIndication 回调。建议设置为大于 100。
- smooth
- 设置音量提示的灵敏度平滑系数,取值范围为 [0, 10],推荐值为 3。数值越大,提示越灵敏。
- reportVad
- 是否启用本地用户的语音活动检测(VAD):
- true:启用语音活动检测,onAudioVolumeIndication 回调中的
vad参数会报告本地用户的语音活动状态。 - false:(默认)关闭语音活动检测,
vad参数不会报告本地用户的语音活动状态,除非引擎自动检测到语音活动。
- true:启用语音活动检测,onAudioVolumeIndication 回调中的
- connection
- 连接信息,详见 RtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
setAudioProfile [1/2]
设置音频配置和音频场景。
public abstract int setAudioProfile(int profile, int scenario);
setAudioProfile(int profile) 设置音频配置,使用 setAudioScenario(int scenario) 设置音频场景。适用场景
该方法适用于多种音频场景,你可以根据实际需求进行选择。例如,在对音质要求较高的场景(如音乐教学)中,建议将 profile 设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4),将 scenario 设置为 AUDIO_SCENARIO_GAME_STREAMING(3)。你可以在加入频道前或加入频道后调用该方法。
调用时机
你可以在加入频道前或后调用该方法。
参数
- profile
- 音频配置,包括采样率、码率、编码模式和声道数,详见
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
- 音频场景,不同场景下设备使用不同的音量类型,详见
scenario:AUDIO_SCENARIO_DEFAULT(0):默认自动场景,SDK 会根据用户角色和音频路由选择合适的音频质量。AUDIO_SCENARIO_GAME_STREAMING(3):高音质场景,适用于主要播放音乐的场景。AUDIO_SCENARIO_CHATROOM(5):聊天室场景,适用于频繁切换角色或静音/取消静音麦克风的场景。AUDIO_SCENARIO_CHORUS(7):实时合唱场景,适用于网络状况良好且对延迟要求极高的场景。使用该枚举前需调用 getAudioDeviceInfo 查看音频设备是否支持超低延迟采集和播放。若要体验超低延迟,需确保音频设备支持超低延迟(isLowLatencyAudioSupported= true)。AUDIO_SCENARIO_MEETING(8):会议场景,以人声为主。AUDIO_SCENARIO_AI_CLIENT(10):AI 对话场景,仅适用于用户与由Conversational AI Engine创建的对话式智能体交互的场景。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
setAudioProfile [2/2]
设置音频配置文件。
public abstract int setAudioProfile(int profile);
如果你需要设置音频场景,可以调用 setAudioScenario 方法,或调用 create 并在 RtcEngineConfig 中设置 mAudioScenario。
适用场景
你可以根据实际需求选择合适的音频配置文件。例如,在音乐教学等对音质要求较高的场景中,建议将 profile 设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)。如果你需要设置音频场景,可以调用 setAudioScenario,或者调用 create [2/2] 并在 RtcEngineConfig 中设置 audioScenario。
调用时机
你可以在加入频道前或加入频道后调用该方法。
参数
- 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):默认自动场景,SDK 会根据用户角色和音频路由选择合适的音质。AUDIO_SCENARIO_GAME_STREAMING(3):高音质场景,适用于主要播放音乐的场景。AUDIO_SCENARIO_CHATROOM(5):聊天室场景,适用于用户频繁切换角色或静音/取消静音麦克风的场景。AUDIO_SCENARIO_CHORUS(7):实时合唱场景,适用于网络状况良好且对超低延迟有要求的场景。在使用该枚举值前,你需要调用 getAudioDeviceInfo 查看音频设备是否支持超低延迟采集和播放。若要体验超低延迟,需确保音频设备支持超低延迟(isLowLatencyAudioSupported= true)。AUDIO_SCENARIO_MEETING(8):会议场景,主要以人声为主。AUDIO_SCENARIO_AI_CLIENT(10):AI 对话场景,仅适用于用户与由Conversational AI Engine创建的对话式智能体交互的场景。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
onActiveSpeaker
最活跃远端说话人回调。
public void onActiveSpeaker(int uid)
- 如果最活跃的远端说话人始终是同一用户,SDK 只会触发一次该回调。
- 如果最活跃的远端说话人变更为其他用户,SDK 会再次触发该回调,并报告新的最活跃远端说话人的用户 ID。
触发时机
该回调在检测到最活跃的远端说话人时被触发。
参数
- uid
- 最活跃远端说话用户的用户 ID。
onAudioQuality
报告每个远端用户发送的音频流的统计信息回调。
public void onAudioQuality(int uid, int quality, short delay, short lost)
该回调每两秒触发一次,用于报告每个正在发送音频流的远端用户的音频质量。
参数
- 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):正在进行 Last-mile 网络探测。
- delay
- 从发送端到接收端的网络延迟(毫秒),包括音频采样预处理、网络传输和网络抖动缓冲造成的延迟。
- lost
- 从远端用户发送到接收端的音频数据包的丢包率(%)。
onAudioVolumeIndication
报告用户音量信息的回调。
public void onAudioVolumeIndication(AudioVolumeInfo[] speakers, int totalVolume)
默认情况下,该回调处于关闭状态。你可以通过调用 enableAudioVolumeIndication 方法开启该回调。开启后,当用户在频道中发送音频流时,SDK 会根据 enableAudioVolumeIndication 中设置的时间间隔触发该回调。SDK 会同时触发两个独立的 onAudioVolumeIndication 回调,分别报告发送音频流的本地用户和瞬时音量最高的最多三位远端用户的音量信息。
- 如果某位远端用户的音量在频道中排名前三,但停止发布音频流超过 20 秒,该回调将不再包含该用户的信息。
- 如果所有远端用户都停止发布音频流超过 20 秒,SDK 将不再触发远端用户的音量回调。
参数
- speakers
- 用户的音量信息。当该数组为空时,表示频道中没有远端用户或远端用户未发送音频流。详见 AudioVolumeInfo。
- totalVolume
- 说话者的音量,取值范围为 [0, 255]。
- 对于本地用户的回调,
totalVolume是发送音频流的本地用户的音量。 - 对于远端用户的回调,
totalVolume是瞬时音量最高的最多三位远端用户的音量总和。 - 如果调用了
startAudioMixing,则totalVolume是混音后的音量。
- 对于本地用户的回调,
onFirstLocalAudioFramePublished
本地音频首帧发布回调。
public void onFirstLocalAudioFramePublished(int elapsed)
- 本地客户端启用音频模块并成功调用
joinChannel。 - 本地客户端依次调用
muteLocalAudioStream(true)和muteLocalAudioStream(false)。 - 本地客户端依次调用 disableAudio 和 enableAudio。
- 本地客户端调用 pushExternalAudioFrame 成功将音频帧推送至 SDK。
触发时机
该回调在本地音频首帧发布时被触发。
参数
- elapsed
- 从本地用户调用
joinChannel到 SDK 触发该回调的时间间隔(毫秒)。
onFirstRemoteAudioDecoded
首帧远端音频解码完成回调。
public void onFirstRemoteAudioDecoded(int uid, int elapsed)
触发时机
- 远端用户加入频道并首次发送音频流。
- 远端用户音频从离线恢复为在线并重新发送音频流。可能的原因包括:远端用户离开频道、掉线、调用 muteLocalAudioStream 停止发送音频流,或调用 disableAudio 禁用音频。
参数
- uid
- 远端用户 ID。
- elapsed
- 从本地用户调用
joinChannel到 SDK 触发该回调的时间(毫秒)。
onFirstRemoteAudioFrame
远端用户音频首帧已接收回调。
public void onFirstRemoteAudioFrame(int uid, int elapsed) {}
触发时机
该回调在 SDK 收到来自某个远端用户的首帧音频时被触发。
参数
- uid
- 远端用户的用户 ID。
- elapsed
- 从本地用户调用
joinChannel到 SDK 触发该回调的时间(毫秒)。
onLocalAudioStateChanged
本地音频流状态发生变化回调。
public void onLocalAudioStateChanged(int state, int reason)
当本地音频流的状态发生变化时,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):本地音频启动失败。
- 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):麦克风被占用。提示用户检查是否有其他应用占用了麦克风。麦克风空闲约五秒后本地音频采集会自动恢复,也可以在麦克风空闲后尝试重新加入频道。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) {}
该回调每两秒触发一次。
触发时机
该回调每两秒触发一次。
参数
- stats
- 本地音频统计信息。详见 LocalAudioStats。
onRemoteAudioStateChanged
远端音频状态发生变化回调。
public void onRemoteAudioStateChanged(int uid, int state, int reason, int elapsed)
该回调在语音/视频通话频道中的远端用户或直播频道中的主播的音频状态发生变化时被触发,用于报告远端音频流的当前状态。
触发时机
该回调在远端用户的音频状态发生变化时被触发。
参数
- uid
- 音频状态发生变化的远端用户 ID。
- state
- 远端音频状态:
REMOTE_AUDIO_STATE_STOPPED(0):远端音频处于初始状态。SDK 在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):远端音频流解码并正常播放。SDK 在REMOTE_AUDIO_REASON_NETWORK_RECOVERY、REMOTE_AUDIO_REASON_LOCAL_UNMUTED或REMOTE_AUDIO_REASON_REMOTE_UNMUTED的情况下报告该状态。REMOTE_AUDIO_STATE_FROZEN(3):远端音频卡顿。SDK 在REMOTE_AUDIO_REASON_NETWORK_CONGESTION的情况下报告该状态。REMOTE_AUDIO_STATE_FAILED(4):远端音频启动失败。SDK 在REMOTE_AUDIO_REASON_INTERNAL的情况下报告该状态。
- reason
- 远端音频状态变化的原因:
REMOTE_AUDIO_REASON_INTERNAL(0):SDK 音频状态改变时报告该原因。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方法到 SDK 触发该回调的时间(毫秒)。
onRemoteAudioStats
报告每个远端音频流的传输层统计信息回调。
public void onRemoteAudioStats(RemoteAudioStats stats) {}
该回调每两秒触发一次。如果频道中有多个远端用户,SDK 会分别为每个用户触发该回调。
参数
- 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 方法时触发。
触发时机
该回调在远端用户调用 muteLocalAudioStream 方法停止或恢复发送音频流时被触发。
参数
- uid
- 远端用户 ID。
- muted
- 远端用户的音频流是否被静音:
- true:音频流被静音。
- false:音频流未被静音。