DeviceManager

The DeviceManager module in ZDK is dedicated to managing a device’s microphones and cameras. It provides users with the capability to switch among available cameras or microphones as needed. This module furnishes developers with straightforward access to these feeds, allowing them to integrate and present them as desired in their applications. If any permission-related issues arise, the module produces clear error messages, ensuring that developers can relay user-friendly notifications to end-users, guiding them to address any access concerns.

• core

Initialization

const devicesManager = new createDevicesManager({
      config: {
        constraints: {
          video: {
            width: 720,
            height: 480,
            frameRate: 32
          },
          audio: {
            noiseSuppression: true,
            echoCancellation: true,
            autoGainControl: true
          }
        }
      }
});

In the ZDK system, setting appropriate constraints is crucial for optimizing the user experience with client services. These constraints, particularly regarding video and audio quality, ensure a balance between performance and clarity. Adapting to various device capabilities and network conditions, the right constraints provide efficient and high-quality media streaming, tailored to each user’s unique viewing environment.

For an optimal experience, we suggest selecting a constraint set from our list that best aligns with your needs. Each option is tailored to different usage scenarios, ensuring you get the most out of our services.

• high resolution:

const highResolutionConstraints = {
    video: {
        width: { min: 1024, ideal: 1920, max: 1920 },
        height: { min: 576, ideal: 1080, max: 1080 },
        frameRate: { min: 24, ideal: 30, max: 60 }
    },
    audio: {
        echoCancellation: true,
        noiseSuppression: true,
        autoGainControl: true
    }
}

• medium resolution:

const mediumResolutionConstraints = {
    video: {
        width: { min: 640, ideal: 1280, max: 1280 },
        height: { min: 360, ideal: 720, max: 720 },
        frameRate: { min: 24, ideal: 30, max: 30 }
    },
    audio: {
        echoCancellation: true,
        noiseSuppression: true,
        autoGainControl: true
    }
}

• low resolution:

const lowResolutionConstraints = {
    video: {
        width: { min: 320, ideal: 640, max: 800 },
        height: { min: 240, ideal: 480, max: 600 },
        frameRate: { min: 15, ideal: 24, max: 30 }
    },
    audio: {
        echoCancellation: true,
        noiseSuppression: true,
        autoGainControl: true
    }
};

If you encounter any issues with obtaining the selected resolution from your chosen device, our system will automatically switch to the low-resolution option from the above list, ensuring continued, smooth service.

Actions

turnOnCam

() => Promise<void>

Activates the selected camera and assigns the media stream to data.camStream. The existence of camStream implies that the status of this camera stream can be read using the variable data.camStreamStatus. Return value

Returns a promise that resolves once the camera is turned on and the stream is established.

• ActionCallError - Permission denied.
• ActionCallError - Permission dismissed.

turnOffCam

() => void

Turns off the currently active camera and clears the associated media stream.

setCam

(deviceId: string) => Promise<void>

Changes the currently selected camera to the one specified by deviceId. If the camera is currently active, the stream is reinitialized to reflect the new camera’s view.

Returns a promise that resolves when the camera has been successfully changed and the stream is refreshed.

• ActionCallError - Selected camera doesn’t exist.
• ActionCallError - Permission denied.
• ActionCallError - Permission dismissed.

setResolution

(constraints: MediaTrackConstraints) => Promise<void>

Adjusts the resolution of the current media stream according to the specified MediaTrackConstraints.

Returns a promise that resolves once the resolution change is successfully applied.

• ActionCallError - Permission denied.
• ActionCallError - Permission dismissed.

turnOnMic

() => Promise<void>

Activates the selected microphone and assigns the media stream to data.micStream. The existence of micStream implies that the status of this microphone stream can be read using the variable data.micStreamStatus.

Returns a promise that resolves once the microphone is turned on and the stream is established.

• ActionCallError - Permission denied.
• ActionCallError - Permission dismissed.

turnOffMic

() => void

Deactivates the currently active microphone and clears the associated media stream.

setMic

(deviceId: string) => Promise<void>

Switches to the specified microphone by deviceId. If the microphone is in use, the stream is updated to capture audio from the new device.

Returns a promise that resolves once the microphone has been changed and the stream is updated.

• ActionCallError - Selected microphone doesn’t exist.
• ActionCallError - Permission denied.
• ActionCallError - Permission dismissed.

enableMicLevelInput

() => Promise<void>

Function enables the microphone input level measurement, allowing the application to monitor and process the audio signal strength in real-time. This function ensures that microphone activity can be tracked, which is useful for features such as volume visualization, voice detection, or automatic gain control. Microphone level input is monitored using requestAnimationFrame.

Returns a promise that resolves once the can be monitored.

• ActionCallError - No audio stream available.
• ActionCallError - Audio stream is not active.
• ActionCallError - MicLevel is already monitored.

disableMicLevelInput

() => Promise<void>

Function disables the microphone input level measurement, stopping the monitoring and processing of the audio signal strength. This function is used to conserve resources when microphone level tracking is no longer needed.

