音频基础功能

adjustUserPlaybackSignalVolume

调节本地播放的指定远端用户信号音量。

C++
virtual int adjustUserPlaybackSignalVolume(unsigned int uid, int volume) = 0;

你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量，则需多次调用该方法。

调用时机

该方法需要在加入频道后调用。

调用限制

无。

参数

uid

远端用户 ID。

volume

音量，取值范围为 [0,400]。

0: 静音。
100: （默认）原始音量。
400: 原始音量的 4 倍，自带溢出保护。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

adjustUserPlaybackSignalVolumeEx

调节本地播放的指定远端用户信号音量。

C++
virtual int adjustUserPlaybackSignalVolumeEx(unsigned int uid, int volume, const RtcConnection& connection) = 0;

你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量，则需多次调用该方法。

调用时机

该方法需要在 joinChannelEx 之后调用。

调用限制

无。

参数

uid

远端用户 ID。

volume

音量，取值范围为 [0,400]。

0: 静音。
100: （默认）原始音量。
400: 原始音量的 4 倍，自带溢出保护。

connection

Connection 信息。详见 RtcConnection。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngineEx

disableAudio

关闭音频模块。

C++
virtual int disableAudio() = 0;

音频模块默认开启，你可以调用该方法关闭音频模块。

调用时机

加入频道前后均可调用。离开频道后仍然有效。

调用限制

该方法重置整个引擎，响应时间较慢，因此声网建议使用如下方法来控制音频模块：

enableLocalAudio：是否启动麦克风采集并创建本地音频流。
enableLoopbackRecording：是否开启声卡采集。
muteLocalAudioStream：是否发布本地音频流。
muteRemoteAudioStream：是否接收并播放远端音频流。
muteAllRemoteAudioStreams：是否接收并播放所有远端音频流。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

enableAudio

启用音频模块。

C++
virtual int enableAudio() = 0;

音频模块默认开启。如果你调用 disableAudio 关闭了音频模块，可调用该方法重新开启。

调用时机

加入频道前后均可调用。离开频道后仍然有效。

调用限制

调用该方法会重置整个引擎，响应时间较慢。你可以根据实际需求用以下方法来独立控制音频模块的某一项功能：
- enableLocalAudio: 是否启动麦克风采集并创建本地音频流。
- muteLocalAudioStream: 是否发布本地音频流。
- muteRemoteAudioStream: 是否接收并播放远端音频流。
- muteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。
在频道内调用该方法时，会重置 enableLocalAudio、muteRemoteAudioStream 和 muteAllRemoteAudioStreams 的设置，需谨慎使用。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

enableAudioVolumeIndication

启用用户音量提示。

C++
virtual int enableAudioVolumeIndication(int interval, int smooth, bool reportVad) = 0;

该方法允许 SDK 定期向 App 报告本地发流用户和瞬时音量最高的远端用户（最多 3 位）的音量相关信息。

调用时机

加入频道前后均可调用。

调用限制

无。

参数

interval

指定音量提示的时间间隔：

≤ 0: 禁用音量提示功能。
> 0: 返回音量提示的间隔，单位为毫秒。建议设置到大于 100 毫秒，不得小于 10 毫秒，否则会收不到 onAudioVolumeIndication 回调。

smooth

平滑系数，指定音量提示的灵敏度。取值范围为 [0,10]，建议值为 3。数字越大，波动越灵敏；数字越小，波动越平滑。

reportVad

true：开启本地人声检测功能。开启后，onAudioVolumeIndication 回调的 vad 参数会报告是否在本地检测到人声。
false：（默认）关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外，onAudioVolumeIndication 回调的 vad 参数不会报告是否在本地检测到人声。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

enableAudioVolumeIndicationEx

启用用户音量提示。

C++
virtual int enableAudioVolumeIndicationEx(int interval, int smooth, bool reportVad, const RtcConnection& connection) = 0;

该方法允许 SDK 定期向 App 报告本地发流用户和瞬时音量最高的远端用户（最多 3 位）的音量相关信息。

