repository·master·Indexed 21 days ago
https://github.com/ericblade/quagga2An advanced JavaScript barcode scanner library for real-time localization and decoding of various barcode types (including EAN, Code 128, and Code 39) using camera streams via getUserMedia or static images. It features a two-stage process of locating barcodes via a binary image and skeletonization, then decoding the encoded information. The library supports browser-based live streams and Node.js file-based decoding, providing a comprehensive API for camera management, event handling, and custom reader registration.
Quagga2 is a JavaScript library designed for decoding common barcodes (such as Code128 and EAN13) directly in the browser. It supports various image sources, including:
getUserMedia for continuous decoding.For precise technical details, use the following reference areas:
When migrating, the project structure changes from a Cypress-centric layout to a Playwright-centric layout.
Cypress Structure:
cypress/e2e/ with .cy.ts extension.cypress.config.ts.Playwright Structure:
tests/e2e/ with .spec.ts extension.playwright.config.ts.tests/fixtures/.Quagga manages two canvas elements for visualization: Quagga.canvas.dom.image (the processed grayscale image) and Quagga.canvas.dom.overlay (a transparent layer for drawing).
result.box and result.boxes match the overlay canvas directly; no scaling is required when drawing on the overlay.canvas.createOverlay: false.If you need to draw on a different canvas (like the original video element), you must scale the coordinates manually:
const scaleX = video.videoWidth / Quagga.canvas.dom.image.width;
const scaleY = video.videoHeight / Quagga.canvas.dom.image.height;
const scaledBox = result.box.map(p => [p[0] * scaleX, p[1] * scaleY]);Quagga2 processes images through a sequential multi-stage pipeline to transform raw input into a decoded barcode result. The pipeline follows this flow:
Input Image $\rightarrow$ Preprocessing $\rightarrow$ Localization $\rightarrow$ Decoding $\rightarrow$ Result
Prepares the raw image for analysis by performing:
inputStream.size configuration.inputStream.area is configured, the image is cropped to that specific region to reduce processing load.locate: true)If localization is enabled (which is the default), the engine identifies where the barcode is located in the frame using:
Once the barcode region is identified, the engine performs:
Quagga2 allows you to extend its capabilities by registering external reader modules. Once registered via Quagga.registerReader(), you can include the custom reader in your configuration's decoder.readers array. The order in the array determines the priority (which reader attempts to decode first).
// Register external reader first
Quagga.registerReader('my_custom_reader', MyCustomReader);
// Use in config - position determines priority
Quagga.init({
decoder: {
// External reader tried first, then built-in readers
readers: ['my_custom_reader', 'ean_reader', 'code_128_reader']
}
});If you are using Quagga2 with TypeScript, you may notice that gl-matrix is listed as a direct dependency rather than a development dependency. This is because the Quagga2 type definitions (type-definitions/quagga.d.ts) import vec2 from gl-matrix to provide typing for the Moment.vec property.
import { vec2 } from 'gl-matrix';
export type Moment = {
// ... other properties
vec?: vec2;
};Because of this import, TypeScript consumers need gl-matrix installed in their own project to resolve these types during compilation. While the gl-matrix runtime code is bundled into the production files (dist/quagga.min.js), the package is required for successful type checking.
import { vec2 } from 'gl-matrix';
export type Moment = {
// ... other properties
vec?: vec2;
};Quagga2 processes barcode detection through a linear pipeline that transforms raw input into a decoded result. The flow follows these stages:
onDetected) with the final result.The QuaggaJS configuration is managed via a config object that controls localization, input sources, scan frequency, decoding logic, and localization behavior.
Key top-level properties include:
locate: Boolean. Enables or disables the ability to find a barcode within an image (default: true).inputStream: Object. Defines the source of images/videos.frequency: Number. The maximum number of scans per second (optional). This is a maximum limit; the system will scan as fast as CPU allows if it cannot meet this rate.decoder: Object. Configures how barcodes are converted into data.locator: Object. Configures the localization process (only relevant if locate: true).debug: Boolean. Enables general debugging.{
locate: true,
inputStream: {...},
frequency: 10,
decoder:{...},
locator: {...},
debug: false,
}The Quagga.CameraAccess API provides direct control over camera functionality, allowing you to manage permissions, enumerate devices, and control hardware features like the torch (flash) independently of the main Quagga initialization. All methods return Promises.
Key Capabilities:
MediaStream and MediaStreamTrack objects// Access via Quagga.CameraAccess
await Quagga.CameraAccess.request(videoElement, constraints);Quagga2 supports three distinct input stream types for barcode reading. Choosing the right type depends on your source media:
getUserMedia() and requires HTTPS in production.<video> element.All stream types implement the same InputStream interface and follow a common asynchronous initialization flow.
| Type | Use Case | Input Source |
|------|----------|--------------|
| **LiveStream** | Real-time camera scanning | Device camera via getUserMedia |
| **VideoStream** | Pre-recorded video files | Video file via `<video>` element |
| **ImageStream** | Static images or image sequences | Image file(s) via URL |Quagga2 supports two primary operating modes, each with different Web API requirements:
Canvas, Typed Arrays, Blob URLs, and Blob Builder.MediaDevices API for camera access.For full compatibility, ensure your target browsers support these APIs. Internet Explorer 11 and below do not support the MediaDevices API and cannot use live camera features.