TUICallEngine

TUICallEngine

tuicall-engine-webrtc 是基于腾讯云 即时通信 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
tuiCallEngine.destroyInstance().then(() => {
  //success
}).catch(error => {
  console.warn('destroyInstance error:', error)
});
Returns:
Type
Promise

setLogLevel(level)

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

Example
tuiCallEngine.setLogLevel(0);
Parameters:
Name Type Description
level LOG_LEVEL required

日志级别

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

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) init() → {Promise}

login() 方法的别名接口,参数一致

Returns:
Type
Promise

(async) login(params) → {Promise}

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

Example
let promise = tuiCallEngine.login({userID: 'your userID', userSig: 'your userSig'});
promise.then(() => {
  //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
let promise = tuiCallEngine.logout();
promise.then(() => {
  //success
}).catch(error => {
  console.warn('logout error:', error)
});
Returns:
Type
Promise

(async) call(params) → {Promise}

C2C邀请通话,被邀请方会收到 TUICallEvent.INVITED 事件

  • 注意:离线推送仅适用于终端(Android 或 iOS),Web 和 微信小程序不支持。
Example
let promise = tuiCallEngine.call({userID: 'user1', type: 1});
promise.then(() => {
  //success
}).catch(error => {
  console.warn('call error:', error)
});
Parameters:
Name Type Description
params Object required

拨打通话配置

Properties
Name Type Description
userID String required

被邀请方 userID

type Number required

0-未知, 1-语音通话,2-视频通话

timeout Number

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

roomID Number

数字房间号, 范围 [1, 2147483647]。支持 v1.4.2+ 版本。

userData String

扩展字段: 用于在邀请信令中增加扩展信息。支持 v1.4.2+ 版本。

offlinePushInfo Object

自定义离线消息推送(选填)-- 需 tsignaling 版本 >= 0.8.0

name Type Description
title string 离线推送标题(选填)
description string 离线推送内容(选填)
androidOPPOChannelID string 离线推送设置 OPPO 手机 8.0 系统及以上的渠道 ID(选填)
extension string 离线推送透传内容(选填)(tsignaling 版本 >= 0.9.0)
Returns:
Type
Promise

(async) groupCall(params) → {Promise}

IM群组邀请通话,被邀请方会收到 TUICallEvent.INVITED 事件
注意:离线推送仅适用于终端(Android 或 iOS),Web 和 微信小程序不支持。

Example
let promise = tuiCallEngine.groupCall({userIDList: ['user1', 'user2'], type: 1, groupID: 'IM群组 ID'});
promise.then(() => {
  //success
}).catch(error => {
  console.warn('groupCall error:', error)
});
Parameters:
Name Type Description
params Object required

群聊拨打通话配置

Properties
Name Type Description
userIDList Array required

邀请列表

type Number required

0-未知, 1-语音通话,2-视频通话

groupID String required

IM 群组 ID

timeout Number

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

roomID Number

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

userData String

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

offlinePushInfo Object

自定义离线消息推送(选填)-- 需 tsignaling 版本 >= 0.8.0

name Type Description
title string 离线推送标题(选填)
description string 离线推送内容(选填)
androidOPPOChannelID string 离线推送设置 OPPO 手机 8.0 系统及以上的渠道 ID (选填)
extension string 离线推送透传内容(选填)(tsignaling 版本 >= 0.9.0)
Returns:
Type
Promise

(async) joinInGroupCall(params)

主动加入此次群组通话。
使用场景:群组内用户主动加入此次群组通话使用。

Example
const params = {
    roomID: 123,
    type: 1,
    groupID: '111'
};
tuiCallEngine.joinInGroupCall(params).then(() => {
    // success
}).catch(error => {
    console.error('joinInGroupCall error:', error);
});
Parameters:
Name Type Description
params Object required

中途加入配置

Properties
Name Type Description
roomID Number required

进入的房间号,此次通话的音视频房间 ID,目前仅支持数字房间号,后续版本会支持字符串房间号

type Number required

通话类型,通话的媒体类型,比如:1 - 语音通话,2 - 视频通话

groupID String required

此次群组通话的群 ID

(async) inviteUser(params)

邀请他人,邀请用户加入此次群组通话。
使用场景:一个群组通话中的用户主动邀请其他人时使用。

  • 被叫接通后处于通话中, 才能邀请他人。例如:A 呼叫 B,B 接通后,B 才能邀请他人。
  • 主叫处于呼叫中、通话中时,都可以邀请他人。例如:A 呼叫 B,B 是否接通,A 都可以邀请他人。
Example
const userIDList = ['jack', 'john'];
const params = {
    userIDList
};
tuiCallEngine.inviteUser(params).then(() => {
    // success
}).catch(error => {
    console.error('inviteUser error:', error);
});
Parameters:
Name Type Description
params Object required

邀请他人配置

Properties
Name Type Description
userIDList Array required

邀请列表

offlinePushInfo Object

自定义离线消息推送(选填)-- 需 tsignaling 版本 >= 0.8.0

name Type Description
title string 离线推送标题(选填)
description string 离线推送内容(选填)
androidOPPOChannelID string 离线推送设置 OPPO 手机 8.0 系统及以上的渠道 ID(选填)
extension string 离线推送透传内容(选填)(tsignaling 版本 >= 0.9.0)

(async) accept() → {Promise}

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

Example
tuiCallEngine.on(TUICallEvent.INVITED, () => {
  tuiCallEngine.accept().then(() => {
    //success
  }).catch(error => {
    console.warn('accept error:', error);
  });
});
Returns:
Type
Promise

(async) reject() → {Promise}

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

Example
tuiCallEngine.on(TUICallEvent.INVITED, () => {
  tuiCallEngine.reject().then(() => {
    //success
  }).catch(error => {
    console.warn('reject error:', error);
  });
});
Returns:
Type
Promise

(async) hangup() → {Promise}

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

  1. 当您处于通话中,可以调用该接口结束通话
  2. 当未拨通时, 可用来取消通话
Example
tuiCallEngine.hangup().then(() => {
   // success
 }).catch(error => {
    console.warn('hangup error:', error);
 });
Returns:
Type
Promise

(async) startRemoteView(params) → {Promise}

启动远端画面渲染。请在收到 USER_VIDEO_AVAILABLE 事件且事件里的 isVideoAvailable 参数为 true 时,可调用该接口将远端用户的摄像头数据渲染到指定的 dom id 节点里。

Example
let options = {
  objectFit: 'contain'
}
let promise = tuiCallEngine.startRemoteView({userID: 'user1', videoViewDomID: 'video_1', options});
promise.then(() => {
  // success
}).catch(error => {
  console.warn('startRemoteView error:', error)
});
Parameters:
Name Type Description
params Object required

渲染远端视频配置

Properties
Name Type Description
userID String required

用户id

videoViewDomID String required

该用户数据将渲染到该dom id节点里

options String

播放选项

Properties
Name Type Description
objectFit String required

视频画面显示模式

  • contain 优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频尺寸与显示视窗尺寸不一致,在保持长宽比的前提下,将视频进行缩放后填满视窗,缩放后的视频四周会有一圈黑边。

  • cover 优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,则视频流会按照显示视窗的比例进行周边裁剪或图像拉伸后填满视窗。

  • fill 保证视窗被填满的同时保证视频内容全部显示,但是不保证视频尺寸比例不变。视频的宽高会被拉伸至和视窗尺寸一致。

    播放视频流默认使用 cover 模式。

muted Boolean required

是否需要 mute 声音

  • 对于本地流,muted 默认为 true,防止播放从麦克风采集的声音。
mirror Boolean required

是否开启视频镜像预览 注意

  • 对于本地音视频流,默认开启镜像预览。建议在使用前置摄像头时开启镜像,使用后置摄像头时关闭镜像。
  • 对于远端音视频流,默认关闭镜像预览。
  • 对于屏幕分享流,不支持开启镜像预览。
  • 该参数只对本地预览有效,推流是没有镜像效果的。
Returns:
Type
Promise

(async) stopRemoteView(params) → {Promise}

停止远端画面渲染

Example
let promise = tuiCallEngine.stopRemoteView({userID: 'user1'});
promise.then(() => {
  //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) startLocalView(params) → {Promise}

启动本地画面渲染。

Deprecated:
  • 在v1.3.2版本后逐步废除,可调用 [openCamera](https://web.sdk.qcloud.com/component/trtccalling/doc/TUICallEngine/web/zh-cn/TUICallEngine.html#openCamera) 打开摄像头并预览。
Example
let promise = tuiCallEngine.startLocalView({userID: 'user1', videoViewDomID: 'video_1'});
promise.then(() => {
  // success
}).catch(error => {
  console.warn('startLocalView error:', error)
});
Parameters:
Name Type Description
params Object required

渲染本地视频配置

Properties
Name Type Description
userID String required

用户id

videoViewDomID String required

该用户数据将渲染到该dom id节点里

options String

播放选项

Properties
Name Type Description
objectFit String required

视频画面显示模式

  • contain 优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频尺寸与显示视窗尺寸不一致,在保持长宽比的前提下,将视频进行缩放后填满视窗,缩放后的视频四周会有一圈黑边。

  • cover 优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,则视频流会按照显示视窗的比例进行周边裁剪或图像拉伸后填满视窗。

  • fill 保证视窗被填满的同时保证视频内容全部显示,但是不保证视频尺寸比例不变。视频的宽高会被拉伸至和视窗尺寸一致。

    播放视频流默认使用 cover 模式。

muted String required

是否需要 mute 声音

  • 对于本地流,muted 默认为 true,防止播放从麦克风采集的声音。
mirror String required

是否开启视频镜像预览 注意

  • 对于本地音视频流,默认开启镜像预览。建议在使用前置摄像头时开启镜像,使用后置摄像头时关闭镜像。
  • 对于远端音视频流,默认关闭镜像预览。
  • 对于屏幕分享流,不支持开启镜像预览。
  • 该参数只对本地预览有效,推流是没有镜像效果的。
Returns:
Type
Promise

(async) stopLocalView(params) → {Promise}

停止远端画面渲染

Deprecated:
  • 在v1.3.2版本后逐步废除,可调用 [closeCamera](https://web.sdk.qcloud.com/component/trtccalling/doc/TUICallEngine/web/zh-cn/TUICallEngine.html#closeCamera) 打开摄像头并预览。
Example
let promise = tuiCallEngine.stopLocalView({userID: 'user1'});
promise.then(() => {
  //success
}).catch(error => {
  console.warn('stopLocalView error:', error)
});
Parameters:
Name Type Description
params Object required

渲染本地视频配置

Properties
Name Type Description
userID String required

用户id TODO: 参数可以不填, 待后续确认

Returns:
Type
Promise

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

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

Example
// 'localView' 是 div 标签对应的 id 值
tuiCallEngine.openCamera('localView').then(() => {
  // success
}).catch(error => {
  console.warn('openCamera error:', error)
});
Parameters:
Name Type Description
videoViewDomID string required

该用户数据将渲染到该 dom id 节点里

isFrontCamera boolean

前后置摄像头,true 表示前置摄像头。仅支持移动端上使用

Returns:

注意:

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

(async) closeCamera() → {Promise}

您可以调用该接口关闭摄像头,处于通话中的用户会收到 USER_VIDEO_AVAILABLE 回调

Example
tuiCallEngine.closeCamera().then(() => {
  // success
}).catch(error => {
  console.warn('closeCamera error:', error)
});
Returns:
Type
Promise

(async) openMicrophone() → {Promise}

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

Example
tuiCallEngine.openMicrophone().then(() => {
  // success
}).catch(error => {
  console.warn('openMicrophone error:', error)
});
Returns:
Type
Promise

(async) closeMicrophone() → {Promise}

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

Example
tuiCallEngine.closeMicrophone().then(() => {
  // success
}).catch(error => {
  console.warn('closeMicrophone error:', error)
});
Returns:
Type
Promise

(async) setVideoQuality(profile) → {Promise}

设置视频分辨率

Example
const profile = '720p';
// 设置视频质量为 720p
tuiCallEngine.setVideoQuality(profile).then(() => {
  // 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)

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

Parameters:
Name Type Description
params ITRTCRenderParams required

显示参数

Properties
Name Type Description
userID String required

用户 ID。不传入 userID 时, 对所有预览进行显示模式设置(包括:本地预览和所有的远端预览)

objectFit String required

视频画面显示模式。目前仅支持: 'contain' | 'cover' | 'fill'

  • contain 优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频尺寸与显示视窗尺寸不一致,在保持长宽比的前提下,将视频进行缩放后填满视窗,缩放后的视频四周会有一圈黑边。v3.0.0 废弃
  • cover 优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,则视频流会按照显示视窗的比例进行周边裁剪或图像拉伸后填满视窗。
  • fill 保证视窗被填满的同时保证视频内容全部显示,但是不保证视频尺寸比例不变。视频的宽高会被拉伸至和视窗尺寸一致。 播放视频流默认使用 cover 模式。
muted String required

是否需要 mute 声音, v3.0.0 废弃

  • 对于本地流,muted 默认为 true,防止播放从麦克风采集的声音。
mirror TRTCVideoMirrorType required

是否开启视频镜像预览

rotation TRTCVideoRotation required

视频画面旋转方向 注意

  • 对于本地音视频流,默认开启镜像预览。建议在使用前置摄像头时开启镜像,使用后置摄像头时关闭镜像。
  • 对于远端音视频流,默认关闭镜像预览。
  • 对于屏幕分享流,不支持开启镜像预览。
  • 该参数只对本地预览有效,推流是没有镜像效果的。

(async) switchCallMediaType(newMediaType)

当前通话类型切换

  • 仅支持1v1通话过程中使用
  • 失败监听 ERROR 事件,code: 60001
Example
tuiCallEngine.switchCallMediaType(1).then(() => { // 视频通话切换语音通话
  // success
}).catch(error => {
  console.warn('switchCallMediaType error:', error)
});
Parameters:
Name Type Description
newMediaType String required

通话类型

  • 1 语音通话
  • 2 视频通话

(async) getDeviceList(deviceType)

获取设备列表

Example
tuiCallEngine.getDeviceList('camera').then((devices)=>{  // 获取摄像头列表
 console.log(devices)
}).catch(error => {
  console.warn('getDeviceList error:', error)
});
Parameters:
Name Type Description
deviceType String required

设备类型

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

(async) switchCamera(cameraPosition)

切换前后置摄像头
Note: v3.0.0+ 支持,且该接口仅在移动端使用生效。

Example
await tuiCallEngine.switchCamera(TUICallCameraPosition.FRONT); // 切换前置摄像头
await tuiCallEngine.switchCamera(TUICallCameraPosition.BACK); // 切换后置摄像头
Parameters:
Name Type Description
cameraPosition TUICallCameraPosition required

摄像头类型

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

(async) switchDevice(params)

切换摄像头或麦克风设备

Example
let promise = tuiCallEngine.switchDevice({deviceType: 'camera', deviceId: cameras[0].deviceId}) // 切换设备
promise.then(() => {
  // 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' 扬声器, v3.0.0+ 支持
deviceId string required

需要切换的设备ID

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

(async) setSelfInfo(params)

设置自己的昵称或头像

Example
let promise = tuiCallEngine.setSelfInfo({
    nickName: 'Jack',
    avatar:'http(s)://url/to/image.jpg'
});
promise.then(() => {
    // success
}).catch(error => {
    console.warn('setSelfInfo error:', error);
});
Parameters:
Name Type Description
params ISwitchDeviceParams required
Properties
Name Type Description
nickName string required

昵称

avatar string required

头像地址

enableMultiDeviceAbility(enable) → {void}

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

  • 注意:v2.1.1+ 才支持。
Example
tuiCallEngine.enableMultiDeviceAbility(true);
Parameters:
Name Type Description
enable boolean required

开启、关闭多设备登录. 开启: true; 关闭: false; 默认: 关闭

Returns:
Type
void

(async) enableAIVoice(enable)

开启/关闭 AI 降噪

Example
let promise = tuiCallEngine.enableAIVoice(true);
promise.then(() => {
  // success
}).catch(error => {
  console.warn('enableAIVoice error:', error)
});
Parameters:
Name Type Description
enable boolean required

开启、关闭 AI 降噪. true 表示开启; false 表示关闭

(async) setBlurBackground(blurLevel) → {Promise}

开关/设置背景虚化
Note: 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}

开关/设置图片背景虚化
Note: v3.0.5+ 支持,暂不支持 H5,后续支持。

Example
await tuiCallEngine.setVirtualBackground('https://xxx.png');
Parameters:
Name Type Description
imagePath string required

图片路径(可以是 url,也可以是相对路径)。imagePath = '' 表示关闭图片背景虚化

Returns:
Type
Promise

getTRTCCloudInstance()

获取 TRTCCloud 实例
Note: v3.1.3+ 支持

Example
tuiCallEngine.getTRTCCloudInstance();