@rongcloud/plugin-rtc 5.2.2 → 5.3.1-alpha.1

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 /*
- * RCRTC - v5.2.2
- * CommitId - cbd066a7185af8c1b56ef6bf88f1332ec9444daa
- * Thu Nov 25 2021 17:52:32 GMT+0800 (China Standard Time)
+ * RCRTC - v5.3.1-alpha.1
+ * CommitId - a0420f5d363442c8159ff21bc21d606ff601abcb
+ * Thu Jan 20 2022 11:04:43 GMT+0800 (China Standard Time)
  * ©2020 RongCloud, Inc. All rights reserved.
  */
-import { EventEmitter, LogLevel, RTCMode, IRuntime, RTCPluginContext, IServerRTCRoomEntry, IJoinRTCRoomData, IReceivedMessage, KVString, RTCJoinType, IRTCJoinedInfo, IPluginGenerator } from '@rongcloud/engine';
+import { EventEmitter, LogLevel, RTCMode, IRuntime, RTCPluginContext, IServerRTCRoomEntry, IReceivedMessage, ErrorCode, IJoinRTCRoomData, KVString, RTCJoinType, IRTCJoinedInfo, IPluginGenerator } from '@rongcloud/engine';
 export { RTCJoinType } from '@rongcloud/engine';
 
 /**
@@ -84,7 +84,9 @@ declare enum RCRTCCode {
     /** 加入 RTC 房间 joinTYype 为 1 时，当前有其他端在房间时的应答码 */
     SIGNAL_JOIN_RTC_ROOM_REFUSED = 53028,
     /** 设置音频输出设备时，无权限使用请求的设备 */
