人声音效

enableVoiceAITuner:type:

启用或关闭语音 AI 调音器。

Objective-C

- (int)enableVoiceAITuner:(BOOL)enabled type:(AgoraVoiceAITunerType)type NS_SWIFT_NAME(enableVoiceAITuner(_:type:));

支持增强音质和调整音色风格。

适用场景

社交娱乐场景，包括在线 KTV、在线播客和展厅直播等对音质要求较高的场景。

调用时机

你可以在加入频道前或后调用该方法。

参数

enabled

是否启用语音 AI 调音器：

• YES：启用语音 AI 调音器。
• NO：（默认）关闭语音 AI 调音器。

type

语音 AI 调音器的音效类型，详见 AgoraVoiceAITunerType。

返回值

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

所属接口类

• AgoraRtcEngineKit

setAdvancedAudioOptions:

设置音频高级选项。

Objective-C

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

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

信息

请在调用 joinChannelByToken、enableAudio 和 enableLocalAudio 之后调用此方法。

参数

options

音频的高级选项，详见 AgoraAdvancedAudioOptions。

返回值

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

所属接口类

• AgoraRtcEngineKit

setAINSMode:mode:

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

Objective-C

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

你可以调用此方法启用 AI 降噪功能。启用后，SDK 会在保证人声质量的前提下，自动检测并减少音频中的稳定噪声和非稳定噪声。 稳定噪声是指在观察时间内平均统计特性恒定、音量波动极小的噪声信号。常见的稳定噪声来源包括：

• 电视；
• 空调；
• 机械设备等。

非稳定噪声是指在观察时间内音量波动剧烈的噪声信号。常见的非稳定噪声来源包括：

• 雷声；
• 爆炸声；
• 破裂声等。

信息

该方法依赖 AI 降噪动态库 AgoraAiNoiseSuppressionExtension.xcframework。如果该动态库被删除，则无法启用该功能。

适用场景

在连麦、在线教育和视频会议等场景中，该功能可检测并减少背景噪声，从而提升体验。

调用时机

你可以在加入频道前或加入频道后调用此方法。

参数

enabled

是否启用 AI 降噪功能：

• YES：启用 AI 降噪功能。
• NO：（默认）关闭 AI 降噪功能。

mode

AI 降噪模式，详见 AUDIO_AINS_MODE。

返回值

0：方法调用成功。 < 0：方法调用失败。

所属接口类

• AgoraRtcEngineKit

setAudioEffectParameters:param1:param2:

设置 SDK 预设音效的参数。

Objective-C

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

调用该方法可为发送音频流的本地用户设置以下参数：

• 3D 人声效果：设置 3D 人声效果的循环周期。
• 音高修正效果：设置音高修正效果的基本调式和主音。

不同的歌曲有不同的调式和主音。声网建议将该方法与界面元素绑定，以便你交互式地调整音高修正效果。设置音效参数后，频道内所有用户都能听到效果。为了获得更好的人声效果，建议你在调用该方法前调用以下 API：

• 调用 setAudioScenario: 将音频场景设置为高音质音频场景，即 AgoraAudioScenarioGameStreaming（3）。
• 调用 setAudioProfile: 将 profile 参数设置为 AgoraAudioProfileMusicHighQuality（4）或 AgoraAudioProfileMusicHighQualityStereo（5）。

信息

• 你可以在加入频道前或加入频道后调用该方法。
• 不要将 setAudioProfile: 中的 profile 参数设置为 AgoraAudioProfileSpeechStandard（1），否则该方法不生效。
• 该方法在人声处理方面效果最佳，声网不建议使用该方法处理包含音乐的音频数据。
• 调用 setAudioEffectParameters:param1:param2: 后，不建议再调用以下方法，否则会覆盖该方法设置的效果：
  • setAudioEffectPreset:
  • setVoiceBeautifierPreset:
  • setLocalVoicePitch:
  • setLocalVoiceEqualizationOfBandFrequency:withGain:
  • setLocalVoiceReverbOfType:withValue:
  • setVoiceBeautifierParameters:param1:param2:
  • setVoiceConversionPreset:
