本文主要介绍连麦过程中添加背景音乐混音的使用场景。

• 从 v5.2.6 版本开始，QNAudioMusicMixer 需要通过 QNRTC.createAudioMusicMixer 接口创建，并通过 QNLocalAudioTrack.addAudioFilter 的方式进行关联。将不再支持通过 QNMicrophoneAudioTrack.createAudioMusicMixer 创建
• 从 v5.1.0 版本开始，QNAudioMixer 已废弃，请使用 QNAudioMusicMixer 控制类进行背景音乐的混音操作
• 背景音乐混音支持本地文件和在线文件，支持的音频文件格式为：aac、mp3、mp4、ogg、opus、wav、m4a、flac
• 请尽量使用本地音乐文件，避免因为网络资源的异常导致的混音卡顿等情况

使用方式如下：

SDK 支持对不同的音频 Track 设置混音控制器，可以通过 QNRTC.createAudioMusicMixer 来创建 QNAudioMusicMixer 对象，再通过 QNLocalAudioTrack.addAudioFilter 的方式进行混音控制器的关联。

String filePath = "/sdcard/music/example.mp3";
QNAudioMusicMixer audioMixer = QNRTC.createAudioMusicMixer(filePath, mAudioMusicMixerListener);  // 创建音乐混音控制器
localAudioTrack.addAudioFilter(audioMixer);  // 关联音乐混音控制器

其中，QNAudioMusicMixerListener 为混音状态监听器，监听回调定义如下：

public interface QNAudioMusicMixerListener {
    /**
     * 混音状态改变时会回调
     *
     * @param state 当前状态
     */
    void onStateChanged(QNAudioMusicMixerState state);

    /**
     * 混音操作进行过程中会回调
     *
     * @param position 当前正在执行混音操作的音频帧时间戳，单位：ms
     */
    void onMixing(long position);

    /**
     * 混音操作发生错误时会回调
     *
     * @param errorCode 错误码
     * @param errorMessage 错误信息
     */
    void onError(int errorCode, String errorMessage);
}

其中，混音状态的改变都会通过 QNAudioMusicMixerListener.onStateChanged 回调通知到上层。回调的监听状态可参考 QNAudioMusicMixerState。混音场景下的错误码可参考混音相关错误码

注意：同一个音乐混音控制器只能关联一个音频 Track，重复添加将会失败。

在创建了 QNAudioMusicMixer 实例后，可以通过该实例提供的混音控制接口进行混音操作的控制，使用代码参考如下：

// 开始混音，成功后会触发 QNAudioMusicMixerState.MIXING 状态的回调
mAudioMixer.start();
// 停止混音，成功后会触发 QNAudioMusicMixerState.STOPPED 状态的回调
mAudioMixer.stop();
// 恢复混音，成功后会触发 QNAudioMusicMixerState.MIXING 状态的回调
mAudioMixer.resume();
// 暂停混音，成功后会触发 QNAudioMusicMixerState.PAUSED 状态的回调
mAudioMixer.pause();
// 跳到指定位置进行混音，成功后回触发 QNAudioMusicMixerState.MIXING 状态的回调
mAudioMixer.seekTo(positionMs);

上述为混音基本流程的控制，更多控制方式请参考 QNAudioMusicMixer。

SDK 混音功能默认会将混音音乐推送至远端。

从 v5.2.0 版本开始，SDK 支持配置混音是否需要推送至远端，若关闭推送，则背景音乐将只做本地播放，配置接口如下：

mAudioMixer.setPublishEnabled(false);

注：若您的业务场景涉及到本地背景音乐的播放，那么为了避免系统的降噪对通话质量产生影响，我们建议您通过背景音乐混音接口替代其他音频播放器来实现本地音乐的播放。

混音场景下，主要包含三种音量设置：麦克风混音音量、背景音乐混音音量、本地播放音量。三种音量的设置方式参考如下：

• 麦克风混音音量：可以通过 QNMicrophoneAudioTrack.setVolume 接口进行配置。
• 背景音乐混音音量：可以通过 QNAudioMusicMixer.setMixingVolume 接口进行配置。
• 本地播放音量：可以通过 QNMicrophoneAudioTrack.setPlayingVolume 接口进行配置，需要注意的是，播放音量是基于混音后的音频进行调整的，会受到混音音量调整的影响。

参考代码如下：

mMicrophoneAudioTrack.setVolume(0.5f);          // 设置麦克风采集(混音)音量
mMicrophoneAudioTrack.setPlayingVolume(0.5f);   // 设置混音后本地播放的音量
mAudioMusicMixer.setMixingVolume(0.5f);         // 设置背景音乐的混音音量

若您在混音场景下，有开启返听的需要，则可以通过 QNMicrophoneAudioTrack.setEarMonitorEnabled 接口进行开启，参考代码如下：

mMicrophoneAudioTrack.setEarMonitorEnabled(true); // 开启返听

为达到最佳体验，建议在佩戴耳机的情况下使用该功能

背景音乐混音仅支持同时混合一路背景音乐，若需要切换背景音乐，可通过重新调用 QNMicrophoneAudioTrack.createAudioMusicMixer 创建 QNAudioMusicMixer 实例实现。参考代码如下：

// 使用 music-1 进行混音
QNAudioMusicMixer audioMusicMixer = QNRTC.createAudioMusicMixer(music1FilePath, mAudioMusicMixerListener); // 创建基于 music-1 的混音控制器
localAudioTrack.addAudioFilter(audioMusicMixer);
audioMusicMixer.start();  // 开始 music-1 的混音
audioMusicMixer.stop();   // 停止 music-1 的混音
// 切换音乐到 music-2 进行混音
audioMusicMixer = QNRTC.createAudioMusicMixer(music2FilePath, mAudioMusicMixerListener); // 创建基于 music-2 的混音控制器
localAudioTrack.addAudioFilter(audioMusicMixer);
audioMusicMixer.start();  // 开始 music-2 的混音
audioMusicMixer.stop();   // 停止 music-2 的混音

1. 混音功能会将混音音乐与当前已发布的音频 Track 数据混合并推送出去，若当前的音频 Track 尚未发布，则混音操作将失效。
2. 混音功能建议在佩戴耳机的情况下使用。需要注意的是 SDK 内部播放器的音量控制采用了 Android 5.0 以上设置播放音量相关的 API，所以存在设置背景音量对部分低版本机型在本地播放时可能会失效，但在远端听到的是设置好的音量的情况，故混音功能推荐在 Android 5.0 以上的机型中使用以获得最好的体验。
3. 同一个音乐混音控制器只能关联一个音频 Track，重复添加将会失败。

背景音乐混音场景的完整示例代码可参考 QNRTC-API-Examples。