多路混流

---

1 功能简介

混流是把多路音视频流混合成单流的技术。

主播端和观众端均可主动触发混流。SDK 既支持音视频混流，也支持纯音频混流。

SDK 对设置混流的时机没有硬性要求，建议开发者在拉流 / 推流后，或根据需求，在其他合适时机进行混流。

注意： 由于主播端和观众端均可主动触发混流，以下步骤的操作方均为 主播端 或 观众端。开发者在实际使用中请注意区分接口调用方。

混流的主要流程是：

1. 设置混流配置。
2. 开始混流。
3. 获取混流配置更新通知。

本文主要以主播端 / 观众端推流后混流为例，其他时机时设置混流的步骤类似，不再赘述。

2 系统架构图

3 使用步骤

相关功能的 Demo 源码，请联系 ZEGO 技术支持获取。

按照上述流程，SDK API 调用过程如下所示。

3.1 前置条件

主播端推流后混流的前置条件为推流，请参考：快速集成-推流

注意： 推混流，请指定推流 API (StartPublishing) 中的 flag 为 ZEGO_MIX_STREAM

3.2 设置混流配置

主播端或客户端推流成功后，调用此 API 进行混流设置。

3.2.1 设置混流配置的回调

1. 设置混流配置的回调 接口：SetMixStreamExCallback (IZegoMixStreamExCallback *pCB)
2. 设置带音量信息的回调(根据需要设置带音量信息的回调) 接口：SetSoundLevelInMixedStreamCallback(IZegoSoundLevelInMixedStreamCallback* pCB)

混流配置回调API

namespace ZEGO
{
namespace MIXSTREAM
{          
    // 多路混流回调
    class IZegoMixStreamExCallback
    {
    public:
        /**
         * 混流请求结果回调
         * @param result 混流结果
         * @param pszMixStreamID 混流 ID
         * @param seq 请求 seq
         */
        virtual void OnMixStream(const AV::ZegoMixStreamResult& result, const char* pszMixStreamID, int seq) = 0;

        virtual ~IZegoMixStreamCallback() {}
    };

    /** 混流中，显示发言者及音量大小的回调。每秒钟10次通知，不拉流没有通知 */
    class IZegoSoundLevelInMixedStreamCallback
    {
    public:
        virtual void OnSoundLevelInMixedPlayStream(AV::SoundLevelInfo *volume_list, int list_size) = 0;

        virtual ~IZegoSoundLevelInMixedStreamCallback() {}
    };           

    /**
     * 设置多路混流的回调
     * @param pCB pCallback 回调
     */
    ZEGOAVKIT_API bool SetMixStreamExCallback (IZegoMixStreamExCallback *pCB); 

    /**
     * 设置接收混流中的音量信息的回调
     * @param pCB pCallback 回调
     */
    ZEGOAVKIT_API bool SetSoundLevelInMixedStreamCallback(IZegoSoundLevelInMixedStreamCallback* pCB);     
}
}

3.2.2 指定混流配置参数

ZegoMixStreamConfig 是 SDK 中定义的混流输出配置参数对象，其中包含输入流信息、输出流布局等信息，开发者需要指定。

注意： ZegoMixStreamConfig 中的 nOutputFps、nOutputBitrate、nOutputWidth、nOutputHeight、pInputStreamList、nInputStreamCount、pOutputList、nOutputStreamCount 参数都必须指定值。

具体结构为：

/** 完整混流配置 */
struct  ZegoMixStreamConfig
{
    /** 混流输出视频帧率，值范围：[1,30]，根据网络情况设定值，帧率越高画面越流畅 */
    int nOutputFps;                             

    /** 混流输出码率控制模式，0 表示 CBR 恒定码率，1 表示 CRF 恒定质量，默认为 0 
     *  CRF 恒定质量 表示保证视频的清晰度在固定水平上，因此若采用此控制模式，码率会根据网速的变化波动。
     * 比如游戏类直播时，为了让观众看到比较流畅的操作类画面会使用恒定质量模式，提升视频质量。
     */
    int nOutputRateControlMode;                 

    /** 混流输出码率，仅当输出码率控制模式设置为 CBR恒定码率 时此设置值生效
     *  视频码率值范围： <= 10M，此参数单位是 bps，1M = 1 * 1000 * 1000 bps
     */
    int nOutputBitrate;                         

