即时通信 IM TUICallEngine

TUICallEngine API 简介
TUICallEngine API 是音视频通话组件的无 UI 接口，如果 TUICallKit 的交互并不满足您的需求，您可以使用这套接口自己封装交互。
API 概览
API
描述
﻿createInstance﻿
创建 TUICallEngine 实例（单例模式）
﻿destroyInstance﻿
销毁 TUICallEngine 实例（单例模式）
﻿init﻿
完成音视频通话基础能力的鉴权
﻿addObserver﻿
增加事件回调
﻿removeObserver﻿
移除回调接口
﻿calls﻿
发起单人或多人通话
﻿accept﻿
接听通话
﻿reject﻿
拒绝通话
﻿hangup﻿
结束通话
﻿inviteUser﻿
在通话中，邀请其他人加入
﻿join﻿
主动加入通话
﻿startRemoteView﻿
开始订阅远端用户视频流
﻿stopRemoteView﻿
停止订阅远端用户视频流
﻿openCamera﻿
开启摄像头
﻿closeCamera﻿
关闭摄像头
﻿switchCamera﻿
切换前后摄像头
﻿openMicrophone﻿
打开麦克风
﻿closeMicrophone﻿
关闭麦克风
﻿selectAudioPlaybackDevice﻿
选择音频播放设备（听筒/扬声器）
﻿setSelfInfo﻿
设置用户的昵称、头像
﻿enableMultiDeviceAbility﻿
开启/关闭 TUICallEngine 的多设备登录模式 （群组通话版套餐 支持）
﻿setVideoRenderParams﻿
设置用户视频画面的渲染模式
﻿setVideoEncoderParams﻿
设置视频编码的编码参数
﻿getTRTCCloudInstance﻿
高级接口，用于接入第三方美颜等
﻿setBeautyLevel﻿
设置美颜级别，支持关闭默认美颜
API 详情
createInstance
创建 TUICallEngine 的单例。
- (TUICallEngine *)createInstance;
destroyInstance
销毁 TUICallEngine 的单例。
- (void)destroyInstance;
init
初始化函数，请在使用所有功能之前先调用该函数，以便完成包含通话服务鉴权在内初始化动作。
- (void)init:(NSString *)sdkAppID userId:(NSString *)userId userSig:(NSString *)userSig succ:(TUICallSucc)succ fail:(TUICallFail)fail;
参数如下表所示：
参数
类型
含义
sdkAppID
NSString
您可以在实时音视频控制台 > 应用管理 > 应用信息中查看 SDKAppID
userId
NSString
当前用户的 ID，字符串类型，只允许包含英文字母（a-z 和 A-Z）、数字（0-9）、连词符（-）和下划线（_）
userSig
NSString
腾讯云设计的一种安全保护签名，获取方式请参见 如何计算及使用 UserSig
succ
TUICallSucc
成功回调
fail
TUICallFail
失败回调
addObserver
添加回调接口，您可以通过这个接口，监听 TUICallObserver 相关的事件回调。
- (void)addObserver:(id<TUICallObserver>)observer;
removeObserver
移除回调接口。
- (void)removeObserver:(id<TUICallObserver>)observer;
calls
发起通话。
﻿
- (void)calls:(NSArray<NSString *> *)userIdList callMediaType:(TUICallMediaType)callMediaType params:(TUICallParams *)params succ:(TUICallSucc)succ fail:(TUICallFail)fail;
参数如下表所示：
参数
类型
含义
userIdList
 NSArray
目标用户的 userId 列表
callMediaType
﻿TUICallMediaType﻿
通话的媒体类型，例如视频通话、语音通话
params
﻿TUICallParams﻿
通话扩展参数，例如：房间号、通话邀请超时时间，离线推送自定义内容等
accept
接受当前通话，当您作为被叫收到 onCallReceived() 的回调时，可以调用该函数接听来电。
- (void)accept:(TUICallSucc)succ fail:(TUICallFail)fail;
reject
拒绝当前通话，当您作为被叫收到 onCallReceived() 的回调时，可以调用该函数拒绝来电。
- (void)reject:(TUICallSucc)succ fail:(TUICallFail)fail;
hangup
挂断当前通话，当您处于通话中，可以调用该函数结束通话。
- (void)hangup:(TUICallSucc)succ fail:(TUICallFail)fail;
inviteUser
邀请用户加入此次群组通话。
使用场景：一个群组通话中的用户主动邀请其他人时使用。
- (void)inviteUser:(NSArray<NSString *> *)userIdList params:(TUICallParams *)params succ:(void(^)(NSArray <NSString *> *userIdList))succ fail:(TUICallFail)fail
参数
类型
含义
userIdList
NSArray
目标用户的 userId 列表
params
﻿TUICallParams﻿
通话参数扩展字段，例如：离线推送自定义内容
succ
TUICallSucc
成功回调
fail
TUICallFail
失败回调
join
主动加入通话。
- (void)join:(NSString *)callId succ:(TUICallSucc)succ fail:(TUICallFail)fail
参数如下表所示：
参数
类型
含义
callId
NSString
此次通话的唯一 ID
startRemoteView
设置显示视频画面的 View 对象
- (void)startRemoteView:(NSString *)userId videoView:(TUIVideoView *)videoView onPlaying:(void(^)(NSString *userId))onPlaying onLoading:(void(^)(NSString *userId))onLoading onError:(void(^)(NSString *userId, int code, NSString *errMsg))onError;
参数
类型
含义
userId
NSString
目标用户的 userId
videoView
TUIVideoView
待渲染的视图
stopRemoteView
停止订阅远端用户的视频数据。
- (void)stopRemoteView:(NSString *)userId;
参数
类型
含义
userId
NSString
目标用户的 userId
openCamera
开启摄像头。
- (void)openCamera:(TUICamera)camera videoView:(TUIVideoView *)videoView succ:(TUICallSucc)succ fail:(TUICallFail)fail;
参数
类型
含义
camera
﻿TUICamera﻿
前置/后置 摄像头
videoView
TUIVideoView
待渲染的视图
succ
TUICallSucc
成功回调
fail
TUICallFail
失败回调
closeCamera
关闭摄像头。
- (void)closeCamera;
switchCamera
切换前后摄像头。
- (void)switchCamera:(TUICamera)camera;
参数
类型
含义
camera
﻿TUICamera﻿
前置/后置摄像头
openMicrophone
打开麦克风。
- (void)openMicrophone:(TUICallSucc)succ fail:(TUICallFail)fail;
closeMicrophone
关闭麦克风。
- (void)closeMicrophone;
selectAudioPlaybackDevice
选择音频播放设备。
目前支持听筒、扬声器，在通话场景中，可以使用这个接口来开启/关闭免提模式。
- (void)selectAudioPlaybackDevice:(TUIAudioPlaybackDevice)device;
参数
类型
含义
device
﻿TUIAudioPlaybackDevice﻿
听筒/扬声器
setSelfInfo
设置用户昵称、头像。
用户昵称不能超过500字节，用户头像必须是 URL 格式。
- (void)setSelfInfo:(NSString *_Nullable)nickname avatar:(NSString *_Nullable)avatar succ:(TUICallSucc)succ fail:(TUICallFail)fail;
参数
类型
含义
nickname
NSString
用户昵称
avatar
NSString
用户头像（格式为 URL）
succ
TUICallSucc
成功回调
fail
TUICallFail
失败回调
enableMultiDeviceAbility
开启/关闭 TUICallEngine 的多设备登录模式（群组通话版套餐 支持）。
- (void)enableMultiDeviceAbility:(BOOL)enable succ:(TUICallSucc)succ fail:(TUICallFail)fail;
setVideoRenderParams
设置用户视频画面的渲染模式。
- (void)setVideoRenderParams:(NSString *)userId params:(TUIVideoRenderParams *)params succ:(TUICallSucc)succ fail:(TUICallFail)fail;
参数
类型
含义
userId

NSString
目标用户的 userId
params
﻿TUIVideoRenderParams﻿
视频画面渲染参数，例如：画面旋转角度、填充模式
succ
TUICallSucc
成功回调
fail
TUICallFail
失败回调
setVideoEncoderParams
设置视频编码的参数。
该设置能够决定远端用户看到的画面质量，同时也能决定云端录制出的视频文件的画面质量。
- (void)setVideoEncoderParams:(TUIVideoEncoderParams *)params succ:(TUICallSucc)succ fail:(TUICallFail)fail;
参数
类型
含义
params
﻿TUIVideoEncoderParams﻿
视频编码的参数，例如：分辨率、视频宽高比
succ
TUICallSucc
成功回调
fail
TUICallFail
失败回调
getTRTCCloudInstance
高级接口。
用于接入第三方美颜等。
- (TRTCCloud *)getTRTCCloudInstance;
setBeautyLevel
设置美颜级别，支持关闭默认美颜。
﻿
- (void)setBeautyLevel:(CGFloat)level succ:(TUICallSucc)succ fail:(TUICallFail)fail;
参数如下表所示：
参数
类型
含义
level
CGFloat
美颜级别，美颜级别，取值范围 0 - 9； 0 表示关闭，9 表示效果最明显。
succ
TUICallSucc
成功回调
fail
TUICallFail
失败回调
废弃接口
call
拨打电话（1v1通话）。注意：v2.9+版本废弃，建议使用 calls 接口。
注意：
字符串房间号目前只支持 Android 和 iOS 平台，Web、小程序、Flutter、Uniapp 等其他平台后续支持，敬请期待！
- (void)call:(NSString *)userId callMediaType:(TUICallMediaType)callMediaType params:(TUICallParams *)params succ:(TUICallSucc)succ fail:(TUICallFail)fail
参数如下表所示：
参数
类型
含义
userId
NSString
目标用户的 userId
callMediaType
﻿TUICallMediaType﻿
通话的媒体类型，例如视频通话、语音通话
params
﻿TUICallParams﻿
通话参数扩展字段，例如：房间号、通话邀请超时时间，离线推送自定义内容等
succ
TUICallSucc
成功回调
fail
TUICallFail
失败回调
ignore
忽略当前通话，当您作为被叫收到 onCallReceived() 的回调时，可以调用该函数忽略来电，此时主叫会收到onUserLineBusy的回调。注意：v2.9+版本废弃，针对 calls 发起的通话不生效，建议使用 reject 接口。
- (void)ignore:(TUICallSucc)succ fail:(TUICallFail)fail;
groupCall
发起群组通话。注意：v2.9+版本废弃，建议使用 calls 接口。
注意：
使用群组通话前需要创建 IM 群组，如果已经创建，请忽略；
字符串房间号目前只支持 Android 和 iOS 平台，Web、小程序、Flutter、Uniapp 等其他平台后续支持，敬请期待！
- (void)groupCall:(NSString *)groupId userIdList:(NSArray <NSString *> *)userIdList callMediaType:(TUICallMediaType)callMediaType params:(TUICallParams *)params succ:(TUICallSucc)succ fail:(TUICallFail)fail
参数
类型
含义
groupId
NSString
此次群组通话的群 ID
userIdList
NSArray
目标用户的 userId 列表
callMediaType
﻿TUICallMediaType﻿
通话的媒体类型，例如视频通话、语音通话
params
﻿TUICallParams﻿
通话参数扩展字段，例如：房间号、通话邀请超时时间，离线推送自定义内容等
succ
TUICallSucc
成功回调
fail
TUICallFail
失败回调
joinInGroupCall
主动加入此次群组通话。注意：v2.9+版本废弃，建议使用 join 接口。
使用场景：群组内用户主动加入此次群组通话使用。
- (void)joinInGroupCall:(TUIRoomId *)roomId groupId:(NSString *)groupId callMediaType:(TUICallMediaType)callMediaType succ:(TUICallSucc)succ fail:(TUICallFail)fail;
参数
类型
含义
roomId
﻿TUIRoomId﻿
此次通话的音视频房间 ID
groupId
NSString
此次群组通话的群 ID
callMediaType
﻿TUICallMediaType﻿
通话的媒体类型，例如视频通话、语音通话
succ
TUICallSucc
成功回调
fail
TUICallFail
失败回调
switchCallMediaType
切换视频通话到语音通话。注意：v2.9+版本废弃，针对 calls 发起的通话不生效；
- (void)switchCallMediaType:(TUICallMediaType)newType;
参数
类型
含义
callMediaType
﻿TUICallMediaType﻿
通话的媒体类型，例如视频通话、语音通话

API	描述
createInstance	创建 TUICallEngine 实例（单例模式）
destroyInstance	销毁 TUICallEngine 实例（单例模式）
init	完成音视频通话基础能力的鉴权
addObserver	增加事件回调
removeObserver	移除回调接口
calls	发起单人或多人通话
accept	接听通话
reject	拒绝通话
hangup	结束通话
inviteUser	在通话中，邀请其他人加入
join	主动加入通话
startRemoteView	开始订阅远端用户视频流
stopRemoteView	停止订阅远端用户视频流
openCamera	开启摄像头
closeCamera	关闭摄像头
switchCamera	切换前后摄像头
openMicrophone	打开麦克风
closeMicrophone	关闭麦克风
selectAudioPlaybackDevice	选择音频播放设备（听筒/扬声器）
setSelfInfo	设置用户的昵称、头像
enableMultiDeviceAbility	开启/关闭 TUICallEngine 的多设备登录模式（群组通话版套餐支持）
setVideoRenderParams	设置用户视频画面的渲染模式
setVideoEncoderParams	设置视频编码的编码参数
getTRTCCloudInstance	高级接口，用于接入第三方美颜等
setBeautyLevel	设置美颜级别，支持关闭默认美颜

参数	类型	含义
sdkAppID	NSString	您可以在实时音视频控制台 > 应用管理 > 应用信息中查看 SDKAppID
userId	NSString	当前用户的 ID，字符串类型，只允许包含英文字母（a-z 和 A-Z）、数字（0-9）、连词符（-）和下划线（_）
userSig	NSString	腾讯云设计的一种安全保护签名，获取方式请参见如何计算及使用 UserSig
succ	TUICallSucc	成功回调
fail	TUICallFail	失败回调

TUICallEngine

本页目录：

TUICallEngine API 简介

API 概览

API 详情

createInstance

destroyInstance

init

addObserver

removeObserver

calls

accept

reject

hangup

inviteUser

join

startRemoteView

stopRemoteView

openCamera

closeCamera

switchCamera

openMicrophone

closeMicrophone

selectAudioPlaybackDevice

setSelfInfo

enableMultiDeviceAbility

setVideoRenderParams

setVideoEncoderParams

getTRTCCloudInstance

setBeautyLevel

废弃接口

call

ignore

groupCall

joinInGroupCall

switchCallMediaType