在音视频通话或直播场景中，默认情况下只有房间成员本人说话的人声。出于烘托气氛、营造多样化语音环境的需求，NERTC SDK 支持通过混音功能播放多个掌声、口哨等短时音效，或者为人声添加背景音乐、伴奏音乐或其他场景效果，并将合成后的声音播放给房间内其他成员。

功能概述

混音，指 SDK 从 App 获取一路音频数据，将 App 提供的音频数据与 SDK 采集的音频数据整合为一路音频数据，通常用于音乐直播、在线KTV、连麦PK、游戏直播等场景。

NERTC SDK 提供混音相关方法，实现播放短时音效和背景音乐的功能。

• 播放短时音效：

  指通话或直播中播放短时音频文件，一般用于渲染房间气氛，例如游戏音效、掌声、口哨、欢呼声、笑声的短时音效。支持多个音效叠加播放。

• 播放背景音乐：

  伴音功能支持在房间中播放本地或者在线音乐文件，作为通话或直播时的背景声音，同时让房间内的其他人听到此音乐。NERTC 播放伴音方法可以用来播放比较长的背景音，例如伴奏音乐、环境白噪声、背景音乐等等。

NERTC SDK 混音功能支持如下设置：

• 混音：混音指的是音乐文件的音频流跟麦克风采集的音频流进行混音（叠加）并编码发送给对方。
• 循环：可以设置是否循环播放混音文件，以及循环次数。
• 音量控制：可以各自控制本地播放以及编码发送的混音音量。
• 定位：混音任务支持从背景音乐文件的任意位置开始播放。
• 叠加：可以同时播放多个短时音效文件。

注意事项

• Web 端 NERTC SDK 在 H5 平台不支持以下伴音相关 API：startAudioMixing、stopAudioMixing、pauseAudioMixing、resumeAudioMixing、adjustAudioMixingVolume、getAudioMixingDuration。如果您调用了这些 API，SDK 会报错 BROWSER_NOT_SUPPORT。
• 伴音相关方法的返回值若小于 0，表示方法调用失败。
• 请在加入房间成功后再启动混音任务。
• 本地混音文件支持 MP3、M4A、AAC、3GP、WMA、WAV 格式，支持在线 URL。

配置音效

配置步骤

1. （可选）在加入房间后调用 preloadEffect 方法，将待播放音效加载至内存，以供您后续快速播放该音效文件。调用此方法时，您需要设置 filePath 和 soundId 指定预加载的音效文件。两个参数的含义如下。

• filePath：指定在线音效文件的相对或绝对路径，即 URL 地址。支持MP3，AAC 以及浏览器支持的其他音频格式。
• soundId：指定音效文件的 ID。该参数为正整数，取值范围为 1 ~ 10000。

2. 调用 playEffect 方法播放指定 soundId 的音效文件。调用此方法时，您需要设置 filePath、soundID 等参数指定播放的音效文件。相关参数的含义如下。

• filePath：指定在线音效文件的相对或绝对路径，即 URL 地址。支持MP3，AAC 以及浏览器支持的其他音频格式。
• soundId：指定音效文件的 ID。该参数为正整数，取值范围为 1 ~ 10000。
• cycle：指定音效文件循环播放的次数。该参数为正整数，取值范围为 1 ~ 10000，默认值为1，即默认仅播放一次。

您可以多次调用此方法以同时播放多个音效文件，实现音效的叠加。

3. 音效播放任务管理。开始播放音效后，您还可以通过其他方法实现音效播放任务管理等更多功能，例如：

• 进度管理：调用 pauseAllEffects 方法暂停播放所有音效、调用 resumeAllEffects 方法恢复播放所有音效。
• 音量管理：调用 setEffectsVolume 方法设置音效文件的播放音量。
• 获取混音相关信息：例如通过调用 getAudioEffectsDuration、getAudioEffectsCurrentPosition 等方法获取音效文件时长或当前播放进度等。
• 在离开房间前，调用 stopAllEffects 方法结束播放所有音效。

示例代码

// 调用 preloadEffect
// soundId 指定音效的 ID。每个音效均有唯一的 ID。正整数，取值范围为 [1,10000]。
// filePath 必须，指定在线音效文件的绝对路径(支持MP3，AAC 以及浏览器支持的其他音频格式。)
rtc.localStream.preloadEffect(soundId, filePath)
    .then(res=>{
    console.log('预加载音效文件成功: ', res)
    }).catch(err=>{
    console.error('预加载音效文件失败: ', err)
    })


 // 调用 playEffect
 // 注意，如果 filePath 指向其他域名下的文件，则该音频文件需进行跨域配置
 let options = {
    filePath,  // 必须，指定在线音效文件的绝对路径(支持MP3，AAC 以及浏览器支持的其他音频格式。)
    cycle,  // 可选，指定音效文件循环播放的次数
    soundId  // 指定音效的 ID。每个音效均有唯一的 ID。
 }