    /** 混流输出视频分辨率宽，不确定用什么分辨率时可采用16:9的规格设置
     *  此值必须大于等于 输入流列表中所有输入流中最大的分辨率宽，即 right 布局值，且输入流的布局位置不能超出此值规定的范围
     */
    int nOutputWidth;   

    /** 混流输出视频分辨率高，不确定用什么分辨率时可采用16:9的规格设置
     *  此值大于等于 输入流列表中所有输入流中最大的分辨率高，即 bottom 布局值，且输入流的布局位置不能超出此值规定的范围
     */                        
    int nOutputHeight;

    /** 混流输入流列表，SDK 根据输入流列表中的流进行混流 */
    ZegoMixStreamInput* pInputStreamList;      

    /** 混流输入流列表个数 */
    int nInputStreamCount;                      

    /** 混流输出列表 */
    ZegoMixStreamOutput* pOutputList;           

    /** 混流输出列表个数 */
    int nOutputStreamCount; 

    /** 混流输出质量，输出码率控制模式设置为 CRF恒定质量 时有效，有效范围 [0,51]，默认值是 23 
     *  若想视频质量好点，在23的基础上降低质量值测试调整
     *  若想文件大小小一点，在23的基础上升高质量值测试调整，以 x 值下的文件大小为例， x + 6 下的文件大小是 x 值下文件大小的一半，x - 6 下的文件大小是 x 值下 文件大小的两倍
     */
    int nOutputQuality;                         

    /** 混流输出音频码率，码率范围值是[10000, 192000]
     *  若音频编码格式采用默认音频编码--outputAudioConfig 参数填0，采用 1/2声道时，建议码率值是 48k/64k，可根据需要在此基础上调整
     *  若音频编码格式采用可选音频编码--outputAudioConfig 参数填1，采用 1/2声道时，建议码率值是 80k/128k，可根据需要在此基础上调整
     */
    int nOutputAudioBitrate;       

    /** 混流输出音频编码格式，默认值为 0。可选值为 0--默认编码；1--可选编码
     *  0--默认编码 在低码率下，编码后的音质要明显好于 1--可选编码，在码率较大后，达到128kbps及以上，两种编码后的音质近乎相同
     *  1--可选编码 的优点在于低复杂性，能兼容更多的设备播放；但是目前经过 0--默认编码 编码后的音频不能正常播放的情况很少
     */      
    int nOutputAudioConfig;                     

    /** 用户自定义数据, 接收端通过媒体次要信息onRecvMediaSideInfo 接口回调 */ 
    const unsigned char * pUserData;            

    /** 用户自定义数据的长度 */
    int nLenOfUserData;                         

    /** 混流声道数，默认为单声道 */   
    int nChannels;                              

    /** 混流背景颜色，前三个字节为 RGB 颜色值，即 0xRRGGBBxx */
    int nOutputBackgroundColor;                

    /** 混流背景图，支持预设图片，如 (preset-id://xxx) */
    const char* pOutputBackgroundImage;         

    /** 是否开启音浪。true：开启，false：关闭 */  
    bool bWithSoundLevel;                       

    /** 扩展信息 */
    int nExtra;                                 

    /** 混流水印 */
    ZegoMixStreamWatermark* pOutputWatermark;   

    /** 混流输入为一条流时，是否混流；非必填。true：不对单流混流，混流输出的流属性与单流一致(分辨率，编码格式等)，混流配置中设置的分辨率等配置无效；false：混单流，混流服务器会对此单流重新编解码，混流输出的流属性与混流配置相同；若需要开启此功能，请先与即构技术支持联系*/
    bool bSingleStreamPassThrough;   

    /** 
     * 高级配置选项，适用于某些定制化的需求，格式 "config1=xxx;config2=xxx"， 请与即构技术支持联系了解可支持字段 
     */
    const char * pAdvancedConfig;          
};

• pInputStreamList 为输入流列表，列表中是 ZegoMixStreamInput 对象。表示流 ID 为 streamID 的流，在输出的混流中的布局位置，根据所需的输入流个数构建 N 个ZegoMixStreamInput 对象放入输入流列表。ZegoMixStreamInput结构如下：

