Merge pull request #27 from zhujingoy/v2.4.0

release v2.4.0

Release/include/cpp/CommonDef.h

@@ -72,6 +72,13 @@ namespace qiniu_v2 {
         SCALE_TO_FIT = 2,   // 缩放视频，使其填充满容器，可能导致拉伸变形 
     };
 
+    // 大小流对应配置
+    enum QNTrackProfile {
+        HIGH,
+        MEDIUM,
+        LOW,
+    };
+
     // 合流背景、水印配置参数 
     struct MergeLayer {
         string layer_url;       // http网络图片地址 
@@ -138,21 +145,37 @@ namespace qiniu_v2 {
         int         network_grade;                  // 网络质量  1 - 优 2 - 良 3 - 中等 4 - 差 
     };
 
-    typedef list<MergeOptInfo> MergeOptInfoList;
-    typedef list<UserInfo> UserInfoList;
-
     //自定义消息接收回调信息 
     struct  CustomMessage
     {
-        std::string msg_id;        //消息唯一id 
-        std::string msg_sendid;    //消息发送者的user id 
-        std::string msg_text;      //消息内容 
-        int         msg_stamp;     //消息时间戳 
+        std::string msg_id;        // 消息唯一id 
+        std::string msg_sendid;    // 消息发送者的user id 
+        std::string msg_text;      // 消息内容 
+        int         msg_stamp;     // 消息时间戳 
     };
-
-    typedef list<CustomMessage> CustomMessageList;
 
+    struct QNTrackLayerSubConfig {
+        QNTrackProfile mProfile;   // 当前 profile 
+        bool mChooseToSub;         // 是否需要切换为当前的 profile 
+        bool mMaintainLayer;       // 开启后，订阅端 profile 会随网络自动切换 （暂时不支持） 
+        bool mActive;              // 当前 profile 为生效状态 
+    };
+
+    // 单路转推配置信息，通过 SDK 将参数发送到服务端 
+    // 服务端按照指定的参数进行合流并推出 RTMP 流 
+    struct ForwardOptInfo
+    {
+        list<string>       track_id_list;       // 单路转推的音频和视频的 track id，audio_only 为 true 时，只存放音频的 track id 
+        bool               audio_only;          // 是否为是否只转推音频 
+        std::string        job_id;              // 单路转推任务 id，由客户端设置，不可为空，若已存在相同 id 的 job，返回错误 
+        std::string        publish_url;         // 转推地址 
+    };
+
+    typedef list<MergeOptInfo> MergeOptInfoList;
+    typedef list<UserInfo> UserInfoList;
+    typedef list<CustomMessage> CustomMessageList;
     typedef list<StatisticsReport> StatisticsReportList;
+    typedef list<QNTrackLayerSubConfig> LayerSubConfigList;
 
     class QNTrackInfo;
     typedef list<QNTrackInfo*> TrackInfoList;
@@ -185,7 +208,8 @@ namespace qiniu_v2 {
         string camera_device_id;                // 摄像头设备 Id，仅当 source_type 为 tst_Camera 时有效 
         TrackSourceType source_type = tst_Invalid;
         unsigned long long start_tp = 0;
-
+        LayerSubConfigList  sub_layer_list;        // 订阅端多流信息 
+        bool   multi_stream_enable  = false;       // 是否支持开启多流功能 
     public:
         // 创建视频 Track 实例，用于 PublishTracks 时使用，使用完成后调用 Release 进行释放 
         // @param camera_device_id_ 摄像头设备 Id，如果不是摄像头采集的话，可为空 
@@ -196,8 +220,9 @@ namespace qiniu_v2 {
         // @param max_fps_ 最大帧率 
         // @param max_bitrate_ 最大码率，单位：bps
         // @param type_ TrackSourceType 根据具体的数据源进行制定 
-        // @param is_master_ 是否为“主”流，默认为 false；
-        //  如果需要与 v1 的接口进行互通，则将其中某一路 Track 置为 true
+        // @param is_master_ 是否为“主”流，默认为 false 
+        //  如果需要与 v1 的接口进行互通，则将其中某一路 Track 置为 true 
+        // @param multi_stream_enable_  是否开启多流功能，默认为 false； 
         // @return 成功：TrackInfo 指针，否则返回空指针；返回值需由 Release 方法释放 
         static QNTrackInfo* CreateVideoTrackInfo(
             const string& camera_device_id_,
@@ -208,7 +233,8 @@ namespace qiniu_v2 {
             int   max_fps_,
             int   max_bitrate_,
             TrackSourceType type_,
-            bool  is_master_ = false
+            bool  is_master_ = false,
+            bool  multi_stream_enable_ = false
         );
 
         // 创建音频 Track 实例，用于 PublishTracks 时使用，返回值需由开发者调用 Release 进行释放
@@ -328,6 +354,17 @@ namespace qiniu_v2 {
             return start_tp;
         }
 
+        virtual LayerSubConfigList& GetLayerInfo()
+        {
+            return sub_layer_list;
+        }
+
+        virtual bool GetMultiStremState()
+        {
+            return multi_stream_enable;
+        }
+
+
     protected:
         QNTrackInfo() {}
         QNTrackInfo(const QNTrackInfo&) = delete;

Release/include/cpp/QNAudioInterface.h

@@ -207,7 +207,7 @@ namespace qiniu_v2 {
         // @brief 测试阶段，慎用 
         virtual int EnableAec(bool enable_) = 0;
 
-        //开启软件回音消除功能，在有些机器上效果不明显，需要强制降采样为16K才有效果， 
+        //开启软件回音消除功能，在有些机器上效果不明显，需要强制降采样为 16K 才有效果， 
         //开启可能会降低音质，内部是默认开启，如果对回音消除没有需求，但对音质有需求，需要禁用。 
         // @param enable_ 是否开启， true or false 
         // @return 目前阶段全部返回 0 

Release/include/cpp/QNRoomInterface.h

@@ -126,11 +126,65 @@ namespace qiniu_v2 {
                 const TrackInfoList& track_list_
             ) = 0;
 
-            //远端音视频质量参数回调 
+            // 远端音视频质量参数回调 
             virtual void OnRemoteStatisticsUpdated(
                 const StatisticsReportList& statistics_list_
             ) = 0;
 
+            // 创建合流任务结果反馈 
+            // @param job_id_ 合流任务 id 
+            // @param error_code_ 0：成功， 非 0： 失败 
+            // @param error_str_ error_code_ 非 0 时的错误描述信息 
+            virtual void OnCreateMergeResult(
+                const std::string& job_id_,
+                int error_code_,
+                const std::string& error_str_
+            ) = 0;
+
+            // 停止合流任务结果反馈 
+            // @param job_id_ 合流任务 id 
+            // @param job_iid_ iid 用于区分 id 相同时的情况，可以不用处理此字段 
+            // @param error_code_ 0：成功， 非 0： 失败 
+            // @param error_str_ error_code_ 非 0 时的错误描述信息 
+            virtual void OnStopMergeResult(
+                const std::string& job_id_,
+                const std::string& job_iid_,
+                int error_code_,
+                const std::string& error_str_
+            ) = 0;
+
+            // 切换远端 Tracks 大小流结果异步通知 
+            // @param error_code_ 0：切换成功；其它请参考错误码列表 
+            // @param error_str_ 当 error_code_ 非 0 时的错误描述信息 
+            // @param track_list_ 切换 profile 的 Tracks 列表 
+            virtual void OnSetSubscribeTracksProfileResult(
+                int error_code_,
+                const string& error_str_,
+                const TrackInfoList& track_list_
+            ) = 0;
+
+            // 创建单路转推任务结果反馈 
+            // @param job_id_ 单路转推的任务 id 
+            // @param error_code_ 0：成功， 非 0： 失败 
+            // @param error_str_ error_code_ 非 0 时的错误描述信息 
+            virtual void OnCreateForwardResult(
+                const std::string& job_id_,
+                int error_code_,
+                const std::string& error_str_
+            ) = 0;
+
+            // 停止单路转推任务结果反馈 
+            // @param job_id_ 单路转推的任务 id 
+            // @param job_iid_ iid 用于区分 id 相同时的情况，可以不用处理此字段 
+            // @param error_code_ 0：成功， 非 0： 失败 
+            // @param error_str_ error_code_ 非 0 时的错误描述信息 
+            virtual void OnStopForwardResult(
+                const std::string& job_id_,
+                const std::string& job_iid_,
+                int error_code_,
+                const std::string& error_str_
+            ) = 0;
+
         protected:
             virtual ~QNRoomListener() {}
         };
@@ -238,6 +292,9 @@ namespace qiniu_v2 {
         virtual int MuteVideo(const string& track_id_, bool mute_flag_) = 0;
 
         // 创建自定义合流任务
+        // 当有合流及单路转推切换需求时，合流必须使用自定义合流，流地址一样时切换会有抢流现象，
+        // 因此需要拼接 "?serialnum=xxx" 决定流的优先级，serialnum 值越大，优先级越高。
+        // 切换成功后务必关闭之前的任务，否则会出现一路任务持续计费的情况
         // @param job_desc: 合流任务配置结构
         // @param merge_background: 合流背景图
         // @param merge_watermark: 合流水印图
@@ -269,13 +326,30 @@ namespace qiniu_v2 {
         // @return 用户 Id
         virtual const string& GetLocalUserId() = 0;
 
-        //发送自定义消息 
-        //@param users 目标用户列表，为空时则给房间中的所有人发消息（注意：不能填null） 
-        //@param messageId 消息ID，可以为空（注意：不能填null） 
-        //@param message 消息内容（注意：不能填null，不支持发送空消息，入参前需转成utf8格式） 
+        // 发送自定义消息 
+        // @param users 目标用户列表，为空时则给房间中的所有人发消息（注意：不能填 null） 
+        // @param messageId 消息 ID，可以为空（注意：不能填 null） 
+        // @param message 消息内容（注意：不能填 null，不支持发送空消息，入参前需转成 utf8 格式） 
         // @return 0:操作成功；其它请参考错误码列表。 
         virtual int SendCustomMessage(const list<string>& users_list_, const string& message_id, const string& message_) = 0;
 
+        // 切换订阅流的 profile 
+        // @param trackInfoList 需要切换 profile 的 tracks 链表 
+        virtual int UpdateSubscribeTracks(TrackInfoList& trackInfo_list_) = 0;
+
+        // 创建单路转推任务
+        // 当有合流及单路转推切换需求时，合流必须使用自定义合流，流地址一样时切换会有抢流现象，
+        // 因此需要拼接 "?serialnum=xxx" 决定流的优先级， serialnum 值越大，优先级越高。
+        // 切换成功后务必关闭之前的任务，否则会出现一路任务持续计费的情况
+        // @param job_des 单路转推任务配置结构 
+        // @return 0:操作成功，具体转推结果请通过观看旁路直播进行查看 
+        virtual int CreateForwardJob(const ForwardOptInfo& job_des) = 0;
+
+        // 停止单路转推任务
+        // @param job_id 单路转推任务 id 
+        // @return 0:操作成功，具体转推结果请通过观看旁路直播进行查看 
+        virtual int StopForwardJob(const string& job_id) = 0;
+
     protected:
         virtual ~QNRoomInterface() {}
     };

Release/include/cpp/QNVideoInterface.h

@@ -375,14 +375,14 @@ namespace qiniu_v2
         // @return 成功返回 0，否则请参考错误码列表 
         virtual int InputH264Frame(H264Nal** nals_ptr_, unsigned int nals_size_, uint8_t is_key_frame_) = 0;
 
-        // 原始帧处理功能接口：裁剪和缩放，设置参数要求如下，如果设置不正确，则输出原始图像，OnVideoFrame回调接口中会有输出宽高体现 
+        // 原始帧处理功能接口：裁剪和缩放，设置参数要求如下，如果设置不正确，则输出原始图像，OnVideoFrame 回调接口中会有输出宽高体现 
         // @param src_capturer_source 数据源类型，目前只支持摄像头采集数据 
-        // @param mode 裁剪还是缩放 
+        // @param mode 裁剪/缩放 
         // @param enable 开/关 
         // @param cropX 开始裁减的 X 坐标点，原点为左上角，必须落在原图之内 
         // @param cropY 开始裁减的 Y 坐标点，原点为左上角，必须落在原图之内 
-        // @param dstWidth 目标图像宽度，必须为4的整数倍，如果是裁剪模式，cropX和cropY，裁剪图像必须在原始图像之内 
-        // @param dstHeight 目标图像高度，必须为4的整数倍，如果是裁剪模式，cropX和cropY，裁剪图像必须在原始图像之内 
+        // @param dstWidth 目标图像宽度，必须为 4 的整数倍，如果是裁剪模式，cropX 和 cropY，裁剪图像必须在原始图像之内 
+        // @param dstHeight 目标图像高度，必须为 4 的整数倍，如果是裁剪模式，cropX 和 cropY，裁剪图像必须在原始图像之内 
         virtual void SetCropAndScale(
             qiniu_v2::TrackSourceType src_capturer_source,
             FrameProcessMode mode,

ReleaseNotes/release-notes-2.4.0.md

@@ -0,0 +1,27 @@
+# QNRTCWin Release Notes for 2.4.0
+
+## 简介
+QNRTCWin 是七牛云推出的一款适用于 Windows7 及以上系统平台的实时音视频 SDK，提供了包含音视频通话、屏幕分享、数据导入、监听等功能，适用于各种直播、教育、医疗等场景，并提供了灵活的开发接口，支持高度定制以及二次开发。
+
+## 注意
+
+自 2.0.0 后，我们为了提高用户阅读文档的体验，使用了新的文档站（老文档地址继续保留），新文档站地址 https://doc.qnsdk.com/rtn
+
+体验新版 Demo 请打开 Demo 后点击 “体验新版本（多 Track）” 即可体验
+
+## 功能
+  - 增加大小流功能
+  - 增加单路转推
+
+## 缺陷
+  - 修复 auth res 信令过长导致解析失败的问题
+  - 修复初始化采集失败导致的奔溃问题
+
+## 注意事项
+- 2.0.0 以前的接口文件移动到了 qiniu 目录下
+- 2.1.0 以后不再提供 Debug 版本的动态库
+- [Demo 源码 GitHub 地址](https://github.com/pili-engineering/QNRTC-Windows)
+- [Demo 体验下载地址](https://sdk-release.qnsdk.com/Windows-RTC-2.4.0.zip) 
+
+## 问题反馈 
+当你遇到任何问题时，可以通过在 GitHub 的 repo 提交 `issues` 来反馈问题，请尽可能的描述清楚遇到的问题，如果有错误信息也一同附带，并且在 ```Labels``` 中指明类型为 bug 或者其他。 [通过这里查看已有的 issues 和提交 bug](https://github.com/pili-engineering/QNRTC-Windows)