quagga2

This is a fork of the original QuaggaJS library, that will be maintained until such time as the original author and maintainer returns, or it has been completely replaced by built-in browser and node functionality.

📚 Documentation

Complete Documentation - Tutorials, guides, API reference, and more (UNDER CONSTRUCTION!!!)

Quick links from this README:

• Changelog
• Browser Support
• Installing
• Getting Started
• Using with React
• Using External Readers
• API
• CameraAccess API
• Configuration
• Tips & Tricks

Using React / Redux?

Please see also https://github.com/ericblade/quagga2-react-example/ and https://github.com/ericblade/quagga2-redux-middleware/. For live browser examples, see docs/examples/.

Using Angular?

Please see https://github.com/julienboulay/ngx-barcode-scanner or https://github.com/classycodeoss/mobile-scanning-demo

Using ThingWorx?

Please see https://github.com/ptc-iot-sharing/ThingworxBarcodeScannerWidget

Using Vue?

• Vue 2: https://github.com/DevinNorgarb/vue-quagga-2
• Vue 3: https://github.com/nick-0101/vue3-quagga-2

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, CODE 32, CODABAR, and PHARMACODE. 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:

• 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:

Browser	result
Edge	true
Chrome	true
Firefox	true
IE 11	false
Safari iOS	true

Installing

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

NPM

> npm install --save @ericblade/quagga2

And then import it as dependency in your project:

import Quagga from '@ericblade/quagga2'; // ES6
const Quagga = require('@ericblade/quagga2').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.

Using with script tag

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

<script src="https://github.com/ericblade/quagga2/raw/1.12.1/quagga.js"></script>

You can get the quagga.js file in the following ways:

By installing the npm module and copying the quagga.js file from the dist folder.

(OR)

You can also build the library yourself and copy quagga.js file from the dist folder(refer to the building section for more details)

(OR)

You can include the following script tags with CDN links:

a) quagga.js

<script src="https://cdn.jsdelivr.net/npm/@ericblade/quagga2/dist/quagga.js"></script>

b) quagga.min.js (minified version)

<script src="https://cdn.jsdelivr.net/npm/@ericblade/quagga2/dist/quagga.min.js"></script>

Note: You can include a specific version of the library by including the version as shown below.

<script src="https://cdn.jsdelivr.net/npm/@ericblade/quagga2@1.2.6/dist/quagga.js"></script>

Getting Started

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

Using with React

There is a separate [example][reactExample] for using quagga2 with ReactJS

Using with External Readers

New in Quagga2 is the ability to specify external reader modules. Please see quagga2-reader-qr. This repository includes a sample external reader that can read complete images, and decode QR codes. A test script is included to demonstrate how to use an external reader in your project.

Quagga2 exports the BarcodeReader prototype, which should also allow you to create new barcode reader implementations using the base BarcodeReader implementation inside Quagga2. The QR reader does not make use of this functionality, as QR is not picked up as a barcode in BarcodeReader.

External Reader Priority

External readers follow the same priority rules as built-in readers. Once registered with Quagga.registerReader(), an external reader can be placed anywhere in the readers array, and its position determines when it attempts to decode relative to other readers.

// Register external reader first
Quagga.registerReader('my_custom_reader', MyCustomReader);

// Use in config - position determines priority
Quagga.init({
    decoder: {
        // External reader tried first, then built-in readers
        readers: ['my_custom_reader', 'ean_reader', 'code_128_reader']
    }
});

Building

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

> npm install
> npm run build

or using Docker:

> docker build --tag quagga2/build .
> docker run -v $(pwd):/quagga2 quagga2/build npm install
> docker run -v $(pwd):/quagga2 quagga2/build npm run build

it's also possible to use docker-compose:

> docker-compose run nodejs npm install
> docker-compose run nodejs npm run build

Note: when using Docker or docker-compose the build artifacts will end up in dist/ as usual thanks to the bind-mount.

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.

Working with a development version from another project

If you are working on a project that includes quagga, but you need to use a development version of quagga, then you can run from the quagga directory:

npm install && npm run build && npm link

then from the other project directory that needs this quagga, do

npm link @ericblade/quagga2

When linking is successful, all future runs of 'npm run build' will update the version that is linked in the project. When combined with an application using webpack-dev-server or some other hot-reload system, you can do very rapid iteration this way.

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.

Important: decodeSingle has a built-in default of inputStream.size: 800. This means images are automatically scaled to 800px on their longest side (both larger images scaled down AND smaller images scaled up). The box, boxes, and line coordinates in the result are returned in this scaled coordinate space, not the original image dimensions. To disable scaling and use original dimensions, set inputStream.size to 0.

Quagga.offProcessed(handler)

In case the onProcessed event is no longer relevant, offProcessed removes the given handler from the event-queue. When no handler is passed, all handlers are removed.

Quagga.offDetected(handler)

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