需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

Class Client

  • 小程序

更新时间不可用

Client 类的构造选项。

Constructors

constructor

new Client(options: object): 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>

销毁客户端对象。

参数
参数名描述
Optional onSuccess?: function

方法调用成功时执行的回调函数。

(): void
Optional onFailure?: function

方法调用失败时执行的回调函数。返回值为错误码和错误信息。

(err: object): void

参数

  • err: object
    • code: number
    • reason: string
表格内容超出当前宽度，可横向滚动查看更多列。
返回值
返回类型描述

Promise<void>

表格内容超出当前宽度，可横向滚动查看更多列。

init

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

初始化客户端对象。

参数
参数名描述
appId: string

你的小程序项目的 App ID。

Optional onSuccess?: function

方法调用成功时执行的回调函数。无返回值。

(): void
Optional onFailure?: function

方法调用失败时执行的回调函数。返回值为错误码和错误信息。

(err: object): void

参数

  • err: object
    • code: number
    • reason: string
表格内容超出当前宽度，可横向滚动查看更多列。
返回值
返回类型描述

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 到 (2³² - 1)。需要保证唯一。如果不指定 uid（即设为 null），服务器会报错。
  • STRING: 字符串，长度不超过 255 个字符。
isAudioOnly: boolean

是否为纯音频场景：

  • true：纯音频场景。
  • false：非纯音频场景。
Optional UidType?: UidType

用户 ID 类型, 可选字段, 默认值为 INT 值 0。详见 UidType。

Optional onSuccess?: function

方法调用成功时执行的回调函数。返回值为用户 ID。

(uid: number): void

参数

  • uid: number
Optional onFailure?: function

方法调用失败时执行的回调函数。返回值为错误码和错误信息。

(err: object): void

参数

  • err: object
    • code: number
    • reason: string
表格内容超出当前宽度，可横向滚动查看更多列。
返回值
返回类型描述

Promise<void>

表格内容超出当前宽度，可横向滚动查看更多列。

leave

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

退出频道。

参数
参数名描述
Optional onSuccess?: function

方法调用成功时执行的回调函数。无返回值。

(): void
Optional onFailure?: function

方法调用失败时执行的回调函数。返回值为错误码和错误信息。

(err: object): void

参数

  • err: object
    • code: number
    • reason: string
表格内容超出当前宽度，可横向滚动查看更多列。
返回值
返回类型描述

Promise<void>

表格内容超出当前宽度，可横向滚动查看更多列。

mute

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

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

参数
参数名描述
uid: number

远端用户的 ID。

target: string

选择停止接收哪一种流，有三种选择：

  • audio：远端用户发送的音频流，即声音。
  • video：远端用户发送的视频流，即视频画面。
  • all：远端用户发送的音视频流，即声音和视频画面。
Optional onSuccess?: function

方法调用成功时执行的回调函数。无返回值。

(): void
Optional onFailure?: function

方法调用失败时执行的回调函数。返回值为错误码和错误信息。

(err: object): void

参数

  • err: object
    • code: number
    • reason: string
表格内容超出当前宽度，可横向滚动查看更多列。
返回值
返回类型描述

Promise<void>

表格内容超出当前宽度，可横向滚动查看更多列。

muteLocal

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

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

参数
参数名描述
target: string

选择停止发送哪一种流，有三种选择：

  • audio：本地用户发送的音频流，即声音。
  • video：本地用户发送的视频流，即视频画面。
  • all：本地用户发送的音视频流，即声音和视频画面。
Optional onSuccess?: function

方法调用成功时执行的回调函数。无返回值。

(): void
Optional onFailure?: function

方法调用失败时执行的回调函数。返回值为错误码和错误信息。

(err: object): void

参数

  • err: object
    • code: number
    • reason: string
表格内容超出当前宽度，可横向滚动查看更多列。
返回值
返回类型描述

Promise<void>

表格内容超出当前宽度，可横向滚动查看更多列。

off

off(event: string): void

取消监听流事件。

参数
参数名描述
event: string

想要取消监听的流事件。

表格内容超出当前宽度，可横向滚动查看更多列。
返回值
返回类型描述

void

表格内容超出当前宽度，可横向滚动查看更多列。

on

publish

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

发布本地音视频流。

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

参数
参数名描述
Optional onSuccess?: function

方法调用成功时执行的回调函数。返回值为音视频流的推流地址。

(url: string): void

