# 音效文件播放 (/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file)

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

<a id="toc_audio_effect_file"></a>

<a id="api_irtcengine_geteffectcurrentposition"></a>

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

## getEffectCurrentPosition [#geteffectcurrentposition]

获取指定音效文件的播放位置。

<a id="api_irtcengine_geteffectcurrentposition__prototype"></a>

```cpp
virtual int getEffectCurrentPosition(int soundId) = 0;
```

<a id="api_irtcengine_geteffectcurrentposition__detailed_desc"></a>

:::note
注： 请在调用 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 后使用此方法。
:::

<a id="api_irtcengine_geteffectcurrentposition__parameters"></a>

### 参数 [#参数]

<ParameterList>
<a id="soundid"></a>
<Parameter name="soundId">

音效 ID。

:::note
注： 每个音效文件的 ID 是唯一的。
:::

</Parameter>
</ParameterList>

<a id="api_irtcengine_geteffectcurrentposition__return_values"></a>

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

- 方法调用成功，返回指定音效文件的播放位置（毫秒）。
- &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_geteffectduration"></a>

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

## getEffectDuration [#geteffectduration]

获取音效文件的时长。

<a id="api_irtcengine_geteffectduration__prototype"></a>

```cpp
virtual int getEffectDuration(const char* filePath) = 0;
```

<a id="api_irtcengine_geteffectduration__detailed_desc"></a>

:::note
注： 请在加入频道后调用此方法。
:::

<a id="api_irtcengine_geteffectduration__parameters"></a>

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

<ParameterList>
<a id="filepath"></a>
<Parameter name="filePath">

音效文件路径：

- Android：文件路径需精确到文件名和后缀名。支持 URL 地址、绝对路径，或以 `/assets/` 开头的文件路径。使用绝对路径访问本地文件可能会遇到权限问题，建议使用 URI 地址。例如：`content://com.android.providers.media.documents/document/audio%3A14441`。
- Windows：音效文件的绝对路径或 URL 地址（包括文件名后缀）。例如：C:\\music\\audio.mp4。
- iOS 或 macOS：音效文件的绝对路径或 URL 地址（包括文件名后缀）。例如：`/var/mobile/Containers/Data/audio.mp4`。

</Parameter>
</ParameterList>

<a id="api_irtcengine_geteffectduration__return_values"></a>

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

- 方法调用成功，返回指定音效文件的总时长（毫秒）。
- &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_geteffectsvolume"></a>

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

## getEffectsVolume [#geteffectsvolume]

获取当前音效的音量。

<a id="api_irtcengine_geteffectsvolume__prototype"></a>

```cpp
virtual int getEffectsVolume() = 0;
```

<a id="api_irtcengine_geteffectsvolume__detailed_desc"></a>

音量为 0 到 100 之间的整数，默认值为 100，表示原始音量。

:::note
注： 请在调用 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 后调用此方法。
:::

<a id="api_irtcengine_geteffectsvolume__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_getvolumeofeffect"></a>

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

## getVolumeOfEffect [#getvolumeofeffect]

获取指定音效文件的音量。

<a id="api_irtcengine_getvolumeofeffect__prototype"></a>

```cpp
virtual int getVolumeOfEffect(int soundId) = 0;
```

<a id="api_irtcengine_getvolumeofeffect__detailed_desc"></a>

<a id="api_irtcengine_getvolumeofeffect__parameters"></a>

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

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

音效文件的 ID。

</Parameter>
</ParameterList>

<a id="api_irtcengine_getvolumeofeffect__return_values"></a>

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

- 方法调用成功，返回指定音效的音量，取值范围为 0 到 100，100 表示原始音量。
- &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_pausealleffects"></a>

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

## pauseAllEffects [#pausealleffects]

暂停所有音效。

<a id="api_irtcengine_pausealleffects__prototype"></a>

```cpp
virtual int pauseAllEffects() = 0;
```

<a id="api_irtcengine_pausealleffects__detailed_desc"></a>

<a id="api_irtcengine_pausealleffects__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_pauseeffect"></a>

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

## pauseEffect [#pauseeffect]

暂停指定音效文件的播放。

<a id="api_irtcengine_pauseeffect__prototype"></a>

