Resource Base
Table of contents

Thanks for downloading Dynamsoft Barcode Reader Package!

Your download will start shortly. If your download does not begin, click here to retry.

BarcodeScanner

A barcode scanner object gets access to a camera via the MediaDevices interface, then uses its built-in UI to show the camera input and perform continuous barcode scanning on the incoming frames.

The default built-in UI of each barcode scanner is defined in the file “dbr.scanner.html”. If used directly, the UI will fit the entire page and sit on top. There are a few ways to customize it, read more on how to Customize the UI.

Although a barcode scanner is designed to scan barcodes from a video input, it also supports a special mode called singleFrameMode which allows the user to select a still image or take a shot with the mobile camera for barcode scanning.

The BarcodeScanner is a child class of BarcodeReader and inherits all its methods and properties which will not be covered in this article.

The following code snippet shows the basic usage of the BarcodeScanner class.

let scanner = await Dynamsoft.DBR.BarcodeScanner.createInstance();
scanner.onUnduplicatedRead = txt => console.log(txt);
await scanner.show();

API Index

Create and Destroy Instances


Decode Barcodes


Basic Interaction


Scan Settings


UI Control


Camera Control


Advanced Camera Control


The following are inherited from the BarcodeReader Class.

Decode Barcodes


Change Settings


Auxiliary


Create and Destroy Instances

createInstance


static createInstance(): Promise<BarcodeScanner>


Creates a BarcodeScanner instance.

Example

let scanner = await Dynamsoft.DBR.BarcodeScanner.createInstance();

destroy


destroy(): Promise<void>


Destroys the BarcodeScanner instance. If your page needs to create a new instance from time to time, don’t forget to destroy unused old instances.

Example

let scanner = await Dynamsoft.DBR.BarcodeScanner.createInstance();
// ... decode ...
scanner.destroy();

bDestroyed


bDestroyed: boolean


Indicates whether the instance has been destroyed.

Decode Barcodes

onUnduplicatedRead


event onUnduplicatedRead?: (txt: string, result: TextResult) => void


This event is triggered when a new, unduplicated barcode is found.

txt holds the barcode text string. result contains more detailed info.

The library keeps each barcode result (type and value) in the buffer for a period of time (can be set with duplicateForgetTime) during which if a new result is an exact match, it’s seen as a duplicate and will again be kept for that period of time while the old result is removed and so on.

Example

scanner.onUnduplicatedRead = (txt, result) => {
  alert(txt);
  console.log(result);
}

onFrameRead


event onFrameRead?: (results: TextResult[]) => void


This event is triggered after the library finishes scanning a frame.

The results object contains all the barcode results in this frame.

Example

scanner.onFrameRead = results => {
  for(let result of results){
    console.log(result.barcodeText);
  }
};

decodeCurrentFrame


decodeCurrentFrame(): Promise<TextResult[]>


Scans the current frame of the video for barcodes.

Example

await scanner.showVideo();
console.log(await scanner.decodeCurrentFrame());

Basic Interaction

show


show(): Promise<ScannerPlayCallbackInfo>


Binds and shows UI, opens the camera and starts decoding.

Example

scanner.onUnduplicatedRead = (txt, result) => { 
  alert(txt); console.log(result); };
await scanner.show();

hide


hide(): Promise<void>


Stops decoding, releases camera and unbinds UI.

Example

await scanner.show();
//...scan barcodes
await scanner.hide();

pauseScan


pauseScan(): void


Pauses the decoding process.

resumeScan


resumeScan(): void


Resumes the decoding process.

Scan Settings

bPlaySoundOnSuccessfulRead


bPlaySoundOnSuccessfulRead: (boolean | string);


Whether and when to play sound on barcode recognition (user input is required on iOS or Chrome for any sound to play). Allowed values are

  • false: never play sound, the default value;
  • true: play sound when one or multiple barcodes are found on a frame;
  • frame: same as true;
  • unduplicated: play sound when a unique/unduplicated barcode is found (if multiple unique barcodes are found on the same frame, play only once).

Example

// A user gesture required. 
startPlayButton.addEventListener('click', function() {
  scanner.bPlaySoundOnSuccessfulRead = true;
});

soundOnSuccessfullRead


soundOnSuccessfullRead: HTMLAudioElement


Specifies the sound to play on barcode recognition. If not specified, the default one is used.

Example

scanner.soundOnSuccessfullRead = new Audio("./pi.mp3");

bVibrateOnSuccessfulRead


bVibrateOnSuccessfulRead: (boolean | string)