参数

  • url: string
Optional onFailure?: function

方法调用失败时执行的回调函数。返回值为错误码和错误信息。

(err: object): void

参数

  • err: object
    • code: number
    • reason: string
表格内容超出当前宽度，可横向滚动查看更多列。
返回值
返回类型描述

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 到 (2³² - 1)。需要保证唯一性。如果不指定 uid（即设为 null），服务器会报错。
  • STRING: 字符串，长度不超过 255 个字符。
uids: number

频道内已有用户的用户 ID 列表。

isAudioOnly: boolean

是否为纯音频场景：

  • true：纯音频场景。
  • false：非纯音频场景。
Optional UidType?: UidType

用户 ID 类型, 可选字段, 默认值为 INT 值 0。详见 UidType。

Optional onSuccess?: function

方法调用成功时执行的回调函数。返回值为用户 ID。

(uid: number): void

参数

  • uid: number
Optional onFailure?: function

方法调用失败时执行的回调函数。返回值为错误码和错误信息。

(err: object): void

参数

  • err: object
    • code: number
    • reason: string
表格内容超出当前宽度，可横向滚动查看更多列。
返回值
返回类型描述

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。

Optional onSuccess?: function

方法调用成功时执行的回调函数。

(): void
Optional onFailure?: function

方法调用失败时执行的回调函数。返回值为错误码和错误信息。

(err: object): void

参数

  • err: object
    • code: number
    • reason: string
表格内容超出当前宽度，可横向滚动查看更多列。
返回值
返回类型描述

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
Optional onSuccess?: function

方法调用成功时执行的回调函数。

(url: string): void

参数

  • url: string
Optional onFailure?: function

方法调用失败时执行的回调函数。返回值为错误码和错误信息。

(err: any): void

参数

  • err: any
表格内容超出当前宽度，可横向滚动查看更多列。
返回值
返回类型描述

Promise<void>

表格内容超出当前宽度，可横向滚动查看更多列。

setRole

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

设置用户角色。

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

参数
参数名描述
role: string

用户角色。选择如下一种角色：

  • broadcaster：将用户角色设置为主播。主播可以调用 publish 和 unpublish 方法。
  • audience：(默认) 将用户角色设置为观众。观众不能调用 publish 和 unpublish 方法。
Optional onSuccess?: function

方法调用成功时执行的回调函数。无返回值。

(): void
Optional onFailure?: function

方法调用失败时执行的回调函数。返回值为错误码和错误信息。

(err: object): void

参数

  • err: object
    • code: number
    • reason: string
表格内容超出当前宽度，可横向滚动查看更多列。
返回值
返回类型描述

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

参数

表格内容超出当前宽度，可横向滚动查看更多列。
返回值
返回类型描述

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

参数

表格内容超出当前宽度，可横向滚动查看更多列。
返回值
返回类型描述

void

表格内容超出当前宽度，可横向滚动查看更多列。

subscribe

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

订阅远端音视频流。

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

参数
参数名描述
uid: number

要订阅的远端用户 ID。

Optional options?: object

设置是否订阅视频或音频。

  • Optional audio?: boolean
  • Optional video?: boolean
Optional onSuccess?: function

方法调用成功时执行的回调函数。返回值为音视频的拉流地址。

(url: string, rotation: number): void

参数

  • url: string
  • rotation: number
Optional onFailure?: function

方法调用失败时执行的回调函数。返回值为错误码和错误信息。

(err: any): void

参数

  • err: any
表格内容超出当前宽度，可横向滚动查看更多列。
返回值
返回类型描述

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：远端用户发送的音视频流，即声音和视频画面。
Optional onSuccess?: function

方法调用成功时执行的回调函数。无返回值。

(): void
Optional onFailure?: function

方法调用失败时执行的回调函数。返回值为错误码和错误信息。

(err: object): void

参数

  • err: object
    • code: number
    • reason: string
表格内容超出当前宽度，可横向滚动查看更多列。
返回值
返回类型描述

Promise<void>

表格内容超出当前宽度，可横向滚动查看更多列。

unmuteLocal

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

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

参数
参数名描述
target: string

选择恢复发送哪一种流，有三种选择：

  • audio：本地用户发送的音频流，即声音。
  • video：本地用户发送的视频流，即视频画面。
  • all：本地用户发送的音视频流，即声音和视频画面。
Optional onSuccess?: function

