CloudHub JSSDK

DeviceManager 的说明以及接口

DeviceManager 接口提供对设备进行的操作的方法，例如枚举设备、设备检测等。
您可以通过 getDeviceManager 获取 DeviceManager 对象。

基础

getDevices

getDevices(onCallback: function): void

方法作用: 枚举可用的媒体输入 / 输出设备，比如麦克风、摄像头、扬声器等。

调用成功后 SDK 会通过 MediaDeviceInfo 对象返回可用的媒体设备。

名称	类型	描述
onCallback	function	成功回调，回调参数携带 MediaDeviceInfo 对象。 MediaDeviceInfo: 详情查看 CloudHubRTC 数据对象文档的 MediaDeviceInfo 说明

Example:

CloudHubRTC.getDeviceManager().getDevices (function(devices) {
  console.log("devices:", devices, devices.length);
});

麦克风

getMicrophones

getMicrophones(onCallback: function): void

方法作用: 枚举音频输入设备。

该方法枚举可用的音频输入设备，比如麦克风。

调用成功后 SDK 会通过 MediaDeviceInfo 对象返回可用的音频输入设备。

名称	类型	描述
onCallback	function	成功回调，回调参数携带 MediaDeviceInfo。 MediaDeviceInfo: 详情查看 CloudHubRTC 数据对象文档的 MediaDeviceInfo 说明

startMicrophoneTest

startMicrophoneTest(deviceId: string, options?: object, onSuccess?:function, onFailure?: function): void

方法作用: 开始进行麦克风设备检测。

名称	类型	描述
deviceId	string	要检测设备 ID, 设备 ID 通过 getDevices 方法获取
options	object	配置项，包含属性如下： * isplay?: boolean 是否创建音频节点元素进行播放，缺省为 true。 * onRealVolume?: function 实时音量回调，缺省为 null/undefined。 * volume?: number 当 isplay 为 true 时，设置播放的音量大小，取值范围在 [0,100], 缺省为 100。
onSuccess	function	成功的回调，回调参数携带播放节点的节点 ID。
onFailure	function	失败的回调，失败的参数携带格式如：{errflag: “NOT_ALLOWED_ERROR”, message: “Permission denied”}。 errflag 字段可能出现以下值： * “NOT_SUPPORT”: 浏览器不支持。 * “INVALID_ARG”: 无效的参数。 * “NOT_ALLOWED_ERROR”: 用户拒绝授予对应的麦克风权限。 * “NOT_READABL_EERROR”: 麦克风被占用。 * “ABORT_ERROR”: 设备中止错误。 * “NOT_FOUND_ERROR”: 没有找到设备。 * “OVER_CONSTRAINED_ERROR”: 配置的约束无法满足要求错误。 * “SECURITY_ERROR”: 安全错误, 网页使用设备媒体被禁止。这个机制是否开启或者关闭取决于单个用户的偏好设置。 * “TYPE_ERROR”: 设备约束都设置为 false 了。 * “REQ_TIMEOUT”: 请求设备超时。 * “UNDEFINED_ERROR”: 未定义错误。 * “MEDIA_ELE_PLAY_ERROR”: 播放报错 [注：message 的值为 StreamPlayError，StreamPlayError: 详情查看 “CloudHubRTC 数据对象文档的 StreamPlayError 说明” ]。 Note: 1. 可以参考浏览器 getUserMedia 接口错误类型。 2. 可以参考 “常量声明以及补充说明” 的浏览器 getUserMedia 接口失败的错误类型。

Note:

若当前有麦克风正在检测，调用 startMicrophoneTest 会自动停止正在进行的检测操作，但若要停止麦克风检测，必须调用 stopMicrophoneTest 方法。
一般情况下，播放音频 / 带声音的视频时，浏览器会要求该行为由手势触发，详见 “处理浏览器的自动播放策略”。
移动端浏览器不支持。

Example:

CloudHubRTC.getDeviceManager().startMicrophoneTest("deviceId", {}, function(mediaEleId) {
  console.log("startMicrophoneTest success", mediaEleId);
}, function(errinfo){
  console.error("startMicrophoneTest fail:", errinfo);
  if (errinfo && errinfo.errflag ===  "MEDIA_ELE_PLAY_ERROR"){

  }
});

stopMicrophoneTest

stopMicrophoneTest(): void

方法作用: 停止进行麦克风设备检测。

Example:

CloudHubRTC.getDeviceManager().stopMicrophoneTest();

setDefaultMicrophoneId

setDefaultMicrophoneId(deviceId:string): void

方法作用: 设置默认的麦克风 id。

名称	类型	描述
deviceId	string	设备 ID。

Example:

CloudHubRTC.getDeviceManager().setDefaultMicrophoneId("deviceid");

getDefaultMicrophoneId

getDefaultMicrophoneId(): string

方法作用: 获取默认的麦克风 id。

Note:

如果为 "" 表示没有设置过默认设备
在本地流类型为 video(即：stream.getType() === “video”) 进行初始化时，如果没有设置过默认设备且没有指定本地流应该使用的设备 id，则 SDK 会自动设置默认设备 id。
移动端不支持设置麦克风 / 扬声器，获取默认设备 id 没有任何意义

Example:

CloudHubRTC.getDeviceManager().getDefaultMicrophoneId();

Returns string

返回默认设备 id，如果为 "" 则表示没有设置过默认设备。

摄像头

getCameras

getCameras(onCallback: function): void

方法作用: 枚举视频输入设备。

该方法枚举可用的视频输入设备，比如摄像头。

调用成功后 SDK 会通过 MediaDeviceInfo 对象返回可用的视频输入设备。

名称	类型	描述
onCallback	function	成功回调，回调参数携带 MediaDeviceInfo。 MediaDeviceInfo: 详情查看 CloudHubRTC 数据对象文档的 MediaDeviceInfo 说明

startCameraTest

startCameraTest(deviceId: string, elementId: string, options?: object, onSuccess?:function, onFailure?: function): void

方法作用: 开始进行摄像头检测。

名称	类型	描述
deviceId	string	要检测设备 ID, 设备 ID 通过 getDevices 方法获取
elementId	string	节点元素 ID。该节点元素用于盛放摄像头对应的视频窗口，一般应为 div 节点
options	object	配置项，包含属性如下： 1. fit?: “cover” \| “contain”: 设置视频播放时的显示模式，有 “cover” 和 “contain” 可以选择，默认为 “cover”，cover 模式和 contain 模式区别如下: * cover 模式：优先保证视窗被填满。视频尺寸等比缩放，直至整个视窗被视频填满。如果视频长宽与显示窗口不同，则视频流会按照显示视窗的比例进行周边裁剪或图像拉伸后填满视窗，可以参考 CSS 属性中 object-fit 的 cover 选项。 * contain 模式：优先保证视频内容全部显示。视频尺寸等比缩放，直至视频窗口的一边与视窗边框对齐。如果视频尺寸与显示视窗尺寸不一致，在保持长宽比的前提下，将视频进行缩放后填满视窗，缩放后的视频四周会有一圈黑边，可以参考 CSS 属性中 object-fit 的 contain 选项。 2. mirror?: boolean 用于表示是否以镜面方式显示视频，缺省 false。 3. loader?: boolean 用于表示未加载到视频数据时是否显示 “加载中” 样式，缺省 true。
onSuccess	function	成功的回调。
onFailure	function	失败的回调，失败的参数携带格式如：{errflag: “NOT_ALLOWED_ERROR”, message: “Permission denied”}。 errflag 字段可能出现以下值： * “NOT_SUPPORT”: 浏览器不支持。 * “INVALID_ARG”: 无效的参数。 * “NOT_ALLOWED_ERROR”: 用户拒绝授予对应的摄像头权限。 * “NOT_READABL_EERROR”: 摄像头被占用。 * “ABORT_ERROR”: 设备中止错误。 * “NOT_FOUND_ERROR”: 没有找到设备。 * “OVER_CONSTRAINED_ERROR”: 配置的约束无法满足要求错误。 * “SECURITY_ERROR”: 安全错误, 网页使用设备媒体被禁止。这个机制是否开启或者关闭取决于单个用户的偏好设置。 * “TYPE_ERROR”: 设备约束都设置为 false 了。 * “REQ_TIMEOUT”: 请求设备超时。 * “UNDEFINED_ERROR”: 未定义错误。 * “MEDIA_ELE_PLAY_ERROR”: 播放报错 [注：message 的值为 StreamPlayError，StreamPlayError: 详情查看 “CloudHubRTC 数据对象文档的 StreamPlayError 说明” ]。 Note: 1. 可以参考浏览器 getUserMedia 接口错误类型。 2. 可以参考 “常量声明以及补充说明” 的浏览器 getUserMedia 接口失败的错误类型。

