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.

<a name="browser-support">Browser Support</a>

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 |

<a name="installing">Installing</a>

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="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.

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

<a name="gettingstarted">Getting Started</a>

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

<a name="usingwithreact">Using with React</a>

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

<a name="usingwithexternalreaders">Using with External Readers</a>

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']
    }
});

<a name="Building">Building</a>

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.

<a name="WorkingWithDev">Working with a development version from another project</a>

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 f