CloudHub JSSDK
- Overview
- CloudHubRTC
- CloudHubRTCObject
- Client
- ClientEvent
- ClientLiveTranscoding
- ClientChannelMediaRelayConfig
- Stream
- StreamEvent
- DeviceManager
- Constants
Description and interface of DeviceManager
- DeviceManager interface provides methods for operations on devices, such as enumerating devices, device detection, and so on.
- You can use the getDeviceManager get DeviceManager object.
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.
name | type | description |
---|---|---|
onCallback | function | successful 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.
name | type | description |
---|---|---|
onCallback | function | successful 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.
name | type | description |
---|---|---|
deviceId | string | The device ID to be detected, the device ID is obtained by the getDevices method |
options | object | Configuration 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. |
onSuccess | function | Successful callback, the callback parameter carries the node ID of the playback node. |
onFailure | function | Failed 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:
- If there is a microphone being detected, call startMicrophoneTest will automatically stop the detection operation in progress, but to stop the microphone detection, you must call stopMicrophoneTest method.
- Generally, when playing audio/video with sound, the browser will require the behavior to be triggered by gestures, see “Processing a browser automatic playback policy”。
- The mobile browser is not supported.
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。
name | type | description |
---|---|---|
deviceId | string | device ID。 |
Example:
CloudHubRTC.getDeviceManager().setDefaultMicrophoneId("deviceid");
getDefaultMicrophoneId
getDefaultMicrophoneId(): string
What it does: Get the default microphone id。
Note:
- If it is “”, it means that the default device has not been set
- When the local stream type is video(which is: stream.getType() === “video”) for initialization, if the default device has not been set and the device id that should be used by the local stream is not specified, the SDK will automatically set the default device id.
- The mobile does not support setting the microphone/speaker, and it makes no sense to get the default device ID
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.
name | type | description |
---|---|---|
onCallback | function | successful 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.
name | type | description |
---|---|---|
deviceId | string | To detect the device ID, device ID is obtained by the getDevices method |
elementId | string | Node element ID. This node element is used to hold the video window corresponding to the camera. It should be a div node. |
options | object | Configuration 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。 |
onSuccess | function | Successful callback. |
onFailure | function | Failed 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:
- If a camera is currently being detected, calling startCameraTest will automatically stop the detection operation in progress, but to stop camera detection, you must call the stopCameraTest method.
- Mobile browsers do not support it.
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.
name | type | description |
---|---|---|
deviceId | string | The 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。
name | type | description |
---|---|---|
deviceId | string | device ID。 |
Example:
CloudHubRTC.getDeviceManager().setDefaultCameraId("deviceid");
getDefaultCameraId
getDefaultCameraId(): string
What it does: Get the default camera id.
Note:
- If it is “”, it means that the default device has not been set
- When the local stream type is video (that is, stream.getType () = “video”), SDK automatically sets the default device id if the default device is not set and the device id, that the local stream should use is not specified.
- Mobile phone camera device id, frontCameraDeviceId Indicates the front camera, backCameraDeviceId For the rear camera.
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:
- If it is “”, it means that the default device has not been set
- When the local stream type is video (that is, stream.getType () = “video”), SDK automatically sets the default device id if the default device is not set and the device id, that the local stream should use is not specified.
- The microphone / speaker is not supported on the mobile side, and it doesn’t make any sense to get the default device id.
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.
name | type | description |
---|---|---|
onCallback | function | successful 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.
name | type | description |
---|---|---|
deviceId | string | To detect the device ID, device ID is obtained by the getDevices method |
audiourl | string | The absolute address of the sound file, it is recommended to use a file in wav format. |
options | object | Configuration 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。 |
onSuccess | function | Successful callback |
onFailure | function | Failed 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:
- If a speaker is currently being detected, calling startSpeakerTest will automatically stop the detection operation in progress, but to stop microphone detection, you must call the stopSpeakerTest method.
- Generally, when playing audio/video with sound, the browser will require the behavior to be triggered by gestures, see “Deal with the automatic playback strategy of the browser”。
- Mobile browsers do not support it.
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.
name | type | description |
---|---|---|
onListener | function | null | This 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。
name | type | description |
---|---|---|
deviceId | string | device 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.
name | type | description |
---|---|---|
deviceId | string | The speaker device ID. |
elementArr | array | The 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. |
onCallback | function | Callback 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
- false: Not supported.
- true: Support.
Audio and video
getVideoTrack
getVideoTrack(deviceId: string, options?:object, onSuccess?:function, onFailure?: function): void
What it does: Get video tracks.
name | type | description |
---|---|---|
deviceId | string | Device ID. |
options | object | Configuration 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. |
onSuccess | function | Successful callback |
onFailure | function | Failed 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.
name | type | description |
---|---|---|
deviceId | string | Device ID. |
options | object | Configuration item. |
onSuccess | function | Successful callback |
onFailure | function | Failed 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.
name | type | description |
---|---|---|
profile | object | Video 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:
- When multi-stream mode (enableMultiStream) is enabled, the video resolution cannot be adjusted upward. The issue is known to Chromium.
- If setDefaultVideoProfile is not called, the default video attribute is {width: 320, height:240, fps:15}.
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).
name | type | description |
---|---|---|
onCallback | function | Callback 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.
name | type | description |
---|---|---|
constraints | object | For 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);
})