NERoom 支持通过混音功能播放掌声、口哨等短时音效，或者为人声添加背景音乐、伴奏音乐或其他场景效果，并将合成后的声音播放给房间内其他成员。在音视频通话或直播场景中，可以更好的烘托气氛、营造多样化语音环境。

功能概述

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

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

• 播放短时音效：

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

• 播放背景音乐：

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

NERoom 混音功能支持如下设置：

• 混音：混音指的是音乐文件的音频流跟麦克风采集的音频流进行混音（叠加）并编码发送给对方。

• 循环：可以设置是否循环播放混音文件，以及循环次数。

• 音量控制：可以各自控制本地播放以及编码发送的混音音量。

• 定位：混音任务支持从背景音乐文件的任意位置开始播放。

• 叠加：可以同时播放多个短时音效文件。

注意事项

• 伴音相关方法的返回值若小于 0，表示方法调用失败。

• 请在加入房间成功后再启动混音任务。

• 本地混音文件支持 MP3、M4A、AAC、3GP、WMA、WAV 格式，支持本地 SD 卡文件和在线 URL。

配置音效

配置步骤

1. 调用 playEffect 方法播放指定 effectId 的音效文件。

   调用此方法时，您需要设置 effectId 指定音效文件的 ID；设置 option 参数指定播放的音效文件。option 参数的含义如下表所示。

   参数	类型	描述
   path	string	待播放的音效文件路径，支持本地绝对路径或 URL 地址
   loopCount	int	音效循环播放的次数。 1：（默认）播放一次。 ≤ 0：无限循环播放音效，直至调用 stopEffect 或 stopAllEffects 后停止。
   sendEnabled	bool	是否将伴音发送远端，默认为 true，即远端用户订阅本端音频流后可听到该伴音。
   sendVolume	uint32_t	音乐文件的发送音量，取值范围为 0~100。默认为 100，表示使用文件的原始音量。
   playbackEnabled	bool	是否可播放。默认为 true，即可在本地播放该音效。
   playbackVolume	int	音乐文件的播放音量，取值范围为 0~100。默认为 100，表示使用文件的原始音量。

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

• 在调用此方法成功播放指定音效文件后，若您反复停止再重新播放该 effectId 对应的音效文件，首次播放时设置的 option 无效，会恢复为默认值。

2. 设置音效的音量。

   • 调用 setEffectSendVolume 方法设置音效文件发送音量。

   • 调用 setEffectPlaybackVolume 方法设置音效文件播放音量。

3. （可选）暂停和恢复音效。

   • 调用 pauseEffect 方法暂停指定音效。
   • 调用 pauseAllEffects 方法暂停所有音效。
   • 调用 resumeEffect 方法恢复播放指定音效。
   • 调用 resumeAllEffects 方法恢复播放所有音效。

4. 在离开房间前，调用 stopAllEffects 方法停止播放所有音效文件。

示例代码

  // 播放指定音效文件
  auto context = m_pRoomKit->getRoomService()->getRoomContext(roomUuid);
  if (context) {
      int effectId = 101;
      NERoomCreateAudioEffectOption option;
      option.path = "D:\\audio_files\\test.mp3";
      option.loopCount = 1;
      option.sendEnabled = true;
      option.playbackVolume = 100;
      option.sendVolume = 100;
      context->getRtcController()->playEffect(effectId, option);
  }

  // 停止播放指定音效文件
  auto context = m_pRoomKit->getRoomService()->getRoomContext(roomUuid);
  if (context) {
      int effectId = 101;
      context->getRtcController()->stopEffect(effectId);
  }

  // 暂停音效文件播放
  auto context = m_pRoomKit->getRoomService()->getRoomContext(roomUuid);
  if (context) {
      int effectId = 101;
      context->getRtcController()->pauseEffect(effectId);
  }

  // 恢复播放指定音效文件
  auto context = m_pRoomKit->getRoomService()->getRoomContext(roomUuid);
  if (context) {
      int effectId = 101;
      context->getRtcController()->resumeEffect(effectId);
  }

  // 设置音效文件发送音量
  auto context = m_pRoomKit->getRoomService()->getRoomContext(roomUuid);
  if (context) {
      int effectId = 101;
      int volume = 100;
      context->getRtcController()->setEffectSendVolume(effectId, volume);
  }

  // 设置音效文件播放音量
  auto context = m_pRoomKit->getRoomService()->getRoomContext(roomUuid);
  if (context) {
      int effectId = 101;
      int volume = 100;
      context->getRtcController()->setEffectPlaybackVolume(effectId, volume);
  }

  // 暂停所有音效文件播放
  auto context = m_pRoomKit->getRoomService()->getRoomContext(roomUuid);
  if (context) {
      context->getRtcController()->stopAllEffects();
  }

  // 恢复播放所有音效文件
  auto context = m_pRoomKit->getRoomService()->getRoomContext(roomUuid);
  if (context) {
      context->getRtcController()->resumeAllEffects();
  }

