人声音效

setAdvancedAudioOptions

设置音频的高级选项。

Dart

Future<void> setAdvancedAudioOptions(AdvancedAudioOptions options);

详情

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

注意

你需要在 joinChannel、enableAudio 和 enableLocalAudio 前调用该方法。

参数

options

音频的高级选项。详见 AdvancedAudioOptions。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

setAINSMode

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

Dart

Future<void> setAINSMode(
      {required bool enabled, required AudioAinsMode mode});

详情

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

• 电视机噪声
• 空调噪声
• 工厂机器噪声等

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

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

信息

• 目前暂不推荐在 Android 6.0 及以下版本的设备上开启该功能。

适用场景

在语音连麦、在线教育、在线会议等场景中，如果周围环境比较嘈杂，AI 降噪功能可以在保证语音质量的前提下，识别并降低周围的稳态噪声和非稳态噪声，提高语音质量和体验。

参数

enabled

是否开启 AI 降噪功能：

• true：开启 AI 降噪功能。
• false：（默认）关闭 AI 降噪功能。

mode

降噪模式，详见 AudioAinsMode。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

setAudioEffectParameters

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

Dart

Future<void> setAudioEffectParameters(
  {required AudioEffectPreset preset,
  required int param1,
  required int param2});

详情

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

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

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

为获取更好的人声效果，建议你在调用该方法前进行以下操作：

• 调用 setAudioScenario 将音频场景设为高音质场景，即 audioScenarioGameStreaming(3)。
• 调用 setAudioProfile 将 profile 设为 audioProfileMusicHighQuality(4) 或 audioProfileMusicHighQualityStereo(5)。

注意

• 该方法在加入频道前后都能调用。
• 请勿将 setAudioProfile 的 profile 参数设置为 audioProfileSpeechStandard(1) 或 audioProfileIot(6)，否则该方法不生效。
• 该方法对人声的处理效果最佳，不建议调用该方法处理含音乐的音频数据。
• 调用 setAudioEffectParameters 后，不建议调用以下方法，否则 setAudioEffectParameters 设置的效果会被覆盖：
  • setAudioEffectPreset
  • setVoiceBeautifierPreset
  • setLocalVoicePitch
  • setLocalVoiceEqualization
  • setLocalVoiceReverb
  • setVoiceBeautifierParameters
  • setVoiceConversionPreset
• 该方法依赖于美声动态库 libagora_audio_beauty_extension.dll，如果删除该动态库会导致无法正常开启该功能。

参数

preset

SDK 预设的音效，支持以下设置：

• roomAcoustics3dVoice，3D 人声音效。
  • 你需要在使用该枚举前将 setAudioProfile 的 profile 参数设置 为 audioProfileMusicStandardStereo(3) 或 audioProfileMusicHighQualityStereo(5)，否则该枚举设置无效。
  • 启用 3D 人声后，用户需要使用支持双声道的音频播放设备才能听到预期效果。
• pitchCorrection，电音音效。

param1

• 如果 preset 设为 roomAcoustics3dVoice ，则 param1 表示 3D 人声音效的环绕周期。取值范围为 [1,60]，单位为秒。默认值为 10，表示人声会 10 秒环绕 360 度。
• 如果 preset 设为 pitchCorrection，则 param1 表示电音音效的基础调式：
  • 1: （默认）自然大调。
  • 2: 自然小调。
  • 3: 和风小调。

param2

• 如果 preset 设为 roomAcoustics3dVoice，你需要将 param2 设置为 0。
• 如果 preset 设为 pitchCorrection，则 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#

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

setAudioEffectPreset

设置 SDK 预设的人声音效。

Dart

Future<void> setAudioEffectPreset(AudioEffectPreset preset);

详情

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

为获取更好的人声效果，建议你在调用该方法前进行以下操作：

• 调用 setAudioScenario 将音频场景设为高音质场景，即 audioScenarioGameStreaming(3)。
• 调用 setAudioProfile 将 profile 设为 audioProfileMusicHighQuality(4) 或 audioProfileMusicHighQualityStereo(5)。

注意

• 该方法在加入频道前后都能调用。
• 请勿将 setAudioProfile 的 profile 参数设置为 audioProfileSpeechStandard(1) 或 audioProfileIot(6)，否则该方法不生效。
• 如果调用 setAudioEffectPreset 并设置除 roomAcoustics3dVoice 或 pitchCorrection 外的枚举，请勿再调用 setAudioEffectParameters，否则 setAudioEffectPreset 设置的效果会被覆盖。
• 调用 setAudioEffectPreset 后，不建议调用以下方法，否则 setAudioEffectPreset 设置的效果会被覆盖：
  • setVoiceBeautifierPreset
  • setLocalVoicePitch
  • setLocalVoiceEqualization
  • setLocalVoiceReverb
  • setVoiceBeautifierParameters
  • setVoiceConversionPreset
• 该方法依赖于美声动态库 libagora_audio_beauty_extension.dll，如果删除该动态库会导致无法正常开启该功能。

参数

preset

预设的音效选项，详见 AudioEffectPreset。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

setLocalVoiceEqualization

设置本地语音音效均衡。

Dart

Future<void> setLocalVoiceEqualization(
  {required AudioEqualizationBandFrequency bandFrequency,
  required int bandGain});

详情

注意

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

参数

bandFrequency

频谱子带索引。取值范围是 [0,9]，分别代表音效的 10 个频带。对应的中心频率为 [31，62，125，250，500，1k，2k，4k，8k，16k] Hz。详见 AudioEqualizationBandFrequency 。

bandGain

每个 band 的增益，单位是 dB，每一个值的范围是 [-15,15]，默认值为 0。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

setLocalVoiceFormant

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

Dart

Future<void> setLocalVoiceFormant(double formantRatio);

详情

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

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

注意

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

参数

formantRatio

共振峰比率，取值范围为 [-1.0，1.0]。默认值为 0.0，即不改变原声的音色。

信息

声网推荐的取值范围为 [-0.4，0.6] ，超出此范围外音效听感可能不佳。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

setLocalVoicePitch

设置本地语音音调。

Dart

Future<void> setLocalVoicePitch(double pitch);

详情

注意

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

参数

pitch

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

setLocalVoiceReverb

设置本地音效混响。

Dart

Future<void> setLocalVoiceReverb(
  {required AudioReverbType reverbKey, required int value});

详情

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

信息

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

参数

reverbKey

混响音效 Key。该方法共有 5 个混响音效 Key，详见 AudioReverbType。

value

各混响音效 Key 所对应的值。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

setVoiceBeautifierParameters

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

Dart

Future<void> setVoiceBeautifierParameters(
  {required VoiceBeautifierPreset preset,
  required int param1,
  required int param2});

详情

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

为获取更好的人声效果，建议你在调用该方法前进行以下操作：

• 调用 setAudioScenario 将音频场景设为高音质场景，即 audioScenarioGameStreaming(3)。
• 调用 setAudioProfile 将 profile 设为 audioProfileMusicHighQuality(4) 或 audioProfileMusicHighQualityStereo(5)。

注意

• 该方法在加入频道前后都能调用。
• 请勿将 setAudioProfile 的 profile 参数设置为 audioProfileSpeechStandard(1) 或 audioProfileIot(6)，否则该方法不生效。
• 该方法对人声的处理效果最佳，不建议调用该方法处理含音乐的音频数据。
• 调用 setVoiceBeautifierParameters，不建议调用以下方法，否则 setVoiceBeautifierParameters 设置的效果会被覆盖：
  • setAudioEffectPreset
  • setAudioEffectParameters
  • setVoiceBeautifierPreset
  • setLocalVoicePitch
  • setLocalVoiceEqualization
  • setLocalVoiceReverb
  • setVoiceConversionPreset
• 该方法依赖于美声动态库 libagora_audio_beauty_extension.dll，如果删除该动态库会导致无法正常开启该功能。

参数

preset

预设的音效：

• SINGING_BEAUTIFIER: 歌唱美声。

param1

歌声的性别特征：

• 1: 男声。
• 2: 女声。

param2

歌声的混响效果：

• 1: 歌声在小房间的混响效果。
• 2: 歌声在大房间的混响效果。
• 3: 歌声在大厅的混响效果。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

setVoiceBeautifierPreset

设置预设的美声效果。

Dart

Future<void> setVoiceBeautifierPreset(VoiceBeautifierPreset preset);

详情

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

为获取更好的人声效果，建议你在调用该方法前进行以下操作：

• 调用 setAudioScenario 将音频场景设为高音质场景，即 audioScenarioGameStreaming(3)。
• 调用 setAudioProfile 将 profile 设为 audioProfileMusicHighQuality(4) 或 audioProfileMusicHighQualityStereo(5)。

注意

• 该方法在加入频道前后都能调用。
• 请勿将 setAudioProfile 的 profile 参数设置为 audioProfileSpeechStandard(1) 或 audioProfileIot(6)，否则该方法不生效。
• 该方法对人声的处理效果最佳，不建议调用该方法处理含音乐的音频数据。
• 调用 setVoiceBeautifierPreset，不建议调用以下方法，否则 setVoiceBeautifierPreset 设置的效果会被覆盖：
  • setAudioEffectPreset
  • setAudioEffectParameters
  • setLocalVoicePitch
  • setLocalVoiceEqualization
  • setLocalVoiceReverb
  • setVoiceBeautifierParameters
  • setVoiceConversionPreset
• 该方法依赖于美声动态库 libagora_audio_beauty_extension.dll，如果删除该动态库会导致无法正常开启该功能。

参数

preset

预设的美声效果选项，详见 VoiceBeautifierPreset。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

setVoiceConversionPreset

设置预设的变声效果。

Dart

Future<void> setVoiceConversionPreset(VoiceConversionPreset preset);

详情

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

为获取更好的人声效果，建议你在调用该方法前进行以下操作：

• 调用 setAudioScenario 将音频场景设为高音质场景，即 audioScenarioGameStreaming(3)。
• 调用 setAudioProfile 将 profile 设为 audioProfileMusicHighQuality(4) 或 audioProfileMusicHighQualityStereo(5)。

注意

• 该方法在加入频道前后都能调用。
• 请勿将 setAudioProfile 的 profile 参数设置为 audioProfileSpeechStandard(1) 或 audioProfileIot(6)，否则该方法不生效。
• 该方法对人声的处理效果最佳，不建议调用该方法处理含音乐的音频数据。
• 调用 setVoiceConversionPreset 后，不建议调用以下方法，否则 setVoiceConversionPreset 设置的效果会被覆盖：
  • setAudioEffectPreset
  • setAudioEffectParameters
  • setVoiceBeautifierPreset
  • setVoiceBeautifierParameters
  • setLocalVoicePitch
  • setLocalVoiceFormant
  • setLocalVoiceEqualization
  • setLocalVoiceReverb
• 该方法依赖于美声动态库 libagora_audio_beauty_extension.dll，如果删除该动态库会导致无法正常开启该功能。

参数

preset

预设的变声效果选项: VoiceConversionPreset。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

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

所属接口类

• RtcEngine