# 音效文件播放 (/zh-CN/api-reference/rtc/android/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>

```java
public abstract int getEffectCurrentPosition(int soundId);
```

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

:::note
注： 请在调用 `playEffect` 方法之后调用此方法。
:::

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

### 参数 [#参数]

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

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

</Parameter>
</ParameterList>

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

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

- 方法调用成功，返回指定音效文件的播放位置（毫秒）。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

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

- [RtcEngine](/zh-CN/api-reference/rtc/android/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>

```java
public abstract int getEffectDuration(String filePath);
```

<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`。

</Parameter>
</ParameterList>

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

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

- 方法调用成功，返回指定音效文件的总时长（毫秒）。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

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

- [RtcEngine](/zh-CN/api-reference/rtc/android/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>

```java
public abstract double getEffectsVolume();
```

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

音量为整数，范围为 0 到 100。默认值为 100，表示原始音量。

:::note
注： 请在调用 `playEffect` 方法后调用此方法。
:::

<a id="api_irtcengine_geteffectsvolume__return_values"></a>

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

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

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

- [RtcEngine](/zh-CN/api-reference/rtc/android/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>

```java
public abstract int getVolumeOfEffect(int soundId);
```

<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 表示原始音量。
- 方法调用失败，返回值小于 0。

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

- [RtcEngine](/zh-CN/api-reference/rtc/android/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>

```java
public abstract int pauseAllEffects();
```

<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]

- [RtcEngine](/zh-CN/api-reference/rtc/android/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>

```java
public abstract int pauseEffect(int soundId);
```

<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]

- [RtcEngine](/zh-CN/api-reference/rtc/android/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>

```java
public abstract int playAllEffects(int loopCount, double pitch, double pan, double gain, boolean publish);
```

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

多次调用 `preloadEffect` 将多个音效预加载到内存后，可以调用该方法为频道内所有用户播放所有预加载的音效。

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

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

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

音效的循环播放次数：

- `-1`：无限循环播放音效，直到调用 [stopEffect](/zh-CN/api-reference/rtc/android/play/audio-effect-file#api_irtcengine_stopeffect) 或 [stopAllEffects](/zh-CN/api-reference/rtc/android/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.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]

- [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_playeffect2"></a>

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

## playEffect [1/2] [#playeffect-12]

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

<a id="api_irtcengine_playeffect2__prototype"></a>

```java
public abstract int playEffect(int soundId, String filePath, int loopCount, double pitch, double pan, double gain, boolean publish);
```

<a id="api_irtcengine_playeffect2__detailed_desc"></a>

该方法支持播放以 `content://` 开头的 URI 文件。关于支持的音频文件格式，详见[声网 RTC SDK 支持哪些格式的音频文件](/zh-CN/reference/faq/product/audio_format)。若本地音乐文件不存在、SDK 不支持该文件格式，或无法访问音乐文件的 URL，SDK 会报告 `AUDIO_MIXING_REASON_CAN_NOT_OPEN`。要同时播放多个音效文件，请使用不同的 `soundId` 和 `filePath` 多次调用该方法。为获得最佳用户体验，声网建议不要同时播放超过三个音频文件。

:::note
注：

- 如果需要播放在线音效文件，建议先将其缓存到本地设备，调用 `preloadEffect` 将文件预加载到内存中，再调用该方法播放音效。否则可能因加载超时或失败导致播放失败或无声。
- 如果在调用 `playEffectEx` 前调用了 `preloadEffectEx`，则 `playEffectEx` 执行后不会关闭文件资源。下次调用 `playEffectEx` 时将从头开始播放。
- 如果未调用 `preloadEffectEx` 就直接调用 `playEffectEx`，则 `playEffectEx` 执行后会销毁资源。下次调用时将尝试重新打开文件并从头播放。
:::

<a id="api_irtcengine_playeffect2__timing"></a>

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

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

<a id="api_irtcengine_playeffect2__related"></a>

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

音效文件播放完成后，SDK 会触发 [onAudioEffectFinished](/zh-CN/api-reference/rtc/android/play/audio-effect-file#callback_irtcengineeventhandler_onaudioeffectfinished) 回调。

<a id="api_irtcengine_playeffect2__parameters"></a>

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

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

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

:::note
注： 如果你已通过调用 `preloadEffect` 将音效预加载到内存中，请确保该参数的值与 `preloadEffect` 中的 `soundId` 相同。
:::

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

:::note
注： 如果你已通过调用 `preloadEffect` 将音效预加载到内存中，请确保该参数的值与 `preloadEffect` 中的 `filePath` 相同。
:::

音效文件路径。支持以下格式：

- 以 `content://` 开头的 URI 地址。
- 以 `/assets/` 开头的路径。
- URL。
- 本地文件的绝对路径（需精确到文件名和扩展名）。

支持的音频格式包括 MP3、AAC、M4A、MP4、WAV 和 3GP。

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

音效的循环播放次数：

- ≥ 0：播放的次数。例如，1 表示循环播放一次，即总共播放两次。
- -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.0 到 100.0，默认值为 100.0，表示原始音量。值越小，音量越低。

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

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

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_playeffect2__return_values"></a>

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

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

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

- [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_playeffect3"></a>

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

## playEffect [2/2] [#playeffect-22]

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

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

```java
public abstract int playEffect(int soundId, String filePath, int loopCount, double pitch, double pan, double gain, boolean publish, int startPos);
```

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

该方法支持播放以 `content://` 开头的 URI 文件。关于支持的音频文件格式，参见 `What formats of audio files does the Agora RTC SDK support`。如果本地音频文件不存在、SDK 不支持该文件格式，或无法访问音频文件的 URL，SDK 会报告 `AUDIO_MIXING_REASON_CAN_NOT_OPEN`。

:::note
注：

- 如果需要播放在线音效文件，建议先将其缓存到本地设备，调用 `preloadEffect` 将文件预加载到内存中，再调用此方法播放。否则可能因加载超时或失败导致播放失败或无声。
- 如果在调用 `playEffect` 前已调用 `preloadEffect`，则 `playEffect` 执行后不会关闭文件资源。下次调用 `playEffect` 时将从头开始播放。
- 如果未调用 `preloadEffect` 就执行 `playEffect`，则播放结束后资源将被销毁。下次调用 `playEffect` 时将尝试重新打开文件并从头播放。
:::

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

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

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

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

### 相关回调 [#相关回调-1]

音效文件播放完成后，SDK 会触发 [onAudioEffectFinished](/zh-CN/api-reference/rtc/android/play/audio-effect-file#callback_irtcengineeventhandler_onaudioeffectfinished) 回调。

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

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

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

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

:::note
注： 如果你已通过调用 `preloadEffect` 将音效预加载到内存中，请确保该参数的值与 `preloadEffect` 中的 `soundId` 相同。
:::

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

文件路径。支持以 `content://` 开头的 URI、以 `/assets/` 开头的路径、URL 以及本地文件的绝对路径。路径需精确到文件名及扩展名。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV 和 3GP。

:::note
注： 如果你已通过调用 `preloadEffect` 将音效预加载到内存中，请确保该参数的值与 `preloadEffect` 中的 `filePath` 相同。
:::

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

音效循环播放的次数：

- ≥ 0：播放的次数。例如，1 表示循环播放一次，即总共播放两次。
- -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.0 到 100.0。默认值为 100.0，表示原始音量。值越小，音量越低。

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

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

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

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

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

</Parameter>
</ParameterList>

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

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

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

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

- [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine)

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

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

## playEffectEx [1/2] [#playeffectex-12]

在频道中播放指定的音效。

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

```java
public abstract int playEffectEx(RtcConnection connection, int soundId, String filePath, int loopCount, double pitch, double pan, double gain, boolean publish, int startPos);
```

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

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

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

:::note
注：

- 声网建议不要同时播放超过三个音效。
- 此方法中的音效 ID 和文件路径必须与 `preloadEffectEx` 方法中的一致。
- 如果在调用 `playEffectEx` 之前调用了 `preloadEffectEx`，则在 `playEffectEx` 执行后文件资源不会被关闭。下次调用 `playEffectEx` 时将从头开始播放。
- 如果在调用 `playEffectEx` 之前未调用 `preloadEffectEx`，则在 `playEffectEx` 执行后资源将被销毁。下次调用 `playEffectEx` 时将尝试重新打开文件并从头开始播放。
:::

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

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

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

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

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

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

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

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

音效 ID。

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

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

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

音效的循环播放次数：

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

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

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

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

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

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

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

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

</Parameter>
<a id="publish-3"></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>

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

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

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

- [RtcEngineEx](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineex)

<a id="api_irtcengineex_playeffectex2"></a>

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

## playEffectEx [2/2] [#playeffectex-22]

在频道中播放指定音效。

<a id="api_irtcengineex_playeffectex2__prototype"></a>

```java
public abstract int playEffectEx(RtcConnection connection, int soundId, String filePath, int loopCount, double pitch, double pan, double gain, boolean publish);
```

<a id="api_irtcengineex_playeffectex2__detailed_desc"></a>

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

调用 `preloadEffectEx` 预加载音效后，可以使用该方法将指定音效播放给频道中的所有用户。你可以多次调用该方法，并传入不同的 `soundId` 和 `filePath`，以同时播放多个音效文件。每次调用该方法只能播放一个音效。

:::note
注：

- 声网建议不要同时播放超过三个音效。
- 本方法中的音效 ID 和文件路径必须与 `preloadEffectEx` 方法中保持一致。
- 如果在调用 `playEffectEx` 之前调用了 `preloadEffectEx`，则在 `playEffectEx` 执行后文件资源不会被关闭。下次调用 `playEffectEx` 时将从头开始播放。
- 如果在调用 `playEffectEx` 之前未调用 `preloadEffectEx`，则在 `playEffectEx` 执行后资源将被销毁。下次调用 `playEffectEx` 时将尝试重新打开文件并从头播放。
:::

<a id="api_irtcengineex_playeffectex2__scenario"></a>

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

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

<a id="api_irtcengineex_playeffectex2__parameters"></a>

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

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

连接信息，详见 [RtcConnection](/zh-CN/api-reference/rtc/android/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="loopcount-4"></a>
<Parameter name="loopCount">

音效的循环播放次数：

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

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

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

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

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

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

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

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

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

是否在频道中发布音效：

- true：在频道中发布音效。
- false：不在频道中发布音效。

</Parameter>
</ParameterList>

<a id="api_irtcengineex_playeffectex2__return_values"></a>

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

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

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

- [RtcEngineEx](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineex)

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

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

## preloadEffect [1/2] [#preloadeffect-12]

预加载指定的音效文件。

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

```java
public abstract int preloadEffect(int soundId, String filePath, int startPos);
```

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

该方法每次调用时仅将一个指定的音效文件预加载到内存中。若需预加载多个音效文件，请多次调用该方法。

:::note
注：

- 为确保通信流畅，请限制音效文件的大小。
- 声网建议在加入频道前调用此方法。
- 如果在调用 `playEffect` 之前调用了 `preloadEffect`，则 `playEffect` 执行后不会关闭文件资源。下次调用 `playEffect` 时将从头开始播放。
- 如果在调用 `playEffect` 之前未调用 `preloadEffect`，则 `playEffect` 执行后资源将被销毁。下次调用 `playEffect` 时将尝试重新打开文件并从头开始播放。
:::

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

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

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

音效的 ID。

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

本地音效文件的绝对路径或在线音效文件的 URL。

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

在线音效文件的起始播放位置。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 和 wav。

</Parameter>
</ParameterList>

<a id="api_irtcengine_preloadeffect__return_values"></a>

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

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

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

- [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_preloadeffect2"></a>

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

## preloadEffect [2/2] [#preloadeffect-22]

将指定的音效文件预加载到内存中。

<a id="api_irtcengine_preloadeffect2__prototype"></a>

```java
public abstract int preloadEffect(int soundId, String filePath);
```

<a id="api_irtcengine_preloadeffect2__detailed_desc"></a>

确保所有预加载文件的总大小不超过限制。详见 `声网 RTC SDK 支持哪些音频文件格式`。

:::note
注：

- 如果在调用 `playEffect` 之前调用了 `preloadEffect`，`playEffect` 执行后不会关闭文件资源。下次调用 `playEffect` 时，将从头开始播放。
- 如果在调用 `playEffect` 之前未调用 `preloadEffect`，`playEffect` 执行后会销毁资源。下次调用 `playEffect` 时，将尝试重新打开文件并从头开始播放。
:::

<a id="api_irtcengine_preloadeffect2__timing"></a>

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

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

<a id="api_irtcengine_preloadeffect2__parameters"></a>

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

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

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

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

文件路径。支持以下格式：

- URL 地址。
- 绝对路径。
- 以 `/assets/` 开头的文件路径。

路径需精确到文件名和后缀名。如果使用绝对路径访问本地文件，可能会遇到权限问题，建议使用 URI 地址，例如：`content://com.android.providers.media.documents/document/audio%3A14441`。

</Parameter>
</ParameterList>

<a id="api_irtcengine_preloadeffect2__return_values"></a>

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

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

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

- [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine)

<a id="api_irtcengineex_preloadeffectex"></a>

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

## preloadEffectEx [1/2] [#preloadeffectex-12]

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

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

```java
public abstract int preloadEffectEx(RtcConnection connection, int soundId, String filePath, int startPos);
```

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

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

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

:::note
注：

- 为确保使用体验流畅，音效文件的大小不应超过限制。
- 声网建议在加入频道前调用该方法。
- 如果在调用 `playEffectEx` 前已调用 `preloadEffectEx`，则 `playEffectEx` 执行后不会关闭文件资源。下次调用 `playEffectEx` 时将从头开始播放。
- 如果在调用 `playEffectEx` 前未调用 `preloadEffectEx`，则 `playEffectEx` 执行后会销毁文件资源。下次调用 `playEffectEx` 时将尝试重新打开文件并从头开始播放。
:::

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

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

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

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

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

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

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

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

音效 ID。

</Parameter>
<a id="filepath-7"></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>

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

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

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

- [RtcEngineEx](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineex)

<a id="api_irtcengineex_preloadeffectex2"></a>

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

## preloadEffectEx [2/2] [#preloadeffectex-22]

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

<a id="api_irtcengineex_preloadeffectex2__prototype"></a>

```java
public abstract int preloadEffectEx(RtcConnection connection, int soundId, String filePath);
```

<a id="api_irtcengineex_preloadeffectex2__detailed_desc"></a>

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

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

:::note
注：

- 为确保使用体验流畅，音效文件的大小不应超过限制。
- 声网建议在加入频道前调用该方法。
- 如果在调用 `playEffectEx` 之前调用了 `preloadEffectEx`，则在 `playEffectEx` 执行后文件资源不会被关闭。下次调用 `playEffectEx` 时将从头开始播放。
- 如果在调用 `playEffectEx` 之前未调用 `preloadEffectEx`，则在 `playEffectEx` 执行后资源将被销毁。下次调用 `playEffectEx` 时将尝试重新打开文件并从头开始播放。
:::

<a id="api_irtcengineex_preloadeffectex2__scenario"></a>

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

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

<a id="api_irtcengineex_preloadeffectex2__parameters"></a>

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

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

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

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

音效 ID。

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

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

</Parameter>
</ParameterList>

<a id="api_irtcengineex_preloadeffectex2__return_values"></a>

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

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

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

- [RtcEngineEx](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineex)

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

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

## resumeAllEffects [#resumealleffects]

恢复播放所有音效文件。

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

```java
public abstract int resumeAllEffects();
```

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

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

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

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

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

<a id="api_irtcengine_resumealleffects__return_values"></a>

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

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

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

- [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine)

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

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

## resumeEffect [#resumeeffect]

恢复播放指定音效。

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

```java
public abstract int resumeEffect(int soundId);
```

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

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

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

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

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

</Parameter>
</ParameterList>

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

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

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

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

- [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine)

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

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

## setEffectPosition [#seteffectposition]

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

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

```java
public abstract int setEffectPosition(int soundId, int pos);
```

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

:::note
注： 请在调用 `playEffect` 方法之后调用此方法。
:::

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

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

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

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

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

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

</Parameter>
</ParameterList>

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

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

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

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

- [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine)

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

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

## setEffectsVolume [#seteffectsvolume]

设置音效的播放音量。

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

```java
public abstract int setEffectsVolume(double volume);
```

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

该方法需要在调用 `playEffect` 方法之后调用。

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

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

该方法需要在调用 `playEffect` 方法之后调用。

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

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

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

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

</Parameter>
</ParameterList>

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

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

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

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

- [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine)

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

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

## setVolumeOfEffect [#setvolumeofeffect]

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

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

```java
public abstract int setVolumeOfEffect(int soundId, double volume);
```

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

在调用 `playEffect` 方法之后调用该方法。

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

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

在调用 `playEffect` 方法之后调用该方法。

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

### 参数 [#参数-16]

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

音效的 ID。每个音效文件具有唯一的 ID。

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

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

</Parameter>
</ParameterList>

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

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

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

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

- [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine)

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

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

## stopAllEffects [#stopalleffects]

停止播放所有音效。

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

```java
public abstract int stopAllEffects();
```

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

如果你只需要暂停播放，请调用 [pauseAllEffects](/zh-CN/api-reference/rtc/android/play/audio-effect-file#api_irtcengine_pausealleffects) 方法。

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

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

在调用 `playEffect` 方法之后调用。

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

### 返回值 [#返回值-20]

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

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

- [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine)

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

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

## stopEffect [#stopeffect]

停止播放指定音效。

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

```java
public abstract int stopEffect(int soundId);
```

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

如果只需要暂停播放，请调用 [pauseEffect](/zh-CN/api-reference/rtc/android/play/audio-effect-file#api_irtcengine_pauseeffect) 方法。

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

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

在调用 `playEffect` 之后调用。

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

### 参数 [#参数-17]

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

音效的 ID。每个音效都有唯一的 ID。

</Parameter>
</ParameterList>

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

### 返回值 [#返回值-21]

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

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

- [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine)

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

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

## unloadEffect [#unloadeffect]

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

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

```java
public abstract int unloadEffect(int soundId);
```

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

调用 `preloadEffect` 将音效文件加载到内存后，如需释放该音效文件，可调用 [unloadEffect](/zh-CN/api-reference/rtc/android/play/audio-effect-file#api_irtcengine_unloadeffect)。

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

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

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

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

### 参数 [#参数-18]

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

音效的 ID。每个音效都有唯一的 ID。

</Parameter>
</ParameterList>

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

### 返回值 [#返回值-22]

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

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

- [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine)

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

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

## onAudioEffectFinished [#onaudioeffectfinished]

本地音效文件播放完成时的回调。

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

```java
public void onAudioEffectFinished(int soundId) {}
```

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

<a id="callback_irtcengineeventhandler_onaudioeffectfinished__timing"></a>

### 触发时机 [#触发时机]

该回调在本地音效文件播放完成时被触发。

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

### 参数 [#参数-19]

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

音效文件的唯一 ID。

</Parameter>
</ParameterList>

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

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