Note:

若当前有摄像头正在检测，调用 startCameraTest 会自动停止正在进行的检测操作，但若要停止摄像头检测，必须调用 stopCameraTest 方法。
移动端浏览器不支持。

Example:

CloudHubRTC.getDeviceManager().startCameraTest(
  "deviceId",
  "elementId",
  {},
  function() {
    console.log("startCameraTest success");
  },
  function(errinfo){
    console.error("startCameraTest fail:", errinfo);
    if (errinfo && errinfo.errflag ===  "MEDIA_ELE_PLAY_ERROR"){

  }
});

stopCameraTest

stopCameraTest(deviceId?: string): void

方法作用: 停止进行摄像头检测。

名称	类型	描述
deviceId	string	要停止检测的设备 ID。 Note: 如果 deviceId 为 null/undefined, 则会停止所有的摄像头检测。

Example:

CloudHubRTC.getDeviceManager().stopCameraTest("deviceId");

setDefaultCameraId

setDefaultCameraId(deviceId:string): void

方法作用: 设置默认的摄像头 id。

名称	类型	描述
deviceId	string	设备 ID。

Example:

CloudHubRTC.getDeviceManager().setDefaultCameraId("deviceid");

getDefaultCameraId

getDefaultCameraId(): string

方法作用: 获取默认的摄像头 id。

Note:

如果为 "" 表示没有设置过默认设备
在本地流类型为 video(即：stream.getType() === “video”) 进行初始化时，如果没有设置过默认设备且没有指定本地流应该使用的设备 id，则 SDK 会自动设置默认设备 id。
移动端的摄像头设备 id 中，frontCameraDeviceId 表示前置摄像头，backCameraDeviceId 为后置摄像头。

Example:

CloudHubRTC.getDeviceManager().getDefaultCameraId();

Returns string

返回默认设备 id，如果为 "" 则表示没有设置过默认设备。

扬声器

getDefaultSpeakerId

getDefaultSpeakerId(): string

方法作用: 获取默认的扬声器 id。

Note:

如果为 "" 表示没有设置过默认设备
在本地流类型为 video(即：stream.getType() === “video”) 进行初始化时，如果没有设置过默认设备且没有指定本地流应该使用的设备 id，则 SDK 会自动设置默认设备 id。
移动端不支持设置麦克风 / 扬声器，获取默认设备 id 没有任何意义

Example:

CloudHubRTC.getDeviceManager().getDefaultSpeakerId();

Returns string

返回默认设备 id，如果为 "" 则表示没有设置过默认设备。

getSpeakers

getSpeakers(onCallback: function): void

方法作用: 枚举音频输出设备。

该方法枚举可用的音频输出设备，比如扬声器。

调用成功后 SDK 会通过 MediaDeviceInfo 对象返回可用的音频输出设备。

名称	类型	描述
onCallback	function	成功回调，回调参数携带 MediaDeviceInfo。 MediaDeviceInfo: 详情查看 CloudHubRTC 数据对象文档的 MediaDeviceInfo 说明

Note： 仅支持 Chrome 49 及以上。

startSpeakerTest

startSpeakerTest(deviceId: string, audiourl: string, options?: object, onSuccess?:function, onFailure?: function): void

方法作用: 开始进行扬声器设备检测。

名称	类型	描述
deviceId	string	要检测设备 ID, 设备 ID 通过 getDevices 方法获取
audiourl	string	声音文件的绝对地址，建议使用 wav 格式的文件。
options	object	配置项，包含属性如下： 1、 loop?: boolean 是否循环播放测试音频文件，缺省为 true。 2、 volume?: number 设置播放的音量大小，取值范围在 [0,100], 缺省为 100。
onSuccess	function	成功的回调
onFailure	function	失败的回调，失败的参数携带格式如：{errflag: “NOT_SUPPORT”, message: “browser not support set speaker”}。 errflag 字段可能出现以下值： * “NOT_SUPPORT”: 浏览器不支持。 * “INVALID_ARG”: 无效的参数。 * “MEDIA_ELE_PLAY_ERROR”: 播放报错 [注：message 的值为 StreamPlayError，StreamPlayError: 详情查看 “CloudHubRTC 数据对象文档的 StreamPlayError 说明” ]。 * “UNDEFINED_ERROR”: 未定义错误。

Note:

若当前有扬声器正在检测，调用 startSpeakerTest 会自动停止正在进行的检测操作，但若要停止麦克风检测，必须调用 stopSpeakerTest 方法。
一般情况下，播放音频 / 带声音的视频时，浏览器会要求该行为由手势触发，详见 “处理浏览器的自动播放策略”。
移动端浏览器不支持。

Example:

CloudHubRTC.getDeviceManager().startSpeakerTest("deviceId", "audiourl", {}, function() {
  console.log("startSpeakerTest success");},function(errinfo){
  console.error("startSpeakerTest fail:", errinfo);
  if (errinfo && errinfo.errflag ===  "MEDIA_ELE_PLAY_ERROR"){

  }
});

stopSpeakerTest

stopSpeakerTest(): void

方法作用: 停止进行扬声器设备检测。

Example:

CloudHubRTC.getDeviceManager().stopSpeakerTest();

registerDeviceChangeListener

registerDeviceChangeListener(onListener: function | null): void

方法作用: 注册 / 移除设备监听器。

主要用于监听设备的添加 / 移除。

名称	类型	描述
onListener	function \| null	当设备变化时会回调该函数, 回调携带的参数: type 和 changedevices，当 onListener 为 null/undefined 时表示移除设备监听器。 type 的值有：“device_add” 和 “device_remove”。 changedevices: 类型为 object，json 格式如下: * {[kind]:[MediaDeviceInfo]}，例如：{videoinput:[{kind:“videoinput”,label:“label”,deviceId:“deviceid”}]}。 * MediaDeviceInfo：详情查看 “CloudHubRTC 数据对象文档的 MediaDeviceInfo 说明”

Note: 经测试，极个别设备的行为异常，在未发生插拔设备的操作时，也会不断触发回调函数。

Example 注册设备监听器:

CloudHubRTC.getDeviceManager().registerDeviceChangeListener(function(type, changedevices){
      console.error("registerDeviceChangeListener:", type, changedevices);
});

Example 移除设备监听器:

CloudHubRTC.getDeviceManager().registerDeviceChangeListener(null);

setDefaultSpeakerId

setDefaultSpeakerId(deviceId:string): void

方法作用: 设置默认的扬声器 id。

名称	类型	描述
deviceId	string	设备 ID。

Example:

CloudHubRTC.getDeviceManager().setDefaultSpeakerId("deviceid");

