TUICallEngine

@trtc/call-engine-lite-js 是基于腾讯云即时通信 IM 和实时音视频 TRTC 两项付费 PaaS 服务构建出的音视频通信组件，支持双人和多人场景下的音视频通话。

Methods

(static) createInstance(options)

创建 TUICallEngine 实例

Example

let options = {
  SDKAppID: 0, // 接入时需要将0替换为您的云通信应用的 SDKAppID
  // tim 参数适用于业务中已存在 TIM 实例，需要传入保证 TIM 实例唯一性
  tim: tim
};
let tuiCallEngine = TUICallEngine.createInstance(options);

Parameters:

Name Type Description

options

Object

required

配置

Properties

Name Type Description

SDKAppID

Number

required

云通信应用的 SDKAppID

tim

ChatSDK

TIM 实例（选填）

tim 参数适用于业务中已存在 TIM 实例，需要传入保证 TIM 实例唯一性

(async) destroyInstance() → {Promise}

销毁 TUICallEngine 实例

注：SDK 会先 logout，然后释放资源

Example

try {
  await tuiCallEngine.destroyInstance();
  // success
} catch (error) {
  console.warn('destroyInstance error:', error);
}

Returns:

Type: Promise

登录接口，所有功能需要先进行登录后才能使用

Example

try {
  await tuiCallEngine.login({userID: 'your userID', userSig: 'your userSig'});
  // success
} catch (error) {
  console.warn('login error:', error);
}

Parameters:

Name Type Description

params

Object

required

登录配置

Properties

Name	Type	Description
`userID`	String	`required` 当前用户的 ID，字符串类型，只允许包含英文字母（a-z 和 A-Z）、数字（0-9）、连词符（-）和下划线（_）
`userSig`	String	`required` 腾讯云设计的一种安全保护签名，获取方式请参考如何计算 UserSig。
`assetsPath`	String	AI 降噪依赖 denoiser-wasm.js，文件部署的 CDN 或者静态资源服务器的路径。具体详见：使用 AI 降噪。

Returns:

Type: Promise

(async) logout() → {Promise}

登出接口，登出后无法再进行拨打操作

Example

try {
  await tuiCallEngine.logout();
  // success
} catch (error) {
  console.warn('logout error:', error);
}

Returns:

Type: Promise

on(eventName, callback, context)

监听事件

Example

let onError = function(error) {
  console.log(error);
};
tuiCallEngine.on(TUICallEvent.ERROR, onError, this);

Parameters:

Name	Type	Description
`eventName`	String	`required` 事件名
`callback`	function	`required` 事件响应回调
`context`	Any	`required` 期望 callback 执行时的上下文

off(eventName, callback, context)

取消监听事件

Example

let onError = function(error) {
  console.log(error)
};
tuiCallEngine.off(TUICallEvent.ERROR, onError, this);

Parameters:

Name	Type	Description
`eventName`	String	`required` 事件名
`callback`	function	`required` 事件响应回调
`context`	Any	`required` 期望 callback 执行时的上下文

(async) calls(params) → {Promise}

发起单人或多人通话
注意：离线推送仅适用于终端（Android 或 iOS)，Web 和微信小程序不支持。

Example

try {
  await tuiCallEngine.calls({
    userIDList: ['user1', 'user2'],
    type: 1,
  });
  // success
} catch (error) {
  console.warn('calls error:', error);
}

Parameters:

Name Type Description

params

Object

required

群聊拨打通话配置

Properties

Name Type Description

userIDList

Array

required

邀请列表

type

Number

required

1-语音通话，2-视频通话

chatGroupID

String

IM 群组 ID

timeout

Number

0为不超时, 单位 s(秒)（选填） - 默认 30s

roomID

Number

数字房间号, 范围 [1, 2147483647]

strRoomID

String

字符串房间号

userData

String

扩展字段: 用于在邀请信令中增加扩展信息

offlinePushInfo

Object

自定义离线消息推送（选填）