-    NO_PERMISSION_TO_USE_REQUESTED_DEVICE = 53029
+    NO_PERMISSION_TO_USE_REQUESTED_DEVICE = 53029,
+    /** 方法在 PK 房间上不可用 */
+    THE_FUNCTION_IS_DISABLED_IN_PKROOM = 53030
 }
 
 /**
@@ -910,6 +912,76 @@ interface IAudioLevelChangeHandler {
 declare type RoomData = {
     [userId: string]: IPublishedResource[];
 };
+/**
+ * 业务层发起连麦、响应连麦可选参数定义
+ */
+interface IReqResPKOptions {
+    autoMix?: boolean;
+    extra?: string;
+}
+interface IPKInviterBaseInfo {
+    /**
+     * 邀请者房间 ID
+     */
+    inviterRoomId: string;
+    /**
+     * 邀请者用户 ID
+     */
+    inviterUserId: string;
+}
+interface IPKInviteeBaseInfo {
+    /**
+     * 被邀请者房间 ID
+     */
+    inviteeRoomId: string;
+    /**
+     * 被邀请者用户 ID
+     */
+    inviteeUserId: string;
+}
+/**
+ * 业务层监听收到连麦邀请、取消连麦的字段
+ */
+interface IPKInviteInfo extends IPKInviterBaseInfo {
+    /**
+     * 邀请额外信息
+     */
+    extra?: string;
+}
+/**
+ * 业务层监听收到连麦应答的字段
+ */
+interface IPKInviteAnswerInfo extends IPKInviterBaseInfo, IPKInviteeBaseInfo {
+    /**
+     * 是否同意邀请
+     */
+    agree: boolean;
+    /**
+     * 响应额外信息
+     */
+    extra?: string;
+}
+/**
+ * 业务层监听收到连麦结束的字段
+ */
+interface IPKEndInfo {
+    /**
+     * 发起结束的房间 ID
+     */
+    endRoomId: string;
+    /**
+     * 发起结束的用户 ID
+     */
+    endUserId: string;
+}
+/**
+ * 观众加房间返回给客户的 CDN 信息
+ */
+interface IJoinResCDNInfo {
+    resolution?: RCResolution;
+    fps?: RCFrameRate;
+    CDNEnable?: boolean;
+}
 
 declare enum RCInnerCDNPushMode {
     AUTOMATIC = 0,
@@ -999,7 +1071,7 @@ interface IExchangeReqBody {
         /**
          * 是否默认合流
          */
-        automix: boolean;
+        autoMix: boolean;
         /**
          * 房间 Id 对应的 SessionId
          */
@@ -1686,9 +1758,21 @@ declare class RCAudienceLivingRoom {
     private readonly _joinResData;
     readonly _livingType: RCLivingType;
     private readonly _service;
+    /**
+     * 主播列表
+     */
     private _roomAnchorList;
+    /**
+     * 合流、分流资源
+     */
     private _roomRes;
+    /**
+     * 主播分流资源
+     */
     private _roomAnchorRes;
+    /**
+     * 合流、分流 remoteTracks
+     */
     private _remoteTracks;
     private _appListener;
     private _pc;
@@ -1709,8 +1793,12 @@ declare class RCAudienceLivingRoom {
     private _CDNUris;
     constructor(_context: RTCPluginContext, _runtime: IRuntime, _initOptions: IRCRTCInitOptions, _roomId: string, _joinResData: {
         token: string;
-        kvEntries?: IServerRTCRoomEntry[];
+        kvEntries: IServerRTCRoomEntry[];
     }, _livingType: RCLivingType);
+    /**
+     * 解析服务端返回的 KV 数据，赋值 room 内数据
+     */
+    private _setInitData;
     protected _assertRoomDestroyed(): RCRTCCode | undefined;
     /**
      * @description 信令数据处理
@@ -1769,8 +1857,7 @@ declare class RCAudienceLivingRoom {
     private _diffCDNUris;
     /**
      * 获取 CDN 资源对应的拉流地址
-     * 首次获取 CDNPlayUrl 时，需传入 url，
-     * 业务层调用时使用内存中 _CDNUris 的 url，无 _CDNUris 时说明观众端未赋值过 _CDNUris
+     * _CDNUris 无 url 时，说明未开启 CDN 推送
      * @returns CDNPlayUrl
      */
     private _getCDNPlayUrl;
@@ -1864,6 +1951,26 @@ declare class RCAudienceLivingRoom {
      * @returns
      */
     getRemoteTracks(): RCRemoteTrack[];
+    /**
+     * 获取远端 RTC tracks
+     */
+    getRemoteRTCTracks(): RCRemoteTrack[];
+    /**
+     * 获取远端 MCU tracks
+     */
+    getRemoteMCUTracks(): RCRemoteTrack[];
+    /**
+     * 获取房间内 CDN 信息
+     */
+    getCDNInfo(): {
+        resolution: RCResolution;
+        fps: RCFrameRate;
+        CDNEnable: boolean | undefined;
+    } | {
+        CDNEnable: boolean;
+        resolution?: undefined;
+        fps?: undefined;
+    };
 }
 
 /**
@@ -1984,6 +2091,171 @@ declare class RCRTCPeerConnection extends EventEmitter {
     clearReTryExchangeTimer(): void;
 }
 
+declare type IOnRecvPKMsg = (msg: IReceivedMessage) => void;
+interface IRoomPKEventListener {
+    /**
+     * 收到连麦邀请
+     */
+    onRequestJoinOtherRoom: (info: IPKInviteInfo) => {};
+    /**
+     * 收到取消连麦邀请
+     */
+    onCancelRequestOtherRoom: (info: IPKInviteInfo) => {};
+    /**
+     * 收到连麦 PK 请求响应结果
+     */
+    onResponseJoinOtherRoom: (info: IPKInviteAnswerInfo) => {};
+    /**
+     * 收到 PK 结束
+     */
+    onFinishOtherRoom: (info: IPKEndInfo) => {};
+}
+declare class RCLivingPKHandler {
+    private readonly _context;
+    private readonly _runtime;
+    private readonly _service;
+    private readonly _initOptions;
+    /**
+     * 主直播房间
+     */
+    private readonly _mainLivingRoom;
+    private readonly _registerPKMsgListener;
+    /**
+     * 加入 PK 房间回调
+     */
+    private readonly _onJoinedPKRoom;
+    /**
+     * 退出 PK 房间回调
+     */
+    private readonly _onLeavePKRoom;
+    /**
+     * PK 邀请超时时间，默认 30s
+     */
+    private readonly _inviteTimeout;
+    /**
+     * PK 房间信息
+     */
+    private _PKInfo;
+    private _appListener;
+    private _mainRoomId;
+    /**
+     * 跨房间连麦加入的 PK 房间
+     */
+    private _joinedPKRooms;
+    constructor(_context: RTCPluginContext, _runtime: IRuntime, _service: RCMediaService, _initOptions: IRCRTCInitOptions, 
+    /**
+     * 主直播房间
+     */
+    _mainLivingRoom: RCLivingRoom, _registerPKMsgListener: (listener: IOnRecvPKMsg) => void, 
+    /**
+     * 加入 PK 房间回调
+     */
+    _onJoinedPKRoom: (roomId: string, room: RCLivingRoom) => void, 
+    /**
+     * 退出 PK 房间回调
+     */
+    _onLeavePKRoom: (roomId: string) => void);
+    private _callAppListener;
+    /**
+     * 收到连麦邀请
+     */
+    private _onInvite;
+    /**
+     * 收到取消连麦
+     */
+    private _onCancelInvite;
+    private _onInviteTimeout;
+    /**
+     * 收到响应连麦
+     */
+    private _onInviteAnswer;
+    /**
+     * 收到连麦结束
+     */
+    private _onPKEnd;
+    /**
+     * 处理跨房间连麦相关消息
+     */
+    private _onRecvPKMsg;
+    /**
+     * 注册跨房间连麦监听事件
+     */
+    registerRoomPKEventListener(listener: IRoomPKEventListener): void;
+    /**
+     * 发起跨房间连麦请求
+     * @param inviteeRoomId 被邀请者所处的房间 roomId
+     * @param inviteeUserId 被邀请者 userId
+     * @param options.autoMix 是否要把邀请者发布的资源，合并到被邀请者房间内的 MCU 流中
+     * @param options.extra 拓展字段，可随邀请连麦消息透传给被邀请者
+     */
+    requestJoinOtherRoom(inviteeRoomId: string, inviteeUserId: string, options?: IReqResPKOptions): Promise<{
+        code: RCRTCCode | ErrorCode;
+    }>;
+    /**
+     * 取消跨房间连麦请求
+     * @param inviteeRoomId 被邀请者所处的房间 roomId
+     * @param inviteeUserId 被邀请者 userId
+     * @param extra 附加信息，可随取消邀请连麦消息透传给被邀请者
+     */
+    cancelRequestJoinOtherRoom(inviteeRoomId: string, inviteeUserId: string, extra?: string): Promise<{
+        code: RCRTCCode | ErrorCode;
+    }>;
+    /**
+     * 响应跨房间连麦请求
+     * @param inviterRoomId 邀请者所处的房间 roomId
+     * @param inviterUserId 邀请者 userId
+     * @param agree 是否同意连麦
+     * @param options.autoMix 是否要把被邀请者发布的资源，合并到邀请者房间内的 MCU 流中
+     * @param options.extra 附加信息，可随响应连麦消息透传给邀请者
+     */
+    responseJoinOtherRoom(inviterRoomId: string, inviterUserId: string, agree: boolean, options?: IReqResPKOptions): Promise<{
+        code: RCRTCCode | ErrorCode;
+    }>;
+    /**
+     * 结束跨房间连麦
+     * @param roomId 需要结束连麦的房间 roomId
+     */
+    private _quitRoomPK;
+    private _relaseCrtRoom;
+    /**
+     * 加入副直播房间
+     * @roomId 副房间的 roomId
+     */
+    joinOtherRoom(roomId: string): Promise<{
+        code: RCRTCCode;
+        room?: RCLivingRoom;
+        userIds?: string[];
+        tracks?: RCRemoteTrack[];
+        CDNEnable?: boolean;
+    }>;
+    /**
+     * 退出副房间
+     * @param room 要退出的副房间的 room 实例
+     * @param isQuitPK 是否要结束连麦
+     */
+    leaveOtherRoom(room: RCLivingRoom, isQuitPK?: boolean): Promise<{
+        code: RCRTCCode;
+    }>;
+    /**
+     * 获取连麦信息
+     * @param roomId 连麦房间的 roomId
+     */
+    getPKInfo(roomId: string): {
+        inviteSessionId: string;
+        inviterRoomId: string;
+        inviterUserId: string;
+        inviterUserAutoMix?: boolean | undefined;
+        inviteeRoomId: string;
+        inviteeUserAutoMix?: boolean | undefined;
+    };
+    /**
+     * 获取已加入的副房间
+     */
+    getJoinedPKRooms(): {
+        [roomId: string]: RCLivingRoom;
+    };
+}
+
 /**
  * 房间抽象基类
  */
@@ -1995,6 +2267,7 @@ declare abstract class RCAbstractRoom {
     protected readonly _service: RCMediaService;
     protected readonly _initOptions: IRCRTCInitOptions;
     private readonly _ntfClearRoomItem;
+    protected _isMainRoom?: boolean | undefined;
     /**
      * 房间资源数据
      */
@@ -2006,7 +2279,7 @@ declare abstract class RCAbstractRoom {
     /**
      * 已订阅参数
      */
-    private readonly _subscribedList;
+    protected readonly _subscribedList: ISubscribeAttr[];
     /**
      * 房间保活 rtcPing
      */
@@ -2022,7 +2295,7 @@ declare abstract class RCAbstractRoom {
     /**
      * PeerConnection 连接实例
      */
-    private readonly _pc;
+    protected readonly _pc: RCRTCPeerConnection;
     private _destroyed;
     /**
      * 北极星上报实例
@@ -2032,7 +2305,7 @@ declare abstract class RCAbstractRoom {
      * 音量上报实例
      */
     private _audioLevelReport;
-    constructor(_context: RTCPluginContext, _runtime: IRuntime, _roomId: string, data: IJoinRTCRoomData, _roomMode: RTCMode, _service: RCMediaService, _initOptions: IRCRTCInitOptions, _ntfClearRoomItem: Function, isUpgrade?: boolean);
+    constructor(_context: RTCPluginContext, _runtime: IRuntime, _roomId: string, data: IJoinRTCRoomData, _roomMode: RTCMode, _service: RCMediaService, _initOptions: IRCRTCInitOptions, _ntfClearRoomItem: Function, isUpgrade?: boolean, _isMainRoom?: boolean | undefined);
     private _initRemoteTracks;
     private _handlePingResult;
     /**
@@ -2208,6 +2481,14 @@ declare abstract class RCAbstractRoom {
         liveUrl?: string;
     }>;
     private __publish;
+    /**
+     * 获取跨房间连麦需携带参数 pushOtherRooms 的值
+     */
+    protected _getPushOtherRoomsParams(): {
+        roomId: string;
+        sessionId: string;
+        autoMix: boolean;
+    }[] | undefined;
     /**
      * ice 断线后，尝试重新走 exchange
      */
@@ -2324,6 +2605,18 @@ declare abstract class RCAbstractRoom {
      * 销毁远端资源
      */
     private _removeRemoteTracks;
+    /**
+     * 存储连麦监听事件
+     */
+    private _onRecvPKMsg;
+    /**
+     * 注册 PK 业务监听方法
+     */
+    protected _registerPKMsgListener(listener: IOnRecvPKMsg | null): void;
+    /**
+     * 退出 PK 房间
+     */
+    protected _quitAllPKRoom(): void;
 }
 
 /**
@@ -2501,18 +2794,37 @@ declare class RCMCUConfigBuilder {
  */
 declare class RCLivingRoom extends RCAbstractRoom {
     private _livingType;
+    /**
+     * 是否是主房间
+     */
+    protected _isMainRoom: boolean;
     readonly _mcuConfigBuilder: RCMCUConfigBuilder;
     /**
      * cdn_uris 信令扩散数据
      */
     private _CDNUris;
     private _CDNEnable;
-    constructor(context: RTCPluginContext, runtime: IRuntime, roomId: string, data: IJoinRTCRoomData, service: RCMediaService, initOptions: IRCRTCInitOptions, clientEvent: Function, _livingType: RCLivingType, isUpgrage?: boolean);
+    /**
+     * 跨房间连麦管理器
+     */
+    private readonly _roomPKHandler;
+    constructor(context: RTCPluginContext, runtime: IRuntime, roomId: string, data: IJoinRTCRoomData, service: RCMediaService, initOptions: IRCRTCInitOptions, clientEvent: Function, _livingType: RCLivingType, isUpgrage: boolean | undefined, 
+    /**
+     * 是否是主房间
+     */
+    _isMainRoom: boolean);
+    /**
+     * resourceId 有效性验证
+     * @param resourceId
+     */
+    protected _isValidResourceId(resourceId: string): boolean;
     getLivingType(): RCLivingType;
     /**
      * 获取 MCU 配置构建对象
      */
-    getMCUConfigBuilder(): RCMCUConfigBuilder;
+    getMCUConfigBuilder(): RCMCUConfigBuilder | {
+        code: RCRTCCode;
+    };
     /**
      * 接收 MCU 配置并向 MediaServer 提交
      * @param data
@@ -2579,6 +2891,30 @@ declare class RCLivingRoom extends RCAbstractRoom {
      * @returns boolean
      */
     __getCDNPushMode(): RCInnerCDNPushMode | undefined;
+    /**
+     * 加入 PK 房间回调
+     */
+    private _onJoinedPKRoom;
+    /**
+     * 离开 PK 房间后，如果参与过连麦，pushOtherRooms 需去掉退出的连麦房间配置，重新和 mediaServer 交互
+     */
+    private _onLeavePKRoom;
+    /**
+     * 携带 pushOtherRooms 与 mediaServer 重新交互
+     */
+    private _exchangeWithPushOtherRoom;
+    /**
+     * 获取 PK 业务处理器
+     * @since version 5.3.0
+     */
+    getRoomPKHandler(): {
+        code: RCRTCCode;
+        roomPKHandler?: RCLivingPKHandler;
+    };
+    /**
+     * 退出所有连麦房间
+     */
+    protected _quitAllPKRoom(): void;
 }
 
 /**
@@ -2665,6 +3001,10 @@ declare class RCRTCClient {
     private readonly _service;
     constructor(_context: RTCPluginContext, _runtime: IRuntime, _options: IRCRTCInitOptions);
     private _handleMessage;
+    /**
+     * 获取加入的连麦房间
+     */
+    private _getJoinedPKRoomList;
     /**
      * 获取当前用户 Id，若 IM 未连接，这返回 `''`
      * @returns
@@ -2753,7 +3093,7 @@ declare class RCRTCClient {
      * @param tag 屏幕共享视轨数据标识
      * @param options
      * @description
-     * 支持 Electron 平台下通过制定 `chromeMediaSrouceId` 的方式获取屏幕共享视频。
+     * 支持 Electron 平台下通过制定 `chromeMediaSourceId` 的方式获取屏幕共享视频。
      * 参考：https://www.electronjs.org/docs/api/desktop-capturer
      */
     createScreenVideoTrack(tag?: string, options?: IScreenVideoProfile): Promise<{
@@ -2810,6 +3150,10 @@ declare class RCRTCClient {
     joinLivingRoomAsAudience(roomId: string, livingType: RCLivingType): Promise<{
         room?: RCAudienceLivingRoom;
         code: RCRTCCode;
+        userIds?: string[];
+        RTCTracks?: RCRemoteTrack[];
+        MCUTracks?: RCRemoteTrack[];
+        CDNUris?: IJoinResCDNInfo;
     }>;
     /**
      * 观众退出并销毁当前房间实例，退出后该房间的所有方法将不可用
@@ -2824,6 +3168,8 @@ declare class RCRTCClient {
     upgradeToAnchorRoom(room: RCAudienceLivingRoom): Promise<{
         room?: RCLivingRoom;
         code: RCRTCCode;
+        userIds?: string[];
+        tracks?: RCRemoteTrack[];
     }>;
     /**
      * 降级为观众房间
@@ -2832,6 +3178,10 @@ declare class RCRTCClient {
     downgradeToAudienceRoom(room: RCLivingRoom): Promise<{
         room?: RCAudienceLivingRoom;
         code: RCRTCCode;
+        userIds?: string[];
+        RTCTracks?: RCRemoteTrack[];
+        MCUTracks?: RCRemoteTrack[];
+        CDNUris?: IJoinResCDNInfo;
     }>;
     /**
      * 获取在房间内用户信息
@@ -2890,4 +3240,4 @@ declare const helper: {
     ifSupportScreenShare: typeof ifSupportScreenShare;
 };
 
-export { BackgroundPictureFillMode, ICameraVideoProfile, IMCUOutputConfig, IMCUOutputVideoConfig, IMicphoneAudioProfile, IPublishAttrs, IPublishedResource, IRCCandidatePairStat, IRCRTCInitOptions, IRCRTCReportListener, IRCRTCStateReport, IRCTrackStat, IRoomEventListener, ISubscribeAttr, IVideoProfile, MixLayoutMode, MixVideoRenderMode, RCAbstractRoom, RCAudienceClient, RCAudienceLivingRoom, RCCameraVideoTrack, RCFrameRate, RCInnerCDNPullIsHttps, RCInnerCDNPullKind, RCKickReason, RCLivingRoom, RCLivingType, RCLocalAudioTrack, RCLocalFileAudioTrack, RCLocalFileTrack, RCLocalFileVideoTrack, RCLocalTrack, RCLocalVideoTrack, RCMCUConfigBuilder, RCMediaType, RCMicphoneAudioTrack, RCRTCClient, RCRTCCode, RCRTCLiveRole, RCRTCPingResult, RCRTCRoom, RCRemoteAudioTrack, RCRemoteTrack, RCRemoteVideoTrack, RCResolution, RCScreenVideoTrack, RCTag, RCTrack, device, helper, installer };
+export { BackgroundPictureFillMode, ICameraVideoProfile, IMCUOutputConfig, IMCUOutputVideoConfig, IMicphoneAudioProfile, IPKEndInfo, IPKInviteAnswerInfo, IPKInviteInfo, IPublishAttrs, IPublishedResource, IRCCandidatePairStat, IRCRTCInitOptions, IRCRTCReportListener, IRCRTCStateReport, IRCTrackStat, IReqResPKOptions, IRoomEventListener, IRoomPKEventListener, ISubscribeAttr, IVideoProfile, MixLayoutMode, MixVideoRenderMode, RCAbstractRoom, RCAudienceClient, RCAudienceLivingRoom, RCCameraVideoTrack, RCFrameRate, RCInnerCDNPullIsHttps, RCInnerCDNPullKind, RCKickReason, RCLivingRoom, RCLivingType, RCLocalAudioTrack, RCLocalFileAudioTrack, RCLocalFileTrack, RCLocalFileVideoTrack, RCLocalTrack, RCLocalVideoTrack, RCMCUConfigBuilder, RCMediaType, RCMicphoneAudioTrack, RCRTCClient, RCRTCCode, RCRTCLiveRole, RCRTCPingResult, RCRTCRoom, RCRemoteAudioTrack, RCRemoteTrack, RCRemoteVideoTrack, RCResolution, RCScreenVideoTrack, RCTag, RCTrack, device, helper, installer };