实时音视频

  • 实时音视频 > 使用指南 > iOS >背景音乐混音

    背景音乐混音

    最近更新时间: 2023-10-20 19:44:29

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

    • v5.0.0 版本将 QNAudioMixer 移除,从 v5.1.0 版本开始,请使用 QNAudioMusicMixer 进行背景音乐的混音操作
    • 背景音乐混音支持本地文件和在线文件,支持的音频文件格式为:aac、mp3、mp4、wav、m4r、caf、ogg、opus、m4a、flac
    • 请尽量使用本地音乐文件,避免因为网络资源的异常导致的混音卡顿等情况
    • 在 [QNRTC deinit] 之前,请先离开房间,再销毁 mixer 和 audioTrack 对象

    使用方式如下:

    创建和销毁 QNAudioMusicMixer

    SDK 当前支持基于 QNMicrophoneAudioTrackQNCustomAudioTrack 的混音功能,可以通过 QNRTC.createAudioMusicMixer 来创建 QNAudioMusicMixer 对象,使用 audioTrack.addAudioFilter 将 audioMusicMixer 对象添加到 audioTrack 中

    NSString *filePath = [[NSBundle mainBundle] pathForResource:@"music" ofType:@"mp3"];
    QNAudioMusicMixer *audioMusicMixer = [QNRTC createAudioMusicMixer:filePath musicMixerDelegate:self];
    [audioTrack addAudioFilter:audioMusicMixer];
    

    其中,QNAudioMusicMixerDelegate 为背景音乐混音回调代理,回调方法定义如下:

    
    /*!
     * @abstract 背景音乐混音发生错误的回调
     *
     * @param audioMusicMixer 背景音乐混音实例
     *
     * @param error 错误
     *
     * @since v5.1.0
     */
    - (void)audioMusicMixer:(QNAudioMusicMixer *)audioMusicMixer didFailWithError:(NSError *)error;
    
    /*!
     * @abstract 背景音乐混音状态变化的回调
     *
     * @param audioMusicMixer 背景音乐混音实例
     *
     * @param musicMixerState 背景音乐混音回调代理
     *
     * @since v5.1.0
     */
    - (void)audioMusicMixer:(QNAudioMusicMixer *)audioMusicMixer didStateChanged:(QNAudioMusicMixerState)musicMixerState;
    
    /*!
     * @abstract 背景音乐混音当前进度的回调
     *
     * @param audioMusicMixer 背景音乐混音实例
     *
     * @param currentPosition 当前进度
     *
     * @discussion 需要注意的是这个回调在解码线程,请不要做过于耗时的操作,否则可能阻塞该线程影响音频输出或其他未知问题。
     *
     * @since v5.1.0
     */
    - (void)audioMusicMixer:(QNAudioMusicMixer *)audioMusicMixer didMixing:(int64_t)currentPosition;
    
    

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

    确认后续不再需要使用或者需要重新创建 QNAudioMusicMixer,先通过 audioTrack.removeAudioFilter 移除 musicMixer,再通过 QNRTC.destroyAudioMusicMixer 接口进行销毁,使用代码参考如下:

    [audioTrack removeAudioFilter:musicMixer];
    [QNRTC destroyAudioMusicMixer:musicMixer];
    

    混音控制

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

    // 开始混音,成功后会触发 didStateChanged 回调状态 QNAudioMusicMixerStateMixing
    [audioMusicMixer start];
    // 停止混音,成功后会触发 didStateChanged 回调状态 QNAudioMusicMixerStateStopped
    [audioMusicMixer stop];
    // 恢复混音,成功后会触发 didStateChanged 回调状态 QNAudioMusicMixerStateMixing
    [audioMusicMixer resume];
    // 暂停混音,成功后会触发 didStateChanged 回调状态 QNAudioMusicMixerStatePaused
    [audioMusicMixer pause];
    // 跳到指定位置进行混音,成功后回触发 didStateChanged 回调状态 QNAudioMusicMixerStateMixing
    [audioMusicMixer seekTo:position);
    

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

    音量控制

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

    参考代码如下:

    [microphoneAudioTrack setVolume:0.5];          // 设置麦克风采集(混音)音量
    [microphoneAudioTrack setPlayingVolume:0.5];   // 设置混音后本地播放的音量
    [audioMusicMixer setMusicVolume:0.5];          // 设置背景音乐的混音音量
    

    返听

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

    [microphoneAudioTrack setEarMonitorEnabled:YES]; // 开启返听
    

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

    发布

    混音场景下,默认背景音乐发布到远端,即 publishEnabled 为 YES。可使用 QNAudioMusicMixer.setPublishEnabled 选择是否发布到远端,设置 publishEnabled 为 NO 时,仅在本地播放,不会发布到远端。

    参考代码如下:

    [audioMusicMixer setPublishEnabled:NO];      // 不发布到远端,仅在本地播放
    

    切换音乐

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

    // 使用 music-1 进行混音
    QNAudioMusicMixer *audioMusicMixer = [microphoneAudioTrack createAudioMusicMixer:music1FilePath musicMixerDelegate:self]; // 创建基于 music-1 的混音控制器
    [audioMusicMixer start];  // 开始 music-1 的混音
    [audioMusicMixer stop];   // 停止 music-1 的混音
    // 切换音乐到 music-2 进行混音
    audioMusicMixer = *audioMusicMixer = [microphoneAudioTrack createAudioMusicMixer:music2FilePath musicMixerDelegate:self]; // 创建基于 music-2 的混音控制器
    [audioMusicMixer start];  // 开始 music-2 的混音
    [audioMusicMixer stop];   // 停止 music-2 的混音
    

    注意事项

    1. 混音功能会将混音音乐与当前已发布的音频 Track 数据混合并推送出去,若当前的音频 Track 尚未发布,则混音操作将失效。
    2. 混音功能建议在佩戴耳机的情况下使用以获得更好的体验。
    3. 加入房间后,请确保 AVAudioSession 的 category 类型和 mode 模式分别是 AVAudioSessionCategoryPlayAndRecordAVAudioSessionModeVoiceChat,以免出现播放声音突然变小、录屏失败(报错 -5833)等非预期问题。

    示例代码

    背景音乐混音场景的示例代码可参考 API-Examples-iOS

    以上内容是否对您有帮助?
  • Qvm free helper
    Close