API 参考

方法	功能描述
playEffect	播放指定音效文件
setEffectSendVolume	设置音效文件发送音量
setEffectPlaybackVolume	设置音效文件播放音量
pauseEffect	暂停指定音效
pauseAllEffects	暂停所有音效
resumeEffect	恢复播放指定音效
resumeAllEffects	恢复播放所有音效
stopAllEffects	停止播放所有音效文件

配置伴音

配置步骤

1. 加入房间成功后，通过 NERoomCreateAudioMixingOption 设置伴音参数，例如伴音文件路径、是否本地播放等等，并调用 startAudioMixing 开始伴音。 NERoomCreateAudioMixingOption 参数的含义如下表所示。

   参数	类型	描述
   path	string	待播放的音乐文件路径，支持本地绝对路径或 URL 地址。
   loopCount	int	伴音循环播放的次数。 1：（默认）播放一次。 ≤ 0：无限循环播放，直至调用 pauseAudioMixing 后暂停，或调用 stopAudioMixing 后停止。
   sendEnabled	bool	是否将伴音发送远端，默认为 true，即远端用户订阅本端音频流后可听到该伴音。
   sendVolume	uint32_t	音乐文件的发送音量，取值范围为 0~200。默认为 100，表示使用文件的原始音量。
   playbackEnabled	bool	是否本地播放伴音。默认为 true，即本地用户可以听到该伴音。
   playbackVolume	uint32_t	音乐文件的播放音量，取值范围为 0~200。默认为 100，表示使用文件的原始音量。
   startTimestamp	uint64_t	音乐文件的播放起始位置，单位毫秒。

2. 设置伴音的音量。

   • 通过 setAudioMixingSendVolume 设置伴音的发送音量。
   • 通过 setAudioMixingPlaybackVolume 设置伴音的播放音量。

   伴音播放音量建议不超过 25，否则伴音过程中语音沟通的体验会受到影响。

3. （可选）暂停和恢复伴音。

   • 调用 pauseAudioMixing 方法暂停指定音乐文件。
   • 调用 resumeAudioMixing 方法恢复播放指定音乐文件。

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

示例代码

  // 开始伴音
  auto context = m_pRoomKit->getRoomService()->getRoomContext(roomUuid);
  if (context) {
      NERoomCreateAudioMixingOption option;
      option.path = "D:\\audio_files\\test.mp3";
      option.loopCount = 1;
      option.sendEnabled = true;
      option.playbackVolume = 100;
      option.sendVolume = 100;
      context->getRtcController()->startAudioMixing(option);
  }

  // 停止伴音
  auto context = m_pRoomKit->getRoomService()->getRoomContext(roomUuid);
  if (context) {
      context->getRtcController()->stopAudioMixing();
  }

  // 调节伴奏发送音量
  auto context = m_pRoomKit->getRoomService()->getRoomContext(roomUuid);
  if (context) {
      int volume = 100;
      context->getRtcController()->setAudioMixingSendVolume(volume);
  }  
  
  // 调节伴奏播放音量
  auto context = m_pRoomKit->getRoomService()->getRoomContext(roomUuid);
  if (context) {
      int volume = 100;
      context->getRtcController()->setAudioMixingPlaybackVolume(volume);
  }
    

API参考

方法	功能描述
startAudioMixing	开始伴音
stopAudioMixing	结束伴音
setAudioMixingSendVolume	设置伴音的发送音量
setAudioMixingPlaybackVolume	设置伴音的播放音量
pauseAudioMixing	暂停指定音乐文件。
resumeAudioMixing	恢复播放指定音乐文件。