@agicash/qr-scanner

High-performance QR code scanner for the web, powered by ZXing-C++ WebAssembly. Drop-in replacement for nimiq/qr-scanner with significantly better decoding of dense QR codes.

Features

• No forced downscale - feeds high-resolution frames to the decoder (720-1080px+)
• WASM decoder - ZXing-C++ compiled to WebAssembly, ~2x faster than pure-JS decoders
• Web Worker - decoding runs off the main thread, keeping UI at 60fps
• tryHarder mode - additional processing passes for hard-to-read codes

Installation

bun add @agicash/qr-scanner
# or
npm install @agicash/qr-scanner

Quick Start

Live Camera Scanner

import QrScanner from '@agicash/qr-scanner';

const scanner = new QrScanner(videoElement, (result) => {
  console.log(result.data);          // decoded string
  console.log(result.cornerPoints);  // QR code corner positions
}, {
  highlightScanRegion: true,
  highlightCodeOutline: true,
});

await scanner.start();

// Later...
scanner.destroy();

Scan a Single Image

import QrScanner from '@agicash/qr-scanner';

const result = await QrScanner.scanImage(fileOrBlobOrUrl);
console.log(result.data);

API

Constructor

new QrScanner(videoElement, onDecode, options?)

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | onDecodeError | (error) => void | no-op | Called when no QR code found | | calculateScanRegion | (video) => ScanRegion | centered 2/3 square | Define the scan crop area | | preferredCamera | 'environment' \| 'user' \| string | 'environment' | Camera to use | | maxScansPerSecond | number | 15 | Max decode attempts per second | | highlightScanRegion | boolean | false | Show scan region overlay | | highlightCodeOutline | boolean | false | Highlight detected QR code | | overlay | HTMLDivElement | - | Custom overlay element | | cameraResolution | object | { width: { ideal: 1920 }, height: { ideal: 1080 } } | Camera resolution | | decoderOptions | Partial<ReaderOptions> | - | zxing-wasm reader options |

Instance Methods

scanner.start(): Promise<void>
scanner.stop(): void
scanner.destroy(): void
scanner.pause(stopStreamImmediately?): Promise<boolean>
scanner.setCamera(facingModeOrDeviceId): Promise<void>
scanner.hasFlash(): Promise<boolean>
scanner.isFlashOn(): boolean
scanner.toggleFlash(): Promise<void>
scanner.turnFlashOn(): Promise<void>
scanner.turnFlashOff(): Promise<void>
scanner.setInversionMode(mode): void

Static Methods

QrScanner.hasCamera(): Promise<boolean>
QrScanner.listCameras(requestLabels?): Promise<Camera[]>
QrScanner.scanImage(source, options?): Promise<ScanResult>
QrScanner.preload(): Promise<void>
QrScanner.configureWasm(overrides): void
QrScanner.setWorkerUrl(url): void
QrScanner.setDebug(enabled): void

Debug Logging

The library includes performance profiling logs (camera acquisition timing, best-camera selection, etc.) that are off by default. Enable them at runtime for debugging:

QrScanner.setDebug(true);  // logs appear in console
QrScanner.setDebug(false); // back to silent (default)

Worker Loading

The library uses a Web Worker for off-thread QR decoding. The worker script (dist/worker.js) is resolved automatically by modern bundlers (Vite, webpack 5, Parcel) via new URL('./worker.js', import.meta.url).

For CJS consumers or non-standard setups, set the worker URL manually:

QrScanner.setWorkerUrl('/assets/@agicash/qr-scanner/dist/worker.js');

WASM Loading

By default, the WASM binary (~919 KB) loads from jsDelivr CDN. To self-host:

QrScanner.configureWasm({
  locateFile: (filename) => `/wasm/${filename}`,
});

Migration from qr-scanner

| qr-scanner | @agicash/qr-scanner | |------------|-----------------| | returnDetailedScanResult: true | Always returns ScanResult | | ScanRegion.downScaledWidth/Height | Removed - no downscaling | | createQrEngine() | Removed - engine is internal | | setGrayscaleWeights() | Removed - handled by WASM | | DEFAULT_CANVAS_SIZE | Removed - no canvas downscale | | Multiple constructor overloads | Single constructor |

Browser Support

Chrome 80+, Safari 16+, Firefox 80+, Edge 80+

License

MIT