ecloud-rcr

天翼云实时云渲染 JS SDK

ecloud-rcr

[toc]

安装

npm install ecloud-rcr

一、快速启动

1.1 前端项目引入

import { RCRLaunch } from 'ecloud-rcr';

const bootstrap = async () => {
  try {
    const launch = await RCRLaunch({ appKey });
    const container = document.getElementById('container');
    await launch.automata(container);
    const connection = launch.getConnection();
    //监听连接状态
    connection.event.close.on(() => console.log('断开连接'));
  } catch (error) {
    console.error(error);
  }
};

bootstrap();

1.2 浏览器直接引入

• Demo：浏览器直接引入.html

// 注意全局对象的名称
const { RCRLaunch } = window.ECloudRCR;

二、启动器(Launcher)

import { RCRLaunch } from 'ecloud-rcr';

const launch = RCRLaunch({
  appKey,
  baseOptions: { ... },
  extendOptions: { ... },
});

2.1 构造属性(Constructors)

属性	说明	类型	是否必填
appKey	应用 key	string	-
baseOptions	基础配置	baseOptions	-
extendOptions	拓展配置	extendOptions	-

2.1.1 baseOptions 基础配置

• Demo：webrtcEnable:true 设置推流
• Demo：webrtcEnable:false 设置推流
• Demo: 投屏

属性	说明	类型	是否必填
startType	1：普通连接 3：投屏连接	number	必填
appSecret	密钥	string	-
webrtcEnable	是否开启webrtc推流，默认为true(详见示例)	boolean	-
exeParameter	自定义应用启动参数	string	-
isCastScreenMaster	(投屏)是否为主控	boolean	-
castScreenMaxQty	(投屏)最大并发数(最大为 5)	number	-
castScreenNickname	(投屏)昵称	string	-
castScreenPwd	(投屏)投屏密钥	boolean	-
joinType	(投屏)加入方式 (1：密钥|3：链接)	number	-

2.1.2 extendOptions 拓展配置

属性	说明	类型	是否必填
onPlay	开始播放回调	() => void	-
onLiveStart	设置直播流url地址(开始)回调	(result:boolean) => void	-
onLiveStop	停⽌直播回调	(result:boolean) => void	-
onLiveUrl	设置直播url地址回调	(result:boolean) => void	-
onMount	虚拟控件挂载回调(返回挂载父节点)	(el:HTMLElement) => void	-
onRotate	视频容器方向变化回调	(rotate:boolean) => void	-
ueMultiTouch	是否开启 UE4 应用多点触控	boolean	-
minBitrate	初始化最小码率(默认为：2000)	number	-
maxBitrate	初始化最大码率(默认为：5000)	number	-
startBitrate	初始化码率(默认为：4000)	number	-
openWebRTCStats	开启 WebRTC 日志打印	boolean	-
holdToolDisplay	是否保持工具栏显示	boolean	-
audioToastDisplay	是否开启音频提示弹窗(默认true)	boolean	-
toolOption	工具栏选项	toolOption	-
eventOption	事件选项	eventOption	-

2.1.2.1 extendOptions.toolOption 工具栏选项

• Demo：自定义工具栏(实现上报功能)

属性	说明	类型	是否必填
dropTools	删除工具栏	DropToolsType	-
dropTools.toolsIndex	工具栏位置(从 0 开始)	number[]	-
dropTools.platform	平台（1:pc|2:移动端|3:全部）	number	-
extendTools	新增工具栏	ExtendToolsType[]	-
extendTools.icon	图标(base64)	string
extendTools.text	标题	string	-
extendTools.platform	平台（1:pc|2:移动端|3:全部）	number	-
extendTools.order	新增位置(从 0 开始)	number	-
extendTools.onClick	点击触发事件	() => void	-

2.1.2.2 extendOptions.eventOption 事件选项

属性	说明	类型	是否必填
enableKeyBoard	是否挂载键盘事件(默认为 true)	boolean	-

2.2 属性(Attributes)

属性名	说明	类型	默认值
runningState	获取运行状态	dn	-
runningState.isOrientationMatch	获取屏幕方向变化(false:横屏|true:竖屏)	boolean	true

2.3 方法(Methods)

• Demo：Launcher 实例的方法

方法名	说明	参数	回调参数
getConnection	获取连接实例	-	连接实例(Connection)
getPlayer	获取播放实例	-	播放实例(LivePlayer)
report	获取实时连接状态	-	object
toggleStatistics	控制连接状态显示状态(影响report)	-	object
toggleFullscreen	切换全屏(横屏)支持情况参考	-	void
destory	断开全部连接	[errMsg]	void
setUpProcessPause	暂停当前运行应用	-	void
setUpProcessRestart	重启运行应用	-	void
setMoveSensitivity	设置鼠标或者触摸移动的敏感度	number(0：低，1：中，2：高)	void
handleSubscribe	手动挂载鼠标、键盘、触控等事件	HTMLElement	void
handleUnsubscribe	手动取消鼠标、键盘、触控等事件	-	void
requestPointerLock	锁定鼠标	-	void
exitPointerLock	解锁鼠标	-	void
handleChangeSubscribe	切换猫头工具的控制权	boolean	void
getOrientationMatch	对比容器与推流的方向是否一致	-	boolean
liveStart	设置直播流url地址，并开始推送；传参为空时，使用之前的url地址(详细参考示例6.9)	[string]	void
liveStop	停⽌推直播流数据	-	void
liveUrl	设置直播url地址，url地址必填	string	void

