larksr_websdk 3.2.1 → 3.2.6

package/README.md

@@ -1,6 +1,6 @@
 # LarkSR WebClient 接入 SDK
 
-SDK 适用于自定义 LarkSR 云渲 Web 客户端的二次开发，自定义 UI 和操作逻辑等。有较高的灵活性。
+SDK 适用于自定义 LarkSR 云渲 Web 客户端或者自定义 VR 监控画面客户端的二次开发，自定义 UI 和操作逻辑等。有较高的灵活性。
 
 对于不需要二次开发，或者简单修改，可以参照使用 iframe 的接入方式，将标准 Web 客户端网页嵌入到系统中去。
 
@@ -12,6 +12,15 @@ SDK 适用于自定义 LarkSR 云渲 Web 客户端的二次开发，自定义 UI
 
 [即刻体验](https://www.pingxingyun.com/experience/experience.html)
 
+SDK 功能包括:
+
+* 处理后台请求和接口
+* 云渲染视频拉取显示
+* 输入方式包括鼠标，键盘，手柄，触摸, 并提供输入接口和控制内部输入方式开启接口
+* 显示和缩放模式，默认以浏览器视口为容器大小, 视频窗口保留宽高比并且不会拉伸完全显示。并可配置
+* 处理全屏模式，并可配置
+* 自动处理横屏模式，手机端强制横屏模式，并可配置
+
 ## 快速接入
 
 ### 安装
@@ -30,22 +39,32 @@ npm i larksr_websdk
 
 ### 使用
 
+使用前应准备好
+
+1. Lark 服务器前台可访问的地址, 如：http://222.128.6.137:8181/
+2. SDK 授权码，联系 business@pingxingyun.com 获取,注意是 SDK 本身的授权码，不是服务器上的授权
+3. 系统中获取的应用 ID,如 http://222.128.6.137:8181/ 系统下的 879408743551336448
+
 ```javascript
 var client;
 // 直接调用进入应用接口创建实例，自动配置连接云端资源
-larksr_websdk.LarkSR.CreateLarkSRClientFromeAPI({
-        // 设置挂在显示的元素
+larksr_websdk.CreateLarkSRClientFromeAPI({
+        // 设置挂载显示的元素
+        // 注意*不要*设置为 document.documentElement
         rootElement: document.getElementById('container'),
-        // 服务器地址
-        serverAddress: "http://222.128.6.137:8181/",
+        // 服务器地址,实际使用中填写您的服务器地址
+        // 如：http://222.128.6.137:8181/
+        serverAddress: "Lark 服务器前台地址",
         // 授权码
         authCode: '您的 SDK 授权码',
-        loadingBgUrl: 'https://home-obs.pingxingyun.com/homePage_4_0/bg.jpg',
+        // 测试载入背景图
+        // loadingBgUrl: 'https://home-obs.pingxingyun.com/homePage_4_0/bg.jpg',
     }, {
         // 要使用的云端资源的应用 ID，从后云雀后台接口获取
         // 参考查询应用一栏文档
         // https://www.pingxingyun.com/online/api3_2.html?id=476
-        appliId: "879408743551336448"
+        // 如 222.128.6.137:8181 系统下的 879408743551336448 应用
+        appliId: "应用ID"
     })
     .then((res) => {
         console.log('enter appli success', res);
@@ -60,18 +79,16 @@ larksr_websdk.LarkSR.CreateLarkSRClientFromeAPI({
     });
 ```
 
-SDK 加载成功之后，导出接口在全局对象 larksr_websdk 下。
+SDK 加载成功之后，非模块模式下，SDK 挂载为全局对象 larksr_websdk。
 
 连接云端资源，管理生命周期和事件等主要在 LarkSR 对象下。通过调用 CreateLarkSRClientFromeAPI 配置后台请求参数，创建 LarkSR 对象实例。
 
 > 默认情况下自动连接云端资源，将容器设置为浏览器视口高度，并配置网页 100% 宽高显示。SDK 内部自动处理按键输入输出。
 
-> SDK 只包含loading，内部不包含其他 UI。主要目的时二次开发云渲染客户端自定义 UI 使用。
-
+> SDK 只包含 loading，内部不包含其他 UI。主要目的时二次开发云渲染客户端自定义 UI 使用。
 
 ## 参考 DEMO 和文档
 
-更多使用方式和 API 文档可以参考下面项目和 .d.ts 中的注释
+更多使用方式和 API 文档可以参考下面项目和 doc 文件夹下的详细文档
 
 [Demos](https://github.com/pingxingyun/lark_sr_websdk_demos)
-

package/dist/doc/config.md

@@ -0,0 +1,108 @@
+# LarkSR 对象参数
+
+创建 LarkSR 对象参数如下
+
+```typescript
+/**
+ * 构造 LarkSR 参数
+ */
+interface ILarkSRConfig {
+    /**
+     * 必选项 根元素。组件会挂载到跟元素下面
+     * 注意*不要*设置为 document.documentElement
+     * 默认模式下会通过旋转根元素实现强制横屏模式。
+     * @see handelRootElementSize
+     * @see scaleMode
+     */
+    rootElement: HTMLElement;
+    /**
+     * 必选项 服务器地址. LarkServer 前台访问的地址
+     * 如： http://192.168.0.55:8181/
+     */
+    serverAddress: string;
+    /**
+     * 可选项。 sdk 授权码。如果不在此处填，则必须在后续的实例里调用 initSDKAuthCode 初始化。
+     */
+    authCode?: string;
+    /**
+     * 可选项，授权是否成功
+     */
+    authCodeCallback?: (isSuccess: boolean, e: any) => void;
+    /**
+     * 可选项，载入时的背景图片 url
+     */
+    loadingBgUrl?: string;
+    /**
+     * 可选项，是否同步传入根的组件的大小样式。
+     * 默认开启，将跟组件大小设置为浏览器视口大小
+     * 如果关闭，内部组件将按照传入的根元素大小去显示
+     * 注意，当关闭时不会自动填充根元素，如果根元素高度为 0 将显示不出来。
+     * 注意，当关闭时 mobileForceLandscape 将失去作用。
+     */
+    handelRootElementSize?: boolean;
+    /**
+     * 是否在sdk内部监听鼠标键盘等输入事件
+     * 如果关闭需要手动发送输入事件
+     * 注意关闭时全屏模式和锁定模式将失效,需要在sdk外部触发
+     * @see fullScreenMode
+     */
+    handlInput?: boolean;
+    /**
+     * 当视频播自动放失败时是否尝试静音播放,静音播放时将抛出事件
+     * 静音播放当用户操作屏幕时将尝试播放声音
+     */
+    mutePlayWhenFiled?: boolean;
+    /**
+     * 可选项，是否是 vr 监控类型。
+     */
+    isMonitor?: boolean;
+    /**
+     * 可选项，码率
+     */
+    codeRate?: number;
+    /**
+     * 可选项，帧率
+     */
+    frameRate?: number;
+    /**
+     * 可选项，音频帧率
+     */
+    audioCodeRate?: number;
+    /**
+     * 可选项，日志级别。默认为 warn
+     */
+    logLevel?: 'info' | 'warn' | 'error';
+    /**
+     * 可选项，载入超时时间. 默认为 60s。超过该事件停止载入
+     */
+    loadingTimeout?: number;
+    /**
+     * 可选项，是否自动同步剪贴板数据
+     */
+    syncLocalToCloudClipboard?: boolean;
+    /**
+     * 可选项，优选选择的视频编码格式
+     */
+    perferDecoder?: 'auto' | 'vp8' | 'vp9' | 'h264' | 'av1x';
+    /**
+     * 可选项，视频在容器中的缩放模式
+     *
+     */
+    scaleMode?: ScaleMode;
+    /**
+     * 全屏模式
+     *  0 -》 用户手动触发
+     *  1 -》 首次点击进入触发
+     *  2 -》 每次点击触发
+     */
+    fullScreenMode?: number;
+    /**
+     * 可选项，手机端的全屏模式，值同  fullScreenMode
+     */
+    mobileFullScreenMode?: number;
+    /**
+     * 可选项，手机端是否强制横屏
+     */
+    mobileForceLandscape?: boolean;
+}
+```

package/dist/doc/events.md

@@ -0,0 +1,129 @@
+# LarkSR 事件系统
+
+在 LarkSR 整个生命周期内会抛出多种事件通知。使用方法类似:
+
+```javascript
+var larksr;
+
+// create code
+...
+
+// 监听连接成功事件
+larksr.on('connect', function(e) { 
+    console.log("LarkSRClientEvent CONNECT", e); 
+});
+```
+
+## 完整事件定义
+
+```javascript
+/**
+ * LarkSR 实例完整事件定义
+ */
+declare const enum LarkSRClientEvent {
+    /**
+     * 连接渲染服务器成功 .
+     */
+    CONNECT = "connect",
+    /**
+     * 登录成功时触发，会返回当前用户id .
+     */
+    LOGIN_SUCCESS = "loginsuccess",
+    /**
+     * 无操作超时时触发 .
+     */
+    NO_OPERATION_TIMEOUT = "operatetimeout",
+    /**
+     * 连接关闭.
+     */
+    CLOSE = "close",
+    /**
+     * 云端应用关闭，但连接未关闭
+     */
+    APP_CLOSE = "appclose",
+    /**
+     * 获取到远端视频流 .
+     */
+    GOT_REMOTE_STREAM = "gotremotesteam",
+    /**
+     * 视频加载成功，等待播放 .
+     */
+    MEDIA_LOADED = "meidaloaded",
+    /**
+     * 视频自动播放成功 .
+     */
+    MEDIA_PLAY_SUCCESS = "mediaplaysuccess",
+    /**
+     * 视频自动播放失败 .
+     */
+    MEDIA_PLAY_FAILED = "mediaplayfailed",
+    /**
+     * 自动播放声音失败，以静音模式播放 .
+     */
+    MEDIA_PLAY_MUTE = "meidaplaymute",
+    /**
+     * 云渲染连接状态改变 .
+     */
+    APPSTATE_CHANGE = "appstatechange",
+    /**
+     * 云端应用大小变化 .
+     */
+    APP_RESIZE = "appresize",
+    /**
+     * 云端应用鼠标模式变化时触发 .
+     */
+    APP_MOUSE_MODE = "appmousemode",
+    /**
+     * 云端应用鼠标状态变化 .
+     */
+    APP_CURSOR_MODE = "appcursormode",
+    /**
+     * 玩家列表 .
+     */
+    PLAYER_LIST = "playerlist",
+    /**
+     * 视频连接状态
+     */
+    PEERSTATUS_REPORT = "peerstatusreport",
+    /**
+     * 云端应用请求输入文字 .
+     */
+    APP_REQUEST_INPUT = "apprequestinput",
+    /**
+     * 云端应用请求手柄震动
+     */
+    APP_REQUEST_GAMEPAD_OUPUT = "apprequestgamepadoutput",
+    /**
+     * 截图成功.
+     */
+    CAPTURE_FRAME = "captureframe",
+    /**
+     * 数据通道打开 .
+     */
+    DATACHANNEL_OPEN = "datachannelopen",
+    /**
+     * 数据通道关闭 .
+     */
+    DATACHANNEL_CLOSE = "datachannelclose",
+    /**
+     * 数据通达收到文字消息 .
+     */
+    DATACHANNEL_TEXT = "datachanneltext",
+    /**
+     * 数据通道收到字节消息 .
+     */
+    DATACHANNEL_BINARY = "datachannelbinary",
+    /**
+     * 更详细的事件状态，主要用于向iframe外部抛出 .
+     */
+    LarkEvent = "larkevent",
+    /**
+     * 发生错误时抛出
+     */
+    ERROR = "error",
+    /**
+     * 一般信息提示
+     */
+    INFO = "info"
+}
+```

package/dist/doc/functions.md

@@ -0,0 +1,65 @@
+# LarkSR 对象成员方法
+
+LarkSR 对象成员方法主要分为以下三类
+
+## 控制流程方法，包括启动，关闭，重启，注册授权码等。
+
+```typescript
+/**
+ *
+ * @param id sdk id 初始化sdkid
+ * @returns
+ */
+initSDKAuthCode(id: string): Promise<void>;
+/**
+ * 开始云渲染流程
+ * @returns 是否成功。主要校验授权码是否成功
+ */
+start(): Promise<void>;
+/**
+ * 重新开始云渲染流程
+ */
+restart(): void;
+/**
+ * 重新启动云端应用
+ */
+restartApp(): void;
+```
+
+## 输入输出相关方法，包括鼠标，键盘，手柄，触摸
+
+```typescript
+/**
+ * 切换当前操作者
+ * @param uid 用户id
+ */
+changeOperater(uid: number): void;
+/**
+ * 向云端应用发送文字。当云端应用出现输入框时，可以将本地文本填写进去.
+ * @param text 文字
+ */
+inputText(text: string): void;
+/**
+ * 操作相关事件
+ * 所有事件坐标相对于云端应用，不相对于网页
+ * @param input 操作指令
+ */
+sendInput(input: CloudLark.IClientInput): void;
+```
+
+## 数据通道扩展，向云端应用数据通道发送数据
+
+```typescript
+/**
+ * 发送文字消息给数据通道
+ * 注意 云端应用要继承数据通道功能
+ * @param text 文字
+ */
+sendTextToDataChannel(text: string): void;
+/**
+ * 发送字节消息给数据通道
+ * 注意 云端应用要继承数据通道功能
+ * @param binary 字节消息
+ */
+sendBinaryToDataChannel(binary: Uint8Array): void;
+```

package/dist/doc/index.md

@@ -0,0 +1,65 @@
+#
+
+## 安装
+
+1. npm 方式
+
+```cmd
+npm i larksr_websdk
+```
+
+2. 直接引入
+
+```html
+<script src="larksr-web-sdk.min.js"></script>
+```
+
+> 直接引入模式下 SDK 挂载为全局对象 larksr_websdk。
+
+## 使用
+
+主要使用 LarkSR 对象实例，所有基本操作和事件通过该实例实现。创建该对象一般通过 `CreateLarkSRClientFromeAPI` 和 `CreateLarkSRClientFromeUrl` 函数创建 LarkSR 实例。
+
+```typescript
+/**
+ * 通过调用后台接口获取云端应用参数
+ * @param config 传入 config @see ILarkSRConfig
+ * @param params 进入应用接口参数。appliId 为必填项
+ * @returns Promise 创建 larksr client 是否成功
+ */
+export declare function CreateLarkSRClientFromeAPI(config: ILarkSRConfig, params: {
+    appliId: string;
+    playerMode?: number;
+    userType?: number;
+    roomCode?: string;
+    taskId?: string;
+}): Promise<LarkSR>;
+
+/**
+ * 通过从url参数中获取云端应用相关参数
+ * @param config 传入 config @see ILarkSRConfig
+ * @returns Promise 创建 larksr client 是否成功
+ */
+export declare function CreateLarkSRClientFromeUrl(config: ILarkSRConfig): Promise<LarkSR>;
+```
+
+## 手动创建
+
+> 注意，如果手动创建该类，要清楚参数的意义，一般只有调试等特殊情况才手动创建该类
+
+```typescript
+/**
+* LarkSR 客户端。所有操作和事件通过该类传递
+* 注意，如果手动创建该类，要清楚参数的意义，一般只有调试等特殊情况才手动创建该类
+* @see CreateLarkSRClientFromeAPI, CreateLarkSRClientFromeUrl
+* @param config 本地配置，如果有 IAppliParams 相同的配置项，优先级最高
+* @param params 云端应用参数等，通过后台接口或者url参数获取。
+*/
+constructor(config: ILarkSRConfig, params: IAppliParams);
+```
+
+## 文档目录
+
+### [参数配置](./config.md)
+### [LarkSR 对象方法](./functons.md)
+### [LarkSR 事件](./functons.md)

package/dist/doc/member_variables.md

@@ -0,0 +1,148 @@
+# LarkSR 对象成员变量
+
+LarkSR 对象成员变量,注意以下划线开头的变量为内部使用私有变量或只读成员变量，不建议修改直接使用。
+
+> 以下代码中 larksr 为创建好的 LarkSR 对象实例。省略创建过程。
+
+```javascript
+let larksr;
+
+...// create code.
+```
+
+## 视频组件
+
+1. `videoComponent` 视频组件
+
+```javascript
+// 获取播放的 <video /> 视频元素
+larksr.videoComponent.getVideo();
+// 播放视频，async 方法播放失败抛出异常
+larksr.videoComponent.playVideo();
+// 停止视频播放
+larksr.videoComponent.stopVideo();
+// 播放视频声音，取消静音播放
+larksr.videoComponent.sountPlayout();
+// 截取一帧，返回 base64，并抛出截图成功事件
+larksr.videoComponent.captrueFrame(data);
+```
+
+2. `videoElement`  html `video` 视频元素本身
+
+```javascript
+larksr.videoElement;
+```
+
+## 配置参数
+
+```javascript
+// `config` IAppliParams传入的 ILarkSRConfig 对象
+larksr.config;
+//  `params` 构造函数中传入的 IAppliParams 对象
+larksr.params;
+```
+
+## 用户模式
+
+```javascript
+// `playerModeType` 当前的玩家模式;
+larksr.playerModeType;
+// `userType` 当前用户类型;
+larksr.userType;
+// 当前是否是交互模式，交互默认即可以操作的模式
+larksr.isInteractiveMode;
+// 是否是观看者模式
+larksr.isObMode;
+```
+
+## 当前 app 的状态
+
+```javascript
+larksr.appState;
+```
+
+具体状态值如下:
+
+```javascript
+export enum APP_STATE {
+    BEFORE_CREATE = 0,
+    INITED,
+    WEBSOCKET_CHANNEL_OPEN,
+    LOGIN_SUCCESS,
+    RTC_CONNECTED,
+    MEDIA_LOADED,
+    MEDIA_PLAED,
+    RTC_RETRY,
+    APP_RETRY,
+    BEFORE_DESTORY,
+    WEBSOCKET_CLOSED,
+    RTC_CLOSED,
+    DESTROYED,
+}
+```
+
+```javascript
+// 云端画面是否准备好，准备好后才可以发送输入事件
+larksr.remoteScreenReady
+```
+
+## 当前的屏幕状态
+
+```javascript
+// 通知视口改变或者需要重新计算显示属性
+larksr.screenState.resize();
+// 当前云端 APP 的大小
+larksr.screenState.appSize;
+// 当前云端 APP 的鼠标状态
+larksr.screenState.appMouseMode;
+// 当前渲染容器的大小
+larksr.screenState.viewPort;
+// 强制横屏模式
+larksr.screenState.screenOrientation;
+// 缩放模式
+larksr.screenState.scaleMode;
+// 是否全屏状态
+larksr.screenState.isFullScreen;
+// 是否锁定鼠标状态
+larksr.screenState.isLockMouse;
+// 云端应用的鼠标样式
+larksr.screenState.cursorStyle;
+// 初始化鼠标模式
+larksr.screenState.initCursorMode;
+// 是否是手机模式
+larksr.screenState.isMobile;
+// 是否渲染本地鼠标
+larksr.screenState.isLocalRenderMouse;
+// 是否锁定鼠标
+larksr.screenState.isLockMosue;
+```
+
+## 操作类实例
+
+```javascript
+// 开始监听,默认情况下自动开始
+larksr.op.startListening();
+// 结束监听输入事件.
+larksr.op.stopListenling();
+// 开启或关闭鼠标输入事件
+larksr.op.setMouseEnable(enable: boolean);
+// 开启或关闭键盘输入事件
+larksr.op.setKeyboardEnable(enable: boolean);
+// 开启或关闭手柄输入事件
+larksr.op.setGamepadEnable(enable: boolean);
+// 开启或关闭触摸屏幕输入事件
+larksr.op.setTouchEnable(enable: boolean);
+```
+
+## 全屏锁屏
+
+```javascript
+// 进入全屏模式
+larksr.fullScreen.launchFullScreen();
+// 退出全屏模式
+larksr.fullScreen.exitFullscreen();
+// 锁定鼠标
+larksr.lockPointer.lockPointer();
+// 释放鼠标
+larksr.lockPointer.exitPointerLock();
+```