调用时机

该方法需要在 joinChannelEx 之后调用。

调用限制

无。

参数

interval

指定音量提示的时间间隔：

≤ 0: 禁用音量提示功能。
> 0: 返回音量提示的间隔，单位为毫秒。建议设置到大于 100 毫秒，不得小于 10 毫秒，否则会收不到 onAudioVolumeIndication 回调。

smooth

平滑系数，指定音量提示的灵敏度。取值范围为 [0,10]，建议值为 3。数字越大，波动越灵敏；数字越小，波动越平滑。

reportVad

true：开启本地人声检测功能。开启后，onAudioVolumeIndication 回调的 vad 参数会报告是否在本地检测到人声。
false：（默认）关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外，onAudioVolumeIndication 回调的 vad 参数不会报告是否在本地检测到人声。

connection

Connection 信息。详见 RtcConnection。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngineEx

setAudioProfile [1/2]

设置音频编码属性和音频场景。

C++
virtual int setAudioProfile(AUDIO_PROFILE_TYPE profile, AUDIO_SCENARIO_TYPE scenario) = 0;

废弃

此方法已废弃，如需设置音频编码属性，请改用 setAudioProfile [2/2]；如需设置音频场景，请改用 setAudioScenario。

适用场景

该方法适用于各种音频场景，你可以按需选择。例如，在音乐教学等高音质需求的场景中，建议将 profile 设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)，scenario 设置为 AUDIO_SCENARIO_GAME_STREAMING(3)。

调用时机

该方法在加入频道前后均可调用。

调用限制

由于 iOS 系统限制，部分音频路由在通话音量模式下无法识别。因此，如需使用外接声卡，建议将音频应用场景设置为高音质场景 AUDIO_SCENARIO_GAME_STREAMING(3)。在这种场景下，SDK 会切换到媒体音量规避该问题。

参数

profile: 音频编码属性，包含采样率、码率、编码模式和声道数。详见 AUDIO_PROFILE_TYPE。
scenario: 音频场景。不同的音频场景下，设备的音量类型是不同的。详见 AUDIO_SCENARIO_TYPE 。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

setAudioProfile [2/2]

设置音频编码属性。

C++
virtual int setAudioProfile(AUDIO_PROFILE_TYPE profile) = 0;

如果你想设置音频应用场景，可以直接调用 setAudioScenario 方法进行设置，也可以调用 initialize 并设置 RtcEngineContext 结构体中的 audioScenario。

适用场景

该方法适用于各种音频场景，你可以按需选择。例如，在音乐教学等高音质需求的场景中，建议将 profile 设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)。

调用时机

该方法在加入频道前后均可调用。

调用限制

无。

参数

profile: 音频编码属性，包含采样率、码率、编码模式和声道数。详见 AUDIO_PROFILE_TYPE。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

setAudioScenario

设置音频场景。

C++
virtual int setAudioScenario(AUDIO_SCENARIO_TYPE scenario) = 0;

适用场景

该方法适用于各种音频场景，你可以按需选择。例如，在音乐教学等高音质需求的场景中，建议将 scenario 设置为 AUDIO_SCENARIO_GAME_STREAMING(3)。

调用时机

该方法在加入频道前后均可调用。

调用限制

参数

scenario: 音频场景。不同的音频场景下，设备的音量类型是不同的。详见 AUDIO_SCENARIO_TYPE 。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

setAudioSessionOperationRestriction

设置 SDK 对 Audio Session 的操作权限。

C++
virtual int setAudioSessionOperationRestriction(AUDIO_SESSION_OPERATION_RESTRICTION restriction) = 0;

详情

默认情况下，SDK 和 App 对 Audio Session 都有操作权限。如果你只需使用 App 对 Audio Session 进行操作，你可以调用该方法限制 SDK 对 Audio Session 的操作权限。

该方法在加入频道前后都能调用。一旦调用该方法限制了 SDK 对 Audio Session 的操作权限，该限制会在 SDK 需要更改 Audio Session 时生效。

注意

