Class Client

Constructors

constructor

new Client(options: object): Client

Client 类的构造选项。

NOTE：加解密功能仅在 IoT 场景适用。

参数

参数名	描述
options: object	Optional encryptionKey?: string 加密密钥。 Optional encryptionMode?: ENCRYPTION_MODE 加密模式。 Optional encryptionSalt?: string 加密盐值，长度为 32 字节。

返回值

Client

Methods

destroy

destroy(onSuccess?: function, onFailure?: function): Promise<void>

销毁客户端对象。

参数

参数名	描述
onSuccess: function	方法调用成功时执行的回调函数。 (): void Returns void
onFailure: function	方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void err: object code: number reason: string Returns void

返回值

Promise<void>

init

init(appId: string, onSuccess?: function, onFailure?: function): Promise<void>

初始化客户端对象。

参数

参数名	描述
appId: string	你的小程序项目的 App ID。
onSuccess: function	方法调用成功时执行的回调函数。无返回值。 (): void Returns void
onFailure: function	方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void err: object code: number reason: string Returns void

返回值

Promise<void>

join

join(channelKey: string, channel: string, uid: number | string, isAudioOnly: boolean, UidType?: UidType, onSuccess?: function, onFailure?: function): Promise<void>

加入频道。

参数

参数名	描述
channelKey: string	在 app 服务器端生成的用于鉴权的 Token： 安全要求不高：你可以使用控制台生成的临时 Token，详见生成 Token。 安全要求高：将值设为你的服务端生成的正式 Token，详见使用 Token 鉴权。
channel: string	频道名，能标识直播频道的字符串。
uid: number | string	指定用户的 ID。 INT: 整数作为用户 ID，需为 32 位无符号整数。建议设置范围：0 到 (232-1)。需要保证唯一。如果不指定 uid（即设为 null），服务器会报错。 STRING: 字符串，长度不超过 255 个字符。
isAudioOnly: boolean	是否为纯音频场景： true：纯音频场景。 false：非纯音频场景。
UidType: UidType	用户 ID 类型, 可选字段, 默认值为 INT 值 0。详见 UidType。
onSuccess: function	方法调用成功时执行的回调函数。返回值为用户 ID。 (uid: number): void uid: number Returns void
onFailure: function	方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void err: object code: number reason: string Returns void

返回值

Promise<void>

leave

leave(onSuccess?: function, onFailure?: function): Promise<void>

退出频道。

参数

参数名	描述
onSuccess: function	方法调用成功时执行的回调函数。无返回值。 (): void Returns void
onFailure: function	方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void err: object code: number reason: string Returns void

返回值

Promise<void>

mute

mute(uid: number, target: string, onSuccess?: function, onFailure?: function): Promise<void>

停止接收远端用户的音视频流。

参数

参数名	描述
uid: number	远端用户的 ID。
target: string	选择停止接收哪一种流，有三种选择： audio：远端用户发送的音频流，即声音。 video：远端用户发送的视频流，即视频画面。 all：远端用户发送的音视频流，即声音和视频画面。
onSuccess: function	方法调用成功时执行的回调函数。无返回值。 (): void Returns void
onFailure: function	方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void err: object code: number reason: string Returns void

返回值

Promise<void>

muteLocal

muteLocal(target: string, onSuccess?: function, onFailure?: function): Promise<void>

停止发送本地用户的音视频流。

参数

参数名	描述
target: string	选择停止发送哪一种流，有三种选择： audio：本地用户发送的音频流，即声音。 video：本地用户发送的视频流，即视频画面。 all：本地用户发送的音视频流，即声音和视频画面。
onSuccess: function	方法调用成功时执行的回调函数。无返回值。 (): void Returns void
onFailure: function	方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void err: object code: number reason: string Returns void

返回值

Promise<void>

off

off(event: string): void

取消监听流事件。

参数

参数名	描述
event: string	想要取消监听的流事件。

返回值

void

on

on(event: "client-banned"): void

