BarcodeScanner for Video

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.

Change Settings

Auxiliary

createInstance

Creates a BarcodeScanner instance.

static createInstance(): Promise<BarcodeScanner>

Parameters

None.

Return value

A promise resolving to the created BarcodeScanner object.

Code Snippet

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

destroy

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.

destroy(): Promise<void>

Parameters

None.

Return value

A promise that resolves when the operation succeeds.

Code Snippet

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

bDestroyed

Indicates whether the instance has been destroyed.

readonly bDestroyed: boolean

onUnduplicatedRead

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

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.

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

Arguments

txt : a string that holds the barcode text.

result : a TextResult object that contains more detailed info.

Code Snippet

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

See also

• TextResult

onFrameRead

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

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

Arguments

results : a TextResult object that contains all the barcode results in this frame.

Code Snippet

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

See also

• TextResult

decodeCurrentFrame

Scans the current frame of the video for barcodes.

decodeCurrentFrame(): Promise<TextResult[]>

Parameters

None.

Return value

A promise resolving to a TextResult object that contains all the barcode results found in this frame.

Code Snippet

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

See also

• TextResult

show

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

show(): Promise<ScannerPlayCallbackInfo>

Parameters

None.

Return value

A promise resolving to a ScannerPlayCallbackInfo object.

Code Snippet

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

See also

• ScannerPlayCallbackInfo

hide

Stops decoding, releases camera and unbinds UI.

hide(): Promise<void>

Parameters

None.

Return value

A promise that resolves when the operation succeeds.

Code Snippet

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

pauseScan

Pauses the decoding process.

pauseScan(): void

Parameters

None.

Return value

None.

resumeScan

Resumes the decoding process.

resumeScan(): void

Parameters

None.

Return value

None.

bPlaySoundOnSuccessfulRead

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).

bPlaySoundOnSuccessfulRead: (boolean | string)

Default value

false

Code Snippet

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

soundOnSuccessfullRead

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

soundOnSuccessfullRead: HTMLAudioElement

Code Snippet

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

See also

• HTMLAudioElement
• bPlaySoundOnSuccessfulRead

bVibrateOnSuccessfulRead

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).

bVibrateOnSuccessfulRead: (boolean | string)

Default value

false

Code Snippet

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

vibrateDuration

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

vibrateDuration: number

See also

• bVibrateOnSuccessfulRead

singleFrameMode

Returns or sets the status of the single-frame mode. If enabled, the video input will not be played and the user can choose to take a picture with the system camera or select an existing image for barcode reading.

The single-frame mode can only be enabled or disabled before the video input starts playing.

singleFrameMode: boolean

getScanSettings

Returns the current scan settings.

getScanSettings(): Promise<ScanSettings>

Parameters

None.

Return value

A promise resolving to a ScanSettings .

Code Snippet

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

See also

• ScanSettings

updateScanSettings

Changes scan settings with the object passed in.

updateScanSettings(settings: ScanSettings): Promise<void>

Parameters

settings : specifies the new scan settings.

Return value

A promise that resolves when the operation succeeds.

Code Snippet

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

See also

• ScanSettings

getUIElement

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

getUIElement(): HTMLElement

setUIElement

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.

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

Parameters

elementOrURL : specifies the element.

Return value

A promise that resolves when the operation succeeds.

Code Snippet

<!-- 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

Returns or sets the URL of the .html file that defines the default UI Element. The URL can only be set before the API createInstance is called.

static defaultUIElementURL: string

Code Snippet

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

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

barcodeFillStyle: string

barcodeStrokeStyle

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).

barcodeStrokeStyle: string

barcodeLineWidth

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

barcodeLineWidth: number

regionMaskFillStyle

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).

regionMaskFillStyle: string

See also

• Read a specific area/region

regionMaskStrokeStyle

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).

regionMaskStrokeStyle: string

See also

• Read a specific area/region

regionMaskLineWidth

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.

regionMaskLineWidth: number

See also

• Read a specific area/region

getAllCameras

Returns infomation 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 scanner.getAllCameras();
if(cameras.length){
  await scanner.setCurrentCamera(cameras[0]);
}

See also

• VideoDeviceInfo

getCurrentCamera

Returns information about the current camera.

getCurrentCamera(): Promise<VideoDeviceInfo | null>

Parameters

None.

Return value

A promise resolving to a VideoDeviceInfo object.

Code Snippet

let camera = await scanner.getCurrentCamera();

See also

• VideoDeviceInfo

setCurrentCamera

Chooses a camera as the video source.

setCurrentCamera(deviceID: string): Promise<ScannerPlayCallbackInfo>

Parameters

deviceID: specifies the camera.

Return value

A promise resolving to a ScannerPlayCallbackInfo object.

Code Snippet

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

See also

• ScannerPlayCallbackInfo

getResolution

Returns the resolution of the current video input.

getResolution(): number[]

Parameters

None.

Return value

An array of two numbers representing the resolution.

Code Snippet

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

setResolution

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

setResolution(width: number, height: number): Promise<ScannerPlayCallbackInfo>

Parameters

width: specifies the horizontal resolution. height: specifies the vertical resolution.

Return value

A promise resolving to a ScannerPlayCallbackInfo object.

Code Snippet

await scanner.setResolution(width, height);

See also

• ScannerPlayCallbackInfo

getVideoSettings

Returns the current video settings.

getVideoSettings(): MediaStreamConstraints

Parameters

None.

Return value

A MediaStreamConstraints object.

See also

• MediaStreamConstraints

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

• MediaStreamConstraints
• ScannerPlayCallbackInfo

openVideo

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

openVideo(): Promise<ScannerPlayCallbackInfo>

Parameters

None.

Return value

A promise resolving to a ScannerPlayCallbackInfo object.

Code Snippet

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());

See also

• ScannerPlayCallbackInfo

showVideo

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

showVideo(): Promise<ScannerPlayCallbackInfo>

Parameters

None.

Return value

A promise resolving to a ScannerPlayCallbackInfo object.

Code Snippet

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());

See also

• ScannerPlayCallbackInfo

play

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

play(): Promise<ScannerPlayCallbackInfo>

Parameters

None.

Return value

A promise resolving to a ScannerPlayCallbackInfo object.

Code Snippet

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

See also

• ScannerPlayCallbackInfo

onPlayed

This event is triggered when the video stream starts playing.

event onPlayed: (info: ScannerPlayCallbackInfo) => void

Arguments

info: a ScannerPlayCallbackInfo object which describes the resolution of the video input.

Code Snippet

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

See also

• ScannerPlayCallbackInfo

pause

Pauses the video without releasing the camera.

pause(): void

Parameters

None.

Return value

None.

stop

Stops the video and releases the camera.

stop(): void

Parameters

None.

Return value

None.

getCapabilities

Inspects and returns the capabilities of the current camera.

Right now, this method only works in Chrome and should be called when the scanner 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

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

See also

• MediaTrackCapabilities

getCameraSettings

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.

getCameraSettings(): any

Parameters

None.

Return value

The current values for each constrainable property of the current camera

Code Snippet

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 also

• getCapabilities

setFrameRate

Adjusts the frame rate.

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

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 scanner.setFrameRate(10);

See also

• getCapabilities

setColorTemperature

Adjusts the color temperature.

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

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 scanner.setColorTemperature(5000);

See also

• getCapabilities

setExposureCompensation

Sets the exposure compensation index.

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

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 scanner.setExposureCompensation(-0.7);

See also

• getCapabilities

setZoom

Sets current zoom value.

setZoom(zoomValue: number): Promise<void>

Parameters

zoomValue: specifies the new zoom value.

Return value

A promise that resolves when the operation succeeds.

Code Snippet

await scanner.setZoom(400);

See also

• getCapabilities

turnOnTorch

Turns on 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.

turnOnTorch(): Promise<void>

Parameters

None.

Return value

A promise that resolves when the operation succeeds.

Code Snippet

await scanner.turnOnTorch();

See also

• turnOffTorch
• getCapabilities

turnOffTorch

Turns off the torch/flashlight.

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

turnOffTorch(): Promise<void>

Parameters

None.

Return value

A promise that resolves when the operation succeeds.

Code Snippet

await scanner.turnOffTorch();

See also

• turnOnTorch
• getCapabilities