混音中带媒体次要信息

---

1 功能简介

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

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

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

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

2 步骤

混音的使用流程如下：

1. App 启用混音功能

2. App 设置混音音量

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

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

2.1 启用混音功能

调用此 API 启用混音功能。

zego-api-audio-aux.h

/**
 混音开关

 @param enable true 启用混音输入，false 关闭混音输入。默认 false
 @return true 成功，false 失败
 @attention 必须确保在 initSDK 后调用
 @note 主播端开启混音后，SDK 在 ILivePublisherCallback::OnAuxCallback 中获取混音输入数据
 */
 bool EnableAux(bool bEnable);

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

2.2 设置混音音量

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

LiveRoom-Publisher.h

/**
 设置混音音量

 @param volume 0~100，默认为 50
 */
 void SetAuxVolume(int volume);

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

LiveRoom-Publisher.h

/**
 混音静音开关

 @param bMute true: aux 输入播放静音，false: 不静音。默认 false
 @return true 成功，false 失败
 @attention 推流开始前调用本 API 进行参数配置
 */
 bool MuteAux(bool bMute);

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

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

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

LiveRoom-Publisher.h

/**
发送媒体次要信息开关

@param bStart true 开启, false 关闭
@param bOnlyAudioPublish true 纯音频直播，不传输视频数据, false 音视频直播，传输视频数据
@param idx 推流 channel Index. 默认为主Channel
@attention onlyAudioPublish 开关在 start 开关开启时才生效
*/
void SetMediaSideFlags(bool bStart, bool bOnlyAudioPublish, AV::PublishChannelIndex idx = AV::PUBLISH_CHN_MAIN);

请注意，SDK 如果需要在混音功能中发送媒体次要信息,必须要开启媒体次要信息开关才能发送成功。

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

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

zego-api-audio-aux.h

/** 混音音频数据输入回调。
当开启混音后，通过此回调获取混音音频数据。
注意：
1. 支持 16k 32k 44.1k 48k 采样率、单声道或者双声道、16位深的PCM 音频数据；
2. 用户根据实际填写采样率及声道数；
3. 为确保混音效果，请不要在此 API 中执行耗时操作 
@param pDataLen
*pDataLen既是输入参数也是输出参数；
作为输入参数，SDK会提供好长度值，用户按照这个长度写入数据即可，数据足够的情况下，无需更改*pDataLen的值
作为输出参数，如果填写的数据不足SDK提供的长度值，则赋值*pDataLen = 0;
或者最后的尾音不足SDK提供的长度值，可以用静音数据补齐。
@param pSampleRate 混音数据采样率，支持16k、32k、44.1k、48k
@param pNumChannels 混音数据声道数，支持1、2
@param pSideInfo 媒体次要信息数据缓冲区地址
@param pSideInfoLength 媒体次要信息数据缓冲区长度
@param bPacket  媒体次要信息数据是否外部已经打包好包头
@attention 用户调用该 API 将混音数据传递给 SDK
@note 混音数据 bit depth 必须为 16
*/
void OnAuxCallbackEx(unsigned char *pData, int *pDataLen, int *pSampleRate, int *pNumChannels,unsigned char *pSideInfo, int *pSideInfoLen, bool *bPacket) {}

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

OnAuxCallbackEx(unsigned char *pData, int *pDataLen, int *pSampleRate, int *pNumChannels,unsigned char *pSideInfo, int *pSideInfoLen, bool *bPacket)
 {
    if ((m_pAuxData != nullptr) && (*pDataLen < m_nAuxDataLen))
    {
        *pSampleRate = 44100;
        *pNumChannels = 2;

        if ((m_nAuxDataPos + *pDataLen) >= m_nAuxDataLen))
        {
            int nSlience = (m_nAuxDataPos + *pDataLen) - m_nAuxDataLen;
            if (nSlience > 0)
            {
                memcpy(pData, m_pAuxData + m_nAuxDataPos, *pDataLen - nSlience);
                memset(pData + *pDataLen - nSlience, 0, nSlience);
            }
            else
            {
                memcpy(pData, m_pAuxData + m_nAuxDataPos, *pDataLen);
            }
            m_nAuxDataPos = 0;
        }
        else
        {
            memcpy(pData, m_pAuxData + m_nAuxDataPos, *pDataLen);
            m_nAuxDataPos += *pDataLen;
        }

        int nCopyLen = ;


        //-------带有媒体次要信息示例代码--------
        //注意: 发送媒体次要信息前提必须要带有混音数据
        Byte mediaSideInfo[] ={0x60,0x61,0x62,0x63,0x64,0x65,0x66,0x67,0x68,0x69};
        *pSideInfoLength = 10;
        *pPacket=false;
        memcpy(pSideInfo, mediaSideInfo, *pSideInfoLength);

    }
    else
    {
        *pDataLen = 0;
    }
    // 以上演示的是循环播放音频,尾端补齐静音，请开发者按照各自的需求实现该方法，不要直接复制。
}

请注意：

1. 以上演示的是循环播放音频，请开发者按照各自的需求实现该方法，不要直接复制。
2. 如果数据足够，则copy pDataLen长度的数据到pData，如果不足要不补齐静音到SDK指定的pDataLen长度，要不设置 *pDataLen = 0。