on(event: "client-banned"): void

用户被服务器禁止。

since

v2.5.4

当你在服务端踢除频道内的用户后，被踢出频道的用户会收到该回调。

参数

参数名	描述
event: "client-banned"	当前触发的事件。"client-banned" 表示用户被服务器禁止。

返回值

void

on(event: "error", callback: function): void

on(event: "error", callback: function): void

通知应用程序发生错误。 该回调中会包含详细的错误码和错误信息。

参数

参数名	描述
event: "error"	当前触发的事件。"error" 表示发生错误。
callback: function	具体的事件详情。 (evt: object): void evt: object code: number reason: string Returns void

返回值

void

on(event: "stream-added", callback: function): void

on(event: "stream-added", callback: function): void

通知应用程序已添加远端音视频流。 该回调中会包含已添加的远端用户 ID。

参数

参数名	描述
event: "stream-added"	当前触发的事件。"stream-added" 表示已添加远端音视频流。
callback: function	具体的事件详情。 (evt: object): void evt: object uid: number Returns void

返回值

void

on(event: "stream-removed", callback: function): void

on(event: "stream-removed", callback: function): void

通知应用程序已删除远端音视频流。 该回调中会包含已删除的远端用户 ID。

参数

参数名	描述
event: "stream-removed"	当前触发的事件。"stream-removed" 表示已删除远端音视频流。
callback: function	具体的事件详情。 (evt: object): void evt: object uid: number Returns void

返回值

void

on(event: "update-url", callback: function): void

on(event: "update-url", callback: function): void

通知应用程序已更新 URL 地址。 该回调中会包含远端用户的 ID 和更新后的拉流地址。

参数

参数名	描述
event: "update-url"	当前触发的事件。"update-url" 表示已更新 URL 地址。
callback: function	具体的事件详情。 (evt: object): void evt: object uid: number url: string Returns void

返回值

void

on(event: "video-rotation", callback: function): void

on(event: "video-rotation", callback: function): void

通知应用程序远端视频已旋转。 该回调中会包含视频的旋转信息以及远端用户的 ID。

参数

参数名	描述
event: "video-rotation"	当前触发的事件。"video-rotation" 表示远端视频已旋转。
callback: function	具体的事件详情。 (evt: object): void evt: object rotation: number uid: number Returns void

返回值

void

on(event: "token-privilege-did-expire"): void

on(event: "token-privilege-did-expire"): void

Token 已过期回调。

since

v2.5.3

在 Token 过期后，会收到该回调。

一般情况下，在收到该消息之后，应向服务端重新申请 Token，并调用 join 方法传入新的 Token 重新加入频道。

参数

参数名	描述
event: "token-privilege-did-expire"	当前触发的事件。"token-privilege-did-expire" 表示 Token 已过期。

返回值

void

on(event: "token-privilege-will-expire"): void

on(event: "token-privilege-will-expire"): void

Token 服务即将过期回调。

since

v2.5.3

在调用 join 时如果指定了 Token，由于 Token 具有一定的时效，在通话过程中如果 Token 即将失效，SDK 会提前 30 秒触发该回调，提醒 App 更新 Token。当收到该回调时，你需要重新在服务端生成新的 Token， 然后调用 renewToken 将新生成的 Token 传给 SDK。

参数

参数名	描述
event: "token-privilege-will-expire"	当前触发的事件。"token-privilege-will-expire" 表示 Token 即将过期。

返回值

void

on(event: "mute-audio", callback: function): void

on(event: "mute-audio", callback: function): void

通知应用程序远端用户已停止发送音频流。 该回调中会包含停止发送音频流的用户 ID。

参数

参数名	描述
event: "mute-audio"	当前触发的事件。"mute-audio" 表示远端用户已停止发送音频流。
callback: function	具体的事件详情。 (evt: object): void evt: object uid: number Returns void

返回值

void

on(event: "mute-video", callback: function): void

on(event: "mute-video", callback: function): void

