Interface 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"

返回值

void

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

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

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

参数

参数名	类型	描述
event	"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"
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"
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"
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"
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"

返回值

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"

返回值

void

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

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

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

参数

参数名	类型	描述
event	"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"
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"
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"
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"
callback	function	(evt: object): void evt: object code: number 事件码 0: 网络中断导致用户与服务器连接断开。 1: 用户与服务器建立连接。 2: 用户已加入源频道。 3: 用户已加入目标频道。 4: SDK 开始向目标频道发送数据包。 5: 服务器收到了目标频道发送的视频流。 6: 服务器收到了目标频道发送的音频流。 7: 目标频道已更新。 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"
callback	function	(evt: object): void evt: object code: number 跨频道媒体流转发出错的错误码： 0: 一切正常。 1: 服务器回应出错。 2: 服务器无回应。 3: SDK 无法获取服务，可能是因为服务器资源有限导致。 4: 发起跨频道转发媒体流请求失败。 5: 接受跨频道转发媒体流请求失败。 6: 服务器接收跨频道转发媒体流失败。 7: 服务器发送跨频道转发媒体流失败。 8: SDK 因网络质量不佳与服务器断开，并且重连失败时抛出这个错。此时 SDK 会重置跨频道媒体流转发的相关状态，可以尝试调用 startChannelMediaRelay 重新进行跨频道媒体流转发。 9: 服务器内部出错。 10: 源频道的 Token 已过期。 11: 目标频道的 Token 已过期。 12: 已经开始跨频道媒体流转发。该错误一般是因为重复调用 startChannelMediaRelay，或者在调用 stopChannelMediaRelay 未成功时就调用了 startChannelMediaRelay。 13: 尚未开始跨频道媒体流转发。该错误一般是因为调用 startChannelMediaRelay 还未成功时就调用了 updateChannelMediaRelay。 state: number 状态码 0: SDK 正在初始化。 1: SDK 尝试跨频道。 2: 源频道主播成功加入目标频道。 3: 发生异常，详见 code 中提示的错误信息。发生异常后，SDK 会重置跨频道媒体流转发的相关状态，你需要调用 startChannelMediaRelay 重新开始跨频道媒体流转发。 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>

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

示例代码

JavaScript

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

示例代码

JavaScript

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 是否订阅音频流： true：（默认）订阅。 false：不订阅。 Optional video?: boolean 是否订阅视频流： true：（默认）订阅。 false：不订阅。
onSuccess	function	方法调用成功时执行的回调函数。返回值为音视频的拉流地址。 (url: string, rotation: number): void url: string rotation: number Returns void
onFailure	function	方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: any): void err: any Returns void

返回值

Promise<object>

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

示例代码

JavaScript

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, e: any): void

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

since

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

参数

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

返回值

void

updatePlayerStateChange

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

上报拉流状态。

since

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

参数

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

返回值

void

updatePusherNetStatus

updatePusherNetStatus(e: any): void

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

since

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

参数

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

返回值

void

updatePusherStateChange

updatePusherStateChange(e: any): void

上报推流状态。

since

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

参数

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

返回值

void