Whether and when to vibrate on barcode recognition (user input is required on iOS or Chrome for the vibration). Allowed values are

  • false: never vibrate, the default value;
  • true: vibrate when one or multiple barcodes are found on a frame;
  • frame: same as true;
  • unduplicated: vibrate when a unique/unduplicated barcode is found (if multiple unique barcodes are found on the same frame, vibrate only once).

Example

// Can I use? https://caniuse.com/?search=vibrate
startVibrateButton.addEventListener('click', function() {
  scanner.bVibrateOnSuccessfulRead = true;
});

vibrateDuration


vibrateDuration: number


Returns or sets how long the vibration lastsin milliseconds. The default value is 300.

@see bVibrateOnSuccessfulRead

getScanSettings


getScanSettings(): Promise<ScanSettings>


Returns the current scan settings.

Example

let scanSettings = await scanner.getScanSettings();
scanSettings.intervalTime = 50;
scanSettings.duplicateForgetTime = 1000;
await scanner.updateScanSettings(scanSettings);

@see ScanSettings

updateScanSettings


updateScanSettings(settings: ScanSettings): Promise<void>


Changes scan settings with the object passed in.

Parameters

  • settings: ScanSettings The object representing the new settings.

Example

let scanSettings = await scanner.getScanSettings();
scanSettings.intervalTime = 50;
scanSettings.duplicateForgetTime = 1000;
await scanner.updateScanSettings(scanSettings);

UI Control

getUIElement


getUIElement(): HTMLElement


Returns the HTML element that is used by the BarcodeScanner instance.

setUIElement


setUIElement(elementOrURL: HTMLElement | string): Promise<void>


Specifies an HTML element for the BarcodeScanner instance to use as its UI. The structure inside the element determines the appearance of the UI. See more on how to customize the UI.

Parameters

  • elementOrURL: HTMLElement | string Specifies the UI Element either with an element on the page or the URL of an .html file which defines the element.

Example

<!-- Define an element that shows only the video input -->
<video class="dbrScanner-video" playsinline="true"></video>
<script>
  let scanner = await Dynamsoft.DBR.BarcodeScanner.createInstance();
  await scanner.setUIElement(document.getElementsByClassName("dbrScanner-video")[0]);
  await scanner.open();
</script>
<!-- Use the default official UI element definition -->
<script>
  let scanner = await Dynamsoft.DBR.BarcodeScanner.createInstance();
  await scanner.setUIElement("https://cdn.jsdelivr.net/npm/dynamsoft-javascript-barcode@8.4.0/dist/dbr.scanner.html");
  await scanner.show();
</script>

defaultUIElementURL


static defaultUIElementURL: string


Returns or sets the URL of the .html file that defines the default UI Element.

The URL is only effective when changed before the API createInstance is called.

Example

Dynamsoft.DBR.BarcodeScanner.defaultUIElementURL = "https://cdn.jsdelivr.net/npm/dynamsoft-javascript-barcode@8.4.0/dist/dbr.scanner.html";
let scanner = await Dynamsoft.DBR.BarcodeScanner.createInstance();
await scanner.show();

barcodeFillStyle


barcodeFillStyle: string


Specifies the color used inside the shape which highlights a found barcode. The default value is rgba(254,180,32,0.3).

barcodeStrokeStyle


barcodeStrokeStyle: string


Specifies the color used to paint the outline of the shape which highlights a found barcode. The default value is rgba(254,180,32,0.9).

barcodeLineWidth


barcodeLineWidth: number


Specifies the line width of the outline of the shape which highlights a found barcode. The default value is 1.

regionMaskFillStyle


regionMaskFillStyle: string


Specifies the color used in the square-loop shape between the actual scanning area and the boundary of the video input. This shape only appears when the barcode scanning is limited to a specified region. The default value is rgba(0,0,0,0.5). @see Read a specific area/region

regionMaskStrokeStyle


regionMaskStrokeStyle: string


Specifies the color used to paint the outline of the scanning region. This outline only appears when the barcode scanning is limited to a specified region. The default value is rgb(254,142,20). @see Read a specific area/region

regionMaskLineWidth


  • regionMaskLineWidth: number

Specifies the width of the outline of the scanning region. This outline only appears when the barcode scanning is limited to a specified region. The default value is 2. @see Read a specific area/region

Camera Control

getAllCameras


getAllCameras(): Promise<VideoDeviceInfo[]>


Returns infomation of all available cameras on the device.

Example

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

getCurrentCamera


getCurrentCamera(): Promise<VideoDeviceInfo | null>


Returns information about the current camera.

Example

let camera = await scanner.getCurrentCamera();

setCurrentCamera


setCurrentCamera(deviceID: string): Promise<ScannerPlayCallbackInfo>


Chooses a camera as the video source.

