# 音效文件播放 (/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:方法调用失败。