播放音效或音乐文件
在游戏、K 歌和互动直播等场景中，你可以使用 RTC SDK 播放音效或音乐文件，并将声音发布给频道内的远端用户。
本文介绍如何在 HarmonyOS 项目中预加载、播放、暂停、恢复、停止和调节音效或音乐文件。
技术原理
- 音效适合播放掌声、欢呼声等较短的声音。你可以为不同音效分配不同的
soundId，同时播放多个音效。 - 音乐适合播放伴奏或背景音乐。同一时间只能播放一个音乐文件。
音效和音乐使用不同的 API。不要使用音乐混音 API 播放短音效，也不要使用音效 API 播放较长的音乐文件。
前提条件
在进行操作之前，请确保你的项目已经实现基本的实时音视频功能，详见实现音视频互动。
播放音效
预加载和播放
为需要重复播放的本地音效分配唯一的 soundId，然后调用 preloadEffect 将文件加载到内存。音效文件较大或只播放一次时，可以直接调用 playEffect。
使用 await 调用 preloadEffect 和 playEffect 时，包含这些调用的函数必须声明为 async，否则会出现语法错误。
async playAudioEffect(): Promise<void> {
// 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 个。
暂停、恢复和停止
// 暂停和恢复指定音效
this.rtcEngine?.pauseEffect(soundId);
this.rtcEngine?.resumeEffect(soundId);
// 停止指定音效，或停止全部音效
this.rtcEngine?.stopEffect(soundId);
this.rtcEngine?.stopAllEffects();
音效播放完成时，SDK 会触发 onAudioEffectFinished 回调：
config.mEventHandler.onAudioEffectFinished = (finishedSoundId: number) => {
Logger.info(TAG, `audio effect finished: ${finishedSoundId}`);
};
调节音效音量和释放资源
// 调节全部音效的音量，取值范围为 [0, 100]
this.rtcEngine?.setEffectsVolume(50);
// 只调节指定音效的音量，取值范围为 [0, 100]
this.rtcEngine?.setVolumeOfEffect(soundId, 50);
// 不再使用预加载的音效时释放内存
this.rtcEngine?.unloadEffect(soundId);
播放音乐
调用 startAudioMixing 播放音乐文件。loopback 设置为 false 时，本地用户和远端用户都可以听到音乐；设置为 true 时，只在本地播放。
const musicPath = "your-music-file-path";
// 播放音乐，-1 表示循环播放，0 表示从文件开头播放。
this.rtcEngine?.startAudioMixing(musicPath, false, -1, 0);
音乐状态变化时，SDK 会触发 onAudioMixingStateChanged 回调。你可以在收到回调后继续执行暂停、恢复或音量控制：
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 状态后再执行依赖音乐文件已经打开的控制操作。