伴音和音效
更新时间: 2024/09/09 14:07:53
NERoom SDK 支持通过混音功能播放掌声、口哨等短时音效,或者为人声添加背景音乐、伴奏音乐或其他场景效果,并将合成后的声音播放给房间内其他成员。在音视频通话或直播场景中,可以更好的烘托气氛、营造多样化语音环境。
功能概述
混音,指 SDK 从 App 获取一路音频数据,将 App 提供的音频数据与 SDK 采集的音频数据整合为一路音频数据,通常用于音乐直播、在线KTV、连麦PK、游戏直播等场景。
NERoom SDK 提供混音相关方法,实现播放短时音效和背景音乐的功能。
-
播放短时音效:
指通话或直播中播放短时音频文件,一般用于渲染房间气氛,例如游戏音效、掌声、口哨、欢呼声、笑声的短时音效。支持多个音效叠加播放。
-
播放背景音乐:
伴音功能支持在房间中播放本地或者在线音乐文件,作为通话或直播时的背景声音,同时让房间内的其他人听到此音乐。NERTC 播放伴音方法可以用来播放比较长的背景音,例如伴奏音乐、环境白噪声、背景音乐等等。
NERoom SDK 混音功能支持如下设置:
-
混音:混音指的是音乐文件的音频流跟麦克风采集的音频流进行混音(叠加)并编码发送给对方。
-
循环:可以设置是否循环播放混音文件,以及循环次数。
-
音量控制:可以各自控制本地播放以及编码发送的混音音量。
-
定位:混音任务支持从背景音乐文件的任意位置开始播放。
-
叠加:可以同时播放多个短时音效文件。
注意事项
-
伴音相关方法的返回值若小于 0,表示方法调用失败。
-
请在加入房间成功后再启动混音任务。
-
本地混音文件支持 MP3、M4A、AAC、3GP、WMA、WAV 格式,支持在线 URL。
配置音效
配置步骤
-
调用
playEffect
方法播放指定 effectId 的音效文件。调用此方法时,您需要设置
effectId
指定音效文件的 ID;设置option
参数指定播放的音效文件。option
参数的含义如下表所示。参数 类型 描述 path string 待播放的音效文件路径,支持 URL 地址 loopCount number 音效循环播放的次数。 - 1:(默认)播放一次。
- ≤ 0:无限循环播放音效,直至调用 stopEffect 或 stopAllEffects 后停止。
playbackVolume int 音乐文件的播放音量,取值范围为 0~100。默认为 100,表示使用文件的原始音量。
-
您可以多次调用此方法以同时播放多个音效文件,实现音效的叠加。
-
在调用此方法成功播放指定音效文件后,若您反复停止再重新播放该 effectId 对应的音效文件,首次播放时设置的 option 无效,会恢复为默认值。
-
(可选)暂停和恢复音效。
- 调用
pauseEffect
方法暂停指定音效。 - 调用
pauseAllEffects
方法暂停所有音效。 - 调用
resumeEffect
方法恢复播放指定音效。 - 调用
resumeAllEffects
方法恢复播放所有音效。
- 调用
-
在离开房间前,调用
stopAllEffects
方法停止播放所有音效文件。
示例代码
/**
* 获取房间上下文NERoomContext
* @param roomUuid 房间ID
*/
const NERoomContext = NERoomService.getRoomContext(roomUuid)
/**
* 播放音效
* @param effectId 指定音效的 ID。每个音效均应有唯一的 ID
* @param option 音效相关参数
*/
NERoomContext.rtcController.playEffect(123, {
path: ''
loopCount: 1
playbackVolume: 50
}).then(res => {
console.log(res, 'playEffect success')
}).catch(err => {
console.error(res, 'playEffect fail')
})
/**
* 停止播放音效
* @param effectId 指定音效的 ID。每个音效均应有唯一的 ID
*/
NERoomContext.rtcController.stopEffect(123).then(res => {
console.log(res, 'stopEffect success')
}).catch(err => {
console.error(res, 'stopEffect fail')
})
API 参考
方法 | 功能描述 |
---|---|
playEffect |
播放指定音效文件 |
stopEffect |
停止播放指定音效文件 |
stopAllEffects |
停止播放所有音效文件 |
pauseEffect |
暂停指定音效 |
pauseAllEffects |
暂停所有音效 |
resumeEffect |
恢复播放指定音效 |
resumeAllEffects |
恢复播放所有音效 |
配置伴音
配置步骤
-
加入房间成功后,通过
NERoomCreateAudioMixingOption
设置伴音参数,例如伴音文件路径、是否本地播放等等,并调用startAudioMixing
开始伴音。NERoomCreateAudioMixingOption
参数的含义如下表所示。参数 类型 描述 path string 待播放的音乐文件路径,支持 URL 地址。 loopback boolean 是否循环播放,默认为false, 如果设置为ture,此时可通过 loopCount 设置循环播放次数,loopCount 默认为 0,表示无限循环播放。 loopCount number 伴音循环播放的次数。 - 1:(默认)播放一次。
- ≤ 0:无限循环播放,直至调用 pauseAudioMixing 后暂停,或调用 stopAudioMixing 后停止。
audioMixingEnd Function 伴音播放完成回调 replace bool 是否要用音频文件替换本地音频流,默认为false playbackVolume number 音乐文件的播放音量,取值范围为 0~200。默认为 100,表示使用文件的原始音量。 playStartTime number 设置音频开始播放时间位置,单位为秒(s)。默认为 0,即从头开始播放。 -
设置伴音的音量。
- 通过
setAudioMixingPlaybackVolume
设置伴音的播放音量。
伴音播放音量建议不超过 25,否则伴音过程中语音沟通的体验会受到影响。
- 通过
-
在离开房间前调用
stopAudioMixing
结束伴音。
示例代码
/**
* 获取房间上下文NERoomContext
* @param roomUuid 房间ID
*/
const NERoomContext = NERoomService.getRoomContext(roomUuid)
/**
* 开始伴音
* @param option 音效相关参数
*/
NERoomContext.rtcController.startAudioMixing({
path: ''
loopCount: 1
audioMixingEnd: () => {console.log('audioMixingEnd')},
loopback: true,
}).then(res => {
console.log(res, 'startAudioMixing success')
}).catch(err => {
console.error(res, 'startAudioMixing fail')
})
/**
* 设置伴音的音量
* @param volume 伴音播放音量,取值范围为 0~100。默认 100,即原始文件音量。
*/
NERoomContext.rtcController.setAudioMixingPlaybackVolume(50).then(res => {
console.log(res, 'stopAudioMixing success')
}).catch(err => {
console.error(res, 'stopAudioMixing fail')
})
/**
* 停止伴音
*/
NERoomContext.rtcController.stopAudioMixing().then(res => {
console.log(res, 'stopAudioMixing success')
}).catch(err => {
console.error(res, 'stopAudioMixing fail')
})
API参考
方法 | 功能描述 |
---|---|
startAudioMixing | 开始伴音 |
stopAudioMixing | 结束伴音 |
setAudioMixingPlaybackVolume | 设置伴音播放音量 |
setAudioMixingSendVolume | 设置伴音的发送音量 |