# 音效文件播放 (/zh-CN/api-reference/rtc/unreal-cpp/play/audio-effect-file) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## getEffectCurrentPosition [#geteffectcurrentposition] 获取指定音效文件的播放进度。 ```cpp virtual int getEffectCurrentPosition(int soundId) = 0; ``` ### 详情 [#详情] :::caution 注意: 该方法需要在 playEffect 后调用。 ::: ### 参数 [#参数] 音效的 ID。每个音效的 ID 具有唯一性。 ### 返回值 [#返回值] - 方法调用成功,返回指定音效文件的播放进度(毫秒)。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类] - [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) ## getEffectDuration [#geteffectduration] 获取指定音效文件总时长。 ```cpp virtual int getEffectDuration(const char* filePath) = 0; ``` ### 详情 [#详情-1] :::caution 注意: 该方法需要在加入频道后调用。 ::: ### 参数 [#参数-1] 文件路径: - Android: 文件路径,需精确到文件名及后缀。支持在线文件的 URL 地址,本地文件的 URI 地址、绝对路径或以 `/assets/` 开头的路径。通过绝对路径访问本地文件可能会遇到权限问题,建议使用 URI 地址访问本地文件。例如 `content://com.android.providers.media.documents/document/audio%3A14441`。 - Windows: 音频文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如 `C:\music\audio.mp4`。 ### 返回值 [#返回值-1] - 方法调用成功,返回指定音效文件时长(毫秒)。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-1] - [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) ## getEffectsVolume [#geteffectsvolume] 获取音效文件的播放音量。 ```cpp virtual int getEffectsVolume() = 0; ``` ### 详情 [#详情-2] 音量范围为 0~100。100 (默认值)为原始文件音量。 :::caution 注意: 该方法需要在 [playEffect](/zh-CN/api-reference/rtc/unreal-cpp/play/audio-effect-file#api_irtcengine_playeffect3) 后调用。 ::: ### 返回值 [#返回值-2] - 音效文件的音量。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-2] - [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) ## getVolumeOfEffect [#getvolumeofeffect] 获取指定音效文件的播放音量。 ```cpp virtual int getVolumeOfEffect(int soundId) = 0; ``` ### 参数 [#参数-2] 音效文件的 ID。 ### 返回值 [#返回值-3] - ≥ 0: 方法调用成功,返回播放音量。音量范围为 [0,100]。100 为原始音量。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-3] - [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) ## pauseAllEffects [#pausealleffects] 暂停所有音效文件播放。 ```cpp virtual int pauseAllEffects() = 0; ``` ### 返回值 [#返回值-4] - 0: 方法调用成功。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-4] - [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) ## pauseEffect [#pauseeffect] 暂停音效文件播放。 ```cpp virtual int pauseEffect(int soundId) = 0; ``` ### 参数 [#参数-3] 音效的 ID。每个音效的 ID 具有唯一性。 ### 返回值 [#返回值-5] - 0: 方法调用成功。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-5] - [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) ## playAllEffects [#playalleffects] 播放所有音效文件。 ```cpp virtual int playAllEffects(int loopCount, double pitch, double pan, int gain, bool publish = false) = 0; ``` ### 详情 [#详情-3] 多次调用 [preloadEffect](/zh-CN/api-reference/rtc/unreal-cpp/play/audio-effect-file#api_irtcengine_preloadeffect) 预加载多个音效文件后,你可以调用本方法播放所有预加载的音效文件。 ### 参数 [#参数-4] 音效文件循环播放的次数: - -1: 无限循环播放音效文件,直至调用 [stopEffect](/zh-CN/api-reference/rtc/unreal-cpp/play/audio-effect-file#api_irtcengine_stopeffect) 或 [stopAllEffects](/zh-CN/api-reference/rtc/unreal-cpp/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] - 0: 方法调用成功。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-6] - [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) ## playEffect [#playeffect] 播放指定的本地或在线音效文件。 ```cpp virtual int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish, int startPos) = 0; ``` 你可以多次调用该方法,传入不同的 soundID 和 filePath,同时播放多个音效文件。为获得最佳用户体验,建议同时播放的音效文件不超过 3 个。 ### 调用时机 [#调用时机] 该方法在加入频道前后均可调用。 ### 调用限制 [#调用限制] 如果你需要播放在线音效文件,声网建议先将在线音效文件缓存到本地设备,调用 [preloadEffect](/zh-CN/api-reference/rtc/unreal-cpp/play/audio-effect-file#api_irtcengine_preloadeffect) 将缓存的音效文件预加载到内存中,然后再调用此方法播放音效。否则,可能出现因在线音效文件加载超时、加载失败而导致的播放失败和无声的问题。 ### 相关回调 [#相关回调] 音效文件播放结束后,SDK 会触发 onAudioEffectFinished 回调。 ### 参数 [#参数-5] 音效的 ID。每个音效的 ID 具有唯一性。 :::caution 注意: 如果你已通过 [preloadEffect](/zh-CN/api-reference/rtc/unreal-cpp/play/audio-effect-file#api_irtcengine_preloadeffect) 将音效加载至内存,请确保该参数与 preloadEffect 中设置的 soundId 相同。 ::: 播放文件的地址,支持在线文件的 URL 地址、播放文件的绝对路径,需精确到文件名及后缀。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP 等。 :::caution 注意: 如果你已通过 [preloadEffect](/zh-CN/api-reference/rtc/unreal-cpp/play/audio-effect-file#api_irtcengine_preloadeffect) 将音效加载至内存,请确保该参数与 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] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-7] - [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) ## preloadEffect [#preloadeffect] 将音效文件加载至内存。 ```cpp virtual int preloadEffect(int soundId, const char* filePath, int startPos = 0) = 0; ``` 为保证通信畅通,请注意控制预加载音效文件的大小。 该方法支持的预加载音频文件的格式见 [RTC SDK 支持播放哪些格式的音频文件](/zh-CN/reference/faq/product/audio_format)。 ### 调用时机 [#调用时机-1] 声网建议在加入频道前调用该方法。 ### 调用限制 [#调用限制-1] 无。 ### 参数 [#参数-6] 音效的 ID。每个音效的 ID 具有唯一性。 文件路径: - Android: 文件路径,需精确到文件名及后缀。支持在线文件的 URL 地址,本地文件的 URI 地址、绝对路径或以 `/assets/` 开头的路径。通过绝对路径访问本地文件可能会遇到权限问题,建议使用 URI 地址访问本地文件。例如 `content://com.android.providers.media.documents/document/audio%3A14441`。 - Windows: 音频文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如 `C:\music\audio.mp4`。 ### 返回值 [#返回值-8] - 0: 方法调用成功。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-8] - [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) ## resumeAllEffects [#resumealleffects] 恢复播放所有音效文件。 ```cpp virtual int resumeAllEffects() = 0; ``` 当你调用 [pauseAllEffects](/zh-CN/api-reference/rtc/unreal-cpp/play/audio-effect-file#api_irtcengine_pausealleffects) 暂停播放所有音效文件后,如需恢复播放,可以调用该方法。 ### 调用时机 [#调用时机-2] 该方法需要在 [pauseAllEffects](/zh-CN/api-reference/rtc/unreal-cpp/play/audio-effect-file#api_irtcengine_pausealleffects) 后调用。 ### 调用限制 [#调用限制-2] 无。 ### 返回值 [#返回值-9] - 0: 方法调用成功。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-9] - [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) ## resumeEffect [#resumeeffect] 恢复播放指定音效文件。 ```cpp virtual int resumeEffect(int soundId) = 0; ``` ### 参数 [#参数-7] 音效的 ID。每个音效的 ID 具有唯一性。 ### 返回值 [#返回值-10] - 0: 方法调用成功。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-10] - [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) ## setEffectPosition [#seteffectposition] 设置指定音效文件的播放位置。 ```cpp virtual int setEffectPosition(int soundId, int pos) = 0; ``` ### 详情 [#详情-4] 成功设置后,本地音效文件会在指定位置开始播放。 :::caution 注意: 该方法需要在 playEffect 后调用。 ::: ### 参数 [#参数-8] 音效的 ID。每个音效的 ID 具有唯一性。 音效文件的播放位置,单位为毫秒。 ### 返回值 [#返回值-11] - 0: 方法调用成功。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-11] - [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) ## setEffectsVolume [#seteffectsvolume] 设置音效文件的播放音量。 ```cpp virtual int setEffectsVolume(int volume) = 0; ``` ### 调用时机 [#调用时机-3] 该方法需要在 [playEffect](/zh-CN/api-reference/rtc/unreal-cpp/play/audio-effect-file#api_irtcengine_playeffect3) 后调用。 ### 调用限制 [#调用限制-3] 无。 ### 参数 [#参数-9] 播放音量。取值范围为 [0,100]。默认值为 100,表示原始音量。 ### 返回值 [#返回值-12] - 0: 方法调用成功。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-12] - [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) ## setVolumeOfEffect [#setvolumeofeffect] 设置指定音效文件的播放音量。 ```cpp virtual int setVolumeOfEffect(int soundId, int volume) = 0; ``` ### 调用时机 [#调用时机-4] 该方法需要在 [playEffect](/zh-CN/api-reference/rtc/unreal-cpp/play/audio-effect-file#api_irtcengine_playeffect3) 后调用。 ### 调用限制 [#调用限制-4] 无。 ### 参数 [#参数-10] 指定音效的 ID。每个音效均有唯一的 ID。 播放音量。取值范围为 [0,100]。默认值为 100,表示原始音量。 ### 返回值 [#返回值-13] - 0: 方法调用成功。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-13] - [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) ## stopAllEffects [#stopalleffects] 停止播放所有音效文件。 ```cpp virtual int stopAllEffects() = 0; ``` 当你不需要再播放音效文件时,可以调用该方法停止播放。如果你仅需暂停播放,请调用 [pauseAllEffects](/zh-CN/api-reference/rtc/unreal-cpp/play/audio-effect-file#api_irtcengine_pausealleffects)。 ### 调用时机 [#调用时机-5] 该方法需要在 [playEffect](/zh-CN/api-reference/rtc/unreal-cpp/play/audio-effect-file#api_irtcengine_playeffect3) 之后调用。 ### 调用限制 [#调用限制-5] 无。 ### 返回值 [#返回值-14] - 0: 方法调用成功。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-14] - [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) ## stopEffect [#stopeffect] 停止播放指定音效文件。 ```cpp virtual int stopEffect(int soundId) = 0; ``` 当你不需要再播放某一音效文件时,可以调用该方法停止播放。如果你仅需暂停播放,请调用 [pauseEffect](/zh-CN/api-reference/rtc/unreal-cpp/play/audio-effect-file#api_irtcengine_pauseeffect)。 ### 调用时机 [#调用时机-6] 该方法需要在 [playEffect](/zh-CN/api-reference/rtc/unreal-cpp/play/audio-effect-file#api_irtcengine_playeffect3) 之后调用。 ### 调用限制 [#调用限制-6] 无。 ### 参数 [#参数-11] 指定音效文件的 ID。每个音效文件均有唯一的 ID。 ### 返回值 [#返回值-15] - 0: 方法调用成功。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-15] - [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) ## unloadAllEffects [#unloadalleffects] 从内存释放所有预加载音效文件。 ```cpp virtual int unloadAllEffects() = 0; ``` ### 返回值 [#返回值-16] - 0: 方法调用成功。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-16] - [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) ## unloadEffect [#unloadeffect] 从内存释放某个预加载的音效文件。 ```cpp virtual int unloadEffect(int soundId) = 0; ``` 调用 [preloadEffect](/zh-CN/api-reference/rtc/unreal-cpp/play/audio-effect-file#api_irtcengine_preloadeffect) 将音效文件加载至内存后,如需释放该音效文件,请调用该方法。 ### 调用时机 [#调用时机-7] 该方法在加入频道前后均可调用。 ### 调用限制 [#调用限制-7] 无。 ### 参数 [#参数-12] 指定音效文件的 ID。每个音效文件均有唯一的 ID。 ### 返回值 [#返回值-17] - 0: 方法调用成功。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-17] - [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) ## onAudioEffectFinished [#onaudioeffectfinished] 本地音效文件播放已结束回调。 ```cpp virtual void onAudioEffectFinished(int soundId) { } ``` ### 详情 [#详情-5] 当播放音效结束后,会触发该回调。 ### 参数 [#参数-13] 指定音效的 ID。每个音效均有唯一的 ID。 ### 所属接口类 [#所属接口类-18] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengineeventhandler)