在通话或直播过程中,除了用户自己说话的声音,有时候需要播放自定义的声音或者音乐文件并且让频道内的其他人也听到,比如需要给游戏添加音效,或者需要播放背景音乐等,Agora 提供以下两组方法可以满足播放音效和音乐文件的需求。
开始前请确保已在你的项目中实现基本的实时音视频功能。 详见开始音视频通话或开始互动直播。
我们在 GitHub 上提供已实现播放混音和音效文件功能的开源示例项目 PlayAudioFiles。你可以下载体验并参考源代码。
音效通常指持续很短的音频。播放音效文件方法主要用来播放短小的氛围音,比如鼓掌、游戏子弹撞击声音等,可以多个音效叠加播放,且音效文件可以预加载以提高性能。
Agora SDK 提供 IAudioEffectManager
类统一管理音效,包含一些管理音效的常用方法。 音效由音频文件路径指定,但在 IAudioEffectManager
内部使用 sound id 来识别和处理音效。音效文件通常保存在 assets 文件夹下;SDK 并不强制如何定义 sound id,保证每个音效有唯一的识别即可。一般的做法有自增 id,使用音效文件名的 hashCode 等。
参考如下步骤,在你的项目中实现播放音效文件:
getAudioEffectManager
方法获取音效管理类 IAudioEffectManager
。preloadEffect
方法预加载音效文件,可以多次调用该方法加载多个音效文件。playEffect
方法播放音效文件,可以多次调用该方法同时播放多个音效。我们建议最多同时播放三个音效文件。IAudioEffectManager
接口类调用。下图展示与播放音效相关的 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();
混音是指播放本地或者在线音乐文件,同时让频道内的其他人听到此音乐。混音方法主要用来播放比较长的背景音,比如直播的时候播放的音乐,同时只可以有一个文件播放。如果在混音播放第一个文件的过程中播放第二个文件,会自动停止第一个文件的播放。
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)
adjustAudioMixingPlayoutVolume
方法和 adjustAudioMixingPublishVolume
方法要在加入频道后调用。startAudioMixing
stopAudioMixing
adjustAudioMixingVolume
adjustAudioMixingPublishVolume
adjustAudioMixingPlayoutVolume
setLocalVoicePitch
setAudioMixingPitch
pauseAudioMixing
resumeAudioMixing
getAudioMixingDuration
getAudioMixingCurrentPosition
setAudioMixingPosition
当播放音乐文件时,你还可以参考如下文档: