@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
package/package.json CHANGED
@@ -1,13 +1,10 @@
1
1
  {
2
2
  "name": "@ericblade/quagga2",
3
- "version": "1.10.1",
3
+ "version": "1.11.0",
4
4
  "description": "An advanced barcode-scanner written in JavaScript",
5
5
  "main": "lib/quagga.js",
6
6
  "types": "type-definitions/quagga.d.ts",
7
7
  "browser": "dist/quagga.min.js",
8
- "overrides": {
9
- "@cypress/request": "^3.0.9"
10
- },
11
8
  "optionalDependencies": {
12
9
  "fsevents": "2.3.3"
13
10
  },
@@ -18,6 +15,7 @@
18
15
  "@babel/plugin-proposal-object-rest-spread": "^7.20.7",
19
16
  "@babel/plugin-proposal-optional-chaining": "^7.21.0",
20
17
  "@babel/plugin-transform-runtime": "^7.28.5",
18
+ "@babel/polyfill": "^7.12.1",
21
19
  "@babel/preset-env": "^7.28.5",
22
20
  "@babel/preset-typescript": "^7.28.5",
23
21
  "@babel/runtime": "^7.28.4",
@@ -34,11 +32,11 @@
34
32
  "@typescript-eslint/parser": "^7.18.0",
35
33
  "babel-loader": "^8.2.5",
36
34
  "babel-plugin-add-module-exports": "^1.0.4",
37
- "chai": "^4.3.10",
38
35
  "babel-plugin-istanbul": "^7.0.1",
36
+ "chai": "^4.3.10",
39
37
  "core-js": "^3.46.0",
40
38
  "cross-env": "^10.1.0",
41
- "cypress": "^13.1.0",
39
+ "cypress": "^13.17.0",
42
40
  "eslint": "^8.57.1",
43
41
  "eslint-config-airbnb-base": "^15.0.0",
44
42
  "eslint-config-airbnb-typescript": "^18.0.0",
@@ -46,25 +44,27 @@
46
44
  "eslint-plugin-import": "^2.32.0",
47
45
  "eslint-plugin-jsx-a11y": "^6.10.2",
48
46
  "eslint-plugin-typescript-sort-keys": "^3.3.0",
47
+ "lodash": "^4.17.21",
49
48
  "mocha": "^5.2.0",
49
+ "ndarray": "^1.0.19",
50
+ "ndarray-linear-interpolate": "^1.0.0",
51
+ "ndarray-pixels": "^5.0.1",
52
+ "nyc": "^17.1.0",
50
53
  "sinon": "^21.0.0",
51
54
  "sinon-chai": "^3.7.0",
52
- "nyc": "^17.1.0",
53
55
  "source-map-loader": "^1.1.1",
54
56
  "ts-mocha": "^11.1.0",
55
57
  "ts-node": "^10.9.2",
56
58
  "typescript": "^5.9.3",
57
59
  "webpack": "^4.44.2",
58
- "webpack-cli": "^3.3.12",
59
- "@babel/polyfill": "^7.12.1",
60
- "gl-matrix": "^3.4.4",
61
- "lodash": "^4.17.21",
62
- "ndarray": "^1.0.19",
63
- "ndarray-linear-interpolate": "^1.0.0",
64
- "ndarray-pixels": "^5.0.1"
60
+ "webpack-cli": "^3.3.12"
61
+ },
62
+ "overrides": {
63
+ "minimist": "1.2.8"
65
64
  },
66
65
  "directories": {
67
- "doc": "doc"
66
+ "doc": "docs",
67
+ "example": "docs/examples"
68
68
  },
69
69
  "scripts": {
70
70
  "check-types": "tsc",
@@ -77,15 +77,16 @@
77
77
  "test:browser-universal": "NOT WORKING -- something like npx cypress run --config testFiles=[universal]",
78
78
  "test:browser-all": "npm run cypress:run",
79
79
  "test:import": "mocha test/test-import.mjs",
80
- "test:node": "npx cross-env NODE_ENV=test ts-mocha -p test/tsconfig.json src/**/test/node/*.spec.* src/**/test/*.spec.* test/integration/integration.spec.ts",
80
+ "test:node": "npx cross-env NODE_ENV=test ts-mocha -p test/tsconfig.json src/**/test/node/*.spec.* src/**/test/*.spec.* test/integration/**/*.spec.ts",
81
81
  "test:require": "mocha test/test-require",
82
82
  "test:module": "npm run test:require && npm run test:import",
83
- "test": "npm run cypress:run && npx cross-env NODE_ENV=test BUILD_ENV=development ts-mocha -p test/tsconfig.json src/**/test/node/*.spec.* src/**/test/*.spec.* test/integration/integration.spec.ts",
83
+ "test": "npm run cypress:run && npx cross-env NODE_ENV=test BUILD_ENV=development ts-mocha -p test/tsconfig.json src/**/test/node/*.spec.* src/**/test/*.spec.* test/integration/**/*.spec.ts",
84
84
  "build-and-test": "npm run build && npm run test",
85
85
  "build:dev": "npx cross-env NODE_ENV=development BUILD_ENV=development NODE_OPTIONS=--openssl-legacy-provider webpack --config configs/webpack.config.js",
86
86
  "build:prod": "npx cross-env NODE_ENV=production BUILD_ENV=production NODE_OPTIONS=--openssl-legacy-provider webpack --config configs/webpack.config.min.js",
87
87
  "build:node": "npx cross-env NODE_ENV=production BABEL_ENV=commonjs BUILD_ENV=node NODE_OPTIONS=--openssl-legacy-provider webpack --config configs/webpack.node.config.js",
88
- "build": "npx cross-env NODE_OPTIONS=--openssl-legacy-provider npm run build-old",
88
+ "build": "npx cross-env NODE_OPTIONS=--openssl-legacy-provider npm run build-old && npm run copy-dist-examples",
89
+ "copy-dist-examples": "npx cpx \"dist/*\" \"docs/examples/dist\"",
89
90
  "build-old": "npm run check-types && npm run build:dev && npm run build:prod && npm run build:node",
90
91
  "watch": "npx cross-env BUILD_ENV=development webpack --watch",
91
92
  "lint": "eslint src",
@@ -188,5 +189,8 @@
188
189
  },