```cpp
virtual int pauseEffect(int soundId) = 0;
```

<a id="api_irtcengine_pauseeffect__detailed_desc"></a>

<a id="api_irtcengine_pauseeffect__parameters"></a>

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

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

音效 ID。每个音效文件的 ID 是唯一的。

</Parameter>
</ParameterList>

<a id="api_irtcengine_pauseeffect__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_playalleffects"></a>

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

## playAllEffects [#playalleffects]

播放所有音效文件。

<a id="api_irtcengine_playalleffects__prototype"></a>

```cpp
virtual int playAllEffects(int loopCount, double pitch, double pan, int gain, bool publish = false) = 0;
```

<a id="api_irtcengine_playalleffects__detailed_desc"></a>

多次调用 [preloadEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_preloadeffect) 将多个音效文件预加载到内存后，可以调用该方法为频道内的所有用户播放所有已加载的音效文件。

<a id="api_irtcengine_playalleffects__parameters"></a>

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

<ParameterList>
<a id="loopcount"></a>
<Parameter name="loopCount">

音效文件的循环播放次数：

- -1：无限循环播放，直到调用 [stopEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_stopeffect) 或 [stopAllEffects](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_stopalleffects)。
- 0：播放一次。
- 1：播放两次。

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

音效的音调。取值范围为 [0.5, 2.0]，默认值为 1.0（原始音调）。值越小，音调越低。

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

音效的空间位置。取值范围为 [-1.0, 1.0]：

- -1.0：音效出现在左侧。
- 0：音效出现在正前方。
- 1.0：音效出现在右侧。

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

音效的音量。取值范围为 [0, 100]，默认值为 100（原始音量）。值越小，音量越低。

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

是否将音效发布给远端用户：

- true：将音效发布给远端用户，本地和远端用户都能听到。
- false：（默认）不发布音效，只有本地用户能听到。

</Parameter>
</ParameterList>

<a id="api_irtcengine_playalleffects__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_playeffect3"></a>

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

## playEffect [#playeffect]

播放指定的本地或在线音效文件。

<a id="api_irtcengine_playeffect3__prototype"></a>

```cpp
virtual int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false, int startPos = 0) = 0;
```

<a id="api_irtcengine_playeffect3__detailed_desc"></a>

调用 [preloadEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_preloadeffect) 后，可以调用该方法为频道内所有用户播放指定的音效。每次调用该方法只能播放一个音效。如需同时播放多个音效，需要多次调用该方法。

:::note
注：

- 如果需要播放在线音效文件，声网建议先将其缓存到本地设备，调用 [preloadEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_preloadeffect) 将其预加载到内存中，再调用该方法播放音效。否则，可能因加载超时或失败导致播放失败或无声。
- 建议同时播放的音效数量不超过三个。
- 该方法中的音效 ID 和文件路径必须与 [preloadEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_preloadeffect) 中的一致。
- 如果在调用 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 前调用了 [preloadEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_preloadeffect)，则在 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 执行后文件资源不会被关闭。下次调用 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 时将直接从头开始播放。
- 如果在调用 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 前未调用 [preloadEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_preloadeffect)，则在 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 执行后资源将被销毁。下次调用 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 时将尝试重新打开文件并从头播放。
:::

<a id="api_irtcengine_playeffect3__timing"></a>

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

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

<a id="api_irtcengine_playeffect3__related"></a>

### 相关回调 [#相关回调]

