# Class Client (/zh-CN/api-reference/rtc/mini-program/classes/client) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## Constructors [#constructors] ### constructor [#constructor] new Client(options: object): [Client](/zh-CN/api-reference/rtc/mini-program/classes/client) **NOTE**:加解密功能仅在 IoT 场景适用。 加密密钥。 [ENCRYPTION_MODE](/zh-CN/api-reference/rtc/mini-program/enums/encryption-mode) 加密模式。 加密盐值,长度为 32 字节。 [Client](/zh-CN/api-reference/rtc/mini-program/classes/client) ## Methods [#methods] ### destroy [#destroy] destroy(onSuccess?: function, onFailure?: function): Promise<void> 销毁客户端对象。 方法调用成功时执行的回调函数。 (): void void 方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void void Promise<void> ### init [#init] init(appId: string, onSuccess?: function, onFailure?: function): Promise<void> 初始化客户端对象。 你的小程序项目的 App ID。 方法调用成功时执行的回调函数。无返回值。 (): void void 方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void void Promise<void> ### join [#join] join(channelKey: string, channel: string, uid: number | string, isAudioOnly: boolean, UidType?: [UidType](/zh-CN/api-reference/rtc/mini-program/enums/uidtype), onSuccess?: function, onFailure?: function): Promise<void> 加入频道。 在 app 服务器端生成的用于鉴权的 Token: - 安全要求不高:你可以使用控制台生成的临时 Token,详见生成 Token。 - 安全要求高:将值设为你的服务端生成的正式 Token,详见使用 Token 鉴权。 频道名,能标识直播频道的字符串。 指定用户的 ID。 - INT: 整数作为用户 ID,需为 32 位无符号整数。建议设置范围:0 到 (2³² - 1)。需要保证唯一。如果不指定 uid(即设为 null),服务器会报错。 - STRING: 字符串,长度不超过 255 个字符。 是否为纯音频场景: - `true`:纯音频场景。 - `false`:非纯音频场景。 [UidType](/zh-CN/api-reference/rtc/mini-program/enums/uidtype) 用户 ID 类型, 可选字段, 默认值为 INT 值 0。详见 [UidType](/zh-CN/api-reference/rtc/mini-program/enums/uidtype)。 方法调用成功时执行的回调函数。返回值为用户 ID。 (uid: number): void void 方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void void Promise<void> ### leave [#leave] leave(onSuccess?: function, onFailure?: function): Promise<void> 退出频道。 方法调用成功时执行的回调函数。无返回值。 (): void void 方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void void Promise<void> ### mute [#mute] mute(uid: number, target: string, onSuccess?: function, onFailure?: function): Promise<void> 停止接收远端用户的音视频流。 远端用户的 ID。 选择停止接收哪一种流,有三种选择: - `audio`:远端用户发送的音频流,即声音。 - `video`:远端用户发送的视频流,即视频画面。 - `all`:远端用户发送的音视频流,即声音和视频画面。 方法调用成功时执行的回调函数。无返回值。 (): void void 方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void void Promise<void> ### muteLocal [#mutelocal] muteLocal(target: string, onSuccess?: function, onFailure?: function): Promise<void> 停止发送本地用户的音视频流。 选择停止发送哪一种流,有三种选择: - `audio`:本地用户发送的音频流,即声音。 - `video`:本地用户发送的视频流,即视频画面。 - `all`:本地用户发送的音视频流,即声音和视频画面。 方法调用成功时执行的回调函数。无返回值。 (): void void 方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void void Promise<void> ### off [#off] off(event: string): void 取消监听流事件。 想要取消监听的流事件。 void ### on [#on] on(event: "client-banned"): void 用户被服务器禁止。 :::info[since] v2.5.4 当你在服务端踢除频道内的用户后,被踢出频道的用户会收到该回调。 ::: 当前触发的事件。`"client-banned"` 表示用户被服务器禁止。 void on(event: "error", callback: function): void 通知应用程序发生错误。 该回调中会包含详细的错误码和错误信息。 当前触发的事件。`"error"` 表示发生错误。 具体的事件详情。 (evt: object): void void void on(event: "stream-added", callback: function): void 通知应用程序已添加远端音视频流。 该回调中会包含已添加的远端用户 ID。 当前触发的事件。`"stream-added"` 表示已添加远端音视频流。 具体的事件详情。 (evt: object): void void void on(event: "stream-removed", callback: function): void 通知应用程序已删除远端音视频流。 该回调中会包含已删除的远端用户 ID。 当前触发的事件。`"stream-removed"` 表示已删除远端音视频流。 具体的事件详情。 (evt: object): void void void on(event: "update-url", callback: function): void 通知应用程序已更新 URL 地址。 该回调中会包含远端用户的 ID 和更新后的拉流地址。 当前触发的事件。`"update-url"` 表示已更新 URL 地址。 具体的事件详情。 (evt: object): void void void on(event: "video-rotation", callback: function): void 通知应用程序远端视频已旋转。 该回调中会包含视频的旋转信息以及远端用户的 ID。 当前触发的事件。`"video-rotation"` 表示远端视频已旋转。 具体的事件详情。 (evt: object): void void void on(event: "token-privilege-did-expire"): void Token 已过期回调。 :::info[since] v2.5.3 在 Token 过期后,会收到该回调。 一般情况下,在收到该消息之后,应向服务端重新申请 Token,并调用 [join](/zh-CN/api-reference/rtc/mini-program/classes/client#join) 方法传入新的 Token 重新加入频道。 ::: 当前触发的事件。`"token-privilege-did-expire"` 表示 Token 已过期。 void on(event: "token-privilege-will-expire"): void Token 服务即将过期回调。 :::info[since] v2.5.3 在调用 [join](/zh-CN/api-reference/rtc/mini-program/classes/client#join) 时如果指定了 Token,由于 Token 具有一定的时效,在通话过程中如果 Token 即将失效,SDK 会提前 30 秒触发该回调,提醒 App 更新 Token。当收到该回调时,你需要重新在服务端生成新的 Token, 然后调用 [renewToken](/zh-CN/api-reference/rtc/mini-program/classes/client#renewtoken) 将新生成的 Token 传给 SDK。 ::: 当前触发的事件。`"token-privilege-will-expire"` 表示 Token 即将过期。 void on(event: "mute-audio", callback: function): void 通知应用程序远端用户已停止发送音频流。 该回调中会包含停止发送音频流的用户 ID。 当前触发的事件。`"mute-audio"` 表示远端用户已停止发送音频流。 具体的事件详情。 (evt: object): void void void on(event: "mute-video", callback: function): void 通知应用程序远端用户已停止发送视频流。 该回调中会包含停止发送视频流的用户 ID。 当前触发的事件。`"mute-video"` 表示远端用户已停止发送视频流。 具体的事件详情。 (evt: object): void void void on(event: "unmute-audio", callback: function): void 通知应用程序远端用户已恢复发送音频流。 该回调中会包含恢复发送音频流的用户 ID。 当前触发的事件。`"unmute-audio"` 表示远端用户已恢复发送音频流。 具体的事件详情。 (evt: object): void void void on(event: "unmute-video", callback: function): void 通知应用程序远端用户已恢复发送视频流。 该回调中会包含恢复发送视频流的用户 ID。 当前触发的事件。`"unmute-video"` 表示远端用户已恢复发送视频流。 具体的事件详情。 (evt: object): void void void on(event: "channel-media-relay-event", callback: function): void 跨频道媒体流转发事件回调。 该回调报告跨频道媒体流转发过程中发生的事件。 当前触发的事件。`"channel-media-relay-event"` 表示报告媒体流转发事件。 具体的事件详情。 (evt: object): void void void on(event: "channel-media-relay-state", callback: function): void 跨频道媒体流转发状态回调。 当跨频道媒体流转发状态发生改变时,SDK 会触发该回调,并报告当前的转发状态以及相关的错误信息。 当前触发的事件。`"channel-media-relay-state"` 表示媒体流转发状态。 具体的事件详情。 (evt: object): void void void ### publish [#publish] publish(onSuccess?: function, onFailure?: function): Promise<string> 发布本地音视频流。 该方法将本地音视频流发布到 SD-RTN。互动直播中,调用该 API 的用户即默认为主播。 方法调用成功时执行的回调函数。返回值为音视频流的推流地址。 (url: string): void void 方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void void Promise<string> string 型,音视频流的推流地址。 ### rejoin [#rejoin] rejoin(channelKey: string, channel: string, uid: number | string, uids: number, isAudioOnly: boolean, UidType?: [UidType](/zh-CN/api-reference/rtc/mini-program/enums/uidtype), onSuccess?: function, onFailure?: function): Promise<void> 重新加入频道。 该方法让用户重新加入声网 RTC 频道。如果你的小程序中有切后台的场景需求,请确保使用该方法做好重连机制。 在 app 服务器端生成的用于鉴权的 Token: - 安全要求不高:你可以使用控制台生成的临时 Token,详见获取临时 Token。 - 安全要求高:将值设为你的服务端生成的正式 Token,详见[从服务端生成 Token](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 频道名,能标识直播频道的字符串。 指定用户的 ID。 - INT: 整数作为用户 ID,需为 32 位无符号整数。建议设置范围:0 到 (2³² - 1)。需要保证唯一性。如果不指定 uid(即设为 null),服务器会报错。 - STRING: 字符串,长度不超过 255 个字符。 频道内已有用户的用户 ID 列表。 是否为纯音频场景: - `true`:纯音频场景。 - `false`:非纯音频场景。 [UidType](/zh-CN/api-reference/rtc/mini-program/enums/uidtype) 用户 ID 类型, 可选字段, 默认值为 INT 值 0。详见 [UidType](/zh-CN/api-reference/rtc/mini-program/enums/uidtype)。 方法调用成功时执行的回调函数。返回值为用户 ID。 (uid: number): void void 方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void void Promise<void> ### renewToken [#renewtoken] renewToken(token: string, onSuccess?: function, onFailure?: function): Promise<void> 更新 Token。 :::info[since] v2.5.3 该方法更新 Token。如果启用了 Token 机制,过一段时间后密钥会失效。 当收到 `client.on("token-privilege-will-expire")` 消息时,调用该 API 以更新 Token,否则 SDK 会无法和服务器建立连接。 ::: 新的 Token。 方法调用成功时执行的回调函数。 (): void void 方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void void Promise<void> ### setAudioCodec [#setaudiocodec] setAudioCodec(audioCodec: [AudioCodec](/zh-CN/api-reference/rtc/mini-program/enums/audiocodec)): void 设置 IoT 设备使用的音频编码格式。 :::info[since] v2.5.6 ::: [AudioCodec](/zh-CN/api-reference/rtc/mini-program/enums/audiocodec) IoT 设备使用的音频编码格式,详见[AudioCodec](/zh-CN/api-reference/rtc/mini-program/enums/audiocodec)。 - 0: PCMU/G711u 格式。 - 8: PCMA/G711a 格式。 - 9: G722 格式。 void ### setRemoteVideoStreamType [#setremotevideostreamtype] setRemoteVideoStreamType(uid: number, streamType: 0 | 1, onSuccess?: function, onFailure?: function): Promise<void> 设置订阅的视频流类型。 :::info[since] v2.5.3 如果发送端选择发送视频双流 (大流和小流),该方法可以在订阅端选择接收大流还是小流。如果不设置,订阅端默认接收大流。 ::: 用户 ID。 方法调用成功时执行的回调函数。 (url: string): void void 方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: any): void void Promise<void> ### setRole [#setrole] setRole(role: string, onSuccess?: function, onFailure?: function): Promise<void> 设置用户角色。 注:如果在主播已 `publish` 的状态下调用该方法将用户角色设置为 `audience`,会导致之前的推流地址无效。 用户角色。选择如下一种角色: - `broadcaster`:将用户角色设置为主播。主播可以调用 [publish](/zh-CN/api-reference/rtc/mini-program/classes/client#publish) 和 [unpublish](/zh-CN/api-reference/rtc/mini-program/classes/client#unpublish) 方法。 - `audience`:(默认) 将用户角色设置为观众。观众不能调用 [publish](/zh-CN/api-reference/rtc/mini-program/classes/client#publish) 和 [unpublish](/zh-CN/api-reference/rtc/mini-program/classes/client#unpublish) 方法。 方法调用成功时执行的回调函数。无返回值。 (): void void 方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void void Promise<void> ### startChannelMediaRelay [#startchannelmediarelay] startChannelMediaRelay(config: [ChannelMediaRelayConfiguration](/zh-CN/api-reference/rtc/mini-program/interfaces/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** - 跨频道媒体流转发功能需要[提交工单](https://ticket.shengwang.cn/)联系技术支持开通。 - 该功能不支持 String 型 UID。 - 请在成功加入频道后调用该方法。 - 直播场景下,只有主播可以调用该方法。 - 成功调用该方法后,若你想再次调用该方法,必须先调用 [stopChannelMediaRelay](/zh-CN/api-reference/rtc/mini-program/classes/client#stopchannelmediarelay) 方法退出当前的转发状态。 #### example [#example] **示例代码** ```javascript client.startChannelMediaRelay(channelMediaConfig, function(e) { if(e) { utils.notification(`startChannelMediaRelay failed: ${JSON.stringify(e)}`); } else { utils.notification(`startChannelMediaRelay success`); } }); ``` [ChannelMediaRelayConfiguration](/zh-CN/api-reference/rtc/mini-program/interfaces/channelmediarelayconfiguration) 跨频道媒体流转发参数配置,详见 [ChannelMediaRelayConfiguration](/zh-CN/api-reference/rtc/mini-program/interfaces/channelmediarelayconfiguration)。 媒体流转发是否成功的回调。 - `null`:媒体流转发成功。 - 如果失败,会通过 [ChannelMediaError](/zh-CN/api-reference/rtc/mini-program/classes/channelmediaerror) 提供错误信息。 (err: null | [ChannelMediaError](/zh-CN/api-reference/rtc/mini-program/classes/channelmediaerror)): void null | [ChannelMediaError](/zh-CN/api-reference/rtc/mini-program/classes/channelmediaerror) void void ### stopChannelMediaRelay [#stopchannelmediarelay] stopChannelMediaRelay(callback: function): void 停止跨频道媒体流转发。 一旦停止转发,用户会退出所有的目标频道。 调用该方法会触发 `Client.on("channel-media-relay-state")` 回调。 - 如果成功停止跨频道媒体流转发,该回调中 `state` 为 0。 - 如果未成功停止跨频道媒体流转发,该回调中 `state` 为 3,`code` 错误码可能为 2 或 8,一般是在网络较差的情况下,退出的消息发送不成功导致的。你可以调用 [Client.leave](/zh-CN/api-reference/rtc/mini-program/classes/client#leave) 离开频道来停止跨频道媒体流转发。 #### example [#example-1] **示例代码** ```javascript stopChannelMediaRelay: function() { client.stopChannelMediaRelay(function(e) { if(e) { utils.notification(`stopChannelMediaRelay failed: ${JSON.stringify(e)}`); } else { utils.notification(`stopChannelMediaRelay success`); } }); } ``` 停止跨频道媒体流转发是否成功的回调。 - `null`:停止跨频道媒体流转发成功。 - 如果失败,会通过 [ChannelMediaError](/zh-CN/api-reference/rtc/mini-program/classes/channelmediaerror) 提供错误信息。 (err: null | [ChannelMediaError](/zh-CN/api-reference/rtc/mini-program/classes/channelmediaerror)): void null | [ChannelMediaError](/zh-CN/api-reference/rtc/mini-program/classes/channelmediaerror) void void ### subscribe [#subscribe] subscribe(uid: number, options?: object, onSuccess?: function, onFailure?: function): Promise<object> 订阅远端音视频流。 该方法从 SD-RTN 订阅并接收远端音视频流。 要订阅的远端用户 ID。 设置是否订阅视频或音频。 方法调用成功时执行的回调函数。返回值为音视频的拉流地址。 (url: string, rotation: number): void void 方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: any): void void Promise<object> 一个对象,包含以下数据: - `url`:string 型,音视频流的拉流地址 - `rotation`:number 型,视频帧顺时针旋转角度。 ### unmute [#unmute] unmute(uid: number, target: string, onSuccess?: function, onFailure?: function): Promise<void> 恢复接收远端用户的音视频流。 远端用户的 ID。 选择停止接收哪一种流,有三种选择: - `audio`:远端用户发送的音频流,即声音。 - `video`:远端用户发送的视频流,即视频画面。 - `all`:远端用户发送的音视频流,即声音和视频画面。 方法调用成功时执行的回调函数。无返回值。 (): void void 方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void void Promise<void> ### unmuteLocal [#unmutelocal] unmuteLocal(target: string, onSuccess?: function, onFailure?: function): Promise<void> 恢复发送本地用户的音视频流。 选择恢复发送哪一种流,有三种选择: - `audio`:本地用户发送的音频流,即声音。 - `video`:本地用户发送的视频流,即视频画面。 - `all`:本地用户发送的音视频流,即声音和视频画面。 方法调用成功时执行的回调函数。无返回值。 (): void void 方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: object): void void Promise<void> ### unpublish [#unpublish] unpublish(onSuccess?: function, onFailure?: function): Promise<void> 停止发布本地音视频流。 方法调用成功时执行的回调函数。无返回值。 (): void void 方法调用失败时执行的回调函数。返回值为错误码和错误信息。 (err: any): void void Promise<void> ### unsubscribe [#unsubscribe] unsubscribe(uid: number, onSuccess?: function, onFailure?: function): Promise<void> 停止订阅远端音视频流。 该方法停止从 SD-RTN 订阅并接收远端音视频流。 要停止订阅的远端用户 ID。 方法调用成功时执行的回调函数。无返回值。 (): void void 方法调用成功时执行的回调函数。返回值为错误码和错误信息。 (err: any): void void Promise<void> ### updateChannelMediaRelay [#updatechannelmediarelay] updateChannelMediaRelay(config: [ChannelMediaRelayConfiguration](/zh-CN/api-reference/rtc/mini-program/interfaces/channelmediarelayconfiguration), callback: function): void 更新媒体流转发的目标频道。 成功开始跨频道转发媒体流后,如果你希望添加或删除媒体流转发的目标频道,可以调用该方法。 调用该方法后,SDK 会触发 `Client.on("channel-media-relay-event")` 回调。 - 如果更新成功,回调中 `code` 为 7。 - 如果更新失败,回调中 `code` 为 8,同时还会触发 `Client.on("channel-media-relay-state")` 回调,其中 `state` 为 3。出错后跨频道媒体流转发状态会被重置,你需要调用 [startChannelMediaRelay](/zh-CN/api-reference/rtc/mini-program/classes/client#startchannelmediarelay) 重新开始跨频道媒体流转发。 **Note** - 请在 [startChannelMediaRelay](/zh-CN/api-reference/rtc/mini-program/classes/client#startchannelmediarelay) 后调用该方法,更新媒体流转发的频道。 - 跨频道媒体流转发最多支持 4 个目标频道。 #### example [#example-2] **示例代码** ```javascript client.updateChannelMediaRelay(channelMediaConfig, function(e) { if(e) { utils.notification(`updateChannelMediaRelay failed: ${JSON.stringify(e)}`); } else { utils.notification(`updateChannelMediaRelay success`); } }); ``` [ChannelMediaRelayConfiguration](/zh-CN/api-reference/rtc/mini-program/interfaces/channelmediarelayconfiguration) 跨频道媒体流转发参数配置,详见 [ChannelMediaRelayConfiguration](/zh-CN/api-reference/rtc/mini-program/interfaces/channelmediarelayconfiguration)。 更新目标频道是否成功的回调。 - `null`:更新目标频道成功。 - 如果失败,会通过 [ChannelMediaError](/zh-CN/api-reference/rtc/mini-program/classes/channelmediaerror) 提供错误信息。 (err: null | [ChannelMediaError](/zh-CN/api-reference/rtc/mini-program/classes/channelmediaerror)): void null | [ChannelMediaError](/zh-CN/api-reference/rtc/mini-program/classes/channelmediaerror) void void ### updatePlayerNetStatus [#updateplayernetstatus] updatePlayerNetStatus(uid: number, event: any): void 上报拉流过程中的网络状态。 :::info[since] v2.5.3 当收到 live-player 组件报告的网络状态通知时,你可以调用该接口将其上报给声网的数据中心。 ::: 远端用户的用户 ID。 微信组件的完整事件回调对象。请直接传入回调参数 `e`;SDK 会读取 `e.detail`。不要传入 `e.detail`。 Note:要收到 live-player 组件报告的网络状态数据,你需要在创建 live-player 组件时注册监听 `bindnetstatus`。详见[微信小程序 live-player 文档](https://developers.weixin.qq.com/miniprogram/dev/component/live-player.html)。 ```javascript client.updatePlayerNetStatus(uid, e) ``` void ### updatePlayerStateChange [#updateplayerstatechange] updatePlayerStateChange(uid: number, event: any): void 上报拉流状态。 :::info[since] v2.5.3 当收到 live-player 组件报告的拉流状态变化通知时,你可以调用该接口将其上报给声网的数据中心。 ::: 远端用户的用户 ID。 微信组件的完整事件回调对象。请直接传入回调参数 `e`;SDK 会读取 `e.detail`。不要传入 `e.detail`。 Note:要收到 live-player 组件报告的拉流状态码,你需要在创建 live-player 组件时注册监听 `bindstatechange`。详见[微信小程序 live-player 文档](https://developers.weixin.qq.com/miniprogram/dev/component/live-player.html)。 ```javascript client.updatePlayerStateChange(uid, e) ``` void ### updatePusherNetStatus [#updatepushernetstatus] updatePusherNetStatus(event: any): void 上报推流过程中的网络状态。 :::info[since] v2.5.3 当收到 live-pusher 组件报告的网络状态通知时,你可以调用该接口将其上报给声网的数据中心。 ::: 微信组件的完整事件回调对象。请直接传入回调参数 `e`;SDK 会读取 `e.detail`。不要传入 `e.detail`。 Note:要收到 live-pusher 组件报告的网络状态通知,你需要在创建 live-pusher 组件时注册监听 `bindnetstatus`。详见[微信小程序 live-pusher 文档](https://developers.weixin.qq.com/miniprogram/dev/component/live-pusher.html)。 ```javascript client.updatePusherNetStatus(e) ``` void ### updatePusherStateChange [#updatepusherstatechange] updatePusherStateChange(event: any): void 上报推流状态。 :::info[since] v2.5.3 当收到 live-pusher 组件报告的推流状态变化通知时,你可以调用该接口将其上报给声网的数据中心。 ::: 微信组件的完整事件回调对象。请直接传入回调参数 `e`;SDK 会读取 `e.detail`。不要传入 `e.detail`。 Note:要收到 live-pusher 组件报告的推流状态码,你需要在创建 live-pusher 组件时注册监听 `bindstatechange`。详见[微信小程序 live-pusher 文档](https://developers.weixin.qq.com/miniprogram/dev/component/live-pusher.html)。 ```javascript client.updatePusherStateChange(e) ``` void