SDK接入

接入参考

1、快速启动

import { Launcher } from "live-cat";
const appKey = "xxxxxxxxxxxxxxxxxxx";
const address = "https://app.3dcat.live";
const bootstrap = async () => {
  try {
    const launch = new Launcher({
      baseOptions: {
        address,
        appKey,
        startType: 1, //	1:普通链接 | 3:投屏链接
      },
    });
    const player = document.querySelector("body");
    document.querySelector("body").style.width = "100vw";
    document.querySelector("body").style.height = "100vh";
    await launch.automata(player);
  } catch (error) {
    console.error(error);
  }
};

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

2、启动器(Launcher)

2.1、构造属性(Constructors)

属性说明类型是否必填
baseOptions基础配置object必填
extendOptions拓展配置object-

2.1.1、baseOptions

属性说明类型是否必填
address连接地址string必填
appKeyappKeystring必填
startType1:普通连接 | 3:投屏连接number必填
appSecret密钥string-
optionalParam自定义命令行参数(公有化,注意:会导致预加载失效)string-
exeParameter自定义命令行参数(私有化,注意:会导致预加载失效)string-
isCastScreenMaster(投屏)是否为主控boolean-
castScreenMaxQty(投屏)最大并发数(最大为 20)number-
castScreenNickname(投屏)昵称string-
castScreenPwd(投屏)投屏密钥boolean-
joinType(投屏)加入方式 (1:密钥 | 3:链接)number-

2.1.2、extendOptions

属性说明类型是否必填
onPlay开始播放回调() => void-
onMount虚拟控件挂载回调(返回挂载父节点)(el:HTMLElement) => void-
onRotate视频容器方向变化回调(rotate:boolean) => void-
onQueue公有化排队变化回调(rank:number) => void-
minBitrate初始化最小码率(默认为2000)number-
maxBitrate初始化最大码率(默认为5000)number-
startBitrate初始化码率(默认为4000)number-
autorunRivatuner统计推流数据默认开关(默认为false,会影响到仪表盘的记录以及webrtc-internals统计数据导出,实例化后可以通过toggleStatistics方法切换开关)boolean-
holdToolDisplay是否保持工具栏显示(包括加载失败)boolean-
audioToastDisplay是否开启音频提示弹窗(默认true)boolean-
audioOptions语音参数配置MediaTrackConstraints
loadingImage自定义loading (参考附录)string | HTMLImageElement-
toolBarLogoImage自定义toolbar 图标(参考附录)string | HTMLImageElement-
toolOption工具栏选项-
eventOption事件选项-

2.1.3、toolOption

属性说明类型是否必填
dropTools删除工具栏DropToolsType-
extendTools新增工具栏ExtendToolsType[]-

2.1.4、dropTools

属性说明类型是否必填
toolsIndex工具栏位置(从 0 开始)number[]-
platform平台(1:pc | 2:移动端 | 3:全部)number-

2.1.5、extendTools

属性说明类型是否必填
icon图标(base64/url)string-
text标题string-
platform平台(1:pc | 2:移动端 | 3:全部)number-
order新增位置(从 0 开始)number-
onClick点击触发事件() => void-

2.1.6、eventOption

属性说明类型是否必填
enableKeyBoard是否挂载键盘事件(默认为 true)boolean-
enableTouchInteraction多点触控模式下发送系统触控数据(默认为 false)boolean-
enableZoomInteraction多点触控模式下发送系统缩放数据(默认为 false)boolean-

2.2、属性(Attributes)

属性名说明类型默认值
runningState.isOrientationMatch获取屏幕方向变化(false:横屏|true:竖屏)booleantrue
moveSensitivity获取鼠标或者触摸移动的敏感度number(0:低,1:中,2:高)0
taskId获取任务IDnumber-

2.3、方法(Methods)

方法名说明参数回调参数
getConnection获取连接实例-连接实例(Connection)
getPlayer获取播放实例-播放实例(LivePlayer)
getManualPlay获取手动播放方法实例(仅当用户操作系统为 iOS 时有效)-手动播放方法实例(() => void))
report获取实时连接状态(详细参考示例)-object
toggleStatistics切换统计数据开关(默认关,详细参考示例)-object
toggleFullscreen切换全屏(横屏)支持情况参考-void
destory断开全部连接[errMsg]void
setMoveSensitivity设置鼠标或者触摸移动的敏感度number(0:低,1:中,2:高)void
handleSubscribe手动挂载鼠标、键盘、触控等事件HTMLElementvoid
handleUnsubscribe手动取消鼠标、键盘、触控等事件-void
handleChangeSubscribe切换猫头工具的控制权booleanvoid
toggleVirtualControl切换键鼠映射显示状态(默认显示,与键鼠映射设置显示按钮优先级一致)-void
setLogAccordingToLevel设置统计数据级别number(1:log/info,2:warn,3:error)void
showDashboard显示仪表盘推流性能数据-void
hideDashboard隐藏仪表盘推流性能数据-void
exportLog导出webrtc-internals统计数据-void

2.4、示例(Examples)

2.4.1、 获取实时连接各种状态

launcher.toggleStatistics()
window.setInterval(() => {
  const { fps, bitrate, packetLossRate, latency, averageJitterBufferDelay } =
        launcher.report();
  console.log(`
FPS: ${fps}
biterate: ${bitrate}kbps
latency: ${latency}ms
averageJitterBufferDelay: ${averageJitterBufferDelay}ms
packetLossRate: ${(packetLossRate * 100).toFixed(3)}%
`);
}, 1000);

3、连接管理(Connection)

3.1、属性(Attributes)

