# 音频基础功能 (/zh-CN/api-reference/rtc/android/audio/audio-basic) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## adjustPlaybackSignalVolume [#adjustplaybacksignalvolume] 调节所有远端用户的本地播放音量。 ```java public abstract int adjustPlaybackSignalVolume(int volume); ``` 如果你需要调节某个指定远端用户在本地播放的音量,建议调用 [adjustUserPlaybackSignalVolume](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengine_adjustuserplaybacksignalvolume)。 ### 调用时机 [#调用时机] 该方法可以在加入频道前或加入频道后调用。 ### 参数 [#参数] 用户的音量,取值范围为 [0,400]。 - 0:静音。 - 100:(默认)原始音量。 - 400:原始音量的四倍(将音频信号放大四倍)。 ### 返回值 [#返回值] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类] - [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) ## adjustUserPlaybackSignalVolume [#adjustuserplaybacksignalvolume] 调节指定远端用户的播放音量。 ```java public abstract int adjustUserPlaybackSignalVolume(int uid, int volume); ``` 你可以调用该方法调节指定远端用户的播放音量。若需调节多个远端用户的播放音量,请分别多次调用该方法,每次针对一个远端用户。 ### 调用时机 [#调用时机-1] 请在加入频道后调用该方法。 ### 参数 [#参数-1] 远端用户的用户 ID。 用户的音量,取值范围为 [0, 400]。 - 0:静音。 - 100:(默认)原始音量。 - 400:原始音量的四倍(将音频信号放大四倍)。 ### 返回值 [#返回值-1] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-1] - [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) ## adjustUserPlaybackSignalVolumeEx [#adjustuserplaybacksignalvolumeex] 调整指定远端用户的播放音量。 ```java public abstract int adjustUserPlaybackSignalVolumeEx(int uid, int volume, RtcConnection connection); ``` 你可以调用此方法调整指定远端用户的播放音量。若需调整多个远端用户的播放音量,请分别多次调用此方法,每次针对一个远端用户。 ### 适用场景 [#适用场景] 该方法适用于多频道场景。 ### 调用时机 [#调用时机-2] 请在调用 [joinChannelEx](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_joinchannelex) 后调用此方法。 ### 参数 [#参数-2] 远端用户的用户 ID。 用户的音量,取值范围为 [0, 400]。 - 0:静音。 - 100:(默认)原始音量。 - 400:原始音量的四倍(将音频信号放大四倍)。 连接信息,详见 [RtcConnection](/zh-CN/api-reference/rtc/android/class-rtcconnection)。 ### 返回值 [#返回值-2] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-2] - [RtcEngineEx](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineex) ## disableAudio [#disableaudio] 禁用音频模块。 ```java public abstract int disableAudio(); ``` 音频模块默认启用。你可以调用该方法来禁用。 :::note 注: 该方法会重置内部引擎,并需要一些时间生效。声网建议使用以下 API 分别控制音频模块: - [enableLocalAudio](/zh-CN/api-reference/rtc/android/audio/audio-capture#api_irtcengine_enablelocalaudio):是否启用麦克风以创建本地音频流。 - [muteLocalAudioStream](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_mutelocalaudiostream):是否发布本地音频流。 - [muteRemoteAudioStream](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_muteremoteaudiostream):是否订阅并播放远端音频流。 - [muteAllRemoteAudioStreams](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_muteallremoteaudiostreams):是否订阅并播放所有远端音频流。 ::: ### 调用时机 [#调用时机-3] 该方法可以在加入频道前或加入频道后调用。离开频道后仍然有效。 ### 返回值 [#返回值-3] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-3] - [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) ## enableAudio [#enableaudio] 启用音频模块。 ```java public abstract int enableAudio(); ``` 调用 [disableAudio](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengine_disableaudio) 方法禁用音频模块后,可以调用 [enableAudio](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengine_enableaudio) 方法重新启用。 :::note 注: - 调用此方法会重置整个引擎,可能导致响应时间变慢。你可以根据实际需求,使用以下方法分别控制音频模块的具体功能: - [enableLocalAudio](/zh-CN/api-reference/rtc/android/audio/audio-capture#api_irtcengine_enablelocalaudio):是否启用麦克风以创建本地音频流。 - [muteLocalAudioStream](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_mutelocalaudiostream):是否发布本地音频流。 - [muteRemoteAudioStream](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_muteremoteaudiostream):是否订阅并播放远端音频流。 - [muteAllRemoteAudioStreams](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_muteallremoteaudiostreams):是否订阅并播放所有远端音频流。 - 成功调用此方法会重置 [enableLocalAudio](/zh-CN/api-reference/rtc/android/audio/audio-capture#api_irtcengine_enablelocalaudio)、[muteRemoteAudioStream](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_muteremoteaudiostream) 和 [muteAllRemoteAudioStreams](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_muteallremoteaudiostreams) 的状态,请谨慎使用。 ::: ### 调用时机 [#调用时机-4] 该方法可以在加入频道前或加入频道后调用,离开频道后仍然有效。 ### 返回值 [#返回值-4] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-4] - [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) ## enableAudioVolumeIndication [#enableaudiovolumeindication] 启用用户音量提示上报功能。 ```java public abstract int enableAudioVolumeIndication(int interval, int smooth, boolean reportVad); ``` 该方法用于启用 SDK 定期向应用上报本地发送流的用户和音量瞬时值最高的最多三位远端用户的音量信息。 ### 调用时机 [#调用时机-5] 该方法可以在加入频道前或加入频道后调用。 ### 相关回调 [#相关回调] 成功调用该方法后,若频道中有用户正在发布流,SDK 会根据设置的时间间隔触发 [onAudioVolumeIndication](/zh-CN/api-reference/rtc/android/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 回调。 ### 参数 [#参数-3] 设置两次音量提示之间的时间间隔(毫秒): - ≤ 0:关闭音量提示。 - > 0:两次音量提示之间的时间间隔(毫秒)。该值需大于 10,否则无法收到 [onAudioVolumeIndication](/zh-CN/api-reference/rtc/android/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 回调。建议设置为大于 100。 设置音量提示的灵敏度平滑系数。取值范围为 0 到 10,推荐值为 3。数值越大,提示越灵敏。 - true:启用本地用户的语音活动检测。启用后,[onAudioVolumeIndication](/zh-CN/api-reference/rtc/android/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 回调中的 `vad` 参数会报告本地用户的语音活动状态。 - false:(默认)关闭本地用户的语音活动检测。关闭后,[onAudioVolumeIndication](/zh-CN/api-reference/rtc/android/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 回调中的 `vad` 参数不会报告本地用户的语音活动状态,除非引擎自动检测到语音活动。 ### 返回值 [#返回值-5] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-5] - [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) ## enableAudioVolumeIndicationEx [#enableaudiovolumeindicationex] 启用用户音量提示的上报功能。 ```java public abstract int enableAudioVolumeIndicationEx(int interval, int smooth, boolean reportVad, RtcConnection connection); ``` 该方法使 SDK 能够定期向应用上报本地发送音频流的用户和音量瞬时值最高的最多三位远端用户的音量信息。 ### 适用场景 [#适用场景-1] 该方法适用于多频道场景。 ### 调用时机 [#调用时机-6] 请在调用 [joinChannelEx](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_joinchannelex) 之后调用该方法。 ### 相关回调 [#相关回调-1] 如果该方法调用成功且频道中有用户发布音频流,SDK 会根据设置的时间间隔触发 [onAudioVolumeIndication](/zh-CN/api-reference/rtc/android/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 回调。 ### 参数 [#参数-4] 设置两次音量提示之间的时间间隔(单位为毫秒): - ≤ 0:关闭音量提示功能。 - > 0:两次音量提示之间的时间间隔。该值需大于 10,否则无法收到 [onAudioVolumeIndication](/zh-CN/api-reference/rtc/android/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 回调。建议设置为大于 100。 设置音量提示的灵敏度平滑系数,取值范围为 [0, 10],推荐值为 3。数值越大,提示越灵敏。 是否启用本地用户的语音活动检测(VAD): - true:启用语音活动检测,[onAudioVolumeIndication](/zh-CN/api-reference/rtc/android/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 回调中的 `vad` 参数会报告本地用户的语音活动状态。 - false:(默认)关闭语音活动检测,`vad` 参数不会报告本地用户的语音活动状态,除非引擎自动检测到语音活动。 连接信息,详见 [RtcConnection](/zh-CN/api-reference/rtc/android/class-rtcconnection)。 ### 返回值 [#返回值-6] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-6] - [RtcEngineEx](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineex) ## setAudioProfile [1/2] [#setaudioprofile-12] 设置音频配置和音频场景。 ```java public abstract int setAudioProfile(int profile, int scenario); ``` :::error[废弃] 该方法已废弃。请使用 `setAudioProfile(int profile)` 设置音频配置,使用 `setAudioScenario(int scenario)` 设置音频场景。 ::: ### 适用场景 [#适用场景-2] 该方法适用于多种音频场景,你可以根据实际需求进行选择。例如,在对音质要求较高的场景(如音乐教学)中,建议将 `profile` 设置为 `AUDIO_PROFILE_MUSIC_HIGH_QUALITY`(4),将 `scenario` 设置为 `AUDIO_SCENARIO_GAME_STREAMING`(3)。你可以在加入频道前或加入频道后调用该方法。 ### 调用时机 [#调用时机-7] 你可以在加入频道前或后调用该方法。 ### 参数 [#参数-5] 音频配置,包括采样率、码率、编码模式和声道数,详见 `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):默认自动场景,SDK 会根据用户角色和音频路由选择合适的音频质量。 - `AUDIO_SCENARIO_GAME_STREAMING` (3):高音质场景,适用于主要播放音乐的场景。 - `AUDIO_SCENARIO_CHATROOM` (5):聊天室场景,适用于频繁切换角色或静音/取消静音麦克风的场景。 - `AUDIO_SCENARIO_CHORUS` (7):实时合唱场景,适用于网络状况良好且对延迟要求极高的场景。使用该枚举前需调用 [getAudioDeviceInfo](/zh-CN/api-reference/rtc/android/device-management/audio-device#api_irtcengine_getaudiodeviceinfo) 查看音频设备是否支持超低延迟采集和播放。若要体验超低延迟,需确保音频设备支持超低延迟(`isLowLatencyAudioSupported` = true)。 - `AUDIO_SCENARIO_MEETING` (8):会议场景,以人声为主。 - `AUDIO_SCENARIO_AI_CLIENT` (10):AI 对话场景,仅适用于用户与由 `Conversational AI Engine` 创建的对话式智能体交互的场景。 ### 返回值 [#返回值-7] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-7] - [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) ## setAudioProfile [2/2] [#setaudioprofile-22] 设置音频配置文件。 ```java public abstract int setAudioProfile(int profile); ``` 如果你需要设置音频场景,可以调用 [setAudioScenario](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengine_setaudioscenario) 方法,或调用 [create](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_create_ilocalspatialaudioengine) 并在 [RtcEngineConfig](/zh-CN/api-reference/rtc/android/class-rtcengineconfig) 中设置 `mAudioScenario`。 ### 适用场景 [#适用场景-3] 你可以根据实际需求选择合适的音频配置文件。例如,在音乐教学等对音质要求较高的场景中,建议将 `profile` 设置为 `AUDIO_PROFILE_MUSIC_HIGH_QUALITY`(4)。如果你需要设置音频场景,可以调用 [setAudioScenario](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengine_setaudioscenario),或者调用 [create [2/2]](/zh-CN/api-reference/rtc/android/initialize#api_irtcengine_initialize) 并在 [RtcEngineConfig](/zh-CN/api-reference/rtc/android/class-rtcengineconfig) 中设置 `audioScenario`。 ### 调用时机 [#调用时机-8] 你可以在加入频道前或加入频道后调用该方法。 ### 参数 [#参数-6] 音频配置文件,包括采样率、码率、编码模式和声道数: - `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。 ### 返回值 [#返回值-8] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-8] - [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) ## setAudioScenario [#setaudioscenario] 设置音频场景。 ```java public abstract int setAudioScenario(int scenario); ``` ### 适用场景 [#适用场景-4] 该方法适用于多种音频场景。例如,在对音质要求较高的音乐教学场景中,建议将 `scenario` 设置为 `AUDIO_SCENARIO_GAME_STREAMING`(3)。 ### 调用时机 [#调用时机-9] 你可以在加入频道前或后调用该方法。 ### 参数 [#参数-7] 音频场景。在不同的音频场景下,设备使用不同的音量类型: - `AUDIO_SCENARIO_DEFAULT`(0):默认自动场景,SDK 会根据用户角色和音频路由选择合适的音质。 - `AUDIO_SCENARIO_GAME_STREAMING`(3):高音质场景,适用于主要播放音乐的场景。 - `AUDIO_SCENARIO_CHATROOM`(5):聊天室场景,适用于用户频繁切换角色或静音/取消静音麦克风的场景。 - `AUDIO_SCENARIO_CHORUS`(7):实时合唱场景,适用于网络状况良好且对超低延迟有要求的场景。在使用该枚举值前,你需要调用 [getAudioDeviceInfo](/zh-CN/api-reference/rtc/android/device-management/audio-device#api_irtcengine_getaudiodeviceinfo) 查看音频设备是否支持超低延迟采集和播放。若要体验超低延迟,需确保音频设备支持超低延迟(`isLowLatencyAudioSupported` = true)。 - `AUDIO_SCENARIO_MEETING`(8):会议场景,主要以人声为主。 - `AUDIO_SCENARIO_AI_CLIENT`(10):AI 对话场景,仅适用于用户与由 `Conversational AI Engine` 创建的对话式智能体交互的场景。 ### 返回值 [#返回值-9] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-9] - [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) ## onActiveSpeaker [#onactivespeaker] 最活跃远端说话人回调。 ```java public void onActiveSpeaker(int uid) ``` 成功调用 [enableAudioVolumeIndication](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengine_enableaudiovolumeindication) 方法后,SDK 会持续检测哪位远端用户的音量最大。在当前周期内,音量被检测为最大次数最多的远端用户即为最活跃用户。当频道中用户数不少于两人,且存在活跃的远端说话人时,SDK 会触发该回调,并报告最活跃远端说话人的用户 ID。 - 如果最活跃的远端说话人始终是同一用户,SDK 只会触发一次该回调。 - 如果最活跃的远端说话人变更为其他用户,SDK 会再次触发该回调,并报告新的最活跃远端说话人的用户 ID。 ### 触发时机 [#触发时机] 该回调在检测到最活跃的远端说话人时被触发。 ### 参数 [#参数-8] 最活跃远端说话用户的用户 ID。 ### 所属接口类 [#所属接口类-10] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineeventhandler) ## onAudioQuality [#onaudioquality] 报告每个远端用户发送的音频流的统计信息回调。 ```java public void onAudioQuality(int uid, int quality, short delay, short lost) ``` :::error[废弃] 该方法已废弃,请改用 [onRemoteAudioStats](/zh-CN/api-reference/rtc/android/audio/audio-basic#callback_irtcengineeventhandler_onremoteaudiostats)。 ::: 该回调每两秒触发一次,用于报告每个正在发送音频流的远端用户的音频质量。 ### 参数 [#参数-9] 发送音频流的远端用户 ID。 用户的音频质量: - `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 网络探测。 从发送端到接收端的网络延迟(毫秒),包括音频采样预处理、网络传输和网络抖动缓冲造成的延迟。 从远端用户发送到接收端的音频数据包的丢包率(%)。 ### 所属接口类 [#所属接口类-11] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineeventhandler) ## onAudioVolumeIndication [#onaudiovolumeindication] 报告用户音量信息的回调。 ```java public void onAudioVolumeIndication(AudioVolumeInfo[] speakers, int totalVolume) ``` 默认情况下,该回调处于关闭状态。你可以通过调用 [enableAudioVolumeIndication](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengine_enableaudiovolumeindication) 方法开启该回调。开启后,当用户在频道中发送音频流时,SDK 会根据 [enableAudioVolumeIndication](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengine_enableaudiovolumeindication) 中设置的时间间隔触发该回调。SDK 会同时触发两个独立的 [onAudioVolumeIndication](/zh-CN/api-reference/rtc/android/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 回调,分别报告发送音频流的本地用户和瞬时音量最高的最多三位远端用户的音量信息。 :::note 注: 开启该回调后,即使本地用户调用 [muteLocalAudioStream](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_mutelocalaudiostream) 方法静音,SDK 仍会继续报告本地用户的音量信息。 - 如果某位远端用户的音量在频道中排名前三,但停止发布音频流超过 20 秒,该回调将不再包含该用户的信息。 - 如果所有远端用户都停止发布音频流超过 20 秒,SDK 将不再触发远端用户的音量回调。 ::: ### 参数 [#参数-10] 用户的音量信息。当该数组为空时,表示频道中没有远端用户或远端用户未发送音频流。详见 [AudioVolumeInfo](/zh-CN/api-reference/rtc/android/class-audiovolumeinfo)。 说话者的音量,取值范围为 [0, 255]。 - 对于本地用户的回调,`totalVolume` 是发送音频流的本地用户的音量。 - 对于远端用户的回调,`totalVolume` 是瞬时音量最高的最多三位远端用户的音量总和。 - 如果调用了 `startAudioMixing`,则 `totalVolume` 是混音后的音量。 ### 所属接口类 [#所属接口类-12] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineeventhandler) ## onFirstLocalAudioFramePublished [#onfirstlocalaudioframepublished] 本地音频首帧发布回调。 ```java public void onFirstLocalAudioFramePublished(int elapsed) ``` 当满足以下任一条件时,SDK 会触发该回调: - 本地客户端启用音频模块并成功调用 `joinChannel`。 - 本地客户端依次调用 `muteLocalAudioStream(true)` 和 `muteLocalAudioStream(false)`。 - 本地客户端依次调用 [disableAudio](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengine_disableaudio) 和 [enableAudio](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengine_enableaudio)。 - 本地客户端调用 [pushExternalAudioFrame](/zh-CN/api-reference/rtc/android/audio/audio-custom-capturenrendering#api_irtcengine_pushaudioframe2) 成功将音频帧推送至 SDK。 ### 触发时机 [#触发时机-1] 该回调在本地音频首帧发布时被触发。 ### 参数 [#参数-11] 从本地用户调用 `joinChannel` 到 SDK 触发该回调的时间间隔(毫秒)。 ### 所属接口类 [#所属接口类-13] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineeventhandler) ## onFirstRemoteAudioDecoded [#onfirstremoteaudiodecoded] 首帧远端音频解码完成回调。 ```java public void onFirstRemoteAudioDecoded(int uid, int elapsed) ``` :::error[废弃] 该方法已废弃,请改用 [onRemoteAudioStateChanged](/zh-CN/api-reference/rtc/android/audio/audio-basic#callback_irtcengineeventhandler_onremoteaudiostatechanged)。 ::: ### 触发时机 [#触发时机-2] 该回调在以下场景中被触发: - 远端用户加入频道并首次发送音频流。 - 远端用户音频从离线恢复为在线并重新发送音频流。可能的原因包括:远端用户离开频道、掉线、调用 [muteLocalAudioStream](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_mutelocalaudiostream) 停止发送音频流,或调用 [disableAudio](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengine_disableaudio) 禁用音频。 ### 参数 [#参数-12] 远端用户 ID。 从本地用户调用 `joinChannel` 到 SDK 触发该回调的时间(毫秒)。 ### 所属接口类 [#所属接口类-14] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineeventhandler) ## onFirstRemoteAudioFrame [#onfirstremoteaudioframe] 远端用户音频首帧已接收回调。 ```java public void onFirstRemoteAudioFrame(int uid, int elapsed) {} ``` :::error[废弃] 该方法已废弃,请改用 [onRemoteAudioStateChanged](/zh-CN/api-reference/rtc/android/audio/audio-basic#callback_irtcengineeventhandler_onremoteaudiostatechanged)。 ::: ### 触发时机 [#触发时机-3] 该回调在 SDK 收到来自某个远端用户的首帧音频时被触发。 ### 参数 [#参数-13] 远端用户的用户 ID。 从本地用户调用 `joinChannel` 到 SDK 触发该回调的时间(毫秒)。 ### 所属接口类 [#所属接口类-15] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineeventhandler) ## onLocalAudioStateChanged [#onlocalaudiostatechanged] 本地音频流状态发生变化回调。 ```java public void onLocalAudioStateChanged(int state, int reason) ``` 当本地音频流的状态发生变化时,SDK 会触发该回调以报告当前状态,便于你在音频异常时排查问题。 :::note 注: 当状态为 `LOCAL_AUDIO_STREAM_STATE_FAILED`(3)时,可以在 `error` 参数中查看错误信息。 ::: ### 触发时机 [#触发时机-4] 该回调在本地音频流状态发生变化时被触发。 ### 参数 [#参数-14] 本地音频的状态: - `LOCAL_AUDIO_STREAM_STATE_STOPPED`(0):本地音频处于初始状态。 - `LOCAL_AUDIO_STREAM_STATE_RECORDING`(1):本地音频采集设备启动成功。 - `LOCAL_AUDIO_STREAM_STATE_ENCODING`(2):首帧音频编码成功。 - `LOCAL_AUDIO_STREAM_STATE_FAILED`(3):本地音频启动失败。 本地音频状态变化的原因: - `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):本地音频采集被系统电话、智能助手或闹钟中断。如果需要继续采集本地音频,提示用户结束电话、智能助手或闹钟。 ### 所属接口类 [#所属接口类-16] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineeventhandler) ## onLocalAudioStats [#onlocalaudiostats] 本地音频流统计信息回调。 ```java public void onLocalAudioStats(LocalAudioStats stats) {} ``` 该回调每两秒触发一次。 ### 触发时机 [#触发时机-5] 该回调每两秒触发一次。 ### 参数 [#参数-15] 本地音频统计信息。详见 [LocalAudioStats](/zh-CN/api-reference/rtc/android/class-localaudiostats)。 ### 所属接口类 [#所属接口类-17] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineeventhandler) ## onRemoteAudioStateChanged [#onremoteaudiostatechanged] 远端音频状态发生变化回调。 ```java public void onRemoteAudioStateChanged(int uid, int state, int reason, int elapsed) ``` 该回调在语音/视频通话频道中的远端用户或直播频道中的主播的音频状态发生变化时被触发,用于报告远端音频流的当前状态。 :::note 注: 当频道中的用户(通信场景)或主播(直播场景)数量超过 32 时,该回调可能无法正常工作。 ::: ### 触发时机 [#触发时机-6] 该回调在远端用户的音频状态发生变化时被触发。 ### 参数 [#参数-16] 音频状态发生变化的远端用户 ID。 远端音频状态: - `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` 的情况下报告该状态。 远端音频状态变化的原因: - `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):远端用户离开频道。 从本地用户调用 `joinChannel` 方法到 SDK 触发该回调的时间(毫秒)。 ### 所属接口类 [#所属接口类-18] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineeventhandler) ## onRemoteAudioStats [#onremoteaudiostats] 报告每个远端音频流的传输层统计信息回调。 ```java public void onRemoteAudioStats(RemoteAudioStats stats) {} ``` 该回调每两秒触发一次。如果频道中有多个远端用户,SDK 会分别为每个用户触发该回调。 ### 参数 [#参数-17] 远端音频流的统计信息。详见 [RemoteAudioStats](/zh-CN/api-reference/rtc/android/class-remoteaudiostats)。 ### 所属接口类 [#所属接口类-19] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineeventhandler) ## onRemoteAudioTransportStats [#onremoteaudiotransportstats] 上报每个远端音频流的传输层统计信息。 ```java public void onRemoteAudioTransportStats(int uid, int delay, int lost, int rxKBitRate) ``` :::error[废弃] 该回调已废弃,请使用 [onRemoteAudioStats](/zh-CN/api-reference/rtc/android/audio/audio-basic#callback_irtcengineeventhandler_onremoteaudiostats) 代替。 ::: 该回调上报远端音频流的传输层统计信息,例如本地用户接收到远端用户音频包后的丢包率和网络时延。 ### 触发时机 [#触发时机-7] 该回调在通话过程中,当本地用户接收到远端用户发送的音频包时每 2 秒被触发。 ### 参数 [#参数-18] 远端用户 ID,即发送音频流的用户。 从远端用户到接收端的网络时延,单位为毫秒。 从远端用户到接收端的音频包丢包率,单位为百分比(%)。 接收到的音频码率,单位为 Kbps。 ### 所属接口类 [#所属接口类-20] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineeventhandler) ## onUserMuteAudio [#onusermuteaudio] 远端用户或主播停止或恢复发送音频流的回调。 ```java public void onUserMuteAudio(int uid, boolean muted) ``` 该回调在远端用户调用 [muteLocalAudioStream](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_mutelocalaudiostream) 方法时触发。 :::note 注: 当频道中用户(在通信场景下)或主播(在直播场景下)数量超过 32 时,该回调可能无法正常工作。 ::: ### 触发时机 [#触发时机-8] 该回调在远端用户调用 [muteLocalAudioStream](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_mutelocalaudiostream) 方法停止或恢复发送音频流时被触发。 ### 参数 [#参数-19] 远端用户 ID。 远端用户的音频流是否被静音: - true:音频流被静音。 - false:音频流未被静音。 ### 所属接口类 [#所属接口类-21] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineeventhandler)