Resource Base
Table of contents

Class CameraEnhancer

Basic Camera Control

API Name Description
static testCameraAccess() Tests whether there is an available camera.
getAllCameras() Returns information of all available cameras on the device.
selectCamera() Chooses a camera as the video source.
getSelectedCamera() Returns information about the selected / current camera.
getCameraState() Returns the state of the selected camera which could be “opening”, “open” or “closed”
open() Turns on the camera to start streaming live video.
cameraOpenTimeout Sets or returns the maximum time allowed for opending a selected camera.
close() Stops video streaming and releases the camera.
isOpen() Returns whether the selected camera is turned on / occupied.
pause() Pauses video streaming without releasing the camera.
isPaused() Returns whether the video streaming is paused.
resume() Resumes video streaming.
getVideoSettings() Returns the current video settings.
updateVideoSettings() Changes the video input.
setResolution() Sets the resolution of the selected camera.
getResolution() Returns the resolution of the selected camera.
getAvailableResolutions() Returns the resolutions supported by the selected camera.
ifSaveLastUsedCamera Returns or sets whether to save the last used camera and resolution.
videoSrc Sets or returns the source of the video.
ifSkipCameraInspection Whether to opt for an optimal rear camera at the first open().

Advanced Camera Control

API Name Description
setFrameRate() Adjusts the frame rate.
getFrameRate() Returns the real-time frame rate.
turnOnTorch() Turns on the torch/flashlight if the current camera supports it.
turnOffTorch() Turns off the torch/flashlight.
getZoomSettings() Returns the zoom settings.
setZoom() Zooms the video stream.
resetZoom() Resets the zoom level of the video.
getFocusSettings() Returns the focus settings.
setFocus() Sets how the camera focuses.
getCapabilities() Inspects and returns the capabilities of the selected camera.
getCameraSettings() Returns the current values for each constrainable property of the selected camera.
getColorTemperature() Returns the color temperature of the selected camera.
setColorTemperature() Adjusts the color temperature of the selected camera.
getExposureCompensation() Returns the exposure compensation index of the selected camera.
setExposureCompensation() Sets the exposure compensation index of the selected camera.
setAutoZoomRange() Sets the range (minimum to maximum) for zoom when it is done automatically.
getAutoZoomRange() Returns the auto zoom range.
enableEnhancedFeatures() Enables the specified enhanced features.
disableEnhancedFeatures() Disables the specified enhanced features.

getAllCameras

Returns information of all available cameras on the device.

getAllCameras(): Promise<VideoDeviceInfo[]>;

Parameters

None.

Return value

A promise resolving to an array of VideoDeviceInfo objects.

Code Snippet

let cameras = await cameraEnhancer.getAllCameras();
if (cameras.length) {
    await cameraEnhancer.selectCamera(cameras[0]);
}

See also

selectCamera

Chooses a camera as the video source.

If called before open() or show() , the selected camera will be used. Otherwise, the system will decide which one to use.

selectCamera(cameraObjectOrDeviceID: VideoDeviceInfo | string): Promise<PlayCallbackInfo>;

Parameters

cameraObjectOrDeviceID : specifies the camera.

Return value

A promise resolving to a PlayCallbackInfo object.

Code Snippet

let cameras = await cameraEnhancer.getAllCameras();
if (cameras.length) {
    await cameraEnhancer.selectCamera(cameras[0]);
}

See also

getSelectedCamera

Returns information about the selected / current camera.

getSelectedCamera(): VideoDeviceInfo;

Parameters

None.

Return value

A VideoDeviceInfo object with details about the selected camera.

Code Snippet

let camera = cameraEnhancer.getSelectedCamera();
console.log(camera.label);

See also

getCameraState

Returns the state of the selected camera which could be “opening”, “open” or “closed”.

getCameraState(): string;

Parameters

None.

Return value

A string indicating the camera state, it is either “opening”, “open” or “closed”.

Code Snippet

let state = cameraEnhancer.getCameraState();
console.log("The camera is " + state);

open

Turns on the camera to start streaming live video.

open(): Promise<PlayCallbackInfo>;

Parameters

None.

Return value

A promise resolving to a PlayCallbackInfo object.

Code Snippet

<div id="enhancerUIContainer" style="width:1280px;height:720px;">
let view = await Dynamsoft.DCE.CameraView.createInstance();
document.getElementById("enhancerUIContainer").append(view.getUIElement());
let cameraEnhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance(view);
await cameraEnhancer.open();

See also

cameraOpenTimeout

Sets or returns the maximum time allowed for opending a selected camera. The default value is 4000 ms.

Setting 0 means canceling the timeout or waiting indefinitely.

cameraOpenTimeout: number;

Code Snippet

cameraEnhancer.cameraOpenTimeout = 10000; // Set the timeout to 10 seconds.

close

Stops video streaming and releases the camera.

close(): void;

Parameters

None.

Return value

None.

isOpen

Returns whether the selected camera is turned on / occupied.

isOpen(): boolean;

Parameters

None.

Return value

true means the camera is turned on and false the opposite.

pause

Pauses video streaming without releasing the camera.

pause(): void;

Parameters

None.

Return value

None.

isPaused

Returns whether the video streaming is paused.

isPaused(): boolean;

Parameters

None.

Return value

A Boolean value indicating whether the video streaming is paused.

resume

Resumes video streaming.

resume(): Promise<void>;

Parameters

None.

Return value

A promise that resolves when the operation succeeds.

getVideoSettings

Returns the current video settings.

getVideoSettings(): MediaStreamConstraints

Return value

A MediaStreamConstraints object.

See also

updateVideoSettings

Changes the video input.

updateVideoSettings(constraints: MediaStreamConstraints): Promise<ScannerPlayCallbackInfo | void>

Parameters

constraints : specifies the new video settings.

Return value

A promise resolving to a ScannerPlayCallbackInfo object.

Code Snippet

await scanner.updateVideoSettings({
    video: {
        width: {
            ideal: 1280
        },
        height: {
            ideal: 720
        },
        facingMode: {
            ideal: 'environment'
        }
    }
});

See also

setResolution

Sets the resolution of the selected camera. If the specified resolution is not exactly supported, the closest resolution will be applied.

If called before open() or show() , the camera will use the set resolution when it opens. Otherwise, the default resolution of 1920x1080 is used (1280x720 on mobile phones and pad devices).

setResolution(resolution: Resolution): Promise<PlayCallbackInfo>;

Parameters

resolution : specifies the resolution.

Return value

A promise resolving to a PlayCallbackInfo object.

Code Snippet

await cameraEnhancer.setResolution({width:1280, height:720});

See also

getResolution

Returns the resolution of the selected camera.

getResolution(): Resolution;

Parameters

None.

Return value

The resolution.

Code Snippet

let resolution = cameraEnhancer.getResolution();
console.log(resolution.width + " x " + resolution.height);

See also

getAvailableResolutions

Returns the resolutions supported by the selected camera.

NOTE

  1. The returned resolutions are limited to these values “160 by 120”, “320 by 240”, “480 by 360”, “640 by 480”, “800 by 600”, “960 by 720”, “1280 by 720”, “1920 by 1080”, “2560 by 1440”, “3840 by 2160”.
  2. The SDK tests all these resolutions to find out which ones are supported. As a result, the method may be time-consuming.
getAvailableResolutions(): Promise<Array<Resolution>>;

Parameters

None.

Return value

A promise that resolves when the operation succeeds.

Code Snippet

const resolutions = await cameraEnhancer.getAvailableResolutions();
console.log(resolutions);

testCameraAccess

Tests whether there is an available camera. This method offers the additional advantage of accelerating the camera opening process for the first time.

static testCameraAccess(): Promise<{ ok: boolean, message: string }>;

Parameters

None.

Return value

A promise resolving to a object containing two properties ok and message.

Code Snippet

const testResponse = await Dynamsoft.DCE.CameraEnhancer.testCameraAccess();
if (testResponse.ok) {
    console.log(testResponse.message);
}

ifSaveLastUsedCamera

Returns or sets whether to save the last used camera and resolution. This feature makes use of the localStorage of the browser.

NOTE

This feature only works on mainstream browsers like Chrome, Firefox and Safari. Other browsers may change the device IDs dynamically thus making it impossible to track the camera.

ifSaveLastUsedCamera: boolean;

videoSrc

Sets or returns the source of the video.

  1. You can use this property to specify an existing video as the source to play which will be processed the same way as the video feed from a live camera.

  2. When playing an existing video, the camera selection and video selection boxes will be hidden.

videoSrc: string;

setFrameRate

Adjusts the frame rate.

At present, this method only works in Edge, Safari, Chrome and other Chromium-based browsers (Firefox is not supported). Also, it should be called when a camera is open. If you provide a value that exceeds the camera’s capabilities, we will automatically adjust it to the maximum value that can be applied.

setFrameRate(rate: number): Promise<void>;

Parameters

rate : specifies the new frame rate.

Return value

A promise that resolves when the operation succeeds.

Code Snippet

await cameraEnhancer.setFrameRate(10);

See also

getFrameRate

Returns the real-time frame rate.

getFrameRate(): number;

Parameters

None.

Return value

The calculated real-time frame rate.

Code Snippet

await cameraEnhancer.getFrameRate();

turnOnTorch

Turns on the torch/flashlight if the current camera supports it.

This method should be called when the camera is turned on. Note that it only works with Chromium-based browsers such as Edge and Chrome on Windows or Android. Other browsers such as Firefox or Safari are not supported. Note that all browsers on iOS (including Chrome) use WebKit as the rendering engine and are not supported.

turnOnTorch(): Promise<void>;

Parameters

None.

Return value

A promise that resolves when the operation succeeds.

Code Snippet

await cameraEnhancer.turnOnTorch();

See also

turnOffTorch

Turns off the torch/flashlight.

This method should be called when the camera is turned on. Note that it only works with Chromium-based browsers such as Edge and Chrome on Windows or Android. Other browsers such as Firefox or Safari are not supported. Note that all browsers on iOS (including Chrome) use WebKit as the rendering engine and are not supported.

turnOffTorch(): Promise<void>;

Parameters

None.

Return value

A promise that resolves when the operation succeeds.

Code Snippet

await cameraEnhancer.turnOffTorch();

See also

getZoomSettings

Returns the zoom settings.

getZoomSettings(): { factor: number };

Parameters

None.

Return value

An object that describes the zoom settings. As of version 3.2, it contains only the zoom factor.

Code Snippet

console.log(cameraEnhancer.getZoomSettings().factor);

setZoom

Zooms the video.

How it works:

  1. If the camera supports zooming and the zoom factor is within its supported range, zooming is done directly by the camera.
  2. If the camera does not support zooming, software-based magnification is used instead.
  3. If the camera supports zooming but the zoom factor is beyond what it supports, the camera’s maximum zoom is used, and software-based magnification is used to do the rest. (In this case, you may see a brief video flicker between the two zooming processes).
setZoom(settings:{factor: number}): Promise<void>;

Parameters

settings : specifies how to zoom the video. As of version 3.2, the setting only contains a zoom factor.

Return value

A promise that resolves when the operation succeeds.

Code Snippet

if(cameraEnhancer.getCapabilities().zoom) {
    await cameraEnhancer.setZoom({
        factor: 3
    });
}

See also

resetZoom

Resets the zoom level of the video.

resetZoom(): Promise<void>;

Parameters

None.

Return value

A promise that resolves when the operation succeeds.

Code Snippet

await cameraEnhancer.resetZoom();

getFocusSettings

Returns the focus settings.

type FocusArea = {
    centerPoint: { x: string, y: string };
    width: string;
    height: string;
};
getFocusSettings(): {mode: string} | {mode: "manual", area: FocusArea} | {mode: "manual", distance: number};

Parameters

None.

Return value

The current focus settings.

Code Snippet

cameraEnhancer.getFocusSettings();

See also

setFocus

Sets how the camera focuses.

NOTE:

  1. This method should be called when the camera is turned on. Note that it only works with Chromium-based browsers such as Edge and Chrome on Windows or Android. Other browsers such as Firefox or Safari are not supported. Note that all browsers on iOS (including Chrome) use WebKit as the rendering engine and are not supported.
  2. Typically, continuous mode works best. manual mode based on a specific area helps the camera focus on that particular area which may seem blurry under continuous mode. manual mode with specified distances is for those rare cases where the camera distance must be fine-tuned to get the best results.
setFocus(settings: { mode: string } | { mode: 'manual', distance: number } | {
    mode: 'manual', area: {
        centerPoint: { x: string, y: string };
        // If not specified, the width is 1/6 of the video width or height, whichever is narrower
        width?: string;
        // If not specified, the height is 1/6 of the video width or height, whichever is narrower
        height?: string;
    }
}): Promise<void>;

Parameters

settings : specifies the focus settings. The value of mode depends on the capabilities of the current camera. Typically, “continuous” and “manual” are supported. distance and area are only effective when mode is set to manual and they should not coexist. The combinations are shown in the code snippet.

Return value

A promise that resolves when the operation succeeds.

Code Snippet

The “continuous” mode invokes the camera to focus automatically and continuously. Use getCapabilities() to inspect whether the camera supports “continuous” mode.

if (cameraEnhancer.getCapabilities().focusMode.find(mode => mode.localeCompare('continuous') == 0)) {
    await cameraEnhancer.setFocus({
        mode: "continuous"
    });
}

The “manual” mode means manually specifying the focus distance. Use getCapabilities() to inspect the distance range.

cameraEnhancer.getCapabilities().focusDistance; > //{max: 1024, min: 0, step: 10}

NOTE: If the set distance is between two allowed values, it will be rounded to the nearest value.

await cameraEnhancer.setFocus({
    mode: "manual",
    distance: 200
});

The SDK also has a built-in algorithm that adjusts focus distance based on the blurriness of a particular area. Specify the area with the parameter area .

NOTE: the area is a rectangle defined by its center point and its width and height. All coordinates can be in pixels or percentages, such as “500px” or “50%”. Percentages are based on stream dimensions.

await cameraEnhancer.setFocus({
    mode: "manual",
    area: {
        centerPoint: {
            x: "50%",
            y: "50%"
        },
        width: "50%",
        height: "50%"
    }
});

See also

getCapabilities

Inspects and returns the capabilities of the selected camera.

At present, this method only works in Edge, Safari, Chrome and other Chromium-based browsers (Firefox is not supported). Also, it should be called when a camera is open.

getCapabilities(): MediaTrackCapabilities;

Parameters

None.

Return value

A MediaTrackCapabilities object which specifies the values or range of values for each constrainable property of the current camera.

Code Snippet

cameraEnhancer.getCapabilities();
/* Result sample
{
  aspectRatio: {max: 1280, min: 0.001388888888888889},
  brightness: {max: 64, min: -64, step: 1},
  colorTemperature: {max: 6500, min: 2800, step: 10},
  contrast: {max: 95, min: 0, step: 1},
  deviceId: "3a505c29a3312600ea0afd79f8e2b4ba4fba3e539257801ff1de8718c27f2bed",
  exposureMode: ["continuous", "manual"],
  exposureTime: {max: 10000, min: 39.0625, step: 39.0625},
  facingMode: [],
  focusDistance: {max: 1024, min: 0, step: 10},
  focusMode: ["continuous", "manual"],
  frameRate: {max: 30, min: 0},
  groupId: "35a82dcb7d5b0ef5bda550718d194f04a812c976175e926ccb81fb9d235d010f",
  height: {max: 720, min: 1},
  resizeMode: ["none", "crop-and-scale"],
  saturation: {max: 100, min: 0, step: 1},
  sharpness: {max: 7, min: 1, step: 1},
  whiteBalanceMode: ["continuous", "manual"],
  width: {max: 1280, min: 1}
}
*/

See also

getCameraSettings

Returns the current values for each constrainable property of the selected camera.

getCameraSettings(): MediaTrackSettings;

Parameters

None.

Return value

The current values for each constrainable property of the current camera in the form of a MediaTrackSettings object.

Code Snippet

cameraEnhancer.getCameraSettings();
/* Result sample
{
  aspectRatio: 1.3333333333333333,
  brightness: 0,
  colorTemperature: 4600,
  contrast: 0,
  deviceId: "3a505c29a3312600ea0afd79f8e2b4ba4fba3e539257801ff1de8718c27f2bed",
  exposureMode: "continuous",
  exposureTime: 156.25,
  focusDistance: 120,
  focusMode: "continuous",
  frameRate: 30,
  groupId: "35a82dcb7d5b0ef5bda550718d194f04a812c976175e926ccb81fb9d235d010f",
  height: 480,
  resizeMode: "none",
  saturation: 73,
  sharpness: 2,
  whiteBalanceMode: "continuous",
  width: 640
}
*/

See also

getColorTemperature

Returns the color temperature of the selected camera.

This method should be called when the camera is turned on. Note that it only works with Chromium-based browsers such as Edge and Chrome on Windows or Android. Other browsers such as Firefox or Safari are not supported. Note that all browsers on iOS (including Chrome) use WebKit as the rendering engine and are not supported.

getColorTemperature(): number;

setColorTemperature

Adjusts the color temperature of the selected camera.

This method should be called when the camera is turned on. Note that it only works with Chromium-based browsers such as Edge and Chrome on Windows or Android. Other browsers such as Firefox or Safari are not supported. Note that all browsers on iOS (including Chrome) use WebKit as the rendering engine and are not supported.

setColorTemperature(colorTemperatur: number): Promise<void>;

Parameters

colorTemperatur : specifies the new color temperature.

Return value

A promise that resolves when the operation succeeds.

Code Snippet

await cameraEnhancer.setColorTemperature(5000);

See also

getExposureCompensation

Returns the exposure compensation index of the selected camera.

This method should be called when the camera is turned on. Note that it only works with Chromium-based browsers such as Edge and Chrome on Windows or Android. Other browsers such as Firefox or Safari are not supported. Note that all browsers on iOS (including Chrome) use WebKit as the rendering engine and are not supported.

getExposureCompensation(): number;

setExposureCompensation

Sets the exposure compensation index of the selected camera.

This method should be called when the camera is turned on. Note that it only works with Chromium-based browsers such as Edge and Chrome on Windows or Android. Other browsers such as Firefox or Safari are not supported. Note that all browsers on iOS (including Chrome) use WebKit as the rendering engine and are not supported.

setExposureCompensation(exposureCompensation: number): Promise<void>;

Parameters

exposureCompensation : specifies the new exposure compensation index.

Return value

A promise that resolves when the operation succeeds.

Code Snippet

await cameraEnhancer.setExposureCompensation(-0.7);

See also

setAutoZoomRange

Sets the range (minimum to maximum) for zoom when it is done automatically.

EF_AUTO_ZOOM is one of the enhanced features that require a license, and is only effective when used in conjunction with other functional products of Dynamsoft.

setAutoZoomRange(range: { min: number, max: number }): void;

Parameters

  • range: specifies the zoom range (from minimum value to maximum value).

Return value

None.

Code Snippet

cameraEnhancer.setAutoZoomRange({min: 1, max: 5});

getAutoZoomRange

Returns the auto zoom range.

getAutoZoomRange(): { min: number, max: number };

Parameters

None.

Return value

The zoom range.

Code Snippet

let zoomRange = cameraEnhancer.getAutoZoomRange();

enableEnhancedFeatures

Enables the specified enhanced features.

  • The enhanced features require a license, and only take effect when used in conjunction with other functional products under Dynamsoft Capture Vision(DCV)architecture: EF_ENHANCED_FOCUS, EF_AUTO_ZOOM,EF_TAP_TO_FOCUS.
  • EF_ENHANCED_FOCUS and EF_TAP_TO_FOCUS only works with Chromium-based browsers such as Edge and Chrome on Windows or Android. Other browsers such as Firefox or Safari are not supported. Note that all browsers on iOS (including Chrome) use WebKit as the rendering engine and are not supported.
enableEnhancedFeatures(features: EnumEnhancedFeatures): Promise<void>;

Parameters

  • features: specifies the features to enable.

Return value

None.

Code Snippet

//you need to include cvr and initialize the license for enabling enhanced features
Dynamsoft.License.LicenseManager.initLicense("YOUR-LICENSE");

await cameraEnhancer.enableEnhancedFeatures(EnumEnhancedFeatures.EF_AUTO_ZOOM);

See also

disableEnhancedFeatures

Disables the specified enhanced features.

disableEnhancedFeatures(features: EnumEnhancedFeatures): void;

Parameters

  • features: specifies the features to disable.

Return value

None.

Code Snippet

await cameraEnhancer.disableEnhancedFeatures(EnumEnhancedFeatures.EF_AUTO_ZOOM);

See also

ifSkipCameraInspection

Sets or returns whether to opt for an optimal rear camera at the first open(). If skipped, the instantiation is done faster. Note that if a previously used camera is already available in the localStorage, the inspection is skipped automatically. Read more on ifSaveLastUsedCamera.

ifSkipCameraInspection: boolean;

This page is compatible for:

Version 1.0

Is this page helpful?

YesYes NoNo

In this article:

latest version

  • Latest version
  • Version 4.x
    • Version 4.0.1(latest)
    • Version 4.0.0
  • Version 3.x
    • Version 3.3.10
    • Version 3.3.9
    • Version 3.3.8
    • Version 3.3.7
    • Version 3.3.6
    • Version 3.3.5
    • Version 3.3.4
    • Version 3.3.3
    • Version 3.3.2
    • Version 3.3.1
    • Version 3.3.0
    • Version 3.2.0
    • Version 3.1.0
    • Version 3.0.1
    • Version 3.0.0
  • Version 2.x
    • Version 2.3.5
    • Version 2.3.2
    • Version 2.3.1
    • Version 2.3.0
    • Version 2.1.4
    • Version 2.1.3
    • Version 2.1.0
    • Version 2.0.0
Change +