该方法仅适用于 iOS 平台。
该方法不会限制 App 对 Audio Session 的操作权限。

参数

restriction: SDK 对 Audio Session 的操作权限，详见 AUDIO_SESSION_OPERATION_RESTRICTION。该参数为 Bit Mask，每个 Bit 对应一个权限。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

onActiveSpeaker

监测到远端最活跃用户回调。

C++
virtual void onActiveSpeaker(uid_t userId) { (void)userId; }

详情

成功调用 enableAudioVolumeIndication 后，SDK 会持续监测音量最大的远端用户，并统计该用户被判断为音量最大者的次数。当前时间段内，该次数累积最多的远端用户为最活跃的用户。

当频道内用户数量大于或等于 2 且有远端活跃用户时，SDK 会触发该回调并报告远端最活跃用户的 uid。

如果远端最活跃用户一直是同一位用户，则 SDK 不会再次触发 onActiveSpeaker 回调。
如果远端最活跃用户有变化，则 SDK 会再次触发该回调并报告新的远端最活跃用户的 uid。

参数

userId: 远端最活跃用户的 ID。

所属接口类

IRtcEngineEventHandler

onAudioQuality

远端声音质量回调。

C++
virtual void onAudioQuality(uid_t uid, int quality, unsigned short delay, unsigned short lost) {
  (void)uid;
  (void)quality;
  (void)delay;
  (void)lost;
}

详情

废弃

请改用 onRemoteAudioStats。

该回调描述远端用户在通话中的音频质量，针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播，该回调每 2 秒会被触发多次。

参数

uid: 用户 ID，指定是谁发的音频流。
quality: 语音质量。详见 QUALITY_TYPE。
delay: 音频包从发送端到接收端的延迟（毫秒），包括声音采样前处理、网络传输、网络抖动缓冲引起的延迟。
lost: 音频包从发送端到接收端的丢包率 (%)。

所属接口类

IRtcEngineEventHandler

onAudioVolumeIndication

用户音量提示回调。

C++
virtual void onAudioVolumeIndication(const AudioVolumeInfo* speakers,
    unsigned int speakerNumber,
    int totalVolume) {
    (void)speakers;
    (void)speakerNumber;
    (void)totalVolume;
    }

详情

该回调默认禁用，你可以通过 enableAudioVolumeIndication 开启。开启后，只要频道内有发流用户，SDK 会在加入频道后按 enableAudioVolumeIndication 中设置的时间间隔触发 onAudioVolumeIndication 回调。每次会触发两个 onAudioVolumeIndication 回调，一个报告本地发流用户的音量相关信息，另一个报告瞬时音量最高的远端用户（最多 3 位）的音量相关信息。

注意

启用该功能后，如果有用户将自己静音（调用了 muteLocalAudioStream），SDK 会继续报告本地用户的音量提示回调。

瞬时音量最高的远端用户静音后 20 秒，远端的音量提示回调中将不再包含该用户；如果远端所有用户都将自己静音，20 秒后 SDK 停止报告远端用户的音量提示回调。

参数

speakers

用户音量信息，详见 AudioVolumeInfo 数组。如果 speakers 为空，则表示远端用户不发流或没有远端用户。

speakerNumber

用户数量。

在本地用户的回调中，只要本地用户在发流，speakerNumber 始终为 1。
在远端用户的回调中，speakerNumber 取值范围为 [0,3]。如果远端发流用户数量大于 3，则此回调中 speakerNumber 值为 3。

totalVolume

混音后的总音量，取值范围为 [0,255]。

在本地用户的回调中，totalVolume 为本地发流用户的音量。
在远端用户的回调中，totalVolume 为瞬时音量最高的远端用户（最多 3 位）混音后的总音量。如果用户调用了 startAudioMixing [2/2]，则 totalVolume 为音乐文件和用户声音的总音量。

所属接口类

IRtcEngineEventHandler

onFirstLocalAudioFramePublished

已发布本地音频首帧回调。

C++
virtual void onFirstLocalAudioFramePublished(int elapsed) {
    (void)elapsed;
    }

