人声音效

setAdvancedAudioOptions

设置音频的高级选项。

Objective-C

- (int)setAdvancedAudioOptions:(AgoraAdvancedAudioOptions * _Nonnull)options;

如果你对音频处理有进阶需求，例如需要采集和发送立体声，可以调用该方法设置音频的高级选项。

注意： 你需要在 joinChannelByToken [2/4]、enableAudio 和 enableLocalAudio 前调用该方法。

参数

参数名	描述
options	音频的高级选项。详见 AgoraAdvancedAudioOptions。

返回值

• 0: 方法调用成功。

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

所属接口类

• AgoraRtcEngineKit

setAINSMode

设置是否开启 AI 降噪功能并设置降噪模式。

Objective-C

- (int)setAINSMode:(BOOL)enabled mode:(AUDIO_AINS_MODE)mode NS_SWIFT_NAME(setAINSMode(_:mode:));

自从

v4.2.0

你可以调用开方法来开启 AI 降噪功能。该功能可以在保证语音质量的前提下，智能化检测并降低周围环境中多种稳态与非稳态噪声，使人声更加清晰。 稳态噪声指在任何时间点上都具有相同频率的噪声，常见的稳态噪声有：

• 电视机噪声

• 空调噪声

• 工厂机器噪声等

非稳态噪声是指随时间而快速变化的噪声，常见的非稳态噪声有：

• 雷声

• 爆炸声

• 破裂声等

参数

参数名	描述
enabled	是否开启 AI 降噪功能： YES：开启 AI 降噪功能。 NO：（默认）关闭 AI 降噪功能。
mode	降噪模式，详见 AUDIO_AINS_MODE。

返回值

• 0: 方法调用成功。

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

所属接口类

• AgoraRtcEngineKit

setAudioEffectParameters

设置 SDK 预设人声音效的参数。

Objective-C

- (int)setAudioEffectParameters:(AgoraAudioEffectPreset)preset param1:(int)param1 param2:(int)param2;

调用该方法可以对本地发流用户进行如下设置：

• 3D 人声音效：设置 3D 人声音效的环绕周期。

• 电音音效：设置电音音效的基础调式和主音音高。为方便用户自行调节电音音效，建议你将基础调式和主音音高配置选项与应用的 UI 元素绑定。

设置后，频道内所有用户都能听到该效果。

注意：

• 该方法在加入频道前后都能调用。

• 为获取更好的人声效果，建议你在调用该方法前将 setAudioProfile [1/2] 的 scenario 设为 AgoraAudioScenarioGameStreaming(3)。

• 请勿将 setAudioProfile [1/2] 的 profile 参数设置为 AgoraAudioProfileSpeechStandard(1)，否则该方法不生效。

• 该方法对人声的处理效果最佳，不建议调用该方法处理含音乐的音频数据。

• 调用 setAudioEffectParameters 后，不建议调用以下方法，否则 setAudioEffectParameters 设置的效果会被覆盖：

  • setAudioEffectPreset

  • setVoiceBeautifierPreset

  • setLocalVoicePitch

  • setLocalVoiceEqualizationOfBandFrequency

  • setLocalVoiceReverbOfType

  • setVoiceBeautifierParameters

  • setVoiceConversionPreset

参数

参数名	描述
preset	SDK 预设的音效，支持以下设置： AgoraAudioEffectPresetRoomAcous3DVoice，3D 人声音效。 你需要在使用该枚举前将 setAudioProfile [1/2] 的 profile 参数设置 为 AgoraAudioProfileMusicStandardStereo(3) 或 AgoraAudioProfileMusicHighQualityStereo(5)，否则该枚举设置无效。 启用 3D 人声后，用户需要使用支持双声道的音频播放设备才能听到预期效果。 AgoraAudioEffectPresetPitchCorrection，电音音效。为获取更好的人声效果，建议你在使用该枚举前将 setAudioProfile [1/2] 的 profile 参数设置为 AgoraAudioProfileMusicHighQuality(4) 或 AgoraAudioProfileMusicHighQualityStereo(5)。
param1	如果 preset 设为 AgoraAudioEffectPresetRoomAcous3DVoice ，则 param1 表示 3D 人声音效的环绕周期。取值范围为 [1,60]，单位为秒。默认值为 10，表示人声会 10 秒环绕 360 度。 如果 preset 设为 AgoraAudioEffectPresetPitchCorrection，则 param1 表示电音音效的基础调式： 1: （默认）自然大调。 2: 自然小调。 3: 和风小调。
param2	如果 preset 设为 AgoraAudioEffectPresetRoomAcous3DVoice，你需要将 param2 设置为 0。 如果 preset 设为 AgoraAudioEffectPresetPitchCorrection，则 param2 表示电音音效的主音音高： 1: A 2: A# 3: B 4: (Default) C 5: C# 6: D 7: D# 8: E 9: F 10: F# 11: G 12: G#

返回值

• 0: 方法调用成功。

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

所属接口类

• AgoraRtcEngineKit

setAudioEffectPreset

设置 SDK 预设的人声音效。

Objective-C

- (int)setAudioEffectPreset:(AgoraAudioEffectPreset)preset;

调用该方法可以为本地发流用户设置 SDK 预设的人声音效，且不会改变原声的性别特征。设置音效后，频道内所有用户都能听到该效果。

为获取更好的人声效果，建议你在调用该方法前将 setAudioProfile [1/2] 的 scenario 设为 AgoraAudioScenarioGameStreaming(3)。

注意：

• 该方法在加入频道前后都能调用。

• 请勿将 setAudioProfile [1/2] 的 profile 参数设置为 AgoraAudioProfileSpeechStandard(1)，否则该方法不生效。

• 该方法对人声的处理效果最佳，不建议调用该方法处理含音乐的音频数据。

• 如果调用 setAudioEffectPreset 并设置除 AgoraAudioEffectPresetRoomAcous3DVoice 或 AgoraAudioEffectPresetPitchCorrection 外的枚举，请勿再调用 setAudioEffectParameters，否则 setAudioEffectPreset 设置的效果会被覆盖。

• 调用 setAudioEffectPreset 后，不建议调用以下方法，否则 setAudioEffectPreset 设置的效果会被覆盖：

  • setVoiceBeautifierPreset

  • setLocalVoicePitch

  • setLocalVoiceEqualizationOfBandFrequency

  • setLocalVoiceReverbOfType

  • setVoiceBeautifierParameters

  • setVoiceConversionPreset

• 该方法依赖于美声动态库 AgoraAudioBeautyExtension.xcframework，如果删除该动态库会导致无法正常开启该功能。

参数

参数名	描述
preset	预设的音效选项，详见 AgoraAudioEffectPreset。

返回值

• 0: 方法调用成功。

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

所属接口类

• AgoraRtcEngineKit

setLocalVoiceEqualizationOfBandFrequency

设置本地语音音效均衡。

Objective-C

- (int)setLocalVoiceEqualizationOfBandFrequency:(AgoraAudioEqualizationBandFrequency)bandFrequency
                    withGain:(NSInteger)gain;

注意： 该方法在加入频道前后都能调用。

参数

参数名	描述
bandFrequency	频谱子带索引。取值范围是 [0,9]，分别代表音效的 10 个频带。对应的中心频率为 [31，62，125，250，500，1k，2k，4k，8k，16k] Hz。详见 AgoraAudioEqualizationBandFrequency 。
gain	每个 band 的增益，单位是 dB，每一个值的范围是 [-15,15]，默认值为 0。

返回值

• 0: 方法调用成功。

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

所属接口类

• AgoraRtcEngineKit

setLocalVoiceFormant

设置共振峰比率以改变语音的音色。

Objective-C

- (int)setLocalVoiceFormant:(double)formantRatio;

自从

v4.2.0

共振峰比率是影响声音音色的一个参数，共振峰比率取值越小声音会更低沉，取值越大声音会更尖锐。

在语音直播、语聊房、K 歌房等场景中，你可以调用该方法设置本地语音的共振峰比率参数从而改变音色效果。设置共振峰比率后，频道内所有用户都能听到该效果。如果你想要在调整音色的同时改变音调，声网推荐你搭配 setLocalVoicePitch 一起使用。 注意： 该方法在加入频道前后均可调用。

参数

参数名	描述
formantRatio	共振峰比率，取值范围为 [-1.0，1.0]。默认值为 0.0，即不改变原声的音色。 注： 声网推荐的取值范围为 [-0.4，0.6] ，超出此范围外音效听感可能不佳。

返回值

• 0: 方法调用成功。

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

所属接口类

• AgoraRtcEngineKit

setLocalVoicePitch

设置本地语音音调。

Objective-C

- (int)setLocalVoicePitch:(double)pitch;

注意： 该方法在加入频道前后都能调用。

参数

参数名	描述
pitch	语音频率。可以 [0.5,2.0] 范围内设置。取值越小，则音调越低。默认值为 1.0，表示不需要修改音调。

返回值

• 0: 方法调用成功。

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

所属接口类

• AgoraRtcEngineKit

setLocalVoiceReverbOfType

设置本地音效混响。

Objective-C

- (int)setLocalVoiceReverbOfType:(AgoraAudioReverbType)reverbType withValue:(NSInteger)value;

SDK 提供一个使用更为简便的方法 setAudioEffectPreset，直接实现流行、R&B、KTV 等预置的混响效果。

注： 该方法在加入频道前后都能调用。

参数

参数名	描述
reverbType	混响音效 Key。该方法共有 5 个混响音效 Key，详见 AgoraAudioReverbType。
value	各混响音效 Key 所对应的值。

返回值

• 0: 方法调用成功。

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

所属接口类

• AgoraRtcEngineKit

setVoiceBeautifierParameters

设置预设美声效果的参数。

Objective-C

- (int)setVoiceBeautifierParameters:(AgoraVoiceBeautifierPreset)preset param1:(int)param1 param2:(int)param2;

调用该方法可以设置歌唱美声效果的性别特征和混响效果。该方法对本地发流用户进行设置。设置后，频道内所有用户都能听到该效果。

