API Reference for web - Class: Client

更新时间: 2023-10-23 16:45:52

# Class: Client

Client.Client

# Hierarchy

EnhancedEventEmitter

↳ Client

# Accessors

# channelName

get channelName(): undefined | string

当前加入的频道名称

如果本地用户没有加入频道，该属性值为 undefined。

# Returns

undefined | string

# connectionState

get connectionState(): ConnectionState

SDK 和服务器的连接状态。

# Returns

ConnectionState

# localTracks

get localTracks(): LocalTrack[]

保存当前正在发布的本地轨道对象列表。

调用 publish 成功后，发布的轨道对象会自动添加到这个列表中。
调用 unpublish 成功后，取消发布的轨道对象会自动从这个列表中移除。

# Returns

LocalTrack[]

# remoteUsers

get remoteUsers(): RTCRemoteUser[]

远端用户信息列表，包含频道中各个远端用户的用户 ID 和轨道信息。

如果本地用户没有加入频道，该列表为空。

# Returns

RTCRemoteUser[]

# uid

get uid(): undefined | string

本地用户的用户 ID。

如果本地用户没有加入频道，该属性值为 undefined。

# Returns

undefined | string

# Core Methods

# join

join(appid, channel, token, uid): Promise<string | number>

加入频道。

该方法让用户加入通话频道，在同一个频道内的用户可以互相通话。

调用该方法加入频道时，本地会触发 [Client.on("connection-state-change")](@link event_connection_state_change) 回调。

通信场景下的用户和直播场景下的主播加入频道后，远端会触发 Client.on("user-joined") 回调。

# Parameters

Name	Type	Description
`appid`	`string`	AppId
`channel`	`string`	标识通话的频道名称，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 88 个字符）: - 26 个小写字母 a-z。 - 26 个大写字母 A-Z。 - 10 个数字 0-9。 - 空格。 - "!", "#", "$", "%", "&", "(", ")", "+", ";", "<", "=", ".", ">", "?", "[", "]", "^", "_", "{", "}", "\|", "~", ","。 - > 对比声网，不能使用 ":"（半角冒号）、"@" 、"-"
`token`	`null` \| `string`	用于鉴权的 token。
`uid`	`null` \| `string` \| `number`	int64的string或者number

# Returns

Promise<string | number>

# Other Methods

# getLocalAudioStats

getLocalAudioStats(): {} | LocalAudioTrackStats

获取本地音频相关信息。

# Returns

{} | LocalAudioTrackStats

# getLocalVideoStats

getLocalVideoStats(): {} | LocalVideoTrackStats

获取本地视频相关信息。

# Returns

{} | LocalVideoTrackStats

# getRTCStats

getRTCStats(): {} | CoreRTCStats

获取当前通话的统计信息。

# Returns

{} | CoreRTCStats

# getRemoteAudioStats

getRemoteAudioStats(): Object

获取远端用户的音频相关信息。

# Returns

Object

# getRemoteVideoStats

getRemoteVideoStats(): Object

获取远端用户的视频相关信息。

# Returns

Object

# getStatsFromServer

getStatsFromServer(): Promise<any>

# Returns

Promise<any>

# leave

leave(): Promise<void>

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

调用该方法离开频道时，本地会触发 [Client.on("connection-state-change")]{@link EventInterface.connectionStateChange} 回调。

主播离开频道后，远端会触发 [Client.on("user-left")] 回调。

# Returns

Promise<void>

# off

off(event, listener): void

取消一个指定事件的监听。

# Parameters

Name	Type	Description
`event`	`string`	指定事件的名称。
`listener`	(...`args`: `any`[]) => `void`	监听事件时传入的回调函数。

# Returns

void

# Overrides

EnhancedEventEmitter.off

# on

on(event, listener): void

# Parameters

Name	Type
`event`	`"connection-state-change"`
`listener`	(`curState`: `ConnectionState`, `revState`: `ConnectionState`, `reason?`: `string`) => `void`

# Returns

void

# Overrides

EnhancedEventEmitter.on

on(event, listener): void

# Parameters

Name	Type
`event`	`"user-joined"`
`listener`	(`user`: `RTCRemoteUser`) => `void`

# Returns

void

# Overrides

EnhancedEventEmitter.on

on(event, listener): void

# Parameters

Name	Type
`event`	`"user-left"`
`listener`	(`user`: `RTCRemoteUser`, `reason`: `string`) => `void`

# Returns

void

# Overrides

EnhancedEventEmitter.on

on(event, listener): void

# Parameters

Name	Type
`event`	`"user-published"`
`listener`	(`user`: `RTCRemoteUser`, `mediaType`: `MediaKind`) => `void`

# Returns

void

# Overrides

EnhancedEventEmitter.on

on(event, listener): void

# Parameters

Name	Type
`event`	`"user-unpublished"`
`listener`	(`user`: `RTCRemoteUser`, `mediaType`: `MediaKind`) => `void`

# Returns

void

# Overrides

