CloudHub Docs
Download Documents

RTC


CloudHub JSSDK

Description and interface of DeviceManager

Base

getDevices

getDevices(onCallback: function): void

What it does: enumerate available media input/output devices, such as microphones, cameras, speakers, etc.

After a successful call, SDK returns the available media devices through the MediaDeviceInfo object.

nametypedescription
onCallbackfunctionsuccessful callback. The callback parameter carries a MediaDeviceInfo object. MediaDeviceInfo: See MediaDeviceInfo description of the CloudHubRTC data object document

Example:

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

Microphone

getMicrophones

getMicrophones(onCallback: function): void

What it does: Enumerate the audio input device.

This method enumerates the available audio input devices, such as microphones.

After a successful call, SDK returns the available audio input device through the MediaDeviceInfo object.

nametypedescription
onCallbackfunctionsuccessful callback. The callback parameter carries a MediaDeviceInfo object. MediaDeviceInfo: See MediaDeviceInfo description of the CloudHubRTC data object document

startMicrophoneTest

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

What it does: Start microphone device detection.

nametypedescription
deviceIdstringThe device ID to be detected, the device ID is obtained by the getDevices method
optionsobjectConfiguration item, contains the properties as follows:
* isplay?: boolean Whether to create audio node elements for playback. Default is true。
* onRealVolume?: function Real-time volume callback, default is null/undefined。
* volume?: number When isplay is true, set the volume to be played. The range is [0,100]. The default is 100.
onSuccessfunctionSuccessful callback, the callback parameter carries the node ID of the playback node.
onFailurefunctionFailed callback. Failed parameters carry formats such as: {errflag: “NOT_ALLOWED_ERROR”, message: “Permission denied”}。
errflag The following values may occur:
* “NOT_SUPPORT”: The browser is not supported.
* “INVALID_ARG”: Invalid parameter.
* “NOT_ALLOWED_ERROR”: The user refuses to grant the corresponding microphone permissions.
* “NOT_READABL_EERROR”: The microphone is occupied.
* “ABORT_ERROR”: Device abort error.
* “NOT_FOUND_ERROR”: Did not find the device.
* “OVER_CONSTRAINED_ERROR”: The configured constraint cannot meet the requirements.
* “SECURITY_ERROR”: Security error, webpage use of device media is prohibited. Whether this mechanism is turned on or off depends on the preferences of individual users.
* “TYPE_ERROR”: Device constraints are set to false
* “REQ_TIMEOUT”: Request timeout.
* “UNDEFINED_ERROR”: Undefined error.
* “MEDIA_ELE_PLAY_ERROR”: Play error [Note:message values is StreamPlayError. StreamPlayError: See “StreamPlayError description of CloudHubRTC data object document”]。
Note:
1. Refer Browser getUserMedia Interface error type
2. See “Constant declaration and supplementary notes” The error type of the browser’s getUserMedia interface failure.

Note:

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

What it does: Stop microphone device detection.

Example:

CloudHubRTC.getDeviceManager().stopMicrophoneTest();

setDefaultMicrophoneId

setDefaultMicrophoneId(deviceId:string): void

What it does: Set the default microphone id。

nametypedescription
deviceIdstringdevice ID。

Example:

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

getDefaultMicrophoneId

getDefaultMicrophoneId(): string

What it does: Get the default microphone id。

Note:

Example:

CloudHubRTC.getDeviceManager().getDefaultMicrophoneId();

Returns string

Return the default device id, if it is “”, it means that the default device has not been set.

Camera

getCameras

getCameras(onCallback: function): void

What it does: Enumerate video input devices.

This method enumerates the available video input devices, such as cameras.

After a successful call, SDK returns the available video input devices through the MediaDeviceInfo object.

nametypedescription
onCallbackfunctionsuccessful callback. The callback parameter carries a MediaDeviceInfo object. MediaDeviceInfo: See MediaDeviceInfo description of the CloudHubRTC data object document

startCameraTest

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

What it does: Start camera check.

