功能描述
在通话或直播过程中,有时候需要播放自定义的音频文件并让频道内的其他人也听到,比如需要给游戏增加音效,或者播放背景音乐等。SDK 提供音效管理器,通过 IAudioEffectManager 统一管理音效,支持音效播放(可以多音效重叠播放)、播放控制(如暂停播放、音量调节、设置播放进度)、预加载音效等功能。
前提条件
在使用音效管理器前,请确保已在项目中实现基本的实时音视频功能。
支持格式
支持 mp3,aac,m4a,3gp,wav 格式
播放音效
使用步骤
- 在加入频道前调用 getAudioEffectManager 方法获取音效管理类 IAudioEffectManager。
- 调用 preloadEffect 方法预加载音效文件,可以多次调用该方法加载多个音效文件。
- 加入频道后调用 playEffect 方法播放音效文件,可以多次调用该方法同时播放多个音效。我们建议最多同时播放的音效文件不超过三个。
管理音效的方法需通过 IAudioEffectManager 接口类调用。
下图展示与播放音效相关的 API 时序,在开始播放音效后你还可以调用 IAudioEffectManager 的其他方法,比如暂停播放音效、设置音效音量、释放预加载的音效等。
示例代码
// 获取音效管理类
IAudioEffectManager manager = rtcEngine.getAudioEffectManager();
// 预加载音效,需注意音效文件的大小,并在加入频道前完成加载
// 开发者可能需要额外记录 id 与文件路径的关联关系,用来播放和停止音效
manager.preloadEffect(1, "path/effect1");
// 播放
manager.playEffect(
1, // 要播放的音效 id
"path/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 参考
开发注意事项
- 预加载不是一个必须的步骤,一般来说为了提高性能或者需要反复播放某个特定的音效的时候,我们建议使用预加载。
- 如果音效文件比较大,不建议预加载。
- 以上方法都有返回值,返回值小于 0 表示方法调用失败。
音乐混音
-
混音是指播放本地或者在线音乐文件,同时让频道内的其他人听到此音乐。
-
混音方法主要用来播放比较长的背景音,比如直播的时候播放的音乐,同时只可以有一个文件播放。如果在混音播放第一个文件的过程中播放第二个文件,会自动停止第一个文件的播放。
混音功能支持如下设置:
-
混音或替换: 混音指的是音乐文件的音频流跟麦克风采集的音频流进行混音(叠加)并编码发送给对方;替换指的是麦克风采集的音频被音乐文件的音频流替换掉,对方只能听见音乐播放。
-
循环:可以设置是否循环播放混音文件,以及循环次数。
-
调节音量:可以同时或分别调节音乐文件在本地和远端的播放音量。
-
调节音调:可以分别调节本地人声的音调和音乐文件的音调。
使用步骤
// 混音设置
int loopCount = -1; //无限循环播放混音文件;设置为正整数则表示混音文件播放的次数
boolean loopback = false; ////文件音频流是否发送给对端;如果设置为 true,音频流仅在本地可以听见,不会发送到对端
boolean cycle = false; //不替换麦克风采集的音频
// 开始播放混音
rtcEngine.startAudioMixing("path/music", loopback, replace, cycle);
// 将本地和远端音乐文件播放音量调节为原始音量的 你70%
int volume = 70;
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();
API 参考
- startAudioMixing
- stopAudioMixing
- adjustAudioMixingVolume
- pauseAudioMixing
- resumeAudioMixing
- getAudioMixingDuration
- getAudioMixingCurrentPosition
- setAudioMixingPosition
开发注意事项
- 混音要求安卓系统版本 4.4 以上、API Level 至少为 19。
- 请在频道内调用混音方法,否则会有潜在问题。
- 以上方法返回值小于 0 表示方法调用失败。