• 该方法依赖于语音美声动态库 AgoraAudioBeautyExtension.xcframework（iOS）或 AgoraAudioBeautyExtension.framework（macOS）。如果该动态库被删除，则无法正常启用该功能。

参数

preset

SDK 预设音效的选项，详见 AgoraAudioEffectPreset：

• AgoraAudioEffectPresetRoomAcous3DVoice（10）：3D 人声效果。
  • 在设置该枚举值前，你需要将 setAudioProfile: 中的 profile 参数设置为 AgoraAudioProfileMusicStandardStereo（3）或 AgoraAudioProfileMusicHighQualityStereo（5），否则设置不生效。
  • 启用 3D 人声效果后，用户需使用立体声播放设备才能听到预期效果。
• AgoraAudioEffectPresetPitchCorrection（11）：音高修正效果。

param1

• 如果将 preset 设置为 AgoraAudioEffectPresetRoomAcous3DVoice，该参数表示 3D 人声效果的循环周期，单位为秒，取值范围为 [1, 60]。默认值为 10，表示声音每 10 秒环绕一次。
• 如果将 preset 设置为 AgoraAudioEffectPresetPitchCorrection，该参数表示音高修正效果的基本调式：
  • 1：（默认）自然大调。
  • 2：自然小调。
  • 3：日本五声音阶。

param2

• 如果将 preset 设置为 AgoraAudioEffectPresetRoomAcous3DVoice，你需要将该参数设置为 0。
• 如果将 preset 设置为 AgoraAudioEffectPresetPitchCorrection，该参数表示音高修正效果的主音：
  • 1：A
  • 2：A#
  • 3：B
  • 4：（默认）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 NS_SWIFT_NAME(setAudioEffectPreset(_:));

你可以调用该方法为发送音频流的本地用户设置声网预设的音效效果。该音效不会改变原始声音的性别特征。设置后，频道内所有用户都能听到该音效效果。 建议你在调用该方法前，先调用以下 API 以获得更好的人声效果：

• 调用 setAudioScenario: 将音频场景设置为高音质音频场景，即 AgoraAudioScenarioGameStreaming（3）。
• 调用 setAudioProfile: 将 profile 参数设置为 AgoraAudioProfileMusicHighQuality（4）或 AgoraAudioProfileMusicHighQualityStereo（5）。

信息

• 不要将 setAudioProfile: 中的 profile 参数设置为 AgoraAudioProfileSpeechStandard（1），否则该方法不生效。
• 如果调用 setAudioEffectPreset: 并设置的枚举值不是 AgoraAudioEffectPresetRoomAcous3DVoice 或 AgoraAudioEffectPresetPitchCorrection，请不要调用 setAudioEffectParameters:param1:param2:，否则 setAudioEffectPreset: 的设置会被覆盖。
• 调用 setAudioEffectPreset: 后，声网不建议你再调用以下方法，否则 setAudioEffectPreset: 设置的效果会被覆盖：
  • setVoiceBeautifierPreset:
  • setLocalVoicePitch:
  • setLocalVoiceEqualizationOfBandFrequency:withGain:
  • setLocalVoiceReverbOfType:withValue:
  • setVoiceBeautifierParameters:param1:param2:
  • setVoiceConversionPreset:
• 该方法依赖于美声特效动态库 AgoraAudioBeautyExtension.xcframework（iOS）或 AgoraAudioBeautyExtension.framework（macOS）。如果该动态库被删除，则无法正常启用该功能。

调用时机

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

参数

preset

声网预设的音效选项，详见 AgoraAudioEffectPreset。

返回值

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

所属接口类

• AgoraRtcEngineKit

setLocalVoiceEqualizationOfBandFrequency:withGain:

设置本地语音的均衡效果。