nametypedescription
deviceIdstringTo detect the device ID, device ID is obtained by the getDevices method
elementIdstringNode element ID. This node element is used to hold the video window corresponding to the camera. It should be a div node.
optionsobjectConfiguration items, including the following attributes:
1. fit?: “cover” | “contain”: Set the display mode for video playback, including “cover” and “contain” can choose. Default is “cover”,The differences between cover mode and contain mode are as follows:
* Cover mode: priority is given to ensuring that the window is filled. The video size is scaled proportionally until the entire window is filled with video. If the length and width of the video is different from that of the display window, the video stream will be clipped according to the proportion of the display window or the image will be stretched to fill the window. You can refer to the cover option of object-fit in the CSS attribute.
* Contain mode: priority is given to ensuring that all video content is displayed. The video size is scaled proportionally until one side of the video window is aligned with the window frame. If the video size is not consistent with the display window size, on the premise of maintaining the aspect ratio, the video is scaled and filled with the window. There will be a black edge around the scaled video. You can refer to the contain option of object-fit in the CSS attribute.
2. mirror?: boolean Used to indicate whether the video is displayed in a mirror way, default is false。
3. loader?: boolean Used to indicate whether the “loading” style is displayed when the video data is not loaded, default is true。
onSuccessfunctionSuccessful callback.
onFailurefunctionFailed callback. Failed parameters carry formats such as: {errflag: “NOT_ALLOWED_ERROR”, message: “Permission denied”}。
errflag The following values may occur:
* “NOT_SUPPORT”: The browser does not support it.
* “INVALID_ARG”: Invalid parameter.
* “NOT_ALLOWED_ERROR”: The user refuses to grant the corresponding camera permissions.
* “NOT_READABL_EERROR”: The camera is occupied.
* “ABORT_ERROR”: Device abort error.
* “NOT_FOUND_ERROR”: Did not find the device.
* “OVER_CONSTRAINED_ERROR”: The configured constraint cannot meet the requirement error.
* “SECURITY_ERROR”: Security error, web page use of device media is prohibited. Whether this mechanism is turned on or off depends on the preferences of individual users.
* “TYPE_ERROR”: Device constraints are set to false
* “REQ_TIMEOUT”: Request timeout.
* “UNDEFINED_ERROR”: Undefined error.
* “MEDIA_ELE_PLAY_ERROR”: Play error [Note:message values is StreamPlayError. StreamPlayError: See “StreamPlayError description of CloudHubRTC data object document”]。
Note:
1. Refer Browser getUserMedia Interface error type.
2. See “Constant declaration and supplementary notes” The error type of the browser’s getUserMedia interface failure.

Note:

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

What it does: Stop the camera detection.

nametypedescription
deviceIdstringThe device ID to stop detection.
Note: If deviceId is null/undefined, all camera detection will be stopped.

Example:

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

setDefaultCameraId

setDefaultCameraId(deviceId:string): void

What it does: Set the default camera id。

nametypedescription
deviceIdstringdevice ID。

Example:

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

getDefaultCameraId

getDefaultCameraId(): string

What it does: Get the default camera id.

Note:

Example:

CloudHubRTC.getDeviceManager().getDefaultCameraId();

Returns string

Returns the default device id,. If it is “”, it means that the default device has not been set.

Speaker

getDefaultSpeakerId

getDefaultSpeakerId(): string

What it does: Get the default speaker id。

Note:

Example:

CloudHubRTC.getDeviceManager().getDefaultSpeakerId();

Returns string

Returns the default device id,. If it is “”, it means that the default device has not been set.

getSpeakers

getSpeakers(onCallback: function): void

What it does: Enumerates audio output devices.

This method enumerates the available audio output devices, such as speakers.

After a successful call, SDK returns the available audio output device through the MediaDeviceInfo object.

nametypedescription
onCallbackfunctionsuccessful callback. The callback parameter carries a MediaDeviceInfo object. MediaDeviceInfo: See MediaDeviceInfo description of the CloudHubRTC data object document

Note: Only Chrome 49 and above are supported.

startSpeakerTest

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

What it does: Start speaker device detection.

nametypedescription
deviceIdstringTo detect the device ID, device ID is obtained by the getDevices method
audiourlstringThe absolute address of the sound file, it is recommended to use a file in wav format.
optionsobjectConfiguration items, including the following attributes:
1、 loop?: boolean Whether to loop the test audio file. Default is true。
2、 volume?: number Sets the volume of playback. The range of values is [0,100], Default is 100。
onSuccessfunctionSuccessful callback
onFailurefunctionFailed callback. Failed parameters carry formats such as: {errflag: “NOT_SUPPORT”, message: “browser not support set speaker”}。
errflag The following values may appear in the field:
* “NOT_SUPPORT”: The browser does not support it.
* “INVALID_ARG”: Invalid parameters.
* “MEDIA_ELE_PLAY_ERROR”: Play error [Note:message values is StreamPlayError. StreamPlayError: See “StreamPlayError description of CloudHubRTC data object document”]。
* “UNDEFINED_ERROR”: Undefined error.

Note:

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

What it does: Stop speaker device detection.

Example:

CloudHubRTC.getDeviceManager().stopSpeakerTest();

registerDeviceChangeListener

registerDeviceChangeListener(onListener: function | null): void

What it does: Register / remove device listeners.

It is mainly used to add/remove listening devices.

nametypedescription
onListenerfunction | nullThis function will be called back when the device changes, and the parameters carried by the callback: type and changedevices,When onListener is null/undefined, the device listener is removed. type value is:“device_add” and “device_remove”。
changedevices: type is object,json format is as follows:
* {[kind]:[MediaDeviceInfo]}eg: {videoinput:[{kind:“videoinput”,label:“label”,deviceId:“deviceid”}]}。
* See: “MediaDeviceInfo description of the CloudHubRTC data object document”

Note: After testing, the behavior of very few devices is abnormal, and the callback function will be triggered continuously when the operation of plugging and unplugging the device does not occur.

Example Register device listener:

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

Example Remove device listener:

CloudHubRTC.getDeviceManager().registerDeviceChangeListener(null);

