quaggaJS

• Changelog (2017-06-07)
• Browser Support
• Installing
• Getting Started
• API
• Configuration
• Tips & Tricks
• Sponsors

What is QuaggaJS?

QuaggaJS is a barcode-scanner entirely written in JavaScript supporting real- time localization and decoding of various types of barcodes such as EAN, CODE 128, CODE 39, EAN 8, UPC-A, UPC-C, I2of5, 2of5, CODE 93 and CODABAR. The library is also capable of using getUserMedia to get direct access to the user's camera stream. Although the code relies on heavy image-processing even recent smartphones are capable of locating and decoding barcodes in real-time.

Try some examples and check out the blog post ([How barcode-localization works in QuaggaJS][oberhofer_co_how]) if you want to dive deeper into this topic.

![teaser][teaser_left]![teaser][teaser_right]

Yet another barcode library?

This is not yet another port of the great [zxing][zxing_github] library, but more of an extension to it. This implementation features a barcode locator which is capable of finding a barcode-like pattern in an image resulting in an estimated bounding box including the rotation. Simply speaking, this reader is invariant to scale and rotation, whereas other libraries require the barcode to be aligned with the viewport.

Browser Support

Quagga makes use of many modern Web-APIs which are not implemented by all browsers yet. There are two modes in which Quagga operates: 1. analyzing static images and 2. using a camera to decode the images from a live-stream. The latter requires the presence of the MediaDevices API. You can track the compatibility of the used Web-APIs for each mode:

• Static Images
• Live Stream

Static Images

The following APIs need to be implemented in your browser: - webworkers - canvas - typedarrays - bloburls - blobbuilder

Live Stream

In addition to the APIs mentioned above: - MediaDevices

Important: Accessing getUserMedia requires a secure origin in most browsers, meaning that http:// can only be used on localhost. All other hostnames need to be served via https://. You can find more information in the Chrome M47 WebRTC Release Notes.

Feature-detection of getUserMedia

Every browser seems to differently implement the mediaDevices.getUserMedia API. Therefore it's highly recommended to include webrtc-adapter in your project.

Here's how you can test your browser's capabilities:

if (navigator.mediaDevices && typeof navigator.mediaDevices.getUserMedia === 'function') {
  // safely access `navigator.mediaDevices.getUserMedia`
}

The above condition evaluates to:

Installing

QuaggaJS can be installed using npm, bower, or by including it with the script tag.

NPM

> npm install quagga

And then import it as dependency in your project:

import Quagga from 'quagga'; // ES6
const Quagga = require('quagga').default; // Common JS (important: default)

Currently, the full functionality is only available through the browser. When using QuaggaJS within node, only file-based decoding is available. See the example for node_examples.

Bower

You can also install QuaggaJS through bower:

> bower install quagga

Script-Tag Anno 1998

You can simply include dist/quagga.min.js in your project and you are ready to go. The script exposes the library on the global namespace under Quagga.

Getting Started

For starters, have a look at the [examples][github_examples] to get an idea where to go from here.

Building

You can build the library yourself by simply cloning the repo and typing:

> npm install
> npm run build

This npm script builds a non optimized version quagga.js and a minified version quagga.min.js and places both files in the dist folder. Additionally, a quagga.map source-map is placed alongside these files. This file is only valid for the non-uglified version quagga.js because the minified version is altered after compression and does not align with the map file any more.

Node

The code in the dist folder is only targeted to the browser and won't work in node due to the dependency on the DOM. For the use in node, the build command also creates a quagga.js file in the lib folder.

API

You can check out the [examples][github_examples] to get an idea of how to use QuaggaJS. Basically the library exposes the following API:

Quagga.init(config, callback)

This method initializes the library for a given configuration config (see below) and invokes the callback(err) when Quagga has finished its bootstrapping phase. The initialization process also requests for camera access if real-time detection is configured. In case of an error, the err parameter is set and contains information about the cause. A potential cause may be the inputStream.type is set to LiveStream, but the browser does not support this API, or simply if the user denies the permission to use the camera.

If you do not specify a target, QuaggaJS would look for an element that matches the CSS selector #interactive.viewport (for backwards compatibility). target can be a string (CSS selector matching one of your DOM node) or a DOM node.

Quagga.init({
    inputStream : {
      name : "Live",
      type : "LiveStream",
      target: document.querySelector('#yourElement')    // Or '#yourElement' (optional)
    },
    decoder : {
      readers : ["code_128_reader"]
    }
  }, function(err) {
      if (err) {
          console.log(err);
          return
      }
      console.log("Initialization finished. Ready to start");
      Quagga.start();
  });

Quagga.start()

When the library is initialized, the start() method starts the video-stream and begins locating and decoding the images.

Quagga.stop()

If the decoder is currently running, after calling stop() the decoder does not process any more images. Additionally, if a camera-stream was requested upon initialization, this operation also disconnects the camera.

Quagga.onProcessed(callback)

This method registers a callback(data) function that is called for each frame after the processing is done. The data object contains detailed information about the success/failure of the operation. The output varies, depending whether the detection and/or decoding were successful or not.

Quagga.onDetected(callback)

Registers a callback(data) function which is triggered whenever a barcode- pattern has been located and decoded successfully. The passed data object contains information about the decoding process including the detected code which can be obtained by calling data.codeResult.code.

Quagga.decodeSingle(config, callback)

In contrast to the calls described above, this method does not rely on getUserMedia and operates on a single image instead. The provided callback is the same as in onDetected and contains the result data object.

Quagga.offProcessed(handler)

In case the onProcessed event is no longer relevant, offProcessed removes the given handler from the event-queue.

Quagga.offDetected(handler)

In case the onDetected event is no longer relevant, offDetected removes the given handler from the event-queue.

The result object

The callbacks passed into onProcessed, onDetected and decodeSingle receive a data object upon execution. The data object contains the following information. Depending on the success, some fields may be undefined or just empty.

{
  "codeResult": {
    "code": "FANAVF1461710",  // the decoded code as a string
    "format": "code_128", // or code_39, codabar, ean_13, ean_8, upc_a, upc_e
    "start": 355,
    "end": 26,
    "codeset": 100,
    "startInfo": {
      "error": 1.0000000000000002,
      "code": 104,
      "start": 21,
      "end": 41
    },
    "decodedCodes": [{
      "code": 104,
      "start": 21,
      "end": 41
    },
    // stripped for brevity
    {
      "error": 0.8888888888888893,
      "code": 106,
      "start": 328,
      "end": 350
    }],
    "endInfo": {
      "error": 0.8888888888888893,
      "code": 106,
      "start": 328,
      "end": 350
    },
    "direction": -1
  },
  "line": [{
    "x": 25.97278706156836,
    "y": 360.5616435369468
  }, {
    "x": 401.9220519377024,
    "y": 70.87524989906444
  }],
  "angle": -0.6565217179979483,
  "pattern": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, /* ... */ 1],
  "box": [
    [77.4074243622672, 410.9288668804402],
    [0.050203235235130705, 310.53619724086366],
    [360.15706727788256, 33.05711026051813],
    [437.5142884049146, 133.44977990009465]
  ],
  "boxes": [
    [
      [77.4074243622672, 410.9288668804402],
      [0.050203235235130705, 310.53619724086366],
      [360.15706727788256, 33.05711026051813],
      [437.5142884049146, 133.44977990009465]
    ],
    [
      [248.90769330706507, 415.2041489551161],
      [198.9532321622869, 352.62160512937635],
      [339.546160777576, 240.3979259789976],
      [389.5006219223542, 302.98046980473737]
    ]
  ]
}

Configuration

The configuration that ships with QuaggaJS covers the default use-cases and can be fine-tuned for specific requirements.

The configuration is managed by the config object defining the following high-level properties:

{
  numOfWorkers: 4,
  locate: true,
  inputStream: {...},
  frequency: 10,
  decoder:{...},
  locator: {...},
  debug: false,
}

numOfWorkers

QuaggaJS supports web-workers out of the box and runs with 4 workers in its default configuration. The number should align with the number of cores available in your targeted devices.

In case you don't know the number upfront, or if the variety of devices is too big, you can either use navigator.hardwareConcurrency (see here) where available or make use of core-estimator.

locate

One of the main features of QuaggaJS is its ability to locate a barcode in a given image. The locate property controls whether this feature is turned on (default) or off.

Why would someone turn this feature off? Localizing a barcode is a computationally expensive operation and might not work properly on some devices. Another reason would be the lack of auto-focus producing blurry images which makes the localization feature very unstable.

However, even if none of the above apply, there is one more case where it might be useful to disable locate: If the orientation, and/or the approximate position of the barcode is known, or if you want to guide the user through a rectangular outline. This can increase performance and robustness at the same time.

inputStream

The inputStream property defines the sources of images/videos within QuaggaJS.

{
  name: "Live",
  type: "LiveStream",
  constraints: {
    width: 640,
    height: 480,
    facingMode: "environment",
    deviceId: "7832475934759384534"
  },
  area: { // defines rectangle of the detection/localization area
    top: "0%",    // top offset
    right: "0%",  // right offset
    left: "0%",   // left offset
    bottom: "0%"  // bottom offset
  },
  singleChannel: false // true: only the red color-channel is read
}

First, the type property can be set to three different values: ImageStream, VideoStream, or LiveStream (default) and should be selected depending on the use-case. Most probably, the default value is sufficient.

Second, the constraint key defines the physical dimensions of the input image and additional properties, such as facingMode which sets the source of the user's camera in case of multiple attached devices. Additionally, if required, the deviceId can be set if the selection of the camera is given to the user. This can be easily achieved via [MediaDevices.enumerateDevices()][enumerateDevices]

Thirdly, the area prop restricts the decoding area of the image. The values are given in percentage, similar to the CSS style property when using position: absolute. This area is also useful in cases the locate property is set to false, defining the rectangle for the user.

The last key singleChannel is only relevant in cases someone wants to debug erroneous behavior of the decoder. If set to true the input image's red color-channel is read instead of calculating the gray-scale values of the source's RGB. This is useful in combination with the ResultCollector where the gray-scale representations of the wrongly identified images are saved.

frequency

This top-level property controls the scan-frequency of the video-stream. It's optional and defines the maximum number of scans per second. This renders useful for cases where the scan-session is long-running and resources such as CPU