三、连接管理(Connection)

const launch = await RCRLaunch({ ... });
await launch.automata(container);
const connection = launch.getConnection();

3.1 属性(Attributes)

• demo：连接实例属性

属性名	说明	类型	默认值
dc	获取 RTCDataChannel 实例	RTCDataChannel	-
pc	获取 RTCPeerConnection 实例	RTCPeerConnection	-
event	Connection 事件	object	-

3.2 方法(Methods)

• demo：和应用双向通信
  • 应用需要集成相应插件：ue4，unity
• demo：重置超时时间：常用于手动挂载键鼠时间时，避免有操作前提下超时断联的问题
• demo：调节码率

方法名	说明	参数	回调参数
emitUIInteraction	发送消息到应用程序	string	Promise<boolean>
send	发送消息到应用程序	string|Blob|ArrayBuffer|boolean	void
changeBandwidth	调节码率	number	void
controlAuthority	转移控制权限(详细参考投屏示例)	[token]	void

3.3 事件(Events)

• demo：连接实例 event

事件名	说明	回调参数
connect	可视化服务连接中	-
dataChannelConnected	连接成功，资源加载中	-
close	连接中断回调	CloseEvent
disconnect	信令断开回调	string
interaction	接收应用端返回数据	string
afk	超时断开	-

四、播放管理(LivePlayer)

const launch = await RCRLaunch({ ... });
await launch.automata(container);
const livePlayer = launch.getPlayer();

4.1 属性(Attributes)

• Demo：播放实例属性

属性名	说明	类型	默认值
videoElement	播放实例节点	HTMLVideoElement	-
playerElement	播放实例父级容器	HTMLDivElement	-
videoVolume	获取 video 当前音量值（应用声音,ios设备永远返回1）	number	0

4.2 方法(Methods)

• Demo：播放实例设置加载文字、音量、背景图
• Demo：播放实例设置显示模式和重置

方法名	说明	参数	回调参数
handleChangeCanResize	设置播放实例显示模式自适应	boolean	void
resizePlayer	初始化播放实例显示模式	-	void
showLoadingText	设置加载中文字	string	void
showTextOverlay	设置播放页遮盖文字	string	void
setVideoVolume	设置 video 播放音量值（应用声音）	number	void
handleChangeBgImage	设置应用加载背景图	string	void
handleChangeOrientationLock	移动端调节旋转	boolean(false:横屏|true:竖屏)	void
handleChangeLandscapeType	设置显示模式	number(1:自适应|2:拉伸|3:裁剪)	void

五、鼠标键盘控制相关接口(可选扩展)

当您需要对鼠标、键盘进行定制时（eg：组合键、改键映射），可以使用下面的能力。

5.1 键盘事件(Keyboard)

• Demo：自定义组合键

import { RCRLaunch, Keyboard } from 'ecloud-rcr';
const launch = await RCRLaunch({
  ...
  extendOptions: {
    eventOption: {
      enableKeyBoard: false, // 关闭默认键盘挂载
    },
    onPlay() {
      // 处理键盘映射
    },
  },
});
await launch.automata(container);
const connection = launch.getConnection();

// eg：发送键盘事件
connection.send(new Keyboard(27, false, false, false, false, false, false, true).dumps());

参数说明：

属性	说明	类型
keycode	键码	number
alt	按下 alt	boolean
shift	按下 shift	boolean
ctrl	按下 ctrl	boolean
nlock	按下 nlock	boolean
clock	按下 clock	boolean
slock	按下 slock	boolean
down	按下	boolean

5.2 鼠标移动事件(MouseMove)

import { MouseMove } from 'ecloud-rcr';
connection.send(new MouseMove(100, 300, 3, 4).dumps());

参数说明：

属性	说明	类型
x	x	number
y	y	number
dx	dx	number
dy	dy	number

5.3 鼠标按钮事件(MouseButton)

import { MouseButton } from 'ecloud-rcr';
connection.send(new MouseButton(1, true).dumps());

参数说明：

属性	说明	类型
mouseButtonType	left = 1,middle=2, right=3	number
down	按下	boolean

5.4 缩放事件(WheelScroll)

import { WheelScroll } from 'ecloud-rcr';
connection.send(new WheelScroll(10, true).dumps());

参数说明：

属性	说明	类型
step	step	number
forward	forward	boolean

5.6、触控事件(TouchSet)

import { TouchSet } from 'ecloud-rcr';
connection.send(new TouchSet(0, [{ x: 10, y: 10, id: 1 }]).dumps());

