This package polyfills the Barcode Detection API for browsers, using a WebAssembly build of the ZBar Bar Code Reader that is written in C/C++. It offers the following features:
- Polyfills the BarcodeDetector class
- Supports these barcode formats:
codabar
,code_39
,code_93
,code_128
,databar
,databar_exp
,ean_2
,ean_5
,ean_8
,ean_13
,ean_13+2
,ean_13+5
,isbn_10
,isbn_13
,isbn_13+2
,isbn_13+5
,itf
,qr_code
,sq_code
,upc_a
,upc_e
- Not supported:
aztec
,data_matrix
,pdf417
- Scans
<img>
,<canvas>
and live<video>
elements, image and videoBlob
s andFile
s and more - Detects multiple barcodes per frame, also with different types
- Barcodes may be oriented horizontally or vertically
- Outperforms pure JavaScript polyfills
An online example is available on GitHub (source code with build scripts for Rollup and esbuild) and on CodePen.
Install:
$ npm install @undecaf/barcode-detector-polyfill
or
$ yarn add @undecaf/barcode-detector-polyfill
Make the polyfill available if necessary:
import { BarcodeDetectorPolyfill } from '@undecaf/barcode-detector-polyfill'
try {
window['BarcodeDetector'].getSupportedFormats()
} catch {
window['BarcodeDetector'] = BarcodeDetectorPolyfill
}
⁝
Expose the BarcodeDetectorPolyfill
API in variable barcodeDetectorPolyfill
:
<script src="https://cdn.jsdelivr.net/npm/@undecaf/zbar-wasm@0.9.15/dist/index.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@undecaf/barcode-detector-polyfill@0.9.21/dist/index.js"></script>
<script>
try {
window['BarcodeDetector'].getSupportedFormats()
} catch {
window['BarcodeDetector'] = barcodeDetectorPolyfill.BarcodeDetectorPolyfill
}
⁝
</script>
const formats = await BarcodeDetector.getSupportedFormats()
const detector = new BarcodeDetector({ formats: ['code_39', 'code_128', 'ean_13'] })
If formats
is omitted then all supported formats will be detected.
Where applicable (e.g. format 'qr_code'
), text is assumed to be UTF-8 encoded. As an extension to the
BarcodeDetector
API, a different encoding can be set for the BarcodeDetectorPolyfill
:
const detector = new BarcodeDetectorPolyfill({
formats: ['qr_code'],
zbar: {
encoding: 'iso-8859-15'
}
})
encoding
may be any of the Encoding API encodings.
const barcodes = await detector.detect(source)
source
must be an object of which an ImageBitmap
can be obtained, or else a
TypeError
will be thrown:
- an
<img>
element (HTMLImageElement
) - a
<video>
element (HTMLVideoElement
) from which a single frame will be taken - a
<canvas>
element (HTMLCanvasElement
) - an
ImageBitmap
- an
ImageData
instance - a
CanvasRenderingContext2D
- a
Blob
or aFile
with a contenttype
ofimage/*
In addition, any object with a zero width
or height
property will be tolerated.
The detector processes the source
in natural size, making detection results independent of the size rendered
by the browser.
Detected barcodes are stored as an array of objects in barcodes
since source
may contain multiple barcodes.
Each object has the following properties
(see here for details):
-
format
: the detected barcode format (one of the formats specified as constructor options) -
rawValue
: the decoded barcode, always astring
decoded from raw data as specified -
boundingBox
: theDOMRectReadOnly
enclosing the barcode in thesource
-
cornerPoints
: an arry of four{x, y}
pairs in clockwise order, representing four corner points of the detected barcode.BarcodeDetectorPolyfill
returns theboundingBox
corner points.
Additional properties provided only by BarcodeDetectorPolyfill
:
-
orientation
:0
→ image is upright,1
→ rotated 90° clockwise,2
→ upside down,3
→ rotated 90° counterclockwise,-1
→ unknown -
quality
: a positive integer indicating the barcode quality as seen by the detector, specific to eachformat
If an error occurs during barcode detection then the detect()
method returns a rejected
Promise
containing the error.
Type definitions for BarcodeDetectorPolyfill
, for constructor and method parameter types and for result types
are provided in @undecaf/barcode-detector-polyfill/dist/main.d.ts
.
This package
is under the MIT license although it depends on @undecaf/zbar-wasm
which is under LGPL.
Nevertheless, @undecaf/zbar-wasm
may be bundled in your project as this does not violate the LGPL requirements.
Module @undecaf/zbar-wasm
, however, expects the WASM file zbar.wasm
to be located at the same path as itself;
details can be found in the documentation of @undecaf/zbar-wasm
.
Therefore, bundlers must be configured accordingly. Configuration examples for Rollup and esbuild
can be found in directory example-bundled
.
They were used to bundle the JavaScript code for this online example
in docs/example-bundled
.
In order to comply with the LGPL,
@undecaf/zbar-wasm
must not be bundled but may only be loaded as a library at runtime.@undecaf/zbar-wasm
can also be loaded at runtime, by default from https://cdn.jsdelivr.net
. It can also be fetched from
a different endpoint if desired.
Bundlers must be configured so that they treat @undecaf/zbar-wasm
as an external dependency instead of trying to resolve it.
Configuration examples for Rollup and esbuild
can be found in directory example-loaded
.
They were used to bundle the JavaScript code for this online example
in docs/example-loaded
.
They also illustrate how to load @undecaf/zbar-wasm
from a non-default endpoint.
-
lekoala for his
barcode-detector-zbar
that has an extensive list of useful links - the makers of Rollup and esbuild for their bundlers which I consider a pleasure to work with
I, the author of this document, have compiled it to the best of my knowledge, but it still expresses my personal opinion. Therefore, in addition to what the licenses mentioned below state, I hereby decline any liability for any false, inaccurate, inappropriate or incomplete information that may be presented here.
Software: MIT
Documentation: CC-BY-SA 4.0