人声音效

enableVoiceAITuner

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

C++

virtual int enableVoiceAITuner(bool enabled, VOICE_AI_TUNER_TYPE type) = 0;

适用场景

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

调用时机

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

参数

enabled

是否启用语音 AI 调音器：

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

type

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

返回值

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

所属接口类

• IRtcEngine

setAdvancedAudioOptions

设置高级音频选项。

C++

virtual int setAdvancedAudioOptions(AdvancedAudioOptions& options, int sourceType = 0) = 0;

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

信息

请在调用 joinChannel、enableAudio 和 enableLocalAudio 之后调用该方法。

参数

options

高级音频选项。详见 AdvancedAudioOptions。

sourceType

音频源的类型。

返回值

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

所属接口类

• IRtcEngine

setAINSMode

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

C++

virtual int setAINSMode(bool enabled,  AUDIO_AINS_MODE mode) = 0;

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

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

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

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

信息

• 该方法依赖 AI 降噪动态库 libagora_ai_noise_suppression_extension.dll。如果该动态库被删除，则无法启用该功能。
• 声网不建议在运行 Android 6.0 及以下版本的设备上启用该功能。

适用场景

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

调用时机

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

参数

enabled

是否启用 AI 降噪功能：

• true：启用 AI 降噪。
• false：（默认）关闭 AI 降噪。

mode

AI 降噪模式。详见 AUDIO_AINS_MODE。

返回值

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

所属接口类

• IRtcEngine

setAudioEffectParameters

设置 SDK 预设音效的参数。

C++

virtual int setAudioEffectParameters(AUDIO_EFFECT_PRESET preset, int param1, int param2) = 0;

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

• ROOM_ACOUSTICS_3D_VOICE：设置声音围绕用户移动的循环周期。
• PITCH_CORRECTION：设置音高修正的基本模式和主音。

不同歌曲的模式和主音可能不同，声网建议将该方法与界面元素绑定，方便用户交互式调整音高修正效果。为了获得更好的人声效果，建议在调用该方法前先调用以下方法：

• 调用 setAudioScenario，将音频场景设置为高音质音频场景，即 AUDIO_SCENARIO_GAME_STREAMING（3）。
• 调用 setAudioProfile，将 profile 设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY（4）或 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO（5）。

信息

• 请勿将 setAudioProfile 中的 profile 设置为 AUDIO_PROFILE_SPEECH_STANDARD（1）或 AUDIO_PROFILE_IOT（6），否则该方法不生效。
• 该方法在人声处理方面效果最佳，不建议用于处理包含音乐的音频数据。
• 调用 setAudioEffectParameters 后，不建议再调用以下方法，否则该方法设置的效果会被覆盖：
  • setAudioEffectPreset
  • setVoiceBeautifierPreset
  • setLocalVoicePitch
  • setLocalVoiceEqualization
  • setLocalVoiceReverb
  • setVoiceBeautifierParameters
  • setVoiceConversionPreset
• 该方法依赖语音美声动态库 libagora_audio_beauty_extension.dll，若该动态库被删除，该功能将无法启用。

调用时机

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

参数

preset

SDK 预设音效选项：

• ROOM_ACOUSTICS_3D_VOICE（3）：3D 人声效果。
  • 设置该枚举值前，需要将 setAudioProfile 中的 profile 设置为 AUDIO_PROFILE_MUSIC_STANDARD_STEREO（3）或 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO（5），否则该设置不生效。
  • 启用后，用户需使用立体声播放设备才能听到预期效果。
• PITCH_CORRECTION（10）：音高修正效果。

param1

• 当 preset 为 ROOM_ACOUSTICS_3D_VOICE 时，设置 3D 人声效果的循环周期，单位为秒，取值范围为 [1, 60]，默认值为 10，表示声音每 10 秒围绕你移动一圈。
• 当 preset 为 PITCH_CORRECTION 时，表示音高修正的基本模式：
  • 1：（默认）自然大调。
  • 2：自然小调。
  • 3：日本五声音阶。

param2

• 当 preset 为 ROOM_ACOUSTICS_3D_VOICE 时，需将 param2 设置为 0。
• 当 preset 为 PITCH_CORRECTION 时，表示音高修正的主音：
  • 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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

setAudioEffectPreset

设置 SDK 预设的音效效果。

C++

virtual int setAudioEffectPreset(AUDIO_EFFECT_PRESET preset) = 0;

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

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

信息

• 不要将 setAudioProfile 中的 profile 参数设置为 AUDIO_PROFILE_SPEECH_STANDARD（1）或 AUDIO_PROFILE_IOT（6），否则该方法不生效。
• 如果调用 setAudioEffectPreset 并设置的枚举值不是 ROOM_ACOUSTICS_3D_VOICE 或 PITCH_CORRECTION，请不要调用 setAudioEffectParameters，否则 setAudioEffectPreset 的设置会被覆盖。
• 调用 setAudioEffectPreset 后，声网不建议再调用以下方法，否则 setAudioEffectPreset 设置的效果会被覆盖：
  • setVoiceBeautifierPreset
  • setLocalVoicePitch
  • setLocalVoiceEqualization
  • setLocalVoiceReverb
  • setVoiceBeautifierParameters
  • setVoiceConversionPreset
• 此方法依赖于美声动态库 libagora_audio_beauty_extension.dll。如果该动态库被删除，则无法正常启用该功能。

调用时机

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

参数

preset

SDK 预设音效选项。详见 AUDIO_EFFECT_PRESET。

返回值

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

所属接口类

• IRtcEngine

setLocalVoiceEqualization

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

C++

virtual int setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain) = 0;

调用时机

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

参数

