音频基础功能
- Flutter
更新时间不可用
adjustPlaybackSignalVolume
调节本地播放的所有远端用户信号音量。
Future<void> adjustPlaybackSignalVolume(int volume);该方法用于调节所有远端用户混音后在本地播放的信号音量，如果你需要调节指定远端用户在本地播放的信号音量，建议你调用 adjustUserPlaybackSignalVolume。
调用时机
加入频道前后均可调用。
参数
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
adjustUserPlaybackSignalVolume
调节本地播放的指定远端用户信号音量。
Future<void> adjustUserPlaybackSignalVolume(
{required int uid, required int volume});你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量，则需多次调用该方法。
调用时机
该方法需要在加入频道后调用。
参数
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
adjustUserPlaybackSignalVolumeEx
调节本地播放的指定远端用户信号音量。
Future<void> adjustUserPlaybackSignalVolumeEx(
{required int uid,
required int volume,
required RtcConnection connection});你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量，则需多次调用该方法。
调用时机
该方法需要在 joinChannelEx 之后调用。
参数
| 参数名 | 描述 |
|---|---|
uid | |
volume | |
connection | Connection 信息。详见 RtcConnection。 |
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
disableAudio
关闭音频模块。
Future<void> disableAudio();音频模块默认开启，你可以调用该方法关闭音频模块。
注： 该方法重置整个引擎，响应时间较慢，因此声网建议使用如下方法来控制音频模块：
- enableLocalAudio：是否启动麦克风采集并创建本地音频流。
- enableLoopbackRecording：是否开启声卡采集。
- muteLocalAudioStream：是否发布本地音频流。
- muteRemoteAudioStream：是否接收并播放远端音频流。
- muteAllRemoteAudioStreams：是否接收并播放所有远端音频流。
调用时机
加入频道前后均可调用。离开频道后仍然有效。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
enableAudio
启用音频模块。
Future<void> enableAudio();音频模块默认开启。如果你调用 disableAudio 关闭了音频模块，可调用该方法重新开启。
注：
-
调用该方法会重置整个引擎，响应时间较慢。你可以根据实际需求用以下方法来独立控制音频模块的某一项功能：
- enableLocalAudio: 是否启动麦克风采集并创建本地音频流。
- muteLocalAudioStream: 是否发布本地音频流。
- muteRemoteAudioStream: 是否接收并播放远端音频流。
- muteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。
-
在频道内调用该方法时，会重置 enableLocalAudio、muteRemoteAudioStream 和 muteAllRemoteAudioStreams 的设置，需谨慎使用。
调用时机
加入频道前后均可调用。离开频道后仍然有效。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
enableAudioVolumeIndication
启用用户音量提示。
Future<void> enableAudioVolumeIndication(
{required int interval, required int smooth, required bool reportVad});该方法允许 SDK 定期向 App 报告本地发流用户和瞬时音量最高的远端用户（最多 3 位）的音量相关信息。
调用时机
加入频道前后均可调用。
相关回调
成功调用该方法、且频道内存在发流用户时，SDK 会按设置的时间间隔触发 onAudioVolumeIndication 回调。
参数
| 参数名 | 描述 |
|---|---|
interval | 指定音量提示的时间间隔：
|
smooth | |
reportVad |
|
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
enableAudioVolumeIndicationEx
启用用户音量提示。
Future<void> enableAudioVolumeIndicationEx(
{required int interval,
required int smooth,
required bool reportVad,
required RtcConnection connection});该方法允许 SDK 定期向 App 报告本地发流用户和瞬时音量最高的远端用户（最多 3 位）的音量相关信息。
调用时机
该方法需要在 joinChannelEx 之后调用。
相关回调
成功调用该方法、且频道内存在发流用户时，SDK 会按设置的时间间隔触发 onAudioVolumeIndication 回调。
参数
| 参数名 | 描述 |
|---|---|
interval | 指定音量提示的时间间隔：
|
smooth | |
reportVad |
|
connection | Connection 信息。详见 RtcConnection。 |
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
所属接口类
setAudioProfile
设置音频编码属性和音频场景。
Future<void> setAudioProfile(
{required AudioProfileType profile,
AudioScenarioType scenario = AudioScenarioType.audioScenarioDefault});注： 由于 iOS 系统限制，部分音频路由在通话音量模式下无法识别。因此，如需使用外接声卡，建议将音频应用场景设置为高音质场景 audioScenarioGameStreaming(3)。在这种场景下，SDK 会切换到媒体音量规避该问题。
适用场景
该方法适用于各种音频场景，你可以按需选择。例如，在音乐教学等高音质需求的场景中，建议将 profile 设置为 AudioProfileMusicHighQuality(4)，scenario 设置为 AudioScenarioGameStreaming(3)。
调用时机
该方法在加入频道前后均可调用。
参数
| 参数名 | 描述 |
|---|---|
profile | 音频编码属性，包含采样率、码率、编码模式和声道数。详见 AudioProfileType。 |
scenario | 音频场景。不同的音频场景下，设备的音量类型是不同的。 详见 AudioScenarioType 。 |
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
setAudioScenario
设置音频场景。
Future<void> setAudioScenario(AudioScenarioType scenario);注： 由于 iOS 系统限制，部分音频路由在通话音量模式下无法识别。因此，如需使用外接声卡，建议将音频应用场景设置为高音质场景 audioScenarioGameStreaming(3)。在这种场景下，SDK 会切换到媒体音量规避该问题。
适用场景
该方法适用于各种音频场景，你可以按需选择。例如，在音乐教学等高音质需求的场景中，建议将 scenario 设置为 AudioScenarioGameStreaming(3)。
调用时机
该方法在加入频道前后均可调用。
参数
| 参数名 | 描述 |
|---|---|
scenario | 音频场景。不同的音频场景下，设备的音量类型是不同的。 详见 AudioScenarioType 。 |
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
setAudioSessionOperationRestriction
设置 SDK 对 Audio Session 的操作权限。
Future<void> setAudioSessionOperationRestriction(
AudioSessionOperationRestriction 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 的操作权限，详见 AudioSessionOperationRestriction。该参数为 Bit Mask，每个 Bit 对应一个权限。 |
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
onActiveSpeaker
监测到远端最活跃用户回调。
final void Function(RtcConnection connection, int uid)? onActiveSpeaker;成功调用 enableAudioVolumeIndication 后，SDK 会持续监测音量最大的远端用户，并统计该用户被判断为音量最大者的次数。当前时间段内，该次数累积最多的远端用户为最活跃的用户。
当频道内用户数量大于或等于 2 且有远端活跃用户时，SDK 会触发该回调并报告远端最活跃用户的 uid。
- 如果远端最活跃用户一直是同一位用户，则 SDK 不会再次触发 onActiveSpeaker 回调。
- 如果远端最活跃用户有变化，则 SDK 会再次触发该回调并报告新的远端最活跃用户的
uid。
参数
| 参数名 | 描述 |
|---|---|
connection | Connection 信息。详见 RtcConnection。 |
uid |
所属接口类
onAudioQuality
远端声音质量回调。
final void Function(RtcConnection connection, int remoteUid,
QualityType quality, int delay, int lost)? onAudioQuality;废弃
弃用： 请改用 onRemoteAudioStats。
该回调描述远端用户在通话中的音频质量，针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播，该回调每 2 秒会被触发多次。
参数
| 参数名 | 描述 |
|---|---|
connection | Connection 信息。详见 RtcConnection。 |
remoteUid | |
quality | 语音质量。详见 QualityType。 |
delay | |
lost |
所属接口类
onAudioVolumeIndication
用户音量提示回调。
final void Function(RtcConnection connection, List<AudioVolumeInfo> speakers,
int speakerNumber, int totalVolume)? onAudioVolumeIndication;该回调默认禁用，你可以通过 enableAudioVolumeIndication 开启。 开启后，只要频道内有发流用户，SDK 会在加入频道后按 enableAudioVolumeIndication 中设置的时间间隔触发 onAudioVolumeIndication 回调。每次会触发两个 onAudioVolumeIndication 回调，一个报告本地发流用户的音量相关信息，另一个报告瞬时音量最高的远端用户（最多 3 位）的音量相关信息。
注： 启用该功能后，如果有用户将自己静音（调用了 muteLocalAudioStream），SDK 会继续报告本地用户的音量提示回调。 瞬时音量最高的远端用户静音后 20 秒，远端的音量提示回调中将不再包含该用户；如果远端所有用户都将自己静音，20 秒后 SDK 停止报告远端用户的音量提示回调。
参数
| 参数名 | 描述 |
|---|---|
connection | Connection 信息。详见 RtcConnection。 |
speakers | 用户音量信息，详见 AudioVolumeInfo 数组。如果 |
speakerNumber | |
totalVolume |
所属接口类
onFirstLocalAudioFramePublished
已发布本地音频首帧回调。
final void Function(RtcConnection connection, int elapsed)?
onFirstLocalAudioFramePublished;SDK 会在以下时机触发该回调：
- 开启本地音频的情况下，调用 joinChannel 成功加入频道后。
- 调用 muteLocalAudioStream(
true)，再调用 muteLocalAudioStream(false)后。 - 调用 disableAudio，再调用 enableAudio 后。
参数
| 参数名 | 描述 |
|---|---|
connection | Connection 信息。详见 RtcConnection。 |
elapsed | 从调用 joinChannel 方法到触发该回调的时间间隔（毫秒）。 |
所属接口类
onFirstRemoteAudioDecoded
已解码远端音频首帧的回调。
final void Function(RtcConnection connection, int uid, int elapsed)?
onFirstRemoteAudioDecoded;废弃
弃用： 请改用 onRemoteAudioStateChanged 。
SDK 会在以下时机触发该回调：
-
远端用户首次上线后发送音频。
-
远端用户音频离线再上线发送音频。音频离线指本地在 15 秒内没有收到音频包，可能有如下原因：
- 远端用户离开频道
- 远端用户掉线
- 远端用户调用 muteLocalAudioStream 方法停止发送音频流
- 远端用户调用 disableAudio 方法关闭音频
参数
| 参数名 | 描述 |
|---|---|
connection | Connection 信息。详见 RtcConnection。 |
uid | |
elapsed | 从本地用户调用 joinChannel 直至该回调触发的延迟，单位为毫秒。 |
所属接口类
onFirstRemoteAudioFrame
已接收远端音频首帧回调。
final void Function(RtcConnection connection, int userId, int elapsed)?
onFirstRemoteAudioFrame;废弃
弃用： 请改用 onRemoteAudioStateChanged 。
参数
| 参数名 | 描述 |
|---|---|
connection | Connection 信息。详见 RtcConnection。 |
userId | |
elapsed | 从本地用户调用 joinChannel 直至该回调触发的延迟，单位为毫秒。 |
所属接口类
onLocalAudioStateChanged
本地音频状态发生改变回调。
final void Function(RtcConnection connection, LocalAudioStreamState state,
LocalAudioStreamReason reason)? onLocalAudioStateChanged;本地音频的状态发生改变时（包括本地麦克风采集状态和音频编码状态），SDK 会触发该回调报告当前的本地音频状态。在本地音频出现故障时，该回调可以帮助你了解当前音频的状态以及出现故障的原因，方便你排查问题。
注： 当状态为 localAudioStreamStateFailed (3) 时， 你可以在 error 参数中查看返回的错误信息。
参数
| 参数名 | 描述 |
|---|---|
connection | Connection 信息。详见 RtcConnection。 |
state | 当前的本地音频状态。详见 LocalAudioStreamState。 |
reason | 本地音频状态改变原因。详见 LocalAudioStreamReason。 |
所属接口类
onLocalAudioStats
通话中本地音频流的统计信息回调。
final void Function(RtcConnection connection, LocalAudioStats stats)?
onLocalAudioStats;SDK 每 2 秒触发该回调一次。
参数
| 参数名 | 描述 |
|---|---|
connection | Connection 信息。详见 RtcConnection。 |
stats | 本地音频统计数据。详见 LocalAudioStats。 |
所属接口类
onRemoteAudioStateChanged
远端音频流状态发生改变回调。
final void Function(
RtcConnection connection,
int remoteUid,
RemoteAudioState state,
RemoteAudioStateReason reason,
int elapsed)? onRemoteAudioStateChanged;远端用户（通信场景）或主播（直播场景）的音频状态发生改变时，SDK 会触发该回调向本地用户报告当前的远端音频流状态。
注： 频道内的用户（通信场景）或主播（直播场景）人数超过 32 人时，该回调可能不准确。
参数
| 参数名 | 描述 |
|---|---|
connection | Connection 信息。详见 RtcConnection。 |
remoteUid | |
state | 远端音频流状态，详见 RemoteAudioState。 |
reason | 远端音频流状态改变的具体原因，详见 RemoteAudioStateReason。 |
elapsed | 从本地用户调用 joinChannel 方法到发生本事件经历的时间，单位为毫秒。 |
所属接口类
onRemoteAudioStats
通话中远端音频流的统计信息回调。
final void Function(RtcConnection connection, RemoteAudioStats stats)?
onRemoteAudioStats;该回调针对每个发送音频流的远端用户/主播每 2 秒触发一次。如果远端有多个用户/主播发送音频流，该回调每 2 秒会被触发多次。
参数
| 参数名 | 描述 |
|---|---|
connection | Connection 信息。详见 RtcConnection。 |
stats | 接收到的远端音频统计数据，详见 RemoteAudioStats。 |
所属接口类
onRemoteAudioTransportStats
通话中远端音频流传输的统计信息回调。
final void Function(RtcConnection connection, int remoteUid, int delay,
int lost, int rxKBitRate)? onRemoteAudioTransportStats;弃用： 请改用 onRemoteAudioStats。 该回调描述远端用户通话中端到端的网络统计信息，通过音频包计算，用客观的数据，如丢包、 网络延迟等，展示当前网络状态。通话中，当用户收到远端用户/主播发送的音频数据包后，会每 2 秒触发一次该回调。
参数
| 参数名 | 描述 |
|---|---|
connection | Connection 信息。详见 RtcConnection。 |
remoteUid | |
delay | |
lost | |
rxKBitrate |
所属接口类
onUserMuteAudio
远端用户（通信场景）/主播（直播场景）停止或恢复发送音频流回调。
final void Function(RtcConnection connection, int remoteUid, bool muted)?
onUserMuteAudio;该回调是由远端用户调用 muteLocalAudioStream 方法关闭或开启音频发送触发的。
注： 频道内的用户（通信场景）或主播（直播场景）人数超过 32 人时，该回调可能不准确。
参数
| 参数名 | 描述 |
|---|---|
connection | Connection 信息。详见 RtcConnection。 |
remoteUid | |
muted |