# 音效文件播放 (/zh-CN/api-reference/rtc/flutter/play/audio-effect-file) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## getEffectCurrentPosition [#geteffectcurrentposition] 获取指定音效文件的播放进度。 ```dart Future getEffectCurrentPosition(int soundId); ``` :::note 注: 该方法需要在 [playEffect](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_playeffect3) 后调用。 ::: ### 参数 [#参数] 音效的 ID。每个音效的 ID 具有唯一性。 ### 返回值 [#返回值] - 方法调用成功,返回指定音效文件的播放进度(毫秒)。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类] - [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) ## getEffectDuration [#geteffectduration] 获取指定音效文件总时长。 ```dart Future getEffectDuration(String filePath); ``` :::note 注: 该方法需要在加入频道后调用。 ::: ### 参数 [#参数-1] 文件路径: - Android: 文件路径,需精确到文件名及后缀。支持在线文件的 URL 地址,本地文件的 URI 地址、绝对路径或以 `/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`。 ### 返回值 [#返回值-1] - 方法调用成功,返回指定音效文件时长(毫秒)。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-1] - [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) ## getEffectsVolume [#geteffectsvolume] 获取音效文件的播放音量。 ```dart Future getEffectsVolume(); ``` 音量范围为 0~100。100 (默认值)为原始文件音量。 :::note 注: 该方法需要在 [playEffect](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_playeffect3) 后调用。 ::: ### 返回值 [#返回值-2] - 音效文件的音量。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-2] - [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) ## getVolumeOfEffect [#getvolumeofeffect] 获取指定音效文件的播放音量。 ```dart Future getVolumeOfEffect(int soundId); ``` ### 参数 [#参数-2] 音效文件的 ID。 ### 返回值 [#返回值-3] - ≥ 0: 方法调用成功,返回播放音量。音量范围为 [0,100]。100 为原始音量。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-3] - [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) ## pauseAllEffects [#pausealleffects] 暂停所有音效文件播放。 ```dart Future pauseAllEffects(); ``` ### 返回值 [#返回值-4] 方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-4] - [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) ## pauseEffect [#pauseeffect] 暂停音效文件播放。 ```dart Future pauseEffect(int soundId); ``` ### 参数 [#参数-3] 音效的 ID。每个音效的 ID 具有唯一性。 ### 返回值 [#返回值-5] 方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-5] - [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) ## playAllEffects [#playalleffects] 播放所有音效文件。 ```dart Future playAllEffects( {required int loopCount, required double pitch, required double pan, required int gain, bool publish = false}); ``` 多次调用 [preloadEffect](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_preloadeffect) 预加载多个音效文件后,你可以调用本方法播放所有预加载的音效文件。 ### 参数 [#参数-4] 音效文件循环播放的次数: - -1: 无限循环播放音效文件,直至调用 [stopEffect](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_stopeffect) 或 [stopAllEffects](/zh-CN/api-reference/rtc/flutter/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: (默认)不将音效发布到远端。只能本地用户能听到该音效。 ### 返回值 [#返回值-6] 方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-6] - [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) ## playEffect [#playeffect] 播放指定的本地或在线音效文件。 ```dart Future playEffect( {required int soundId, required String filePath, required int loopCount, required double pitch, required double pan, required int gain, bool publish = false, int startPos = 0}); ``` 你可以多次调用该方法,传入不同的 `soundID` 和 `filePath`,同时播放多个音效文件。为获得最佳用户体验,建议同时播放的音效文件不超过 3 个。 :::note 注: 如果你需要播放在线音效文件,声网建议先将在线音效文件缓存到本地设备,调用 [preloadEffect](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_preloadeffect) 将缓存的音效文件预加载到内存中,然后再调用此方法播放音效。否则,可能出现因在线音效文件加载超时、加载失败而导致的播放失败和无声的问题。 ::: ### 调用时机 [#调用时机] 该方法在加入频道前后均可调用。 ### 相关回调 [#相关回调] 音效文件播放结束后,SDK 会触发 [onAudioEffectFinished](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#callback_irtcengineeventhandler_onaudioeffectfinished) 回调。 ### 参数 [#参数-5] 音效的 ID。每个音效的 ID 具有唯一性。 :::note 注: 如果你已通过 [preloadEffect](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_preloadeffect) 将音效加载至内存,请确保该参数与 [preloadEffect](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_preloadeffect) 中设置的 `soundId` 相同。 ::: 播放文件的地址,支持在线文件的 URL 地址、播放文件的绝对路径,需精确到文件名及后缀。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP 等。 :::note 注: 如果你已通过 [preloadEffect](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_preloadeffect) 将音效加载至内存,请确保该参数与 [preloadEffect](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_preloadeffect) 中设置的 `filePath` 相同。 ::: 音效循环播放的次数。 - ≥ 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: 不将音效发布至远端。只有本地用户能听到音效。 音效文件的播放位置,单位为毫秒。 ### 返回值 [#返回值-7] 方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-7] - [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) ## playEffectEx [#playeffectex] 在频道中播放指定音效。 ```dart Future playEffectEx( {required RtcConnection connection, required int soundId, required String filePath, required int loopCount, required double pitch, required double pan, required int gain, bool publish = false, int startPos = 0}); ``` :::info[自从] 自 v6.6.2 版本新增。 ::: 你可以调用该方法在频道内向所有用户播放指定音效。每次调用该方法只能播放一个音效。若需同时播放多个音效,请使用不同的 `soundId` 和 `filePath` 多次调用该方法。你还可以设置是否在频道中发布该音效。 :::note 注: - 声网建议不要同时播放超过三个音效。 - 该方法中的音效 ID 和文件路径必须与 [preloadEffectEx](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengineex_preloadeffectex) 方法中的保持一致。 - 如果在调用 [playEffectEx](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengineex_playeffectex) 之前调用了 [preloadEffectEx](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengineex_preloadeffectex),[playEffectEx](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengineex_playeffectex) 执行后不会关闭文件资源。下次调用 [playEffectEx](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengineex_playeffectex) 时会直接从头开始播放。 - 如果在调用 [playEffectEx](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengineex_playeffectex) 之前未调用 [preloadEffectEx](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengineex_preloadeffectex),[playEffectEx](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengineex_playeffectex) 执行后会销毁资源。下次调用 [playEffectEx](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengineex_playeffectex) 时会尝试重新打开文件并从头播放。 ::: ### 适用场景 [#适用场景] 该方法适用于多频道场景。 ### 参数 [#参数-6] [RtcConnection](/zh-CN/api-reference/rtc/flutter/class-rtcconnection) 对象,详见 [RtcConnection](/zh-CN/api-reference/rtc/flutter/class-rtcconnection)。 音效 ID。 本地文件的绝对路径或在线文件的 URL。支持的音频格式包括 mp3、mp4、m4a、aac、3gp、mkv 和 wav。 音效的循环播放次数: - `-1`:无限循环,直到调用 [stopEffect](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_stopeffect) 或 [stopAllEffects](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_stopalleffects)。 - `0`:播放一次。 - `1`:播放两次。 音效的音调。取值范围为 0.5 到 2.0,默认值为 1.0(原始音调)。数值越小,音调越低。 音效的空间位置。取值范围为 -1.0 到 1.0: - `-1.0`:音效从用户左侧传来。 - `0.0`:音效从用户正前方传来。 - `1.0`:音效从用户右侧传来。 音效的音量。取值范围为 0 到 100,默认值为 100(原始音量)。数值越小,音量越低。 是否在频道中发布该音效: - true:在频道中发布该音效。 - false:(默认)不在频道中发布该音效。 音效文件的播放起始位置,单位为毫秒。 ### 返回值 [#返回值-8] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-8] - [RtcEngineEx](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineex) ## preloadEffect [#preloadeffect] 将音效文件加载至内存。 ```dart Future preloadEffect( {required int soundId, required String filePath, int startPos = 0}); ``` 为保证通信畅通,请注意控制预加载音效文件的大小。 该方法支持的预加载音频文件的格式见 [RTC SDK 支持播放哪些格式的音频文件](/zh-CN/reference/faq/product/audio_format)。 ### 调用时机 [#调用时机-1] 声网建议在加入频道前调用该方法。 ### 参数 [#参数-7] 音效的 ID。每个音效的 ID 具有唯一性。 文件路径: - Android: 文件路径,需精确到文件名及后缀。支持在线文件的 URL 地址,本地文件的 URI 地址、绝对路径或以 `/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`。 音效文件加载的起始位置,单位为毫秒。 ### 返回值 [#返回值-9] 方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-9] - [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) ## preloadEffectEx [#preloadeffectex] 将指定音效预加载到频道中。 ```dart Future preloadEffectEx( {required RtcConnection connection, required int soundId, required String filePath, int startPos = 0}); ``` :::info[自从] 自 v6.6.2 版本新增。 ::: 每次调用该方法时,只能将一个音效文件预加载到内存中。如果需要预加载多个音效文件,请多次调用该方法。预加载完成后,可以调用 [playEffect](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_playeffect3) 播放预加载的音效,或调用 [playAllEffects](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_playalleffects) 播放所有预加载的音效。 :::note 注: - 为确保使用体验流畅,音效文件的大小不应超过限制。 - 声网建议在加入频道前调用该方法。 - 如果在调用 [playEffectEx](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengineex_playeffectex) 前已调用 [preloadEffectEx](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengineex_preloadeffectex),则 [playEffectEx](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengineex_playeffectex) 执行后不会关闭文件资源。下次调用 [playEffectEx](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengineex_playeffectex) 时会直接从头开始播放。 - 如果在调用 [playEffectEx](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengineex_playeffectex) 前未调用 [preloadEffectEx](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengineex_preloadeffectex),则 [playEffectEx](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengineex_playeffectex) 执行后会销毁资源。下次调用 [playEffectEx](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengineex_playeffectex) 时会尝试重新打开文件并从头开始播放。 ::: ### 适用场景 [#适用场景-1] 该方法适用于多频道场景。 ### 参数 [#参数-8] 连接信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/flutter/class-rtcconnection)。 音效 ID。 本地文件的绝对路径或在线文件的 URL。支持的音频格式包括:mp3、mp4、m4a、aac、3gp、mkv 和 wav。 音效文件的播放起始位置(单位为毫秒)。 ### 返回值 [#返回值-10] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-10] - [RtcEngineEx](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineex) ## resumeAllEffects [#resumealleffects] 恢复播放所有音效文件。 ```dart Future resumeAllEffects(); ``` 当你调用 [pauseAllEffects](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_pausealleffects) 暂停播放所有音效文件后,如需恢复播放,可以调用该方法。 ### 调用时机 [#调用时机-2] 该方法需要在 [pauseAllEffects](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_pausealleffects) 后调用。 ### 返回值 [#返回值-11] 方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-11] - [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) ## resumeEffect [#resumeeffect] 恢复播放指定音效文件。 ```dart Future resumeEffect(int soundId); ``` ### 参数 [#参数-9] 音效的 ID。每个音效的 ID 具有唯一性。 ### 返回值 [#返回值-12] 方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-12] - [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) ## setEffectPosition [#seteffectposition] 设置指定音效文件的播放位置。 ```dart Future setEffectPosition({required int soundId, required int pos}); ``` 成功设置后,本地音效文件会在指定位置开始播放。 :::note 注: 该方法需要在 [playEffect](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_playeffect3) 后调用。 ::: ### 参数 [#参数-10] 音效的 ID。每个音效的 ID 具有唯一性。 音效文件的播放位置,单位为毫秒。 ### 返回值 [#返回值-13] 方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-13] - [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) ## setEffectsVolume [#seteffectsvolume] 设置音效文件的播放音量。 ```dart Future setEffectsVolume(int volume); ``` ### 调用时机 [#调用时机-3] 该方法需要在 [playEffect](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_playeffect3) 后调用。 ### 参数 [#参数-11] 播放音量。取值范围为 [0,100]。默认值为 100,表示原始音量。 ### 返回值 [#返回值-14] 方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-14] - [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) ## setVolumeOfEffect [#setvolumeofeffect] 设置指定音效文件的播放音量。 ```dart Future setVolumeOfEffect({required int soundId, required int volume}); ``` ### 调用时机 [#调用时机-4] 该方法需要在 [playEffect](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_playeffect3) 后调用。 ### 参数 [#参数-12] 指定音效的 ID。每个音效均有唯一的 ID。 播放音量。取值范围为 [0,100]。默认值为 100,表示原始音量。 ### 返回值 [#返回值-15] 方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-15] - [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) ## stopAllEffects [#stopalleffects] 停止播放所有音效文件。 ```dart Future stopAllEffects(); ``` 当你不需要再播放音效文件时,可以调用该方法停止播放。如果你仅需暂停播放,请调用 [pauseAllEffects](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_pausealleffects)。 ### 调用时机 [#调用时机-5] 该方法需要在 [playEffect](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_playeffect3) 之后调用。 ### 返回值 [#返回值-16] 方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-16] - [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) ## stopEffect [#stopeffect] 停止播放指定音效文件。 ```dart Future stopEffect(int soundId); ``` 当你不需要再播放某一音效文件时,可以调用该方法停止播放。如果你仅需暂停播放,请调用 [pauseEffect](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_pauseeffect)。 ### 调用时机 [#调用时机-6] 该方法需要在 [playEffect](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_playeffect3) 之后调用。 ### 参数 [#参数-13] 指定音效文件的 ID。每个音效文件均有唯一的 ID。 ### 返回值 [#返回值-17] 方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-17] - [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) ## unloadAllEffects [#unloadalleffects] 从内存释放所有预加载音效文件。 ```dart Future unloadAllEffects(); ``` ### 返回值 [#返回值-18] 方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-18] - [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) ## unloadEffect [#unloadeffect] 从内存释放某个预加载的音效文件。 ```dart Future unloadEffect(int soundId); ``` 调用 [preloadEffect](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_preloadeffect) 将音效文件加载至内存后,如需释放该音效文件,请调用该方法。 ### 调用时机 [#调用时机-7] 该方法在加入频道前后均可调用。 ### 参数 [#参数-14] 指定音效文件的 ID。每个音效文件均有唯一的 ID。 ### 返回值 [#返回值-19] 方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-19] - [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) ## onAudioEffectFinished [#onaudioeffectfinished] 本地音效文件播放已结束回调。 ```dart final void Function(int soundId)? onAudioEffectFinished; ``` 当播放音效结束后,会触发该回调。 ### 参数 [#参数-15] 指定音效的 ID。每个音效均有唯一的 ID。 ### 所属接口类 [#所属接口类-20] - [RtcEngineEventHandler](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineeventhandler)