# 音效文件播放 (/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## playEffect [#playeffect]
播放指定的本地或在线音效文件。
```ts
public abstract playEffect(soundId:number,filePath:string,loopCount:number,pitch:number,pan:number,gain:number,publish?:boolean,startPos?:number):Promise;
```
你可以多次调用该方法,传入不同的 soundID 和 filePath,同时播放多个音效文件。为获得最佳用户体验,建议同时播放的音效文件不超过 3 个。
### 调用时机 [#调用时机]
该方法在加入频道前后均可调用。
### 调用限制 [#调用限制]
无。
### 相关回调 [#相关回调]
音效文件播放结束后,SDK 会触发 onAudioEffectFinished 回调。
### 参数 [#参数]
音效的 ID。每个音效的 ID 具有唯一性。
播放文件的地址。
音效循环播放的次数。
- ≥ 0: 循环播放次数。例如,1 表示循环播放 1 次,即总计播放 2 次。
- -1: 无限循环播放。
音效的音调,取值范围为 [0.5,2.0]。默认值为 1.0,表示原始音调。取值越小,则音调越低。
音效的空间位置。取值范围为 [-1.0,1.0],例如:
- -1.0:音效出现在左边
- 0.0:音效出现在正前方
- 1.0:音效出现在右边
音效的音量。取值范围为 [0.0,100.0]。默认值为 100.0,表示原始音量。取值越小,则音量越低。
是否将音效发布至远端:
- `true`: 将音效发布至远端。本地用户和远端用户都能听到音效。
- `false`: 不将音效发布至远端。只有本地用户能听到音效。
音效文件的播放位置,单位为毫秒。
### 返回值 [#返回值]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
## stopEffect [#stopeffect]
停止播放指定音效文件。
```ts
public abstract stopEffect(soundId:number):number;
```
### 调用时机 [#调用时机-1]
该方法需要在 [playEffect](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_playeffect3) 之后调用。
### 调用限制 [#调用限制-1]
无。
### 参数 [#参数-1]
指定音效文件的 ID。每个音效文件均有唯一的 ID。
### 返回值 [#返回值-1]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
## playAllEffects [#playalleffects]
播放所有音效文件。
```ts
public abstract playAllEffects(loopCount:number,pitch:number,pan:number,gain:number,publish:boolean):number;
```
### 详情 [#详情]
多次调用 [preloadEffect](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_preloadeffect) 预加载多个音效文件后,你可以调用本方法播放所有预加载的音效文件。
### 参数 [#参数-2]
音效文件循环播放的次数:
- -1: 无限循环播放音效文件,直至调用 [stopEffect](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_stopeffect) 或 [stopAllEffects](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_stopalleffects) 后停止。
- 0: 播放音效文件一次。
- 1: 播放音效文件两次。
音效的音调。取值范围为 [0.5,2.0]。默认值为 1.0,代表原始音调。取值越小,则音调越低。
音效的空间位置。取值范围为 [-1.0,1.0]:
- -1.0: 音效出现在左边。
- 0: 音效出现在正前边。
- 1.0: 音效出现在右边。
音效的音量。取值范围为 [0,100]。100 为默认值,代表原始音量。取值越小,则音量越低。
是否将音效发布到远端:
- `true`: 将音效发布到远端。本地和远端用户都能听到该音效。
- `false`: (默认)不将音效发布到远端。只能本地用户能听到该音效。
### 返回值 [#返回值-2]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
## unloadAllEffects [#unloadalleffects]
从内存释放所有预加载音效文件。
```ts
public abstract unloadAllEffects():number;
```
### 返回值 [#返回值-3]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
## onAudioEffectFinished [#onaudioeffectfinished]
本地音效文件播放已结束回调。
```ts
onAudioEffectFinished?:(soundId:number) => void;
```
### 详情 [#详情-1]
当播放音效结束后,会触发该回调。
### 参数 [#参数-3]
指定音效的 ID。每个音效均有唯一的 ID。
### 所属接口类 [#所属接口类]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengineeventhandler)
## getEffectsVolume [#geteffectsvolume]
获取音效文件的播放音量。
```ts
public abstract getEffectsVolume():number;
```
### 参数 [#参数-4]
### 返回值 [#返回值-4]
0:方法调用成功;小于 0:方法调用失败。
## setEffectsVolume [#seteffectsvolume]
设置音效文件的播放音量。
```ts
public abstract setEffectsVolume(volume:number):number;
```
### 参数 [#参数-5]
播放音量。取值范围为 [0,100]。默认值为 100,表示原始音量。
### 返回值 [#返回值-5]
0:方法调用成功;小于 0:方法调用失败。
## preloadEffect [#preloadeffect]
将音效文件加载至内存。
```ts
public abstract preloadEffect(soundId:number,filePath:string,startPos?:number):Promise;
```
### 参数 [#参数-6]
音效的 ID。每个音效的 ID 具有唯一性。
文件路径:
音效文件加载的起始位置,单位为毫秒。
### 返回值 [#返回值-6]
Promise 完成时返回操作结果。
## setVolumeOfEffect [#setvolumeofeffect]
设置指定音效文件的播放音量。
```ts
public abstract setVolumeOfEffect(soundId:number,volume:number):number;
```
### 参数 [#参数-7]
指定音效的 ID。每个音效均有唯一的 ID。
播放音量。取值范围为 [0,100]。默认值为 100,表示原始音量。
### 返回值 [#返回值-7]
0:方法调用成功;小于 0:方法调用失败。
## pauseEffect [#pauseeffect]
暂停音效文件播放。
```ts
public abstract pauseEffect(soundId:number):number;
```
### 参数 [#参数-8]
音效文件的 ID。
### 返回值 [#返回值-8]
0:方法调用成功;小于 0:方法调用失败。
## pauseAllEffects [#pausealleffects]
暂停所有音效文件播放。
```ts
public abstract pauseAllEffects():number;
```
### 参数 [#参数-9]
### 返回值 [#返回值-9]
0:方法调用成功;小于 0:方法调用失败。
## resumeEffect [#resumeeffect]
恢复播放指定音效文件。
```ts
public abstract resumeEffect(soundId:number):number;
```
### 参数 [#参数-10]
音效文件的 ID。
### 返回值 [#返回值-10]
0:方法调用成功;小于 0:方法调用失败。
## resumeAllEffects [#resumealleffects]
恢复播放所有音效文件。
```ts
public abstract resumeAllEffects():number;
```
### 参数 [#参数-11]
### 返回值 [#返回值-11]
0:方法调用成功;小于 0:方法调用失败。
## stopAllEffects [#stopalleffects]
停止播放所有音效文件。
```ts
public abstract stopAllEffects():number;
```
### 参数 [#参数-12]
### 返回值 [#返回值-12]
0:方法调用成功;小于 0:方法调用失败。
## unloadEffect [#unloadeffect]
从内存释放某个预加载的音效文件。
```ts
public abstract unloadEffect(soundId:number):number;
```
### 参数 [#参数-13]
指定音效文件的 ID。每个音效文件均有唯一的 ID。
### 返回值 [#返回值-13]
0:方法调用成功;小于 0:方法调用失败。
## getVolumeOfEffect [#getvolumeofeffect]
获取指定音效文件的播放音量。
```ts
public abstract getVolumeOfEffect(soundId:number):number;
```
### 参数 [#参数-14]
音效文件的 ID。
### 返回值 [#返回值-14]
0:方法调用成功;小于 0:方法调用失败。