通知应用程序远端用户已停止发送视频流。 该回调中会包含停止发送视频流的用户 ID。

参数

参数名	描述
event: "mute-video"	当前触发的事件。"mute-video" 表示远端用户已停止发送视频流。
callback: function	具体的事件详情。 (evt: object): void evt: object uid: number Returns void

返回值

void

on(event: "unmute-audio", callback: function): void

on(event: "unmute-audio", callback: function): void

通知应用程序远端用户已恢复发送音频流。 该回调中会包含恢复发送音频流的用户 ID。

参数

参数名	描述
event: "unmute-audio"	当前触发的事件。"unmute-audio" 表示远端用户已恢复发送音频流。
callback: function	具体的事件详情。 (evt: object): void evt: object uid: number Returns void

返回值

void

on(event: "unmute-video", callback: function): void

on(event: "unmute-video", callback: function): void

通知应用程序远端用户已恢复发送视频流。 该回调中会包含恢复发送视频流的用户 ID。

参数

参数名	描述
event: "unmute-video"	当前触发的事件。"unmute-video" 表示远端用户已恢复发送视频流。
callback: function	具体的事件详情。 (evt: object): void evt: object uid: number Returns void

返回值

void

on(event: "channel-media-relay-event", callback: function): void

on(event: "channel-media-relay-event", callback: function): void

跨频道媒体流转发事件回调。

该回调报告跨频道媒体流转发过程中发生的事件。

参数

参数名	描述
event: "channel-media-relay-event"	当前触发的事件。"channel-media-relay-event" 表示报告媒体流转发事件。
callback: function	具体的事件详情。 (evt: object): void evt: object code: number Returns void

返回值

void

on(event: "channel-media-relay-state", callback: function): void

on(event: "channel-media-relay-state", callback: function): void

跨频道媒体流转发状态回调。

当跨频道媒体流转发状态发生改变时，SDK 会触发该回调，并报告当前的转发状态以及相关的错误信息。

参数

参数名	描述
event: "channel-media-relay-state"	当前触发的事件。"channel-media-relay-state" 表示媒体流转发状态。
callback: function	具体的事件详情。 (evt: object): void evt: object code: number state: number Returns void

返回值

void

publish

publish(onSuccess?: function, onFailure?: function): Promise<string>

发布本地音视频流。

该方法将本地音视频流发布到 SD-RTN。互动直播中，调用该 API 的用户即默认为主播。

参数

参数名	描述
onSuccess: function	方法调用成功时执行的回调函数。返回值为音视频流的推流地址。 (url: string): void url: string Returns void
onFailure: function	方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void err: object code: number reason: string Returns void

返回值

Promise<string>

string 型，音视频流的推流地址。

rejoin

rejoin(channelKey: string, channel: string, uid: number | string, uids: number, isAudioOnly: boolean, UidType?: UidType, onSuccess?: function, onFailure?: function): Promise<void>

重新加入频道。

该方法让用户重新加入声网 RTC 频道。如果你的小程序中有切后台的场景需求，请确保使用该方法做好重连机制。

参数

参数名	描述
channelKey: string	在 app 服务器端生成的用于鉴权的 Token： 安全要求不高：你可以使用控制台生成的临时 Token，详见获取临时 Token。 安全要求高：将值设为你的服务端生成的正式 Token，详见从服务端生成 Token。
channel: string	频道名，能标识直播频道的字符串。
uid: number | string	指定用户的 ID。 INT: 整数作为用户 ID，需为 32 位无符号整数。建议设置范围：0 到 (232-1)。需要保证唯一性。如果不指定 uid（即设为 null），服务器会报错。 STRING: 字符串，长度不超过 255 个字符。
uids: number	频道内已有用户的用户 ID 列表。
isAudioOnly: boolean	是否为纯音频场景： true：纯音频场景。 false：非纯音频场景。
UidType: UidType	用户 ID 类型, 可选字段, 默认值为 INT 值 0。详见 UidType。
onSuccess: function	方法调用成功时执行的回调函数。返回值为用户 ID。 (uid: number): void uid: number Returns void
onFailure: function	方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void err: object code: number reason: string Returns void

