DingRTCClient_音视频通信(RTC)-阿里云帮助中心

DingRTCClient 提供音视频通话的核心功能，比如加入频道、发布和订阅音视频轨道等。

您可以通过 createClient 创建一个 Client 对象。一个 Client 对象代表一个本地客户端。

属性列表

属性	类型	描述	支持的最低版本
channelName	string	频道名称。如果本地用户没有加入频道，该属性值为 undefined。	3.0.0
connectionState	ConnectionState	sdk 实例与服务器连接状态。	3.0.0
localTracks	LocalTrack[]	保存当前正在发布的本地轨道对象列表。调用 publish 成功后，发布的轨道对象会自动添加到这个列表中。调用 unpublish 成功后，取消发布的轨道对象会自动从这个列表中移除。	3.0.0
remoteUsers `readonly`	RemoteUser[]	远端用户信息列表，包含频道中各个远端用户的用户 ID 和轨道信息。如果本地用户没有加入频道，则该列表为空。	3.0.0
userId`readonly`	string	本地用户的用户 ID。如果本地用户没有加入频道，该属性值为 undefined。	3.0.0

接口列表

接口	描述	支持的最低版本
getLocalAudioStats()	获取本地音频相关信息。	3.0.0
getLocalVideoStats()	获取本地视频相关信息。	3.0.0
getRemoteVideoStats()	获取远端用户的视频统计信息。	3.0.0
join()	加入频道,在同一个频道内的用户可以互相通话。调用该方法加入频道时，本地会触发 "connection-state-change" 回调。本端加入频道成功后，远端会触发 "user-joined" 回调。	3.0.0
leave()	离开频道，即挂断或退出通话。调用该方法离开频道时，本地会触发 "connection-state-change" 回调。远端会触发 "user-left" 回调。	3.0.0
publish()	发布本地音视频轨道至频道中。发布音视频轨道之后，远端会触发 "user-published" 回调。	3.0.0
unpublish()	取消发布本地音视频轨道。取消发布音视频轨道之后，远端会触发 "user-unpublished" 回调。	3.0.0
setRemoteDefaultVideoStreamType()	设置订阅所有远端用户的视频类型。如果远端用户开启了双流模式，本地用户调用 subscribe 后会直接订阅本方法中 streamType 参数所指定的流类型。如不设置，默认订阅大流	3.0.0
setRemoteVideoStreamType()	设置订阅特定远端用户的视频类型。	3.0.0
subscribe()	订阅远端用户的音视频轨道。	3.0.0
unsubscribe()	取消订阅远端用户的音视频轨道。	3.0.0
batchSubscribe()	批量订阅远端用户的音视频轨道。	3.1.0
batchUnsubscribe()	批量取消订阅远端用户的音视频轨道。	3.1.0
off()	取消一个指定事件的监听回调函数。	3.0.0
on()	监听一个指定事件并设置回调函数。	3.0.0
once()	监听一个指定事件一次，回调函数触发后移除。	3.0.0
removeAllListeners()	取消该对象指定事件或所有事件上的监听回调。	3.0.0

事件列表

事件	事件参数	描述	支持的最低版本
"connection-state-change"	(curState:ConnectionState, revState:ConnectionState, reason?:DisconnectedReason) => void	SDK 与服务器的连接状态发生改变回调。	3.0.0
"media-reconnect-end"	(uid: string) => void	SDK 重新建立媒体连接（用于发布和订阅）结束的回调。	3.0.0
"media-reconnect-start"	(uid: string) => void	SDK 开始尝试重新建立媒体连接（用于发布和订阅）的回调。	3.0.0
"stream-type-changed"	(uid: string, streamType:RemoteStreamType) => void	订阅的视频流类型发生改变回调。视频流类型改变指视频大流（高码率、高分辨率）变为视频小流（低码率、低分辨率），或视频小流变为视频大流。	3.0.0
"user-info-updated"	(uid: string, msg: 'mute-audio' \| 'mute-video' \| 'unmute-audio' \| 'unmute-video') => void	该回调用于提示用户状态变化。在大部分情况下，你只需要监听 user-published 和 user-unpublished 就可以完成订阅、取消订阅、展示远端用户是否打开了摄像头和麦克风等工作，无需特别关注实际用户状态的变化，SDK 会自动处理用户状态变化。	3.0.0
"user-joined"	(user:RemoteUser) => void	远端用户或主播加入频道回调。	3.0.0
"user-left"	(user:RemoteUser) => void	远端用户或主播离开频道回调。	3.0.0
"user-published"	(user:RemoteUser, mediaType:TrackMediaType, auxiliary?: boolean) => void	该回调通知远端用户发布了新的音频轨道或者视频轨道。你可以在该回调中订阅并播放远端用户的音视频轨道。	3.0.0
"user-unpublished"	(user:RemoteUser, mediaType:TrackMediaType, auxiliary?: boolean) => void	该回调通知远端用户取消发布音频轨道或者视频轨道。	3.0.0
"volume-indicator"	(uids: string[]) => void	提示频道内正在说话的远端用户列表，三人及以上时自动开启。 uids 正在说话人的uid，第一个为音量最高的人，列表为空时代表无人在说话。	3.0.0
"network-quality"	(uplinkNetworkQuality:NetworkQuality, downlinkNetworkQuality:NetworkQuality) => void	客户端侧网络质量报告回调，加入频道后每2秒触发一次,仅用来当参考值。