rtc.localStream.playEffect({
    filePath, 
    cycle,
    soundId
    }).then(res=>{
    console.log('音效文件播放成功: ', res)
    }).catch(err=>{
    console.error('播放音效文件失败: ', err)
    })


// 调用 pauseAllEffects 暂停所有音效播放
rtc.localStream.pauseAllEffects()
    .then(res=>{
    console.log('pauseAllEffects 成功')
    }).catch(err=>{
    console.error('pauseAllEffects 失败: ', err)
    })


// 调用 resumeAllEffects 恢复所有音效播放
rtc.localStream.resumeAllEffects()
    .then(res=>{
      console.log('resumeAllEffects 成功')
    }).catch(err=>{
      console.error('resumeAllEffects 失败: ', err)
    })


// 调用 setEffectsVolume 设置所有音效文件播放音量
rtc.localStream.setEffectsVolume(volume)
    .then(res=>{
        console.log('setEffectsVolume 成功', res)
    }).catch(err=>{
        console.error('setEffectsVolume 失败: ', err)
    })


// 调用 getAudioEffectsDuration 获取音效文件时长
let audioEffectsDuration  = rtc.localStream.getAudioEffectsDuration({filePath,soundId})


// 调用 getAudioEffectsCurrentPosition 获取当前音效播放进度
let audioEffectsCurrentPosition = rtc.localStream.getAudioEffectsCurrentPosition({filePath,soundId})


// 调用 stopAllEffects 结束音效播放
rtc.localStream.stopAllEffects()
    .then(res=>{
      console.log('stopAllEffects 成功', res)
    }).catch(err=>{
      console.error('stopAllEffects失败: ', err)
    })

API 参考

方法	功能描述
preloadEffect	预加载指定音效文件
unloadEffect	释放指定音效文件
playEffect	播放指定音效文件
stopEffect	停止播放指定音效文件
pauseEffect	暂停播放指定音效文件
resumeEffect	恢复播放指定音效文件
stopAllEffects	停止播放所有音效文件
pauseAllEffects	暂停播放所有音效文件
resumeAllEffects	恢复播放所有音效文件
setVolumeOfEffect	设置指定音效文件的播放音量
setEffcetsVolume	设置所有音效文件的播放音量
getEffectsVolume	获取所有音效文件的播放音量
getAudioEffectsDuration	获取音效文件的时长
getAudioEffectsCurrentPosition	获取音效文件的播放进度
StopAllEffects	停止播放所有音效文件

配置伴音

配置步骤

1. 加入房间成功后，调用 startAudioMixing 创建伴音任务。

2. 伴音任务管理。开始伴音后，还可以通过其他方法实现伴音任务管理等更多功能，例如：

• 进度管理: 通过 pauseAudioMixing 和 resumeAudioMixing 暂停或恢复伴音、通过 setAudioMixingPosition 设置伴音文件的播放进度。
• 音量管理：通过 adjustAudioMixingVolume 调整伴音音量。
• 获取混音相关信息：例如通过 getAudioMixingDuration、setAudioMixingPosition等接口获取伴音文件的播放进度等。

3. 在离开房间前调用 stopAudioMixing 结束伴音。

示例代码

//开始伴音
const audioMixingEndHandler = function(event){
  console.warn('伴音结束: ', event)
}

const options = {
  audioFilePath: '"someaudio.mp3"', 
  loopback: false,
  replace: false,
  cycle: 0,
  playStartTime: 0,
  volume: 200,
  auidoMixingEnd: audioMixingEndHandler
}
localStream.startAudioMixing(options).then(res=>{
  console.log('伴音成功')
}).catch(err=>{
  console.error('伴音失败: ', err)
})

//暂停伴音
localStream.pauseAudioMixing().then(res=>{
  console.log('暂停伴音成功')
}).catch(err=>{
  console.error('暂停伴音失败: ', err)
})

//恢复伴音
localStream.resumeAudioMixing().then(res=>{
  console.log('恢复伴音成功')
}).catch(err=>{
  console.error('恢复伴音失败: ', err)
})

//停止伴音
localStream.stopAudioMixing().then(res=>{
  console.log('停止伴音成功')
}).catch(err=>{
  console.error('停止伴音失败: ', err)
})

API 参考

方法	功能描述
startAudioMixing	开始播放音乐文件和本地麦克风声音的混合
pauseAudioMixing	暂停播放音乐文件
resumeaudiomixing	恢复播放指定音效文件
stopaudiomixing	停止播放指定音效文件
adjustaudiomixingvolume	调节音乐文件音量
getaudiomixingduration	获取音乐文件时长
getaudiomixingcurrentposition	获取音乐文件当前播放进度
setaudiomixingposition	设置音乐文件的播放进度

常见问题

为什么我开启伴音效果后，对方听不清我的人声？

答：一般是因为您设置的伴音音量和人声音量不合理，导致接收端的音频效果较差。网易云信建议您调用 adjustRecordingSignalVolume 方法设置采集音量为 100，即不对信号做缩放；且调用 setAudioMixingPlaybackVolume 方法设置的混音播放音量不超过 25，否则伴音过程中语音沟通的体验会受到影响。