bandFrequency

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

bandGain

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

返回值

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

所属接口类

• IRtcEngine

setLocalVoiceFormant

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

C++

virtual int setLocalVoiceFormant(double formantRatio) = 0;

共振峰比例会影响声音的音色。值越小，声音越低沉；值越大，声音越尖锐。如果你希望同时改变音色和音调，建议同时使用 setLocalVoiceFormant 和 setLocalVoicePitch。

适用场景

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

调用时机

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

参数

formantRatio

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

信息

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

返回值

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

所属接口类

• IRtcEngine

setLocalVoicePitch

设置本地语音的音调。

C++

virtual int setLocalVoicePitch(double pitch) = 0;

调用时机

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

参数

pitch

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

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。

所属接口类

• IRtcEngine

setLocalVoiceReverb

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

C++

virtual int setLocalVoiceReverb(AUDIO_REVERB_TYPE reverbKey, int value) = 0;

你也可以使用更易用的方法 setAudioEffectPreset，直接实现如流行、R&B 和 KTV 等预设混响效果。

调用时机

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

参数

reverbKey

混响键，详见 AUDIO_REVERB_TYPE。

value

混响键对应的取值。

返回值

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

所属接口类

• IRtcEngine

setVoiceBeautifierParameters

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

C++

virtual int setVoiceBeautifierParameters(VOICE_BEAUTIFIER_PRESET preset, int param1, int param2) = 0;

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

• 调用 setAudioScenario，将音频场景设置为高音质音频场景，即 AUDIO_SCENARIO_GAME_STREAMING（3）。
• 调用 setAudioProfile，将 profile 参数设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY（4）或 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO（5）。

信息

• 请勿将 setAudioProfile 中的 profile 参数设置为 AUDIO_PROFILE_SPEECH_STANDARD（1）或 AUDIO_PROFILE_IOT（6），否则该方法不生效。
• 该方法在人声处理方面效果最佳，不建议用于处理包含音乐的音频数据。
• 调用 setVoiceBeautifierParameters 后，不建议再调用以下方法，否则会覆盖该方法设置的效果：
  • setAudioEffectPreset
  • setAudioEffectParameters
  • setVoiceBeautifierPreset
  • setLocalVoicePitch
  • setLocalVoiceEqualization
  • setLocalVoiceReverb
  • setVoiceConversionPreset
• 该方法依赖于美声特效动态库 libagora_audio_beauty_extension.dll。如果该动态库被删除，该功能将无法正常使用。

调用时机

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

参数

preset

预设音效选项：

• SINGING_BEAUTIFIER：歌唱美声特效。

param1

歌声的性别特征选项：

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

param2

歌声的混响效果选项：

• 1：混响效果类似在小房间中歌唱。
• 2：混响效果类似在大房间中歌唱。
• 3：混响效果类似在大厅中歌唱。

返回值

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

所属接口类

• IRtcEngine

setVoiceBeautifierPreset

设置预设的美声特效。

C++

virtual int setVoiceBeautifierPreset(VOICE_BEAUTIFIER_PRESET preset) = 0;

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

信息

• 不要将 setAudioProfile 中的 profile 参数设置为 AUDIO_PROFILE_SPEECH_STANDARD（1）或 AUDIO_PROFILE_IOT（6），否则该方法不生效。
• 该方法在人声处理方面效果最佳，不建议用于处理包含音乐的音频数据。
• 调用 setVoiceBeautifierPreset 后，不建议再调用以下方法，否则会覆盖通过 setVoiceBeautifierPreset 设置的效果：
  • setAudioEffectPreset
  • setAudioEffectParameters
  • setLocalVoicePitch
  • setLocalVoiceEqualization
  • setLocalVoiceReverb
  • setVoiceBeautifierParameters
  • setVoiceConversionPreset
• 该方法依赖于美声特效动态库 libagora_audio_beauty_extension.dll。如果该动态库被删除，则无法正常启用该功能。

调用时机

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

参数

preset

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

返回值

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

所属接口类

• IRtcEngine

setVoiceConversionPreset

设置预设的声动语聊特效。

C++

virtual int setVoiceConversionPreset(VOICE_CONVERSION_PRESET preset) = 0;

调用该方法为发布音频流的本地用户设置预设的变声效果。设置后，频道内所有用户都能听到该变声效果。你可以根据不同场景为用户设置不同的变声效果。 为了获得更好的语音效果，建议在调用该方法前调用以下方法：

• 调用 setAudioScenario，将音频场景设置为高音质音频场景，即 AUDIO_SCENARIO_GAME_STREAMING（3）。
• 调用 setAudioProfile，将 profile 参数设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY（4）或 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO（5）。

信息

• 请勿将 setAudioProfile 中的 profile 参数设置为 AUDIO_PROFILE_SPEECH_STANDARD（1）或 AUDIO_PROFILE_IOT（6），否则该方法不生效。
• 该方法对人声处理效果最佳，不建议用于处理包含音乐的音频数据。
• 调用 setVoiceConversionPreset 后，不建议再调用以下方法，否则会覆盖该方法设置的效果：
  • setAudioEffectPreset
  • setAudioEffectParameters
  • setVoiceBeautifierPreset
  • setVoiceBeautifierParameters
  • setLocalVoicePitch
  • setLocalVoiceFormant
  • setLocalVoiceEqualization
  • setLocalVoiceReverb
• 该方法依赖声动语聊动态库 libagora_audio_beauty_extension.dll。若该动态库被删除，则该功能无法正常启用。

调用时机

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

参数

preset

预设的声动语聊特效选项，详见 VOICE_CONVERSION_PRESET。

返回值

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

所属接口类

• IRtcEngine