189
190
  "publishConfig": {
190
191
  "access": "public"
192
+ },
193
+ "dependencies": {
194
+ "gl-matrix": "^3.4.4"
191
195
  }
192
196
  }
@@ -112,6 +112,12 @@ export type QuaggaImageData = Array<number>;
112
112
 
113
113
  export type BarcodeReaderType = string;
114
114
 
115
+ /**
116
+ * Constructor type for a BarcodeReader class.
117
+ * Used when registering custom readers via registerReader().
118
+ */
119
+ export type BarcodeReaderConstructor = new (config?: BarcodeReaderConfig, supplements?: Array<Readers.BarcodeReader>) => Readers.BarcodeReader;
120
+
115
121
  export interface BarcodeReaderConfig {
116
122
  normalizeBarSpaceWidth?: boolean,
117
123
  supplements?: Array<BarcodeReaderType>,
@@ -489,9 +495,21 @@ export interface QuaggaJSStatic {
489
495
  * When the library is initialized, the start()
490
496
  * method starts the video-stream and begins locating and decoding the
491
497
  * images.
498
+ *
499
+ * Optionally, you can pass a config object to start(), which will
500
+ * call init() and then start() for convenience.
501
+ *
502
+ * If start() is called without init() having been completed first,
503
+ * and no config is provided, an error will be thrown.
492
504
  */
493
505
  start(): void;
494
506
 
507
+ /**
508
+ * Combines init() and start() into a single call. Pass a config object
509
+ * and optionally a callback. If no callback is provided, returns a Promise.
510
+ */
511
+ start(config: QuaggaJSConfigObject, callback?: (err: any) => void): Promise<void>;
512
+
495
513
  /**
496
514
  * If the decoder is currently running, after calling
497
515
  * stop() the decoder does not process any more images.
@@ -535,7 +553,7 @@ export interface QuaggaJSStatic {
535
553
  ResultCollector: QuaggaJSResultCollector;
536
554
  registerResultCollector(resultCollector: QuaggaJSResultCollector): void;
537
555
  setReaders(readers: (QuaggaJSReaderConfig | string)[]): void;
538
- registerReader(name: string, reader: object): void;
556
+ registerReader(name: string, reader: BarcodeReaderConstructor): void;
539
557
 
540
558
  /**
541
559
  * In contrast to the calls described
@@ -564,15 +582,23 @@ export interface QuaggaJSStatic {
564
582
  canvas: {
565
583
  ctx: {
566
584
  image: CanvasRenderingContext2D;
567
- overlay: CanvasRenderingContext2D;
585
+ overlay: CanvasRenderingContext2D | null;
568
586
  };
569
587
  dom: {
570
588
  image: HTMLCanvasElement;
571
- overlay: HTMLCanvasElement;
589
+ overlay: HTMLCanvasElement | null;
572
590
  };
573
591
  };
574
592
 
575
593
  CameraAccess: QuaggaJSCameraAccess;
594
+
595
+ /**
596
+ * Draws a scanner area overlay onto the overlay canvas using the current instance's configured area.
597
+ * Uses the actual adjusted scanning area (after patch alignment) to accurately show where barcodes will be detected.
598
+ * Useful when user code clears the overlay each frame and wants to re-render the area.
599
+ * Only draws when locate is false and inputStream.area is configured with styling.
600
+ */
601
+ drawScannerArea(): void;
576
602
  }
577
603
 
578
604
  /**
@@ -581,7 +607,23 @@ export interface QuaggaJSStatic {
581
607
  export interface QuaggaJSCameraAccess {
582
608
  disableTorch(): Promise<void>;
583
609
  enableTorch(): Promise<void>;
584
- enumerateVideoDevices(): Promise<MediaDeviceInfo[]> | never;
610
+ /**
611
+ * Enumerates video input devices, optionally filtering by constraints.
612
+ * @param videoConstraints Optional constraints to filter devices.
613
+ * When provided, only devices that satisfy the given constraints will be returned.
614
+ * This works by attempting to get a media stream for each device with the constraints
615
+ * and returning only the devices that succeed.
616
+ * @returns Promise resolving to an array of MediaDeviceInfo for video input devices.
617
+ */
618
+ enumerateVideoDevices(
619
+ videoConstraints?: MediaTrackConstraintsWithDeprecated
620
+ ): Promise<MediaDeviceInfo[]> | never;
621
+ /**
622
+ * Returns the active MediaStream, or null if no stream is active.
623
+ * Use this when you need access to the full stream, for example to pass to WebRTC
624
+ * or to clone the stream. For just the video track, use getActiveTrack() instead.
625
+ */
626
+ getActiveStream(): MediaStream | null;
585
627
  getActiveStreamLabel(): string;
586
628
  getActiveTrack(): MediaStreamTrack | null;
587
629
  release(): Promise<void>;
@@ -784,11 +826,6 @@ export interface QuaggaJSConfigObject {
784
826
  src?: string | Uint8Array;
785
827
 
786
828
  inputStream?: {
787
- /**
788
- * @default "Live"
789
- */
790
- name?: string;
791
-
792
829
  /**
793
830
  * @default "LiveStream"
794
831
  */
@@ -834,6 +871,28 @@ export interface QuaggaJSConfigObject {
834
871
  * 'line' that is in the middle half
835
872
  */
836
873
  bottom?: string;
874
+
875
+ /**
876
+ * Color of the area border. When defined, draws a rectangle on the overlay canvas
877
+ * showing the scan area boundaries. Requires createOverlay to be true.
878
+ * Can be any valid CSS color value.
879
+ * @default undefined (no border drawn)
880
+ */
881
+ borderColor?: string;
882
+
883
+ /**
884
+ * Line width of the area border in pixels.
885
+ * When defined with a value > 0, draws a rectangle on the overlay canvas.
886
+ * @default undefined (no border drawn)
887
+ */
888
+ borderWidth?: number;
889
+
890
+ /**
891
+ * Background color to fill the scan area.
892
+ * Can be any valid CSS color value (e.g., 'rgba(0, 255, 0, 0.1)' for a light green tint).
893
+ * @default undefined (no background fill)
894
+ */
895
+ backgroundColor?: string;
837
896
  };
838
897
 
839
898
  mime?: string;
@@ -841,6 +900,14 @@ export interface QuaggaJSConfigObject {
841
900
  singleChannel?: boolean;
842
901
  size?: number;
843
902
  sequence?: boolean;
903
+
904
+ debug?: {
905
+ /**
906
+ * @default false
907
+ * Logs frame grabber info, canvas size adjustments, and image loading details
908
+ */
909
+ showImageDetails?: boolean;
910
+ };
844
911
  };
845
912
 
846
913
  /**
@@ -863,9 +930,26 @@ export interface QuaggaJSConfigObject {
863
930
  * It’s optional and defines the maximum number of scans per second.
864
931
  * This renders useful for cases where the scan-session is long-running and
865
932
  * resources such as CPU power are of concern.
933
+ *
934
+ * Note: This specifies a maximum, not an absolute rate. If the system cannot
935
+ * achieve the requested frequency due to CPU limitations or other factors,
936
+ * scans will occur as fast as the system allows.
866
937
  */
867
938
  frequency?: number;
868
939
 
940
+ /**
941
+ * Canvas configuration options for controlling overlay and debug canvases.
942
+ */
943
+ canvas?: {
944
+ /**
945
+ * Whether to create the overlay canvas (drawingBuffer) for drawing bounding boxes
946
+ * and scan lines. Set to false if you don't need visual feedback and want to
947
+ * improve performance.
948
+ * @default true
949
+ */
950
+ createOverlay?: boolean;
951
+ };
952
+
869
953
  decoder?: {
870
954
  /**
871
955
  * @default [ "code_128_reader" ]
@@ -892,6 +976,12 @@ export interface QuaggaJSConfigObject {
892
976
  * @default false
893
977
  */
894
978
  showPattern?: boolean;
979
+
980
+ /**
981
+ * @default false
982
+ * Logs reader registration and initialization to console
983
+ */
984
+ printReaderInfo?: boolean;
895
985
  };
896
986
 
897
987
  /**
@@ -951,6 +1041,18 @@ export interface QuaggaJSConfigObject {
951
1041
  */
952
1042
  showRemainingPatchLabels?: boolean;
953
1043
 
1044
+ /**
1045
+ * @default false
1046
+ * Logs calculated patch size to console
1047
+ */
1048
+ showPatchSize?: boolean;
1049
+
1050
+ /**
1051
+ * @default false
1052
+ * Logs image wrapper size and canvas details to console
1053
+ */
1054
+ showImageDetails?: boolean;
1055
+
954
1056
  boxFromPatches?: {
955
1057
  /**
956
1058
  * @default false