associateElementsToSpeaker

associateElementsToSpeaker(deviceId: string, elementArr?: array, onCallback?: function): void

方法作用: 关联媒体元素节点 (video/audio) 到扬声器。

名称	类型	描述
deviceId	string	扬声器的设备 ID。
elementArr	array	要关联的节点元素数组。 Note: 如果传 null/undefined，则表示将界面的所有 audio/video 都设置该扬声器 ID。
onCallback	function	回调函数，参数携带 err，如果成功 err 为 undefined 表示设置成功，否则表示设置失败。

Note： 移动端浏览器不支持。

Example:

CloudHubRTC.getDeviceManager().associateElementsToSpeaker("deviceId", undefined, function(err){
    if(err)
      console.error("associateElementsToSpeaker fail, err:", err);
    else
      console.log("associateElementsToSpeaker success");
});

桌面共享

checkScreenIsSupport

checkScreenIsSupport(): boolean

方法作用: 检测是否支持屏幕 / 程序共享。

Example:

CloudHubRTC.getDeviceManager().checkScreenIsSupport();

Returns boolean

false: 不支持。
true: 支持。

音视频

getVideoTrack

getVideoTrack(deviceId: string, options?:object, onSuccess?:function, onFailure?: function): void

方法作用: 获取视频轨道。

名称	类型	描述
deviceId	string	设备 ID。
options	object	配置项，有如下配置： * width?:number 视频宽度，缺省为默认的视频宽度。 * height?:number 视频高度，缺省为默认的视频高度。 * fps?:number 视频帧率，缺省为默认的视频帧率。
onSuccess	function	成功的回调
onFailure	function	失败的回调，失败的参数携带格式如：{errflag: “NOT_ALLOWED_ERROR”, message: “Permission denied”}。 errflag 字段可能出现以下值： * “NOT_SUPPORT”: 浏览器不支持。 * “INVALID_ARG”: 无效的参数。 * “NOT_ALLOWED_ERROR”: 用户拒绝授予对应的摄像头或麦克风权限。 * “NOT_READABL_EERROR”: 摄像头或麦克风被占用。 * “ABORT_ERROR”: 设备中止错误。 * “NOT_FOUND_ERROR”: 没有找到设备。 * “OVER_CONSTRAINED_ERROR”: 配置的约束无法满足要求错误。 * “SECURITY_ERROR”: 安全错误, 网页使用设备媒体被禁止。这个机制是否开启或者关闭取决于单个用户的偏好设置。 * “TYPE_ERROR”: 设备约束都设置为 false 了。 * “REQ_TIMEOUT”: 请求设备超时。“UNDEFINED_ERROR”: 未定义错误。

Example:

CloudHubRTC.getDeviceManager().getVideoTrack("deviceId", {}, function(track) {
  console.log("getVideoTrack success", track);
  }, function(errStr){
    console.error("getVideoTrack fail:", errStr);
});

getAudioTrack

getAudioTrack(deviceId: string, options?:object, onSuccess?:function, onFailure?: function): void

方法作用: 获取音频轨道。

名称	类型	描述
deviceId	string	设备 ID。
options	object	配置项。
onSuccess	function	成功的回调
onFailure	function	失败的回调，失败的参数携带格式如：{errflag: “NOT_ALLOWED_ERROR”, message: “Permission denied”}。 errflag 字段可能出现以下值： * “NOT_SUPPORT”: 浏览器不支持。 * “INVALID_ARG”: 无效的参数。 * “NOT_ALLOWED_ERROR”: 用户拒绝授予对应的摄像头或麦克风权限。 * “NOT_READABL_EERROR”: 摄像头或麦克风被占用。 * “ABORT_ERROR”: 设备中止错误。 * “NOT_FOUND_ERROR”: 没有找到设备。 * “OVER_CONSTRAINED_ERROR”: 配置的约束无法满足要求错误。 * “SECURITY_ERROR”: 安全错误, 网页使用设备媒体被禁止。这个机制是否开启或者关闭取决于单个用户的偏好设置。 * “TYPE_ERROR”: 设备约束都设置为 false 了。 * “REQ_TIMEOUT”: 请求设备超时。“UNDEFINED_ERROR”: 未定义错误。

