Class: TRROSDK

Constructor

new TRROSDK(params)

Parameters:

Name Type Description

params

Object

Properties

Name Type Attributes Default Description

cloudMode

CloudMode

"private"

云模式

取值：

public 公有云
public_intl 公有云国际站
private 私有云

serverIp

string | Array.<string>

信令调度服务器的域名或 IP 地址，可传入多个信令调度服务器地址

云模式 cloudMode 设置为 public 或 public_intl 时，该字段无效；
云模式 cloudMode 设置为 private 时，必须提供该字段，否则将抛出错误。

port

number

信令调度服务端口。
公有云模式下，该字段无效，私有云模式下默认为 3000/443（启用 https）。

https

boolean

false

是否启用 https 协议，可选。
公有云模式下强制使用 https，该字段无效，私有云模式下默认为 false。

mqttOptions

Object

MQTT 配置项，可选。

Properties

Name Type Attributes Default Description

url

string | Array.<string>

MQTT 服务器的域名或 IP，可选，可传入多个 MQTT 服务器地址。
公有云模式下，一般无需配置该字段；私有云模式下默认与 serverIp 一致。

port

number

MQTT 服务器端口，可选。
公有云模式下，一般无需配置该字段；私有云模式下默认为 2833。

forceLogin

boolean

false

强制登录

若配置为 true，则登录时会无视是否已有同名用户登录，并踢掉已登录的同名用户

projectId

string | number

项目 ID

remoteDeviceId

string

远端设备 ID

password

string

远端设备密码

observer

TRROMediaObserver

事件回调函数,完整字段说明详见 TRROMediaObserver

loggerOption

Object

SDK 日志配置,完整字段说明详见 TRROConfig#loggerOption

customMessageOption

Object

自定义消息(onControlData)相关配置,完整字段说明详见 TRROConfig#customMessageOption

Example

// 公有云模式，初始化最小配置
new TRROSDK({
 cloudMode: 'public',
 projectId: 'xxxxxxxx',
 remoteDeviceId: 'xxxxxxxx',
 password: '********',
});

// 私有云模式，初始化最小配置
new TRROSDK({
 serverIp: '1.1.1.1',
 projectId: 1111,
 remoteDeviceId: 'xxxxxxxx',
 password: '',
});

Methods

(async) init()

初始化 MQTT 连接

Returns:

返回 Promise 对象。

Name	Type	Description
code	number	0 success, 21 mqtt client connnect error, 26 mqtt client alreay connected, 100 request error
message	string	描述信息，error 信息

Example

init()

setSessionPermissionToken(fieldDeviceId, token) → {void}

设置指定现场设备的临时会话密钥。
只有在公有云模式下，通过使用项目共享密钥生成的远端设备 ID 和密码，实现远端设备的自动注册和登录时，才需要调用该方法。

Parameters:

Name	Type	Description
`fieldDeviceId`	string
`token`	string

Returns:

Type:: void

Example

setSessionPermissionToken('<FIELD-DEVICE-ID>', '<TOKEN>')

(async) connect(fieldDeviceId)

连接指定现场设备

Parameters:

Name	Type	Description
`fieldDeviceId`	string	现场设备 ID

Returns:

返回 Promise 对象。

字段	类型	描述
code	number	错误码
message	string	描述信息

其中，code 和 message 字段的含义如下：

code	message	描述
0	Already joined.	已连接
2	Joining	当前传入的现场设备正在连接中
20	Connect failed for public cloud mode, MQTT client not found.	公有云模式，MQTT 未初始化
21	Connect failed for public cloud mode: xxxxxx	公有云模式，MQTT 连接失败

Example

connect('<FIELD-DEVICE-ID>')

订阅媒体流（拉流）

Parameters:

Name Type Description

params

Object

Properties

Name Type Attributes Description

fieldDeviceId

string

现场设备 ID

containers

Array.<Object>

Properties

Name	Type	Description
`streamId`	number	视频流流号
`mount`	string	视频流挂载节点，以 ID 形式，#test-div-0，SDK 会在该节点下自动创建媒体元素并播放流。
`callback`	function	latency 为端到端延迟，metadata 为 requestVideoFrameCallback 回调的 metadata

audioContainer

string

音频流挂载节点，以 ID 形式，#test-div-0。SDK 会在该节点下自动创建媒体元素并播放流。若不传该字段，则不拉取音频流。若不传 containers 字段，则该字段无效，订阅接口返回错误码。

incremental

boolean

是否增量订阅，默认为 false，即每次调用订阅接口传入的参数，会全量覆盖现有的订阅状态。若为 true，则会增量订阅，即保持现有流的订阅状态并新增订阅的传入的流，或者更新已订阅的流的相关参数（如挂载节点）

Returns:

返回 Promise 对象。

Name	Type	Description
code	number	0 success, 1 unjoined, 2 joining, 3 failed, 4 streams not published, 5 empty containers, 20 mqtt client not found, 21 mqtt client not connected, 100 request error
message	string	描述信息，error 信息

Example

subscribe({
  fieldDeviceId: 'xxxxxxxx',
  containers: [{
    streamId: 0,
    mount: '#test-div-0',
    callback: ({latency, metadata}) => {
     console.log(latency, metadata);
    }
  },{
    streamId: 1,
    mount: '#test-div-1',
    callback: ({latency, metadata}) => {
     console.log(latency, metadata);
    }
  }],
 audioContainer: '#test-div-audio'
})

(async) unsubscribe(params)

取消订阅 track （拉流）

Parameters:

Name Type Description

params

Object

Properties

Name	Type	Attributes	Description
`fieldDeviceId`	string		现场设备 ID
`streamIds`	Array.<number>		需要取消订阅的视频流流号
`audioStream`	boolean	<optional>	是否取消订阅音频流，默认为 false

Returns:

返回 Promise 对象。

Name	Type	Description
code	number	0 success, 1 unjoined, 2 joining, 5 empty streamIds，20 mqtt client not found, 21 mqtt client not connected, 100 request error
message	string	描述信息，error 信息

Example

unsubscribe({ fieldDeviceId: 'xxxxxxxx', streamIds: [0] })

(async) publish(params)

发布音频流（推流）
只有在成功订阅了视频流的情况下，才能发布音频流，若取消订阅了所有视频流，则 SDK 会自动取消发布音频流，并通过 onEvent 回调通知
一个 SDK 实例只允许发布一个音频流
若使用 server 模式，需先调用 requestPermission 申请 master 权限，否则无法推流

Parameters:

Name Type Description

params

Object

Properties

Name	Type	Description
`audioTrack`	MediaStreamTrack	音频流。需要业务层自行通过 `navigator.mediaDevices.getUserMedia()` 等手段获取 `MediaStreamTrack` 对象。·

Returns:

返回 Promise 对象。

Name	Type	Description
code	number	0 success, 1 unjoined, 2 joining, 3 failed, 4 streams not published, 5 empty containers, 20 mqtt client not found, 21 mqtt client not connected, 100 request error
message	string	描述信息，error 信息

Example

try {
  // 初始化 SDK 实例
  const client = new TRROSDK({ ... });
  // 连接指定现场设备
  await client.connect('xxxxxxxx');
  // 订阅视频流
  await client.subscribe({ fieldDeviceId: 'xxxxxxxx', containers: [{ streamId: 0, mount: '#test-div-0' }] });
  // 获取本地音频流
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true, video: false });
  [audioTrack] = stream.getAudioTracks()
  // 发布音频流
  await client.publish({ audioTrack });
} catch () {}

(async) unpublish()

取消发布音频流（取消推流）

Returns:

返回 Promise 对象。

Name	Type	Description
code	number	0 success, 1 unjoined, 2 joining, 3 failed, 4 streams not published, 5 empty containers, 20 mqtt client not found, 21 mqtt client not connected, 100 request error
message	string	描述信息，error 信息

Example

unpublish();

(async) muteAudio(params)

静音或者取消静音指定音频流

Parameters:

Name Type Description

params

Object

Properties

Name	Type	Description
`deviceId`	string	现场设备 ID 或远端设备 ID（即 SDK 初始化时传入的 `remoteDeviceId`）
`muted`	boolean	true 表示静音，false 表示取消静音

Returns:

返回 Promise 对象。

Name	Type	Description
code	number	0 success, 1 unjoined, 2 joining, 5 empty streamIds，20 mqtt client not found, 21 mqtt client not connected, 100 request error
message	string	描述信息，error 信息

Example

muteAudio({ deviceId: 'xxxxxxxx', muted: true })

(async) disconnect(fieldDeviceId)

断开与指定现场设备的连接

Parameters:

Name	Type	Description
`fieldDeviceId`	string	现场设备

Returns:

返回 Promise 对象。

Name	Type	Description
code	number	0 success, 1 unjoined, 3 failed, 100 request error
message	string	描述信息，error 信息

Example

disconnect('xxxxxxxx')

(async) disconnectAll()

断开与所有现场设备的连接

Returns:

返回 Promise 对象。

Name	Type	Description
code	number	0 success, 1 unjoined, 3 failed, 100 request error
message	string	描述信息，error 信息

Example

disconnectAll()

(async) destroy()

销毁所有连接

Returns:

返回 Promise 对象。

Name	Type	Description
code	number	0 success, 1 unjoined, 3 failed, 100 request error
message	string	描述信息，error 信息

Example

destroy()

changeFieldDeviceEncodeConfig(fieldDeviceId, params)

调整现场设备编码配置。
调用此接口将临时更新现场设备的编码配置，现场设备重启后仍会恢复到原配置。
配置更新只涉及传入的字段，未传入的配置项将保持当前状态。

Parameters:

Name Type Description

fieldDeviceId

string

现场设备 ID

params

Array.<Object>

Properties

Name Type Description

streamId

number

视频流流号

encodeConfig

Object

视频流编码配置

Properties

Name	Type	Attributes	Description
`encodeWidth`	number	<optional>	编码分辨率宽度
`encodeHeight`	number	<optional>	编码分辨率高度
`minWidth`	number	<optional>	最低分辨率宽度
`fps`	number	<optional>	视频期望帧率
`minFps`	number	<optional>	视频最低帧率
`bps`	number	<optional>	视频期望码率，单位 kbps
`minBps`	number	<optional>	视频最低码率，单位 kbps
`forceMinBps`	boolean	<optional>	是否强制保证视频分配码率不低于最低码率

Returns:

Name	Type	Description
code	number	0 success, 1 unjoined, 2 joining, 20 mqtt client not found, 21 mqtt client not connected
message	string	描述信息，error 信息

Example

changeFieldDeviceEncodeConfig('xxxxxxxx', [{ streamId: 0, encodeConfig: { minBps: 1000, forceMin: true } }])

(async) requestPermission(fieldDeviceId, params)

网关权限申请

Parameters:

Name Type Description

fieldDeviceId

string

现场设备 ID

params

Array.<Object>

Properties

Name	Type	Description
`permission`	PermissionState	master 控制权限及观看权限 guest 仅观看权限

Returns:

Name	Type	Description
code	number	0 success, 1 unjoined, 2 joining, 20 mqtt client not found, 21 mqtt client not connected, 22 mqtt message publish failed, 23 request pending 24 request timeout
message	string	描述信息，error 信息

Example

requestPermission({ fieldDeviceId: 'xxx', permission: 'master' })

(async) pullGatewayList()

拉取网关设备列表

Returns:

Name	Type	Description
code	number	0 success, 20 mqtt client not found, 21 mqtt client not connected, 22 request publish failed, 23 request pending 24 request timeout
message	string	描述信息，error 信息

Example

pullGatewayList()

(async) getGatewayInfo(gatewayId)

获取指定网关设备信息

Parameters:

Name	Type	Description
`gatewayId`	string	网关设备 ID

Returns:

Name	Type	Description
code	number	0 success, 20 mqtt client not found, 21 mqtt client not connected, 22 request publish failed, 23 request pending 24 request timeout
message	string	描述信息，error 信息
data	Gateway	网关设备信息

Example

getGatewayInfo('gateway_id_123')

(async) adjustVideoRate(fieldDeviceId, params)

调整视频码率

Parameters:

Name Type Description

fieldDeviceId

string

现场设备 ID

params

Array.<Object>

Properties

Name	Type	Description
`streamId`	number	视频流流号
`videoRate`	number	码率，单位 kbps

Returns:

返回 Promise 对象。

Name	Type	Description
code	number	0 success, 1 unjoined, 2 joining, 3 failed, 20 mqtt client not found, 21 mqtt client not connected, 100 request error
message	string	描述信息，error 信息

Example

adjustVideoRate('xxxxxxxx', [{ streamId: 0, videoRate: 3000 }, { streamId: 1, videoRate: 1000 }])

sendControlData(fieldDeviceId, params)

通过 DataChannel 或 MQTT 发送自定义消息。需先调用 requestPermission 申请 master 权限，否则返回失败。

Parameters:

Name Type Description

fieldDeviceId

string

现场设备 ID

params

Object

Properties

Name	Type	Attributes	Default	Description
`data`	string \| ArrayBuffer			自定义消息
`ordered`	boolean	<optional>	true	是否通过可靠通道发送（仅 SCTP 通道有效，与 channelType='mqtt' 互斥）
`channelType`	'sctp' \| 'mqtt'	<optional>	'sctp'	消息通道类型，'sctp' 表示 DataChannel，'mqtt' 表示 MQTT

Returns:

返回 Promise 对象。

Name	Type	Description
code	number	0 success, 1 unjoined (仅SCTP), 2 joining (仅SCTP), 3 failed, 20 mqtt client not found, 21 mqtt client not connected, 42 no permission, 45 no subscribed streams (仅SCTP), 100 request error
message	string	描述信息，error 信息

Example

// 通过 SCTP DataChannel 发送（需要先 connect 和 subscribe）
sendControlData('xxxxxxxx', { data: 'xxx', ordered: true })

// 通过 MQTT 发送（只需登录，无需 connect 和 subscribe）
await sdk.init(); // 登录成功即可
await sdk.requestPermission('fieldDeviceId', { permission: 'master' });
sendControlData('xxxxxxxx', { data: 'xxx', channelType: 'mqtt' })

(async) requestDiagnosisReport(fieldDeviceId) → {Promise.<DiagnosisReport>}

获取诊断报告。通常需要等待 10 秒后才能获取到诊断报告，最大等待时间为 15 秒。

Parameters:

Name	Type	Description
`fieldDeviceId`	string	现场设备 ID

Returns:

返回诊断报告。

Type:: Promise.<DiagnosisReport>

Example

requestDiagnosisReport('<FIELD-DEVICE-ID>')

setJitterBufferTarget(params) → {Object}

设置 jitterBufferTarget（抖动缓冲区目标值）。若网络环境较差，视频卡顿比较明显，可以尝试手动调用该方法调大 jitterBufferTarget。注意：调大 jitterBufferTarget 会增加视频延迟；Chrome 浏览器推荐优先调整 playoutDelayHint 而不是 jitterBufferTarget。

Parameters:

Name Type Description

params

Object

参数对象

Properties

Name	Type	Description
`fieldDeviceId`	string	现场设备 ID
`streamId`	number	流 ID
`jitterBufferTarget`	number \| null	jitterBufferTarget 值，单位毫秒，传 null 还原为默认值

Returns:

返回状态对象，包含 code（0 成功, -1 失败）和 message（描述信息）

Type:: Object

Example

setJitterBufferTarget({ fieldDeviceId: '<FIELD-DEVICE-ID>', streamId: 0, jitterBufferTarget: 100 })
setJitterBufferTarget({ fieldDeviceId: '<FIELD-DEVICE-ID>', streamId: 0, jitterBufferTarget: null }) // 还原默认值

setPlayoutDelayHint(params) → {Object}