Returns a promise that resolves once the can be monitored.

• ActionCallError - No audio stream available.
• ActionCallError - Audio stream is not active.
• ActionCallError - MicLevel is already monitored.

turnOnScreenShare

(displaySurface?: DisplayCaptureSurfaceType, audio?: boolean | MediaTrackConstraints) => Promise<void>

Function starts screen sharing with a specified display type (displaySurface) and optional audio capture (audio). It requests access to a screen, window, or browser tab, and if the user selects a different display surface than requested, an error is thrown. The behavior of screen and audio capture depends on the browser and operating system, as some platforms may not support audio capture or may impose restrictions on certain display surfaces.

Returns a promise that resolves when proper screen is shared.

• ActionCallError - Wrong display surface.
• ActionCallError - Streaming is not supported.

turnOffScreenShare

() => void

turnOffScreenShare is a synchronous function that stops the active screen-sharing session by disabling the associated media stream. It ensures that all video and audio tracks from the screen capture are properly stopped and releases system resources immediately.

Void

Data (Getters)

availableCams

Getter output type: { label: string, value: string }[]

Provides a list of available cameras, each with a label and a value representing the device’s identifier. This list is populated only after the client grants the browser permission to use the camera. Permissions requirements vary by browser—Chromium-based browsers generally require a one-time authorization for a specific page/URL, while Safari may require permission each time the page is accessed. Without the necessary permissions or in the absence of camera devices, the returned array will be empty, reflecting that the user cannot select a camera until permissions are granted.

availableMics

Getter output type: { label: string, value: string }[]

This getter provides an array of available microphones, where each microphone is represented by an object containing a label for display purposes and a value corresponding to the device’s unique identifier. Access to this list is contingent upon the client granting the browser permission to use the microphone. Permission prompts and behavior may vary by browser: for instance, Chromium-based browsers typically request permission once per page/URL, whereas Safari may prompt every time the page is accessed. Until such permissions are given, this list remains empty, which means users will not be able to select a microphone. If no microphones are available or permissions are not granted, the array will also be empty.

camStatus

Getter output type: 'unavailable' | 'init' | 'prompt' | 'ready' | 'denied' | 'dismissed' | 'deniedBySystem'

The camStatus getter provides a status string that describes the current state of the camera device. Below is a breakdown of what each status represents:

'unavailable'
The camera is not available on the device.
Possible causes:

• No camera is physically connected or detected.
• The browser does not support camera access.
• The camera is in use by another application, making it unavailable.
  

'init'
The camera is in the process of being initialized. This state occurs before any permissions are requested or before the device is fully detected.

'prompt'
The system is asking the user for permission to access the camera. This occurs when the application requests camera access, and the user has not yet granted or denied permission. The user sees a browser/system permission dialog at this stage.

'ready'
The camera is available, and permission has been granted. The application can now access the camera and retrieve a media stream. This is the ideal state for using the camera in the application.

'denied'
The user has explicitly denied camera access. This can happen when the user selects “Block” in the browser’s permission prompt. The application cannot access the camera unless the user manually updates their permissions.

'dismissed'
The user closed the permission prompt without making a decision. Some browsers consider this different from ‘denied’, as the user did not explicitly reject access. The application can retry requesting access.

'deniedBySystem'
The operating system or browser has blocked camera access at a system level.
Possible causes:

• Camera access is disabled in system settings or privacy controls.
• A policy (e.g., enterprise security settings) is preventing access.
• The camera is restricted due to security concerns.
  

Unlike ‘denied’, this is not something the user can typically change through the browser alone. Each of these statuses helps determine how the application should handle camera access and inform the user about what actions may be needed.

camStream

Getter output type: MediaStream | undefined

Retrieves the MediaStream from the currently selected camera. This stream can be utilized to present a preview of the camera’s view to the client, such as showing what the camera sees before the client enters a video chat room. If no camera has been selected or the stream is not available, the getter will return undefined.

camStreamStatus

Getter output type: undefined | 'active' | 'muted' | 'ended'

Describes status of current camStream.

micStatus

Getter output type: 'unavailable' | 'init' | 'prompt' | 'ready' | 'denied' | 'dismissed' | 'deniedBySystem'

Description The micStatus getter provides a status string that describes the current state of the microphone device. Below is a breakdown of what each status represents:

'unavailable'
The microphone is not available on the device.
Possible causes:

• No microphone is physically connected or detected.
• The browser does not support microphone access.
• The microphone is in use by another application, making it unavailable.

'init'
The microphone is in the process of being initialized. This state occurs before any permissions are requested or before the device is fully detected.

'prompt'
The system is asking the user for permission to access the microphone. This occurs when the application requests microphone access, and the user has not yet granted or denied permission. The user sees a browser/system permission dialog at this stage.

'ready'
The microphone is available, and permission has been granted. The application can now access the microphone and retrieve an audio stream. This is the ideal state for using the microphone in the application.

