音效与伴音
更新时间: 2024/09/18 16:26:13
在音视频通话或直播场景中,默认情况下只有房间成员本人说话的人声。出于烘托气氛、营造多样化语音环境的需求,NERTC SDK 支持通过混音功能播放多个掌声、口哨等短时音效,或者为人声添加背景音乐、伴奏音乐或其他场景效果,并将合成后的声音播放给房间内其他成员。
功能概述
混音,指 SDK 从 App 获取一路音频数据,将 App 提供的音频数据与 SDK 采集的音频数据整合为一路音频数据,通常用于音乐直播、在线KTV、连麦PK、游戏直播等场景。
NERTC SDK 提供混音相关方法,实现播放短时音效和背景音乐的功能。
-
播放短时音效:
指通话或直播中播放短时音频文件,一般用于渲染房间气氛,例如游戏音效、掌声、口哨、欢呼声、笑声的短时音效。支持多个音效叠加播放。
-
播放背景音乐:
伴音功能支持在房间中播放本地或者在线音乐文件,作为通话或直播时的背景声音,同时让房间内的其他人听到此音乐。NERTC 播放伴音方法可以用来播放比较长的背景音,例如伴奏音乐、环境白噪声、背景音乐等等。
NERTC 支持在麦克风关闭的状态下,发送伴音。在娱乐社交、在线教育等场景中,即使用户不想要开启麦克风进行语音聊天,也能在房间内播放背景音乐。
NERTC SDK 混音功能支持如下设置:
-
混音:支持将音乐文件的音频流跟麦克风采集的音频流(主流)进行叠加并编码发送给对方,同时伴音功能支持通过辅流通道传输音乐文件的音频流。
-
循环:可以设置是否循环播放混音文件,以及循环次数。
-
音量控制:可以各自控制本地播放以及编码发送的混音音量。
-
音调控制:可以按半音音阶调整本地播放的音乐文件的音调。例如在 K 歌场景中,为了使歌曲更适合主播的声线音域,主播可以调整伴音的音调,升高或降低伴奏的音阶。
-
定位:混音任务支持从背景音乐文件的任意位置开始播放。
-
叠加:可以同时播放多个短时音效文件。
注意事项
-
伴音相关方法的返回值若小于 0,表示方法调用失败。
-
加入房间前或加入房间后,均可启动音效和伴音。
-
本地混音文件支持 MP3、M4A、AAC、3GP、WMA、WAV 格式,支持本地 SD 卡文件和在线 URL。
-
可通过
onAudioMixingStateChanged
回调接收音乐文件播放状态改变的相关信息,如果播放出错,可通过对应错误码排查故障。
配置音效
配置步骤
- 调用
playEffect
方法播放指定effectId
的音效文件。调用此方法时,您需要设置option
参数指定播放的音效文件。相关参数的含义如下表。
参数 | 参数说明 |
---|---|
path | 指定音效文件的路径,例如 D:\\audio_files\\test.mp3 。支持本地绝对路径或 URL 地址。 |
effectId | 指定音效文件的 ID。 |
loopCount | 指定音效文件循环播放的次数。该参数为正整数,可取最大值为 10000,默认值为 1,即默认仅播放一次。若该值小于等于 0,则默认为无限循环播放。 |
sendEnabled | 是否将音效发送至远端。该参数的默认值为 YES,即远端用户可以听到该音效。 |
sendVolume | 音效文件的发送音量。该参数的取值范围为 0 ~ 200,默认值为 100,表示使用文件的原始音量。 |
playbackEnabled | 是否本地播放该音效。默认为 YES,即本地用户可以听到该音效。 |
playbackVolume | 音效文件的播放音量。该参数的取值范围为 0 ~ 200,默认值为 100,表示使用文件的原始音量。 |
-
您可以多次调用此方法以同时播放多个音效文件,实现音效的叠加。
-
在调用此方法成功播放指定音效文件后,若您反复停止再重新播放该 effectId 对应的音效文件,首次播放时设置的 option 无效,会恢复为默认值。
-
音效播放任务管理。开始播放音效后,您还可以通过其他方法实现音效播放任务管理等更多功能,例如:
-
进度管理:调用
pauseAllEffects
方法暂停播放所有音效、调用resumeAllEffects
方法恢复播放所有音效、调用setEffectPosition
方法设置音效文件的播放位置等,此外也可以通过注册onAudioEffectTimestampUpdate
回调以监听音效文件的实时播放进度。 -
音量管理:调用
setEffectSendVolume
方法设置音效文件发送音量、调用setEffectPlaybackVolume
方法设置音效文件播放音量。 -
音调管理:调用
setEffectPitch
方法并通过pitch
参数设置音效文件的音调。- 仅开始播放音效文件后可调用此方法;播放结束后,音调将恢复为默认值。
- 音调
pitch
参数的取值范围为 [-12,12],默认值为 0,每相邻两个值的音调高度相差半音;取值的绝对值越大,音调升高或降低得越多。 - 若 SDK 返回 30003,表示参数设置错误;若 SDK 返回 30005,表示引擎尚未初始化或未找到当前音效文件。
-
获取音效相关信息:调用
getEffectSendVolume
方法获取音效文件发送音量、调用getEffectPitch
方法获取音效文件的音调、调用getEffectCurrentPosition
方法获取音效文件当前播放进度等。
-
-
在离开房间前,调用
stopAllEffects
方法结束播放所有音效。
示例项目源码
网易云信提供音效示例项目源码,您可以参考该源码配置音效。
示例代码
// 调用 playEffect 播放指定的音效文件
int audioEffectId = 1;
NERtcCreateAudioEffectOption option = new NERtcCreateAudioEffectOption();
option.path = "audioEffectPath";
option.playbackEnabled = true;
option.playbackVolume = 100;
option.sendEnabled = true;
option.sendVolume = 100;
option.loopCount = 1;
int ret = NERtcEx.getInstance().playEffect(mAudioEffectId, option);
// 调用 stopEffect 结束播放音效文件
NERtcEx.getInstance().stopEffect(audioEffectId);
// 调用 pauseEffect 暂停播放音效文件
NERtcEx.getInstance().pauseEffect(audioEffectId);
// 调用 resumeEffect 恢复播放音效文件
NERtcEx.getInstance().resumeEffect(audioEffectId);
// 调用 pauseAllEffects 暂停所有音效播放
NERtcEx.getInstance().pauseAllEffects();
// 调用 resumeAllEffects 恢复所有音效播放
NERtcEx.getInstance().resumeAllEffects();
// 调用 setEffectSendVolume 设置音效文件发送音量
NERtcEx.getInstance().setEffectSendVolume(audioEffectId, 50);
// 调用 getEffectSendVolume 获取音效文件发送音量
int volume = NERtcEx.getInstance().getEffectSendVolume(audioEffectId);
// 调用 setEffectPlaybackVolume 设置音效文件播放音量
NERtcEx.getInstance().setEffectPlaybackVolume(audioEffectId, 50);
// 调用 getEffectPlaybackVolume 设置音效文件播放音量
int volume = NERtcEx.getInstance().getEffectPlaybackVolume(audioEffectId);
// 调用 setEffectPitch 设置音效文件的音调
NERtcEx.getInstance().setEffectPitch(audioEffectId, 6);
// 调用 getEffectPitch 获取音效文件的音调
int pitch = NERtcEx.getInstance().getEffectPitch(audioEffectId);
// 调用 setEffectPosition 设置音效文件的播放位置
NERtcEx.getInstance().setEffectPosition(mAudioEffectId1, 1000);
// 调用 getEffectCurrentPosition 获取音效文件当前播放进度
long position = NERtcEx.getInstance().getEffectCurrentPosition(effectId);
// 调用 stopAllEffects 结束音效播放
NERtcEx.getInstance().stopAllEffects();
API 参考
方法 | 功能描述 |
---|---|
playEffect |
播放指定音效文件 |
pauseEffect |
暂停播放指定音效文件 |
pauseAllEffects |
暂停播放所有音效文件 |
resumeEffect |
恢复播放指定音效文件 |
resumeAllEffects |
恢复播放所有音效文件 |
setEffectSendVolume |
设置音效文件发送音量 |
getEffectSendVolume |
获取音效文件发送音量 |
setEffectPlaybackVolume |
设置音效文件播放音量 |
getEffectPlaybackVolume |
获取音效文件播放音量 |
setEffectPitch |
设置音效文件的音调 |
getEffectPitch |
获取音效文件的音调 |
setEffectPosition |
设置音效文件的播放位置 |
getEffectsDuration |
获取音效文件时长 |
getEffectCurrentPosition |
获取音效的播放进度 |
stopEffect |
停止播放指定音效文件 |
stopAllEffects |
停止播放所有音效文件 |
事件 | 事件描述 |
---|---|
onAudioEffectFinished |
本地音效文件播放已结束回调 |
onAudioEffectTimestampUpdate |
本地音效文件播放进度回调 |
配置伴音
配置步骤
-
通过
NERtcCreateAudioMixingOption
设置伴音参数,例如伴音文件路径、是否本地播放、是否通过辅流通道传输等等,并调用startAudioMixing
开始伴音。若您选择通过辅流通道传输伴音音频流,请先调用
enableLocalSubStreamAudio
方法开启音频辅流。 -
伴音任务管理。开始伴音后,还可以通过其他方法实现伴音任务管理等更多功能,例如:
-
进度管理: 通过
pauseAudioMixing
和resumeAudioMixing
暂停或恢复伴音、通过setAudioMixingPosition
设置伴音文件的播放进度。 -
音量管理:通过
setAudioMixingPlaybackVolume
和setAudioMixingSendVolume
等方法设置伴音的播放音量、伴音的发送音量。 -
音调管理:调用
setAudioMixingPitch
方法并通过pitch
参数设置伴音文件的音调。- 仅开始伴音后可调用此方法;伴音结束后,音调将恢复为默认值。
- 音调
pitch
参数的取值范围为 [-12,12],默认值为 0,每相邻两个值的音调高度相差半音;取值的绝对值越大,音调升高或降低得越多。 - 若 SDK 返回 30003,表示参数设置错误;若 SDK 返回 30005,表示引擎尚未初始化或未找到当前伴音文件。
-
获取伴音相关信息:例如通过
getAudioMixingCurrentPosition
等接口获取伴音文件的播放进度、调用getAudioMixingPitch
方法获取伴音文件的音调等。
-
-
在离开房间前调用
stopAudioMixing
结束伴音。
示例项目源码
网易云信提供伴音示例项目源码,您可以参考该源码配置伴音。
示例代码
// 首先设置伴音参数
NERtcCreateAudioMixingOption option = new NERtcCreateAudioMixingOption();
option.path = "/sdcard/test.mp3"; //伴音文件路径
option.playbackEnabled = true; //是否本地播放
option.playbackVolume = 100; //本地播放音量
option.sendEnabled = true; //是否编码发送
option.sendVolume = 100; //发送音量
option.loopCount = 1; //循环次数
option.startTimeStamp = 0; //音乐文件开始播放的时间,UTC 时间戳
option.sendWithAudioType = NERtcAudioStreamType.kNERtcAudioStreamTypeMain; //伴音跟随音频主流还是辅流,默认跟随主流
int ret = NERtcEx.getInstance().startAudioMixing(option);; //开始伴音任务
if(ret == NERtcConstants.ErrorCode.OK) {
//创建伴音任务成功
}else {
//创建伴音任务失败
}
// 暂停、恢复伴音任务
NERtcEx.getInstance().pauseAudioMixing();
NERtcEx.getInstance().resumeAudioMixing();
// 获取和设置本地播放伴音的音量,范围为 0 ~ 100
int volume = NERtcEx.getInstance().getAudioMixingPlaybackVolume();
NERtcEx.getInstance().setAudioMixingPlaybackVolume(volume);
// 获取和设置编码发送伴音的音量,范围为 0 ~ 100
int volume = NERtcEx.getInstance().getAudioMixingSendVolume();
NERtcEx.getInstance().setAudioMixingSendVolume(volume);
// 获取和设置本地播放伴音的音调,范围为 -12 ~ 12
int pitch = NERtcEx.getInstance().getAudioMixingPitch();
NERtcEx.getInstance().setAudioMixingPitch(pitch);
// 获取伴音文件总时长
long time = NERtcEx.getInstance().getAudioMixingDuration();
// 获取当前伴音文件播放位置
long position = NERtcEx.getInstance().getAudioMixingCurrentPosition();
// 设置伴音文件播放位置
NERtcEx.getInstance().seekAudioMixingPosition(position);
// 结束伴音任务
NERtcEx.getInstance().stopAudioMixing();
API参考
方法 | 功能描述 |
---|---|
startAudioMixing |
开始伴音 |
enableLocalSubStreamAudio |
开启音频辅流 |
stopAudioMixing |
结束伴音 |
pauseAudioMixing |
暂停伴音 |
resumeAudioMixing |
恢复伴音 |
setAudioMixingPlaybackVolume |
设置伴音文件的播放音量 |
setAudioMixingSendVolume |
设置伴音文件的发送音量 |
getAudioMixingPlaybackVolume |
获取伴音文件的播放音量 |
getAudioMixingSendVolume |
获取伴音文件的发送音量 |
getAudioMixingDuration |
获取伴音的总长度 |
setAudioMixingPosition |
设置伴音文件的播放进度 |
getAudioMixingCurrentPosition |
获取伴音文件的当前播放进度 |
getAudioMixingPitch |
获取伴音文件的音调 |
setAudioMixingPitch |
设置伴音文件的音调 |
事件 | 事件描述 |
---|---|
onAudioMixingStateChanged |
本地用户的伴音文件播放状态改变回调 |
onAudioMixingTimestampUpdate |
伴音文件播放进度回调 |