方法调用成功时执行的回调函数。无返回值。

(): void
Optional onFailure?: function

方法调用失败时执行的回调函数。返回值为错误码和错误信息。

(err: object): void

参数

  • err: object
    • code: number
    • reason: string
表格内容超出当前宽度，可横向滚动查看更多列。
返回值
返回类型描述

Promise<void>

表格内容超出当前宽度，可横向滚动查看更多列。

unpublish

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

停止发布本地音视频流。

参数
参数名描述
Optional onSuccess?: function

方法调用成功时执行的回调函数。无返回值。

(): void
Optional onFailure?: function

方法调用失败时执行的回调函数。返回值为错误码和错误信息。

(err: any): void

参数

  • err: any
表格内容超出当前宽度，可横向滚动查看更多列。
返回值
返回类型描述

Promise<void>

表格内容超出当前宽度，可横向滚动查看更多列。

unsubscribe

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

停止订阅远端音视频流。

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

参数
参数名描述
uid: number

要停止订阅的远端用户 ID。

Optional onSuccess?: function

方法调用成功时执行的回调函数。无返回值。

(): void
Optional onFailure?: function

方法调用成功时执行的回调函数。返回值为错误码和错误信息。

(err: any): void

参数

  • err: any
表格内容超出当前宽度，可横向滚动查看更多列。
返回值
返回类型描述

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

参数

表格内容超出当前宽度，可横向滚动查看更多列。
返回值
返回类型描述

void

表格内容超出当前宽度，可横向滚动查看更多列。

updatePlayerNetStatus

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

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

since

v2.5.3

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

参数
参数名描述
uid: number

远端用户的用户 ID。

event: any

微信组件的完整事件回调对象。请直接传入回调参数 e；SDK 会读取 e.detail。不要传入 e.detail。 Note：要收到 live-player 组件报告的网络状态数据，你需要在创建 live-player 组件时注册监听 bindnetstatus。详见微信小程序 live-player 文档。

表格内容超出当前宽度，可横向滚动查看更多列。
JavaScript
<live-player bindnetstatus="onPlayerNetStatus" />
client.updatePlayerNetStatus(uid, e)
返回值
返回类型描述

void

表格内容超出当前宽度，可横向滚动查看更多列。

updatePlayerStateChange

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

上报拉流状态。

since

v2.5.3

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

参数
参数名描述
uid: number

远端用户的用户 ID。

event: any

微信组件的完整事件回调对象。请直接传入回调参数 e；SDK 会读取 e.detail。不要传入 e.detail。 Note：要收到 live-player 组件报告的拉流状态码，你需要在创建 live-player 组件时注册监听 bindstatechange。详见微信小程序 live-player 文档。

表格内容超出当前宽度，可横向滚动查看更多列。
JavaScript
<live-player bindstatechange="onPlayerStateChange" />
client.updatePlayerStateChange(uid, e)
返回值
返回类型描述

void

表格内容超出当前宽度，可横向滚动查看更多列。

updatePusherNetStatus

updatePusherNetStatus(event: any): void

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

since

v2.5.3

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

参数
参数名描述
event: any

微信组件的完整事件回调对象。请直接传入回调参数 e；SDK 会读取 e.detail。不要传入 e.detail。 Note：要收到 live-pusher 组件报告的网络状态通知，你需要在创建 live-pusher 组件时注册监听 bindnetstatus。详见微信小程序 live-pusher 文档。

表格内容超出当前宽度，可横向滚动查看更多列。
JavaScript
<live-pusher bindnetstatus="onPusherNetStatus" />
client.updatePusherNetStatus(e)
返回值
返回类型描述

void

表格内容超出当前宽度，可横向滚动查看更多列。

updatePusherStateChange

updatePusherStateChange(event: any): void

上报推流状态。

since

v2.5.3

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

参数
参数名描述
event: any

微信组件的完整事件回调对象。请直接传入回调参数 e；SDK 会读取 e.detail。不要传入 e.detail。 Note：要收到 live-pusher 组件报告的推流状态码，你需要在创建 live-pusher 组件时注册监听 bindstatechange。详见微信小程序 live-pusher 文档。

表格内容超出当前宽度，可横向滚动查看更多列。
JavaScript
<live-pusher bindstatechange="onPusherStateChange" />
client.updatePusherStateChange(e)
返回值
返回类型描述

void

表格内容超出当前宽度，可横向滚动查看更多列。

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利