@ericblade/quagga2 1.10.1 → 1.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/DEPENDENCIES.md +286 -0
  2. package/HALFSAMPLE_PERFORMANCE_ANALYSIS.md +178 -0
  3. package/README.md +119 -10
  4. package/dist/quagga.js +11087 -10681
  5. package/dist/quagga.min.js +4 -3
  6. package/docs/_config.yml +3 -0
  7. package/docs/assets/bb-binary.png +0 -0
  8. package/docs/assets/bb-rotated.png +0 -0
  9. package/docs/assets/binary.png +0 -0
  10. package/docs/assets/component-labeling-line.png +0 -0
  11. package/docs/assets/component-labeling-text.png +0 -0
  12. package/docs/assets/component-labeling.png +0 -0
  13. package/docs/assets/connected-patch-labels.png +0 -0
  14. package/docs/assets/mobile-detected.png +0 -0
  15. package/docs/assets/mobile-located.png +0 -0
  16. package/docs/assets/patches_found.png +0 -0
  17. package/docs/assets/quaggaJS-code128.png +0 -0
  18. package/docs/assets/remaining-patch-labels.png +0 -0
  19. package/docs/assets/skeleton.png +0 -0
  20. package/docs/assets/teaser.png +0 -0
  21. package/docs/contributing.md +102 -0
  22. package/docs/explanation/algorithm-overview.md +69 -0
  23. package/docs/explanation/architecture.md +117 -0
  24. package/docs/explanation/how-barcode-localization-works.md +197 -0
  25. package/docs/explanation/index.md +80 -0
  26. package/docs/explanation/input-streams.md +270 -0
  27. package/docs/getting-started.md +213 -0
  28. package/docs/how-to-guides/configure-readers.md +79 -0
  29. package/docs/how-to-guides/external-readers.md +234 -0
  30. package/docs/how-to-guides/handle-difficult-barcodes.md +127 -0
  31. package/docs/how-to-guides/index.md +77 -0
  32. package/docs/how-to-guides/optimize-performance.md +114 -0
  33. package/docs/how-to-guides/tips-and-tricks.md +115 -0
  34. package/docs/how-to-guides/use-debug-flags.md +776 -0
  35. package/docs/how-to-guides/working-with-coordinates.md +254 -0
  36. package/docs/index.md +118 -0
  37. package/docs/reference/api.md +716 -0
  38. package/docs/reference/browser-support.md +109 -0
  39. package/docs/reference/camera-access.md +376 -0
  40. package/docs/reference/configuration.md +1008 -0
  41. package/docs/reference/dependencies.md +295 -0
  42. package/docs/reference/index.md +74 -0
  43. package/docs/reference/readers.md +261 -0
  44. package/docs/tutorials/first-scan.md +141 -0
  45. package/docs/tutorials/index.md +77 -0
  46. package/docs/tutorials/node-usage.md +182 -0
  47. package/docs/tutorials/react-integration.md +176 -0
  48. package/docs/tutorials/static-image.md +130 -0
  49. package/lib/quagga.js +3140 -2757
  50. package/package.json +22 -18
  51. package/type-definitions/quagga.d.ts +111 -9