成功调用该方法后，SDK 会触发 [onAudioEffectFinished](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#callback_irtcengineeventhandler_onaudioeffectfinished) 回调报告音效播放完成。

<a id="api_irtcengine_playeffect3__parameters"></a>

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

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

音效的 ID。

</Parameter>
<a id="filepath-1"></a>
<Parameter name="filePath">

本地音效文件的绝对路径或在线音效文件的 URL。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 和 wav。

</Parameter>
<a id="loopcount-1"></a>
<Parameter name="loopCount">

音效的循环播放次数：

- `-1`：无限循环播放，直到调用 [stopEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_stopeffect) 或 [stopAllEffects](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_stopalleffects)。
- `0`：播放一次。
- `1`：播放两次。

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

音效的音调。取值范围为 0.5 到 2.0，默认值为 `1.0`（原始音调）。值越小，音调越低。

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

音效的空间位置。取值范围为 -1.0 到 1.0：

- `-1.0`：音效定位在左侧。
- `0.0`：音效定位在正前方。
- `1.0`：音效定位在右侧。

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

音效的音量。取值范围为 0 到 100，默认值为 `100`（原始音量）。值越小，音量越低。

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

是否将音效发布到远端：

- true：将音效发布到远端。
- false：（默认）不将音效发布到远端。

</Parameter>
<a id="startpos"></a>
<Parameter name="startPos">

音效文件的播放起始位置，单位为毫秒。

</Parameter>
</ParameterList>

<a id="api_irtcengine_playeffect3__return_values"></a>

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

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

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

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

<a id="api_irtcengineex_playeffectex"></a>

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

## playEffectEx [#playeffectex]

在频道中播放指定音效。

<a id="api_irtcengineex_playeffectex__prototype"></a>

```cpp
virtual int playEffectEx(const RtcConnection& connection, int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false, int startPos = 0) = 0;
```

<a id="api_irtcengineex_playeffectex__detailed_desc"></a>

:::info[自从]
自 v4.6.0 版本新增。
:::

你可以调用该方法在频道内向所有用户播放指定音效。每次调用该方法只能播放一个音效。若需同时播放多个音效，请使用不同的 `soundId` 和 `filePath` 多次调用该方法。你还可以设置是否在频道中发布该音效。

:::note
注：

- 声网建议不要同时播放超过三个音效。
- 该方法中的音效 ID 和文件路径必须与 [preloadEffectEx](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengineex_preloadeffectex) 方法中的保持一致。
- 如果在调用 [playEffectEx](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengineex_playeffectex) 之前调用了 [preloadEffectEx](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengineex_preloadeffectex)，[playEffectEx](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengineex_playeffectex) 执行后不会关闭文件资源。下次调用 [playEffectEx](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengineex_playeffectex) 时会直接从头开始播放。
- 如果在调用 [playEffectEx](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengineex_playeffectex) 之前未调用 [preloadEffectEx](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengineex_preloadeffectex)，[playEffectEx](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengineex_playeffectex) 执行后会销毁资源。下次调用 [playEffectEx](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengineex_playeffectex) 时会尝试重新打开文件并从头播放。
:::

<a id="api_irtcengineex_playeffectex__scenario"></a>

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

该方法适用于多频道场景。

<a id="api_irtcengineex_playeffectex__parameters"></a>

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

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

[RtcConnection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection) 对象，详见 [RtcConnection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection)。

</Parameter>
<a id="soundid-4"></a>
<Parameter name="soundId">

音效 ID。

</Parameter>
<a id="filepath-2"></a>
<Parameter name="filePath">

本地文件的绝对路径或在线文件的 URL。支持的音频格式包括 mp3、mp4、m4a、aac、3gp、mkv 和 wav。

</Parameter>
<a id="loopcount-2"></a>
<Parameter name="loopCount">

音效的循环播放次数：

- `-1`：无限循环，直到调用 [stopEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_stopeffect) 或 [stopAllEffects](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_stopalleffects)。
- `0`：播放一次。
- `1`：播放两次。

</Parameter>
<a id="pitch-2"></a>
<Parameter name="pitch">

音效的音调。取值范围为 0.5 到 2.0，默认值为 1.0（原始音调）。数值越小，音调越低。

</Parameter>
<a id="pan-2"></a>
<Parameter name="pan">

音效的空间位置。取值范围为 -1.0 到 1.0：

- `-1.0`：音效从用户左侧传来。
- `0.0`：音效从用户正前方传来。
- `1.0`：音效从用户右侧传来。

</Parameter>
<a id="gain-2"></a>
<Parameter name="gain">

音效的音量。取值范围为 0 到 100，默认值为 100（原始音量）。数值越小，音量越低。

</Parameter>
<a id="publish-2"></a>
<Parameter name="publish">

是否在频道中发布该音效：

- true：在频道中发布该音效。
- false：（默认）不在频道中发布该音效。

</Parameter>
<a id="startpos-1"></a>
<Parameter name="startPos">

音效文件的播放起始位置，单位为毫秒。

</Parameter>
</ParameterList>

<a id="api_irtcengineex_playeffectex__return_values"></a>

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

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

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

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

<a id="api_irtcengine_preloadeffect"></a>

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

## preloadEffect [#preloadeffect]

预加载指定的音效文件。

<a id="api_irtcengine_preloadeffect__prototype"></a>

```cpp
virtual int preloadEffect(int soundId, const char* filePath, int startPos = 0) = 0;
```

<a id="api_irtcengine_preloadeffect__detailed_desc"></a>

该方法每次调用时仅将一个指定的音效文件预加载到内存中。要预加载多个音效文件，需要多次调用该方法。预加载完成后，你可以调用 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 播放预加载的音效，或调用 [playAllEffects](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playalleffects) 播放所有预加载的音效。

:::note
注：

- 为确保通信顺畅，请限制音效文件的大小。
- 声网建议在加入频道前调用该方法。
- 如果在调用 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 之前调用了 [preloadEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_preloadeffect)，则在 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 执行后文件资源不会被关闭。下次调用 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 时会从头开始播放。
- 如果在调用 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 之前未调用 [preloadEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_preloadeffect)，则在 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 执行后资源会被销毁。下次调用 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 时会尝试重新打开文件并从头开始播放。
:::

<a id="api_irtcengine_preloadeffect__timing"></a>

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

建议在加入频道前调用该方法。

<a id="api_irtcengine_preloadeffect__parameters"></a>

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

<ParameterList>
<a id="soundid-5"></a>
<Parameter name="soundId">

音效 ID。每个音效文件的 ID 必须唯一。

</Parameter>
<a id="filepath-3"></a>
<Parameter name="filePath">

本地音效文件的绝对路径或在线音效文件的 URL。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 和 wav。

</Parameter>
<a id="startpos-2"></a>
<Parameter name="startPos">

音效播放的起始位置，单位为毫秒。默认值为 0，表示从头开始播放。

</Parameter>
</ParameterList>

<a id="api_irtcengine_preloadeffect__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_irtcengineex_preloadeffectex"></a>

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

## preloadEffectEx [#preloadeffectex]

将指定音效预加载到频道中。

<a id="api_irtcengineex_preloadeffectex__prototype"></a>

```cpp
virtual int preloadEffectEx(const RtcConnection& connection, int soundId, const char* filePath, int startPos = 0) = 0;
```

<a id="api_irtcengineex_preloadeffectex__detailed_desc"></a>

:::info[自从]
自 v4.6.0 版本新增。
:::

每次调用该方法时，只能将一个音效文件预加载到内存中。如果需要预加载多个音效文件，请多次调用该方法。预加载完成后，可以调用 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 播放预加载的音效，或调用 [playAllEffects](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playalleffects) 播放所有预加载的音效。

:::note
注：

- 为确保使用体验流畅，音效文件的大小不应超过限制。
- 声网建议在加入频道前调用该方法。
- 如果在调用 [playEffectEx](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengineex_playeffectex) 前已调用 [preloadEffectEx](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengineex_preloadeffectex)，则 [playEffectEx](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengineex_playeffectex) 执行后不会关闭文件资源。下次调用 [playEffectEx](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengineex_playeffectex) 时会直接从头开始播放。
- 如果在调用 [playEffectEx](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengineex_playeffectex) 前未调用 [preloadEffectEx](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengineex_preloadeffectex)，则 [playEffectEx](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengineex_playeffectex) 执行后会销毁资源。下次调用 [playEffectEx](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengineex_playeffectex) 时会尝试重新打开文件并从头开始播放。
:::

<a id="api_irtcengineex_preloadeffectex__scenario"></a>

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

该方法适用于多频道场景。

<a id="api_irtcengineex_preloadeffectex__parameters"></a>

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

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

连接信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection)。

</Parameter>
<a id="soundid-6"></a>
<Parameter name="soundId">

音效 ID。

</Parameter>
<a id="filepath-4"></a>
<Parameter name="filePath">

本地文件的绝对路径或在线文件的 URL。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 和 wav。

</Parameter>
<a id="startpos-3"></a>
<Parameter name="startPos">

音效文件的播放起始位置（单位为毫秒）。

</Parameter>
</ParameterList>

<a id="api_irtcengineex_preloadeffectex__return_values"></a>

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

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

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

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

<a id="api_irtcengine_resumealleffects"></a>

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

## resumeAllEffects [#resumealleffects]

恢复播放所有音效文件。

<a id="api_irtcengine_resumealleffects__prototype"></a>

```cpp
virtual int resumeAllEffects() = 0;
```

<a id="api_irtcengine_resumealleffects__detailed_desc"></a>

调用 [pauseAllEffects](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_pausealleffects) 暂停播放后，可以调用该方法恢复播放。

<a id="api_irtcengine_resumealleffects__timing"></a>

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

请在调用 [pauseAllEffects](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_pausealleffects) 之后调用此方法。

<a id="api_irtcengine_resumealleffects__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)

<a id="api_irtcengine_resumeeffect"></a>

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

## resumeEffect [#resumeeffect]

恢复播放指定音效的播放。

<a id="api_irtcengine_resumeeffect__prototype"></a>

```cpp
virtual int resumeEffect(int soundId) = 0;
```

<a id="api_irtcengine_resumeeffect__detailed_desc"></a>

<a id="api_irtcengine_resumeeffect__parameters"></a>

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

<ParameterList>
<a id="soundid-7"></a>
<Parameter name="soundId">

音效 ID。每个音效文件的 ID 是唯一的。

</Parameter>
</ParameterList>

<a id="api_irtcengine_resumeeffect__return_values"></a>

### 返回值 [#返回值-12]

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

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

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

<a id="api_irtcengine_seteffectposition"></a>

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

## setEffectPosition [#seteffectposition]

设置音效文件的播放位置。

<a id="api_irtcengine_seteffectposition__prototype"></a>

```cpp
virtual int setEffectPosition(int soundId, int pos) = 0;
```

<a id="api_irtcengine_seteffectposition__detailed_desc"></a>

设置成功后，音效文件将从指定位置开始播放。

:::note
注： 请在调用 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 方法后调用此方法。
:::

<a id="api_irtcengine_seteffectposition__parameters"></a>

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

<ParameterList>
<a id="soundid-8"></a>
<Parameter name="soundId">

音效 ID。每个音效文件的 ID 是唯一的。

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

音效文件的播放位置，单位为毫秒。

</Parameter>
</ParameterList>

<a id="api_irtcengine_seteffectposition__return_values"></a>

### 返回值 [#返回值-13]

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

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

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

<a id="api_irtcengine_seteffectsvolume"></a>

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

## setEffectsVolume [#seteffectsvolume]

设置音效播放音量。

<a id="api_irtcengine_seteffectsvolume__prototype"></a>

```cpp
virtual int setEffectsVolume(int volume) = 0;
```

<a id="api_irtcengine_seteffectsvolume__detailed_desc"></a>

<a id="api_irtcengine_seteffectsvolume__timing"></a>

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

在调用 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 方法之后调用。

<a id="api_irtcengine_seteffectsvolume__parameters"></a>

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

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

播放音量。取值范围为 [0, 100]。默认值为 100，表示原始音量。

</Parameter>
</ParameterList>

<a id="api_irtcengine_seteffectsvolume__return_values"></a>

### 返回值 [#返回值-14]

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

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

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

<a id="api_irtcengine_setvolumeofeffect"></a>

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

## setVolumeOfEffect [#setvolumeofeffect]

设置指定音效文件的播放音量。

<a id="api_irtcengine_setvolumeofeffect__prototype"></a>

```cpp
virtual int setVolumeOfEffect(int soundId, int volume) = 0;
```

<a id="api_irtcengine_setvolumeofeffect__detailed_desc"></a>

<a id="api_irtcengine_setvolumeofeffect__timing"></a>

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

在调用 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 之后调用该方法。

<a id="api_irtcengine_setvolumeofeffect__parameters"></a>

### 参数 [#参数-12]

<ParameterList>
<a id="soundid-9"></a>
<Parameter name="soundId">