返回值

Promise<void>

renewToken

renewToken(token: string, onSuccess?: function, onFailure?: function): Promise<void>

更新 Token。

since

v2.5.3

该方法更新 Token。如果启用了 Token 机制，过一段时间后密钥会失效。 当收到 client.on("token-privilege-will-expire") 消息时，调用该 API 以更新 Token，否则 SDK 会无法和服务器建立连接。

参数

参数名	描述
token: string	新的 Token。
onSuccess: function	方法调用成功时执行的回调函数。 (): void Returns void
onFailure: function	方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void err: object code: number reason: string Returns void

返回值

Promise<void>

setAudioCodec

setAudioCodec(audioCodec: AudioCodec): void

设置 IoT 设备使用的音频编码格式。

since

v2.5.6

参数

参数名	描述
audioCodec: AudioCodec	IoT 设备使用的音频编码格式，详见AudioCodec。 0: PCMU/G711u 格式。 8: PCMA/G711a 格式。 9: G722 格式。

返回值

void

setRemoteVideoStreamType

setRemoteVideoStreamType(uid: number, streamType: 0 | 1, onSuccess?: function, onFailure?: function): Promise<void>

设置订阅的视频流类型。

since

v2.5.3

如果发送端选择发送视频双流 (大流和小流)，该方法可以在订阅端选择接收大流还是小流。如果不设置，订阅端默认接收大流。

参数

参数名	描述
uid: number	用户 ID。
streamType: 0 | 1
onSuccess: function	方法调用成功时执行的回调函数。 (url: string): void url: string Returns void
onFailure: function	方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: any): void err: any Returns void

返回值

Promise<void>

setRole

setRole(role: string, onSuccess?: function, onFailure?: function): Promise<void>

设置用户角色。

注：如果在主播已 publish 的状态下调用该方法将用户角色设置为 audience，会导致之前的推流地址无效。

参数

参数名	描述
role: string	用户角色。选择如下一种角色： broadcaster：将用户角色设置为主播。主播可以调用 publish 和 unpublish 方法。 audience：(默认) 将用户角色设置为观众。观众不能调用 publish 和 unpublish 方法。
onSuccess: function	方法调用成功时执行的回调函数。无返回值。 (): void Returns void
onFailure: function	方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void err: object code: number reason: string Returns void

返回值

Promise<void>

startChannelMediaRelay

startChannelMediaRelay(config: ChannelMediaRelayConfiguration, callback: function): void

开始跨频道媒体流转发。

该方法可用于实现跨频道媒体流转发。

调用该方法后，SDK 会触发以下回调：

• Client.on("channel-media-relay-state")，报告当前的跨频道媒体流转发状态和错误码。
  • 如果转发成功，该回调中 state 为 2，code 为 0。
  • 如果转发出现异常，该回调中 state 为 3，code 为错误码。你可以尝试再次调用本方法。
• Client.on("channel-media-relay-event")，报告跨频道媒体流转发相关的事件。
  • 如果转发成功，该回调中 code 为 4，表示 SDK 开始向目标频道发送数据包。

Note

• 跨频道媒体流转发功能需要提交工单联系技术支持开通。
• 该功能不支持 String 型 UID。
• 请在成功加入频道后调用该方法。
• 直播场景下，只有主播可以调用该方法。
• 成功调用该方法后，若你想再次调用该方法，必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。

example

示例代码

client.startChannelMediaRelay(channelMediaConfig, function(e) {
 if(e) {
 utils.notification(`startChannelMediaRelay failed: ${JSON.stringify(e)}`);
 } else {
 utils.notification(`startChannelMediaRelay success`);
 }
});

参数

