# 人声音效 (/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<a id="toc_audio_effect"></a>

<a id="api_irtcengine_enablevoiceaituner"></a>

<a id="ariaid-title2"></a>

## enableVoiceAITuner [#enablevoiceaituner]

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

<a id="api_irtcengine_enablevoiceaituner__prototype"></a>

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

<a id="api_irtcengine_enablevoiceaituner__detailed_desc"></a>

<a id="api_irtcengine_enablevoiceaituner__scenario"></a>

### 适用场景 [#适用场景]

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

<a id="api_irtcengine_enablevoiceaituner__timing"></a>

### 调用时机 [#调用时机]

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

<a id="api_irtcengine_enablevoiceaituner__parameters"></a>

### 参数 [#参数]

<ParameterList>
<a id="enabled"></a>
<Parameter name="enabled">

是否启用语音 AI 调音器：

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

</Parameter>
<a id="type"></a>
<Parameter name="type">

语音 AI 调音器的音效类型，详见 [VOICE_AI_TUNER_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-voiceaitunertype)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_enablevoiceaituner__return_values"></a>

### 返回值 [#返回值]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setadvancedaudiooptions"></a>

<a id="ariaid-title3"></a>

## setAdvancedAudioOptions [#setadvancedaudiooptions]

设置高级音频选项。

<a id="api_irtcengine_setadvancedaudiooptions__prototype"></a>

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

<a id="api_irtcengine_setadvancedaudiooptions__detailed_desc"></a>

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