音效文件的唯一 ID。

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

播放音量，取值范围为 [0, 100]。（默认）为 100，表示原始音量。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setvolumeofeffect__return_values"></a>

### 返回值 [#返回值-15]

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

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

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

<a id="api_irtcengine_stopalleffects"></a>

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

## stopAllEffects [#stopalleffects]

停止播放所有音效。

<a id="api_irtcengine_stopalleffects__prototype"></a>

```cpp
virtual int stopAllEffects() = 0;
```

<a id="api_irtcengine_stopalleffects__detailed_desc"></a>

调用该方法可以停止所有音效的播放。如果只需暂停播放，请调用 [pauseAllEffects](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_pausealleffects)。

<a id="api_irtcengine_stopalleffects__timing"></a>

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

请在调用 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 之后调用此方法。

<a id="api_irtcengine_stopalleffects__return_values"></a>

### 返回值 [#返回值-16]

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

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

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

<a id="api_irtcengine_stopeffect"></a>

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

## stopEffect [#stopeffect]

停止播放指定音效。

<a id="api_irtcengine_stopeffect__prototype"></a>

```cpp
virtual int stopEffect(int soundId) = 0;
```

<a id="api_irtcengine_stopeffect__detailed_desc"></a>

调用该方法可停止播放指定的音效。如果只需暂停播放，请调用 [pauseEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_pauseeffect) 方法。

<a id="api_irtcengine_stopeffect__timing"></a>

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

请在调用 [playEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 方法之后调用此方法。

<a id="api_irtcengine_stopeffect__parameters"></a>

### 参数 [#参数-13]

<ParameterList>
<a id="soundid-10"></a>
<Parameter name="soundId">

音效的 ID，每个音效具有唯一的 ID。

</Parameter>
</ParameterList>

<a id="api_irtcengine_stopeffect__return_values"></a>

### 返回值 [#返回值-17]

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

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

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

<a id="api_irtcengine_unloadalleffects"></a>

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

## unloadAllEffects [#unloadalleffects]

释放内存中的所有预加载音效。

<a id="api_irtcengine_unloadalleffects__prototype"></a>

```cpp
virtual int unloadAllEffects() = 0;
```

<a id="api_irtcengine_unloadalleffects__detailed_desc"></a>

<a id="api_irtcengine_unloadalleffects__return_values"></a>

### 返回值 [#返回值-18]

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

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

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

<a id="api_irtcengine_unloadeffect"></a>

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

## unloadEffect [#unloadeffect]

释放指定的预加载音效文件。

<a id="api_irtcengine_unloadeffect__prototype"></a>

```cpp
virtual int unloadEffect(int soundId) = 0;
```

<a id="api_irtcengine_unloadeffect__detailed_desc"></a>

调用 [preloadEffect](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_preloadeffect) 将音效文件加载到内存后，如需释放该音效文件，可调用该方法。

<a id="api_irtcengine_unloadeffect__timing"></a>

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

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

<a id="api_irtcengine_unloadeffect__parameters"></a>

### 参数 [#参数-14]

<ParameterList>
<a id="soundid-11"></a>
<Parameter name="soundId">

音效的 ID。

</Parameter>
</ParameterList>

<a id="api_irtcengine_unloadeffect__return_values"></a>

### 返回值 [#返回值-19]

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

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

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

<a id="callback_irtcengineeventhandler_onaudioeffectfinished"></a>

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

## onAudioEffectFinished [#onaudioeffectfinished]

本地音效文件播放结束回调。

<a id="callback_irtcengineeventhandler_onaudioeffectfinished__prototype"></a>

```cpp
virtual void onAudioEffectFinished(int soundId) {}
```

<a id="callback_irtcengineeventhandler_onaudioeffectfinished__detailed_desc"></a>

当本地音效文件播放结束时，会触发该回调。你可以通过该回调获知指定音效是否已播放完成。

<a id="callback_irtcengineeventhandler_onaudioeffectfinished__parameters"></a>

### 参数 [#参数-15]

<ParameterList>
<a id="soundid-12"></a>
<Parameter name="soundId">

音效 ID，每个音效文件的唯一标识。

</Parameter>
</ParameterList>

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

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