Options
All
  • Public
  • Public/Protected
  • All
Menu

Dynamsoft BarcodeReader SDK for Javascript

Dynamsoft JavaScript Barcode SDK

Version: 7.1.0

This repository aims to help developers get familiar with Dynamsoft BarcodeReader SDK for Javascript.

Features

  • Supported Symbologies:

    1D barcode: Code 39, Code 93, Code 128, Codabar, EAN-8, EAN-13, UPC-A, UPC-E, Interleaved 2 of 5 (ITF), Industrial 2 of 5 (Code 2 of 5 Industry, Standard 2 of 5, Code 2 of 5), ITF-14.

    2D barcode: PDF417, QR, DataMatrix, and Aztec.

  • Supported Data Sources: Blob, HTMLImageElement, HTMLVideoElement, and URL, etc.

  • Browser Compatibility:

Browser Name Version
Chrome v57+ (v59+ on Android/iOS1)
Firefox v52+ (v55+ on Android/iOS1)
Edge v16+
Safari2 v11+

1 On iOS, camera video streaming only works in Safari.

2 Safari 11.2.2 ~ 11.2.6 are not supported.

Node.js v8+ is also supported. However, it can only use BarcodeReader to read barcode from still-images. The video stream reader object BarcodeScanner is not supported.

Table of Contents

Live Demo

The following is a screenshot of the live demo. Try it here.

Getting Started: HelloWorld

This section will help you use the library to build a simple web application to decode barcodes from a video stream.

Basic Requirements:

  • Internet connection

  • Camera Access

Step One: Write the code in minutes!

Create an HTML file with the following content. Deploy it to your web server if you have it already.

  • The sample is missing one piece of information to actually work which is the field LICENSE-KEY, you can acquire a trial key here and replace the field with your key.
  • If you don't have a ready-to-use web server and you happen to have a package manager like npm or yarn, you can set up a simple http server in minutes. Check out http-server on npm or yarn.