为获取更好的人声效果，建议你在调用该方法前将 setAudioProfile [1/2] 的 scenario 设为 AgoraAudioScenarioGameStreaming(3)，并将 profile 设为 AgoraAudioProfileMusicHighQuality(4) 或 AgoraAudioProfileMusicHighQualityStereo(5)。

注意：

• 该方法在加入频道前后都能调用。

• 请勿将 setAudioProfile [1/2] 的 profile 参数设置为 AgoraAudioProfileSpeechStandard(1)，否则该方法不生效。

• 该方法对人声的处理效果最佳，不建议调用该方法处理含音乐的音频数据。

• 调用 setVoiceBeautifierParameters，不建议调用以下方法，否则 setVoiceBeautifierParameters 设置的效果会被覆盖：

  • setAudioEffectPreset

  • setAudioEffectParameters

  • setVoiceBeautifierPreset

  • setLocalVoicePitch

  • setLocalVoiceEqualizationOfBandFrequency

  • setLocalVoiceReverbOfType

  • setVoiceConversionPreset

参数

参数名	描述
preset	预设的音效： SINGING_BEAUTIFIER: 歌唱美声。
param1	歌声的性别特征： 1: 男声。 2: 女声。
param2	歌声的混响效果： 1: 歌声在小房间的混响效果。 2: 歌声在大房间的混响效果。 3: 歌声在大厅的混响效果。

返回值

• 0: 方法调用成功。

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

所属接口类

• AgoraRtcEngineKit

setVoiceBeautifierPreset

设置预设的美声效果。

Objective-C

- (int)setVoiceBeautifierPreset:(AgoraVoiceBeautifierPreset)preset;

调用该方法可以为本地发流用户设置预设的人声美化效果。设置美声效果后，频道内所有用户都能听到该效果。根据不同的场景，你可以为用户设置不同的美声效果。各美声效果的适用场景可参考设置人声效果。

为获取更好的人声效果，建议你在调用该方法前将 setAudioProfile [1/2] 的 scenario 设为 AgoraAudioScenarioGameStreaming(3)，并将 profile 设为 AgoraAudioProfileMusicHighQuality(4) 或 AgoraAudioProfileMusicHighQualityStereo(5)。

注意：

• 该方法在加入频道前后都能调用。

• 请勿将 setAudioProfile [1/2] 的 profile 参数设置为 AgoraAudioProfileSpeechStandard(1)，否则该方法不生效。

• 该方法对人声的处理效果最佳，不建议调用该方法处理含音乐的音频数据。

• 调用 setVoiceBeautifierPreset，不建议调用以下方法，否则 setVoiceBeautifierPreset 设置的效果会被覆盖：

  • setAudioEffectPreset

  • setAudioEffectParameters

  • setLocalVoicePitch

  • setLocalVoiceEqualizationOfBandFrequency

  • setLocalVoiceReverbOfType

  • setVoiceBeautifierParameters

  • setVoiceConversionPreset

• 该方法依赖于美声动态库 AgoraAudioBeautyExtension.xcframework，如果删除该动态库会导致无法正常开启该功能。

参数

参数名	描述
preset	预设的美声效果选项，详见 AgoraVoiceBeautifierPreset。

返回值

• 0: 方法调用成功。

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

所属接口类

• AgoraRtcEngineKit

setVoiceConversionPreset

设置预设的变声效果。

Objective-C

- (int)setVoiceConversionPreset:(AgoraVoiceConversionPreset)preset;

调用该方法可以为本地发流用户设置 SDK 预设的变声效果。设置变声效果后，频道内所有用户都能听到该效果。根据不同的场景，你可以为用户设置不同的变声效果。各变声效果的适用场景可参考《设置人声效果》。

为获取更好的人声效果，建议你在调用该方法前将 setAudioProfile [1/2] 的 profile 设为 AgoraAudioProfileMusicHighQuality(4) 或 AgoraAudioProfileMusicHighQualityStereo(5)，并将 scenario 设为 AgoraAudioScenarioGameStreaming(3)。

注意：

• 该方法在加入频道前后都能调用。

• 请勿将 setAudioProfile [1/2] 的 profile 参数设置为 AgoraAudioProfileSpeechStandard(1)，否则该方法不生效。

• 该方法对人声的处理效果最佳，不建议调用该方法处理含音乐的音频数据。

• 调用 setVoiceConversionPreset 后，不建议调用以下方法，否则 setVoiceConversionPreset 设置的效果会被覆盖：

  • setAudioEffectPreset

  • setAudioEffectParameters

  • setVoiceBeautifierPreset

  • setVoiceBeautifierParameters

  • setLocalVoicePitch

  • setLocalVoiceFormant

  • setLocalVoiceEqualizationOfBandFrequency

  • setLocalVoiceReverbOfType

• 该方法依赖于美声动态库 AgoraAudioBeautyExtension.xcframework，如果删除该动态库会导致无法正常开启该功能。

参数

参数名	描述
preset	预设的变声效果选项: AgoraVoiceConversionPreset。

返回值

• 0：方法调用成功。

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

所属接口类

• AgoraRtcEngineKit