Example:

CloudHubRTC.getDeviceManager().getAudioTrack("deviceId",{} ,function(track) {
  console.log("getAudioTrack success", track);
  }, function(errStr){
    console.error("getAudioTrack fail:", errStr);
});

setDefaultVideoProfile

setDefaultVideoProfile(profile: object): object

方法作用: 设置默认的视频属性。

名称	类型	描述
profile	object	视频属性，有以下属性： * width?:number 视频宽度，缺省为原默认视频的 width。 * height?:number 视频高度，缺省为原默认视频的 height。 * fps?:number 视频帧率，缺省为原默认视频的 fps。

Note:

开启多流模式（enableMultiStream）后，无法向上调整视频分辨率。该问题为 Chromium 已知问题。
如果不调用 setDefaultVideoProfile，则默认的视频属性为 {width: 320, height:240, fps:15}

Example:

CloudHubRTC.getDeviceManager().setDefaultVideoProfile({width: 320, height:240, fps:15});

Returns object 返回实际设置的视频属性，如：{width: 320, height:240, fps:15}。

audioEleTestPlay

audioEleTestPlay(onCallback?: function): void

方法作用: 音频节点播放测试 (主要用于检测浏览器能否允许音频元素播放 — 有些浏览器会阻止音频元素非人为点击的播放)。

名称	类型	描述
onCallback	function	播放是否成功的回调, 回调参数携 StreamPlayError * 如果播放成功该参数为 null/undefined。 * 如果播放失败可以通过 StreamPlayError 了解可能的原因。 StreamPlayError: 详情查看 “CloudHubRTC 数据对象文档的 StreamPlayError 说明” 。

Example:

CloudHubRTC.getDeviceManager().audioEleTestPlay(function(err){
  if(err){
    console.info('audio ele not allow play', err);
      var div = document.createElement('div');
      div.style = 'top:0;left: 0px;position: absolute;z-index: 8888;background: rgba(106, 120, 122, 0.17);width: 100%;height: 100%;';
      var button = document.createElement('button');
      button.style = 'position: absolute;left: 50%;top: 50%;transform: translate(-50%, -50%);padding: 15px 20px;border-radius: 15px;border: none;background: #03a9f4;font-size: 15px;color: white;font-weight: bolder;'
      button.innerHTML = '浏览器不允许音频节点自动播放，要求需要人为进行播放，请点击按钮授权播放';
      button.onclick = function(){
        document.body.removeChild(div);
        console.info('trigger allow auto btn click event');
        CloudHubRTC.getDeviceManager().audioEleTestPlay();



      }
      div.appendChild(button);
      document.body.appendChild(div);
    }else{



    }
});

getUserMedia

getUserMedia(constraints: object): Promise

方法作用: 浏览器 navigator.mediaDevices.getUserMedia 的封装，SDK 内部对 navigator.mediaDevices.getUserMedia 进行了一些浏览器适配。

名称	类型	描述
constraints	object	关于约束，请参考浏览器的 navigator.mediaDevices.getUserMedia 的约束条件。 * 可以参考浏览器 getUserMedia 接口错误类型。 * 可以参考 “常量声明以及补充说明” 的浏览器 getUserMedia 接口失败的错误类型。

Note: 该方法一般用于浏览器音频自动播放被限制时获取权限使用。

Example:

CloudHubRTC.getDeviceManager().getUserMedia({video:true, audio:true})
    .then(function(mediaStream){
      console.log("getUserMedia  success");
    })
    .catch(function(err){
      console.error("getUserMedia err:", err);
    })