<!DOCTYPE html>
<html>
<body>
    <!--
        Warning: Use a specific version in production. (e.g. https://cdn.jsdelivr.net/npm/dynamsoft-javascript-barcode@x.x.x/dist/dbr.min.js)
        Please visit https://www.dynamsoft.com/CustomerPortal/Portal/TrialLicense.aspx to get trial license.
    -->
    <script src="https://cdn.jsdelivr.net/npm/dynamsoft-javascript-barcode@7/dist/dbr.min.js" data-productKeys="LICENSE-KEY"></script>
    <script>
        let barcodeScanner = null;
        Dynamsoft.BarcodeScanner.createInstance({
            onFrameRead: results => {console.log(results);},
            onUnduplicatedRead: (txt, result) => {alert(txt);}
        }).then(scanner => {
            barcodeScanner = scanner;
            barcodeScanner.show();
        });
    </script>
</body>
</html>

Try in JSFiddle

Step Two: Tackle a few issues

Open the file in your browser (must be one that is supported) and there will be a pop-up asking for permission to access the camera. Once the access is granted, you will see the video stream in the default UI of the BarcodeScanner.

General Issue one

If you open the HTML file as file:/// or http://, the following error may appear in the browser console

[Deprecation] getUserMedia() no longer works on insecure origins. To use this feature, you should consider switching your application to a secure origin, such as HTTPS. See https://goo.gl/rStTGz for more details.

In Safari 12 the error is

Trying to call getUserMedia from an insecure document.

As the error states, to access the camera with the API getUserMedia, a secure channel (https://) is required.

If you use Chrome or Firefox, you might not get the error because these two browsers allow camera access via file:/// and http://localhost.

To make sure your web application can access the camera, try to configure your web server to support HTTPS. The following links may help.

General Issue Two

For testing purposes, a self-signed certificate can be used when configuring HTTPS. When accessing the site, the browser might say "the site is not secure". In this case, go to the certificate settings and trust this certificate.

In a production environment, you will need a valid HTTPS certificate that does not have this issue. If you don't have one yet, you can get a free one from Let’s Encrypt. Of course, you are advised to apply for a paid certificate from companies such as Verisign, GeoTrust, etc.

Step Three: Time to scan!

Put something with a barcode in front of the camera and you'll see it located and decoded right in the UI.

Step Four: Dive into the code

Now, take a look at the sample code. You can find that there is nothing but two scripts inside the <body>

  • The following script includes the core library in the application via a jsDelivr CDN

    <script src="https://cdn.jsdelivr.net/npm/dynamsoft-javascript-barcode@7/dist/dbr.min.js" data-productKeys="LICENSE-KEY"></script>

    The same can be done with other CDNs like unpkg as well

    <script src="https://unpkg.com/dynamsoft-javascript-barcode@7/dist/dbr.min.js" data-productKeys="LICENSE-KEY"></script>
  • The following script initializes and uses the library:

    <script>
        let barcodeScanner = null;
        Dynamsoft.BarcodeScanner.createInstance({
            onFrameRead: results => {console.log(results);},
            onUnduplicatedRead: (txt, result) => {alert(txt);}
        }).then(scanner => {
            barcodeScanner = scanner;
            barcodeScanner.show();
        });
    </script>

    For now, pay attention to the following two events.

    • onFrameRead This event is triggered after a single frame is scanned. The results object contains all the barcode results that the library found on this frame.
      • onUnduplicatedRead This event is triggered when a new barcode (not a duplicate) is found. txt holds the barcode text value while result is an object that holds details of the found barcode.

In the following sections, you'll find more detailed information on how the library works and how you can customize it to your needs.

Getting Started: Take a closer look

Initializing

The library is based on the WebAssembly standard, therefore, on first use, it needs some time to download and compile the WebAssembly files. After the first use, the program will cache the wasm file in the IndexedDB so that the next time you can just open and play.

Dynamsoft.BarcodeReader.loadWasm is the API used to start the initialization. However, other APIs like Dynamsoft.BarcodeReader.createInstance, Dynamsoft.BarcodeScanner.createInstance will call loadWasm internally so it is not necessary to explicitly call loadWasm when using these APIs.

Including the library with a script tag doesn't automatically initializes the library.

The initialization includes the following steps:

  1. Download

Dynamsoft.BarcodeReader._onWasmDownloaded is a built-in callback that gets triggered when the WebAssembly files are downloaded. As the downloading only happens on the first use, this callback will only be triggered once as well (assume that the user doesn't clear the old cached files).

  1. Compile

The WebAssembly files are automatically compiled once downloaded. The compilation time varies among different devices & browsers. While it takes less than tenth of a seconds on latest phones or PCs, it may take seconds on some older devices.

  1. Initialize

The library needs to initialize every time the page loads. Use the following code to listen to the initialization process:

Dynamsoft.BarcodeReader.loadWasm()
    .then(()=>{ /* success */ }, ex=>{console.error(ex.message||ex);})

You can use Dynamsoft.BarcodeReader.createInstance or Dynamsoft.BarcodeScanner.createInstance as well, to listen to the initialization process during createInstance.

Configuring Scanner Settings

When creating an instance of the BarcodeScanner object, there are a number of configuration options. The following code shows some of the most useful ones:

let barcodeScanner = null;
Dynamsoft.BarcodeScanner.createInstance({
    // The following two callbacks are explained in previous context
    onFrameRead: results => {console.log(results);},
    onUnduplicatedRead: (txt, result) => {alert(txt);}
}).then(scanner => {
    barcodeScanner = scanner;
    // updateVideoSettings sets which camera and what resolution to use
    barcodeScanner.updateVideoSettings({ video: { width: 1280, height: 720, facingMode: "environment" } });

    let runtimeSettings = barcodeScanner.getRuntimeSettings();
    // Specify which symbologies are to enabled
    runtimeSettings.BarcodeFormatIds = Dynamsoft.EnumBarcodeFormat.OneD | Dynamsoft.EnumBarcodeFormat.QR_CODE;
    // By default, the library assumes accurate focus and good lighting. The settings below are for more complex environments. Check out according API descriptions for more info.
    runtimeSettings.localizationModes = [2,16,4,8,0,0,0,0];
    // Discard results which have a low confidence score.
    runtimeSettings.minResultConfidence = 30;
    barcodeScanner.updateRuntimeSettings(runtimeSettings);

    let scanSettings = barcodeScanner.getScanSettings();
    // Disregard duplicated results found in a specified time period
    scanSettings.duplicateForgetTime = 20000;
    // Set a interval so that the CPU can relax
    scanSettings.intervalTime = 300;
    barcodeScanner.updateScanSettings(scanSettings);
    barcodeScanner.show();
})

Try in JSFiddle

As you can see in the code, there are basically three categories of configurations.

  • get/updateVideoSettings: Configures the data source, I.E., the video stream. These settings include which camera to use , the resolution, etc.. Check out more information here.
  • get/updateRuntimeSettings: Configures the decode engine. Find a full list of these settings and their corresponding descriptions here. Below lists the recommended settings for specific usage. Try in JSFiddle

    fast

    let settings = barcodeScanner.getRuntimeSettings();
    settings.localizationModes = [2, 0, 0, 0, 0, 0, 0, 0];
    settings.deblurLevel = 0;
    barcodeScanner.updateRuntimeSettings(settings);

    1D

    let settings = barcodeScanner.getRuntimeSettings();
    settings.localizationModes = [2, 4, 8, 0, 0, 0, 0, 0];
    settings.deblurLevel = 0;
    barcodeScanner.updateRuntimeSettings(settings);

    2D

    let settings = barcodeScanner.getRuntimeSettings();
    settings.localizationModes = [2, 4, 8, 0, 0, 0, 0, 0];
    settings.deblurLevel = 2;
    barcodeScanner.updateRuntimeSettings(settings);
  • get/updateScanSettings: Configures the scanner. For v7.0, the configurations for the scanner are limited to duplicateForgetTime and intervalTime.

Customizing the UI

While the library provides a built-in BarcodeScanner which has its own UI, you are free to use your own UI. Check out the following code on how it's done.

<!DOCTYPE html>
<html>
<body>
    <div id="div-video-container">
        <video class="dbrScanner-video" playsinline="true"></video>
    </div>
    <!--
        Warning: Use a specific version in production. (e.g. https://cdn.jsdelivr.net/npm/dynamsoft-javascript-barcode@x.x.x/dist/dbr.min.js)
        Please visit https://www.dynamsoft.com/CustomerPortal/Portal/TrialLicense.aspx to get trial license.
    -->
    <script src="https://cdn.jsdelivr.net/npm/dynamsoft-javascript-barcode@7/dist/dbr.min.js" data-productKeys="LICENSE-KEY"></script>
    <script>
        let barcodeScanner = null;
        Dynamsoft.BarcodeScanner.createInstance({
            UIElement: document.getElementById('div-video-container'),
            onFrameRead: results => {console.log(results);},
            onUnduplicatedRead: (txt, result) => {alert(txt);}
        }).then(scanner => {
            barcodeScanner = scanner;
            barcodeScanner.show();
        });
    </script>
</body>
</html>

Try in JSFiddle

The code has specified the UIElement with the ID div-video-container as the data source element and has put a video element inside to show the camera video stream.

Important: The class name of the video element must be dbrScanner-video.

<video class="dbrScanner-video" playsinline="true"></video>

Next, you can add the camera list and resolution list.

If the class names match the default ones which are dbrScanner-sel-camera and dbrScanner-sel-resolution, the library will automatically populate the lists and handle the camera/resolution switching automatically.

<select class="dbrScanner-sel-camera"></select>

Try in JSFiddle

<select class="dbrScanner-sel-resolution"></select>

8 default resolutions will automatically show up.

Try in JSFiddle

Too many resolutions may be overwhelming for end users. Check out the following code on how to offer your own resolution options.

<select class="dbrScanner-sel-resolution">
    <option class="dbrScanner-opt-gotResolution" value="got"></option>
    <option data-width="1920" data-height="1080">1920 x 1080</option>
    <option data-width="1280" data-height="720">1280 x 720</option>
    <option data-width="640" data-height="480">640 x 480</option>
</select>

Possible Issue: Generally you need to provide a resolution that the camera supports. However, in case a camera does not support a specified resolution, it usually will just use the nearest supported resolution. As a result, the selected resolution may not be the actual resolution.

Resolution: To take care of this issue, you can add a option with the class name dbrScanner-opt-gotResolution (as shown above) which the library will then use to show the actual resolution being used.

Try in JSFiddle

Customizing Further

You may not want to use elements with the default class names to show the camera list or resolution list. In this case, you need to populate the two lists yourself.

For camera list, you can use the API getAllCameras() to get all available cameras and then populate them on the page.

<select id="custom-camera-list"></select>
let currentCamera = "";
let cameraList = document.getElementById("custom-camera-list");
barcodeScanner.show()
    .then(() => barcodeScanner.getCurrentCamera())
    .then(camera => {
        currentCamera = camera;
    })
    .then(() => barcodeScanner.getAllCameras())
    .then(allCameras => {
        cameraList.options.length = 0;
        for (let i = 0; i < allCameras.length; i++) {
            let camera = allCameras[i];
            cameraList.options.add(new Option(camera.label, camera.deviceId));
            if (camera.deviceId == currentCamera.deviceId)
                cameraList.selectedIndex = i;
        }
    });

Switch to the selected camera.

cameraList.onchange = () => {
    barcodeScanner.setCurrentCamera(cameraList.options[cameraList.selectedIndex].value);
};

Try in JSFiddle

If you have more than one camera and would like to use a certain one of them. Try out the code below.

barcodeScanner.show()
    .then(() => barcodeScanner.getAllCameras())
    .then(allCameras => {
        for (let camera of allCameras) {
            if (camera.label == 'Your-Camera-Name') {
                barcodeScanner.setCurrentCamera(camera.deviceId);
                break;
            }
        }
    });

Try in JSFiddle

For resolution list, you can show your preferred resolutions and use the API setResolution to set the selected option.

<select id="custom-camera-resolution">
    <option data-width="1920" data-height="1080">1920 x 1080</option>
    <option data-width="1280" data-height="720">1280 x 720</option>
    <option data-width="640" data-height="480">640 x 480</option>
</select>
let resolutionList = document.getElementById("custom-camera-resolution");
resolutionList.onchange = () => {
    barcodeScanner.setResolution(
        resolutionList.options[resolutionList.selectedIndex].getAttribute("data-width"),
        resolutionList.options[resolutionList.selectedIndex].getAttribute("data-height")
    );
};

Try in JSFiddle

Advanced Usage

Include the following in your code to print internal logs in the console.

Dynamsoft.BarcodeReader._onLog = console.log;

Show found barcodes

Try the following code to show found barcodes in input elements on the page

<input id="ipt-0">
<input id="ipt-1">
<input id="ipt-2">
let iptIndex = 0;
let barcodeScanner = null;
Dynamsoft.BarcodeScanner.createInstance({
    UIElement: document.getElementById('div-video-container'),
    onFrameRead: results => {console.log(results);},
    onUnduplicatedRead: (txt)=>{
        document.getElementById('ipt-' + iptIndex).value = txt;
        if(3 == ++iptIndex){
            barcodeScanner.onUnduplicatedRead = undefined;
            // Hide the scanner if you only need to read these three barcodes
            barcodeScanner.stop();
            barcodeScanner.hide();
        }
    }
}).then(scanner => {
    barcodeScanner = scanner;
    barcodeScanner.show();
});

Try in JSFiddle

Read a specific area/region

To speed up the scanning process, you can choose to scan only a specific area/region.

let settings = barcodeScanner.getRuntimeSettings();
/*
 * 1 means true
 * Using a percentage is easier
 * The following code ignores 25% to each side of the video stream
 */
settings.region.measuredByPercentage = 1;
settings.region.left = 25;
settings.region.top = 25;
settings.region.right = 75;
settings.region.bottom = 75;
barcodeScanner.updateRuntimeSettings(settings);

Try in JSFiddle

Custom Deployment

The library consists of several files. In the sample code above, we used it via a CDN which hosts all the necessary files. Most of the time using the CDN is enough. However, you may prefer to deploy the library on your own server in some cases. For example, in an environment without internet access. The following shows how it's done.

  • Step one: Place the files

Create a directory called dist on your server and put the following files in there.

Download zip to get these files.

  dbr-<version>.min.js
  dbr-<version>.wasm.min.js
  dbr-<version>.wasm
  dbr-<version>.wasm.withio.min.js
  dbr-<version>.withio.wasm
  dbr-<version>.esm.min.js

It's recommended to place all the files. If you want to place only the necessary ones, check out the following instructions.

  • web + document + UMD:

    dbr-<version>.min.js
    dbr-<version>.wasm.min.js
    dbr-<version>.wasm
  • web + worker + UMD:

    dbr-<version>.min.js
    dbr-<version>.wasm.withio.min.js
    dbr-<version>.withio.wasm
  • web + document + es6 module:

    dbr-<version>.min.esm.js
    dbr-<version>.wasm.min.js
    dbr-<version>.wasm
  • web + worker + es6 module:

    dbr-<version>.min.esm.js
    dbr-<version>.wasm.withio.min.js
    dbr-<version>.withio.wasm
  • nodejs + UMD:

    dbr-<version>.min.js
    dbr-<version>.wasm.withio.min.js
    dbr-<version>.withio.wasm
  • Step two: Configure the server

    Make sure that your webserver serves the *.wasm file with Content-Type: application/wasm . Otherwise the browser won't be able to recognize it.

    Basically, all you need to do is set the MIME type for .wasm to application/wasm.

    Different servers are configured differently, below lists a few popular ones

Changelog

7.1.0

Updated algorithm to 7.1.

Improved the speed to download, build and initialize the library.

Improved the readability of barcode result text by using UTF-8 encoding.

Improved developer’s guide to be clearer and more precise.

Renamed setScanSettings for updateScanSettings for naming consistence.

7.0.0

Built Dynamsoft Barcode Reader 7.0 to JS(WebAssembly) version.

Added the capability to enable/disable the torch/flashlight of a mobile device (when available, only Chrome on Android).

Added APIs for finer video control. These APIs are getAllCameras, getCurrentCamera, setCurrentCamera, getResolution, setResolution.

6.5.2.1

Improve video decoding capabilities.

6.5.2

Built Dynamsoft Barcode Reader 6.5.2 to JS(WebAssembly) version.

Walkaround for certain scenarios of Content Security Policy (CSP).

Add a setting can turn off the feature of using IndexedDB.

6.5.1

Added video view for barcode scan. Compatible with Node.js.

6.4.1.3

The dbr-6.4.1.3.wasm size is now reduced to 3.41M.

6.4.1.1

Fixed a memory leak related to mTimeout in RuntimeSettings.

6.4.1.0

Built Dynamsoft Barcode Reader 6.4.1 to JS(WebAssembly) version.

Combined the normal and the mobile version into one.

6.3.0.2

Added built-in Worker support.

6.3.0.1

Set dbr-<version>.js(stable) as the main branch.

Added dbr-<version>.mobile.js(smaller, compiles quicker, requires less memory, but not as stable) for mobile Safari.

6.3.0

Dynamsoft Barcode Reader JS/WebAssembly version released.

API Documentation

Decoding Images:

BarcodeReader

Decoding Video Stream:

BarcodeScanner

License Activation

It takes several steps to activate a purchased license, the following steps assume you have already acquired a commercial license from Dynamsoft. If you haven't done so, you can purchase here.

  • Step One : Create a Dynamsoft Account

    If you don't have a Dynamsoft Account yet, sign up here.

  • Step Two : Log into Dynamsoft Customer Portal

    Once logged in, click Barcode Reader SDK on the menu bar on the left under License Center and you should be able to see your purchased key on the right pane.

  • Step Three : Activate the License

    Under Status, click the link Activate Now where you will be asked to input a domain which your license key will be bound to. The domain binding is a security feature to protect your license, although it's optional, it's highly recommended.

    A few examples of the domain:

    www.dynamsoft.com

    demo.dynamsoft.com

    *.dynamsoft.com

    *.dynamsoft.com; *.yoursite.com

  • Step Four : Use the License

    You may have noticed that in all the samples above, we have the following line of code

    <script src="https://cdn.jsdelivr.net/npm/dynamsoft-javascript-barcode@7/dist/dbr.min.js" data-productKeys="LICENSE-KEY"></script>

    To use your license, you simply need to replace LICENSE-KEY with it.

License Agreement

https://www.dynamsoft.com/Products/barcode-reader-license-agreement.aspx#javascript

Contact Us

If there are any questions, please feel free to contact support@dynamsoft.com.

Generated using TypeDoc