API中心Raystreaming JS SDKSDK接入
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 | 必填 |
appKey | appKey | string | 必填 |
startType | 1:普通连接 | 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:竖屏) | boolean | true |
moveSensitivity | 获取鼠标或者触摸移动的敏感度 | number(0:低,1:中,2:高) | 0 |
taskId | 获取任务ID | number | - |
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 | 手动挂载鼠标、键盘、触控等事件 | HTMLElement | void |
handleUnsubscribe | 手动取消鼠标、键盘、触控等事件 | - | void |
handleChangeSubscribe | 切换猫头工具的控制权 | boolean | void |
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)
3.2、方法(Methods)
方法名 | 说明 | 参数 | 回调参数 |
---|
emitUIInteraction | 发送消息到应用程序 | string|ArrayBuffer | Promise<boolean> |
send | 发送消息(第二个参数为 true 可重置超时时间) | (string|Blob|ArrayBuffer,boolean) | void |
changeBandwidth | 调节码率(详细参考示例) | number | void |
controlAuthority | 转移控制权限(详细参考投屏示例) | token | void |
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)
4.2、方法(Methods)
方法名 | 说明 | 参数 | 回调参数 |
---|
handleChangeCanResize | 设置播放实例显示模式自适应(详细看示例) | boolean | void |
resizePlayer | 初始化播放实例显示模式 | - | void |
showLoadingText | 设置加载中文字 | msg: string, opt?: { usePercentStage(是否显示当前加载百分比进度)?: boolean, stageNumber(下一阶段进度的百分比数值对比当前阶段的相加值)?: number, specificNumber(下一阶段进度的百分比数值)?: number, loadingFinished(是否完成加载,即显示加载完成数值为 100%)?: boolean } | void |
showTextOverlay | 设置播放页遮盖文字 | string | void |
setVideoVolume | 设置 video 播放音量值(应用声音,ios设备不支持) | number | void |
handleChangeLandscapeType | 设置显示模式(详细参考 4.3 示例) | number(1:自适应|2:拉伸|3:裁剪) | void |
handleChangeBgImage | 设置应用加载背景图 | string | void |
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 | 按下 alt | boolean |
shift | 按下 shift | boolean |
ctrl | 按下 ctrl | boolean |
nlock | 按下 nlock | boolean |
clock | 按下 clock | boolean |
slock | 按下 slock | boolean |
down | 按下 | boolean |
5.3、鼠标移动事件(MouseMove)
5.3.1、构造属性(Constructors)
属性 | 说明 | 类型 |
---|
x | x | number |
y | y | number |
dx | dx | number |
dy | dy | number |
5.4、鼠标按钮事件(MouseButton)
5.4.1、构造属性(Constructors)
属性 | 说明 | 类型 |
---|
mouseButtonType | left = 1,middle=2, right=3 | number |
down | 按下 | boolean |
5.5、缩放事件(WheelScroll)
5.5.1、构造属性(Constructors)
属性 | 说明 | 类型 |
---|
step | step | number |
forward | forward | boolean |
5.6、触控事件(TouchSet)
5.6.1、构造属性(Constructors)
属性 | 说明 | 类型 |
---|
touchType | down = 0,update=1, up=2 | number |
touchList | TouchPoint:{x: number y: number id: number} //id:touch identifier | TouchPoint[] |
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:number | cursor |
5.8.3、方法(Methods)
方法名 | 说明 | 参数 | 回调参数 |
---|
setCursor | 设置鼠标大小/形状 | Cursor | void |
destory | 销毁 | - | void |