参数名	描述
config: ChannelMediaRelayConfiguration	跨频道媒体流转发参数配置，详见 ChannelMediaRelayConfiguration。
callback: function	媒体流转发是否成功的回调。 null：媒体流转发成功。 如果失败，会通过 ChannelMediaError 提供错误信息。 (err: null | ChannelMediaError): void err: null | ChannelMediaError Returns void

返回值

void

stopChannelMediaRelay

stopChannelMediaRelay(callback: function): void

停止跨频道媒体流转发。

一旦停止转发，用户会退出所有的目标频道。

调用该方法会触发 Client.on("channel-media-relay-state") 回调。

• 如果成功停止跨频道媒体流转发，该回调中 state 为 0。
• 如果未成功停止跨频道媒体流转发，该回调中 state 为 3，code 错误码可能为 2 或 8，一般是在网络较差的情况下，退出的消息发送不成功导致的。你可以调用 Client.leave 离开频道来停止跨频道媒体流转发。

example

示例代码

stopChannelMediaRelay: function() {
 client.stopChannelMediaRelay(function(e) {
 if(e) {
 utils.notification(`stopChannelMediaRelay failed: ${JSON.stringify(e)}`);
 } else {
 utils.notification(`stopChannelMediaRelay success`);
 }
 });
}

参数

参数名	描述
callback: function	停止跨频道媒体流转发是否成功的回调。 null：停止跨频道媒体流转发成功。 如果失败，会通过 ChannelMediaError 提供错误信息。 (err: null | ChannelMediaError): void err: null | ChannelMediaError Returns void

返回值

void

subscribe

subscribe(uid: number, options?: object, onSuccess?: function, onFailure?: function): Promise<object>

订阅远端音视频流。

该方法从 SD-RTN 订阅并接收远端音视频流。

参数

参数名	描述
uid: number	要订阅的远端用户 ID。
options: object	设置是否订阅视频或音频。 Optional audio?: boolean Optional video?: boolean
onSuccess: function	方法调用成功时执行的回调函数。返回值为音视频的拉流地址。 (url: string, rotation: number): void url: string rotation: number Returns void
onFailure: function	方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: any): void err: any Returns void

返回值

Promise<object>

一个对象，包含以下数据：

• url：string 型，音视频流的拉流地址
• rotation：number 型，视频帧顺时针旋转角度。

unmute

unmute(uid: number, target: string, onSuccess?: function, onFailure?: function): Promise<void>

恢复接收远端用户的音视频流。

参数

参数名	描述
uid: number	远端用户的 ID。
target: string	选择停止接收哪一种流，有三种选择： audio：远端用户发送的音频流，即声音。 video：远端用户发送的视频流，即视频画面。 all：远端用户发送的音视频流，即声音和视频画面。
onSuccess: function	方法调用成功时执行的回调函数。无返回值。 (): void Returns void
onFailure: function	方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void err: object code: number reason: string Returns void

返回值

Promise<void>

unmuteLocal

unmuteLocal(target: string, onSuccess?: function, onFailure?: function): Promise<void>

恢复发送本地用户的音视频流。

参数

参数名	描述
target: string	选择恢复发送哪一种流，有三种选择： audio：本地用户发送的音频流，即声音。 video：本地用户发送的视频流，即视频画面。 all：本地用户发送的音视频流，即声音和视频画面。
onSuccess: function	方法调用成功时执行的回调函数。无返回值。 (): void Returns void
onFailure: function	方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void err: object code: number reason: string Returns void

返回值

Promise<void>

unpublish

unpublish(onSuccess?: function, onFailure?: function): Promise<void>

停止发布本地音视频流。

参数

参数名	描述
onSuccess: function	方法调用成功时执行的回调函数。无返回值。 (): void Returns void
onFailure: function	方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: any): void err: any Returns void

返回值

Promise<void>

unsubscribe

unsubscribe(uid: number, onSuccess?: function, onFailure?: function): Promise<void>

停止订阅远端音视频流。

该方法停止从 SD-RTN 订阅并接收远端音视频流。

参数

