• 文档中心 /
• RTC 实时音视频 /
• 音视频SDK /
• Web /
• Client /

CloudHub JSSDK

• 概览
• CloudHubRTC
• CloudHubRTCObject
• Client
• ClientEvent
• ClientLiveTranscoding
• ClientChannelMediaRelayConfig
• Stream
• StreamEvent
• DeviceManager
• 常量

Client 的说明以及接口

• Client 接口提供音视频通话的核心功能，例如加入频道、发布和订阅音视频流等。
• 您可以通过 createClient 创建 Client 对象。一个 Client 对象代表一个本地客户端。

基础

init

方法作用: 初始化客户端对象。 使用该方法初始化客户端对象。

init(appId: string, options?:object, onSuccess?: function, onFailure?: function): void

// example:
client.init(appId, {}, function() {
  console.log("client initialized");
}, function(err) {
  console.log("client init failed", err);
});

renewToken

方法作用: 更新 Token。 如果启用了 Token 机制，过一段时间后使用的 Token 会失效。当触发 Client.on(‘token-privilege-will-expire’) 回调时 App 应重新获取 Token，然后调用该方法更新 Token，否则 SDK 无法和服务器建立连接。

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

// example:
client.renewToken(<token>,  function(){
  console.info("renewToken success");
}, function(errflag){
  console.error("renewToken fail", errflag);
});

Note： token 的生成由 authkey、secretkey 、channel、userid、expiretime 组合生成，所以请确保新生成的 token 使用的 authkey、secretkey 、channel、userid 不变。

事件

off

方法作用: 取消事件绑定。 该方法用于移除通过 Client.on() 绑定的事件。

off(eventType: string, listener: function): void

// example:
client.on("stream-published", function processStreamPublished(evt) {
  console.log("Stream Published");
  evt.stream.play("divId");
  client.off("stream-published", processStreamPublished);
}

on

方法作用: 进行事件绑定。 目前支持绑定的事件以及事件的作用详情请看 Client 事件文档

on(eventType: string, listener: function): void

// example:
client.on('first-audio-frame-decode', function (evt) {
  // 已完成远端音频首帧解码回调。
  // 本地订阅远端流成功并完成第一帧音频解码时会触发该回调。
  console.log('first-audio-frame-decode', evt);
})

offAll

方法作用: 取消指定类型下的所有事件绑定。

offAll(eventType: string): void

// example:
client.offAll("stream-network-quality");

频道

setChannelConfig

方法作用: 设置通道配置, 可以在进入频道前修改’编码方式’和’频道的使用场景'

client.setChannelConfig({
    codec: 'vp8',
    mode: 'live',
});

joinChannel

方法作用: 加入 CloudHubRTC 频道。
该方法让用户加入 CloudHubRTC 频道。调用该方法加入频道成功后，本地会触发 Client.on(“signal-connected”) 和 Client.on(“signal-connection-state-change”) 回调。
通信场景下，远端会触发 Client.on(“peer-join”) 回调。
直播场景下，加入频道的用户角色是主播则远端将会触发 Client.on(“peer-join”) 回调，如果是观众则远端不会触发 Client.on(“peer-join”) 回调。

joinChannel(token: string | null, channelId: string, uid: string | null, options?: object, onSuccess?: function, onFailure?: function): void

// example:
client.joinChannel(<token>, "1024", "userid", {}, function(uid) {
  console.log("client" + uid + "joined channel");
  // Create a local stream
  //……
}, function(err) {
  console.error("client join failed", err);
  // Error handling
});

Note:

• 加入频道成功后本地会触发 Client.on(“signal-connected”) 回调，详情请看 Client 事件文档。
• 当信令通道连接成功 (即：本地触发 Client.on(“signal-connected”) 回调)后，可能因为网络原因导致信令通道断开连接，SDK 会自动重新连接，重连成功后本地会再触发 Client.on(“signal-connected”)回调。
• 在信令通道断开连接期间，请不要进行任何通信行为（如：pubMsg、delMsg 等），建议界面出现浮层，不要让用户进行界面上的操作，直到信令通道连接恢复。

leaveChannel

方法作用: 离开 CloudHubRTC 频道。 该方法让用户离开 CloudHubRTC 频道。 调用该方法离开频道时，本地会触发 Client.on(“signal-connection-state-change”) 回调。 通信场景下，远端会触发 Client.on(“peer-leave”) 回调。 直播场景下，离开频道的用户角色是主播则远端将会触发 Client.on(“peer-leave”) 回调，如果是观众则远端不会触发 Client.on(“peer-leave”) 回调。

leaveChannel(): void

// example:
client.leaveChannel()

音视频

publish

方法作用: 发布本地音视频流。 该方法将本地音视频流发布至服务器。
发布音视频流之后，本地会触发 Client.on(“stream-published”) 回调；远端会触发 Client.on(“stream-added”) 回调。
直播场景下，用户的角色如果是观众 (audience)，在调用 publish 的时候会自动切换成主播(host) 角色, 本地会触发 Client.on(“client-role-changed”) 回调, 远端会触发 Client.on(“peer-join”)。

publish(stream: Stream, options?:object, onFailure?: function): void

// example:
client.publish(stream, {}, function(err) {
  console.log(err);
  // 处理发布失败的代码逻辑
})

Note:

• sdk 存在自动重新发布策略，一旦触发自动重新发布，则会触发 Client.on(“stream-reconnect-start”)和 Client.on(“stream-reconnect-end”)， 详情请看 Client 事件文档 的 stream-reconnect-start 和 stream-reconnect-end。
• 重新发布可能由以下原因引发：
  • “PUB_ACK_FAILED”: 发布 ACK 失败，一般是在发布过程中连接丢失【注：此失败 SDK 会自动重新发布】。
  • “PUB_TIMEOUT”: 发布超时【注：SDK 会自动重新发布】。
  • “PUB_CONNECTION_FAILED”: 发布后媒体传输通道建立失败【注：SDK 会自动重新发布】。
  • “PUB_CONNECTION_INSTABILITY”: 流已经发布成功，但是媒体传输通道不稳定，需要强制重新发布【注：SDK 会自动重新发布】。
  • “PUB_CONNECTION_ICE_DISCONNECTED”: 流已经发布成功，但媒体传输通道断开连接【注：SDK 会自动重新发布】。
  • “PUB_APP_HIDDEN_CATON”: 发布成功后因为隐藏 APP(如：按 Home 键) 后重新显示 APP 导致卡顿【注：SDK 会自动重新发布】。
  • “PUB_UNDEFINED_FAIL”: 未定义的发布失败【注：SDK 会自动重新发布】。
  • “PUB_SDK_FORCE_RECONN”: 因为浏览器版本过低，进行切换设备 / 切换分辨率，需要强制重新发布【注：SDK 会自动重新发布】。
• sdk 自动重新发布会先取消发布此流，然后再发布。因此如果流已经发布成功后进行的重新发布远端会触发 Client.on(“stream-removed”) 回调， 本地会触发 Client.on(“stream-unpublished”) 回调。如果重新发布成功本地会触发 Client.on(“stream-published”) 回调， 远端会触发 Client.on(“stream-added”) 回调。
• 标注有 “SDK 会自动重新发布” 的注释，SDK 会在失败后自动重新发布，如果不想再发布请调用 unpublish 方法。
• 建议失败原因为 “PUBLISH_STREAM_LIMIT” 时调用 unpublish 方法。
• 因为 SDK 重新发布机制，Client.on(“stream-removed”)、Client.on(“stream-unpublished”)、Client.on(“stream-published”)、Client.on(“stream-added”) 可能触发多次。 比如发布成功后因为链路原因重新发布成功，则本地会触发 Client.on(“stream-unpublished”) 回调后触发 Client.on(“stream-published”)， 远端会触发 Client.on(“stream-removed”) 回调后触发 Client.on(“stream-added”)。

subscribe

方法作用: 订阅远端音视频流。 该方法从服务器端接收远端音视频流。 订阅远端音视频流之后，本地会触发 Client.on(“stream-subscribed”) 回调。 如果订阅流中包含音频，还会触发 Client.on(“first-audio-frame-decode”) 回调；如果订阅流中包含视频，还会触发 Client.on(“first-video-frame-decode”) 回调。

subscribe(stream: Stream, options?:object, onFailure?: function): void

// example:
client.subscribe(stream, {}, function(err) {
    console.error("stream subscribe failed", err);
    // 处理订阅失败的代码逻辑
})

Note:

• sdk 存在自动重新订阅策略，一旦触发自动重新订阅，则会触发 Client.on(“stream-reconnect-start”)和 Client.on(“stream-reconnect-end”)， 详情请看 “Client 事件文档” 的 stream-reconnect-start 和 stream-reconnect-end。
• 重新订阅可能由以下原因引发：
  • “SUB_ACK_FAILED”: 订阅 ACK 失败，一般是在订阅过程中连接断开【注：SDK 会自动重新订阅】。
  • “SUB_TIMEOUT”: 订阅超时【注：SDK 会自动重新订阅】。
  • “SUB_CONNECTION_FAILED”: 订阅后媒体传输通道建立失败【注：SDK 会自动重新订阅】。
  • “SUB_CONNECTION_INSTABILITY”: 流已经订阅成功，但是媒体传输通道不稳定，需要强制重新订阅【注：SDK 会自动重新订阅】。
  • “SUB_CONNECTION_ICE_DISCONNECTED”: 流已经订阅成功，但媒体传输通道断开连接【注：SDK 会自动重新订阅】。
  • “SUB_APP_HIDDEN_CATON”: 订阅成功后因为隐藏 APP(如：按 Home 键) 后重新显示 APP 导致卡顿【注：SDK 会自动重新订阅】。
  • “SUB_UNDEFINED_FAIL”: 未定义的订阅失败【注：SDK 会自动重新订阅】。
• sdk 自动重新订阅会先取消订阅此流，本地会触发 Client.on(“stream-unsubscribed”) 回调，然后再订阅，如果重新订阅成功本地会触发 Client.on(“stream-subscribed”) 回调。 如果订阅流中包含音频，还会触发 Client.on(“first-audio-frame-decode”) 回调；如果订阅流中包含视频，还会触发 Client.on(“first-video-frame-decode”) 回调。
• 标注有 “SDK 会自动重新订阅” 的注释，SDK 会在失败后自动重新订阅，如果不想再订阅请调用 unsubscribe 方法。
• 因为 SDK 重新订阅机制，Client.on(“stream-unsubscribed”) 、Client.on(“stream-subscribed”) 可能触发多次，比如订阅成功后因为链路原因重新订阅成功，则会触发 Client.on(“stream-unsubscribed”) 和 Client.on(“stream-subscribed”)。

unpublish

方法作用: 取消发布本地音视频流。
该方法取消发布本地音视频流。取消发布音视频流之后，远端会触发 Client.on(“stream-removed”) 回调，本地会触发 Client.on(“stream-unpublished”) 回调。
直播场景下，用户的角色如果是主播 (host)，在调用 unpublish 后如果没有本地流发布，则会自动切换成观众(audience) 角色, 本地会触发 Client.on(“client-role-changed”) 回调, 远端会触发 Client.on(“peer-leave”)。

unpublish(stream: Stream, options?:object, onSuccess?: function, onFailure?: function): void

// example:
client.unpublish(stream, {}, function(){
  console.log("unpublish success");
  }, function(err) {
    console.log(err);
    //……
})

unsubscribe

方法作用: 取消订阅远端音视频流。
该方法取消接收远端音视频流。

unsubscribe(stream: Stream, options?:object, onSuccess?: function, onFailure?: function): void

// example:
client.unsubscribe(stream, {}, function(){
console.log("unsubscribe success");
}, function(err) {
    console.log(err);
    //……
})

getRemoteAudioStats

方法作用: 获取远端订阅流的音频统计数据。

getRemoteAudioStats(onCallback: function): void

// example:
client.getRemoteAudioStats((remoteAudioStatsMap) => {
  console.log("remoteAudioStatsMap", remoteAudioStatsMap);
});

enableAudioVolumeIndicator

方法作用: 启用说话者音量提示。 该方法允许 SDK 定期返回已发布 / 已订阅的流的音量提示。 启用该方法后，无论频道中有没有人说话，SDK 都会每 interval 毫秒触发 “stream-volume-indicator” 回调返回音量提示。 只返回流类型为 video 的音量提示（即：stream.getType() === “video”）

enableAudioVolumeIndicator(interval?:number): void

// example:
client.enableAudioVolumeIndicator(2000); // 每两秒触发 "volume-indicator" 回调
client.on("stream-volume-indicator", function(evt){
    console.log("stream-volume-indicator", evt);
});

getLocalAudioStats

方法作用: 获取本地发布流的音频统计数据。

getLocalAudioStats(onCallback: function): void

//example:
client.getLocalAudioStats((localAudioStats) => {
  console.log("localAudioStats:", localAudioStats);
});

Note：

• 部分统计数据需要在 stream-published 事件后进行统计，可能耗费 0-3 秒时间返回。
• Edge 浏览器不支持。

getLocalVideoStats

getLocalVideoStats(onCallback: function): void

//example:
client.getLocalVideoStats((localVideoStats) => {
    console.log("localVideoStats:", localVideoStats);
});

方法作用: 获取本地发布流的视频统计数据。

Note：

• 部分统计数据需要在 stream-published 事件后进行统计，可能耗费 0-3 秒时间返回。
• Edge 浏览器不支持。

getRemoteVideoStats

方法作用: 获取远端订阅流的视频统计数据。

getRemoteVideoStats(onCallback: function): void
// example:
client.getRemoteVideoStats((remoteVideoStatsMap) => {
  console.log("remoteVideoStatsMap", remoteVideoStatsMap);
});

Note:

• 统计数据需要在 stream-subscribed 事件后进行统计，可能耗费 0-3 秒时间返回。
• Edge 浏览器不支持。

enableMultiStream

方法作用: 是否启用多流模式。

enableMultiStream(bEnable:boolean): void

// example:
client.enableMultiStream(true)

Note:

• 多流模式指可以发布多个设备流。

• 需要启用多流模式时，请在 joinChannel 前调用 enableMultiStream 方法进行启用。

• joinChannel 调用后 enableMultiStream 方法将失效。

• 不支持多流模式和单流模式在频道内切换。

• 移动端不支持多流模式，即：不能发布多个设备流。

消息

sendChatMsg

方法作用: 发送聊天消息。 接收到聊天消息后会触发 Client.on(“recv-chat-msg”) 回调。

sendChatMsg(message:string, toId: string, extraData?:object): void

// example:
client.sendChatMsg("this is chat msg", CloudHubRTC.CONSTANTS.MSG_TO_ALLUSER, {"key1":"value1", "key2":"value2"});

Note：

• 1. 在 1 秒内发送的聊天消息过多时，聊天消息可能被丢弃，一般每秒 20-100 条。
• 2. CloudHub 会针对聊天消息进行敏感词过滤。

pubMsg

方法作用: 发送信令消息。 接收到 “发送信令消息” 后会触发 Client.on(“recv-pub-msg”) 回调。

pubMsg(msgName: string, msgId:string, toId:string, data:object, save?:boolean,associatedMsgID?:string): void

//example:
client.pubMsg("msgname", "msgid", CloudHubRTC.CONSTANTS.MSG_TO_ALLUSER, {testdata: 1}, true);

Note: 直播场景中建议只让部分人 (主播或者被授予权限的观众等) 能够发 pubMsg，而不要让所有人都能主动发 pubMsg【 比如: 10 万人的频道，观众有 9.99 万人，那么这些人不应该有主动发 pubMsg 的能力，而应该让主播授权给某个观众，这个观众才能发 pubMsg 】。

delMsg

方法作用: 删除信令消息。接收到 “删除信令消息” 后会触发 Client.on(“recv-del-msg”) 回调。

delMsg(msgName: string, msgId:string, toId:string): void

// example:
client.delMsg("msgname", "msgid", CloudHubRTC.CONSTANTS.MSG_TO_ALLUSER);

Note: 直播场景中建议只让部分人 (主播或者被授予权限的观众等) 能够发 delMsg，而不要让所有人都能主动发 delMsg【比如: 10 万人的频道，观众有 9.99 万人，那么这些人不应该有主动发 delMsg 的能力，而应该让主播授权给某个观众，这个观众才能发 delMsg】。

信令

getSignalConnectionState

getSignalConnectionState(): string

方法作用: 获取 SDK 与信令服务器的连接状态。 调用该方法会返回 SDK 与信令服务器的连接状态。 SDK 与信令服务器的连接状态，共有以下 3 种：

• DISCONNECTED：连接断开。该状态表示 SDK 处于以下任一阶段：
• 调用 Client.joinChannel 加入频道前的初始化阶段
• 调用 Client.leaveChannel 后的离开频道阶段
• CONNECTING：正在连接中。在调用 Client.joinChannel 或者连接中断自动重连的时候为此状态。
• CONNECTED：已连接。该状态表示用户已经加入频道，可以在频道内发布或订阅媒体流。

Note:

• 当状态变为 DISCONNECTED 后需要清除 UI 层缓存的数据，如流列表、用户列表、UI 界面、频道已关闭连接等。【注：此状态一般为用户调用 leaveChannel 或者被踢出频道时触发，会真正与服务器断开连接，不会进行重连】
• 当收到 signal-reconnect 事件时 (即：状态为 CONNECTING)，需要清除 UI 层缓存的数据，如流列表、用户列表、UI 界面等。【注：此状态一般为当前网络与服务器断开连接，会进行重连，当网络恢复时就能重连上服务器】

Note:

• 统计数据需要在 stream-subscribed 事件后进行统计，可能耗费 0-3 秒时间返回。
• Edge 浏览器不支持。

用户

evictUser

方法作用: 将用户踢出频道。

evictUser(uid:string, reason?:string): void
// example:
client.evictUser("uid", "reason");

setProperty

方法作用: 改变用户的自定义用户属性。 该方法改变某用户属性，并将属性变化通知给频道中的指定用户，指定用户会收到 Client.on(“user-properties-update”) 回调。

setProperty(uid: string, properties: object, toId?: string): void

// example:
client.setProperty("userid", {key1:value1}, CloudHubRTC.CONSTANTS.MSG_TO_ALLUSER);

Note：

• 直播场景中调用 setProperty 接口，如果被改变者为观众，则不会通知自定义用户属性改变，即 Client.on(“user-properties-update”) 不触发回调。
• 直播场景中不建议观众调用 setProperty 接口。

setClientRole

方法作用: 设置用户角色。 本方法仅适用于直播场景。 直播场景下，可以调用本方法设置用户角色。 在加入频道前，用户可以通过本方法设置自己的角色。 在加入频道后，用户可以通过本方法切换角色：

• 直播场景下，调用 Client.setClientRole 将主播 (host) 切换为观众(audience)，会自动将所有本地流取消发布。
• 直播场景下，用户的角色如果是主播 (host)，在调用 unpublish 后如果没有本地流发布，则会自动切换成观众(audience) 角色, 本地会触发 Client.on(“client-role-changed”) 回调, 远端会触发 Client.on(“peer-leave”)。
• 直播场景下，用户的角色如果是观众 (audience)，在调用 publish 的时候会自动切换成主播(host) 角色, 本地会触发 Client.on(“client-role-changed”) 回调, 远端会触发 Client.on(“peer-join”)。

如果你在加入频道后调用该方法切换用户角色，切换成功后，本地会触发 Client.on(“client-role-changed”) 回调；远端会触发 Client.on(“peer-join”) 或者 Client.on(“peer-leave”) 回调。

setClientRole(role:string, onCallback?:function): void

// example:
client.setClientRole("host", function(errinfo) {
  if (!errinfo) {
    console.log("setClientRole success");
  } else {
    console.log("setClientRole error", errinfo);
  }
});

Note： 通信场景（mode 设置为 rtc）无法使用本方法，默认所有用户都是 host 角色。

录制

startServerRecord

方法作用: 开始服务器端录制。 录制功能需要联系 cloudHub 的商务人员开启，如果没有开启，调用此接口也无法录制。 会触发 Client.on(“server-record-state-change”) 回调。

startServerRecord(config?:object): void
// example:
client.startServerRecord({});

Note: 连续调用两次 startServerRecord（即没调用 stopServerRecord 就再次调用 startServerRecord）将以第 1 次调用为准。

stopServerRecord

方法作用: 停止服务器端录制。 会触发 Client.on(“server-record-state-change”) 回调。

stopServerRecord(): void
// example:
client.stopServerRecord();

pauseServerRecord

方法作用: 暂停服务器端录制。

会触发 Client.on(“server-record-state-change”) 回调。

pauseServerRecord(): void

//  example:
client.pauseServerRecord();

resumeServerRecord

方法作用: 恢复服务器端录制。 会触发 Client.on(“server-record-state-change”) 回调。

resumeServerRecord(): void

//  example:
client.resumeServerRecord();

推流

addPublishStreamUrl

方法作用: 增加旁路推流地址。

addPublishStreamUrl(url:string): void

//  example:
client.removePublishStreamUrl("xxxx");

removePublishStreamUrl

方法作用: 删除旁路推流地址。

removePublishStreamUrl(url:string): void

setLiveTranscoding

方法作用: 设置直播推流转码。

setLiveTranscoding(liveTranscoding:LiveTranscoding): void

//  example:
var liveTranscoding = {
    "width": 640,
    "height": 360,
    "videoBitrate": 400,
    "videoFramerate": 15,
    "audioSampleRate": 48000,
    "audioBitrate": 48,
    "audioChannels": 1,
    "audioCodecProfile": 0,
    "videoGop": 30,
    "videoCodecProfile": 100,
    "streamCount": 1,
    "backgroundColor": 0x000000,
    "transcodingStreams": [{
      "x": 0,
      "y": 0,
      "width": 640,
      "height": 360,
      "zOrder": 0,
      "uid": "123456",
      "type": "video",
      "sourceID": "default_source_id"
    }]
  };
client.setLiveTranscoding(liveTranscoding);

startChannelMediaRelay

方法作用: 开始跨频道媒体流转发。

startChannelMediaRelay(channelMediaRelayConfig:ChannelMediaRelayConfig): void

//  example:
var channelMediaRelayConfig = client.produceChannelMediaRelayConfig();
  channelMediaRelayConfig.setDestChannelInfo(
    "destChannelName",
    {
      uid: "Relay_myChannelName_Requester_myuid"
    }
  );
client.startChannelMediaRelay(channelMediaRelayConfig);

Note： 相关流转发状态的事件请看 client.on(“channel-media-relay-state”) 的事件描述

updateChannelMediaRelay

方法作用: 更新跨频道媒体流转发。

updateChannelMediaRelay(channelMediaRelayConfig:ChannelMediaRelayConfig): void

// example:
channelMediaRelayConfig.setDestChannelInfo(
    "destChannelName2",
    {
        uid: "Relay_myChannelName_Requester_myuid"
    }
);
client.updateChannelMediaRelay(channelMediaRelayConfig);

Note： 相关流转发状态的事件请看 client.on(“channel-media-relay-state”) 的事件描述

stopChannelMediaRelay

方法作用: 停止跨频道媒体流转发。

stopChannelMediaRelay(): void

// example:
client.stopChannelMediaRelay();

Note: 相关流转发状态的事件请看 client.on(“channel-media-relay-state”) 的事件描述

produceChannelMediaRelayConfig

方法作用: 生产跨频道媒体转发配置实例。关于 ChannelMediaRelayConfig 详见 ChannelMediaRelayConfig 说明

produceChannelMediaRelayConfig(): void

// example:
var channelMediaRelayConfig = client.produceChannelMediaRelayConfig();