Objective-C

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

调用时机

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

参数

bandFrequency

频段频率，详见 AgoraAudioEqualizationBandFrequency。取值范围为 0 到 9，分别对应语音特效的 10 个中心频率段：31、62、125、250、500、1k、2k、4k、8k 和 16k Hz。

gain

每个频段的增益值，单位为 dB。取值范围为 -15 到 15，默认值为 0。

返回值

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

所属接口类

• AgoraRtcEngineKit

setLocalVoiceFormant:

设置共振峰比例以改变人声音色。

Objective-C

- (int)setLocalVoiceFormant:(double)formantRatio;

共振峰比例会影响声音的音色。值越小，声音越低沉；值越大，声音越尖锐。设置共振峰比例后，频道内所有用户都能听到改变后的声音。如果你希望同时改变音色和音调，声网建议同时使用 setLocalVoiceFormant: 和 setLocalVoicePitch: 方法。

适用场景

你可以调用该方法设置本地音频的共振峰比例，以改变人声音色。

调用时机

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

参数

formantRatio

共振峰比例。取值范围为 [-1.0, 1.0]。默认值为 0.0，表示不改变声音的音色。

信息

声网建议将该值设置在 [-0.4, 0.6] 范围内，否则声音可能会严重失真。

返回值

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

所属接口类

• AgoraRtcEngineKit

setLocalVoicePitch:

改变本地语音的音调。

Objective-C

- (int)setLocalVoicePitch:(double)pitch NS_SWIFT_NAME(setLocalVoicePitch(_:));

调用时机

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

参数

pitch

本地语音的音调。取值范围为 [0.5, 2.0]，值越小，音调越低。默认值为 1.0（默认），表示不改变音调。

返回值

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

所属接口类

• AgoraRtcEngineKit

setLocalVoiceReverbOfType:withValue:

设置本地语音的混响效果。

Objective-C

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

你可以在加入频道前或加入频道后调用该方法。SDK 提供了更易用的方法 setAudioEffectPreset:，可直接实现如流行、R&B 和 KTV 等预设混响效果。

参数

reverbType

混响键。详见 AgoraAudioReverbType。

value

混响键的取值。

返回值

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

所属接口类

• AgoraRtcEngineKit

setVoiceBeautifierParameters:param1:param2:

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

Objective-C

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

调用该方法为美声特效设置性别特征和混响效果。该方法为发送音频流的本地用户设置参数。设置完成后，频道内所有用户都能听到该效果。为了获得更好的人声效果，建议在调用本方法前调用以下 API：

• 调用 setAudioScenario: 将音频场景设置为高音质音频场景，即 AgoraAudioScenarioGameStreaming（3）。
• 调用 setAudioProfile: 将 profile 参数设置为 AgoraAudioProfileMusicHighQuality（4）或 AgoraAudioProfileMusicHighQualityStereo（5）。

信息

• 你可以在加入频道前或加入频道后调用该方法。
• 请勿将 setAudioProfile: 中的 profile 参数设置为 AgoraAudioProfileSpeechStandard（1），否则该方法不生效。
• 该方法对人声处理效果最佳，不建议用于处理包含音乐的音频数据。
• 调用 setVoiceBeautifierParameters:param1:param2: 后，不建议再调用以下方法，否则会覆盖该方法设置的效果：
  • setAudioEffectPreset:
  • setAudioEffectParameters:param1:param2:
  • setVoiceBeautifierPreset:
  • setLocalVoicePitch:
  • setLocalVoiceEqualizationOfBandFrequency:withGain:
  • setLocalVoiceReverbOfType:withValue:
  • setVoiceConversionPreset:
• 该方法依赖于美声特效动态库 AgoraAudioBeautyExtension.xcframework（iOS）或 AgoraAudioBeautyExtension.framework（macOS）。如果该动态库被删除，功能将无法正常启用。

参数

preset

预设音效选项。详见 AgoraVoiceBeautifierPreset。