参数说明：

属性	说明	类型
touchType	down = 0,update=1, up=2	number
touchList	TouchPoint:{x: number y: number id: number} //id：touch identifier	TouchPoint[]

5.7、文本传输事件(TextInput)

• demo：聚焦应用输入框，发送内容

import { TextInput } from 'ecloud-rcr';
connection.send(new TextInput('test text').dumps());

参数说明：

属性	说明	类型
text	聚焦应用输入框时能够快速发送内容，比如实现复制粘贴功能	string

5.8、鼠标控制管理相关(PointerManager)

• demo：设置鼠标样式

import { PointerManager } from 'ecloud-rcr';
new PointerManager(target);

参数说明：

属性	说明	类型
target	宿主容器	HTMLElement
onExit	全局退出或者中断回调	() => void

属性说明：

属性名	说明	类型	默认值
cursor	光标实例	base64: string, show: boolean, x: number, y: number	cursor

方法说明：

方法名	说明	参数	回调参数
setCursor	设置鼠标大小/形状	Cursor	void
destory	销毁	-	void

六、常用问题

6.1 接入微信小程序

• 步骤
  1. 使用 jssdk 开发，打包成 html 部署到线上(生产环境需要域名解析)
  2. 微信小程序通过 web-view 嵌入 html 地址(域名链接)
• 开发 html 时候，微信(小程序)环境需要注意监听 WeixinJSBridgeReady 事件，然后开始对接 jssdk

window.addEventListener('DOMContentLoaded', () => {
  if (navigator.userAgent.includes('miniProgram') || navigator.userAgent.includes('MicroMessenger')) {
    //微信浏览器/微信小程序环境
    document.addEventListener('WeixinJSBridgeReady', bootstrap, false);
  } else {
    bootstrap();
  }
});

6.2 WebRTC 调试参考

• 方法1：在任一浏览器标签地址打开 chrome://webrtc-internals，即可看到 WebRTC 的完整调试数据
• 方法2：调⽤ Launcher showDashboard⽅法，显示仪表盘推流性能数据(注：空数据情况下记得调⽤ launcher toggleStatistics ⽅法切换状态)
• 方法3：调⽤ Launcher exportLog ⽅法，导出 webrtc-internal s统计数据(注：空数据情况下记得调⽤ launcher toggleStatistics ⽅法切换状态)

6.3 接入多点触控需求（UE4）

1. 接入 3DCAT 的 UE4 插件
2. 在后台管理->应用详情->设置->开启多点触控。

6.4 投屏分享功能

功能说明：

• 投屏交互分为主控端、观看端
• 主控端需要使用投屏 appKey 初始化应用
• 主控端生成观看端链接
• 主控端可以赋予/回收临时操控权给观看端（需要创建投屏链接时勾选该功能）

主控端示例：

const launch = await RCRLaunch({
  appKey, // 投屏专用 appKey ，需要先增加投屏链接获取
  address, // 投屏需要指定集群地址，和观看端保持同集群
  baseOptions: {
    startType: 3, // 投屏链接
    isCastScreenMaster: true,
  },
  extendOptions: {
    onMount: () => {
      // 获取投屏观看端临时 appKey ，拼接投屏地址
      // 投屏地址可以直接使用当前页面（定义 query 参数来区分端），或使用独立的分享页面来进行物理分隔
      copyUrl = `${window.location.origin}${window.location.pathname}?appKey=${key}&type=share`;
    },
    toolOption: {
      // 生成投屏的功能按钮
      extendTools:[
        {
          icon: "your icon",
          text: "访问邀请",
          platform: 3,
          onClick: () => { 
            // 复制生成的投屏地址
          },
        },
      ],
    },
  },
});

connection.event.clientInfo.on((data) => {
  const list = data.clients || [];

  list.forEach((client) => {
    const { nickname, isControlAuthority, token } = client;
    // 渲染投屏用户列表，注意：
    // 1、仅主控端可以进行权限转移
    // 2、列表样式用户自行定义

    // 判断当前用户是自己
    if (token === launch.clientToken) {
      launch.handleChangeSubscribe(isControlAuthority); // 切换猫头工具的控制权
      isControlAuthority ? launch.handleSubscribe(videoEle) : launch.handleUnsubscribe(); // 订阅交互 or 取消订阅交互
    }
  });
});

观看端示例：

const bootstrap = async (nickname) => {
  try {
    const launch = await RCRLaunch({
      // appKey, // 不需要填，默认从 query 中读取观看端 appKey
      address, // 需要显式指定集群地址，确保和主控端在同一集群
      baseOptions: {
        startType: 3, // 投屏链接
        isCastScreenMaster: false,
        nickname: nickname, // 分享端必填
      },
    });
    connection.event.clientInfo.on((data) => {
      // 
    });
  } catch (error) {
    console.error(error);
  }
};

// 分享端要先拿到分享信息，渲染一个需要输入 nickname 的界面给用户填写，填写后再启动应用