struct ZegoMixStreamInput
{
    char szStreamID[ZEGO_MAX_COMMON_LEN];       /**< 混流 ID */
    struct
    {
        int top;
        int left;
        int bottom;
        int right;
    } layout;
    unsigned int uSoundLevelID;                 /**< 音浪ID，用于标识用户，注意大小是32位无符号数 */
    int nContentControl;                        /**< 推流内容控制，0表示音视频都要，2表示只要视频。默认值：0 */
    /**
     *  原点在左上角，top/bottom/left/right 定义如下：
     *
     *  (left, top)-----------------------
     *  |                                |
     *  |                                |
     *  |                                |
     *  |                                |
     *  -------------------(right, bottom)
     */
};

备注: ZegoMixStreamInput 的使用示例：假设指定某条流的左上角坐标为（50，300），右下角坐标为（200，450），这条流在最终的输出混流中的位置如下所示：

• pOutputList 为输出流列表，列表中是 ZegoMixStreamOutput 对象。表示流输出为 url 或者流名，如果需要将流推到 CDN 上，采用 url；不需要将流推到 CDN 上时，由调用者决定采用 url 或者流名。

注意： 如果需要配置单路流，输出流列表中只放一个 ZegoMixStreamOutput 对象；如果需要配置多路流，输出流列表中放N个ZegoMixStreamOutput 对象。

ZegoMixStreamOutput 结构如下：

struct ZegoMixStreamOutput
{
    bool isUrl;                             /**< 输出是否为流名或 URL*/ 

    char target[ZEGO_MAX_COMMON_LEN];       /**< isUrl为true: target 是完整 RTMP URL，isUrl为false: target 是流名 */      
};

• watermark 为混流水印，在输出的流中的指定位置上增加水印，其类型ZegoMixStreamWatermark结构如下：

struct ZegoMixStreamWatermark
{     
    char image[ZEGO_MAX_COMMON_LEN];       /**< 水印图片 */   

    struct
    {
        int top;
        int left;
        int bottom;
        int right;
    } layout;   

    /**
     *  原点在左上角，top/bottom/left/right 定义如下：
     *
     *  (left, top)-----------------------
     *  |                                |
     *  |                                |
     *  |                                |
     *  |                                |
     *  -------------------(right, bottom)
     */
};

3.3 开始混流

App 组装 ZegoMixStreamConfig 成功后，调用 MixStreamEx (const char *mixStreamID, const ZegoMixStreamConfig &config) 将混流配置发送至 Zego 混流服务器。 混流成功后，等待 IZegoMixStreamExCallback::OnMixStreamEx 回调。

注意： 当混流信息发生变更（例如，混流的输入流列表发生增减、调整混流视频输出码率等），开发者仍然需要在合适的时机调用本接口，更新Zego混流服务器上的混流配置。

混流API

namespace ZEGO
{
namespace MIXSTREAM
{         
    /**
     * 开始混流，支持一路或者多路混流输出
     * @param mixStreamID 混流ID
     * @param config 混流配置
     * @return 序列号， 如果 > 0 表示调用成功，而且这个返回值会和 OnMixStream 的参数 seq 一一匹配
     * @note 每次需要更新混流配置时，都可以调用此接口；通过返回的seq区分回调 ；混流ID，表示混流的唯一ID，调用方应该保证 taskID 的唯一性。如果 taskID 相同，服务端就认为是更新同一个混流。
     */
    ZEGOAVKIT_API int MixStreamEx (const char *mixStreamID, const ZegoMixStreamConfig &config);

}
}

备注： 如果开发者想混流纯音频数据，ZegoMixStreamConfig 的部分参数配置需要特殊处理：

1. 输入流 ZegoMixStreamInput 纯音频配置规则：top / left / bottom / right 不能全设置为 0，或全设置为 1。推荐配置：top = 0，left = 0，bottom = 1，right = 1。
2. ZEGO::MIXSTREAM::ZegoMixStreamConfig 纯音频配置规则：outputFps、outputBitrate 不能设置为 0。推荐配置：outputFps = 1，outputBitrate = 1，outputResolution = (1,1)

3.4 混流配置更新通知

混流请求发送成功后，调用者可在此回调中获取混流配置的结果及混流 ID。

混流配置更新通知API

zego-api-mix-stream.h

/**
 混流请求结果/配置更新回调

 @param result 混流结果
 @param pszMixStreamID 混流 ID
 @param seq 请求 seq
 */
 virtual void OnMixStreamEx (const AV::ZegoMixStreamResultEx &result, const char *pszMixStreamID, int seq) {}

• ZegoMixStreamResultEx为混流结果，其结构如下：