设置 playoutDelayHint（播放延迟提示值）。若网络环境较差，视频卡顿比较明显，可以尝试手动调用该方法调大 playoutDelayHint。注意：调大 playoutDelayHint 会增加视频延迟；Chrome 浏览器推荐优先调整 playoutDelayHint 而不是 jitterBufferTarget。

Parameters:

Name Type Description

params

Object

参数对象

Properties

Name	Type	Description
`fieldDeviceId`	string	现场设备 ID
`streamId`	number	流 ID
`playoutDelayHint`	number \| null	playoutDelayHint 值，单位毫秒，传 null 还原为默认值

Returns:

返回状态对象，包含 code（0 成功, -1 失败）和 message（描述信息）

Type:: Object

Example

setPlayoutDelayHint({ fieldDeviceId: '<FIELD-DEVICE-ID>', streamId: 0, playoutDelayHint: 100 })
setPlayoutDelayHint({ fieldDeviceId: '<FIELD-DEVICE-ID>', streamId: 0, playoutDelayHint: null }) // 还原默认值

getCameraViewNavigationLine(params) → {Array.<NavigationLinePoint>}

获取车辆行驶方向的导航线坐标（实验性功能）。基于针孔相机视角模型构建，需要根据真实参数设置，可接近图中真实轨迹。

Parameters:

Name Type Description

params

CameraViewNavigationLineParams

导航线计算参数

Properties

Name	Type	Description
`navDist`	number	导航线远端到车辆的距离，单位与其他距离参数一致（如米）
`blindDist`	number	导航线近端（相机图像底部）到车辆的真实距离，即前方视觉盲区的距离
`carWidth`	number	车辆宽度，单位与距离参数一致
`carLength`	number	车辆前后轮轴距，单位与距离参数一致
`cameraHeight`	number	相机安装高度，单位与距离参数一致
`cameraPitchDegree`	number	相机俯仰角，范围 (0, 90] 度，正对前方为 90 度
`cameraAspectRatio`	number	相机图像宽高比（图像宽度 / 高度）
`carAngle`	number	车辆转向角，范围 -90 到 90 度，左转为负值，右转为正值，可取内侧轮转向角度
`size`	number	导航线采样点数（至少为 2）

Returns:

导航线坐标数组，共 size 个采样点。坐标原点为画面中心点，X/Y 坐标范围均为 (-1, 1)。

Type:: Array.<NavigationLinePoint>

Example

const points = sdk.getCameraViewNavigationLine({
  navDist: 20,
  blindDist: 2,
  carWidth: 2.5,
  carLength: 3.5,
  cameraHeight: 2.0,
  cameraPitchDegree: 75,
  cameraAspectRatio: 16 / 9,
  carAngle: 15,
  size: 20,
});
// 使用坐标在 Canvas 上绘制导航线
points.filter(p => p.valid).forEach(p => {
  const canvasX = (p.leftX + 1) / 2 * canvasWidth;
  const canvasY = (1 - (p.leftY + 1) / 2) * canvasHeight;
  // ...绑定绘制逻辑
});

Constructor

new TRROSDK(params)

Properties

Properties

Methods

(async) init()

setSessionPermissionToken(fieldDeviceId, token) → {void}

(async) connect(fieldDeviceId)

(async) subscribe(params)

Properties

Properties

(async) unsubscribe(params)

Properties

(async) publish(params)

Properties

(async) unpublish()

(async) muteAudio(params)

Properties

(async) disconnect(fieldDeviceId)

(async) disconnectAll()

(async) destroy()

changeFieldDeviceEncodeConfig(fieldDeviceId, params)

Properties

Properties

(async) requestPermission(fieldDeviceId, params)

Properties

(async) pullGatewayList()

(async) getGatewayInfo(gatewayId)

(async) adjustVideoRate(fieldDeviceId, params)

Properties

sendControlData(fieldDeviceId, params)

Properties

(async) requestDiagnosisReport(fieldDeviceId) → {Promise.<DiagnosisReport>}

setJitterBufferTarget(params) → {Object}

Properties

setPlayoutDelayHint(params) → {Object}

Properties

getCameraViewNavigationLine(params) → {Array.<NavigationLinePoint>}

Properties