属性名说明类型默认值
dc获取 RTCDataChannel 实例RTCDataChannel-
eventConnection 事件(参考 3.3 事件(Events))object-
pc获取 RTCPeerConnection 实例RTCPeerConnection-

3.2、方法(Methods)

方法名说明参数回调参数
emitUIInteraction发送消息到应用程序string|ArrayBufferPromise<boolean>
send发送消息(第二个参数为 true 可重置超时时间)(string|Blob|ArrayBuffer,boolean)void
changeBandwidth调节码率(详细参考示例)numbervoid
controlAuthority转移控制权限(详细参考投屏示例)tokenvoid
screenshot云端截图{index?: number;left?: number;top?: number; width?: number;height?: number;}void
changeEncodeResolution修改云端编码分辨率{width?: number||1920,height?: number||1080}void

3.3、事件(Events)

事件名说明回调参数
connect可视化服务连接中{action: 'connect';code: number;message: string;}
dataChannelConnected连接成功,资源加载中(DataChannel 实例打开时;当收到该事件时说明可以开始交互)Event
close连接中断回调CloseEvent
disconnect信令断开回调string
interaction接收应用端返回数据string|ArrayBuffer
afk超时断开number
receivedTrack接收到的音视频流MediaStreamTrack
screenshot完整接收完截图数据时;payload 为截图数据Blob
screenshotData收到截图数据时;payload 为数据字节长度number

3.4、示例(Examples)

3.4.1、调节码率

Connection.changeBandwidth(
  8000, // start bitrate kbps
  10000, // max bitrate kbps
  5000 // min bitrate kbps
);
Connection.changeBandwidth(
  10000 // medians bitrate kbps
);

4、播放管理(LivePlayer)

4.1、属性(Attributes)

属性名说明类型默认值
videoElement播放实例节点HTMLVideoElement-
playerElement播放实例父级容器HTMLDivElement-
videoVolume获取 video 当前音量值(应用声音,ios设备永远返回1number0
displayRect获取显示区域的参数object-

4.2、方法(Methods)

方法名说明参数回调参数
handleChangeCanResize设置播放实例显示模式自适应(详细看示例)booleanvoid
resizePlayer初始化播放实例显示模式-void
showLoadingText设置加载中文字msg: string,
opt?: {
  usePercentStage(是否显示当前加载百分比进度)?: boolean,
  stageNumber(下一阶段进度的百分比数值对比当前阶段的相加值)?: number,
  specificNumber(下一阶段进度的百分比数值)?: number,
  loadingFinished(是否完成加载,即显示加载完成数值为 100%)?: boolean
}
void
showTextOverlay设置播放页遮盖文字stringvoid
setVideoVolume设置 video 播放音量值(应用声音,ios设备不支持numbervoid
handleChangeLandscapeType设置显示模式(详细参考 4.3 示例)number(1:自适应|2:拉伸|3:裁剪)void
handleChangeBgImage设置应用加载背景图stringvoid
handleChangeOrientationLock移动端调节旋转boolean(false:横屏|true:竖屏)void

4.3、示例(Examples)

4.3.1、调节播放实例显示模式

默认为自适应模式,如需初始化其他显示模式,建议写在 Launcher->onPlay 钩子

4.3.1.1、拉伸模式

livePlayer.handleChangeLandscapeType(2);

4.3.1.2、裁剪模式

livePlayer.handleChangeLandscapeType(3);

4.3.1.3、自适应模式

livePlayer.handleChangeLandscapeType(1);

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

5.1、示例

import {
  Keyboard,
  MouseMove,
  MouseButton,
  WheelScroll,
  TouchSet,
  TextInput,
  PointerManager,
} from "ray-streaming";

//键盘事件
connection.send(
  new Keyboard(27, false, false, false, false, false, false, true).dumps()
);
//鼠标移动事件
connection.send(new MouseMove(100, 300, 3, 4).dumps());

//鼠标按钮事件
connection.send(new MouseButton(1, true).dumps());

//缩放事件
connection.send(new WheelScroll(10, true).dumps());

//触控事件
connection.send(new TouchSet(0, [{ x: 10, y: 10, id: 1 }]).dumps());

//文本传输事件
connection.send(new TextInput("test text").dumps());

//鼠标控制管理相关
new PointerManager(target);

5.2、键盘事件(Keyboard)

5.2.1、构造属性(Constructors)

属性说明类型
keycode键码number
alt按下 altboolean
shift按下 shiftboolean
ctrl按下 ctrlboolean
nlock按下 nlockboolean
clock按下 clockboolean
slock按下 slockboolean
down按下boolean

5.3、鼠标移动事件(MouseMove)

5.3.1、构造属性(Constructors)

属性说明类型
xxnumber
yynumber
dxdxnumber
dydynumber

5.4、鼠标按钮事件(MouseButton)

5.4.1、构造属性(Constructors)

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

5.5、缩放事件(WheelScroll)

5.5.1、构造属性(Constructors)

属性说明类型
stepstepnumber
forwardforwardboolean

5.6、触控事件(TouchSet)

5.6.1、构造属性(Constructors)

属性说明类型
touchTypedown = 0,update=1, up=2number
touchListTouchPoint:{x: number y: number id: number} //id:touch identifierTouchPoint[]

5.7、文本传输事件(TextInput)

5.7.1、构造属性(Constructors)

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

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

5.8.1、构造属性(Constructors)

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

5.8.2、属性(Attributes)

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

5.8.3、方法(Methods)

方法名说明参数回调参数
setCursor设置鼠标大小/形状Cursorvoid
destory销毁-void
业务咨询:400-8037-298