struct ZegoMixStreamResultEx
{     
    unsigned int uiErrorcode;         /**< 错误码，0 表示成功*/ 

    int nNonExistsStreamCount;        /**< 不存在的输入流个数 */ 

    const char* ppNonExistsStreamIDList [ZEGO_MAX_MIX_INPUT_COUNT];           /**< 不存在的输入流 ID 列表 */ 

    int nStreamInfoCount;             /**< 混流输出个数 */ 

    ZegoStreamInfo* pStreamInfoList;  /**< 混流输出列表 */    
}    

• pStreamInfoList是混流输出列表，列表中是ZegoStreamInfo对象，其结构如下：

// zego-api-defines.h
// ZEGO::AV::ZegoStreamInfo
struct ZegoStreamInfo
{     
    char szStreamID [ZEGO_MAX_COMMON_LEN];     /**< 流ID*/ 

    char szMixStreamID [ZEGO_MAX_COMMON_LEN];  /**< 混流ID*/ 

    char* arrRtmpURLs [ZEGO_MAX_URL_COUNT];    /**< RTMP URL列表*/ 

    unsigned int uiRtmpURLCount;         /**< RTMP URL 个数*/ 

    char* arrFlvRULs [ZEGO_MAX_URL_COUNT];   /**< Flv URL列表*/ 

    unsigned int uiFlvURLCount;        /**< Flv URL个数 */ 

    char* arrHlsURLs [ZEGO_MAX_URL_COUNT];           /**< Hls URL列表 */ 

    unsigned int uiHlsURLCount;             /**< Hls URL个数 */     
}    

3.5 获取混流前每条流的音量

由于混流会将多条流混成一条流，之前各条流的音量信息也会因此消失，如果要获取混流前各条流的音量信息，就需要做一些额外的设置。

3.5.1 修改混流配置

在推流方，在混流配置中增加两项设置, ZEGO::MIXSTREAM::ZegoMixStreamConfig 中的 bWithSoundLevel 用于标记混流时是否要附带上各条流的音量信息， ZEGO::MIXSTREAM::ZegoMixStreamInput 中的 uSoundLevelID 用于标记各条流，即用于标记推这条流的用户。

struct ZegoMixStreamConfig
{
    bool bWithSoundLevel;                       /**< 是否开启音浪。true：开启，false：关闭 */
};

struct ZegoMixStreamInput
{
    unsigned int uSoundLevelID;                 /**< 音浪ID，用于标识用户，注意大小是32位无符号数 */
};

3.5.2 设置音量信息回调

在拉流方，也需要设置对应的回调 IZegoSoundLevelInMixedStreamCallback，在回调中带回的 volume_list 里面就会有之前设置的流标记信息 soundLevelID 和音量信息 soundLevel。

注意: 这个回调是高频的同步回调，不要在回调中处理业务逻辑。

设置音量回调API

/**
 * 设置接收混流中的音量信息的回调
 * @param pCB pCallback 回调
 */
ZEGOAVKIT_API bool SetSoundLevelInMixedStreamCallback(IZegoSoundLevelInMixedStreamCallback* pCB);

• IZegoSoundLevelInMixedStreamCallback结构如下：

/** 混流中，显示发言者及音量大小的回调。每秒钟10次通知，不拉流没有通知 */
class IZegoSoundLevelInMixedStreamCallback
{
public:
    virtual void OnSoundLevelInMixedPlayStream(AV::SoundLevelInfo *volume_list, int list_size) = 0;

    virtual ~IZegoSoundLevelInMixedStreamCallback() {}
};

• SoundLevelInfo结构体如下：

struct ZegoMixStreamInput
{
    unsigned int soundLevelID;                 /**< 音浪ID，用于标识用户，注意大小是32位无符号数 */

    unsigned int soundLevel;                 /**< 音量level */
};

3.6 停止混流

停止混流也是调用 MixStreamEx (const char *mixStreamID, const ZegoMixStreamConfig &config) 实现。

操作步骤为：

1. 将之前的 config 对象中的 inputStreamList 置为空列表，即清空输入列表内容。outputList 设置为和开始或更新混流的一致。
2. 调用 MixStream(const AV::ZegoCompleteMixStreamConfig& config, int seq) 更新 Zego 混流服务器上的混流配置 config。

注意： 开始混流和停止混流使用的mixStreamID需要保持一致。

4 常见错误码