@@ -0,0 +1,1008 @@
1
+ # Configuration Reference {#configuration-reference}
2
+
3
+ Complete reference for all Quagga2 configuration options.
4
+
5
+ ## Configuration Object Structure {#configuration-object-structure}
6
+
7
+ The configuration object passed to `Quagga.init()` defines all aspects of barcode detection and decoding:
8
+
9
+ ```javascript
10
+ {
11
+ locate: true,
12
+ inputStream: { ... },
13
+ frequency: 10,
14
+ decoder: { ... },
15
+ locator: { ... },
16
+ debug: false
17
+ }
18
+ ```
19
+
20
+ ## Top-Level Properties {#top-level-properties}
21
+
22
+ ### `locate` {#locate}
23
+
24
+ **Type**: `boolean`
25
+
26
+ **Default**: `true`
27
+
28
+ **Description**: Controls whether Quagga attempts to locate the barcode in the image.
29
+
30
+ **When to use `true`** (default):
31
+
32
+ - Barcode position is unknown
33
+ - Barcode can be anywhere in the frame
34
+ - Barcode may be rotated
35
+ - Best accuracy for varied conditions
36
+
37
+ **When to use `false`**:
38
+
39
+ - Barcode position is fixed and known
40
+ - Using a guide/overlay to position barcode
41
+ - Performance is critical
42
+ - Barcode is always centered and aligned
43
+ - Device lacks auto-focus (blurry images make localization unstable)
44
+
45
+ **Example**:
46
+
47
+ ```javascript
48
+ Quagga.init({
49
+ locate: false, // Expect barcode in center
50
+ inputStream: {
51
+ area: { // Define scan area
52
+ top: "25%",
53
+ right: "25%",
54
+ left: "25%",
55
+ bottom: "25%"
56
+ }
57
+ }
58
+ });
59
+ ```
60
+
61
+ **Performance Impact**: Disabling `locate` significantly improves performance but requires barcode to be properly positioned.
62
+
63
+ ### `inputStream` {#inputstream}
64
+
65
+ **Type**: `object`
66
+
67
+ **Description**: Defines the source of images/video for barcode detection.
68
+
69
+ See [inputStream Configuration](#inputstream-configuration) below for complete details.
70
+
71
+ ### `frequency` {#frequency}
72
+
73
+ **Type**: `number` (optional)
74
+
75
+ **Default**: unlimited (processes as fast as possible, limited by `requestAnimationFrame` which typically matches display refresh rate)
76
+
77
+ **Description**: Maximum scans per second. Controls how often frames are processed.
78
+
79
+ **Important**: `frequency` specifies a **maximum** rate, not an absolute rate. If the system cannot achieve the requested frequency due to CPU limitations, decoding complexity, or other factors, scans will occur as fast as the system allows. For example, if you set `frequency: 10` but your system can only process 8 scans per second, you will get approximately 8 scans per second.
80
+
81
+ **Example**:
82
+
83
+ ```javascript
84
+ Quagga.init({
85
+ frequency: 10 // Process max 10 frames per second
86
+ });
87
+ ```
88
+
89
+ **Use cases**:
90
+
91
+ - Limit CPU usage on long-running sessions
92
+ - Reduce battery drain on mobile devices
93
+ - Throttle processing when high frame rate isn't needed
94
+
95
+ ### `decoder` {#decoder}
96
+
97
+ **Type**: `object`
98
+
99
+ **Description**: Configuration for barcode decoding.
100
+
101
+ See [Decoder Configuration](#decoder-configuration) below for complete details.
102
+
103
+ ### `locator` {#locator}
104
+
105
+ **Type**: `object`
106
+
107
+ **Description**: Configuration for barcode localization algorithm.
108
+
109
+ See [Locator Configuration](#locator-configuration) below for complete details.
110
+
111
+ ### `debug` {#debug}
112
+
113
+ **Type**: `boolean`
114
+
115
+ **Default**: `false`
116
+
117
+ **Description**: Enables global debug mode. When `true` and running development build:
118
+
119
+ - Enables additional logging
120
+ - Allows visual debug flags to work
121
+
122
+ **Note**: More fine-grained debug control is available via `inputStream.debug`, `decoder.debug`, and `locator.debug`. See [Debug Flags Guide](../how-to-guides/use-debug-flags.md).
123
+
124
+ ### `canvas` {#canvas}
125
+
126
+ **Type**: `object`
127
+
128
+ **Description**: Configuration for canvas elements used by Quagga.
129
+
130
+ See [Canvas Configuration](#canvas-configuration) below for complete details.
131
+
132
+ ## inputStream Configuration {#inputstream-configuration}
133
+
134
+ Controls the source and properties of the image/video stream.
135
+
136
+ ### inputStream Structure {#inputstream-structure}
137
+
138
+ ```javascript
139
+ inputStream: {
140
+ type: "LiveStream",
141
+ target: document.querySelector('#scanner'), // or '#scanner'
142
+ constraints: {
143
+ width: 640,
144
+ height: 480,
145
+ facingMode: "environment",
146
+ deviceId: "abc123...",
147
+ aspectRatio: 1.333
148
+ },
149
+ area: {
150
+ top: "0%",
151
+ right: "0%",
152
+ left: "0%",
153
+ bottom: "0%"
154
+ },
155
+ singleChannel: false,
156
+ debug: {
157
+ showImageDetails: false
158
+ }
159
+ }
160
+ ```
161
+
162
+ ### `inputStream.type` {#inputstream-type}
163
+
164
+ **Type**: `string`
165
+
166
+ **Options**: `"LiveStream"` | `"VideoStream"` | `"ImageStream"`
167
+
168
+ **Description**: Type of input source.
169
+
170
+ **LiveStream** (default):
171
+
172
+ - Uses `getUserMedia` for live camera
173
+ - Real-time barcode scanning
174
+ - Requires camera permission
175
+
176
+ **VideoStream**:
177
+
178
+ - Processes a pre-recorded video file
179
+ - Useful for testing
180
+
181
+ **ImageStream**:
182
+
183
+ - Processes static images
184
+ - Can use file paths or data URLs
185
+
186
+ ### `inputStream.target` {#inputstream-target}
187
+
188
+ **Type**: `HTMLElement | string`
189
+
190
+ **Description**: DOM element or CSS selector where Quagga renders the video/canvas.
191
+
192
+ **Examples**:
193
+
194
+ ```javascript
195
+ // Direct element reference
196
+ target: document.querySelector('#scanner-container')
197
+
198
+ // CSS selector
199
+ target: '#scanner-container'
200
+
201
+ // Default if omitted: '#interactive.viewport'
202
+ ```
203
+
204
+ ### `inputStream.constraints` {#inputstream-constraints}
205
+
206
+ **Type**: `object`
207
+
208
+ **Description**: MediaStream constraints for camera selection and configuration. Follows [MediaTrackConstraints](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints) spec.
209
+
210
+ **Common Properties**:
211
+
212
+ ```javascript
213
+ constraints: {
214
+ width: { ideal: 1280 }, // Preferred width
215
+ height: { ideal: 720 }, // Preferred height
216
+ facingMode: "environment", // "user" (front) or "environment" (back)
217
+ deviceId: "abc123...", // Specific camera by ID
218
+ aspectRatio: { ideal: 1.777 } // 16:9 aspect ratio
219
+ }
220
+ ```
221
+
222
+ **Constraint Types**:
223
+
224
+ ```javascript
225
+ // Exact value (strict)
226
+ width: { exact: 1920 }
227
+
228
+ // Ideal value (preferred, not required)
229
+ width: { ideal: 1920 }
230
+
231
+ // Range
232
+ width: { min: 640, max: 1920 }
233
+
234
+ // Simple value (treated as ideal)
235
+ width: 1280
236
+ ```
237
+
238
+ **facingMode**:
239
+
240
+ - `"user"` - Front-facing camera (selfie camera)
241
+ - `"environment"` - Back-facing camera (main camera)
242
+ - `{ exact: "environment" }` - Require specific camera (fails if unavailable)
243
+
244
+ **Example - High Resolution**:
245
+
246
+ ```javascript
247
+ constraints: {
248
+ width: { ideal: 1920 },
249
+ height: { ideal: 1080 },
250
+ facingMode: "environment"
251
+ }
252
+ ```
253
+
254
+ **Example - Specific Camera**:
255
+
256
+ ```javascript
257
+ // First, enumerate devices
258
+ const devices = await Quagga.CameraAccess.enumerateVideoDevices();
259
+ const backCamera = devices.find(d => d.label.includes('back'));
260
+
261
+ // Then use deviceId
262
+ constraints: {
263
+ deviceId: { exact: backCamera.deviceId }
264
+ }
265
+ ```
266
+
267
+ ### `inputStream.area` {#inputstream-area}
268
+
269
+ **Type**: `object`
270
+
271
+ **Description**: Defines rectangular region for detection/localization as percentage offsets. Also supports visual styling options for the scan area.
272
+
273
+ **Structure**:
274
+
275
+ ```javascript
276
+ area: {
277
+ top: "0%", // Offset from top
278
+ right: "0%", // Offset from right
279
+ left: "0%", // Offset from left
280
+ bottom: "0%", // Offset from bottom
281
+ borderColor: undefined, // Border color (draws border when defined)
282
+ borderWidth: undefined, // Border width in pixels (draws border when > 0)
283
+ backgroundColor: undefined // Background fill color
284
+ }
285
+ ```
286
+
287
+ **Example - Center Rectangle with Border**:
288
+
289
+ ```javascript
290
+ area: {
291
+ top: "25%",
292
+ right: "25%",
293
+ left: "25%",
294
+ bottom: "25%",
295
+ borderColor: "rgba(0, 255, 0, 0.7)", // Green border
296
+ borderWidth: 3
297
+ }
298
+ // Results in a 50% x 50% rectangle in the center with a green border
299
+ ```
300
+
301
+ **Example - Scan Area with Background Tint**:
302
+
303
+ ```javascript
304
+ area: {
305
+ top: "10%",
306
+ right: "10%",
307
+ left: "10%",
308
+ bottom: "10%",
309
+ borderColor: "red",
310
+ borderWidth: 2,
311
+ backgroundColor: "rgba(0, 255, 0, 0.1)" // Light green tint
312
+ }
313
+ ```
314
+
315
+ **Use cases**:
316
+
317
+ - Restrict scanning to specific area
318
+ - Guide user with visual overlay showing scan region
319
+ - Improve performance by processing less pixels
320
+ - Required when `locate: false` to define scan region
321
+
322
+ #### `inputStream.area.borderColor` {#inputstream-area-bordercolor}
323
+
324
+ **Type**: `string`
325
+
326
+ **Default**: `undefined` (no border drawn)
327
+
328
+ **Description**: Color of the area border. When defined, draws a rectangle on the overlay canvas showing the scan area boundaries. Requires `canvas.createOverlay: true` (default). Can be any valid CSS color value.
329
+
330
+ **Example**:
331
+
332
+ ```javascript
333
+ area: {
334
+ top: '25%',
335
+ bottom: '25%',
336
+ borderColor: 'red' // Red border
337
+ // or: 'rgba(255, 0, 0, 0.7)' // Semi-transparent red
338
+ }
339
+ ```
340
+
341
+ #### `inputStream.area.borderWidth` {#inputstream-area-borderwidth}
342
+
343
+ **Type**: `number`
344
+
345
+ **Default**: `undefined` (uses default of 2 when borderColor is defined)
346
+
347
+ **Description**: Width of the area border line in pixels. When defined with a value > 0, draws a rectangle on the overlay canvas.
348
+
349
+ **Example**:
350
+
351
+ ```javascript
352
+ area: {
353
+ top: '25%',
354
+ bottom: '25%',
355
+ borderColor: 'green',
356
+ borderWidth: 5 // Thicker border for visibility
357
+ }
358
+ ```
359
+
360
+ #### `inputStream.area.backgroundColor` {#inputstream-area-backgroundcolor}
361
+
362
+ **Type**: `string`
363
+
364
+ **Default**: `undefined` (no background fill)
365
+
366
+ **Description**: Background color to fill the scan area. Can be any valid CSS color value. Useful for tinting the scan area to make it more visible.
367
+
368
+ **Example**:
369
+
370
+ ```javascript
371
+ area: {
372
+ top: '10%',
373
+ right: '10%',
374
+ bottom: '10%',
375
+ left: '10%',
376
+ backgroundColor: 'rgba(0, 255, 0, 0.1)' // Light green tint
377
+ }
378
+ ```
379
+
380
+ #### Drawing Behavior {#inputstream-area-drawing}
381
+
382
+ - When `locate: false`: the scanner area is drawn on the overlay canvas every processed frame (if `canvas.createOverlay: true`). Use `borderColor`/`borderWidth` for the outline and `backgroundColor` for a translucent fill.
383
+ - When `locate: true`: the area values can constrain processing internally, but the area overlay is not drawn by default.
384
+ - Public API: you can trigger drawing yourself at any time via `Quagga.drawScannerArea()`, which uses the configured `inputStream.area` and draws the actual adjusted scanning area.
385
+ - Requirement: the overlay canvas must exist (`canvas.createOverlay: true`).
386
+
387
+ > **Note**: When `locate: false`, the actual adjusted scanning area dimensions (after patch alignment) are available in `result.boxes[0]` within callbacks like `onProcessed`. These dimensions may differ slightly from percentage-based calculations due to rounding to patch size multiples. See [Result Properties](#result-properties) in the API reference for details.
388
+
389
+ ### `inputStream.singleChannel` {#inputstream-singlechannel}
390
+
391
+ **Type**: `boolean`
392
+
393
+ **Default**: `false`
394
+
395
+ **Description**: When `true`, only reads the red color channel instead of converting to grayscale.
396
+
397
+ **Use cases**:
398
+
399
+ - Debugging decoder issues
400
+ - Used with ResultCollector for analysis
401
+ - Not recommended for normal use
402
+
403
+ ### `inputStream.size` {#inputstream-size}
404
+
405
+ **Type**: `number`
406
+
407
+ **Default**: `800` when using `decodeSingle()`; `0` (original image dimensions) otherwise
408
+
409
+ **Description**: Scales the input image so that the longest side (width or height) equals this value, maintaining aspect ratio.
410
+
411
+ **Important**: When using `decodeSingle()`, the default is `size: 800`. This means images are **automatically scaled to 800px** on their longest side (both larger and smaller images are scaled to match this value) unless you explicitly specify a different value. When using `init()`, no default scaling is applied - original dimensions are used unless you specify a size. The `box`, `boxes`, and `line` coordinates in the result are returned in the **scaled coordinate space**, not the original image dimensions. To use the original image size without any scaling, set `inputStream.size` to `0`. See [Working with Box Coordinates](../how-to-guides/working-with-coordinates.md) for details on handling scaled coordinates.
412
+
413
+ **Note on Scaling**: This parameter scales images both up and down. While upscaling typically introduces interpolation artifacts, testing has shown that moderate upscaling can actually **improve** barcode detection accuracy, even with `halfSample:false`. The benefits include:
414
+
415
+ - **More pixels per bar**: Upscaling provides more pixel data for the locator to analyze
416
+ - **Interpolation smoothing**: Acts as a smoothing filter that can reduce noise and compression artifacts
417
+ - **Integer scaling**: 2x scaling provides clean pixel doubling with minimal artifacts
418
+ - **Works with both halfSample modes**: Benefits seen in both halfSample:true and halfSample:false
419
+
420
+ **Scaling Guidelines**:
421
+
422
+ - Start with **2x the original image size** (e.g., 1100px → 2200px) for testing
423
+ - Try 1.25x-1.5x if 2x doesn't work well
424
+ - Performance typically peaks at moderate upscaling (1.25x-2x range)
425
+ - Performance degrades beyond 2.5x due to excessive interpolation artifacts
426
+ - Optimal scaling depends on image quality, compression, and barcode size/condition - not necessarily barcode type
427
+
428
+ **Recommended approach**: Experiment with different scaling factors. Start with 2x (e.g., 1600-2200 for typical barcode images), then try lower values if needed. The optimal value varies by image content and quality.
429
+
430
+ **Example**:
431
+
432
+ ```javascript
433
+ // Default behavior: decodeSingle uses size: 800 by default
434
+ Quagga.decodeSingle({
435
+ src: "./large-image.jpg", // 3000x2000 image
436
+ // size defaults to 800, so this scales down to 800x533
437
+ // Result coordinates (box, line) will be in 800x533 space
438
+ });
439
+
440
+ // Override to preserve larger processing resolution
441
+ Quagga.decodeSingle({
442
+ src: "./large-image.jpg", // 3000x2000 image
443
+ inputStream: {
444
+ size: 1600 // Scales down to 1600x1067
445
+ }
446
+ });
447
+
448
+ // Disable scaling entirely - use original image dimensions
449
+ Quagga.decodeSingle({
450
+ src: "./medium-image.jpg", // 1280x720 image
451
+ inputStream: {
452
+ size: 0 // Zero disables scaling, uses original 1280x720
453
+ }
454
+ });
455
+
456
+ // Upscale for fine details (can improve detection)
457
+ Quagga.decodeSingle({
458
+ src: "./small-barcode.jpg", // 1100x658 image with fine barcode
459
+ inputStream: {
460
+ size: 1600 // Scales up to 1600x957, may improve detection
461
+ }
462
+ });
463
+ ```
464
+
465
+ **Performance Note**: Higher values increase processing time. Balance detection accuracy against speed based on your use case. Test different values to find the optimal setting for your specific images.
466
+
467
+ ### `inputStream.debug` {#inputstream-debug}
468
+
469
+ **Type**: `object`
470
+
471
+ **Description**: Enable console logging for input stream diagnostics.
472
+
473
+ ```javascript
474
+ debug: {
475
+ showImageDetails: false // Log frame grabber operations
476
+ }
477
+ ```
478
+
479
+ #### `inputStream.debug.showImageDetails` {#inputstream-debug-showimagedetails}
480
+
481
+ **Type**: `boolean`
482
+
483
+ **Default**: `false`
484
+
485
+ **Description**: Logs frame grabber info, canvas size adjustments, and image loading details to the console.
486
+
487
+ See [Debug Flags Guide](../how-to-guides/use-debug-flags.md) for details.
488
+
489
+ ### `inputStream.sequence` (ImageStream only) {#inputstream-sequence}
490
+
491
+ **Type**: `boolean` (default: `false`)
492
+
493
+ **Description**: When set to `true` and used with `type: 'ImageStream'`, Quagga will load a sequence of images named `image-001.jpg`, `image-002.jpg`, etc., from the base path specified by `src`, starting at the `offset` index and loading `size` images.
494
+
495
+ **Note:** Sequence mode currently only supports `.jpg` files. Images with other extensions (e.g., `.png`) will not be loaded. If you need support for other formats, see the related feature request or use single image mode.
496
+
497
+ **Related Properties:**
498
+ - `inputStream.src`: Base path for images (e.g., `/path/to/images/`)
499
+ - `inputStream.size`: Number of images to load
500
+ - `inputStream.offset`: Starting index (default: 1)
501
+
502
+ **Example:**
503
+
504
+ ```javascript
505
+ Quagga.init({
506
+ inputStream: {
507
+ type: 'ImageStream',
508
+ src: '/path/to/images/', // Base path for images
509
+ sequence: true,
510
+ size: 3, // Number of images to load
511
+ offset: 1 // Starting index (optional)
512
+ },
513
+ decoder: { readers: ['code_128_reader'] }
514
+ });
515
+ ```
516
+
517
+ This will load `/path/to/images/image-001.jpg`, `/path/to/images/image-002.jpg`, `/path/to/images/image-003.jpg`.
518
+
519
+ Sequence mode is ideal for batch testing or processing multiple images with predictable filenames.
520
+
521
+ ## Decoder Configuration {#decoder-configuration}
522
+
523
+ Controls barcode detection and decoding behavior.
524
+
525
+ ### Decoder Structure {#decoder-structure}
526
+
527
+ ```javascript
528
+ decoder: {
529
+ readers: ["code_128_reader"],
530
+ debug: {
531
+ drawBoundingBox: false,
532
+ showFrequency: false,
533
+ drawScanline: false,
534
+ showPattern: false,
535
+ printReaderInfo: false
536
+ },
537
+ multiple: false
538
+ }
539
+ ```
540
+
541
+ ### `decoder.readers` {#decoder-readers}
542
+
543
+ **Type**: `Array<string | object>`
544
+
545
+ **Required**: Yes
546
+
547
+ **Description**: Array of barcode reader types to use.
548
+
549
+ **Available Readers**:
550
+
551
+ - `code_128_reader` - Code 128
552
+ - `ean_reader` - EAN-13
553
+ - `ean_8_reader` - EAN-8
554
+ - `code_39_reader` - Code 39
555
+ - `code_39_vin_reader` - Code 39 VIN
556
+ - `codabar_reader` - Codabar
557
+ - `upc_reader` - UPC-A
558
+ - `upc_e_reader` - UPC-E
559
+ - `i2of5_reader` - Interleaved 2 of 5
560
+ - `2of5_reader` - Standard 2 of 5
561
+ - `code_93_reader` - Code 93
562
+ - `code_32_reader` - Code 32 (Italian Pharmacode)
563
+
564
+ See [Supported Barcode Types](readers.md) for complete details.
565
+
566
+ **Simple Example**:
567
+
568
+ ```javascript
569
+ readers: ["code_128_reader", "ean_reader"]
570
+ ```
571
+
572
+ **With Configuration** (e.g., EAN extensions):
573
+
574
+ ```javascript
575
+ readers: [
576
+ "ean_reader", // Regular EAN without extensions
577
+ {
578
+ format: "ean_reader",
579
+ config: {
580
+ supplements: ['ean_5_reader', 'ean_2_reader']
581
+ }
582
+ } // EAN with 2 or 5 digit extensions
583
+ ]
584
+ ```
585
+
586
+ **Important**: Readers are processed in the exact order specified. The first reader to successfully decode wins. List most common/expected formats first for better performance and accuracy. See [Reader Priority](readers.md#reader-priority-and-order) for details.
587
+
588
+ ### `decoder.debug` {#decoder-debug}
589
+
590
+ **Type**: `object`
591
+
592
+ **Description**: Enable visual debug overlays and console logging for decoder.
593
+
594
+ ```javascript
595
+ debug: {
596
+ drawBoundingBox: false, // Draw box around detected barcode
597
+ showFrequency: false, // Display frequency data
598
+ drawScanline: false, // Draw the scan line
599
+ showPattern: false, // Display pattern data
600
+ printReaderInfo: false // Log reader registration to console
601
+ }
602
+ ```
603
+
604
+ See [Debug Flags Guide](../how-to-guides/use-debug-flags.md) for details.
605
+
606
+ ### `decoder.multiple` {#decoder-multiple}
607
+
608
+ **Type**: `boolean`
609
+
610
+ **Default**: `false`
611
+
612
+ **Description**: When `true`, continues decoding after finding a barcode to detect multiple barcodes in a single image.
613
+
614
+ **Example**:
615
+
616
+ ```javascript
617
+ decoder: {
618
+ readers: ["code_128_reader"],
619
+ multiple: true
620
+ }
621
+ ```
622
+
623
+ **Result format**: When `true`, the result is an array of result objects:
624
+
625
+ ```javascript
626
+ Quagga.onDetected(function(results) {
627
+ // results is an array
628
+ results.forEach(function(result) {
629
+ if (result.codeResult) {
630
+ console.log("Found:", result.codeResult.code);
631
+ }
632
+ });
633
+ });
634
+ ```
635
+
636
+ ## Locator Configuration {#locator-configuration}
637
+
638
+ Controls the barcode localization algorithm. Only relevant when `locate: true`.
639
+
640
+ ### Locator Structure {#locator-structure}
641
+
642
+ ```javascript
643
+ locator: {
644
+ halfSample: true,
645
+ patchSize: "medium",
646
+ debug: {
647
+ showCanvas: false,
648
+ showPatches: false,
649
+ showFoundPatches: false,
650
+ showSkeleton: false,
651
+ showLabels: false,
652
+ showPatchLabels: false,
653
+ showRemainingPatchLabels: false,
654
+ showPatchSize: false,
655
+ showImageDetails: false,
656
+ boxFromPatches: {
657
+ showTransformed: false,
658
+ showTransformedBox: false,
659
+ showBB: false
660
+ }
661
+ }
662
+ }
663
+ ```
664
+
665
+ ### `locator.halfSample` {#locator-halfsample}
666
+
667
+ **Type**: `boolean`
668
+
669
+ **Default**: `true`
670
+
671
+ **Description**: When `true`, operates on image scaled to half width/height (quarter pixel count).
672
+
673
+ **Benefits of `true`** (recommended):
674
+
675
+ - Significantly faster processing
676
+ - Implicit smoothing helps find barcodes
677
+ - Reduces noise
678
+
679
+ **When to use `false`**:
680
+
681
+ - Barcodes are very small
682
+ - Need full resolution to detect fine details
683
+ - Have high-resolution camera and need every pixel
684
+
685
+ **Recommendation**: Keep `true` and increase camera resolution if needed, rather than disabling half-sampling.
686
+
687
+ ### `locator.patchSize` {#locator-patchsize}
688
+
689
+ **Type**: `string`
690
+
691
+ **Options**: `"x-small"` | `"small"` | `"medium"` | `"large"` | `"x-large"`
692
+
693
+ **Default**: `"medium"`
694
+
695
+ **Description**: Controls search grid density. Affects how the locator divides the image for analysis.
696
+
697
+ **Size Guidelines**:
698
+
699
+ | Patch Size | Barcode Distance | Use Case |
700
+ |------------|------------------|----------|
701
+ | `x-small` | Far away | Small barcodes, poor focus, low resolution |
702
+ | `small` | Moderately far | Small to medium barcodes |
703
+ | `medium` | Normal | General purpose (recommended default) |
704
+ | `large` | Close up | Large barcodes held close to camera |
705
+ | `x-large` | Very close | Very large barcodes, macro shots |
706
+
707
+ **Relationship to Resolution**:
708
+
709
+ - Smaller patches = denser search grid = slower but finds smaller barcodes
710
+ - Larger patches = coarser search grid = faster but may miss small barcodes
711
+
712
+ **Example - Small Distant Barcodes**:
713
+
714
+ ```javascript
715
+ locator: {
716
+ patchSize: "small",
717
+ halfSample: true // Keep half-sampling on
718
+ },
719
+ inputStream: {
720
+ constraints: {
721
+ width: { ideal: 1280 }, // Higher resolution compensates
722
+ height: { ideal: 720 }
723
+ }
724
+ }
725
+ ```
726
+
727
+ **Example - Large Close-Up Barcodes**:
728
+
729
+ ```javascript
730
+ locator: {
731
+ patchSize: "large",
732
+ halfSample: true
733
+ }
734
+ ```
735
+
736
+ ### `locator.debug` {#locator-debug}
737
+
738
+ **Type**: `object`
739
+
740
+ **Description**: Enable visual debug overlays and console logging for locator.
741
+
742
+ **Console logging flags**:
743
+
744
+ ```javascript
745
+ debug: {
746
+ showPatchSize: false, // Log calculated patch dimensions
747
+ showImageDetails: false // Log image wrapper and canvas details
748
+ }
749
+ ```
750
+
751
+ **Visual overlay flags**:
752
+
753
+ ```javascript
754
+ debug: {
755
+ showCanvas: false, // Show locator's internal canvas
756
+ showPatches: false, // Draw all extracted patches
757
+ showFoundPatches: false, // Highlight candidate patches
758
+ showSkeleton: false, // Show skeleton structure
759
+ showLabels: false, // Show component labels
760
+ showPatchLabels: false, // Show patch labels
761
+ showRemainingPatchLabels: false, // Show post-filter labels
762
+ boxFromPatches: {
763
+ showTransformed: false, // Show transformed coordinates
764
+ showTransformedBox: false, // Show transformed box
765
+ showBB: false // Show final bounding box
766
+ }
767
+ }
768
+ ```
769
+
770
+ See [Debug Flags Guide](../how-to-guides/use-debug-flags.md) for complete details on all debug options.
771
+
772
+ ## Canvas Configuration {#canvas-configuration}
773
+
774
+ Controls the creation and management of canvas elements.
775
+
776
+ ### Canvas Structure {#canvas-structure}
777
+
778
+ ```javascript
779
+ canvas: {
780
+ createOverlay: true // Set to false to disable overlay canvas creation
781
+ }
782
+ ```
783
+
784
+ ### `canvas.createOverlay` {#canvas-createoverlay}
785
+
786
+ **Type**: `boolean`
787
+
788
+ **Default**: `true`
789
+
790
+ **Description**: Controls whether Quagga creates the overlay canvas (`drawingBuffer`). The overlay canvas is used for drawing bounding boxes, scan lines, and other visual feedback on top of the video stream.
791
+
792
+ **When to set `false`**:
793
+
794
+ - You don't need visual feedback/overlays
795
+ - You want to improve performance
796
+ - You're building a headless/server-side application
797
+ - You want to avoid the CSS complexity of hiding the canvas
798
+
799
+ **When to keep `true`** (default):
800
+
801
+ - You want to draw bounding boxes around detected barcodes
802
+ - You want to visualize the scanning process
803
+ - You're using custom drawing in `onProcessed` callbacks
804
+
805
+ **Example - Disable overlay canvas**:
806
+
807
+ ```javascript
808
+ Quagga.init({
809
+ canvas: {
810
+ createOverlay: false // No overlay canvas created
811
+ },
812
+ inputStream: {
813
+ type: "LiveStream",
814
+ target: '#scanner'
815
+ },
816
+ decoder: {
817
+ readers: ["code_128_reader"]
818
+ }
819
+ }, function(err) {
820
+ if (err) {
821
+ console.error(err);
822
+ return;
823
+ }
824
+ Quagga.start();
825
+ });
826
+ ```
827
+
828
+ **Important**: When `createOverlay` is `false`:
829
+
830
+ - `Quagga.canvas.dom.overlay` will be `null`
831
+ - `Quagga.canvas.ctx.overlay` will be `null`
832
+ - You cannot use `Quagga.ImageDebug.drawPath()` with the overlay canvas
833
+
834
+ **Note about debug flags**: The `decoder.debug.drawBoundingBox` and `decoder.debug.drawScanline` flags only work in development builds and require the overlay canvas to exist. These flags draw on the overlay canvas when it's available.
835
+
836
+ **Example - Using overlay canvas for drawing**:
837
+
838
+ ```javascript
839
+ // With createOverlay: true (default)
840
+ Quagga.onProcessed(function(result) {
841
+ const ctx = Quagga.canvas.ctx.overlay;
842
+ const canvas = Quagga.canvas.dom.overlay;
843
+
844
+ // Check if overlay exists before using
845
+ if (ctx && canvas) {
846
+ ctx.clearRect(0, 0, canvas.width, canvas.height);
847
+
848
+ if (result && result.box) {
849
+ Quagga.ImageDebug.drawPath(result.box, {x: 0, y: 1}, ctx, {
850
+ color: "green",
851
+ lineWidth: 2
852
+ });
853
+ }
854
+ }
855
+ });
856
+ ```
857
+
858
+ ## Complete Configuration Examples {#complete-configuration-examples}
859
+
860
+ ### Example 1: Live Camera Scanning {#example-live-camera-scanning}
861
+
862
+ ```javascript
863
+ Quagga.init({
864
+ inputStream: {
865
+ type: "LiveStream",
866
+ target: document.querySelector('#scanner'),
867
+ constraints: {
868
+ width: { ideal: 1280 },
869
+ height: { ideal: 720 },
870
+ facingMode: "environment"
871
+ }
872
+ },
873
+ locate: true,
874
+ frequency: 10,
875
+ decoder: {
876
+ readers: ["code_128_reader", "ean_reader"]
877
+ },
878
+ locator: {
879
+ halfSample: true,
880
+ patchSize: "medium"
881
+ }
882
+ }, function(err) {
883
+ if (err) {
884
+ console.error(err);
885
+ return;
886
+ }
887
+ Quagga.start();
888
+ });
889
+ ```
890
+
891
+ ### Example 2: Static Image Processing {#example-static-image-processing}
892
+
893
+ ```javascript
894
+ Quagga.decodeSingle({
895
+ src: "/images/barcode.jpg",
896
+ locate: true,
897
+ decoder: {
898
+ readers: ["code_128_reader"]
899
+ },
900
+ locator: {
901
+ patchSize: "medium",
902
+ halfSample: true
903
+ }
904
+ }, function(result) {
905
+ if (result && result.codeResult) {
906
+ console.log("Code:", result.codeResult.code);
907
+ }
908
+ });
909
+ ```
910
+
911
+ ### Example 3: Guided Scanning (No Localization) {#example-guided-scanning}
912
+
913
+ ```javascript
914
+ Quagga.init({
915
+ inputStream: {
916
+ type: "LiveStream",
917
+ target: '#scanner',
918
+ constraints: {
919
+ width: 640,
920
+ height: 480,
921
+ facingMode: "environment"
922
+ },
923
+ area: {
924
+ top: "30%",
925
+ right: "20%",
926
+ left: "20%",
927
+ bottom: "30%"
928
+ }
929
+ },
930
+ locate: false, // Barcode must be centered in defined area
931
+ decoder: {
932
+ readers: ["ean_reader", "upc_reader"]
933
+ }
934
+ });
935
+ ```
936
+
937
+ ### Example 4: Multiple Barcode Detection {#example-multiple-barcode-detection}
938
+
939
+ ```javascript
940
+ Quagga.init({
941
+ inputStream: {
942
+ type: "LiveStream",
943
+ target: '#scanner'
944
+ },
945
+ decoder: {
946
+ readers: ["code_128_reader"],
947
+ multiple: true // Detect multiple barcodes per frame
948
+ },
949
+ locate: true,
950
+ locator: {
951
+ patchSize: "medium"
952
+ }
953
+ });
954
+
955
+ Quagga.onDetected(function(results) {
956
+ // results is an array when multiple: true
957
+ console.log(`Found ${results.length} barcodes`);
958
+ results.forEach(r => {
959
+ if (r.codeResult) {
960
+ console.log("Code:", r.codeResult.code);
961
+ }
962
+ });
963
+ });
964
+ ```
965
+
966
+ ### Example 5: Node.js Processing {#example-nodejs-processing}
967
+
968
+ ```javascript
969
+ const Quagga = require('@ericblade/quagga2').default;
970
+
971
+ Quagga.decodeSingle({
972
+ src: "./barcode.jpg",
973
+ inputStream: {
974
+ size: 800 // Scale to max 800px
975
+ },
976
+ locate: true,
977
+ decoder: {
978
+ readers: ["code_128_reader", "ean_reader"]
979
+ }
980
+ }, function(result) {
981
+ if (result && result.codeResult) {
982
+ console.log("Detected:", result.codeResult.code);
983
+ } else {
984
+ console.log("No barcode found");
985
+ }
986
+ });
987
+ ```
988
+
989
+ ## Configuration Best Practices {#configuration-best-practices}
990
+
991
+ 1. **Start simple**: Use defaults, only add specific readers you need
992
+ 2. **Test thoroughly**: Different devices and lighting require different settings
993
+ 3. **Optimize iteratively**: Start with `patchSize: "medium"`, adjust based on results
994
+ 4. **Limit readers**: Only enable barcode formats you actually expect
995
+ 5. **Consider performance**: Balance quality vs. speed based on use case
996
+ 6. **Use constraints wisely**: Higher resolution helps but costs performance
997
+ 7. **Debug systematically**: Enable debug flags to understand behavior
998
+
999
+ ## Related {#related}
1000
+
1001
+ - [API Documentation](api.md) - How to use Quagga methods
1002
+ - [Supported Barcode Types](readers.md) - Available readers
1003
+ - [Browser Support](browser-support.md) - Compatibility information
1004
+ - [Debug Flags Guide](../how-to-guides/use-debug-flags.md) - Diagnostic tools
1005
+
1006
+ ---
1007
+
1008
+ [← Back to Reference](index.md)