接口详情

getLocalAudioStats()

获取本地音频相关信息。

类型签名

getLocalAudioStats(): LocalAudioStates;

LocalAudioStates

getLocalVideoStats()

获取本地视频相关信息。

类型签名

getLocalVideoStats(): LocalVideoStatesMap;

LocalVideoStatesMap

getRemoteVideoStats()

获取远端用户的视频统计信息。

类型签名

getRemoteVideoStats(): RemoteVideoStatesMap;

RemoteVideoStatesMap

join()

加入频道,在同一个频道内的用户可以互相通话。

调用该方法加入频道时，本地会触发 "connection-state-change" 回调。

本端加入频道成功后，远端会触发 "user-joined" 回调。

类型签名

join(joinInfo: JoinParam): Promise<{
  remoteUsers: RemoteUser[];
  timeLeft: number;
}>;

入参：

参数	类型	描述
joinInfo	JoinParam	加入频道所需参数

返回：

参数	类型	描述	版本
remoteUsers	RemoteUser[];	远端用户列表	3.0.0
timeLeft	number	频道剩余时长	3.1.0

Promise<{ remoteUsers: RemoteUser[]; timeLeft: number }>

leave()

离开频道，即挂断或退出通话。

调用该方法离开频道时，本地会触发 "connection-state-change" 回调。

远端会触发 "user-left" 回调。

类型签名

leave(): void;

void

publish()

发布本地音视频轨道至频道中。

发布音视频轨道之后，远端会触发 "user-published" 回调。

类型签名

publish(tracks: LocalTrack | LocalTrack[]): Promise<void>;

参数	类型	描述
tracks	LocalTrack\|LocalTrack[]	通过 DingRTC.createMicrophoneAudioTrack / DingRTC.createCameraTrack 或其他方法创建的本地 Track 对象。

Promise<void>

setRemoteDefaultVideoStreamType()

设置订阅所有远端用户的视频类型。

如果远端用户开启了双流模式，本地用户调用 subscribe 后会直接订阅本方法中 streamType 参数所指定的流类型。如不设置，默认订阅大流

类型签名

setRemoteDefaultVideoStreamType(streamType: RemoteStreamType): void;

参数	类型	描述
streamType	RemoteStreamType	订阅的视频流类型，high 代表大流，low 代表小流

void

setRemoteVideoStreamType()

设置订阅特定远端用户的视频类型。

类型签名

setRemoteVideoStreamType(uid: string, streamType: RemoteStreamType): Promise<void>;

参数	类型	描述
uid	string	远端用户的 ID。
streamType	RemoteStreamType	订阅的视频流类型，high 代表大流，low 代表小流

Promise<void>

subscribe()

订阅远端用户的音视频轨道。

类型签名

subscribe(uid: string, mediaType: TrackMediaType, auxiliary?: boolean): Promise<RemoteAudioTrack | RemoteVideoTrack>;

参数	类型	描述
uid	string	远端用户id
mediaType	TrackMediaType	订阅的轨道媒体类型
auxiliary	boolean	(Optional)如果订阅视频轨道，是否是订阅桌面共享视频流

Promise<RemoteAudioTrack|RemoteVideoTrack>

batchSubscribe()

批量订阅远端用户的音视频轨道。

类型签名

batchSubscribe(batchSubscribeParam: SubscribeParam[]): Promise<SubscribeResult[]>;

参数	类型	描述
batchSubscribeParam	数据类型[]	订阅远端音视频轨道参数

Promise<数据类型[]>

说明

当前还未支持指定到个人的音频订阅，请需要订阅音频时将userId 置为字符串'mcu'，代表订阅的是频道内远端用户合流后的音频。指定到个人的音频订阅将在近期支持。

unpublish()

取消发布本地音视频轨道。

取消发布音视频轨道之后，远端会触发 "user-unpublished" 回调。

类型签名

unpublish(tracks?: LocalTrack | LocalTrack[]): Promise<void>;