setDefaultSpeakerId

setDefaultSpeakerId(deviceId:string): void

What it does: Set the default speaker id。

nametypedescription
deviceIdstringdevice ID。

Example:

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

associateElementsToSpeaker

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

What it does: Associate the media element node (video/audio) to the speakers.

nametypedescription
deviceIdstringThe speaker device ID.
elementArrarrayThe node element array to be associated.
Note: If you send null/undefined, it means that all audio/video of the interface will be set to the speaker ID.
onCallbackfunctionCallback function. The parameter carries err,. If err is successful, undefined means the setting is successful, otherwise it means the setting failed.

Note: Mobile browsers do not support it.

Example:

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

Desktop sharing

checkScreenIsSupport

checkScreenIsSupport(): boolean

What it does: Detect whether screen / program sharing is supported.

Example:

CloudHubRTC.getDeviceManager().checkScreenIsSupport();

Returns boolean

Audio and video

getVideoTrack

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

What it does: Get video tracks.

nametypedescription
deviceIdstringDevice ID.
optionsobjectConfiguration items, which are configured as follows:
* width?:number Video width, the default is the default video width.
* height?:number Video height, the default is the default video height.
* fps?:number Video frame rate. Default is the default video frame rate.
onSuccessfunctionSuccessful callback
onFailurefunctionFailed callback. Failed parameters carry formats such as: {errflag: “NOT_ALLOWED_ERROR”, message: “Permission denied”}。
errflag The following values may appear in the field:
* “NOT_SUPPORT”: The browser does not support it.
* “INVALID_ARG”: Invalid parameters.
* “NOT_ALLOWED_ERROR”: The user refuses to grant the corresponding camera or microphone permission.
* “NOT_READABL_EERROR”: The camera or microphone is occupied.
* “ABORT_ERROR”: The device has aborted the error.
* “NOT_FOUND_ERROR”: Did not find the device.
* “OVER_CONSTRAINED_ERROR”: The configured constraint cannot meet the requirements.
* “SECURITY_ERROR”: Security error, webpage use of device media is prohibited. Whether this mechanism is turned on or off depends on the preferences of individual users.
* “TYPE_ERROR”: Device constraints are set to false
* “REQ_TIMEOUT”: Request timeout.
* “UNDEFINED_ERROR”: 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

What it does: Get an audio track.

nametypedescription
deviceIdstringDevice ID.
optionsobjectConfiguration item.
onSuccessfunctionSuccessful callback
onFailurefunctionFailed callback. Failed parameters carry formats such as: {errflag: “NOT_ALLOWED_ERROR”, message: “Permission denied”}。
errflag The following values may appear in the field:
* “NOT_SUPPORT”: The browser is not supported.
* “INVALID_ARG”: Invalid parameters.
* “NOT_ALLOWED_ERROR”: The user refuses to grant the corresponding camera or microphone permission.
* “NOT_READABL_EERROR”: The camera or microphone is occupied.
* “ABORT_ERROR”: The device has aborted the error.
* “NOT_FOUND_ERROR”: Did not find the device.
* “OVER_CONSTRAINED_ERROR”: The configured constraint cannot meet the requirements.
* “SECURITY_ERROR”: Security error, webpage use of device media is prohibited. Whether this mechanism is turned on or off depends on the preferences of individual users.
* “TYPE_ERROR”: Device constraints are set to false
* “REQ_TIMEOUT”: Request timeout.
* “UNDEFINED_ERROR”: 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

What it does: Set the default video properties.

nametypedescription
profileobjectVideo attributes, with the following attributes:
* width?:number Video width, the default is the default video width。
* height?:number Video height, the default is the default video height.
* fps?:number Video frame rate. Default is the default video frame rate.

Note:

Example:

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

Returns object Returns the video properties actually set, such as {width: 320, height:240, fps:15}.

audioEleTestPlay

audioEleTestPlay(onCallback?: function): void

What it does: Audio node playback test (mainly used to test whether browsers can allow audio elements to play-some browsers will block the playback of audio elements that are not artificially clicked).

nametypedescription
onCallbackfunctionCallback whether the playback is successful or not, Callback parameter carrying StreamPlayError
* If the playback is successful, this parameter is null/undefined.
* 如If the playback fails, you can find out the possible reasons through StreamPlayError.
StreamPlayError: See “StreamPlayError description of CloudHubRTC data object document”.

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 = 'The browser does not allow the audio node to play automatically. It needs to be played artificially. Please click the button to authorize the playback.';
      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);
    }
});

getUserMedia

getUserMedia(constraints: object): Promise

What it does: Browser navigator.mediaDevices.getUserMedia Package, Some browser navigator.mediaDevices.getUserMedia adaptations have been made to the SDK internally.

nametypedescription
constraintsobjectFor constraints, please refer to the browser navigator.mediaDevices.getUserMedia The constraints.
* See Browser getUserMedia interface error type
* See “Constant declaration and supplementary notes” The error type of the browser’s getUserMedia interface failure.

Note: This method is typically used to obtain permission when browser audio automatic playback is limited.

Example:

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