@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,109 @@
1
+ # Browser Support {#browser-support}
2
+
3
+ Quagga2 makes use of many modern Web APIs which are not implemented by all browsers yet. This page details browser compatibility and required APIs.
4
+
5
+ ## Operating Modes {#operating-modes}
6
+
7
+ Quagga2 operates in two modes:
8
+
9
+ 1. **Analyzing static images** - Process existing image files
10
+ 2. **Using a camera** - Decode images from a live video stream
11
+
12
+ The latter requires the MediaDevices API for camera access.
13
+
14
+ ## Browser Compatibility {#browser-compatibility}
15
+
16
+ You can track the compatibility of the used Web APIs for each mode:
17
+
18
+ - [Static Images](http://caniuse.com/#feat=canvas,typedarrays,bloburls,blobbuilder)
19
+ - [Live Stream](http://caniuse.com/#feat=canvas,typedarrays,bloburls,blobbuilder,stream)
20
+
21
+ ### Static Image Mode {#static-image-mode}
22
+
23
+ The following APIs must be supported by your browser:
24
+
25
+ - [Canvas](http://caniuse.com/#feat=canvas)
26
+ - [Typed Arrays](http://caniuse.com/#feat=typedarrays)
27
+ - [Blob URLs](http://caniuse.com/#feat=bloburls)
28
+ - [Blob Builder](http://caniuse.com/#feat=blobbuilder)
29
+
30
+ ### Live Stream Mode {#live-stream-mode}
31
+
32
+ In addition to the APIs required for static images:
33
+
34
+ - [MediaDevices API](http://caniuse.com/#feat=stream) - Required for camera access
35
+
36
+ ## Secure Origins Required {#secure-origins}
37
+
38
+ **Important**: Accessing `getUserMedia` requires a secure origin in most browsers:
39
+
40
+ - `http://` can **only** be used on `localhost`
41
+ - All other hostnames **must** be served via `https://`
42
+
43
+ This is a browser security requirement. Read more in the [Chrome M47 WebRTC Release Notes](https://groups.google.com/forum/#!topic/discuss-webrtc/sq5CVmY69sc).
44
+
45
+ ## Feature Detection {#feature-detection}
46
+
47
+ ### Detecting getUserMedia Support {#detecting-getusermedia}
48
+
49
+ Every browser implements the `mediaDevices.getUserMedia` API differently. It's highly recommended to include [webrtc-adapter](https://github.com/webrtc/adapter) in your project for cross-browser compatibility.
50
+
51
+ **How to test browser capabilities:**
52
+
53
+ ```javascript
54
+ if (navigator.mediaDevices && typeof navigator.mediaDevices.getUserMedia === 'function') {
55
+ // Safe to use getUserMedia
56
+ console.log('Camera access is supported');
57
+ } else {
58
+ // Camera access not available
59
+ console.log('Camera access is NOT supported');
60
+ }
61
+ ```
62
+
63
+ ### Browser Support Table {#browser-support-table}
64
+
65
+ The above condition evaluates as follows:
66
+
67
+ | Browser | Result | Notes |
68
+ |---------------|---------|-------|
69
+ | Chrome | `true` | Full support |
70
+ | Firefox | `true` | Full support |
71
+ | Edge | `true` | Full support |
72
+ | Safari iOS | `true` | Requires HTTPS |
73
+ | IE 11 | `false` | Not supported |
74
+ | Safari Desktop| `true` | macOS 11+ |
75
+
76
+ ## Known Issues {#known-issues}
77
+
78
+ ### iOS Torch/Flash {#ios-torch-flash}
79
+
80
+ Torch (flash) control via `CameraAccess.enableTorch()` and `CameraAccess.disableTorch()` does **not work** on iOS devices running version 16.4 and earlier. Support on later versions may vary.
81
+
82
+ ### Safari Limitations {#safari-limitations}
83
+
84
+ - Older Safari versions may require user interaction before camera access
85
+ - Some older iOS versions have limited WebRTC support
86
+
87
+ ### Internet Explorer {#internet-explorer}
88
+
89
+ Internet Explorer 11 and below do not support the MediaDevices API and cannot use live camera features. Static image decoding may work with polyfills, but this is not officially supported.
90
+
91
+ ## Recommendations {#recommendations}
92
+
93
+ For best compatibility:
94
+
95
+ 1. **Use HTTPS** - Required for camera access on all non-localhost domains
96
+ 2. **Include webrtc-adapter** - Normalizes browser differences
97
+ 3. **Feature detect** - Check for API support before attempting to use camera
98
+ 4. **Provide fallbacks** - Offer file upload as alternative to camera access
99
+ 5. **Test thoroughly** - Browser behavior varies, especially on mobile
100
+
101
+ ## Related {#related}
102
+
103
+ - [Configuration Reference](configuration.md) - How to configure Quagga2
104
+ - [Camera Access API](camera-access.md) - Camera control methods
105
+ - [Getting Started](../getting-started.md) - Installation and setup
106
+
107
+ ---
108
+
109
+ [← Back to Reference](index.md)
@@ -0,0 +1,376 @@
1
+ # CameraAccess API {#cameraaccess-api}
2
+
3
+ Quagga2 exposes a `CameraAccess` API for direct control of camera functionality. This API provides shortcuts for commonly used camera operations.
4
+
5
+ **Access**: `Quagga.CameraAccess`
6
+
7
+ ## Overview {#overview}
8
+
9
+ The CameraAccess API allows you to:
10
+
11
+ - Request and release camera access
12
+ - Enumerate available video devices
13
+ - Control camera torch (flash)
14
+ - Get information about active video streams and tracks
15
+
16
+ All methods return Promises for async operation handling.
17
+
18
+ ## Methods {#methods}
19
+
20
+ ### `CameraAccess.request(videoElement, constraints)` {#cameraaccess-request}
21
+
22
+ Initializes the camera and starts playback.
23
+
24
+ **Parameters**:
25
+
26
+ - `videoElement` (HTMLVideoElement | null) - Video element to display camera stream. If `null`, camera initializes but remains invisible.
27
+ - `constraints` (MediaTrackConstraints, optional) - Camera selection and configuration constraints.
28
+
29
+ **Returns**: `Promise<void>` - Resolves when camera is ready, rejects on error.
30
+
31
+ **Example**:
32
+
33
+ ```javascript
34
+ const video = document.querySelector('#camera-video');
35
+
36
+ // Request camera with default constraints
37
+ await Quagga.CameraAccess.request(video);
38
+
39
+ // Request specific camera
40
+ await Quagga.CameraAccess.request(video, {
41
+ facingMode: 'environment', // Back camera on mobile
42
+ width: { ideal: 1280 },
43
+ height: { ideal: 720 }
44
+ });
45
+
46
+ // Request camera by device ID
47
+ const deviceId = 'abc123...';
48
+ await Quagga.CameraAccess.request(video, { deviceId });
49
+
50
+ // Initialize camera without displaying (for probing)
51
+ await Quagga.CameraAccess.request(null);
52
+ ```
53
+
54
+ **Use cases**:
55
+
56
+ - Start camera before Quagga initialization
57
+ - Probe camera availability and permissions
58
+ - Initialize camera without displaying video
59
+
60
+ ### `CameraAccess.release()` {#cameraaccess-release}
61
+
62
+ Stops the video stream and releases all camera resources.
63
+
64
+ **Returns**: `Promise<void>` - Resolves when all tracks are stopped and resources released.
65
+
66
+ **Example**:
67
+
68
+ ```javascript
69
+ // Stop camera
70
+ await Quagga.CameraAccess.release();
71
+ console.log('Camera released');
72
+ ```
73
+
74
+ **Behavior**:
75
+
76
+ 1. Pauses the video element
77
+ 2. Stops all tracks in the media stream
78
+ 3. Releases camera for use by other applications
79
+
80
+ **Note**: Always call `release()` when finished with the camera to free system resources.
81
+
82
+ ### `CameraAccess.enumerateVideoDevices(constraints?)` {#cameraaccess-enumeratevideodevices}
83
+
84
+ Lists all available video input devices (cameras), optionally filtered by constraints.
85
+
86
+ **Parameters**:
87
+
88
+ - `constraints` (MediaTrackConstraints, optional) - Constraints to filter devices. When provided, only devices that can satisfy the given constraints will be returned.
89
+
90
+ **Returns**: `Promise<MediaDeviceInfo[]>` - Array of video device information.
91
+
92
+ **Example**:
93
+
94
+ ```javascript
95
+ // Get all video devices
96
+ const devices = await Quagga.CameraAccess.enumerateVideoDevices();
97
+
98
+ devices.forEach(device => {
99
+ console.log('Device:', device.label);
100
+ console.log('Device ID:', device.deviceId);
101
+ console.log('Group ID:', device.groupId);
102
+ });
103
+
104
+ // Example output:
105
+ // Device: Front Camera
106
+ // Device ID: abc123...
107
+ // Device: Back Camera
108
+ // Device ID: def456...
109
+ ```
110
+
111
+ **Filtering devices with constraints**:
112
+
113
+ ```javascript
114
+ // Get only devices that support a minimum resolution
115
+ const hdDevices = await Quagga.CameraAccess.enumerateVideoDevices({
116
+ width: { min: 1280 },
117
+ height: { min: 720 }
118
+ });
119
+
120
+ // Get only back-facing cameras
121
+ const backCameras = await Quagga.CameraAccess.enumerateVideoDevices({
122
+ facingMode: 'environment'
123
+ });
124
+
125
+ // Eliminate wide-angle only cameras by specifying aspect ratio
126
+ const standardCameras = await Quagga.CameraAccess.enumerateVideoDevices({
127
+ aspectRatio: { ideal: 1.777 } // 16:9
128
+ });
129
+ ```
130
+
131
+ **Use cases**:
132
+
133
+ - Build camera selector UI
134
+ - Detect available cameras before initialization
135
+ - Check for front/back camera availability on mobile
136
+ - Filter out cameras that don't meet quality requirements
137
+ - Eliminate wide-angle cameras that may not be suitable for barcode scanning
138
+
139
+ **Note**: Device labels may be empty strings until camera permission is granted. When using constraints, the method will request temporary access to each device to test if it satisfies the constraints.
140
+
141
+ ### `CameraAccess.getActiveStreamLabel()` {#cameraaccess-getactivestreamlabel}
142
+
143
+ Gets the label of the currently active video track.
144
+
145
+ **Returns**: `string` - Label of active video track (e.g., "Back Camera", "USB Camera").
146
+
147
+ **Example**:
148
+
149
+ ```javascript
150
+ const label = Quagga.CameraAccess.getActiveStreamLabel();
151
+ console.log('Using camera:', label);
152
+ // Output: "Using camera: Back Camera"
153
+ ```
154
+
155
+ **Use cases**:
156
+
157
+ - Display which camera is currently active
158
+ - Verify correct camera is being used
159
+ - Logging and debugging
160
+
161
+ ### `CameraAccess.getActiveStream()` {#cameraaccess-getactivestream}
162
+
163
+ Gets the complete MediaStream object for the currently active video.
164
+
165
+ **Returns**: `MediaStream | null` - The active MediaStream object, or `null` if no camera is active.
166
+
167
+ **Example**:
168
+
169
+ ```javascript
170
+ const stream = Quagga.CameraAccess.getActiveStream();
171
+
172
+ if (stream) {
173
+ console.log('Stream ID:', stream.id);
174
+ console.log('Stream active:', stream.active);
175
+ console.log('Video tracks:', stream.getVideoTracks().length);
176
+ console.log('Audio tracks:', stream.getAudioTracks().length);
177
+
178
+ // Clone the stream
179
+ const clonedStream = stream.clone();
180
+ }
181
+
182
+ // Pass stream to WebRTC peer connection
183
+ if (stream?.active) {
184
+ peerConnection.addStream(stream);
185
+ }
186
+ ```
187
+
188
+ **Use cases**:
189
+
190
+ - Pass the stream to WebRTC peer connections
191
+ - Clone the stream for multiple consumers
192
+ - Check if the stream is still active via `stream.active`
193
+ - Access the stream ID
194
+ - Work with all tracks (video and audio) in the stream
195
+
196
+ **Note**: For accessing just the video track, use `getActiveTrack()` instead.
197
+
198
+ ### `CameraAccess.getActiveTrack()` {#cameraaccess-getactivetrack}
199
+
200
+ Gets the MediaStreamTrack for the currently active video.
201
+
202
+ **Returns**: `MediaStreamTrack | null` - Active video track object, or `null` if no camera is active.
203
+
204
+ **Example**:
205
+
206
+ ```javascript
207
+ const track = Quagga.CameraAccess.getActiveTrack();
208
+
209
+ console.log('Track state:', track.readyState);
210
+ console.log('Track settings:', track.getSettings());
211
+ console.log('Track capabilities:', track.getCapabilities());
212
+
213
+ // Get current resolution
214
+ const settings = track.getSettings();
215
+ console.log(`Resolution: ${settings.width}x${settings.height}`);
216
+ ```
217
+
218
+ **Use cases**:
219
+
220
+ - Access advanced track capabilities
221
+ - Monitor track state
222
+ - Apply additional constraints
223
+ - Access camera capabilities (zoom, focus, etc.)
224
+
225
+ ### `CameraAccess.enableTorch()` {#cameraaccess-enabletorch}
226
+
227
+ Turns on the camera torch (flash).
228
+
229
+ **Returns**: `Promise<void>` - Resolves when torch is enabled, rejects on error.
230
+
231
+ **Example**:
232
+
233
+ ```javascript
234
+ try {
235
+ await Quagga.CameraAccess.enableTorch();
236
+ console.log('Torch enabled');
237
+ } catch (error) {
238
+ console.error('Failed to enable torch:', error);
239
+ }
240
+ ```
241
+
242
+ **Browser Support**:
243
+
244
+ - ✅ Chrome (Android)
245
+ - ✅ Chrome (Desktop with supported cameras)
246
+ - ❌ Safari iOS 16.4 and earlier
247
+ - ⚠️ Safari iOS later versions - may or may not work
248
+
249
+ **Requirements**:
250
+
251
+ - Camera must support torch capability
252
+ - Camera must be actively streaming
253
+ - Browser must support torch constraint
254
+
255
+ **Note**: Always wrap in try-catch as not all devices support torch.
256
+
257
+ ### `CameraAccess.disableTorch()` {#cameraaccess-disabletorch}
258
+
259
+ Turns off the camera torch (flash).
260
+
261
+ **Returns**: `Promise<void>` - Resolves when torch is disabled, rejects on error.
262
+
263
+ **Example**:
264
+
265
+ ```javascript
266
+ try {
267
+ await Quagga.CameraAccess.disableTorch();
268
+ console.log('Torch disabled');
269
+ } catch (error) {
270
+ console.error('Failed to disable torch:', error);
271
+ }
272
+ ```
273
+
274
+ **Browser Support**: Same as `enableTorch()`.
275
+
276
+ ## Complete Example {#complete-example}
277
+
278
+ ```javascript
279
+ // Enumerate cameras and let user choose
280
+ const devices = await Quagga.CameraAccess.enumerateVideoDevices();
281
+ const backCamera = devices.find(d => d.label.includes('back'));
282
+
283
+ // Initialize camera
284
+ const video = document.querySelector('#video');
285
+ await Quagga.CameraAccess.request(video, {
286
+ deviceId: backCamera.deviceId
287
+ });
288
+
289
+ console.log('Active camera:', Quagga.CameraAccess.getActiveStreamLabel());
290
+
291
+ // Enable torch for better scanning in dark environments
292
+ try {
293
+ await Quagga.CameraAccess.enableTorch();
294
+ } catch (error) {
295
+ console.log('Torch not available');
296
+ }
297
+
298
+ // ... use camera for scanning ...
299
+
300
+ // Cleanup
301
+ await Quagga.CameraAccess.disableTorch();
302
+ await Quagga.CameraAccess.release();
303
+ ```
304
+
305
+ ## Torch Control in Live Scanning {#torch-control}
306
+
307
+ For torch control during live scanning, you may want to provide a toggle button:
308
+
309
+ ```javascript
310
+ let torchEnabled = false;
311
+
312
+ document.querySelector('#torch-toggle').addEventListener('click', async () => {
313
+ try {
314
+ if (torchEnabled) {
315
+ await Quagga.CameraAccess.disableTorch();
316
+ torchEnabled = false;
317
+ } else {
318
+ await Quagga.CameraAccess.enableTorch();
319
+ torchEnabled = true;
320
+ }
321
+ } catch (error) {
322
+ console.error('Torch control failed:', error);
323
+ alert('Torch not available on this device');
324
+ }
325
+ });
326
+ ```
327
+
328
+ ## Advanced Camera Control {#advanced-camera-control}
329
+
330
+ For advanced camera control (zoom, focus, etc.), use the MediaStreamTrack API:
331
+
332
+ ```javascript
333
+ const track = Quagga.CameraAccess.getActiveTrack();
334
+ const capabilities = track.getCapabilities();
335
+
336
+ // Check if zoom is supported
337
+ if (capabilities.zoom) {
338
+ console.log('Zoom range:', capabilities.zoom.min, '-', capabilities.zoom.max);
339
+
340
+ // Apply zoom
341
+ await track.applyConstraints({
342
+ advanced: [{ zoom: 2.0 }]
343
+ });
344
+ }
345
+ ```
346
+
347
+ Read more: [MediaStreamTrack Capabilities](https://www.oberhofer.co/mediastreamtrack-and-its-capabilities)
348
+
349
+ ## Error Handling {#error-handling}
350
+
351
+ Always handle errors when using CameraAccess methods:
352
+
353
+ ```javascript
354
+ try {
355
+ await Quagga.CameraAccess.request(video);
356
+ } catch (error) {
357
+ if (error.name === 'NotAllowedError') {
358
+ console.error('Camera permission denied');
359
+ } else if (error.name === 'NotFoundError') {
360
+ console.error('No camera found');
361
+ } else {
362
+ console.error('Camera error:', error);
363
+ }
364
+ }
365
+ ```
366
+
367
+ ## Related {#related}
368
+
369
+ - [Browser Support](browser-support.md) - Camera compatibility information
370
+ - [Configuration Reference](configuration.md) - Camera configuration in Quagga.init()
371
+ - [API Documentation](api.md) - Main Quagga API methods
372
+ - [Tips & Tricks](../how-to-guides/tips-and-tricks.md) - Camera optimization tips
373
+
374
+ ---
375
+
376
+ [← Back to Reference](index.md)