参数	类型	描述
tracks	LocalTrack\|LocalTrack[]	(Optional)要取消发布的轨道。如果留空，会将所有发布过的音视频轨道取消发布。

Promise<void>

unsubscribe()

取消订阅远端用户的音视频轨道。

类型签名

unsubscribe(uid: string, mediaType?: TrackMediaType, auxiliary?: boolean): Promise<void>;

参数	类型	描述
uid	string	远端用户id。
mediaType	TrackMediaType	(Optional)取消订阅的轨道媒体类型。
auxiliary	boolean	(Optional)如果是订阅视频轨道，是否是订阅桌面共享视频流

Promise<void>

batchUnsubscribe()

批量订阅远端用户的音视频轨道。

类型签名

batchSubscribe(batchUnsubscribeParam: UnsubscribeParam[]): Promise<void>;

参数	类型	描述
batchUnsubscribeParam	数据类型[]	取消订阅远端音视频轨道参数

Promise<void>

说明

当前还未支持指定到个人的音频订阅，请需要取消订阅音频时将userId 置为字符串'mcu'，代表取消订阅的是频道内远端用户合流后的音频。指定到个人的音频取消订阅将在近期支持。

on()

监听一个指定事件并设置回调函数

类型签名

on(event: string, fn: Function): void;

参数

参数	类型	描述
event	string	监听的指定事件
fn	Function	监听事件触发时的回调函数

void

off()

取消一个指定事件的监听回调函数

类型签名

off(event: string, fn: Function): void;

参数

参数	类型	描述
event	string	监听的指定事件
fn	Function	监听事件触发时的回调函数

void

once()

监听一个指定事件一次，回调函数触发后移除

类型签名

once(event: string, fn: Function): void;

参数

参数	类型	描述
event	string	监听的指定事件
fn	Function	监听事件触发时的回调函数

void

removeAllListeners()

取消该对象指定事件或所有事件上的监听回调

类型签名

removeAllListeners(event?: string): void;

参数

参数	类型	描述
event	string	(Optional)设置了指定事件时，对应监听回调函数将会清空。当参数未填写时，对象的所有事件的监听函数都将清空

void

事件列表

"connection-state-change"

SDK 与服务器的连接状态发生改变回调。

类型签名

'connection-state-change': (curState: ConnectionState, revState: ConnectionState, reason?: DisconnectedReason) => void;

"media-reconnect-end"

SDK 重新建立媒体连接（用于发布和订阅）结束的回调。

类型签名

'media-reconnect-end': (uid: string) => void;

"media-reconnect-start"

SDK 开始尝试重新建立媒体连接（用于发布和订阅）的回调。

类型签名

'media-reconnect-start': (uid: string) => void;

"stream-type-changed"

订阅的视频流类型发生改变回调。视频流类型改变指视频大流（高码率、高分辨率）变为视频小流（低码率、低分辨率），或视频小流变为视频大流。

类型签名

'stream-type-changed': (uid: string, streamType: RemoteStreamType) => void;

"user-info-updated"

该回调用于提示用户状态变化。

在大部分情况下，你只需要监听 user-published 和 user-unpublished 就可以完成订阅、取消订阅、展示远端用户是否打开了摄像头和麦克风等工作，无需特别关注实际用户状态的变化，SDK 会自动处理用户状态变化。

类型签名

'user-info-updated': (uid: string, msg: 'mute-audio' | 'mute-video' | 'unmute-audio' | 'unmute-video') => void;

"user-joined"

远端用户加入频道回调。

类型签名

'user-joined': (user: RemoteUser) => void;

"user-left"

远端用户离开频道回调。

类型签名

'user-left': (user: RemoteUser) => void;

"user-published"

该回调通知远端用户发布了新的音频轨道或者视频轨道。

你可以在该回调中订阅并播放远端用户的音视频轨道。

类型签名

'user-published': (user: RemoteUser, mediaType: TrackMediaType, auxiliary?: boolean) => void;

"user-unpublished"

该回调通知远端用户取消发布音频轨道或者视频轨道。

类型签名

'user-unpublished': (user: RemoteUser, mediaType: TrackMediaType, auxiliary?: boolean) => void;

"volume-indicator"

提示频道内正在说话的远端用户列表，当有三人及以上时自动开启。

uids 正在说话人的uid，第一个为音量最高的人，列表为空时代表无人在说话。

类型签名

'volume-indicator': (uids: string[]) => void;

"network-quality"

客户端侧网络质量报告回调，加入频道后每2秒触发一次，仅用作参考值。

类型签名

'network-quality': (uplinkNetworkQuality: NetworkQuality, downlinkNetworkQuality: NetworkQuality) => void;