音频基础功能

adjustUserPlaybackSignalVolume:volume:

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

Objective-C

- (int)adjustUserPlaybackSignalVolume:(NSUInteger)uid volume:(int)volume;

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

调用时机

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

调用限制

无。

参数

uid

远端用户 ID。

volume

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

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

返回值

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

所属接口类

• AgoraRtcEngineKit

adjustUserPlaybackSignalVolumeEx:volume:connection:

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

Objective-C

- (int)adjustUserPlaybackSignalVolumeEx:(NSUInteger)uid
                              volume:(NSInteger)volume
                          connection:(AgoraRtcConnection* _Nonnull)connection;

自从

v4.1.0

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

调用时机

该方法需要在 joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess: 之后调用。

调用限制

无。

参数

uid

远端用户 ID。

volume

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

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

connection

Connection 信息。详见 AgoraRtcConnection。

返回值

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

所属接口类

• AgoraRtcEngineKitEx

disableAudio

关闭音频模块。

Objective-C

- (int)disableAudio;

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

调用时机

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

调用限制

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

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

返回值

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

所属接口类

• AgoraRtcEngineKit

enableAudio

启用音频模块。

Objective-C

- (int)enableAudio;

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

调用时机

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

调用限制

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

返回值

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

所属接口类

• AgoraRtcEngineKit

enableAudioVolumeIndication:smooth:reportVad:

启用用户音量提示。

Objective-C

- (int)enableAudioVolumeIndication:(NSInteger)interval
                            smooth:(NSInteger)smooth
                            reportVad:(BOOL)reportVad;

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

调用时机

加入频道前后均可调用。

调用限制

无。

相关回调

成功调用该方法、且频道内存在发流用户时，SDK 会按设置的时间间隔触发 rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: 回调。

参数

interval

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

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

smooth

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

reportVad

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

返回值

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

所属接口类

• AgoraRtcEngineKit

enableAudioVolumeIndicationEx:smooth:reportVad:connection:

启用用户音量提示。

Objective-C

- (int)enableAudioVolumeIndicationEx:(NSInteger)interval
                              smooth:(NSInteger)smooth
                           reportVad:(BOOL)reportVad
                          connection:(AgoraRtcConnection* _Nonnull)connection NS_SWIFT_NAME(enableAudioVolumeIndicationEx(_:smooth:reportVad:connection:));

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

调用时机

该方法需要在 joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess: 之后调用。

调用限制

无。

相关回调

成功调用该方法、且频道内存在发流用户时，SDK 会按设置的时间间隔触发 rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: 回调。

参数

interval

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

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

smooth

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

reportVad

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

connection

Connection 信息。详见 AgoraRtcConnection。

返回值

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

所属接口类

• AgoraRtcEngineKitEx

setAudioProfile:scenario:

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

Objective-C

- (int)setAudioProfile:(AgoraAudioProfile)profile scenario:(AgoraAudioScenario)scenario;

废弃

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

适用场景

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

调用时机

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

调用限制

无。

参数

profile

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

scenario

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

返回值

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

所属接口类

• AgoraRtcEngineKit

setAudioProfile:

设置音频编码属性。

Objective-C

- (int)setAudioProfile:(AgoraAudioProfile)profile;

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

适用场景

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

调用时机

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

调用限制

无。

参数

profile

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

返回值

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

所属接口类

• AgoraRtcEngineKit

setAudioScenario:

设置音频场景。

Objective-C

- (int)setAudioScenario:(AgoraAudioScenario)scenario;

适用场景

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

调用时机

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

调用限制

无。

参数

scenario

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

返回值

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

所属接口类

• AgoraRtcEngineKit

rtcEngine:activeSpeaker:

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

Objective-C

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine activeSpeaker:(NSUInteger)speakerUid;

详情

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

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

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

参数

engine

AgoraRtcEngineKit 对象。

speakerUid

远端最活跃用户的 ID。

所属接口类

• AgoraRtcEngineDelegate

audioQualityBlock:

远端声音质量回调。

Objective-C

- (void)audioQualityBlock:(void (^_Nullable)(NSUInteger uid, AgoraNetworkQuality quality, NSUInteger delay, NSUInteger lost))audioQualityBlock

详情

废弃

请改用 rtcEngine:remoteAudioStats:。

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

参数

engine

AgoraRtcEngineKit 对象。

uid

用户 ID，指定是谁发的音频流。

quality

语音质量。详见 AgoraNetworkQuality。

delay

音频包从发送端到接收端的延迟（毫秒），包括声音采样前处理、网络传输、网络抖动缓冲引起的延迟。

lost

音频包从发送端到接收端的丢包率 (%)。

所属接口类

• AgoraRtcEngineDelegate

rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume:

用户音量提示回调。

Objective-C

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine
        reportAudioVolumeIndicationOfSpeakers:(NSArray<AgoraRtcAudioVolumeInfo *> * _Nonnull)speakers
        totalVolume:(NSInteger)totalVolume;

详情

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

注意

在收到该回调后如需更新 UI 界面，请将确保将执行的线程转至 UI 线程中。

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

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

参数

engine

AgoraRtcEngineKit 对象。

speakers

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

totalVolume

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

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

所属接口类

• AgoraRtcEngineDelegate