Parameters

  • deviceID Specifies the camera with its device ID.

Example

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

getResolution


getResolution(): number[]


Returns the resolution of the current video input.

Example

let rsl = await scanner.getResolution();
console.log(rsl.width + " x " + rsl.height);

setResolution


setResolution(width: number, height: number)


Sets the resolution of the current video input. If the specified resolution is not exactly supported, the closest resolution will be applied.

Example

await scanner.setResolution(width, height);

getVideoSettings


getVideoSettings(): MediaStreamConstraints


Returns the current video settings.

updateVideoSettings


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


Changes the video input.

Parameters

  • constraints A MediaStreamConstraints object specifying the requirements for the video input.

Example

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

openVideo


openVideo(): Promise<ScannerPlayCallbackInfo>


Binds UI and opens the camera to show the video stream.

Example

await scanner.setUIElement("https://cdn.jsdelivr.net/npm/dynamsoft-javascript-barcode@8.4.0/dist/dbr.scanner.html");
await scanner.openVideo(); // The video will start playing but it may not be visible on the page
console.log(await scanner.decodeCurrentFrame());

showVideo


showVideo(): Promise<ScannerPlayCallbackInfo>


Similar to openVideo but will also show the UI Element if it is hidden.

Example

await scanner.setUIElement("https://cdn.jsdelivr.net/npm/dynamsoft-javascript-barcode@8.4.0/dist/dbr.scanner.html");
await scanner.showVideo(); // The video will start playing and show up on the page
console.log(await scanner.decodeCurrentFrame());

play


play(): Promise<ScannerPlayCallbackInfo>


Play the video if it is already open but paused or stopped. If the video is already playing, it will start again.

Example

scanner.pause();
//..doing other things without the video
await scanner.play();

onPlayed


event onPlayed?: (info: ScannerPlayCallbackInfo) => void


This event is triggered when the video stream starts playing.

Example

scanner.onplayed = rsl=>{ console.log(rsl.width+'x'+rsl.height) };
await scanner.show(); // or open(), play(), setCurrentCamera(), etc.

pause


pause(): void


Pauses the video without releasing the camera.

stop


stop(): void


Stops the video and releases the camera.

Advanced Camera Control

getCapabilities


getCapabilities(): MediaTrackCapabilities


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

Right now, this method only works in Chrome and should be called when the scanner is open.

Example

scanner.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}
}
*/

getCameraSettings


getCameraSettings(): any


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

Right now, this method only works in Chrome and should be called when the scanner is open.

Example

scanner.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 getCapabilities

setFrameRate


setFrameRate(rate: number): Promise<void>


Adjusts the frame rate.

Right now, this method only works in Chrome and should be called when the scanner is open.

Parameters

  • rate Specifies the frame rate.

Example

await scanner.setFrameRate(10);

@see getCapabilities

setColorTemperature


setColorTemperature(colorTemperatur: number): Promise<void>


Adjusts the color temperature.

Right now, this method only works in Chrome and should be called when the scanner is open.

Parameters

  • colorTemperatur Specifies the color temperatur.

Example

await scanner.setColorTemperature(5000);

@see getCapabilities

setExposureCompensation


setExposureCompensation(exposureCompensation: number): Promise<void>


Adjusts the exposure level.

Right now, this method only works in Chrome and should be called when the scanner is open.

Parameters

  • exposureCompensation Specifies the exposure compensation.

Example

await scanner.setExposureCompensation(-0.7);

@see getCapabilities

setZoom


setZoom(zoomLevel: number): Promise<void>


Adjusts the video zoom.

Right now, this method only works in Chrome and should be called when the scanner is open.

Parameters

  • zoomLevel Specifies the zoom level.

Example

await scanner.setZoom(400);

@see getCapabilities

turnOnTorch


turnOnTorch(): Promise<void>


Turns on the torch/flashlight.

Right now, this method only works in Chrome and should be called when the scanner is open.

Example

await scanner.turnOnTorch();

@see turnOffTorch, getCapabilities

turnOffTorch


turnOffTorch(): Promise<void>


Turns off the torch/flashlight.

Right now, this method only works in Chrome and should be called when the scanner is open.

Example

await scanner.turnOffTorch();

@see turnOnTorch getCapabilities

This page is compatible for:

Version 7.5

Is this page helpful?

YesYes NoNo

In this article:

latest version

  • Latest Version
  • version 8.4
  • version 8.2.5
  • version 8.2
  • version 8.1.2
  • version 8.0
  • version 7.6
  • version 7.5
Change +
© 2003–2021 Dynamsoft. All rights reserved.
Privacy Statement / Site Map / Home / Purchase / Support