音频基础功能
adjustPlaybackSignalVolume:
调节所有远端用户的播放信号音量。
- (int)adjustPlaybackSignalVolume:(NSInteger)volume NS_SWIFT_NAME(adjustPlaybackSignalVolume(_:));
该方法用于调节本地混音播放的所有远端用户的信号音量。如果你需要调节本地播放的指定远端用户的信号音量，建议调用 adjustUserPlaybackSignalVolume: 方法。
调用时机
该方法可以在加入频道前或后调用。
参数
- volume
- 用户的音量。取值范围为 [0,400]。
- 0：静音。
- 100：（默认）原始音量。
- 400：原始音量的四倍（将音频信号放大四倍）。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
adjustUserPlaybackSignalVolume:volume:
调整指定远端用户的播放音量。
- (int)adjustUserPlaybackSignalVolume:(NSUInteger)uid volume:(int)volume NS_SWIFT_NAME(adjustUserPlaybackSignalVolume(_:volume:));
你可以调用该方法调整指定远端用户的播放音量。若需调整多个远端用户的播放音量，请分别多次调用该方法，每次针对一个远端用户。
调用时机
请在加入频道后调用此方法。
参数
- uid
- 远端用户的用户 ID。
- volume
- 用户的音量，取值范围为 [0,400]。
- 0：静音。
- 100：（默认）原始音量。
- 400：原始音量的四倍（将音频信号放大四倍）。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
adjustUserPlaybackSignalVolumeEx:volume:connection:
调节指定远端用户的播放信号音量。
- (int)adjustUserPlaybackSignalVolumeEx:(NSUInteger)uid
volume:(NSInteger)volume
connection:(AgoraRtcConnection* _Nonnull)connection;
你可以调用此方法调节指定远端用户的播放音量。若需调节多个远端用户的播放音量，请分别多次调用此方法，每次针对一个远端用户。
适用场景
该方法适用于多频道场景。
调用时机
请在调用 joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess: 之后调用此方法。
参数
- uid
- 远端用户的用户 ID。
- volume
- 用户的音量，取值范围为 [0,400]。
- 0：静音。
- 100：（默认）原始音量。
- 400：原始音量的四倍（将音频信号放大四倍）。
- connection
- 连接信息。详见 AgoraRtcConnection。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
disableAudio
禁用音频模块。
- (int)disableAudio NS_SWIFT_NAME(disableAudio());
音频模块默认启用。你可以调用该方法禁用音频模块。
- enableLocalAudio:：是否启用麦克风以创建本地音频流。
- （仅适用于 macOS）
enableLoopbackRecording:deviceName:：是否启用回采音频采集。 - muteLocalAudioStream:：是否发布本地音频流。
- muteRemoteAudioStream:mute:：是否订阅并播放远端音频流。
- muteAllRemoteAudioStreams:：是否订阅并播放所有远端音频流。
调用时机
该方法可以在加入频道前或加入频道后调用。离开频道后仍然有效。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
enableAudio
启用音频模块。
- (int)enableAudio NS_SWIFT_NAME(enableAudio());
音频模块默认处于启用状态。你在调用 disableAudio 方法禁用音频模块后，可以调用该方法重新启用音频模块。
- 调用该方法会重置整个引擎，导致响应时间变慢。你可以根据实际需求，使用以下方法分别控制音频模块的具体功能：
- enableLocalAudio:：是否启用麦克风以创建本地音频流。
- muteLocalAudioStream:：是否发布本地音频流。
- muteRemoteAudioStream:mute:：是否订阅并播放远端音频流。
- muteAllRemoteAudioStreams:：是否订阅并播放所有远端音频流。
- 成功调用该方法会重置 enableLocalAudio:、muteRemoteAudioStream:mute: 和 muteAllRemoteAudioStreams: 的设置，请谨慎使用。
调用时机
该方法可以在加入频道前或加入频道后调用，离开频道后仍然有效。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
enableAudioVolumeIndication:smooth:reportVad:
启用用户音量提示的上报功能。
- (int)enableAudioVolumeIndication:(NSInteger)interval
smooth:(NSInteger)smooth
reportVad:(BOOL)reportVad NS_SWIFT_NAME(enableAudioVolumeIndication(_:smooth:reportVad:));
该方法用于启用 SDK 定期向你报告本地发送音频流用户和瞬时音量最高的最多三位远端用户的音量信息。
调用时机
该方法可以在加入频道前或后调用。
参数
- interval
- 设置两次音量提示之间的时间间隔（单位为毫秒）：
- ≤ 0：关闭音量提示功能。
- > 0：两次音量提示之间的时间间隔。确保该参数值大于 10，否则你将无法收到 rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: 回调。建议设置为大于 100。
- smooth
- 设置音量提示的灵敏度平滑系数，取值范围为 0 到 10，推荐值为 3。数值越大，音量提示越灵敏。
- reportVad
- 是否启用本地用户的语音活动检测（Voice Activity Detection）：
- YES：启用语音活动检测。启用后，rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: 回调中的
vad参数会报告本地用户的语音活动状态。 - NO：（默认）关闭语音活动检测。关闭后，除非引擎自动检测本地用户的语音活动，否则
vad参数不会报告本地用户的语音活动状态。
- YES：启用语音活动检测。启用后，rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: 回调中的
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
enableAudioVolumeIndicationEx:smooth:reportVad:connection:
启用用户音量提示的上报功能。
- (int)enableAudioVolumeIndicationEx:(NSInteger)interval
smooth:(NSInteger)smooth
reportVad:(BOOL)reportVad
connection:(AgoraRtcConnection* _Nonnull)connection NS_SWIFT_NAME(enableAudioVolumeIndicationEx(_:smooth:reportVad:connection:));
该方法用于启用 SDK 定期向发送音频流的本地用户和音量瞬时值最高的最多三位远端用户的应用程序上报音量信息。
适用场景
该方法适用于多频道场景。
调用时机
请在调用 joinChannelExByToken 之后调用该方法。
相关回调
成功调用该方法后，若频道中有用户发布流，SDK 会根据设置的时间间隔触发 rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: 回调，报告音量信息。
参数
- interval
- 设置两次音量提示之间的时间间隔（毫秒）：
- ≤ 0：关闭音量提示功能。
- > 0：两次音量提示之间的时间间隔（单位为毫秒）。确保该参数值大于 10，否则你将无法收到 rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: 回调。声网建议将该值设置为大于 100。
- smooth
- 设置音量提示灵敏度的平滑系数，取值范围为 [0, 10]，推荐值为 3。值越大，提示越灵敏。
- reportVad
- 是否启用本地用户的语音活动检测（Voice Activity Detection）：
- YES：启用本地用户的语音活动检测。启用后，rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: 回调中的
vad参数会报告本地用户的语音活动状态。 - NO：（默认）关闭本地用户的语音活动检测。关闭后，rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: 回调中的
vad参数不会报告本地用户的语音活动状态，除非引擎自动检测到本地用户的语音活动。
- YES：启用本地用户的语音活动检测。启用后，rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: 回调中的
- connection
- 连接信息。详见 AgoraRtcConnection。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
setAudioProfile:scenario:
设置音频配置和音频场景。
- (int)setAudioProfile:(AgoraAudioProfile)profile scenario:(AgoraAudioScenario)scenario NS_SWIFT_NAME(setAudioProfile(_:scenario:)) __deprecated_msg("use setAudioProfile: instead.");
该方法适用于多种音频场景，可根据需要选择。例如，在音乐教学等对音质要求较高的场景中，建议将 profile 设置为 AgoraAudioProfileMusicHighQuality（4），将 scenario 设置为 AgoraAudioScenarioGameStreaming（3）。
AgoraAudioScenarioGameStreaming（3）。在该场景下，SDK 会切换为媒体音量以避免该问题。适用场景
该方法适用于多种音频场景，你可以根据实际需求进行选择。例如，在对音质要求较高的场景（如音乐教学）中，建议将 profile 设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY（4），将 scenario 设置为 AUDIO_SCENARIO_GAME_STREAMING（3）。你可以在加入频道前或加入频道后调用该方法。
调用时机
你可以在加入频道前或加入频道后调用该方法。
参数
- profile
- 音频配置，包括采样率、码率、编码模式和声道数。详见 AgoraAudioProfile。
- scenario
- 音频场景。在不同的音频场景下，设备使用不同的音量类型。详见 AgoraAudioScenario。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
setAudioProfile:
设置音频配置。
- (int)setAudioProfile:(AgoraAudioProfile)profile NS_SWIFT_NAME(setAudioProfile(_:));
如果你需要设置音频场景，可以调用 setAudioScenario:，或者调用 sharedEngineWithConfig:delegate: 并在 AgoraRtcEngineConfig 中设置 audioScenario。
适用场景
你可以根据实际需求选择合适的音频配置文件。例如，在音乐教学等对音质要求较高的场景中，建议将 profile 设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY（4）。如果你需要设置音频场景，可以调用 setAudioScenario:，或者调用 sharedEngineWithConfig:delegate: 并在 AgoraRtcEngineConfig 中设置 audioScenario。
调用时机
你可以在加入频道前或后调用该方法。
参数
- profile
- 音频配置，包括采样率、码率、编码模式和声道数。详见 AgoraAudioProfile。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
setAudioScenario:
设置音频场景。
- (int)setAudioScenario:(AgoraAudioScenario)scenario NS_SWIFT_NAME(setAudioScenario(_:));
该方法适用于多种音频场景。你可以根据需要进行选择。例如，在音乐教学等对音质要求较高的场景中，建议将 scenario 设置为 AgoraAudioScenarioGameStreaming（3）。
AgoraAudioScenarioGameStreaming（3）。在该场景下，SDK 会切换为媒体音量以避免该问题。适用场景
该方法适用于多种音频场景。例如，在对音质要求较高的音乐教学场景中，建议将 scenario 设置为 AUDIO_SCENARIO_GAME_STREAMING（3）。
调用时机
你可以在加入频道前或后调用该方法。
参数
- scenario
- 音频场景。在不同的音频场景下，设备使用不同的音量类型。详见 AgoraAudioScenario。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
setAudioSessionOperationRestriction:
设置 SDK 对音频会话的操作权限。
- (void)setAudioSessionOperationRestriction:(AgoraAudioSessionOperationRestriction)restriction NS_SWIFT_NAME(setAudioSessionOperationRestriction(_:));
默认情况下，SDK 和 App 都可以配置音频会话。如果你只需要使用 App 来配置音频会话，可以通过该方法限制 SDK 对音频会话的操作权限。你可以在加入频道前或后调用该方法。一旦调用该方法限制 SDK 的操作权限，该限制会在 SDK 需要更改音频会话时生效。
参数
- restriction
- SDK 对音频会话的操作权限。该参数为位掩码格式，每一位对应一个权限。详见 AgoraAudioSessionOperationRestriction。
rtcEngine:activeSpeaker:
检测到最活跃的远端说话人时触发的回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine activeSpeaker:(NSUInteger)speakerUid NS_SWIFT_NAME(rtcEngine(_:activeSpeaker:));
enableAudioVolumeIndication 方法后，SDK 会持续检测哪位远端用户的音量最大。在当前周期内，音量被检测为最大次数最多的远端用户即为最活跃用户。当频道中用户数不少于两人且存在活跃的远端说话人时，SDK 会触发该回调并报告最活跃远端说话人的用户 ID（speakerUid）。 - 如果最活跃的远端说话人始终是同一用户，SDK 只会触发一次该回调。
- 如果最活跃的远端说话人变更为其他用户，SDK 会再次触发该回调并报告新的最活跃远端说话人的用户 ID。
触发时机
该回调在检测到最活跃的远端说话人时被触发。
参数
- engine
- 引擎实例。详见 AgoraRtcEngineKit。
- speakerUid
- 最活跃远端说话用户的用户 ID。
audioQualityBlock:
当前通话的音频质量，每两秒报告一次。
- (void)audioQualityBlock:(void(^ _Nullable)(NSUInteger uid, AgoraNetworkQuality quality, NSUInteger delay, NSUInteger lost))audioQualityBlock NS_SWIFT_NAME(audioQualityBlock(_:)) __deprecated_msg("use delegate instead.");
remoteAudioStats。参数
- audioQualityBlock
- 回调 block，包含以下内容：
uid：说话者的用户 ID。quality：网络质量，详见 AgoraNetworkQuality。delay：时延，单位为毫秒。lost：丢包率，单位为 %。
rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume:
报告用户音量信息的回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine reportAudioVolumeIndicationOfSpeakers:(NSArray<AgoraRtcAudioVolumeInfo *> * _Nonnull)speakers totalVolume:(NSInteger)totalVolume NS_SWIFT_NAME(rtcEngine(_:reportAudioVolumeIndicationOfSpeakers:totalVolume:));
你可以通过调用 enableAudioVolumeIndication 方法开启该回调。开启后，当用户在频道中发送音频流时，SDK 会根据 enableAudioVolumeIndication 中设置的时间间隔触发该回调。SDK 会同时触发两个独立的回调，分别报告发送音频流的本地用户和瞬时音量最高的最多三位远端用户的音量信息。
muteLocalAudioStream 方法进行静音，SDK 仍会继续报告本地用户的音量信息。如果频道中音量排名前三的远端用户停止发布音频流超过 20 秒，回调中将不再包含该用户的信息；如果所有远端用户都停止发布音频流超过 20 秒，SDK 将不再触发远端用户的音量回调。触发时机
该回调在启用音量提示并有用户发送音频流时被触发。
参数
- engine
- speakers
- 用户的音量信息。详见 AgoraRtcAudioVolumeInfo。当该数组为空时，表示频道中没有远端用户或远端用户未发送音频流。
- totalVolume
- 扬声器的音量，取值范围为 [0, 255]。
- 对于本地用户的回调，
totalVolume是发送音频流的本地用户的音量。 - 对于远端用户的回调，
totalVolume是瞬时音量最高的最多三位远端用户的音量总和。如果你调用了startAudioMixing，则totalVolume是混音后的音量。
- 对于本地用户的回调，
rtcEngine:firstLocalAudioFramePublished:
本地音频首帧发布回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine firstLocalAudioFramePublished:(NSInteger)elapsed NS_SWIFT_NAME(rtcEngine(_:firstLocalAudioFramePublished:));
- 启用音频模块并成功调用
joinChannelByToken加入频道。 - 依次调用
muteLocalAudioStream（设为 YES）和muteLocalAudioStream（设为 NO）。 - 依次调用 disableAudio 和 enableAudio。
- 调用
pushExternalAudioFrameRawData成功向 SDK 推送自定义音频帧。
触发时机
该回调在本地音频首帧成功发布时被触发。
参数
- engine
- elapsed
- 从调用
joinChannelByToken到 SDK 触发该回调的时间间隔（毫秒）。
rtcEngine:firstRemoteAudioFrameDecodedOfUid:elapsed:
当 SDK 解码来自某个远端用户的首帧音频时触发回调。
- (void)rtcEngine:(AgoraRtcEngineKit* _Nonnull)engine firstRemoteAudioFrameDecodedOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed NS_SWIFT_NAME(rtcEngine(_:firstRemoteAudioFrameDecodedOfUid:elapsed:)) __deprecated_msg("use rtcEngine:remoteAudioStateChangedOfUid:state:reason:elapsed: instead.");
触发时机
该回调在 SDK 解码来自某个远端用户的首帧音频时被触发。
参数
- engine
- uid
- 远端用户的用户 ID。
- elapsed
- 从调用 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 方法到 SDK 触发该回调的时间间隔（毫秒）。
rtcEngine:firstRemoteAudioFrameOfUid:elapsed:
rtcEngine:firstRemoteAudioFrameOfUid:elapsed: 回调。远端用户的第一帧音频被接收并解码时触发。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine firstRemoteAudioFrameOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed NS_SWIFT_NAME(rtcEngine(_:firstRemoteAudioFrameOfUid:elapsed:));
触发时机
该回调在接收到并解码远端用户的第一帧音频时触发。
参数
- engine
- 声网引擎实例。详见 AgoraRtcEngineKit。
- uid
- 远端用户 ID。
- elapsed
- 从本地用户调用
joinChannelByToken到该回调被触发的时间（毫秒）。
rtcEngine:localAudioStateChanged:reason:
本地音频流状态发生变化时的回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine localAudioStateChanged:(AgoraAudioLocalState)state reason:(AgoraAudioLocalReason)reason NS_SWIFT_NAME(rtcEngine(_:localAudioStateChanged:reason:));
当本地音频流状态（包括音频采集和编码状态）发生变化时，SDK 会触发该回调以报告当前状态，便于你在出现音频异常时排查问题。
AgoraAudioLocalStateFailed（3）时，可以在 error 参数中查看错误信息。触发时机
该回调在本地音频流状态发生变化时被触发。
参数
- engine
- state
- 本地音频的状态。详见 AgoraAudioLocalState。
- reason
- 本地音频状态变化的原因。详见 AgoraAudioLocalReason。
rtcEngine:localAudioStats:
上报本地音频流的统计信息。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine localAudioStats:(AgoraRtcLocalAudioStats * _Nonnull)stats NS_SWIFT_NAME(rtcEngine(_:localAudioStats:));
触发时机
该回调每两秒触发一次。
参数
- engine
- stats
- 本地音频统计信息，详见 AgoraRtcLocalAudioStats。
rtcEngine:remoteAudioStateChangedOfUid:state:reason:elapsed:
远端音频状态发生变化回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine remoteAudioStateChangedOfUid:(NSUInteger)uid state:(AgoraAudioRemoteState)state reason:(AgoraAudioRemoteReason)reason elapsed:(NSInteger)elapsed NS_SWIFT_NAME(rtcEngine(_:remoteAudioStateChangedOfUid:state:reason:elapsed:));
当语音/视频通话频道中的远端用户，或直播频道中的主播的音频状态发生变化时，SDK 会触发该回调以报告远端音频流的当前状态。
触发时机
该回调在远端用户的音频状态发生变化时被触发。
参数
- engine
- uid
- 音频状态发生变化的远端用户 ID。
- state
- 远端音频的状态，详见 AgoraAudioRemoteState。
- reason
- 远端音频状态变化的原因，详见 AgoraAudioRemoteReason。
- elapsed
- 从调用
joinChannelByToken方法到 SDK 触发该回调的时间（毫秒）。
rtcEngine:remoteAudioStats:
上报每个远端音频流的传输层统计信息。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine remoteAudioStats:(AgoraRtcRemoteAudioStats * _Nonnull)stats NS_SWIFT_NAME(rtcEngine(_:remoteAudioStats:));
该回调每两秒触发一次，用于上报每个正在发送音频流的远端用户的传输层统计信息。如果频道中有多个远端用户，SDK 会分别为每个用户触发该回调。
触发时机
该回调每两秒触发一次。
参数
- engine
- stats
- 接收的远端音频流的统计信息，详见 AgoraRtcRemoteAudioStats。
rtcEngine:audioTransportStatsOfUid:delay:lost:rxKBitRate:
报告每个远端音频流的传输层统计信息。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine audioTransportStatsOfUid:(NSUInteger)uid delay:(NSUInteger)delay lost:(NSUInteger)lost rxKBitRate:(NSUInteger)rxKBitRate NS_SWIFT_NAME(rtcEngine(_:audioTransportStatsOfUid:delay:lost:rxKBitRate:)) __deprecated_msg("use rtcEngine:remoteAudioStats: instead");
触发时机
该回调在通话过程中，当你接收到远端用户发送的音频包时，每 2 秒触发一次。
参数
- engine
- 引擎对象，详见 AgoraRtcEngineKit。
- uid
- 发送音频流的远端用户 ID。
- delay
- 从远端用户到接收端的网络时延（毫秒）。
- lost
- 从远端用户到接收端的音频包丢包率（%）。
- rxKBitRate
- 接收到的音频码率（Kbps）。
rtcEngine:didAudioMuted:byUid:
rtcEngine:didAudioMuted:byUid: 回调。当远端用户或主播停止或恢复发送音频流时触发。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didAudioMuted:(BOOL)muted byUid:(NSUInteger)uid NS_SWIFT_NAME(rtcEngine(_:didAudioMuted:byUid:));
当远端用户调用 muteLocalAudioStream: 方法停止或恢复发送音频流时，SDK 会触发该回调。
触发时机
该回调在远端用户或主播停止或恢复发送音频流时被触发。
参数
- engine
- muted
- 远端用户的音频流是否被静音：
- YES：用户的音频流被静音。
- NO：用户的音频流未被静音。
- uid
- 远端用户 ID。