• SINGING_BEAUTIFIER：美声特效。

param1

歌声的性别特征选项：

• 1：男性音色。
• 2：女性音色。

param2

歌声的混响效果选项：

• 1：小房间混响效果。
• 2：大房间混响效果。
• 3：大厅混响效果。

返回值

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

所属接口类

• AgoraRtcEngineKit

setVoiceBeautifierPreset:

设置预设的美声特效。

Objective-C

- (int)setVoiceBeautifierPreset:(AgoraVoiceBeautifierPreset)preset NS_SWIFT_NAME(setVoiceBeautifierPreset(_:));

调用该方法为发送音频流的本地用户设置预设的美声特效。设置后，频道内所有用户都能听到该特效。你可以根据不同场景设置不同的美声特效。

信息

• 不要将 setAudioProfile: 中的 profile 参数设置为 AgoraAudioProfileSpeechStandard（1），否则该方法不生效。
• 此方法对人声处理效果最佳，不建议用于处理包含音乐的音频数据。
• 调用 setVoiceBeautifierPreset: 后，不建议再调用以下方法，否则会覆盖该方法设置的效果：
  • setAudioEffectPreset:
  • setAudioEffectParameters:param1:param2:
  • setLocalVoicePitch:
  • setLocalVoiceEqualizationOfBandFrequency:withGain:
  • setLocalVoiceReverbOfType:withValue:
  • setVoiceBeautifierParameters:param1:param2:
  • setVoiceConversionPreset:
• 此方法依赖于美声特效动态库 AgoraAudioBeautyExtension.xcframework（iOS）或 AgoraAudioBeautyExtension.framework（macOS）。如果该动态库被删除，则无法正常启用该功能。

调用时机

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

参数

preset

预设的美声特效选项，详见 AgoraVoiceBeautifierPreset。

返回值

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

所属接口类

• AgoraRtcEngineKit

setVoiceConversionPreset:

设置预设的变声效果。

Objective-C

- (int)setVoiceConversionPreset:(AgoraVoiceConversionPreset)preset NS_SWIFT_NAME(setVoiceConversionPreset(_:));

调用该方法为在频道中发布音频流的本地用户设置预设的变声效果。设置后，频道内所有用户都能听到该变声效果。你可以根据不同的场景为用户设置不同的变声效果。

信息

• 不要将 setAudioProfile: 中的 profile 参数设置为 AgoraAudioProfileSpeechStandard（1），否则该方法不生效。
• 该方法对人声处理效果最佳，声网不建议使用该方法处理包含音乐的音频数据。
• 调用 setVoiceConversionPreset: 后，声网不建议你再调用以下方法，否则会覆盖 setVoiceConversionPreset: 设置的效果：
  • setAudioEffectPreset:
  • setAudioEffectParameters:param1:param2:
  • setVoiceBeautifierPreset:
  • setVoiceBeautifierParameters:param1:param2:
  • setLocalVoicePitch:
  • setLocalVoiceFormant:
  • setLocalVoiceEqualizationOfBandFrequency:withGain:
  • setLocalVoiceReverbOfType:withValue:
• 该方法依赖于美声特效动态库 AgoraAudioBeautyExtension.xcframework（iOS）或 AgoraAudioBeautyExtension.framework（macOS）。如果该动态库被删除，则无法正常启用该功能。

调用时机

该方法可以在加入频道前或加入频道后调用。为获得更好的音效，建议在调用该方法前先调用以下方法：

• 调用 setAudioScenario: 将音频场景设置为高音质场景，即 AgoraAudioScenarioGameStreaming（3）。
• 调用 setAudioProfile: 并将 profile 参数设置为 AgoraAudioProfileMusicHighQuality（4）或 AgoraAudioProfileMusicHighQualityStereo（5）。

参数

preset

预设的变声效果选项，详见 AgoraVoiceConversionPreset。

返回值

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

所属接口类

• AgoraRtcEngineKit