'denied'
The user has explicitly denied microphone access. This can happen when the user selects “Block” in the browser’s permission prompt. The application cannot access the microphone unless the user manually updates their permissions.

'dismissed'
The user closed the permission prompt without making a decision. Some browsers consider this different from ‘denied’, as the user did not explicitly reject access. The application can retry requesting access.

'deniedBySystem'
The operating system or browser has blocked microphone access at a system level. Possible causes:

• Microphone access is disabled in system settings or privacy controls.
• A policy (e.g., enterprise security settings) is preventing access.
• The microphone is restricted due to security concerns.

Unlike ‘denied’, this is not something the user can typically change through the browser alone. Each of these statuses helps determine how the application should handle microphone access and inform the user about what actions may be needed.

micStream

Getter output type: MediaStream | undefined

Provides the MediaStream from the currently selected microphone. This can be used, for instance, to test the microphone’s output and ensure it’s functioning correctly before the client enters a room. If no microphone has been selected or if a stream is not currently active, the getter will return undefined.

micStreamStatus

Getter output type: undefined | 'active' | 'muted' | 'ended'

Describes status of current micStream.

screenShareStatus

Getter output type: ‘unavailable’ | ‘init’ | ‘prompt’ | ‘active’ | ‘denied’ | ‘dismissed’ | ‘deniedBySystem’

Description The screenShareStatus getter provides a status string that describes the current state of the screen-sharing session. Below is a breakdown of what each status represents:

'unavailable'
Screen sharing is not available on the device or browser.

Possible causes:

• The browser does not support getDisplayMedia.
• Screen sharing is blocked by system policies.
• The feature is disabled due to security settings.

'init'
The screen-sharing process is initializing. This state occurs before any permissions are requested or before the system detects available display sources.

'prompt'
The system is asking the user for permission to start screen sharing. This occurs when the application requests screen capture, and the user has not yet granted or denied access. The user sees a browser/system permission dialog at this stage.

'ready'
The screen is currently being shared, and the application has access to the screen capture stream. This is the ideal state for using screen-sharing features in the application.

'denied'
The user has explicitly denied screen-sharing access. This can happen when the user selects “Block” in the browser’s permission prompt. The application cannot access screen sharing unless the user manually updates their permissions.

'dismissed'
The user closed the permission prompt without making a decision or picked wrong display surface. The application can retry requesting screen-sharing permissions.

'deniedBySystem'
The operating system or browser has blocked screen-sharing access at a system level.

Possible causes:

• Screen sharing is disabled in system settings or privacy controls.
• A policy (e.g., enterprise security settings) is preventing access.
• Screen sharing is restricted due to security concerns.

Unlike ‘denied’, this is not something the user can typically change through the browser alone.

screenShareStream

Getter output type: MediaStream | undefined

Provides the MediaStream from the currently selected screen.

screenShareStreamStatus

Getter output type: undefined | 'active' | 'muted' | 'ended'

Describes status of current screenShareStream.

screenShareAudioStatus

Getter output type: ‘unavailable’ | ‘init’ | ‘prompt’ | ‘ready’ | ‘denied’ | ‘dismissed’ | ‘deniedBySystem’

Description The screenShareAudioStatus getter provides a status string that describes the current state of the audio part of screen-sharing session. Below is a breakdown of what each status represents:

'unavailable'
Screen sharing is not available on the device or browser.

Possible causes:

• The browser does not support getDisplayMedia.
• Screen sharing is blocked by system policies.
• The feature is disabled due to security settings.

'init'
The screen-sharing process is initializing. This state occurs before any permissions are requested or before the system detects available display sources.

'prompt'
The system is asking the user for permission to start screen sharing. This occurs when the application requests screen capture, and the user has not yet granted or denied access. The user sees a browser/system permission dialog at this stage.

'ready'
The screen is currently being shared, and the application has access to the screen capture stream and stream contains audio tracks. This is the ideal state for using screen-sharing audio features in the application.

'denied'
The user has explicitly denied screen-sharing access. This can happen when the user selects “Block” in the browser’s permission prompt. The application cannot access screen sharing unless the user manually updates their permissions.

'dismissed'
User didn’t allow to share audio or system prevents from doing it.

'deniedBySystem'
The operating system or browser has blocked screen-sharing access at a system level.

Possible causes:

• Screen sharing is disabled in system settings or privacy controls.
• A policy (e.g., enterprise security settings) is preventing access.
• Screen sharing is restricted due to security concerns.

Unlike ‘denied’, this is not something the user can typically change through the browser alone.

screenShareAudioStream

Getter output type: MediaStream | undefined

Provides the MediaStream from the currently selected screen.

screenShareAudioStreamStatus

Getter output type: undefined | 'active' | 'muted' | 'ended'

Describes status of current screenShareAudioStream.

Events

The module provides the following ListenerCreator:

onDeviceChange

{ev: Event}

The method sets up a function that will be called whenever a list of available devices is changing. Updated list is immediately applied to availableCams or/and availableMics.