:::note
注： 请在调用 `joinChannel`、[enableAudio](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengine_enableaudio) 和 [enableLocalAudio](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-capture#api_irtcengine_enablelocalaudio) 之前调用该方法。
:::

<a id="api_irtcengine_setadvancedaudiooptions__parameters"></a>

### 参数 [#参数-1]

<ParameterList>
<a id="options"></a>
<Parameter name="options">

高级音频选项。详见 [AdvancedAudioOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-advancedaudiooptions)。

</Parameter>
<a id="sourcetype"></a>
<Parameter name="sourceType">

音频源的类型。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setadvancedaudiooptions__return_values"></a>

### 返回值 [#返回值-1]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-1]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setainsmode"></a>

<a id="ariaid-title4"></a>

## setAINSMode [#setainsmode]

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

<a id="api_irtcengine_setainsmode__prototype"></a>

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

<a id="api_irtcengine_setainsmode__detailed_desc"></a>

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

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

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

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

:::note
注：

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

<a id="api_irtcengine_setainsmode__scenario"></a>

### 适用场景 [#适用场景-1]

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

<a id="api_irtcengine_setainsmode__timing"></a>

### 调用时机 [#调用时机-1]

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

<a id="api_irtcengine_setainsmode__parameters"></a>

### 参数 [#参数-2]

<ParameterList>
<a id="enabled-1"></a>
<Parameter name="enabled">

是否启用 AI 降噪功能：

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

</Parameter>
<a id="mode"></a>
<Parameter name="mode">

AI 降噪模式。详见 [AUDIO_AINS_MODE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-audioainsmode)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setainsmode__return_values"></a>

### 返回值 [#返回值-2]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-2]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setaudioeffectparameters"></a>

<a id="ariaid-title5"></a>

## setAudioEffectParameters [#setaudioeffectparameters]

设置 SDK 预设音效的参数。

<a id="api_irtcengine_setaudioeffectparameters__prototype"></a>

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

<a id="api_irtcengine_setaudioeffectparameters__detailed_desc"></a>

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

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

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

- 调用 [setAudioScenario](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengine_setaudioscenario)，将音频场景设置为高音质音频场景，即 `AUDIO_SCENARIO_GAME_STREAMING`（3）。
- 调用 `setAudioProfile`，将 `profile` 设置为 `AUDIO_PROFILE_MUSIC_HIGH_QUALITY`（4）或 `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO`（5）。

:::note
注：

- 请勿将 `setAudioProfile` 中的 `profile` 设置为 `AUDIO_PROFILE_SPEECH_STANDARD`（1）或 `AUDIO_PROFILE_IOT`（6），否则该方法不生效。
- 该方法在人声处理方面效果最佳，不建议用于处理包含音乐的音频数据。
- 调用 [setAudioEffectParameters](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setaudioeffectparameters) 后，不建议再调用以下方法，否则该方法设置的效果会被覆盖：

  - [setAudioEffectPreset](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setaudioeffectpreset)
  - [setVoiceBeautifierPreset](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierpreset)
  - [setLocalVoicePitch](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicepitch)
  - [setLocalVoiceEqualization](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoiceequalization)
  - [setLocalVoiceReverb](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicereverb)
  - [setVoiceBeautifierParameters](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierparameters)
  - [setVoiceConversionPreset](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setvoiceconversionpreset)
- 该方法依赖语音美声动态库 libagora_audio_beauty_extension.dll，若该动态库被删除，该功能将无法启用。
:::

<a id="api_irtcengine_setaudioeffectparameters__timing"></a>

### 调用时机 [#调用时机-2]

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

<a id="api_irtcengine_setaudioeffectparameters__parameters"></a>

### 参数 [#参数-3]

<ParameterList>
<a id="preset"></a>
<Parameter name="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）：音高修正效果。

</Parameter>
<a id="param1"></a>
<Parameter name="param1">

- 当 `preset` 为 `ROOM_ACOUSTICS_3D_VOICE` 时，设置 3D 人声效果的循环周期，单位为秒，取值范围为 [1, 60]，默认值为 10，表示声音每 10 秒围绕你移动一圈。
- 当 `preset` 为 `PITCH_CORRECTION` 时，表示音高修正的基本模式：

  - `1`：（默认）自然大调。
  - `2`：自然小调。
  - `3`：日本五声音阶。

</Parameter>
<a id="param2"></a>
<Parameter name="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#

</Parameter>
</ParameterList>

<a id="api_irtcengine_setaudioeffectparameters__return_values"></a>

### 返回值 [#返回值-3]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-3]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setaudioeffectpreset"></a>

<a id="ariaid-title6"></a>

## setAudioEffectPreset [#setaudioeffectpreset]

设置 SDK 预设的音效效果。

<a id="api_irtcengine_setaudioeffectpreset__prototype"></a>

```cpp
virtual int setAudioEffectPreset(AUDIO_EFFECT_PRESET preset) = 0;
```

<a id="api_irtcengine_setaudioeffectpreset__detailed_desc"></a>

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

- 调用 [setAudioScenario](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengine_setaudioscenario)，将音频场景设置为高音质音频场景，即 `AUDIO_SCENARIO_GAME_STREAMING`（3）。
- 调用 `setAudioProfile`，并将 `profile` 参数设置为 `AUDIO_PROFILE_MUSIC_HIGH_QUALITY`（4）或 `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO`（5）。

:::note
注：

- 不要将 `setAudioProfile` 中的 `profile` 参数设置为 `AUDIO_PROFILE_SPEECH_STANDARD`（1）或 `AUDIO_PROFILE_IOT`（6），否则该方法不生效。
- 如果调用 [setAudioEffectPreset](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setaudioeffectpreset) 并设置的枚举值不是 `ROOM_ACOUSTICS_3D_VOICE` 或 `PITCH_CORRECTION`，请不要调用 [setAudioEffectParameters](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setaudioeffectparameters)，否则 [setAudioEffectPreset](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setaudioeffectpreset) 的设置会被覆盖。
- 调用 [setAudioEffectPreset](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setaudioeffectpreset) 后，声网不建议再调用以下方法，否则 [setAudioEffectPreset](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setaudioeffectpreset) 设置的效果会被覆盖：

  - [setVoiceBeautifierPreset](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierpreset)
  - [setLocalVoicePitch](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicepitch)
  - [setLocalVoiceEqualization](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoiceequalization)
  - [setLocalVoiceReverb](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicereverb)
  - [setVoiceBeautifierParameters](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierparameters)
  - [setVoiceConversionPreset](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setvoiceconversionpreset)
- 此方法依赖于美声动态库 libagora_audio_beauty_extension.dll。如果该动态库被删除，则无法正常启用该功能。
:::

<a id="api_irtcengine_setaudioeffectpreset__timing"></a>

### 调用时机 [#调用时机-3]

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

<a id="api_irtcengine_setaudioeffectpreset__parameters"></a>

### 参数 [#参数-4]

<ParameterList>
<a id="preset-1"></a>
<Parameter name="preset">

SDK 预设音效选项。详见 [AUDIO_EFFECT_PRESET](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-audioeffectpreset)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setaudioeffectpreset__return_values"></a>

### 返回值 [#返回值-4]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-4]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setlocalvoiceequalization"></a>

<a id="ariaid-title7"></a>

## setLocalVoiceEqualization [#setlocalvoiceequalization]

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

<a id="api_irtcengine_setlocalvoiceequalization__prototype"></a>

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

<a id="api_irtcengine_setlocalvoiceequalization__detailed_desc"></a>

<a id="api_irtcengine_setlocalvoiceequalization__timing"></a>

### 调用时机 [#调用时机-4]

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

<a id="api_irtcengine_setlocalvoiceequalization__parameters"></a>

### 参数 [#参数-5]

<ParameterList>
<a id="bandfrequency"></a>
<Parameter name="bandFrequency">

频段索引，取值范围为 0 到 9，分别对应语音效果的 10 个中心频率段：31、62、125、250、500、1k、2k、4k、8k 和 16k Hz。详见 [AUDIO_EQUALIZATION_BAND_FREQUENCY](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-audioequalizationbandfrequency)。

</Parameter>
<a id="bandgain"></a>
<Parameter name="bandGain">

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_setlocalvoiceequalization__return_values"></a>

### 返回值 [#返回值-5]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-5]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setlocalvoiceformant"></a>

<a id="ariaid-title8"></a>

## setLocalVoiceFormant [#setlocalvoiceformant]

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

<a id="api_irtcengine_setlocalvoiceformant__prototype"></a>

```cpp
virtual int setLocalVoiceFormant(double formantRatio) = 0;
```

<a id="api_irtcengine_setlocalvoiceformant__detailed_desc"></a>

共振峰比例会影响声音的音色。值越小，声音越低沉；值越大，声音越尖锐。如果你希望同时改变音色和音调，建议同时使用 [setLocalVoiceFormant](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoiceformant) 和 [setLocalVoicePitch](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicepitch)。

<a id="api_irtcengine_setlocalvoiceformant__scenario"></a>

### 适用场景 [#适用场景-2]

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

<a id="api_irtcengine_setlocalvoiceformant__timing"></a>

### 调用时机 [#调用时机-5]

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

<a id="api_irtcengine_setlocalvoiceformant__parameters"></a>

### 参数 [#参数-6]

<ParameterList>
<a id="formantratio"></a>
<Parameter name="formantRatio">

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

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_setlocalvoiceformant__return_values"></a>

### 返回值 [#返回值-6]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-6]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setlocalvoicepitch"></a>

<a id="ariaid-title9"></a>

## setLocalVoicePitch [#setlocalvoicepitch]

设置本地语音的音调。

<a id="api_irtcengine_setlocalvoicepitch__prototype"></a>

```cpp
virtual int setLocalVoicePitch(double pitch) = 0;
```

<a id="api_irtcengine_setlocalvoicepitch__detailed_desc"></a>

<a id="api_irtcengine_setlocalvoicepitch__timing"></a>

### 调用时机 [#调用时机-6]

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

<a id="api_irtcengine_setlocalvoicepitch__parameters"></a>

### 参数 [#参数-7]

<ParameterList>
<a id="pitch"></a>
<Parameter name="pitch">

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_setlocalvoicepitch__return_values"></a>

### 返回值 [#返回值-7]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。

### 所属接口类 [#所属接口类-7]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setlocalvoicereverb"></a>

<a id="ariaid-title10"></a>

## setLocalVoiceReverb [#setlocalvoicereverb]

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

<a id="api_irtcengine_setlocalvoicereverb__prototype"></a>

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

<a id="api_irtcengine_setlocalvoicereverb__detailed_desc"></a>

你也可以使用更易用的方法 [setAudioEffectPreset](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setaudioeffectpreset)，直接实现如流行、R&B 和 KTV 等预设混响效果。

<a id="api_irtcengine_setlocalvoicereverb__timing"></a>

### 调用时机 [#调用时机-7]

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

<a id="api_irtcengine_setlocalvoicereverb__parameters"></a>

### 参数 [#参数-8]

<ParameterList>
<a id="reverbkey"></a>
<Parameter name="reverbKey">

混响键，详见 [AUDIO_REVERB_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-audioreverbtype)。

</Parameter>
<a id="value"></a>
<Parameter name="value">

混响键对应的取值。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setlocalvoicereverb__return_values"></a>

### 返回值 [#返回值-8]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-8]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setvoicebeautifierparameters"></a>

<a id="ariaid-title11"></a>

## setVoiceBeautifierParameters [#setvoicebeautifierparameters]

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

<a id="api_irtcengine_setvoicebeautifierparameters__prototype"></a>

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

<a id="api_irtcengine_setvoicebeautifierparameters__detailed_desc"></a>

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

- 调用 [setAudioScenario](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengine_setaudioscenario)，将音频场景设置为高音质音频场景，即 `AUDIO_SCENARIO_GAME_STREAMING`（3）。
- 调用 `setAudioProfile`，将 `profile` 参数设置为 `AUDIO_PROFILE_MUSIC_HIGH_QUALITY`（4）或 `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO`（5）。

:::note
注：

- 请勿将 `setAudioProfile` 中的 `profile` 参数设置为 `AUDIO_PROFILE_SPEECH_STANDARD`（1）或 `AUDIO_PROFILE_IOT`（6），否则该方法不生效。
- 该方法在人声处理方面效果最佳，不建议用于处理包含音乐的音频数据。
- 调用 [setVoiceBeautifierParameters](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierparameters) 后，不建议再调用以下方法，否则会覆盖该方法设置的效果：

  - [setAudioEffectPreset](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setaudioeffectpreset)
  - [setAudioEffectParameters](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setaudioeffectparameters)
  - [setVoiceBeautifierPreset](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierpreset)
  - [setLocalVoicePitch](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicepitch)
  - [setLocalVoiceEqualization](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoiceequalization)
  - [setLocalVoiceReverb](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicereverb)
  - [setVoiceConversionPreset](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setvoiceconversionpreset)
- 该方法依赖于美声特效动态库 libagora_audio_beauty_extension.dll。如果该动态库被删除，该功能将无法正常使用。
:::

<a id="api_irtcengine_setvoicebeautifierparameters__timing"></a>

### 调用时机 [#调用时机-8]

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

<a id="api_irtcengine_setvoicebeautifierparameters__parameters"></a>

### 参数 [#参数-9]

<ParameterList>
<a id="preset-2"></a>
<Parameter name="preset">

预设音效选项：

- `SINGING_BEAUTIFIER`：歌唱美声特效。

</Parameter>
<a id="param1-1"></a>
<Parameter name="param1">

歌声的性别特征选项：

- `1`：男性音色。
- `2`：女性音色。

</Parameter>
<a id="param2-1"></a>
<Parameter name="param2">

歌声的混响效果选项：

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_setvoicebeautifierparameters__return_values"></a>

### 返回值 [#返回值-9]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-9]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setvoicebeautifierpreset"></a>

<a id="ariaid-title12"></a>

## setVoiceBeautifierPreset [#setvoicebeautifierpreset]

设置预设的美声特效。

<a id="api_irtcengine_setvoicebeautifierpreset__prototype"></a>

```cpp
virtual int setVoiceBeautifierPreset(VOICE_BEAUTIFIER_PRESET preset) = 0;
```

<a id="api_irtcengine_setvoicebeautifierpreset__detailed_desc"></a>

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

:::note
注：

- 不要将 `setAudioProfile` 中的 `profile` 参数设置为 `AUDIO_PROFILE_SPEECH_STANDARD`（1）或 `AUDIO_PROFILE_IOT`（6），否则该方法不生效。
- 该方法在人声处理方面效果最佳，不建议用于处理包含音乐的音频数据。
- 调用 [setVoiceBeautifierPreset](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierpreset) 后，不建议再调用以下方法，否则会覆盖通过 [setVoiceBeautifierPreset](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierpreset) 设置的效果：

  - [setAudioEffectPreset](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setaudioeffectpreset)
  - [setAudioEffectParameters](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setaudioeffectparameters)
  - [setLocalVoicePitch](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicepitch)
  - [setLocalVoiceEqualization](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoiceequalization)
  - [setLocalVoiceReverb](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicereverb)
  - [setVoiceBeautifierParameters](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierparameters)
  - [setVoiceConversionPreset](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setvoiceconversionpreset)
- 该方法依赖于美声特效动态库 libagora_audio_beauty_extension.dll。如果该动态库被删除，则无法正常启用该功能。
:::

<a id="api_irtcengine_setvoicebeautifierpreset__timing"></a>

### 调用时机 [#调用时机-9]

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

<a id="api_irtcengine_setvoicebeautifierpreset__parameters"></a>

### 参数 [#参数-10]

<ParameterList>
<a id="preset-3"></a>
<Parameter name="preset">

预设的美声特效选项，详见 [VOICE_BEAUTIFIER_PRESET](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-voicebeautifierpreset)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setvoicebeautifierpreset__return_values"></a>

### 返回值 [#返回值-10]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-10]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setvoiceconversionpreset"></a>

<a id="ariaid-title13"></a>

## setVoiceConversionPreset [#setvoiceconversionpreset]

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

<a id="api_irtcengine_setvoiceconversionpreset__prototype"></a>

```cpp
virtual int setVoiceConversionPreset(VOICE_CONVERSION_PRESET preset) = 0;
```

<a id="api_irtcengine_setvoiceconversionpreset__detailed_desc"></a>

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

- 调用 [setAudioScenario](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengine_setaudioscenario)，将音频场景设置为高音质音频场景，即 `AUDIO_SCENARIO_GAME_STREAMING`（3）。
- 调用 `setAudioProfile`，将 `profile` 参数设置为 `AUDIO_PROFILE_MUSIC_HIGH_QUALITY`（4）或 `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO`（5）。

:::note
注：

- 请勿将 `setAudioProfile` 中的 `profile` 参数设置为 `AUDIO_PROFILE_SPEECH_STANDARD`（1）或 `AUDIO_PROFILE_IOT`（6），否则该方法不生效。
- 该方法对人声处理效果最佳，不建议用于处理包含音乐的音频数据。
- 调用 [setVoiceConversionPreset](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setvoiceconversionpreset) 后，不建议再调用以下方法，否则会覆盖该方法设置的效果：

  - [setAudioEffectPreset](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setaudioeffectpreset)
  - [setAudioEffectParameters](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setaudioeffectparameters)
  - [setVoiceBeautifierPreset](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierpreset)
  - [setVoiceBeautifierParameters](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierparameters)
  - [setLocalVoicePitch](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicepitch)
  - [setLocalVoiceFormant](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoiceformant)
  - [setLocalVoiceEqualization](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoiceequalization)
  - [setLocalVoiceReverb](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicereverb)
- 该方法依赖声动语聊动态库 libagora_audio_beauty_extension.dll。若该动态库被删除，则该功能无法正常启用。
:::

<a id="api_irtcengine_setvoiceconversionpreset__timing"></a>

### 调用时机 [#调用时机-10]

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

<a id="api_irtcengine_setvoiceconversionpreset__parameters"></a>

### 参数 [#参数-11]

<ParameterList>
<a id="preset-4"></a>
<Parameter name="preset">

预设的声动语聊特效选项，详见 [VOICE_CONVERSION_PRESET](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-voiceconversionpreset)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setvoiceconversionpreset__return_values"></a>

### 返回值 [#返回值-11]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-11]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)