A WebAssembly build of the ZBar Bar Code Reader
This project was forked from ZBar.wasm, a WebAssembly build of the ZBar Bar Code Reader written in C/C++.
Features
- 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
Examples based on zbar-wasm
-
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
Getting started
<script type="module">
Using zbar-wasm as 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/zbar-wasm@0.10.1/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>
<script>
Using zbar-wasm as plain Almost identical to the snippet above, just replace the lines
⁝
<script type="module">
import * as zbarWasm from 'https://cdn.jsdelivr.net/npm/@undecaf/zbar-wasm@0.10.1/dist/index.js'
⁝
with
⁝
<script src="https://cdn.jsdelivr.net/npm/@undecaf/zbar-wasm@0.10.1/dist/index.js"></script>
<script>
⁝
Using zbar-wasm as an ESM or CommonJS module in Node.js
Installing:
$ npm install @undecaf/zbar-wasm@0.10.1
or
$ yarn add @undecaf/zbar-wasm@0.10.1
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(ssymbols[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');
Bundling/deploying zbar-wasm
zbar-wasm provides ESM and CommonJS modules for Node.js and browsers. One of them needs to be
bundled in your application. In any case, barcode scanning is delegated to the WebAssembly code
in file zbar.wasm
. At runtime, this file can be provided in different ways depending on the
bundling configuration and on which zbar-wasm module was emitted by the bundler:
- It can be loaded from a CDN by browsers.
- It can be bundled as an asset. That asset should be served to browsers as
application/wasm
so that it can be compiled in parallel with being received. - Several zbar-wasm modules contain
zbar.wasm
as inline data.
This overview shows which modules are available in zbar-wasm:
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 runs bundling tests with Webpack, Rollup and
esbuild and also tests 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>
|
API documentation
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.
Building zbar-wasm from source
Prerequisites:
- A Linux platform
- GNU
make
,tar
andcurl
- Docker or Podman
- 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 Podman as container engine then replace
withEM_ENGINE = $(EM_DOCKER)
in the providedEM_ENGINE = $(EM_PODMAN)
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.
Credits to ...
- 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
License
Software: LGPL-2.1
Documentation: CC-BY-SA 4.0