@microblink/camera-manager 7.2.0 → 7.2.2

package/dist/camera-manager.js

@@ -538,6 +538,13 @@ const asError = (thrown) => {
 };
 class CameraError extends Error {
   code;
+  /**
+   * Creates a new camera error.
+   *
+   * @param message - The error message.
+   * @param code - The error code.
+   * @param cause - The cause of the error.
+   */
   constructor(message, code, cause) {
     super(message);
     this.code = code;
@@ -600,12 +607,40 @@ const createConstraints = (resolution, facing, id) => {
   };
   return constraints;
 };
+function scoreCameraCapabilities(camera) {
+  let score = 0;
+  if (camera.torchSupported) score += 1;
+  if (camera.singleShotSupported) score += 1;
+  return score;
+}
+function filterCamerasByFacing(cameras, requestedFacing) {
+  return cameras.filter((camera) => {
+    if (requestedFacing === "back" || requestedFacing === void 0) {
+      return isBackCameraName(camera.name);
+    } else {
+      return isFrontCameraName(camera.name);
+    }
+  });
+}
 const findIdealCamera = async (cameras, resolution = "4k", requestedFacing = "back") => {
   if (cameras.length === 0) {
     throw new Error("No cameras found");
   }
+  if (cameras.length === 1) {
+    await cameras[0].startStream(resolution);
+    return cameras[0];
+  }
+  let cameraPool = filterCamerasByFacing(cameras, requestedFacing);
+  if (cameraPool.length === 1) {
+    await cameraPool[0].startStream(resolution);
+    return cameraPool[0];
+  }
+  if (cameraPool.length === 0) {
+    console.debug("No camera found with requested facing, using all cameras");
+    cameraPool = cameras;
+  }
   if (requestedFacing === "back") {
-    const dualWideCamera = cameras.find(
+    const dualWideCamera = cameraPool.find(
       (camera) => backDualWideCameraLocalizations.includes(camera.name)
     );
     if (dualWideCamera) {
@@ -613,65 +648,44 @@ const findIdealCamera = async (cameras, resolution = "4k", requestedFacing = "ba
       return dualWideCamera;
     }
   }
-  const cameraPool = cameras.filter((camera) => {
-    if (requestedFacing === "back" || requestedFacing === void 0) {
-      return isBackCameraName(camera.name);
-    } else {
-      return isFrontCameraName(camera.name);
-    }
-  });
-  if (cameraPool.length === 1 && cameraPool[0].facingMode === requestedFacing) {
-    await cameraPool[0].startStream(resolution);
-    return cameraPool[0];
-  }
-  if (cameraPool.length > 0 && requestedFacing === "front") {
+  if (requestedFacing === "front") {
     const lastCamera = cameraPool[cameraPool.length - 1];
     await lastCamera.startStream(resolution);
     return lastCamera;
   }
-  if (cameraPool.length === 0) {
-    console.debug("No camera found with requested facing, using all cameras");
-    cameraPool.push(...cameras);
-  }
   const cameraScores = /* @__PURE__ */ new Map();
-  cameras.forEach((camera) => cameraScores.set(camera, 0));
+  let bestCamera;
+  let maxScore = -Infinity;
   for (let i = cameraPool.length - 1; i >= 0; i--) {
     const camera = cameraPool[i];
-    await camera.startStream(resolution);
-    if (!camera.facingMode) {
-      console.debug("No facing mode, returning last camera");
-      return camera;
-    }
-    if (camera.facingMode && camera.facingMode !== requestedFacing) {
-      console.debug("Mismatched facing mode, moving on to the next camera");
-      camera.stopStream();
-      continue;
-    }
-    if (camera.torchSupported && camera.singleShotSupported) {
-      console.debug("Camera supports torch and single shot, returning");
-      return camera;
-    }
-    if (camera.torchSupported) {
-      cameraScores.set(camera, cameraScores.get(camera) + 1);
-    }
-    if (camera.singleShotSupported) {
-      cameraScores.set(camera, cameraScores.get(camera) + 1);
-    }
-    if (i === 0) {
-      console.debug("Last camera in the pool, picking the best one");
-      let maxKey;
-      let maxValue = -Infinity;
-      cameraScores.forEach((score, camera2) => {
-        if (score > maxValue) {
-          maxValue = score;
-          maxKey = camera2;
+    try {
+      await camera.startStream(resolution);
+      const score = scoreCameraCapabilities(camera);
+      cameraScores.set(camera, score);
+      if (score > maxScore) {
+        if (bestCamera && bestCamera !== camera) {
+          bestCamera.stopStream();
         }
-      });
-      return maxKey;
+        maxScore = score;
+        bestCamera = camera;
+      } else {
+        camera.stopStream();
+      }
+      if (score === 2) {
+        console.debug("Found camera with all capabilities, returning early");
+        return camera;
+      }
+    } catch (error) {
+      console.warn(`Failed to test camera ${camera.name}:`, error);
+      camera.stopStream();
     }
-    camera.stopStream();
   }
-  throw new Error("No camera found, should not happen");
+  if (bestCamera) {
+    return bestCamera;
+  }
+  const firstCamera = cameraPool[0];
+  await firstCamera.startStream(resolution);
+  return firstCamera;
 };
 function createCameras(cameras) {
   const camerasWithStream = [];
@@ -734,6 +748,9 @@ function findResolutionKey(videoTrackResolution) {
   return resolutionKey;
 }
 class Camera {
+  /**
+   * The device info.
+   */
   deviceInfo;
   /**
    * Stream capabilities as reported by the stream.
@@ -767,6 +784,11 @@ class Camera {
    * @deprecated Not used. Reconsider using once Firefox and Chrome align on this.
    */
   #deviceCapabilities;
+  /**
+   * Creates a new Camera instance.
+   *
+   * @param deviceInfo - The device info.
+   */
   constructor(deviceInfo) {
     if (deviceInfo.kind !== "videoinput") {
       throw new Error("Device is not a video input device");
@@ -797,6 +819,12 @@ class Camera {
     };
     return proxy;
   }
+  /**
+   * Starts a stream with the specified resolution.
+   *
+   * @param resolution - The resolution to start the stream with.
+   * @returns The stream.
+   */
   async startStream(resolution) {
     if (this.activeStream) {
       return this.activeStream;
@@ -820,6 +848,9 @@ class Camera {
   /**
    * Acquires a camera stream with the specified resolution.
    * If acquisition fails, it tries a lower resolution as fallback.
+   *
+   * @param resolution - The resolution to acquire the stream with.
+   * @returns The stream.
    */
   async acquireStreamWithFallback(resolution) {
     try {
@@ -844,6 +875,8 @@ class Camera {
   }
   /**
    * Populates the camera instance with capabilities from the stream.
+   *
+   * @param stream - The stream to populate the capabilities from.
    */
   populateCapabilities(stream) {
     this.streamCapabilities = stream.getVideoTracks()[0].getCapabilities();
@@ -885,6 +918,11 @@ class Camera {
       }
     }
   }
+  /**
+   * Toggles the torch on the camera.
+   *
+   * @returns The torch status.
+   */
   async toggleTorch() {
     const videoTrack = this.getVideoTrack();
     if (!videoTrack) {
@@ -910,6 +948,9 @@ class Camera {
     }
     return this.torchEnabled;
   }
+  /**
+   * Stops the stream on the camera.
+   */
   stopStream() {
     if (this.activeStream) {
       console.debug(`Stopping active stream on ${this.name}`);
@@ -919,6 +960,11 @@ class Camera {
       this.torchEnabled = false;
     }
   }
+  /**
+   * Gets the video track on the camera.
+   *
+   * @returns The video track.
+   */
   getVideoTrack() {
     if (!this.activeStream) {
       console.warn(`No active stream on Camera instance: ${this.name}.`);
@@ -1241,6 +1287,11 @@ class VideoFrameProcessor {
   #cachedHeight = 0;
   #canvasRenderingMode;
   #requiredPackAlignment = 4;
+  /**
+   * Creates a new VideoFrameProcessor.
+   *
+   * @param options - The options for the VideoFrameProcessor.
+   */
   constructor(options = {}) {
     const { canvasRenderingMode = "webgl2", fallbackWebGlTo2d = true } = options;
     this.#canvasRenderingMode = canvasRenderingMode;
@@ -1268,7 +1319,7 @@ class VideoFrameProcessor {
     }
   }
   /**
-   * Initializes the 2D canvas context
+   * Initializes the 2D canvas context.
    */
   #initialize2dContext() {
     const ctx = this.#canvas.getContext("2d", {
@@ -1279,7 +1330,7 @@ class VideoFrameProcessor {
     this.#context2d = ctx;
   }
   /**
-   * Initializes the WebGL2 context and resources
+   * Initializes the WebGL2 context and resources.
    */
   #initializeWebGl2Context() {
     const ctx = this.#canvas.getContext("webgl2", {
@@ -1315,9 +1366,12 @@ class VideoFrameProcessor {
     );
   }
   /**
-   * Returns ownership of an ArrayBuffer to the processor for reuse
-   * This should only be called with ArrayBuffers that were originally from this processor
-   * Typically used after transferring the buffer to/from a worker
+   * Returns ownership of an ArrayBuffer to the processor for reuse.
+   *
+   * This should only be called with ArrayBuffers that were originally from this processor.
+   * Typically used after transferring the buffer to/from a worker.
+   *
+   * @param arrayBuffer - The array buffer to reattach.
    */
   reattachArrayBuffer(arrayBuffer) {
     const actualBuffer = getBuffer(arrayBuffer);
@@ -1334,7 +1388,9 @@ class VideoFrameProcessor {
     }
   }
   /**
-   * Used to check if the processor owns the buffer
+   * Used to check if the processor owns the buffer.
+   *
+   * @returns true if the processor owns the buffer, false otherwise.
    */
   isBufferDetached() {
     if (!this.#buffer) {
@@ -1343,7 +1399,11 @@ class VideoFrameProcessor {
     return isBufferDetached(this.#buffer.buffer);
   }
   /**
-   * Extracts image data from a source element
+   * Extracts image data from a source element.
+   *
+   * @param source - The source element to extract image data from.
+   * @param area - The extraction area.
+   * @returns The image data.
    */
   getImageData(source, area) {
     return this.#canvasRenderingMode === "2d" ? this.#getImageData2d(source, area) : this.#getImageDataWebGl2(source, area);
@@ -1352,6 +1412,7 @@ class VideoFrameProcessor {
    * Used to get the current ImageData object with the current buffer. Useful
    * when you need to get the same `ImageData` object multiple times after the
    * original `ImageData` buffer has been detached
+   *
    * @returns ImageData object with the current buffer
    */
   getCurrentImageData() {
@@ -1361,7 +1422,11 @@ class VideoFrameProcessor {
     return new ImageData(this.#buffer, this.#cachedWidth, this.#cachedHeight);
   }
   /**
-   * Extract image data using 2D canvas
+   * Extract image data using 2D canvas.
+   *
+   * @param source - The source element to extract image data from.
+   * @param area - The extraction area.
+   * @returns The image data.
    */
   #getImageData2d(source, area) {
     if (!this.#context2d)
@@ -1377,7 +1442,11 @@ class VideoFrameProcessor {
     return this.#context2d.getImageData(0, 0, w, h);
   }
   /**
-   * Extract image data using WebGL2
+   * Extract image data using WebGL2.
+   *
+   * @param source - The source element to extract image data from.
+   * @param area - The extraction area.
+   * @returns The image data.
    */
   #getImageDataWebGl2(source, area) {
     if (!this.#contextWebGl2 || !this.#webGl2Texture || !this.#webGl2Framebuffer) {
@@ -1418,9 +1487,12 @@ class VideoFrameProcessor {
     return new ImageData(this.#buffer, w, h);
   }
   /**
-   * Update canvas dimensions if needed
+   * Update canvas dimensions if needed.
+   *
+   * This canvas is the orientation-aware.
    *
-   * This canvas is the orientation-aware
+   * @param width - The width of the canvas.
+   * @param height - The height of the canvas.
    */
   #updateCanvasSize(width, height) {
     if (this.#cachedWidth !== width || this.#cachedHeight !== height) {
@@ -1433,7 +1505,7 @@ class VideoFrameProcessor {
     }
   }
   /**
-   * Clean up resources
+   * Clean up resources.
    */
   dispose() {
     if (this.#contextWebGl2) {
@@ -1474,6 +1546,10 @@ class CameraManager {
    * CameraManager from throwing errors when the user interrupts the process.
    */
   #userInitiatedAbort = false;
+  /**
+   * If true, the user has initiated an abort. This will prevent the
+   * CameraManager from throwing errors when the user interrupts the process.
+   */
   get userInitiatedAbort() {
     return this.#userInitiatedAbort;
   }
@@ -1482,6 +1558,7 @@ class CameraManager {
   }
   /**
    * Sets the area of the video frame that will be extracted.
+   *
    * @param extractionArea The area of the video frame that will be extracted.
    */
   setExtractionArea(extractionArea) {
@@ -1492,6 +1569,12 @@ class CameraManager {
    * "capturing".
    */
   #frameCaptureCallbacks = /* @__PURE__ */ new Set();
+  /**
+   * Creates a new CameraManager instance.
+   *
+   * @param options - The options for the CameraManager.
+   * @param videoFrameProcessorOptions - The options for the VideoFrameProcessor.
+   */
   constructor(options = {}, videoFrameProcessorOptions) {
     const { mirrorFrontCameras } = {
       ...defaultCameraManagerOptions,
@@ -1503,7 +1586,9 @@ class CameraManager {
     this.#mirrorFrontCameras = mirrorFrontCameras;
   }
   /**
-   * Sets the resolution of the camera stream
+   * Sets the resolution of the camera stream.
+   *
+   * @param resolution - The resolution to set.
    */
   setResolution = async (resolution) => {
     this.#resolution = resolution;
@@ -1514,16 +1599,25 @@ class CameraManager {
       await this.startCameraStream();
     }
   };
+  /**
+   * The resolution of the camera stream.
+   */
   get resolution() {
     return this.#resolution;
   }
   /**
    * True if there is a video playing or capturing
-   * TODO: see if we can simplify this, by observing the video playback state
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaSession/playbackState for more details.
    */
   get isActive() {
     return cameraManagerStore.getState().playbackState !== "idle";
   }
+  /**
+   * Sets the facing filter.
+   *
+   * @param facingFilter - The facing filter.
+   */
   setFacingFilter(facingFilter) {
     cameraManagerStore.setState({
       facingFilter
@@ -1532,6 +1626,8 @@ class CameraManager {
   /**
    * Returns the cameras that are available to the user, filtered by the facing mode.
    * If no facing mode is set, all cameras are returned.
+   *
+   * @returns The cameras that are available to the user, filtered by the facing mode.
    */
   async getCameraDevices() {
     let allCameras = cameraManagerStore.getState().cameras;
@@ -1549,7 +1645,9 @@ class CameraManager {
     return filteredCameras;
   }
   /**
-   * Single-time setup for a video element
+   * Single-time setup for a video element.
+   *
+   * @param videoElement - The video element to initialize.
    */
   #initVideoElement(videoElement) {
     if (!(videoElement instanceof HTMLVideoElement)) {
@@ -1629,6 +1727,8 @@ class CameraManager {
   }
   /**
    * Initializes the CameraManager with a video element.
+   *
+   * @param videoElement - The video element to initialize.
    */
   initVideoElement(videoElement) {
     try {
@@ -1645,13 +1745,16 @@ class CameraManager {
    * Adds a callback that will be triggered on each frame when the playback state
    * is "capturing".
    *
-   * @param frameCaptureCallback
+   * @param frameCaptureCallback - The callback to add.
    * @returns a cleanup function to remove the callback
    */
   addFrameCaptureCallback(frameCaptureCallback) {
     this.#frameCaptureCallbacks.add(frameCaptureCallback);
     return () => this.#frameCaptureCallbacks.delete(frameCaptureCallback);
   }
+  /**
+   * Cleans up the video element, and stops the stream.
+   */
   releaseVideoElement() {
     this.#eventListenerCleanup?.();
     cameraManagerStore.setState({
@@ -1659,10 +1762,11 @@ class CameraManager {
     });
     this.stopStream();
   }
+  // TODO: might become a private method in the future as an implementation detail of `startStream`
   /**
    * Select a camera device from available ones.
    *
-   * TODO: might become a private method in the future as an implementation detail of `startStream`
+   * @param camera - The camera to select.
    */
   async selectCamera(camera) {
     const playbackState = cameraManagerStore.getState().playbackState;
@@ -1704,6 +1808,8 @@ class CameraManager {
   }
   /**
    * Refreshes available devices on the system and updates the state.
+   *
+   * @returns resolves when the camera devices are refreshed
    */
   async refreshCameraDevices() {
     if (cameraManagerStore.getState().isQueryingCameras || cameraManagerStore.getState().isSwappingCamera) {
@@ -1790,6 +1896,8 @@ class CameraManager {
   }
   /**
    * Starts playback and frame capturing.
+   *
+   * @returns resolves when frame capture starts
    */
   async #startFrameCapture() {
     const state = cameraManagerStore.getState();
@@ -1820,6 +1928,8 @@ class CameraManager {
   }
   /**
    * Starts capturing frames from the video element.
+   *
+   * @returns resolves when frame capture starts
    */
   startFrameCapture = async () => {
     try {
@@ -1832,6 +1942,12 @@ class CameraManager {
       }
     }
   };
+  /**
+   * Starts a camera stream.
+   *
+   * @param params - The parameters for the camera stream.
+   * @returns resolves when the camera stream starts
+   */
   async #startCameraStream({
     autoplay = true,
     preferredCamera,
@@ -1912,6 +2028,9 @@ class CameraManager {
   /**
    * Starts a best-effort camera stream. Will pick a camera automatically if
    * none is selected.
+   *
+   * @param params - The parameters for the camera stream.
+   * @returns resolves when the camera stream starts
    */
   async startCameraStream(params = {}) {
     try {
@@ -1924,12 +2043,17 @@ class CameraManager {
       }
     }
   }
+  /**
+   * Checks if the error state is a permission error.
+   *
+   * @returns true if the error state is a permission error
+   */
   #hasPermissionError = () => {
     const errorState = cameraManagerStore.getState().errorState;
     return errorState instanceof CameraError && errorState.code === "PERMISSION_DENIED";
   };
   /**
-   * Pauses capturing frames without pausing playback.
+   * Pauses capturing frames, without stopping playback.
    */
   stopFrameCapture() {
     cameraManagerStore.setState({
@@ -1966,7 +2090,7 @@ class CameraManager {
     video.pause();
   }
   /**
-   * The main recognition loop. Do not call this method directly, use #queueFrame instead.
+   * The main recognition loop. Do not call this method directly, use `#queueFrame` instead.
    */
   async #loop() {
     const state = cameraManagerStore.getState();
@@ -2007,7 +2131,7 @@ class CameraManager {
     this.#queueFrame();
   }
   /**
-   * Queues the next frame to be processed
+   * Queues the next frame to be processed.
    */
   #queueFrame() {
     const state = cameraManagerStore.getState();
@@ -2046,6 +2170,8 @@ class CameraManager {
   }
   /**
    * If true, the video and captured frames will be mirrored horizontally.
+   *
+   * @param mirrorX - If true, the video and captured frames will be mirrored horizontally.
    */
   setCameraMirrorX(mirrorX) {
     const currentState = cameraManagerStore.getState();
@@ -2068,15 +2194,19 @@ class CameraManager {
   /**
    * Allows the user to subscribe to state changes inside the Camera Manager.
    * Implemented using Zustand. For usage information, see
-   * {@link https://github.com/pmndrs/zustand#using-subscribe-with-selector}
+   * @see https://github.com/pmndrs/zustand#using-subscribe-with-selector for more details.
+   *
+   * @returns a cleanup function to remove the subscription
    */
   subscribe = cameraManagerStore.subscribe;
   /**
    * Gets the current internal state of the CameraManager.
+   *
+   * @returns the current state of the CameraManager
    */
   getState = cameraManagerStore.getState;
   /**
-   * Resets the CameraManager and stop all streams
+   * Resets the CameraManager and stops all streams.
    */
   reset() {
     console.debug("Resetting camera manager");