参数名	描述
uid: number	要停止订阅的远端用户 ID。
onSuccess: function	方法调用成功时执行的回调函数。无返回值。 (): void Returns void
onFailure: function	方法调用成功时执行的回调函数。返回值为错误码和错误信息。 (err: any): void err: any Returns void

返回值

Promise<void>

updateChannelMediaRelay

updateChannelMediaRelay(config: ChannelMediaRelayConfiguration, callback: function): void

更新媒体流转发的目标频道。

成功开始跨频道转发媒体流后，如果你希望添加或删除媒体流转发的目标频道，可以调用该方法。

调用该方法后，SDK 会触发 Client.on("channel-media-relay-event") 回调。

• 如果更新成功，回调中 code 为 7。
• 如果更新失败，回调中 code 为 8，同时还会触发 Client.on("channel-media-relay-state") 回调，其中 state 为 3。出错后跨频道媒体流转发状态会被重置，你需要调用 startChannelMediaRelay 重新开始跨频道媒体流转发。

Note

• 请在 startChannelMediaRelay 后调用该方法，更新媒体流转发的频道。
• 跨频道媒体流转发最多支持 4 个目标频道。

example

示例代码

client.updateChannelMediaRelay(channelMediaConfig, function(e) {
 if(e) {
 utils.notification(`updateChannelMediaRelay failed: ${JSON.stringify(e)}`);
 } else {
 utils.notification(`updateChannelMediaRelay success`);
 }
});

参数

参数名	描述
config: ChannelMediaRelayConfiguration	跨频道媒体流转发参数配置，详见 ChannelMediaRelayConfiguration。
callback: function	更新目标频道是否成功的回调。 null：更新目标频道成功。 如果失败，会通过 ChannelMediaError 提供错误信息。 (err: null | ChannelMediaError): void err: null | ChannelMediaError Returns void

返回值

void

updatePlayerNetStatus

updatePlayerNetStatus(uid: number, detail: any): void

上报拉流过程中的网络状态。

since

v2.5.3

当收到 live-player 组件报告的网络状态通知时，你可以调用该接口将其上报给声网的数据中心。

参数

参数名	描述
uid: number	远端用户的用户 ID。
detail: any	微信事件回调的 e.detail 对象。 Note：要收到 live-player 组件报告的网络状态数据，你需要在创建 live-player 组件时注册监听 bindnetstatus。详见微信小程序 live-player 文档。

返回值

void

updatePlayerStateChange

updatePlayerStateChange(uid: number, detail: any): void

上报拉流状态。

since

v2.5.3

当收到 live-player 组件报告的拉流状态变化通知时，你可以调用该接口将其上报给声网的数据中心。

参数

参数名	描述
uid: number	远端用户的用户 ID。
detail: any	微信事件回调的 e.detail 对象。 Note：要收到 live-player 组件报告的拉流状态码，你需要在创建 live-player 组件时注册监听 bindstatechange。详见微信小程序 live-player 文档。

返回值

void

updatePusherNetStatus

updatePusherNetStatus(detail: any): void

上报推流过程中的网络状态。

since

v2.5.3

当收到 live-pusher 组件报告的网络状态通知时，你可以调用该接口将其上报给声网的数据中心。

参数

参数名	描述
detail: any	微信事件回调的 e.detail 对象。 Note：要收到 live-pusher 组件报告的网络状态通知，你需要在创建 live-pusher 组件时注册监听 bindnetstatus。详见微信小程序 live-pusher 文档。

返回值

void

updatePusherStateChange

updatePusherStateChange(detail: any): void

上报推流状态。

since

v2.5.3

当收到 live-pusher 组件报告的推流状态变化通知时，你可以调用该接口将其上报给声网的数据中心。

参数

参数名	描述
detail: any	微信事件回调的 e.detail 对象。 Note：要收到 live-pusher 组件报告的推流状态码，你需要在创建 live-pusher 组件时注册监听 bindstatechange。详见微信小程序 live-pusher 文档。

返回值

void