Add support for torch and make beta APIs non beta. (#570)

* Add support for torch and make beta APIs non beta. ### Version 2.2.5 #### Added support for turning `torch` On and Off in `Html5QrcodeScanner`. On supported devices + browsers. This new feature will implement the feature request - [Issue#129](#129) and add support for torch (also called flash) on supported devices and browsers. So far I have confirmed functionality on Samsung Flip 4 Chrome and Internet (Samsung's default browser). This is only supported on `Html5QrcodeScanner` and can be enabled using the config like this. ```ts let html5QrcodeScanner = new Html5QrcodeScanner( "reader", { fps: 10, qrbox: qrboxFunction, // Important notice: this is experimental feature, use it at your // own risk. See documentation in // mebjas@/html5-qrcode/src/experimental-features.ts experimentalFeatures: { useBarCodeDetectorIfSupported: true }, rememberLastUsedCamera: true, aspectRatio: 1.7777778, showTorchButtonIfSupported: true }); ``` The `showTorchButtonIfSupported: true` part is the crucial one. It's off by default for now as I don't like the UI very much. #### Added support for `getRunningTrackSettings()`. Added a new API to get settings (type: [MediaTrackSettings](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackSettings)) for running video streams while QR code is being scanned. ```ts /** * Returns the supported settings of the running video track. * * @returns the supported settings of the running video track. * @throws error if the scanning is not in running state. */ public getRunningTrackSettings(): MediaTrackSettings {} ``` This API can be used to check the currently applied settings on the running video stream like weather torch is on or not. #### `getRunningTrackCapabilities(..)` and `applyVideoConstraints(..)` out of beta. Both `Html5Qrcode` and `Html5QrcodeScanner` classes had support for following APIs. ```ts /** * Returns the capabilities of the running video track. * * Note: Should only be called if {@code Html5QrcodeScanner#getState()} * returns {@code Html5QrcodeScannerState#SCANNING} or * {@code Html5QrcodeScannerState#PAUSED}. * * @returns the capabilities of a running video track. * @throws error if the scanning is not in running state. */ public getRunningTrackCapabilities(): MediaTrackCapabilities {} /** * Apply a video constraints on running video track from camera. * * Note: Should only be called if {@code Html5QrcodeScanner#getState()} * returns {@code Html5QrcodeScannerState#SCANNING} or * {@code Html5QrcodeScannerState#PAUSED}. * * @param {MediaTrackConstraints} specifies a variety of video or camera * controls as defined in * https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints * @returns a Promise which succeeds if the passed constraints are applied, * fails otherwise. * @throws error if the scanning is not in running state. */ public applyVideoConstraints(videoConstaints: MediaTrackConstraints) : Promise<any> {} ``` These have now been taken out of beta and publicly documented. More blog articles to be published for these. * Fix stateful error in torch UI If we start() --> enable torch --> stop() And then start() again, the UI was showing `Set torch off` and clicking wouldn't do anything. This is now fixed. * Code review fixed + codacy related fixes. * Update torch-button.ts replace console.error with error callback. * Update torch-button.ts
mebjas · Oct 30, 2022 · 9bf350a · 9bf350a
1 parent 0da084b
commit 9bf350a
Show file tree

Hide file tree

Showing 8 changed files with 27,657 additions and 19 deletions.
diff --git a/README.md b/README.md
@@ -508,6 +508,8 @@ interface Html5QrcodeScannerConfig
    * were previously granted and what camera was last used. If the permissions
    * is already granted for "camera", QR code scanning will automatically
    * start for previously used camera.
+   * 
+   * Note: default value is {@code true}.
    */
   rememberLastUsedCamera?: boolean | undefined;
 
@@ -527,21 +529,29 @@ interface Html5QrcodeScannerConfig
    *  - Setting wrong values or multiple values will fail.
    */
   supportedScanTypes: Array<Html5QrcodeScanType> | [];
+
+  /**
+   * If {@code true} the rendered UI will have button to turn flash on or off 
+   * based on device + browser support.
+   * 
+   * Note: default value is {@code false}.
+   */
+  showTorchButtonIfSupported?: boolean | undefined;
 };
 
 class Html5Qrcode {
   /**
    * Returns a Promise with a list of all cameras supported by the device.
    */
-  static getCameras(): Array<CameraDevice> // Returns a Promise
+  static getCameras(): Promise<Array<CameraDevice>>;
 
   /**
    * Initialize QR Code scanner.
    * 
    * @param elementId - Id of the HTML element.
    * @param verbose - optional configuration object
    */
-  constructor(elementId: string, config:  Html5QrcodeFullConfig | undefined) {}
+  constructor(elementId: string, config:  Html5QrcodeFullConfig | undefined);
 
   /**
    * Start scanning QR codes or barcodes for a given camera.
@@ -560,7 +570,7 @@ class Html5Qrcode {
     configuration: Html5QrcodeCameraScanConfig | undefined,
     qrCodeSuccessCallback: QrcodeSuccessCallback | undefined,
     qrCodeErrorCallback: QrcodeErrorCallback | undefined,
-  ): Promise<null> {}
+  ): Promise<null>;
 
   /**
    * Pauses the ongoing scan.
@@ -589,7 +599,7 @@ class Html5Qrcode {
   /**
    * Stops streaming QR Code video and scanning. 
    */
-  stop(): Promise<void> {}
+  stop(): Promise<void>;
 
   /**
    * Gets state of the camera scan.
@@ -611,15 +621,59 @@ class Html5Qrcode {
    */
   scanFile(
     imageFile: File,
-    /* default=true */ showImage: boolean | undefined): Promise<string> {}
+    /* default=true */ showImage: boolean | undefined): Promise<string>;
 
   /**
    * Clears the existing canvas.
    * 
    * Note: in case of ongoing web-cam based scan, it needs to be explicitly
    * closed before calling this method, else it will throw an exception.
    */
-  clear(): void {}  // Returns void
+  clear(): void;
+
+
+  /**
+   * Returns the capabilities of the running video track.
+   * 
+   * Read more: https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/getConstraints
+   * 
+   * Important:
+   *  1. Must be called only if the camera based scanning is in progress.
+   *
+   * @returns the capabilities of a running video track.
+   * @throws error if the scanning is not in running state.
+   */
+  getRunningTrackCapabilities(): MediaTrackCapabilities;
+
+  /**
+   * Returns the object containing the current values of each constrainable
+   * property of the running video track.
+   * 
+   * Read more: https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/getSettings
+   * 
+   * Important:
+   *  1. Must be called only if the camera based scanning is in progress.
+   *
+   * @returns the supported settings of the running video track.
+   * @throws error if the scanning is not in running state.
+   */
+  getRunningTrackSettings(): MediaTrackSettings;
+
+  /**
+   * Apply a video constraints on running video track from camera.
+   *
+   * Note: Should only be called if {@code Html5QrcodeScanner#getState()}
+   *   returns {@code Html5QrcodeScannerState#SCANNING} or 
+   *   {@code Html5QrcodeScannerState#PAUSED}.
+   *
+   * @param {MediaTrackConstraints} specifies a variety of video or camera
+   *  controls as defined in
+   *  https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints
+   * @returns a Promise which succeeds if the passed constraints are applied,
+   *  fails otherwise.
+   * @throws error if the scanning is not in running state.
+   */
+  applyVideoConstraints(videoConstaints: MediaTrackConstraints): Promise<void>;
 }
 
 class Html5QrcodeScanner {
@@ -633,7 +687,7 @@ class Html5QrcodeScanner {
   constructor(
     elementId: string,
     config: Html5QrcodeScannerConfig | undefined,
-    verbose: boolean | undefined) {}
+    verbose: boolean | undefined);
 
   /**
    * Renders the User Interface.
@@ -645,7 +699,7 @@ class Html5QrcodeScanner {
    */
   render(
     qrCodeSuccessCallback: QrcodeSuccessCallback,
-    qrCodeErrorCallback: QrcodeErrorCallback | undefined) {}
+    qrCodeErrorCallback: QrcodeErrorCallback | undefined);
 
   /**
    * Pauses the ongoing scan.
@@ -684,7 +738,52 @@ class Html5QrcodeScanner {
   getState(): Html5QrcodeScannerState;
 
   /** Removes the QR Code scanner UI. */
-  clear(): Promise<void>  {}
+  clear(): Promise<void>;
+
+  /**
+   * Returns the capabilities of the running video track.
+   * 
+   * Read more: https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/getConstraints
+   * 
+   * Note: Should only be called if {@code Html5QrcodeScanner#getState()}
+   *   returns {@code Html5QrcodeScannerState#SCANNING} or 
+   *   {@code Html5QrcodeScannerState#PAUSED}.
+   *
+   * @returns the capabilities of a running video track.
+   * @throws error if the scanning is not in running state.
+   */
+  getRunningTrackCapabilities(): MediaTrackCapabilities;
+
+  /**
+   * Returns the object containing the current values of each constrainable
+   * property of the running video track.
+   * 
+   * Read more: https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/getSettings
+   * 
+   * Note: Should only be called if {@code Html5QrcodeScanner#getState()}
+   *   returns {@code Html5QrcodeScannerState#SCANNING} or 
+   *   {@code Html5QrcodeScannerState#PAUSED}.
+   *
+   * @returns the supported settings of the running video track.
+   * @throws error if the scanning is not in running state.
+   */
+  getRunningTrackSettings(): MediaTrackSettings;
+
+  /**
+   * Apply a video constraints on running video track from camera.
+   *
+   * Note: Should only be called if {@code Html5QrcodeScanner#getState()}
+   *   returns {@code Html5QrcodeScannerState#SCANNING} or 
+   *   {@code Html5QrcodeScannerState#PAUSED}.
+   *
+   * @param {MediaTrackConstraints} specifies a variety of video or camera
+   *  controls as defined in
+   *  https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints
+   * @returns a Promise which succeeds if the passed constraints are applied,
+   *  fails otherwise.
+   * @throws error if the scanning is not in running state.
+   */
+  applyVideoConstraints(videoConstaints: MediaTrackConstraints) : Promise<void>;
 }
 ```
 
@@ -752,6 +851,8 @@ granted and what camera was last used. If the permissions is already granted for
 "camera", QR code scanning will automatically * start for previously used camera.
 
 #### `supportedScanTypes` - `Array<Html5QrcodeScanType> | []`
+> This is only supported for `Html5QrcodeScanner`.
+
 Default = `[Html5QrcodeScanType.SCAN_TYPE_CAMERA, Html5QrcodeScanType.SCAN_TYPE_FILE]`
 
 This field can be used to:
@@ -798,6 +899,11 @@ supportedScanTypes: [
   Html5QrcodeScanType.SCAN_TYPE_CAMERA]
 ```
 
+#### `showTorchButtonIfSupported` - `boolean | undefined`
+> This is only supported for `Html5QrcodeScanner`.
+
+If `true` the rendered UI will have button to turn flash on or off based on device + browser support. The value is `false` by default.
+
 ### Scanning only specific formats
 By default, both camera stream and image files are scanned against all the
 supported code formats.  Both `Html5QrcodeScanner` and `Html5Qrcode` classes can