详情

SDK 会在以下时机触发该回调：

开启本地音频的情况下，调用 joinChannel [2/2] 成功加入频道后。
调用 muteLocalAudioStream(true)，再调用 muteLocalAudioStream(false) 后。
调用 disableAudio，再调用 enableAudio 后。
调用 pushAudioFrame 成功向 SDK 推送音频帧后。

参数

elapsed: 从调用 joinChannel [2/2] 方法到触发该回调的时间间隔（毫秒）。

所属接口类

IRtcEngineEventHandler

onFirstRemoteAudioDecoded

已解码远端音频首帧的回调。

C++
virtual void onFirstRemoteAudioDecoded(uid_t uid, int elapsed) {
                (void)uid;
                (void)elapsed;
                }
            

详情

废弃

请改用 onRemoteAudioStateChanged 。

SDK 会在以下时机触发该回调：

远端用户首次上线后发送音频。
远端用户音频离线再上线发送音频。音频离线指本地在 15 秒内没有收到音频包，可能有如下原因：
- 远端用户离开频道
- 远端用户掉线
- 远端用户调用 muteLocalAudioStream 方法停止发送音频流
- 远端用户调用 disableAudio 方法关闭音频

参数

uid: 远端用户 ID。
elapsed: 从本地用户调用 joinChannel [2/2] 直至该回调触发的延迟，单位为毫秒。

所属接口类

IRtcEngineEventHandler

onFirstRemoteAudioFrame

已接收远端音频首帧回调。

C++
virtual void onFirstRemoteAudioFrame(uid_t uid, int elapsed) AGORA_DEPRECATED_ATTRIBUTE {
    (void)uid;
    (void)elapsed;
  }

详情

废弃

请改用 onRemoteAudioStateChanged 。

参数

uid: 发送音频帧的远端用户的用户 ID。
elapsed: 从本地用户调用 joinChannel [2/2] 直至该回调触发的延迟，单位为毫秒。

所属接口类

IRtcEngineEventHandler

onLocalAudioStateChanged

本地音频状态发生改变回调。

C++
  virtual void onLocalAudioStateChanged(LOCAL_AUDIO_STREAM_STATE state, LOCAL_AUDIO_STREAM_REASON reason) {
    (void)state;
    (void)reason;
  }

详情

本地音频的状态发生改变时（包括本地麦克风采集状态和音频编码状态），SDK 会触发该回调报告当前的本地音频状态。在本地音频出现故障时，该回调可以帮助你了解当前音频的状态以及出现故障的原因，方便你排查问题。

注意

当状态为 LOCAL_AUDIO_STREAM_STATE_FAILED (3) 时，你可以在 error 参数中查看返回的错误信息。

参数

state: 当前的本地音频状态。详见 LOCAL_AUDIO_STREAM_STATE。
reason: 本地音频状态改变原因。详见 LOCAL_AUDIO_STREAM_REASON。

所属接口类

IRtcEngineEventHandler

onLocalAudioStats

通话中本地音频流的统计信息回调。

C++
virtual void onLocalAudioStats(const LocalAudioStats& stats) {
    (void)stats;
    }

详情

SDK 每 2 秒触发该回调一次。

参数

stats: 本地音频统计数据。详见 LocalAudioStats。

所属接口类

IRtcEngineEventHandler

onRemoteAudioStateChanged

远端音频流状态发生改变回调。

C++
virtual void onRemoteAudioStateChanged(uid_t uid,
     REMOTE_AUDIO_STATE state,
     REMOTE_AUDIO_STATE_REASON reason,
     int elapsed) {
     (void)uid;
     (void)state;
     (void)reason;
     (void)elapsed;
     }

详情

远端用户（通信场景）或主播（直播场景）的音频状态发生改变时，SDK 会触发该回调向本地用户报告当前的远端音频流状态。

注意

频道内的用户（通信场景）或主播（直播场景）人数超过 17 人时，该回调可能不准确。

参数

