This project was forked from ZBar.wasm, a WebAssembly build of the ZBar Bar Code Reader written in C/C++.
- Provided as minified ES module, CommonJS module and plain script
- Runs in modern browsers, in Node.js and also in workers
- Deployment size approx. 330 kByte
- Supports Code-39, Code-93, Code-128, Codabar, Databar/Expanded, EAN/GTIN-5/8/13, ISBN-10/13, ISBN-13+2, ISBN-13+5, ITF (Interleaved 2 of 5), QR Code, UPC-A/E.
- Detects multiple barcodes per frame, also with different types
- Barcodes may be oriented horizontally or vertically
- Scans
ImageData
and RGB/grayscaleArrayBuffer
objects - Outperforms pure JavaScript barcode scanners
-
A simple example: on GitHub (source code), on CodePen
-
A polyfill for the
BarcodeDetector
Web API: on GitHub (source code with build scripts for Rollup and esbuild), on CodePen
An example that scans a static image file:
<!DOCTYPE html>
<html>
<body>
<img id="img" crossorigin="anonymous" src="https://raw.githubusercontent.com/undecaf/zbar-wasm/master/tests/img/qr_code.png">
<pre id="result"></pre>
<script type="module">
import * as zbarWasm from 'https://cdn.jsdelivr.net/npm/@undecaf/[email protected]/dist/index.js'
(async () => {
const
img = document.getElementById('img'),
result = document.getElementById('result'),
canvas = document.createElement('canvas'),
context = canvas.getContext('2d');
await img.decode()
canvas.width = img.naturalWidth
canvas.height = img.naturalHeight
context.drawImage(img, 0, 0)
const
imageData = context.getImageData(0, 0, canvas.width, canvas.height),
symbols = await zbarWasm.scanImageData(imageData);
symbols.forEach(s => s.rawData = s.decode())
result.innerText = JSON.stringify(symbols, null, 2)
})()
</script>
</body>
</html>
Almost identical to the snippet above, just replace the lines
⁝
<script type="module">
import * as zbarWasm from 'https://cdn.jsdelivr.net/npm/@undecaf/[email protected]/dist/index.js'
⁝
with
⁝
<script src="https://cdn.jsdelivr.net/npm/@undecaf/[email protected]/dist/index.js"></script>
<script>
⁝
Installing:
$ npm install @undecaf/[email protected]
or
$ yarn add @undecaf/[email protected]
Using:
import ... from '@undecaf/zbar-wasm'
pulls the ES module from the package,
require('@undecaf/zbar-wasm')
pulls the CommonJS module.
Please refer to the API documentation for what can be imported/required.
A simple ES module that scans a static image file:
import { createCanvas, loadImage } from 'canvas';
import { scanImageData } from '@undecaf/zbar-wasm';
(async (url) => {
const
img = await loadImage(url),
canvas = createCanvas(img.width, img.height),
ctx = canvas.getContext('2d');
ctx.drawImage(img, 0, 0)
const
imageData = ctx.getImageData(0, 0, img.width, img.height),
symbols = await scanImageData(imageData);
console.log(symbols[0]?.typeName, symbols[0]?.decode())
})('https://raw.githubusercontent.com/undecaf/zbar-wasm/master/tests/img/qr_code.png')
For a CommonJS module, just replace the first lines with
const { createCanvas, loadImage } = require('canvas');
const { scanImageData } = require('@undecaf/zbar-wasm');
Barcode scanning is always delegated to the WebAssembly code in file zbar.wasm
.
zbar-wasm provides various functionally equivalent ESM and CommonJS modules for Node.js and for browsers
that differ in how zbar.wasm
is to be provided at runtime:
zbar.wasm
can be loaded from a CDN by browsers.zbar.wasm
can be bundled as an asset. That asset should be served to browsers asapplication/wasm
so that it can be compiled in parallel with being received.- Several zbar-wasm modules contain
zbar.wasm
as inline data.
The following overview shows the modules that are available in zbar-wasm. One of them needs to be bundled in your application.
Path in package | Module type | Node core modules polyfilled (suitable for browsers) |
zbar.wasm inlined |
---|---|---|---|
/dist/index.mjs |
ESM | ✔️ | |
/dist/index.js |
CommonJS | ✔️ | |
/dist/main.mjs |
ESM | ||
/dist/main.cjs |
CommonJS | ||
/dist/inlined/index.mjs |
ESM | ✔️ | ✔️ |
/dist/inlined/index.js |
CommonJS | ✔️ | ✔️ |
/dist/inlined/main.mjs |
ESM | ✔️ | |
/dist/inlined/main.cjs |
CommonJS | ✔️ |
The package entry points of zbar-wasm have been chosen so that bundlers will emit the
appropriate module by default in most cases. However, zbar.wasm
as inline data requires a suitable
export condition in the bundler configuration, typically 'zbar-inlined'
.
Please refer to the exports
section of package.json
for details.
Building zbar-wasm includes testing the bundling process with Webpack, Rollup and
esbuild and also testing the resulting bundles. The bundler configuration files
tests/{webpack,rollup,esbuild}.config.js
may be used as a reference of how to achieve a particular bundling result. Each of them covers
the following combinations of platforms, module types and zbar.wasm
provisioning for the
respective bundler:
zbar.wasm |
Node module types | Browser module types |
---|---|---|
loaded from CDN | ESM, plain <script> |
|
bundled as asset | ESM, CommonJS | ESM |
inlined in module | ESM, CommonJS | ESM, plain <script> |
As a last resort, if you cannot make your bundler place zbar.wasm
where it can be located by the script,
you can specify an URL or path for that WASM file at runtime:
import { scanImageData, setModuleArgs } from '@undecaf/zbar-wasm';
⁝
// Call this function once at the beginning
setModuleArgs({
/**
* This function must return the URL or path of the WASM file.
*
* @param filename default WASM filename ('zbar.wasm')
* @param directory default WASM directory (URL or directory of the current script)
* @returns {string} URL or path of the WASM file
*/
locateFile: (filename, directory) => {
return 'file:///your/wasm/directory/zbar.wasm'
}
});
⁝
// Then use the scanner
const symbols = await scanImageData(...);
Owing to the predecessor of this project, samsam2310/zbar.wasm, a wiki and an extensive API Reference are already available. Many thanks to the author!
Please note that a few classes have been renamed compared to the documentation in order to avoid conflicts with built-in JavaScript class names:
Symbol
→ZBarSymbol
Image
→ZBarImage
ImageScanner
→ZBarScanner
BarcodeDetector
Web API
The BarcodeDetector polyfill
package (in this repository, by the same author) is based on
zbar-wasm
but provides a standardized, higher-level and more flexible API.
Prerequisites:
- A Linux platform
- GNU
make
,tar
andcurl
- Podman or Docker
- Node.js v16+
- At least one of the browsers supported by TestCafé
To build:
- Clone this repository:
$ git clone https://github.com/undecaf/zbar-wasm $ cd zbar-wasm
- Enter your browser(s) in
.testcaferc.json
(supported browsers). - Enter two available port numbers in
tests/src/ports.js
. - If you prefer Docker over Podman as container engine then replace
with
EM_ENGINE = $(EM_PODMAN)
in the providedEM_ENGINE = $(EM_DOCKER)
Makefile
. - Run the build process:
The
$ make
make
command runs emscripten in a container, compiling the C/C++ sources of the ZBar Bar Code Reader to WebAssembly. It also compiles and bundles the TypeScript glue code and runs the tests in Node.js and in the selected browser(s) on the host machine.
- samsam2310 for providing invaluable information in his zbar.wasm repository
- mchehab for maintaining zbar
- the emscripten folks for their compiler toolchain
- the contributors to this package
Software: LGPL-2.1
Documentation: CC-BY-SA 4.0