播放音效或音乐文件

  • HarmonyOS

更新时间

了解实时互动 RTC 在不同平台上的播放音效或音乐文件方式,包括接入流程、关键配置和平台差异。

在游戏、K 歌和互动直播等场景中,你可以使用 RTC SDK 播放音效或音乐文件,并将声音发布给频道内的远端用户。

本文介绍如何在 HarmonyOS 项目中预加载、播放、暂停、恢复、停止和调节音效或音乐文件。

技术原理

  • 音效适合播放掌声、欢呼声等较短的声音。你可以为不同音效分配不同的 soundId,同时播放多个音效。
  • 音乐适合播放伴奏或背景音乐。同一时间只能播放一个音乐文件。

音效和音乐使用不同的 API。不要使用音乐混音 API 播放短音效,也不要使用音效 API 播放较长的音乐文件。

前提条件

在进行操作之前,请确保你的项目已经实现基本的实时音视频功能,详见实现音视频互动。

播放音效

预加载和播放

为需要重复播放的本地音效分配唯一的 soundId,然后调用 preloadEffect 将文件加载到内存。音效文件较大或只播放一次时,可以直接调用 playEffect。

使用 await 调用 preloadEffect 和 playEffect 时,包含这些调用的函数必须声明为 async,否则会出现语法错误。

TypeScript
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 个。

暂停、恢复和停止

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);

播放音乐

调用 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 状态后再执行依赖音乐文件已经打开的控制操作。

参考信息

API 参考