2024/10/17 14:17:33
播放音效或音乐文件
在游戏或 K 歌等实时音视频场景中，为烘托气氛、增添趣味性，用户通常需要播放音效或音乐文件。
本文介绍如何在你的项目中实现播放音效或音乐文件功能。
技术原理
声网提供了以下 API， 帮助你实现播放音效或音乐文件：
- 音效 API：播放持续时间短的氛围音，例如掌声、欢呼声、打斗声、枪击声等，通常可以同时播放多个音效文件。
- 音乐 API：播放比较长的音乐文件，例如，在唱歌时播放伴奏，在聊天时播放背景音乐。同一时间，只能播放一个音乐文件。
注意
如果使用 startAudioMixing 等音乐 API 播放时长较短的音效文件、或使用 playEffect 等音效 API 播放时长较长的音乐文件可能会播放失败。
这些方法主要包括如下功能：
| 功能 | 音效 API | 音乐 API |
|---|---|---|
| 播放或停止播放特定的音频文件 |
|
|
| 暂停或恢复播放音频文件 |
|
|
| 获取和调整音频文件的播放位置和音量 |
|
|
| 报告音频文件的播放状态 | onAudioEffectFinished | onAudioMixingStateChanged |
前提条件
在进行操作之前，请确保你已满足以下条件：
- 项目已经实现了基本的实时音视频功能。
- 了解目标开发平台支持的媒体格式：
- Windows：Media Foundation 中支持的媒体格式
- macOS：Best Practices for Audio
实现方法
本节介绍如何调用音效 API 和音乐混音 API，在你的项目中播放音效和音乐混音文件。
播放音效
加入频道后，调用 playEffect 方法播放指定音效文件。多次调用 playEffect，设置多个音效 ID，同时播放多个音效文件。音效播放结束后，SDK 触发 onAudioEffectFinished 回调。
在你的声网项目中，打开管理音效播放的文件并添加如下代码：
TypeScript
// 注册音效播放完成回调
const EventHandles = {
onAudioEffectFinished: (soundId) => {
console.log(`soundId:${soundId}`);
}
}
rtcEngine.registerEventHandler(EventHandles);
// 播放音效文件
rtcEngine.playEffect(
soundId: 0, // 设置音效 ID
filePath: 'your file path', // 设置音效文件路径
loopCount: 1, // 设置音效循环播放的次数。1 表示循环一次
pitch: 1.0, // 设置音效的音调。1.0 表示原始音调
pan: 0, // 设置音效的空间位置。0.0 表示音效出现在正前方
gain: 100, // 设置音效音量。100 表示原始音量
publish: false, // 设置是否将音效发布至远端
startPos: 0, // 设置音效文件的播放位置。0 表示从音效文件的第 0 ms 开始播放
);
播放音乐文件
调用 startAudioMixing 方法播放音乐文件。成功调用该方法后，音乐混音状态发生变化时，SDK 触发 onAudioMixingStateChanged 回调，报告改变后的音乐文件播放状态以及改变的原因。
在你的声网项目中，打开管理音效播放的文件夹添加以下代码：
TypeScript
// 注册音乐文件的播放状态已改变回调
const EventHandles = {
onAudioMixingStateChanged: (state, reason) => {
console.log(`state:${state}, reason:${reason}`);
}
}
rtcEngine.registerEventHandler(EventHandles);
// 播放音乐文件
rtcEngine.startAudioMixing(
filePath: 'your file path', // 设置音乐文件路径
loopback: false, // 设置是否只在本地播放音乐文件。false 表示将本地播放的音乐文件发布至远端，本地用户和远端用户都能听到音乐
cycle: -1, // 设置音乐文件的播放次数。-1 表示无限循环播放
startPos: 0, // 设置音乐文件的播放位置。0 表示从音效文件的第 0 ms 开始播放
);
参考信息
示例项目
声网提供了开源的播放音效或音乐文件示例项目供你参考，你可以前往下载或查看其中的源代码。
