功能描述

在通话或直播过程中，除了用户自己说话的声音，有时候需要播放自定义的声音或者音乐文件并且让频道内的其他人也听到，比如需要给游戏添加音效，或者需要播放背景音乐等，Agora 提供以下两组方法可以满足播放音效和音乐文件的需求。

开始前请确保已在你的项目中实现基本的实时音视频功能。 详见开始音视频通话或开始互动直播。

示例项目

我们在 GitHub 上提供已实现播放混音和音效文件功能的开源示例项目 PlayAudioFiles。你可以下载体验并参考源代码。

播放音效文件

音效通常指持续很短的音频。播放音效文件方法主要用来播放短小的氛围音，比如鼓掌、游戏子弹撞击声音等，可以多个音效叠加播放，且音效文件可以预加载以提高性能。
Agora SDK 提供 IAudioEffectManager 类统一管理音效，包含一些管理音效的常用方法。 音效由音频文件路径指定，但在 IAudioEffectManager 内部使用 sound id 来识别和处理音效。音效文件通常保存在 assets 文件夹下；SDK 并不强制如何定义 sound id，保证每个音效有唯一的识别即可。一般的做法有自增 id，使用音效文件名的 hashCode 等。

实现方法

参考如下步骤，在你的项目中实现播放音效文件：

1. 在加入频道前调用 getAudioEffectManager 方法获取音效管理类 IAudioEffectManager。
2. 调用 preloadEffect 方法预加载音效文件，可以多次调用该方法加载多个音效文件。
3. 加入频道后调用 playEffect 方法播放音效文件，可以多次调用该方法同时播放多个音效。我们建议最多同时播放三个音效文件。

下图展示与播放音效相关的 API 时序，在开始播放音效后你还可以调用其他音效相关的方法实现更多功能，包括暂停播放音效、设置音效音量、释放预加载的音效等。

示例代码

// 首先获取全局的音效管理类
IAudioEffectManager manager = rtcEngine.getAudioEffectManager();

// 预加载音效（推荐），需注意音效文件的大小，并在加入频道前完成加载
// 仅支持 mp3，aac，m4a，3gp，wav格式
// 开发者可能需要额外记录 id 与文件路径的关联关系，用来播放和停止音效
int id = 0;
manager.preloadEffect(id++, "path/to/effect1");

// 可以加载多个音效
manager.preloadEffect(id++, "path/to/effect2");

// 播放一个音效
manager.playEffect(
0,                         // 要播放的音效 id 
"path/to/effect1",         // 播放文件的路径
-1,                        // 播放次数，-1 代表无限循环
0.0,                       // 改变音效的空间位置，0表示正前方
100,                       // 音量，取值 0 ~ 100， 100 代表原始音量
true                       // 是否令远端也能听到音效的声音
 );

// 暂停所有音效播放
manager.pauseAllEffects();

// 获取音效的音量，范围为 [0,100]
double volume = manager.getEffectsVolume();

// 保证音效音量在原始音量的 80% 以上
volume = volume < 80 ? 80 : volume;
manager.setEffectsVolume(volume);

// 继续播放暂停的音效
manager.resumeAllEffects();

// 停止所有音效
manager.stopAllEffects();

// 释放预加载的音效
manager.unloadAllEffects();

API 参考

• getAudioEffectManager

开发注意事项

• 预加载不是一个必须的步骤，一般来说为了提高性能或者需要反复播放某个特定的音效的时候，我们建议使用预加载。但如果音效文件比较大，不建议预加载。
• 以上方法都有返回值，返回值小于 0 表示方法调用失败。

音乐混音

混音是指播放本地或者在线音乐文件，同时让频道内的其他人听到此音乐。混音方法主要用来播放比较长的背景音，比如直播的时候播放的音乐，同时只可以有一个文件播放。如果在混音播放第一个文件的过程中播放第二个文件，会自动停止第一个文件的播放。

Agora 混音功能支持如下设置：

• 混音或替换： 混音指的是音乐文件的音频流跟麦克风采集的音频流进行混音（叠加）并编码发送给对方；替换指的是麦克风采集的音频被音乐文件的音频流替换掉，对方只能听见音乐播放。
• 循环：可以设置是否循环播放混音文件，以及循环次数。
• 调节音量：可以同时或分别调节音乐文件在本地和远端的播放音量。
• 调节音调：可以分别调节本地人声的音调和音乐文件的音调。

实现方法

// 混音设置
int loopCount = -1; //无限循环播放混音文件；设置为正整数表示混音文件播放的次数
boolean loopback = false; ////文件音频流是否发送给对端；如果设置为 true，文件音频流仅在本地可以听见，不会发送到对端
boolean cycle = false; //不替换麦克风采集的音频

// 开始播放混音
rtcEngine.startAudioMixing("path/to/music", loopback, replace, cycle);

// 将本地和远端音乐文件播放音量调节为 50
int volume = 50;
rtcEngine.adjustAudioMixingVolume(volume);

// 将本地人声的音调设为 1.5
double pitch = 1.5;
rtcEngine.setLocalVoicePitch(pitch);

// 将本地音乐文件的音调升 10 个半音。
int pitch = 10;
rtcEngine.setAudioMixingPitch(pitch);

// 获取当前播放的混音音乐的时长
int duration = rtcEngine.getAudioMixingDuration();
// duration 可以用来设置播放进度条的最大进度等
// seekBar.setMax(duration);

// 获取当前混音的播放进度
int currentPosition = rtcEngine.getAudioMixingCurrentPosition();
// 可以设置 timer 定时获取播放进度，用来显示播放进度
// seekBar.setProgress(currentPosition);

// 若用户拖动了进度条，可以在 seekBar 的回调中获取 progress 并重设音乐当前播放的位置
rtcEngine.setAudioMixingPosition(progress);

// 暂停、恢复混音文件播放
rtcEngine.pauseAudioMixing();
rtcEngine.resumeAudioMixing();

// 停止播放混音文件，麦克风采集播放恢复
rtcEngine.stopAudioMixing()；

你也可以通过 adjustAudioMixingPlayoutVolume 方法和 adjustAudioMixingPublishVolume 方法分别调节本地用户和远端用户听到的混音音量。其中 volume 的取值范围为 [0, 100]。

// 将远端用户听到的音乐文件音量设置为 50
rtcEngine.adjustAudioMixingPublishVolume(50)

// 将本地用户听到的音乐文件音量设置为 50
rtcEngine.adjustAudioMixingPlayoutVolume(50)

API 参考

• startAudioMixing
• stopAudioMixing
• adjustAudioMixingVolume
• adjustAudioMixingPublishVolume
• adjustAudioMixingPlayoutVolume
• setLocalVoicePitch
• setAudioMixingPitch
• pauseAudioMixing
• resumeAudioMixing
• getAudioMixingDuration
• getAudioMixingCurrentPosition
• setAudioMixingPosition

开发注意事项

• 混音要求安卓系统版本 4.2 以上、API Level 至少为 16。
• 在频道内调用混音方法，否则会有潜在问题。
• 若运行在模拟器中，混音只能播放位于 /sdcard/ 下的 mp3 文件。
• 以上方法都有返回值。返回值小于 0 表示方法调用失败。

相关链接

当播放音乐文件时，你还可以参考如下文档：

• 为什么 Android 10 无法使用 startAudioMixing 播放背景音乐？