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

功能概述

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

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

• 播放短时音效：

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

• 播放背景音乐：

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

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

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

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

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

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

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

注意事项

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

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

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

配置音效

配置步骤

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

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

   • path：指定音效文件的路径，例如 D:\\audio_files\\test.mp3。支持本地绝对路径或 URL 地址。

   • loopCount：指定音效文件循环播放的次数。默认值为1，即默认仅播放一次；若该值小于等于0，则默认为无限循环播放。

   • sendEnabled：是否将音效发送至远端。该参数的默认值为 YES，即远端用户可以听到该音效。

   • sendVolume：音效文件的发送音量。该参数的取值范围为 0 ~ 100，默认值为 100，表示使用文件的原始音量。

   • playbackEnabled：是否本地播放该音效。默认为 YES，即本地用户可以听到该音效。

   • playbackVolume：音效文件的播放音量。该参数的取值范围为 0 ~ 100，默认值为 100，表示使用文件的原始音量。

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

2. 设置音效的音量。

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

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

示例代码

// 打开音效
let roomContext = NERoomKit.shared().roomService.getRoomContext(roomUuid: "房间ID")

guard let roomContext = roomContext else {
    return
}
let option = NERoomAudioOption()
option.playbackVolume = 100
option.path = "音效文件的路径"
option.loopCount = 1
option.sendEnabled = true
option.sendVolume = 100
option.playbackEnabled = true
let effectId = 1
roomContext.rtcController.playEffect(effectId: effectId, option: option) { code, string in
    if code == 0 {
        print("Successfully play effect.")
    } else {
        print("Failed to play effect. Reason: \(string ?? "")")
    }
}

// 设置音效发送音量
roomContext.rtcController.setEffectSendVolume(effectId: effectId, volume: 80) { code, string in
    if code == 0 {
        print("Successfully set effect send volume.")
    } else {
        print("Failed to set effect send volume. Reason: \(string ?? "")")
    }
}

// 设置音效播放音量
roomContext.rtcController.setEffectPlaybackVolume(effectId: effectId, volume: 80) { code, string in
    if code == 0 {
        print("Successfully set effect playback volume.")
    } else {
        print("Failed to set effect playback volume. Reason: \(string ?? "")")
    }
}

// 根据id关闭音效
roomContext.rtcController.stopEffect(effectId: effectId) { code, string in
    if code == 0 {
        print("Successfully stop effect.")
    } else {
        print("Failed to stop effect. Reason: \(string ?? "")")
    }
}

// 关闭所有音效
roomContext.rtcController.stopAllEffect() { code, string in
    if code == 0 {
        print("Successfully stop all effect.")
    } else {
        print("Failed to stop all effect. Reason: \(string ?? "")")
    }
}

API 参考

方法	功能描述
playEffect	播放指定音效文件
setEffectSendVolume	设置音效文件发送音量
setEffectPlaybackVolume	设置音效文件播放音量
stopEffect	停止播放指定音效文件
stopAllEffect	停止播放所有音效文件

配置伴音

配置步骤

1. 加入房间成功后，通过 NERoomAudioOption 设置伴音参数，例如伴音文件路径、是否本地播放等等。

2. 调用 startAudioMixing 开始伴音。

3. 设置伴音的音量。

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

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

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

示例代码

// 打开混音
let roomContext = NERoomKit.shared().roomService.getRoomContext(roomUuid: "房间ID")

guard let roomContext = roomContext else {
    return
}
let option = NERoomAudioOption()
option.playbackVolume = 100
option.path = "伴音文件的路径"
option.loopCount = 1
option.sendEnabled = true
option.sendVolume = 100
option.playbackEnabled = true
let effectId = 1
roomContext.rtcController.startAudioMixing(option: option) { code, string in
    if code == 0 {
        print("Successfully start audio mixing.")
    } else {
        print("Failed to start audio mixing. Reason: \(string ?? "")")
    }
}

// 设置混音发送音量
roomContext.rtcController.setAudioMixingSendVolume(volume: 80) { code, string in
    if code == 0 {
        print("Successfully set audio mixing send volume.")
    } else {
        print("Failed to set audio mixing send volume. Reason: \(string ?? "")")
    }
}

// 设置混音播放音量
roomContext.rtcController.setAudioMixingPlaybackVolume(volume: 80) { code, string in
    if code == 0 {
        print("Successfully set audio mixing playback volume.")
    } else {
        print("Failed to set audio mixing playback volume. Reason: \(string ?? "")")
    }
}

// 关闭混音
roomContext.rtcController.stopAudioMixing() { code, string in
    if code == 0 {
        print("Successfully stop audio mixing.")
    } else {
        print("Failed to stop audio mixing. Reason: \(string ?? "")")
    }
}

API参考

方法	功能描述
startAudioMixing	开始伴音
stopAudioMixing	结束伴音
setAudioMixingPlaybackVolume	设置伴音播放音量
setAudioMixingSendVolume	设置伴音的发送音量