混音中带媒体次要信息

---

1 功能简介

ZegoLiveRoom SDK 为开发者提供了混音功能。

混音是指，SDK 从 App 获取一路音频数据，将其与采集的音频数据，整合为一路混音数据，进而推流。

直播过程中的掌声，口哨，背景音等音效均可通过混音实现。

混音的过程中可以带有(不能大于 1000 Bytes)媒体次要信息。

2 步骤

混音的使用流程如下：

1. App 启用混音功能

2. App 设置混音音量

3. App 设置媒体次要信息开关(如果不需要发送媒体次要信息,可不用设置,默认为关闭)

4. App 将混音数据中带有媒体次要信息传递给 SDK

2.1 启用混音功能

调用此 API 启用混音功能。

ZegoAudioAux.java
/**
 * 混音开关。
 * 注意：必须在 {@link #initSDK(long, byte[], Context)} 后调用，在需要混音的任一时间开启。
 * 当开启混音后，SDK 会在 {@link IZegoAudioAuxCallback#onAuxCallback(int expectDataLength)} 中获取用于混音的音频数据。
 *
 * @param enable   true: 开启，false: 关闭。默认 false（关闭混音）
 * @return         true: 调用成功，false: 调用失败
 */
public boolean enableAux(boolean enable);

请注意，后续操作均基于开启混音功能的基础上。

2.2 设置混音音量

启用混音后，调用此 API 调整混音音量。

ZegoLiveRoom.java
/**
 * 设置混音音量。
 *
 * @param volume 音量 0 ~ 100，默认为 50
 *
 * @see #muteAux(boolean)
 * @see #enableAux(boolean)
 */
public void setAuxVolume(int volume);

也可调用此 API 设置混音静音。

ZegoLiveRoom.java
/**
 * 混音静音开关。
 * 当设置为 true 后，主播和观众端都将听不到混音内容。
 *
 * @param mute      true:开启, false:关闭
 * @return          true:调用成功, false:调用失败
 *
 * @see #setAuxVolume(int)
 */
public boolean muteAux(boolean mute);

请注意，SDK 对上述两个混音音量相关的 API 的调用时机无要求，混音前或混音后调用均可，取决于用户需求。

2.3 App 设置媒体次要信息开关(如果不需要发送媒体次要信息,可不用设置,默认为关闭)

启用混音后，如果需要传递媒体次要信息,则需要开启媒体次要信息开关,如果不需要发送媒体次要信息 则可以不用开启，默认为不开启

ZegoLiveRoom.java
/**
* 发送媒体次要信息开关.
*
* @param start              true 开启, false 关闭
* @param onlyAudioPublish   true:纯音频直播，不传输视频数据; false:音视频直播，传输视频数据
*/
public void setMediaSideFlags(boolean start, boolean onlyAudioPublish);

2.4 App 将混音数据中带有媒体次要信息传递给 SDK

启用混音后，SDK 通过此 API 获取待传递的混音数据和媒体次要信息

IZegoAudioAuxCallbackEx.java


/**
* 混音音频数据输入回调。
* 当开启混音后，通过此回调获取混音音频数据。
* 发送媒体次要信息前需要调用setMediaSideFlags设置媒体次要信息开关
* 此接口带媒体次要信息时必须要带有混音音频数据才能发送媒体次要信息
* 如果不带混音音频数据则会丢掉媒体次要信息
* 注意：
* 1. 支持 16k 32k 44.1k 48k 采样率、单声道或者双声道、16位深的PCM 音频数据
* 2. 用户根据实际填写采样率及声道数； 
* 3. 为确保混音效果，请不要在此 API 中执行耗时操作
* @param expectDataLength SDK会提供好长度值, 用户按照这个长度写入数据即可, 如果填写的数据不足SDK提供的长度值, 则返回NULL值;
* 或者最后的尾音不足SDK提供的长度值，可以用静音数据补齐。
* @return 混音音频数据(包括媒体次要信息)、格式必须是位深为 16(2字节), 支持的采样率为 16k、32k、44.1k、48k, 支持的声道数为 1、2。
* @see com.zego.zegoavkit2.audioaux.ZegoAudioAux#enableAux(boolean)
* @see com.zego.zegoavkit2.entities.AuxDataEx
*/
AuxDataEx onAuxCallback(int expectDataLength);

示例代码片段如下： 示例代码中pcm文件采样率为:44100 声道数为: 2

IZegoAudioAuxCallbackEx.java

final static int AUX_DATA_CHANNEL_COUNT = 2;
final static int AUX_DATA_SAMPLE_RATE = 44100;
IZegoAudioAuxCallbackEx() {
    @Override
    public AuxDataEx onAuxCallback(int expectDataLength) {
        // 开启伴奏后, SDK 每 20ms 取一次数据
        if (!mEnableBackgroundMusic) {
            return null;
        }

         auxData.auxDataBuf = ByteBuffer.allocateDirect(expectDataLength);
         auxData.auxDataBufLen = expectDataLength;
         byte[] bytes = new byte[expectDataLength];

        try {
            AssetManager am = getAssets();
            if (mIsBackgroundMusic == null) {
            // a.pcm 为用于混音的音频数据，其采样率为 44100，声道数为 2，位深 16
            mIsBackgroundMusic = am.open("a.pcm");
        }
            int len = mIsBackgroundMusic.read(bytes);
            if (len <= 0 || len < expectDataLength) {
                // 歌曲播放完毕
                mIsBackgroundMusic.close();
                mIsBackgroundMusic = null;
                auxData.auxDataBufLen = 0;
            }
        } catch (IOException e) {
            e.printStackTrace();
        }

        auxData.auxDataBuf.put(bytes);
        // 设置声道数，请根据实际音频数据设置
        auxData.channelCount = AUX_DATA_CHANNEL_COUNT;
        // 设置采样率，请根据实际音频数据设置
        auxData.sampleRate = AUX_DATA_SAMPLE_RATE;

        //-------媒体次要信息示例代码--------
        //注意: 发送媒体次要信息前提必须要带有混音数据

        //注意: 必须使用ByteBuffer.allocateDirect(int)创建buffer, 否则数据无法传递给sdk
        auxData.mediaSideInfoBuf = ByteBuffer.allocateDirect(10);
        //需要发送的信息
        byte[] mediaSide = new byte[]{0x60,0x61,0x62,0x63,0x64,0x65,0x66,0x67,0x68,0x69};
        auxData.mediaSideInfoBuf.put(mediaSide);
        //媒体次要信息长度
        auxData.mediaSideInfoBufLen=10;
        //是否外部已经打包好包头, true:已打包, false:未打包
        auxData.packet=false;


        return auxData;
    }
}

请注意：

1. 目前 SDK 仅支持位深为 16bit 的 PCM 音频数据格式。

2. 如果用完混音功能后,不需要再次使用到混音功能 , 请调用ZegoAudioAux中enableAux (false); 并把回调值为NULL

3. SDK会提供好长度值, 用户按照这个长度写入数据即可, 如果填写的数据不足SDK提供的长度值, 则返回NULL值;

4. 以上演示的是循环播放音频，请开发者按照各自的需求实现该方法，不要直接复制。