@@ -909,6 +1015,7 @@ You can contribute to the project in several ways:
 This project would not be possible without all of our fantastic contributors and [sponsors](https://github.com/sponsors/mebjas). If you'd like to support the maintenance and upkeep of this project you can [donate via GitHub Sponsors](https://github.com/sponsors/mebjas).
 
 <!-- sponsors -->
+<a href="https://github.com/bujjivadu"><img src="https://github.com/bujjivadu.png" width="40px" alt="" /></a>
 <a href="https://github.com/ben-gy"><img src="https://github.com/ben-gy.png" width="40px" alt="" /></a>
 <!-- sponsors -->
 

diff --git a/changelog.md b/changelog.md
@@ -1,3 +1,98 @@
+### Version 2.2.5
+
+#### Added support for turning `torch` On and Off in `Html5QrcodeScanner`.
+On supported devices + browsers.
+
+This new feature will implement the feature request - [Issue#129](https://github.com/mebjas/html5-qrcode/issues/129) and add support for torch (also called flash) on supported devices and browsers.
+
+So far I have confirmed functionality on Samsung Flip 4 Chrome and Internet (Samsung's default browser).
+
+This is only supported on `Html5QrcodeScanner` and can be enabled using the config like this.
+
+```ts
+let html5QrcodeScanner = new Html5QrcodeScanner(
+    "reader", 
+    { 
+        fps: 10,
+        qrbox: qrboxFunction,
+        // Important notice: this is experimental feature, use it at your
+        // own risk. See documentation in
+        // mebjas@/html5-qrcode/src/experimental-features.ts
+        experimentalFeatures: {
+            useBarCodeDetectorIfSupported: true
+        },
+        rememberLastUsedCamera: true,
+        aspectRatio: 1.7777778,
+        showTorchButtonIfSupported: true
+    });
+```
+
+The `showTorchButtonIfSupported: true` part is the crucial one. It's off by default for now as I don't like the UI very much.
+
+#### Added support for `getRunningTrackSettings()`.
+
+Added a new API to get settings (type: [MediaTrackSettings](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackSettings)) for running video streams while QR code is being scanned.
+
+```ts
+/**
+ * Returns the object containing the current values of each constrainable
+ * property of the running video track.
+ * 
+ * Read more: https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/getSettings
+ * 
+ * Important:
+ *  1. Must be called only if the camera based scanning is in progress.
+ *
+ * @returns the supported settings of the running video track.
+ * @throws error if the scanning is not in running state.
+ */
+public getRunningTrackSettings(): MediaTrackSettings {}
+```
+
+This API can be used to check the currently applied settings on the running video stream like weather torch is on or not.
+
+#### `getRunningTrackCapabilities(..)` and `applyVideoConstraints(..)` out of beta.
+
+Both `Html5Qrcode` and `Html5QrcodeScanner` classes had support for following APIs.
+
+```ts
+/**
+ * Returns the capabilities of the running video track.
+ * 
+ * Read more: https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/getConstraints
+ * 
+ * Important:
+ *  1. Must be called only if the camera based scanning is in progress.
+ *
+ * @returns the capabilities of a running video track.
+ * @throws error if the scanning is not in running state.
+ */
+public getRunningTrackCapabilities(): MediaTrackCapabilities {}
+
+/**
+ * Apply a video constraints on running video track from camera.
+ *
+ * Important:
+ *  1. Must be called only if the camera based scanning is in progress.
+ *  2. Changing aspectRatio while scanner is running is not yet supported.
+ *
+ * @param {MediaTrackConstraints} specifies a variety of video or camera
+ *  controls as defined in
+ *  https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints
+ * @returns a Promise which succeeds if the passed constraints are applied,
+ *  fails otherwise.
+ * @throws error if the scanning is not in running state.
+ */
+public applyVideoConstraints(videoConstaints: MediaTrackConstraints)
+    : Promise<any> {}
+```
+
+These have now been taken out of beta and publicly documented. More blog articles to be published for these.
+
+#### Sponsorship
+
+Thanks <a href="https://github.com/bujjivadu"><img src="https://github.com/bujjivadu.png" width="40px" alt="" /></a> for sponsorship!
+
 ### Version 2.2.4
  - Improved support for Huawei browser with [PR#563](https://github.com/mebjas/html5-qrcode/pull/563), Contribution by [jackhe16](https://github.com/jackhe16).
  - Fixed QR Border Placement with [PR#555](https://github.com/mebjas/html5-qrcode/pull/555), Contribution by [allanbrault](https://github.com/allanbrault).

diff --git a/minified/html5-qrcode.min.js b/minified/html5-qrcode.min.js
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "html5-qrcode",
-  "version": "2.2.4",
+  "version": "2.2.5",
   "description": "A cross platform HTML5 QR Code & bar code scanner",
   "main": "./cjs/index.js",
   "module": "./esm/index.js",