# 播放音效或音乐文件 (/zh-CN/realtime-media/rtc/build/audio/audio-effect-mixing/harmonyos) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 在游戏、K 歌和互动直播等场景中,你可以使用 RTC SDK 播放音效或音乐文件,并将声音发布给频道内的远端用户。 本文介绍如何在 HarmonyOS 项目中预加载、播放、暂停、恢复、停止和调节音效或音乐文件。 ## 技术原理 [#技术原理-7] - **音效**适合播放掌声、欢呼声等较短的声音。你可以为不同音效分配不同的 `soundId`,同时播放多个音效。 - **音乐**适合播放伴奏或背景音乐。同一时间只能播放一个音乐文件。 音效和音乐使用不同的 API。不要使用音乐混音 API 播放短音效,也不要使用音效 API 播放较长的音乐文件。 ## 前提条件 [#前提条件-7] 在进行操作之前,请确保你的项目已经实现基本的实时音视频功能,详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。 ## 播放音效 [#播放音效-5] ### 预加载和播放 [#预加载和播放] 为需要重复播放的本地音效分配唯一的 `soundId`,然后调用 `preloadEffect` 将文件加载到内存。音效文件较大或只播放一次时,可以直接调用 `playEffect`。 使用 `await` 调用 `preloadEffect` 和 `playEffect` 时,包含这些调用的函数必须声明为 `async`,否则会出现语法错误。 ```typescript async playAudioEffect(): Promise { // filePath 可以替换为项目中可访问的音效文件路径 const soundId = 1; const filePath = "your-effect-file-path"; // 预加载音效。preloadEffect 返回 Promise。 await this.rtcEngine?.preloadEffect(soundId, filePath); // 播放音效:循环 0 次、原始音调、居中声道、原始音量,并发布给远端用户。 await this.rtcEngine?.playEffect(soundId, filePath, 0, 1.0, 0.0, 100, true, 0); } ``` `playEffect` 的 `loopCount` 设置为 `-1` 可以循环播放,直到调用 `stopEffect` 或 `stopAllEffects`。多次传入不同的 `soundId` 和文件路径,可以同时播放多个音效。为获得更好的体验,建议同时播放的音效不超过 3 个。 ### 暂停、恢复和停止 [#暂停恢复和停止] ```typescript // 暂停和恢复指定音效 this.rtcEngine?.pauseEffect(soundId); this.rtcEngine?.resumeEffect(soundId); // 停止指定音效,或停止全部音效 this.rtcEngine?.stopEffect(soundId); this.rtcEngine?.stopAllEffects(); ``` 音效播放完成时,SDK 会触发 `onAudioEffectFinished` 回调: ```typescript config.mEventHandler.onAudioEffectFinished = (finishedSoundId: number) => { Logger.info(TAG, `audio effect finished: ${finishedSoundId}`); }; ``` ### 调节音效音量和释放资源 [#调节音效音量和释放资源] ```typescript // 调节全部音效的音量,取值范围为 [0, 100] this.rtcEngine?.setEffectsVolume(50); // 只调节指定音效的音量,取值范围为 [0, 100] this.rtcEngine?.setVolumeOfEffect(soundId, 50); // 不再使用预加载的音效时释放内存 this.rtcEngine?.unloadEffect(soundId); ``` ## 播放音乐 [#播放音乐-5] 调用 `startAudioMixing` 播放音乐文件。`loopback` 设置为 `false` 时,本地用户和远端用户都可以听到音乐;设置为 `true` 时,只在本地播放。 ```typescript const musicPath = "your-music-file-path"; // 播放音乐,-1 表示循环播放,0 表示从文件开头播放。 this.rtcEngine?.startAudioMixing(musicPath, false, -1, 0); ``` 音乐状态变化时,SDK 会触发 `onAudioMixingStateChanged` 回调。你可以在收到回调后继续执行暂停、恢复或音量控制: ```typescript config.mEventHandler.onAudioMixingStateChanged = ( state: Constants.AudioMixingState, reason: Constants.AudioMixingReason ) => { Logger.info(TAG, `audio mixing state=${state}, reason=${reason}`); }; // 暂停、恢复或停止音乐 this.rtcEngine?.pauseAudioMixing(); this.rtcEngine?.resumeAudioMixing(); this.rtcEngine?.stopAudioMixing(); // 设置播放位置,单位为毫秒 this.rtcEngine?.setAudioMixingPosition(500); // 分别设置本地播放音量和远端发布音量,取值范围以 API 参考为准 this.rtcEngine?.adjustAudioMixingPlayoutVolume(50); this.rtcEngine?.adjustAudioMixingPublishVolume(50); ``` 如果本地文件不存在、格式不支持或 SDK 无法访问在线文件,SDK 会通过音乐状态回调报告打开失败。请在收到 `PLAYING` 状态后再执行依赖音乐文件已经打开的控制操作。 ## 参考信息 [#参考信息-8] ### API 参考 [#api-参考-8] - [`preloadEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_preloadeffect) - [`playEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_playeffect3) - [`pauseEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_pauseeffect) - [`resumeEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_resumeeffect) - [`stopAllEffects`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_stopalleffects) - [`setEffectsVolume`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_seteffectsvolume) - [`setVolumeOfEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_setvolumeofeffect) - [`unloadEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_unloadeffect) - [`startAudioMixing`](/zh-CN/api-reference/rtc/harmonyos/play/audio-mixing#api_irtcengine_startaudiomixing2) - [`pauseAudioMixing`](/zh-CN/api-reference/rtc/harmonyos/play/audio-mixing#api_irtcengine_pauseaudiomixing) - [`resumeAudioMixing`](/zh-CN/api-reference/rtc/harmonyos/play/audio-mixing#api_irtcengine_resumeaudiomixing) - [`stopAudioMixing`](/zh-CN/api-reference/rtc/harmonyos/play/audio-mixing#api_irtcengine_stopaudiomixing) - [`setAudioMixingPosition`](/zh-CN/api-reference/rtc/harmonyos/play/audio-mixing#api_irtcengine_setaudiomixingposition) - [`adjustAudioMixingPlayoutVolume`](/zh-CN/api-reference/rtc/harmonyos/play/audio-mixing#api_irtcengine_adjustaudiomixingplayoutvolume) - [`adjustAudioMixingPublishVolume`](/zh-CN/api-reference/rtc/harmonyos/play/audio-mixing#api_irtcengine_adjustaudiomixingpublishvolume)