# 音频基础功能 (/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## adjustPlaybackSignalVolume [#adjustplaybacksignalvolume] 调节所有远端用户的本地播放音量。 ```cpp virtual int adjustPlaybackSignalVolume(int volume) = 0; ``` 如果你需要调节某个指定远端用户的本地播放音量,建议调用 [adjustUserPlaybackSignalVolume](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengine_adjustuserplaybacksignalvolume) 方法。 ### 调用时机 [#调用时机] 该方法可以在加入频道前或加入频道后调用。 ### 参数 [#参数] 用户的音量,取值范围为 [0,400]。 - 0:静音。 - 100:(默认)原始音量。 - 400:原始音量的四倍(将音频信号放大四倍)。 ### 返回值 [#返回值] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类] - [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) ## adjustUserPlaybackSignalVolume [#adjustuserplaybacksignalvolume] 调整指定远端用户的播放信号音量。 ```cpp virtual int adjustUserPlaybackSignalVolume(uid_t uid, int volume) = 0; ``` 你可以调用该方法调整指定远端用户的播放音量。若需调整多个远端用户的播放音量,请分别多次调用该方法,每次针对一个远端用户。 ### 调用时机 [#调用时机-1] 请在加入频道后调用该方法。 ### 参数 [#参数-1] 远端用户的用户 ID。 用户的音量,取值范围为 [0, 400]。 - 0:静音。 - 100:(默认)原始音量。 - 400:原始音量的四倍(将音频信号放大四倍)。 ### 返回值 [#返回值-1] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-1] - [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) ## adjustUserPlaybackSignalVolumeEx [#adjustuserplaybacksignalvolumeex] 调整指定远端用户的播放信号音量。 ```cpp virtual int adjustUserPlaybackSignalVolumeEx(uid_t uid, int volume, const RtcConnection& connection) = 0; ``` 你可以调用该方法调整指定远端用户的播放音量。若需调整多个远端用户的播放音量,请分别多次调用该方法,每次针对一个远端用户。 ### 适用场景 [#适用场景] 该方法适用于多频道场景。 ### 调用时机 [#调用时机-2] 请在调用 [joinChannelEx](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_joinchannelex) 后调用该方法。 ### 参数 [#参数-2] 远端用户的用户 ID。 用户的音量,取值范围为 [0, 400]: - 0:静音。 - 100:(默认)原始音量。 - 400:原始音量的四倍(将音频信号放大四倍)。 连接信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection)。 ### 返回值 [#返回值-2] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-2] - [IRtcEngineEx](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineex) ## disableAudio [#disableaudio] 禁用音频模块。 ```cpp virtual int disableAudio() = 0; ``` :::note 注: 该方法会重置内部引擎,并需要一定时间生效。声网建议使用以下 API 分别控制音频模块: - [enableLocalAudio](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-capture#api_irtcengine_enablelocalaudio):是否启用麦克风以创建本地音频流。 - [enableLoopbackRecording](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-capture#api_irtcengine_enableloopbackrecording):是否启用回环音频采集。 - [muteLocalAudioStream](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_mutelocalaudiostream):是否发布本地音频流。 - [muteRemoteAudioStream](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_muteremoteaudiostream):是否订阅并播放远端音频流。 - [muteAllRemoteAudioStreams](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_muteallremoteaudiostreams):是否订阅并播放所有远端音频流。 ::: ### 调用时机 [#调用时机-3] 该方法可以在加入频道前或加入频道后调用。离开频道后仍然有效。 ### 返回值 [#返回值-3] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-3] - [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) ## enableAudio [#enableaudio] 启用音频模块。 ```cpp virtual int enableAudio() = 0; ``` 音频模块默认处于启用状态。调用 [disableAudio](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengine_disableaudio) 方法禁用音频模块后,可以调用该方法重新启用音频模块。 :::note 注: 调用该方法会重置整个引擎,可能导致响应时间变慢。你可以根据实际需求,使用以下方法分别控制音频模块的具体功能: - [enableLocalAudio](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-capture#api_irtcengine_enablelocalaudio):是否启用麦克风以创建本地音频流。 - [muteLocalAudioStream](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_mutelocalaudiostream):是否发布本地音频流。 - [muteRemoteAudioStream](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_muteremoteaudiostream):是否订阅并播放远端音频流。 - [muteAllRemoteAudioStreams](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_muteallremoteaudiostreams):是否订阅并播放所有远端音频流。 成功调用该方法会重置 [enableLocalAudio](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-capture#api_irtcengine_enablelocalaudio)、[muteRemoteAudioStream](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_muteremoteaudiostream) 和 [muteAllRemoteAudioStreams](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_muteallremoteaudiostreams) 的设置,请谨慎使用。 ::: ### 调用时机 [#调用时机-4] 该方法可以在加入频道前或加入频道后调用,离开频道后仍然有效。 ### 返回值 [#返回值-4] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-4] - [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) ## enableAudioVolumeIndication [#enableaudiovolumeindication] 启用用户音量提示的上报功能。 ```cpp virtual int enableAudioVolumeIndication(int interval, int smooth, bool reportVad) = 0; ``` 该方法用于启用 SDK 定期向应用上报本地发送音频流的用户和瞬时音量最大的最多三位远端用户的音量信息。 ### 调用时机 [#调用时机-5] 该方法可以在加入频道前或加入频道后调用。 ### 相关回调 [#相关回调] 成功调用该方法后,若频道中有用户发布音频流,SDK 会按照设置的时间间隔触发 [onAudioVolumeIndication](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 回调。 ### 参数 [#参数-3] 设置两次音量提示之间的时间间隔(毫秒): - ≤ 0:关闭音量提示功能。 - > 0:两次音量提示之间的时间间隔(单位为毫秒)。该值需大于 10,否则无法收到 [onAudioVolumeIndication](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 回调。建议设置为大于 100。 设置音量提示的灵敏度平滑系数,取值范围为 0 到 10,推荐值为 3。值越大,提示越灵敏。 是否启用本地用户的语音活动检测(VAD): - true:启用语音活动检测。启用后,[onAudioVolumeIndication](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 回调中的 `vad` 参数会报告本地用户的语音活动状态。 - false:(默认)关闭语音活动检测。关闭后,[onAudioVolumeIndication](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 回调中的 `vad` 参数不会报告本地用户的语音活动状态,除非引擎自动检测到语音活动。 ### 返回值 [#返回值-5] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-5] - [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) ## enableAudioVolumeIndicationEx [#enableaudiovolumeindicationex] 启用用户音量提示的上报功能。 ```cpp virtual int enableAudioVolumeIndicationEx(int interval, int smooth, bool reportVad, const RtcConnection& connection) = 0; ``` 该方法用于启用 SDK 定期向应用上报本地发送音频流的用户和音量瞬时值最高的最多三位远端用户的音量信息。 ### 适用场景 [#适用场景-1] 该方法适用于多频道场景。 ### 调用时机 [#调用时机-6] 请在调用 [joinChannelEx](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_joinchannelex) 后调用该方法。 ### 相关回调 [#相关回调-1] 成功调用该方法后,SDK 会根据设置的时间间隔触发 [onAudioVolumeIndication](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 回调,在频道中有用户发布音频流时报告音量信息。 ### 参数 [#参数-4] 设置两次音量提示之间的时间间隔(毫秒): - ≤ 0:关闭音量提示。 - > 0:两次音量提示之间的时间间隔(毫秒)。该值需大于 10,否则无法收到 [onAudioVolumeIndication](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 回调。建议设置为大于 100。 设置音量提示的灵敏度平滑系数,取值范围为 0 到 10,推荐值为 3。值越大,提示越灵敏。 是否启用本地用户的语音活动检测(Voice Activity Detection): - true:启用语音活动检测。启用后,[onAudioVolumeIndication](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 回调中的 `vad` 参数会报告本地用户的语音活动状态。 - false:(默认)关闭语音活动检测。关闭后,[onAudioVolumeIndication](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 回调中的 `vad` 参数不会报告本地用户的语音活动状态,除非引擎自动检测到语音活动。 连接信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection)。 ### 返回值 [#返回值-6] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-6] - [IRtcEngineEx](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineex) ## setAudioProfile [1/2] [#setaudioprofile-12] 设置音频配置和音频场景。 ```cpp virtual int setAudioProfile(AUDIO_PROFILE_TYPE profile, AUDIO_SCENARIO_TYPE scenario) __deprecated = 0; ``` :::error[废弃] 该方法已废弃。你可以改用 [setAudioProfile [2/2]](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengine_setaudioprofile2) 方法。若需设置音频场景,请调用 [initialize](/zh-CN/api-reference/rtc/cpp-all-platforms/initialize#api_irtcengine_initialize) 方法,并在 [RtcEngineContext](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcengineconfig) 结构体中的 `audioScenario` 成员中传入值。 ::: :::note 注: 由于 iOS 系统限制,在通话音量模式下部分音频路由无法识别。因此,如需使用外置声卡,建议将音频场景设置为 `AUDIO_SCENARIO_GAME_STREAMING`(3)。在该场景下,SDK 会切换为媒体音量以规避该问题。 ::: ### 适用场景 [#适用场景-2] 该方法适用于多种音频场景,你可以根据实际需求进行选择。例如,在对音质要求较高的场景(如音乐教学)中,建议将 `profile` 设置为 `AUDIO_PROFILE_MUSIC_HIGH_QUALITY`(4),将 `scenario` 设置为 `AUDIO_SCENARIO_GAME_STREAMING`(3)。你可以在加入频道前或加入频道后调用该方法。 ### 参数 [#参数-5] 音频配置,包括采样率、码率、编码模式和声道数。详见 [AUDIO_PROFILE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-audioprofiletype)。 音频场景,在不同的音频场景下设备使用不同的音量类型。详见 [AUDIO_SCENARIO_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-audioscenariotype)。 ### 返回值 [#返回值-7] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-7] - [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) ## setAudioProfile [2/2] [#setaudioprofile-22] 设置音频配置文件。 ```cpp virtual int setAudioProfile(AUDIO_PROFILE_TYPE profile) = 0; ``` ### 适用场景 [#适用场景-3] 你可以根据实际需求选择合适的音频配置文件。例如,在音乐教学等对音质要求较高的场景中,建议将 `profile` 设置为 `AUDIO_PROFILE_MUSIC_HIGH_QUALITY`(4)。如果你需要设置音频场景,可以调用 [setAudioScenario](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengine_setaudioscenario),或者调用 [initialize](/zh-CN/api-reference/rtc/cpp-all-platforms/initialize#api_irtcengine_initialize) 并在 [RtcEngineContext](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcengineconfig) 中设置 `audioScenario`。 ### 调用时机 [#调用时机-7] 你可以在加入频道前或后调用该方法。 ### 参数 [#参数-6] 音频配置文件,包括采样率、码率、编码模式和声道数。详见 [AUDIO_PROFILE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-audioprofiletype)。 ### 返回值 [#返回值-8] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-8] - [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) ## setAudioScenario [#setaudioscenario] 设置音频场景。 ```cpp virtual int setAudioScenario(AUDIO_SCENARIO_TYPE scenario) = 0; ``` :::note 注: 由于 iOS 系统限制,在通话音量模式下,部分音频路由可能无法识别。如果你需要使用外置声卡,建议将音频场景设置为 `AUDIO_SCENARIO_GAME_STREAMING`(3)。在该场景下,SDK 会切换为媒体音量,以避免该问题。 ::: ### 适用场景 [#适用场景-4] 该方法适用于多种音频场景。例如,在对音质要求较高的音乐教学场景中,建议将 `scenario` 设置为 `AUDIO_SCENARIO_GAME_STREAMING`(3)。 ### 调用时机 [#调用时机-8] 你可以在加入频道前或加入频道后调用该方法。 ### 参数 [#参数-7] 音频场景。不同音频场景下,设备使用不同的音量类型。详见 [AUDIO_SCENARIO_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-audioscenariotype)。 ### 返回值 [#返回值-9] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-9] - [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) ## setAudioSessionOperationRestriction [#setaudiosessionoperationrestriction] 设置 SDK 对音频会话的操作权限。 ```cpp virtual int setAudioSessionOperationRestriction(AUDIO_SESSION_OPERATION_RESTRICTION restriction) = 0; ``` 默认情况下,SDK 和 App 都可以配置音频会话。如果你只希望由 App 配置音频会话,可以通过该方法限制 SDK 的操作权限。你可以在加入频道前或后调用该方法。一旦调用该方法进行限制,当 SDK 需要更改音频会话时,该限制将生效。 :::note 注: - 该方法仅适用于 iOS。 - 该方法不会限制 App 对音频会话的操作权限。 ::: ### 参数 [#参数-8] SDK 对音频会话的操作权限。该参数为位掩码格式,每一位对应一个权限。详见 [AUDIO_SESSION_OPERATION_RESTRICTION](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-audiosessionoperationrestriction)。 ### 返回值 [#返回值-10] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-10] - [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) ## onActiveSpeaker [#onactivespeaker] 最活跃远端说话人回调。 ```cpp virtual void onActiveSpeaker(uid_t uid) ``` 调用 [enableAudioVolumeIndication](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengine_enableaudiovolumeindication) 方法成功后,SDK 会持续检测哪位远端用户的音量最大。在当前周期内,音量被检测为最大次数最多的远端用户即为最活跃用户。当频道中用户数不少于两人且存在活跃的远端说话人时,SDK 会触发该回调并报告最活跃远端说话人的用户 ID。 - 如果最活跃的远端说话人始终是同一用户,SDK 只会触发一次该回调。 - 如果最活跃的远端说话人变更为其他用户,SDK 会再次触发该回调并报告新的最活跃远端说话人的用户 ID。 ### 参数 [#参数-9] 最活跃远端说话人的用户 ID。 ### 所属接口类 [#所属接口类-11] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler) ## onAudioQuality [#onaudioquality] 报告每个远端用户发送的音频流的统计信息。 ```cpp virtual void onAudioQuality(uid_t uid, int quality, unsigned short delay, unsigned short lost) __deprecated ``` :::error[废弃] 该回调已废弃,请改用 [onRemoteAudioStats](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#callback_irtcengineeventhandler_onremoteaudiostats)。 ::: SDK 每两秒触发一次该回调,用于报告每个正在发送音频流的远端用户的音频质量。如果频道中有多个用户发送音频流,SDK 会触发多次该回调。 ### 参数 [#参数-10] 发送音频流的远端用户 ID。 该用户的音频质量,详见 [QUALITY_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-qualitytype)。 从发送端到接收端的网络延迟(毫秒),包括音频采样预处理、网络传输和网络抖动缓冲造成的延迟。 从远端用户到接收端的音频数据包丢包率(%)。 ### 所属接口类 [#所属接口类-12] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler) ## onAudioVolumeIndication [#onaudiovolumeindication] [onAudioVolumeIndication](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 回调。 ```cpp virtual void onAudioVolumeIndication(const AudioVolumeInfo* speakers, unsigned int speakerNumber, int totalVolume) ``` 默认情况下,该回调处于关闭状态。你可以通过调用 [enableAudioVolumeIndication](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengine_enableaudiovolumeindication) 方法开启该回调。开启后,当频道中有用户发送音频流时,SDK 会按照 [enableAudioVolumeIndication](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengine_enableaudiovolumeindication) 中设置的时间间隔触发该回调。SDK 会同时触发两个独立的 [onAudioVolumeIndication](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 回调,分别报告发送音频流的本地用户和瞬时音量最高的最多三位远端用户的音量信息。 :::note 注: 开启该回调后,即使本地用户调用 [muteLocalAudioStream](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_mutelocalaudiostream) 方法将音频静音,SDK 仍会继续报告本地用户的音量信息。如果某位远端用户的音量为频道中前三高之一,但停止发布音频流超过 20 秒,该回调将不再包含该用户的信息;如果所有远端用户都停止发布音频流超过 20 秒,SDK 将不再触发远端用户的音量回调。 ::: ### 触发时机 [#触发时机] 当启用音量提示并有用户发送音频流时触发。 ### 参数 [#参数-11] 用户的音量信息。详见 [AudioVolumeInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-audiovolumeinfo)。当该回调中的 `speakers` 数组为空时,表示频道中没有远端用户或没有用户发送音频流。 用户总数。 - 本地用户的回调中,如果本地用户正在发送音频流,`speakerNumber` 的值为 1。 - 远端用户的回调中,`speakerNumber` 的取值范围为 [0, 3]。如果发送音频流的远端用户数量大于或等于 3,`speakerNumber` 的值为 3。 说话者的音量,取值范围为 [0, 255]。 - 本地用户的回调中,`totalVolume` 表示本地用户的音量。 - 远端用户的回调中,`totalVolume` 表示瞬时音量最高的最多三位远端用户的音量总和。如果调用了 `startAudioMixing`,则该值为混音后的音量。 ### 所属接口类 [#所属接口类-13] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler) ## onFirstLocalAudioFramePublished [#onfirstlocalaudioframepublished] 本地用户发布首帧音频时触发的回调。 ```cpp virtual void onFirstLocalAudioFramePublished(int elapsed) ``` ### 触发时机 [#触发时机-1] 该回调在以下任一情况下由 SDK 触发: - 本地客户端启用音频模块并成功调用 `joinChannel`。 - 本地客户端依次调用 `muteLocalAudioStream(true)` 和 `muteLocalAudioStream(false)`。 - 本地客户端依次调用 [disableAudio](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengine_disableaudio) 和 [enableAudio](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengine_enableaudio)。 - 本地客户端调用 [pushAudioFrame](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-custom-capturenrendering#api_imediaengine_pushaudioframe) 成功将音频帧推送至 SDK。 ### 参数 [#参数-12] 从本地用户调用 `joinChannel` 到 SDK 触发该回调的时间间隔(毫秒)。 ### 所属接口类 [#所属接口类-14] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler) ## onFirstRemoteAudioDecoded [#onfirstremoteaudiodecoded] 首帧远端音频解码完成回调。 ```cpp virtual void onFirstRemoteAudioDecoded(uid_t uid, int elapsed) __deprecated ``` :::error[废弃] 该方法已废弃,请改用 [onRemoteAudioStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#callback_irtcengineeventhandler_onremoteaudiostatechanged)。 ::: ### 触发时机 [#触发时机-2] 当远端用户首次发送音频流,或音频从离线恢复为在线重新发送音频时触发。 ### 参数 [#参数-13] 远端用户 ID。 从本地用户调用 `joinChannel` 加入频道到 SDK 触发该回调的时间,单位为毫秒。 ### 所属接口类 [#所属接口类-15] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler) ## onFirstRemoteAudioFrame [#onfirstremoteaudioframe] 远端用户音频首帧到达回调。 ```cpp virtual void onFirstRemoteAudioFrame(uid_t uid, int elapsed) __deprecated ``` :::error[废弃] 该方法已废弃,请改用 [onRemoteAudioStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#callback_irtcengineeventhandler_onremoteaudiostatechanged)。 ::: ### 参数 [#参数-14] 远端用户 ID。 从本地用户调用 `joinChannel` 加入频道到 SDK 触发该回调的时间,单位为毫秒。 ### 所属接口类 [#所属接口类-16] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler) ## onLocalAudioStateChanged [#onlocalaudiostatechanged] 本地音频流状态发生变化回调。 ```cpp virtual void onLocalAudioStateChanged(LOCAL_AUDIO_STREAM_STATE state, LOCAL_AUDIO_STREAM_REASON reason) ``` 当本地音频流的状态(包括音频采集和编码状态)发生变化时,SDK 会触发该回调报告当前状态,帮助你排查音频异常问题。 :::note 注: 当状态为 `LOCAL_AUDIO_STREAM_STATE_FAILED`(3)时,可以在 `reason` 参数中查看错误信息。 ::: ### 参数 [#参数-15] 本地音频流的状态,详见 [LOCAL_AUDIO_STREAM_STATE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-localaudiostreamstate)。 本地音频流状态变化的原因,详见 [LOCAL_AUDIO_STREAM_REASON](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-localaudiostreamreason)。 ### 所属接口类 [#所属接口类-17] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler) ## onLocalAudioStats [#onlocalaudiostats] 本地音频统计信息回调。 ```cpp virtual void onLocalAudioStats(const LocalAudioStats& stats) ``` ### 触发时机 [#触发时机-3] SDK 每两秒触发一次该回调。 ### 参数 [#参数-16] 本地音频统计信息。详见 [LocalAudioStats](/zh-CN/api-reference/rtc/cpp-all-platforms/class-localaudiostats)。 ### 所属接口类 [#所属接口类-18] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler) ## onRemoteAudioStateChanged [#onremoteaudiostatechanged] 远端音频状态发生变化回调。 ```cpp virtual void onRemoteAudioStateChanged(uid_t uid, REMOTE_AUDIO_STATE state, REMOTE_AUDIO_STATE_REASON reason, int elapsed) ``` :::note 注: 当通信场景下的用户或直播场景下的主播数量超过 32 时,该回调无法正常工作。 ::: ### 触发时机 [#触发时机-4] 当远端用户的音频状态发生变化时触发。 ### 参数 [#参数-17] 音频状态发生变化的远端用户 ID。 远端音频状态。详见 [REMOTE_AUDIO_STATE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-remoteaudiostate)。 远端音频状态变化的原因。详见 [REMOTE_AUDIO_STATE_REASON](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-remoteaudiostatereason)。 从本地用户调用 `joinChannel` 方法到 SDK 触发该回调的时间间隔(毫秒)。 ### 所属接口类 [#所属接口类-19] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler) ## onRemoteAudioStats [#onremoteaudiostats] 远端音频流统计信息回调。 ```cpp virtual void onRemoteAudioStats(const RemoteAudioStats& stats) ``` 该回调每两秒触发一次,用于报告每个正在发送音频流的远端用户的传输层统计信息。如果频道中有多个远端用户,SDK 会分别为每个用户触发该回调。 ### 参数 [#参数-18] 远端音频流的统计信息。详见 [RemoteAudioStats](/zh-CN/api-reference/rtc/cpp-all-platforms/class-remoteaudiostats)。 ### 所属接口类 [#所属接口类-20] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler) ## onRemoteAudioTransportStats [#onremoteaudiotransportstats] 报告每个远端音频流的传输层统计信息回调。 ```cpp virtual void onRemoteAudioTransportStats(uid_t uid, unsigned short delay, unsigned short lost, unsigned short rxKBitRate) __deprecated ``` :::error[废弃] 该方法已废弃,请改用 [onRemoteAudioStats](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#callback_irtcengineeventhandler_onremoteaudiostats)。 ::: 该回调报告传输层的统计信息,例如在本地用户接收到远端用户的音频数据包后,数据包的丢失率和网络时延。该回调在通话过程中每 2 秒触发一次。 ### 触发时机 [#触发时机-5] 在通话过程中,每当本地用户接收到远端用户发送的音频数据包时,每 2 秒触发一次。 ### 参数 [#参数-19] 远端用户 ID,即发送音频流的用户。 从远端用户到本地接收端的网络时延(毫秒)。 从远端用户到本地接收端的音频数据包丢失率(%)。 接收到的音频码率(Kbps)。 ### 所属接口类 [#所属接口类-21] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler) ## onUserMuteAudio [#onusermuteaudio] 远端用户或主播停止或恢复发送音频流回调。 ```cpp virtual void onUserMuteAudio(uid_t uid, bool muted) ``` 当远端用户调用 [muteLocalAudioStream](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_mutelocalaudiostream) 停止或恢复发送音频流时,SDK 会触发该回调。 :::note 注: 当通信场景中的用户数量或直播场景中的主播数量超过 32 时,该回调可能无法正常工作。 ::: ### 参数 [#参数-20] 远端用户 ID。 远端用户的音频流是否被静音: - true:音频流被静音。 - false:音频流未被静音。 ### 所属接口类 [#所属接口类-22] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)