name	Type	Description
title	string	离线推送标题（选填）
description	string	离线推送内容（选填）
androidOPPOChannelID	string	离线推送设置 OPPO 手机 8.0 系统及以上的渠道 ID （选填）
extension	string	离线推送透传内容（选填）
ignoreIOSBadge	boolean	离线推送忽略 badge 计数（仅对 iOS 生效）（选填）
iOSSound	string	离线推送声音设置(仅对 iOS 生效)（选填）
androidSound	string	离线推送声音设置（仅对 Android 生效)（选填）
androidVIVOClassification	number	VIVO 推送消息分类（选填）
androidXiaoMiChannelID	string	小米手机 8.0 系统及以上的渠道 ID（选填）
androidFCMChannelID	string	FCM 通道手机 8.0 系统及以上的渠道 ID（选填）
androidHuaWeiCategory	string	华为推送消息分类（选填）
isDisablePush	boolean	是否关闭推送（默认开启推送）（选填）
iOSPushType	number	iOS 离线推送类型，默认：APNs（选填）

Returns:

Type: Promise

(async) join(params)

主动加入通话

Example

try {
  await tuiCallEngine.join({
    callId: 'call_123456'
  });
  // success
} catch (error) {
  console.warn('join error:', error);
}

Parameters:

Name Type Description

params

required

Properties

Name	Type	Description
`callId`	String	`required` 当前通话的唯一 id

(async) accept() → {Promise}

当您作为被邀请方收到 TUICallEvent.ON_CALL_RECEIVED 事件的回调时，可以调用该接口接听来电

Example

tuiCallEngine.on(TUICallEvent.ON_CALL_RECEIVED, async () => {
  try {
    await tuiCallEngine.accept();
    // success
  } catch (error) {
    console.warn('accept error:', error);
  }
});

Returns:

Type: Promise

(async) reject() → {Promise}

当您作为被邀请方收到 TUICallEvent.INVITED 事件的回调时，可以调用该接口拒绝来电

Example

tuiCallEngine.on(TUICallEvent.INVITED, async () => {
  try {
    await tuiCallEngine.reject();
    // success
  } catch (error) {
    console.warn('reject error:', error);
  }
});

Returns:

Type: Promise

(async) hangup() → {Promise}

挂断当前通话，当您处于通话中，可以调用该函数结束通话；当您处于呼叫状态时，可以调用该函数取消通话

当您处于通话中，可以调用该接口结束通话
当未拨通时, 可用来取消通话

Example

try {
  await tuiCallEngine.hangup();
  // success
} catch (error) {
  console.warn('hangup error:', error);
}

Returns:

Type: Promise

(async) openCamera(videoViewDomID, isFrontCameraopt) → {Promise}

您可以调用该接口开启摄像头，处于通话中的用户会收到 USER_VIDEO_AVAILABLE 回调

Example

// 'localView' is the id value corresponding to the div tag
try {
  await tuiCallEngine.openCamera('localView');
  // success
} catch (error) {
  console.warn('openCamera error:', error);
}

Parameters:

Name	Type	Description
`videoViewDomID`	string	`required` 该用户数据将渲染到该 dom id 节点里
`isFrontCamera`	boolean	前后置摄像头，true 表示前置摄像头。仅支持移动端上使用

Returns:

注意：

当传入 string 类型的 videoViewDomID 时，需要确保 videoViewDomID 在 DOM 中，否则调用接口会报错。
业务侧可自行调整该 DOM 元素的 css 宽高来控制 video 标签显示的宽高。

Type: Promise

(async) closeCamera() → {Promise}

关闭摄像头

Example

try {
  await tuiCallEngine.closeCamera();
  // success
} catch (error) {
  console.warn('closeCamera error:', error);
}

Returns:

Type: Promise

(async) switchCamera(cameraPosition)

切换前后置摄像头

注意: 该接口仅在移动端使用生效。

Example

await tuiCallEngine.switchCamera(TUICallCameraPosition.FRONT); // 切换前置摄像头
await tuiCallEngine.switchCamera(TUICallCameraPosition.BACK); // 切换后置摄像头

Parameters:

Name Type Description

Name	Type	Description
`cameraPosition`	TUICallCameraPosition	`required` 摄像头类型 TUICallCameraPosition.FRONT 前置摄像头 TUICallCameraPosition.BACK 后置摄像头

cameraPosition

TUICallCameraPosition

required

摄像头类型

TUICallCameraPosition.FRONT 前置摄像头
TUICallCameraPosition.BACK 后置摄像头

(async) setVideoQuality(profile) → {Promise}

设置视频分辨率

Example

const profile = '720p';
// Set video quality to 720p
try {
  await tuiCallEngine.setVideoQuality(profile);
  // success
} catch (error) {
  console.warn('setVideoQuality error:', error);
}

Parameters:

Name Type Description

profile

String

required

视频 profile

视频 Profile	分辨率（宽 x 高）
480p	640 x 480
720p	1280 x 720
1080p	1920 x 1080

iOS Safari 不支持采集 1080p
由于设备和浏览器的限制，视频分辨率不一定能够完全匹配，在这种情况下，浏览器会自动调整分辨率使其接近 Profile 对应的分辨率。
默认使用 480p。

Returns:

Type: Promise

(async) setVideoRenderParams(params)

设置用户视频画面的显示模式

Example

const params = {
 userID: '132',
 rotation: 0, // 旋转
 objectFit: 'contain',
 mirror: false,
};
await trtcCloud.setVideoRenderParams(params);

Parameters:

Name Type Description

params

IVideoRenderParam

required

显示参数

Properties

Name	Type	Description
`userID`	String	`required` 用户 ID。不传入 userID 时, 对所有预览进行显示模式设置（包括：本地预览和所有的远端预览）
`objectFit`	String	`required` 视频画面显示模式。目前仅支持: 'contain' \| 'cover' \| 'fill' contain 优先保证视频内容全部显示。视频尺寸等比缩放，直至视频窗口的一边与视窗边框对齐。如果视频尺寸与显示视窗尺寸不一致，在保持长宽比的前提下，将视频进行缩放后填满视窗，缩放后的视频四周会有一圈黑边。v3.0.0 废弃 cover 优先保证视窗被填满。视频尺寸等比缩放，直至整个视窗被视频填满。如果视频长宽与显示窗口不同，则视频流会按照显示视窗的比例进行周边裁剪或图像拉伸后填满视窗。 fill 保证视窗被填满的同时保证视频内容全部显示，但是不保证视频尺寸比例不变。视频的宽高会被拉伸至和视窗尺寸一致。播放视频流默认使用 cover 模式。
`mirror`	TRTCVideoMirrorType	`required` 是否开启视频镜像预览
`rotation`	TRTCVideoRotation	`required` 视频画面旋转方向注意对于本地音视频流，默认开启镜像预览。建议在使用前置摄像头时开启镜像，使用后置摄像头时关闭镜像。对于远端音视频流，默认关闭镜像预览。对于屏幕分享流，不支持开启镜像预览。该参数只对本地预览有效，推流是没有镜像效果的。

(async) openMicrophone() → {Promise}

打开麦克风，处于通话中的用户会收到 USER_AUDIO_AVAILABLE 回调

Example

try {
  await tuiCallEngine.openMicrophone();
  // success
} catch (error) {
  console.warn('openMicrophone error:', error);
}

Returns:

Type: Promise

(async) closeMicrophone() → {Promise}

关闭麦克风，处于通话中的用户会收到 USER_AUDIO_AVAILABLE 回调

Example

try {
  await tuiCallEngine.closeMicrophone();
  // success
} catch (error) {
  console.warn('closeMicrophone error:', error);
}

Returns:

Type: Promise

(async) startRemoteView(params) → {Promise}

开始渲染远端用户视频流

Example

try {
  await tuiCallEngine.startRemoteView({
    userID: 'remote_user_123',
    videoViewDomID: 'remoteVideo'
  });
  // success
} catch (error) {
  console.warn('startRemoteView error:', error);
}

Parameters:

Name Type Description

params

IStartRemoteViewParam

required

远端视频渲染参数

Properties

Name	Type	Description
`userID`	string	`required` 远端用户ID
`videoViewDomID`	string	`required` 视频渲染的 DOM 元素 ID

Returns:

Type: Promise

(async) stopRemoteView(params) → {Promise}

停止远端画面渲染

Example

try {
  await tuiCallEngine.stopRemoteView({userID: 'user1'});
  // success
} catch (error) {
  console.warn('stopRemoteView error:', error);
}

Parameters:

Name Type Description

params

Object

required

渲染远端视频配置

Properties

Name	Type	Description
`userID`	String	`required` 用户id

Returns:

Type: Promise

(async) setBlurBackground(blurLevel) → {Promise}

开关/设置背景虚化

注意: v3.0.5+ 支持，暂不支持 H5，后续支持。

Example

await tuiCallEngine.setBlurBackground(1);

Parameters:

Name	Type	Description
`blurLevel`	number	`required` 虚化等级, 0 - 表示关闭背景虚化。目前不支持 blurLevel 等级的设置，后续支持。使用时需要 blurLevel > 0

Returns:

Type: Promise

(async) setVirtualBackground(imagePath) → {Promise}

开关/设置图片背景虚化

注意: v3.0.5+ 支持，暂不支持 H5，后续支持。

Example

await tuiCallEngine.setVirtualBackground('https://xxx.png');

Parameters:

Name	Type	Description
`imagePath`	string	`required` 图片路径（可以是 url，也可以是相对路径）。imagePath = '' 表示关闭图片背景虚化

Returns:

Type: Promise

enableMultiDeviceAbility(enable) → {void}

开启/关闭 TUICallEngine 的多设备登录模式（尊享版套餐支持）

注意：v2.1.1+ 才支持。

Example

tuiCallEngine.enableMultiDeviceAbility(true);

Parameters:

Name	Type	Description
`enable`	boolean	`required` 开启、关闭多设备登录. 开启: true; 关闭: false; 默认: 关闭

Returns:

Type: void

(async) setSelfInfo(options) → {Promise.<void>}

设置当前用户基本信息（用户名、用户头像）

Example

// 设置当前用户用户名及用户头像
await TUICallEngine.setSelfInfo({
 nickName: '',     // 填写您的新用户名
 avatar: '',    // 填写您的新头像地址
})

Parameters:

Name Type Description

options

object

required

Properties

Name	Type	Description
`nickName`	string	`required` 用户名，必填
`avatar`	string	`required` 用户头像，必填 App 管理员可以通过即时通信 IM 控制台 > 用户自定义字段新增自定义资料字段用户自定义字段生效以后，用户可以调用 setSelfInfo 接口设置自定义资料

Returns:

Type: Promise.<void>

(async) setBeautyLevel(style, beautyLevel, whitenessLevel, ruddinessLevel) → {Promise}

支持 webrtc 的基础美颜

Example

await setBeautyLevel({
 type: TRTCBeautyStyle.TRTCBeautyStyleSmooth,
 beautyLevel: 0.3,
 whitenessLevel: 0.4,
 ruddinessLevel: 0.5,
})

Parameters:

Name	Type	Description
`style`	TRTCBeautyStyle	`required` 磨皮算法，有"光滑"(TRTCBeautyStyleSmooth=0)和"自然"(TRTCBeautyStyleNature=1)两种算法, 默认为 TRTCBeautyStyleNature
`beautyLevel`	number	`required` 美颜级别，取值范围 [0 - 9]，0表示关闭，1 - 9值越大，效果越明显。
`whitenessLevel`	number	`required` 美白级别，取值范围 [0 - 9]，0表示关闭，1 - 9值越大，效果越明显。
`ruddinessLevel`	number	`required` 红润级别，取值范围 [0 - 9]，0表示关闭，1 - 9值越大，效果越明显。

Returns:

Type: Promise

setLogLevel(level)

设置日志级别，低于 level 的日志将不会输出。

Example

tuiCallEngine.setLogLevel(0);