rtcEngine:firstLocalAudioFramePublished:

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

Objective-C

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine firstLocalAudioFramePublished:(NSInteger)elapsed;

详情

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

• 开启本地音频的情况下，调用 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 成功加入频道后。
• 调用 muteLocalAudioStream:(YES)，再调用 muteLocalAudioStream:(NO) 后。
• 调用 disableAudio，再调用 enableAudio 后。
• 调用 pushExternalAudioFrameRawData:samples:sampleRate:channels:trackId:timestamp: 成功向 SDK 推送音频帧后。

参数

engine

AgoraRtcEngineKit 对象。

elapsed

从调用 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 方法到触发该回调的时间间隔（毫秒）。

所属接口类

• AgoraRtcEngineDelegate

rtcEngine:firstRemoteAudioFrameDecodedOfUid:elapsed:

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

Objective-C

- (void)rtcEngine:(AgoraRtcEngineKit* _Nonnull)engine firstRemoteAudioFrameDecodedOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed;

详情

废弃

请改用 rtcEngine:remoteAudioStateChangedOfUid:state:reason:elapsed: 。

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

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

参数

engine

AgoraRtcEngineKit 对象。

uid

远端用户 ID。

elapsed

从本地用户调用 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 直至该回调触发的延迟，单位为毫秒。

所属接口类

• AgoraRtcEngineDelegate

rtcEngine:firstRemoteAudioFrameOfUid:elapsed:

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

Objective-C

- (void)rtcEngine:(AgoraRtcEngineKit* _Nonnull)engine firstRemoteAudioFrameOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed NS_SWIFT_NAME(rtcEngine(_:firstRemoteAudioFrameOfUid:elapsed:));

详情

废弃

请改用 rtcEngine:remoteAudioStateChangedOfUid:state:reason:elapsed: 。

参数

engine

AgoraRtcEngineKit 对象。

uid

发送音频帧的远端用户的用户 ID。

elapsed

从本地用户调用 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 直至该回调触发的延迟，单位为毫秒。

所属接口类

• AgoraRtcEngineDelegate

rtcEngine:localAudioStateChanged:reason:

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

Objective-C

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine localAudioStateChanged:(AgoraAudioLocalState)state reason:(AgoraAudioLocalReason)reason NS_SWIFT_NAME(rtcEngine(_:localAudioStateChanged:reason:));

详情

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

注意

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

参数

engine

AgoraRtcEngineKit 对象。

state

当前的本地音频状态。详见 AgoraAudioLocalState。

reason

本地音频状态改变原因。详见 AgoraAudioLocalReason。

所属接口类

• AgoraRtcEngineDelegate

rtcEngine:localAudioStats:

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

Objective-C

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine
    localAudioStats:(AgoraRtcLocalAudioStats * _Nonnull)stats;

详情

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

参数

engine

AgoraRtcEngineKit 对象。

stats

本地音频统计数据。详见 AgoraRtcLocalAudioStats。

所属接口类

• AgoraRtcEngineDelegate

rtcEngine:remoteAudioStateChangedOfUid:state:reason:elapsed:

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

Objective-C

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine
     remoteAudioStateChangedOfUid:(NSUInteger)uid state:(AgoraAudioRemoteState)state reason:(AgoraAudioRemoteReason)reason elapsed:(NSInteger)elapsed;

详情

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

注意

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

参数

engine

AgoraRtcEngineKit 对象。

uid

发生音频状态改变的远端用户 ID。

state

远端音频流状态，详见 AgoraAudioRemoteState。

reason

远端音频流状态改变的具体原因，详见 AgoraAudioRemoteReason。

elapsed

从本地用户调用 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 方法到发生本事件经历的时间，单位为毫秒。

所属接口类

• AgoraRtcEngineDelegate

rtcEngine:remoteAudioStats:

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

Objective-C

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine
    remoteAudioStats:(AgoraRtcRemoteAudioStats * _Nonnull)stats;

详情

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

参数

engine

AgoraRtcEngineKit 对象。

stats

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

所属接口类

• AgoraRtcEngineDelegate

rtcEngine:audioTransportStatsOfUid:delay:lost:rxKBitRate:

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

Objective-C

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine
                  audioTransportStatsOfUid:(NSUInteger)uid
                  delay:(NSUInteger)delay
                  lost:(NSUInteger)lost
                  rxKBitRate:(NSUInteger)rxKBitRate;

详情

废弃

请改用 rtcEngine:remoteAudioStats:。

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

参数

engine

AgoraRtcEngineKit 对象。

uid

用户 ID，指定是哪个用户/主播的音频包。

delay

音频包从发送端到接收端的延时（毫秒）。

lost

音频包从发送端到接收端的丢包率 (%)。

rxKBitrate

远端音频包的接收码率（Kbps）。

所属接口类

• AgoraRtcEngineDelegate

rtcEngine:didAudioMuted:byUid:

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

Objective-C

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didAudioMuted:(BOOL)muted byUid:(NSUInteger)uid;

详情

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

注意

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

参数

uid

用户 ID。

muted

该用户是否静音：

• YES: 该用户已将音频静音。
• NO: 该用户取消了音频静音。

所属接口类

• AgoraRtcEngineDelegate