uid: 发生音频状态改变的远端用户 ID。
state: 远端音频流状态，详见 REMOTE_AUDIO_STATE。
reason: 远端音频流状态改变的具体原因，详见 REMOTE_AUDIO_STATE_REASON。
elapsed: 从本地用户调用 joinChannel [2/2] 方法到发生本事件经历的时间，单位为毫秒。

所属接口类

IRtcEngineEventHandler

onRemoteAudioStats

通话中远端音频流的统计信息回调。

C++
virtual void onRemoteAudioStats(const RemoteAudioStats& stats) {
    (void)stats;
    }

详情

该回调针对每个发送音频流的远端用户/主播每 2 秒触发一次。如果远端有多个用户/主播发送音频流，该回调每 2 秒会被触发多次。

参数

stats: 接收到的远端音频统计数据，详见 RemoteAudioStats。

所属接口类

IRtcEngineEventHandler

onRemoteAudioTransportStats

通话中远端音频流传输的统计信息回调。

C++
virtual void onRemoteAudioTransportStats(uid_t uid,
     unsigned short delay,
     unsigned short lost,
     unsigned short rxKBitRate) {
     (void)uid;
     (void)delay;
     (void)lost;
     (void)rxKBitRate;
     }

详情

废弃

请改用 onRemoteAudioStats。

该回调描述远端用户通话中端到端的网络统计信息，通过音频包计算，用客观的数据，如丢包、网络延迟等，展示当前网络状态。通话中，当用户收到远端用户/主播发送的音频数据包后，会每 2 秒触发一次该回调。

参数

uid: 用户 ID，指定是哪个用户/主播的音频包。
delay: 音频包从发送端到接收端的延时（毫秒）。
lost: 音频包从发送端到接收端的丢包率 (%)。
rxKBitrate: 远端音频包的接收码率（Kbps）。

所属接口类

IRtcEngineEventHandler

onUserMuteAudio

远端用户（通信场景）/主播（直播场景）停止或恢复发送音频流回调。

C++
virtual void onUserMuteAudio(uid_t uid, bool muted) {
    (void)uid;
    (void)muted;
    }

详情

该回调是由远端用户调用 muteLocalAudioStream 方法关闭或开启音频发送触发的。

注意

频道内的用户（通信场景）或主播（直播场景）人数超过 17 人时，该回调可能不准确。

参数

uid

用户 ID。

muted

该用户是否静音：

true: 该用户已将音频静音。
false: 该用户取消了音频静音。

所属接口类

IRtcEngineEventHandler

adjustUserPlaybackSignalVolume

调用时机

调用限制

参数​

返回值​

adjustUserPlaybackSignalVolumeEx

调用时机

调用限制

参数​

返回值​

disableAudio

调用时机

调用限制

返回值​

enableAudio

调用时机

调用限制

返回值​

enableAudioVolumeIndication

调用时机

调用限制

相关回调

参数​

返回值​

enableAudioVolumeIndicationEx

调用时机

调用限制

相关回调

参数​

返回值​

setAudioProfile [1/2]

适用场景

调用时机

调用限制

参数​

返回值​

setAudioProfile [2/2]

适用场景

调用时机

调用限制

参数​

返回值​

setAudioScenario

适用场景

调用时机

调用限制

参数​

返回值​

setAudioSessionOperationRestriction

详情​

参数​

返回值​

onActiveSpeaker

详情​

参数​

onAudioQuality

详情​

参数​

onAudioVolumeIndication

详情​

参数​

onFirstLocalAudioFramePublished

详情​

参数​

onFirstRemoteAudioDecoded

详情​

参数​

onFirstRemoteAudioFrame

详情​

参数​

onLocalAudioStateChanged

详情​

参数​

onLocalAudioStats

详情​

参数​

onRemoteAudioStateChanged

详情​

参数​

onRemoteAudioStats

参数

返回值

参数

返回值

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

详情

参数

返回值

详情

参数

详情

参数

详情

参数

详情

参数

详情

参数

详情

参数

详情

参数

详情

参数

详情

参数

详情

参数

详情

参数

详情

参数