QuaggaJS is a barcode-scanner entirely written in JavaScript supporting real-time localization and decoding of
## What is QuaggaJS?
various types of barcodes such as __EAN__ and __CODE128__. 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](http://serratus.github.io/quaggaJS/examples) and check out the blog post
QuaggaJS is a barcode-scanner entirely written in JavaScript supporting real-
([How barcode-localization works in QuaggaJS](http://www.oberhofer.co/how-barcode-localization-works-in-quaggajs/))
time localization and decoding of various types of barcodes such as __EAN__,
__CODE128__ and __CODE39__. 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](http://serratus.github.io/quaggaJS/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.
if you want to dive deeper into this topic.
![teaser][teaser_left]![teaser][teaser_right]
![teaser][teaser_left]![teaser][teaser_right]
@ -17,63 +21,70 @@ if you want to dive deeper into this topic.
## Yet another barcode library?
## 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 is not yet another port of the great [zxing][zxing_github] library, but
This implementation features a barcode locator which is capable of finding a barcode-like pattern in an
more of an extension to it. This implementation features a barcode locator which
image resulting in an estimated bounding box including the rotation. Simply speaking, this reader is invariant
is capable of finding a barcode-like pattern in an image resulting in an
to scale and rotation, whereas other libraries require the barcode to be aligned with the viewport.
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.
## Requirements
## Requirements
In order to take full advantage of quaggaJS, the browser needs to support the `getUserMedia` API which is
In order to take full advantage of quaggaJS, the browser needs to support the
already implemented in recent versions of Firefox, Chrome and Opera. The API is also available on their
`getUserMedia` API which is already implemented in recent versions of Firefox,
mobile counterparts installed on Android. Safari and IE do not allow the access to the camera yet, neither
Chrome and Opera. The API is also available on their mobile counterparts
on desktop, nor on mobile. You can check [caniuse][caniuse_getusermedia] for updates.
installed on Android. Safari and IE do not allow the access to the camera yet,
neither on desktop, nor on mobile. You can check [caniuse][caniuse_getusermedia]
for updates.
In cases where real-time decoding is not needed, or the platform does not
support `getUserMedia` QuaggaJS is also capable of decoding image-files using
the File API or other URL sources.
In cases where real-time decoding is not needed, or the platform does not support `getUserMedia` QuaggaJS is
## Getting Started
also capable of decoding image-files using the File API or other URL sources.
## <aname="installation">Installation</a>
You can simply include `dist/quagga.min.js` in your project and you are ready
to go.
Just clone the repository and include `dist/quagga.js` in your project. You can also build the library yourself
If you want to keep your project modular, you can also install QuaggaJS via npm:
by simply typing:
```console
```console
> npm install
> npm install quagga
> grunt
```
```
### Minification
And then import it as dependency in your project:
```javascript
var quagga = require('quagga');
```
Currently, I strongly disapprove using `grunt uglify` since it does not handle asm.js code correctly
For starters, have a look at the [examples][github_examples] to get an idea
(see [issue](https://github.com/mishoo/UglifyJS2/issues/167)). The resulting code still works, but
where to go from here.
the performance might suffer, especially in Firefox. Additionally it triggers some ugly log-warnings
in the console.
This is how you create a minified version of quaggaJS (saved in `dist/quagga.min.js`):
## <aname="Building">Building</a>
You can build the library yourself by simply cloning the repo and typing:
```console
```console
> grunt uglify
> npm install
> grunt dist
```
```
Special care has to be taken if a minimized/uglified version of the code is needed. Basically the grunt task
This grunt task builds a non optimized version `quagga.js` and a minified
`grunt uglify` takes the `dist/quagga.js` as input and saves the minified code in `dist/quagga.min.js`.
version `quagga.min.js` and places both files in the `dist` folder.
Since the introduction of web-workers in quaggaJS, the filename of the script is important, because
the instantiation of the workers rely on it. This script-name defaults to `quagga.js` and can be changed
in the config with the key `config.scriptName`. The supplied string must match the filename of the
file being served by the webserver. Now, in the case of a minified version, the config must be adapted
so that `config.scriptName` points to `quagga.min.js`.
See the [config](#configobject) for all supported options.
## Usage
## API
You can check out the [examples](http://serratus.github.io/quaggaJS/examples) to get an idea of how to use QuaggaJS.
You can check out the [examples][github_examples] to get an idea of how to
Basically the library exposes the following API:
use QuaggaJS. Basically the library exposes the following API:
### Quagga.init(config, callback)
### Quagga.init(config, callback)
This method initializes the library for a given configuration `config` (see below) and invokes the `callback` when Quagga is ready to start. The initialization process also requests for camera access if real-time detection is configured.
This method initializes the library for a given configuration `config` (see
below) and invokes the `callback` when Quagga is ready to start. The
initialization process also requests for camera access if real-time detection is
configured.
```javascript
```javascript
Quagga.init({
Quagga.init({
@ -92,31 +103,41 @@ Quagga.init({
### Quagga.start()
### Quagga.start()
When the library is initialized, the `start()` method starts the video-stream and begins locating and decoding
When the library is initialized, the `start()` method starts the video-stream
the images.
and begins locating and decoding the images.
### Quagga.stop()
### 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.
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)
### 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.
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)
### Quagga.onDetected(callback)
Registers a `callback(data)` function which is triggered whenever a barcode-pattern has been located and decoded
Registers a `callback(data)` function which is triggered whenever a barcode-
successfully. The passed `data` object contains information about the decoding process including the detected code which can be obtained by calling `data.codeResult.code`.
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)
### Quagga.decodeSingle(config, callback)
In contrast to the calls described above, this method does not rely on`getUserMedia` and operates on a
In contrast to the calls described above, this method does not rely on
single image instead. The provided callback is the same as in `onDetected` and contains the result `data`
`getUserMedia` and operates on a single image instead. The provided callback
object.
is the same as in `onDetected` and contains the result `data`object.
## <aname="resultobject">The result object</a>
## <aname="resultobject">The result object</a>
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.
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.
```javascript
```javascript
{
{
@ -202,7 +223,6 @@ The default `config` object is set as followed:
controls: false,
controls: false,
locate: true,
locate: true,
numOfWorkers: 4,
numOfWorkers: 4,
scriptName: 'quagga.js',
visual: {
visual: {
show: true
show: true
},
},
@ -235,8 +255,9 @@ The default `config` object is set as followed:
## Examples
## Examples
The following example takes an image `src` as input and prints the result on the console.
The following example takes an image `src` as input and prints the result on the
The decoder is configured to detect _Code128_ barcodes and enables the locating-mechanism for more robust results.
console. The decoder is configured to detect _Code128_ barcodes and enables the
locating-mechanism for more robust results.
```javascript
```javascript
Quagga.decodeSingle({
Quagga.decodeSingle({
@ -250,7 +271,9 @@ Quagga.decodeSingle({
## Tests
## Tests
Unit Tests can be run with [Karma][karmaUrl] and written using [Mocha][mochaUrl], [Chai][chaiUrl] and [SinonJS][sinonUrl]. Coverage reports are automatically generated in the coverage/ folder.
Unit Tests can be run with [Karma][karmaUrl] and written using
[Mocha][mochaUrl], [Chai][chaiUrl] and [SinonJS][sinonUrl]. Coverage reports are
automatically generated in the coverage/ folder.
```console
```console
> npm install
> npm install
@ -258,10 +281,21 @@ Unit Tests can be run with [Karma][karmaUrl] and written using [Mocha][mochaUrl]
```
```
## Image Debugging
## Image Debugging
In case you want to take a deeper dive into the inner workings of Quagga, get to know the _debugging_ capabilities of the current implementation. The various flags exposed through the `config` object give you the abilily to visualize almost every step in the processing. Because of the introduction of the web-workers, and their restriction not to have access to the DOM, the configuration must be explicitly set to `config.numOfWorkers = 0` in order to work.
In case you want to take a deeper dive into the inner workings of Quagga, get to
know the _debugging_ capabilities of the current implementation. The various
flags exposed through the `config` object give you the abilily to visualize
almost every step in the processing. Because of the introduction of the
web-workers, and their restriction not to have access to the DOM, the
configuration must be explicitly set to `config.numOfWorkers = 0` in order to
work.
## <aname="changelog">Changelog</a>
## <aname="changelog">Changelog</a>
### 2015-03-16
- Improvements
- now includes minified version (23.3KB gzipped)
- No need for configuration of script-name any more
### 2015-03-12
### 2015-03-12
- Improvements
- Improvements
- removed dependency on async.js
- removed dependency on async.js
@ -272,16 +306,24 @@ In case you want to take a deeper dive into the inner workings of Quagga, get to
### 2015-01-21
### 2015-01-21
- Features
- Features
- Added support for web-worker (using 4 workers as default, can be changed through `config.numOfWorkers`)
- Added support for web-worker (using 4 workers as default, can be changed
- Due to the way how web-workers are created, the name of the script file (`config.scriptName`) should be kept in sync with your actual filename
through `config.numOfWorkers`)
- Removed canvas-overlay for decoding (boxes & scanline) which can now be easily implemented using the existing API (see example)
- Due to the way how web-workers are created, the name of the script file
(`config.scriptName`) should be kept in sync with your actual filename
- Removed canvas-overlay for decoding (boxes & scanline) which can now be
easily implemented using the existing API (see example)
- API Changes
- API Changes
In the course of implementing web-workers some breaking changes were introduced to the API.
In the course of implementing web-workers some breaking changes were
- The `Quagga.init` function no longer receives the callback as part of the config but rather as a second argument: `Quagga.init(config, cb)`
introduced to the API.
- The callback to `Quagga.onDetected` now receives an object containing much more information in addition to the decoded code. (see [data](#resultobject))
- The `Quagga.init` function no longer receives the callback as part of the
- Added `Quagga.onProcessed(callback)` which provides a way to get information for each image processed.
config but rather as a second argument: `Quagga.init(config, cb)`
The callback receives the same `data` object as `Quagga.onDetected` does. Depending on the success of the process the `data` object
- The callback to `Quagga.onDetected` now receives an object containing
might not contain any `resultCode` and/or `box` properties.
much more information in addition to the decoded code.(see
[data](#resultobject))
- Added `Quagga.onProcessed(callback)` which provides a way to get information
for each image processed. The callback receives the same `data` object as
`Quagga.onDetected` does. Depending on the success of the process the `data`
object might not contain any `resultCode` and/or `box` properties.
Christoph Oberhofer
10 years ago