Parameters:

Name Type Description

Name	Type	Description
`level`	LOG_LEVEL	`required` 日志级别 0 普通级别，日志量较多，接入时建议使用 1 主要级别，SDK 输出关键信息，默认日志等级 2 告警级别，SDK 只输出告警和错误级别的日志 3 错误级别，SDK 只输出错误级别的日志 4 无日志级别，SDK 将不打印任何日志

level

LOG_LEVEL

required

日志级别

0 普通级别，日志量较多，接入时建议使用
1 主要级别，SDK 输出关键信息，默认日志等级
2 告警级别，SDK 只输出告警和错误级别的日志
3 错误级别，SDK 只输出错误级别的日志
4 无日志级别，SDK 将不打印任何日志

(async) getDeviceList(deviceType)

获取设备列表

Example

try {
  const devices = await tuiCallEngine.getDeviceList('camera'); // Get camera list
  console.log(devices);
} catch (error) {
  console.warn('getDeviceList error:', error);
}

Parameters:

Name Type Description

Name	Type	Description
`deviceType`	String	`required` 设备类型 'camera' 摄像头 'microphones' 麦克风，后续废弃 'microphones'。v3.0.0+ 支持传入 'microphone' 'speaker' 扬声器，v3.0.0+ 才支持该参数

deviceType

String

required

设备类型

'camera' 摄像头
'microphones' 麦克风，后续废弃 'microphones'。v3.0.0+ 支持传入 'microphone'
'speaker' 扬声器，v3.0.0+ 才支持该参数

(async) switchDevice(params)

切换摄像头或麦克风设备

Example

try {
  await tuiCallEngine.switchDevice({deviceType: 'camera', deviceId: cameras[0].deviceId}); // Switch device
  // success
} catch (error) {
  console.warn('switchDevice error:', error);
}

Parameters:

Name Type Description

params

ISwitchDeviceParams

required

Properties

Name Type Description

deviceType

string

required

需要切换的设备类型

'video' 摄像头, 后续废弃 'video'。v3.0.0+ 支持传入 'camera' 切换摄像头。
'audio' 麦克风, 后续废弃 'audio'。v3.0.0+ 支持传入 'microphone' 切换麦克风。
'speaker' 扬声器。

deviceId

string

required

需要切换的设备ID

摄像头设备标识通过 getDeviceList('camera') 获取。
麦克风设备标识通过 getDeviceList('microphone') 获取。
扬声器设备标识通过 getDeviceList('speaker') 获取。

Methods

(static) createInstance(options)

Example

Parameters:

Properties

(async) destroyInstance() → {Promise}

Example

Returns:

(async) login(params) → {Promise}

Example

Parameters:

Properties

Returns:

(async) logout() → {Promise}

Example

Returns:

on(eventName, callback, context)

Example

Parameters:

off(eventName, callback, context)

Example

Parameters:

(async) calls(params) → {Promise}

Example

Parameters:

Properties

Returns:

(async) join(params)

Example

Parameters:

Properties

(async) accept() → {Promise}

Example

Returns:

(async) reject() → {Promise}

Example

Returns:

(async) hangup() → {Promise}

Example

Returns:

(async) openCamera(videoViewDomID, isFrontCameraopt) → {Promise}

Example

Parameters:

Returns:

(async) closeCamera() → {Promise}

Example

Returns:

(async) switchCamera(cameraPosition)

Example

Parameters:

(async) setVideoQuality(profile) → {Promise}

Example

Parameters:

Returns:

(async) setVideoRenderParams(params)

Example

Parameters:

Properties

(async) openMicrophone() → {Promise}

Example

Returns:

(async) closeMicrophone() → {Promise}

Example

Returns:

(async) startRemoteView(params) → {Promise}

Example

Parameters:

Properties

Returns:

(async) stopRemoteView(params) → {Promise}

Example

Parameters:

Properties

Returns:

(async) setBlurBackground(blurLevel) → {Promise}

Example

Parameters:

Returns:

(async) setVirtualBackground(imagePath) → {Promise}