EnhancedEventEmitter.on

on(event, listener): void

# Parameters

Name	Type
`event`	`"media-reconnect-start"`
`listener`	(`uid`: `string` \| `number`) => `void`

# Returns

void

# Overrides

EnhancedEventEmitter.on

on(event, listener): void

# Parameters

Name	Type
`event`	`"media-reconnect-end"`
`listener`	(`uid`: `string` \| `number`) => `void`

# Returns

void

# Overrides

EnhancedEventEmitter.on

on(event, listener): void

# Parameters

Name	Type
`event`	`"token-privilege-will-expire"`
`listener`	() => `void`

# Returns

void

# Overrides

EnhancedEventEmitter.on

on(event, listener): Client

# Parameters

Name	Type
`event`	`"network-quality"`
`listener`	(`stats`: `NetworkQuality`) => `void`

# Returns

Client

# Overrides

EnhancedEventEmitter.on

# once

once(event, listener): Client

监听一个指定的事件，当事件触发时会调用传入的回调函数。当监听后事件第一次触发时，该监听和回调函数就会被立刻移除，也就是只监听一次指定事件。

# Parameters

Name	Type	Description
`event`	`string`	指定事件的名称。
`listener`	(...`args`: `any`[]) => `void`	传入的回调函数。

# Returns

Client

# Overrides

EnhancedEventEmitter.once

# publish

publish(tracks, isReconnect?): Promise<void>

发布本地音视频轨道。该方法将本地音视频轨道发布至频道中。

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

Note:

调用该方法前，必须先调用 setClientRole 将用户角色设为主播。

可以多次调用该方法添加要发布的轨道。

一个 Client 对象可以发布多个音频轨道，SDK 会自动混音，将多个音频轨道合并为一个音频轨道。Safari 12 之前的版本不支持发布多个音频轨道。

一个 Client 对象 只能发布一个视频轨道 。如果你想要更换视频轨道，例如已经发布了一个摄像头视频轨道，想要切换为屏幕共享视频轨道，你必须先取消发布。

# Parameters

Name	Type	Default value
`tracks`	`LocalTrack` \| `LocalTrack`[]	`undefined`
`isReconnect`	`boolean`	`false`

# Returns

Promise<void>

# removeAllListeners

removeAllListeners(event): Client

指定一个事件，取消其所有的监听。

# Parameters

Name	Type	Description
`event`	`undefined` \| `string`	指定事件的名称，如果没有指定事件，则取消所有事件的所有监听。

# Returns

Client

# Overrides

EnhancedEventEmitter.removeAllListeners

# renewToken

renewToken(token): void

更新 token。

如果启用了 token 机制，过一段时间后 token 会失效。当收到 Client.on("token-privilege-will-expire") 回调时, 调用该方法传入新的 token，否则 SDK 会无法和服务器建立连接。

# Parameters

Name	Type	Description
`token`	`string`	新的 token。

# Returns

void

# setClientRole

setClientRole(role): Promise<void>

用户角色有 "host"（主播）和 "audience"（观众）。主播既可发布轨道，也可订阅轨道；观众不能进行 publish 操作。直播场景中的用户角色默认为观众。如需发布音视频，必须先调用本方法切换角色为主播

# Parameters

Name	Type
`role`	`ClientRole`

# Returns

Promise<void>

subscribe(user, mediaType): Promise<RemoteAudioTrack | RemoteVideoTrack>

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

await client.subscribe(user，"audio");
user.audioTrack.play();

# Parameters

Name	Type	Description
`user`	`RTCRemoteUser`	远端用户对象。
`mediaType`	`MediaKind`	订阅的轨道媒体类型。 - `"video"`: 订阅指定用户发布的视频轨道。 - `“audio”`: 订阅指定用户发布的音频轨道。

# Returns

Promise<RemoteAudioTrack | RemoteVideoTrack>

订阅的异步操作完成后，返回远端轨道对象，该对象也会在 user.audioTrack 和 user.videoTrack上更新，之后直接调用 audioTrack.play 或 videoTrack.play 就可以播放了。

如果指定要订阅的音视频轨道不存在会抛出 TRACK_IS_NOT_PUBLISHED 错误。

# unpublish

unpublish(tracks?): Promise<void>

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

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

# Parameters

Name	Type
`tracks?`	`LocalTrack` \| `LocalTrack`[]

# Returns

Promise<void>

# unsubscribe

unsubscribe(user, mediaType?): Promise<undefined>

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

# Parameters

Name	Type	Description
`user`	`RTCRemoteUser`	远端用户对象。
`mediaType?`	`"video"` \| `"audio"`	取消订阅的轨道媒体类型。 - `"video"`: 仅取消订阅指定用户的视频轨道。 - `“audio”`: 仅取消订阅指定用户的音频轨道。 - empty: 如不填，取消订阅该用户发布的所有轨道。

# Returns

Promise<undefined>

如果指定的音视频轨道不存在会抛出 TRACK_IS_NOT_SUBSCRIBED 错误。