音频基础功能
AdjustUserPlaybackSignalVolume
调节本地播放的指定远端用户信号音量。
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
int AdjustUserPlaybackSignalVolume(int64 uid, int volume);
你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量，则需多次调用该方法。
调用时机
该方法需要在加入频道后调用。
调用限制
无。
参数
- uid
- 远端用户 ID。
- volume
- 音量，取值范围为 [0,400]。
- 0: 静音。
- 100: （默认）原始音量。
- 400: 原始音量的 4 倍，自带溢出保护。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
AdjustUserPlaybackSignalVolumeEx
调节本地播放的指定远端用户信号音量。
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
int AdjustUserPlaybackSignalVolumeEx(int64 uid, int volume, const FRtcConnection& connection);
你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量，则需多次调用该方法。
调用时机
该方法需要在 JoinChannelEx 之后调用。
调用限制
无。
参数
- uid
- 远端用户 ID。
- volume
- 音量，取值范围为 [0,400]。
- 0: 静音。
- 100: （默认）原始音量。
- 400: 原始音量的 4 倍，自带溢出保护。
- connection
- Connection 信息。详见 FRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
DisableAudio
关闭音频模块。
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
int DisableAudio();
音频模块默认开启，你可以调用该方法关闭音频模块。
调用时机
加入频道前后均可调用。离开频道后仍然有效。
调用限制
- EnableLocalAudio：是否启动麦克风采集并创建本地音频流。
- EnableLoopbackRecording：是否开启声卡采集。
- MuteLocalAudioStream：是否发布本地音频流。
- MuteRemoteAudioStream：是否接收并播放远端音频流。
- MuteAllRemoteAudioStreams：是否接收并播放所有远端音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
EnableAudio
启用音频模块。
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
int EnableAudio();
音频模块默认开启。如果你调用 DisableAudio 关闭了音频模块，可调用该方法重新开启。
调用时机
加入频道前后均可调用。离开频道后仍然有效。
调用限制
- 调用该方法会重置整个引擎，响应时间较慢。你可以根据实际需求用以下方法来独立控制音频模块的某一项功能：
- EnableLocalAudio: 是否启动麦克风采集并创建本地音频流。
- MuteLocalAudioStream: 是否发布本地音频流。
- MuteRemoteAudioStream: 是否接收并播放远端音频流。
- MuteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。
- 在频道内调用该方法时，会重置 EnableLocalAudio、MuteRemoteAudioStream 和 MuteAllRemoteAudioStreams 的设置，需谨慎使用。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
EnableAudioVolumeIndication
启用用户音量提示。
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
int EnableAudioVolumeIndication(int interval, int smooth, bool 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
启用用户音量提示。
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
int EnableAudioVolumeIndicationEx(int interval, int smooth, bool reportVad, const FRtcConnection& 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 信息。详见 FRtcConnection。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
SetAudioProfileAndScenario
设置音频编码属性和音频场景。
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
int SetAudioProfileAndScenario(EAUDIO_PROFILE_TYPE profile = EAUDIO_PROFILE_TYPE::AUDIO_PROFILE_DEFAULT, EAUDIO_SCENARIO_TYPE scenario = EAUDIO_SCENARIO_TYPE::AUDIO_SCENARIO_DEFAULT);
适用场景
该方法适用于各种音频场景，你可以按需选择。例如，在音乐教学等高音质需求的场景中，建议将 profile 设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)，scenario 设置为 AUDIO_SCENARIO_GAME_STREAMING(3)。
调用时机
该方法在加入频道前后均可调用。
调用限制
由于 iOS 系统限制，部分音频路由在通话音量模式下无法识别。因此，如需使用外接声卡，建议将音频应用场景设置为高音质场景 AUDIO_SCENARIO_GAME_STREAMING(3)。在这种场景下，SDK 会切换到媒体音量规避该问题。
参数
- profile
音频编码属性，包含采样率、码率、编码模式和声道数。详见 EAUDIO_PROFILE_TYPE。
- scenario
- 音频场景。不同的音频场景下，设备的音量类型是不同的。 详见 EAUDIO_SCENARIO_TYPE 。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetAudioProfile
设置音频编码属性。
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
int SetAudioProfile(EAUDIO_PROFILE_TYPE profile = EAUDIO_PROFILE_TYPE::AUDIO_PROFILE_DEFAULT);
如果你想设置音频应用场景，可以直接调用 SetAudioScenario 方法进行设置，也可以调用 Initialize 并设置 FRtcEngineContext 结构体中的 audioScenario。
适用场景
该方法适用于各种音频场景，你可以按需选择。例如，在音乐教学等高音质需求的场景中，建议将 profile 设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)。
调用时机
该方法在加入频道前后均可调用。
调用限制
无。
参数
- profile
音频编码属性，包含采样率、码率、编码模式和声道数。详见 EAUDIO_PROFILE_TYPE。
SetAudioScenario
设置音频场景。
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
int SetAudioScenario(EAUDIO_SCENARIO_TYPE scenario = EAUDIO_SCENARIO_TYPE::AUDIO_SCENARIO_DEFAULT);
适用场景
该方法适用于各种音频场景，你可以按需选择。例如，在音乐教学等高音质需求的场景中，建议将 scenario 设置为 AUDIO_SCENARIO_GAME_STREAMING(3)。
调用时机
该方法在加入频道前后均可调用。
调用限制
由于 iOS 系统限制，部分音频路由在通话音量模式下无法识别。因此，如需使用外接声卡，建议将音频应用场景设置为高音质场景 AUDIO_SCENARIO_GAME_STREAMING(3)。在这种场景下，SDK 会切换到媒体音量规避该问题。
参数
- scenario
- 音频场景。不同的音频场景下，设备的音量类型是不同的。 详见 EAUDIO_SCENARIO_TYPE 。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetAudioSessionOperationRestriction
设置 SDK 对 Audio Session 的操作权限。
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
int SetAudioSessionOperationRestriction(EAUDIO_SESSION_OPERATION_RESTRICTION restriction);
详情
默认情况下，SDK 和 App 对 Audio Session 都有操作权限。如果你只需使用 App 对 Audio Session 进行操作，你可以调用该方法限制 SDK 对 Audio Session 的操作权限。
该方法在加入频道前后都能调用。一旦调用该方法限制了 SDK 对 Audio Session 的操作权限，该限制会在 SDK 需要更改 Audio Session 时生效。
- 该方法仅适用于 iOS 平台。
- 该方法不会限制 App 对 Audio Session 的操作权限。
参数
- restriction
- SDK 对 Audio Session 的操作权限，详见 EAUDIO_SESSION_OPERATION_RESTRICTION。该参数为 Bit Mask，每个 Bit 对应一个权限。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
OnActiveSpeaker
监测到远端最活跃用户回调。
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
void OnActiveSpeaker(int64 uid);
详情
成功调用 EnableAudioVolumeIndication 后，SDK 会持续监测音量最大的远端用户，并统计该用户被判断为音量最大者的次数。当前时间段内，该次数累积最多的远端用户为最活跃的用户。
- 如果远端最活跃用户一直是同一位用户，则 SDK 不会再次触发 OnActiveSpeaker 回调。
- 如果远端最活跃用户有变化，则 SDK 会再次触发该回调并报告新的远端最活跃用户的 uid。
参数
- userId
- 远端最活跃用户的 ID。
OnAudioQuality
远端声音质量回调。
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
void OnAudioQuality(int64 uid, int quality, int delay, int 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
用户音量提示回调。
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
void OnAudioVolumeIndication(const TArray<FAudioVolumeInfo>& speakers, int totalVolume);
详情
该回调默认禁用，你可以通过 EnableAudioVolumeIndication 开启。 开启后，只要频道内有发流用户，SDK 会在加入频道后按 EnableAudioVolumeIndication 中设置的时间间隔触发 OnAudioVolumeIndication 回调。每次会触发两个 OnAudioVolumeIndication 回调，一个报告本地发流用户的音量相关信息，另一个报告瞬时音量最高的远端用户（最多 3 位）的音量相关信息。
启用该功能后，如果有用户将自己静音（调用了 MuteLocalAudioStream），SDK 会继续报告本地用户的音量提示回调。
瞬时音量最高的远端用户静音后 20 秒，远端的音量提示回调中将不再包含该用户；如果远端所有用户都将自己静音，20 秒后 SDK 停止报告远端用户的音量提示回调。
参数
- speakers
- 用户音量信息，详见 FAudioVolumeInfo 数组。如果 speakers 为空，则表示远端用户不发流或没有远端用户。
- totalVolume
- 混音后的总音量，取值范围为 [0,255]。
- 在本地用户的回调中，totalVolume 为本地发流用户的音量。
- 在远端用户的回调中，totalVolume 为瞬时音量最高的远端用户（最多 3 位）混音后的总音量。 如果用户调用了 StartAudioMixing，则 totalVolume 为音乐文件和用户声音的总音量。
OnFirstLocalAudioFramePublished
已发布本地音频首帧回调。
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
void OnFirstLocalAudioFramePublished(int elapsed);
详情
- 开启本地音频的情况下，调用 JoinChannelWithOptions 成功加入频道后。
- 调用 MuteLocalAudioStream(
true)，再调用 MuteLocalAudioStream(false)后。 - 调用 DisableAudio，再调用 EnableAudio 后。
参数
- elapsed
- 从调用 JoinChannelWithOptions 方法到触发该回调的时间间隔（毫秒）。
OnFirstRemoteAudioDecoded
已解码远端音频首帧的回调。
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
void OnFirstRemoteAudioDecoded(int64 uid, int elapsed);
详情
- 远端用户首次上线后发送音频。
- 远端用户音频离线再上线发送音频。音频离线指本地在 15 秒内没有收到音频包，可能有如下原因：
- 远端用户离开频道
- 远端用户掉线
- 远端用户调用 MuteLocalAudioStream 方法停止发送音频流
- 远端用户调用 DisableAudio 方法关闭音频
参数
- uid
- 远端用户 ID。
- elapsed
- 从本地用户调用 JoinChannelWithOptions 直至该回调触发的延迟，单位为毫秒。
OnFirstRemoteAudioFrame
OnLocalAudioStateChanged
本地音频状态发生改变回调。
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
void OnLocalAudioStateChanged(ELOCAL_AUDIO_STREAM_STATE state, ELOCAL_AUDIO_STREAM_REASON reason);
详情
本地音频的状态发生改变时（包括本地麦克风采集状态和音频编码状态），SDK 会触发该回调报告当前的本地音频状态。在本地音频出现故障时，该回调可以帮助你了解当前音频的状态以及出现故障的原因，方便你排查问题。
参数
- state
- 当前的本地音频状态。详见 ELOCAL_AUDIO_STREAM_STATE。
- reason
- 本地音频状态改变原因。详见 ELOCAL_AUDIO_STREAM_REASON。
OnLocalAudioStats
通话中本地音频流的统计信息回调。
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
void OnLocalAudioStats(const FLocalAudioStats& stats);
详情
SDK 每 2 秒触发该回调一次。
参数
- stats
- 本地音频统计数据。详见 FLocalAudioStats。
OnRemoteAudioStateChanged
远端音频流状态发生改变回调。
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
void OnRemoteAudioStateChanged(int64 uid, EREMOTE_AUDIO_STATE state, EREMOTE_AUDIO_STATE_REASON reason, int elapsed);
详情
远端用户（通信场景）或主播（直播场景）的音频状态发生改变时，SDK 会触发该回调向本地用户报告当前的远端音频流状态。
参数
- uid
- 发生音频状态改变的远端用户 ID。
- state
- 远端音频流状态，详见 EREMOTE_AUDIO_STATE。
- reason
- 远端音频流状态改变的具体原因，详见 EREMOTE_AUDIO_STATE_REASON。
- elapsed
- 从本地用户调用 JoinChannelWithOptions 方法到发生本事件经历的时间，单位为毫秒。
OnRemoteAudioStats
通话中远端音频流的统计信息回调。
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
void OnRemoteAudioStats(const FRemoteAudioStats& stats);
详情
该回调针对每个发送音频流的远端用户/主播每 2 秒触发一次。如果远端有多个用户/主播发送音频流，该回调每 2 秒会被触发多次。
参数
- stats
- 接收到的远端音频统计数据，详见 FRemoteAudioStats。
OnRemoteAudioTransportStats
通话中远端音频流传输的统计信息回调。
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
void OnRemoteAudioTransportStats(int64 uid, int delay, int lost, int rxKBitRate);
详情
该回调描述远端用户通话中端到端的网络统计信息，通过音频包计算，用客观的数据，如丢包、 网络延迟等，展示当前网络状态。通话中，当用户收到远端用户/主播发送的音频数据包后 ，会每 2 秒触发一次该回调。
参数
- uid
- 用户 ID，指定是哪个用户/主播的音频包。
- delay
- 音频包从发送端到接收端的延时（毫秒）。
- lost
- 音频包从发送端到接收端的丢包率 (%)。
- rxKBitrate
- 远端音频包的接收码率（Kbps）。
OnUserMuteAudio
远端用户（通信场景）/主播（直播场景）停止或恢复发送音频流回调。
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
void OnUserMuteAudio(int64 uid, bool muted);
详情
该回调是由远端用户调用 MuteLocalAudioStream 方法关闭或开启音频发送触发的。
参数
- uid
- 用户 ID。
- muted
- 该用户是否静音：
true: 该用户已将音频静音。false: 该用户取消了音频静音。