@microblink/camera-manager 7.2.1 → 7.2.3

package/dist/camera-manager.js

@@ -48,28 +48,6 @@ if (typeof HTMLVideoElement !== "undefined" && !("requestVideoFrameCallback" in
     delete this._rvfcpolyfillmap[handle];
   };
 }
-const initialState$1 = {
-  cameras: [],
-  facingFilter: void 0,
-  videoElement: void 0,
-  playbackState: "idle",
-  selectedCamera: void 0,
-  isSwappingCamera: false,
-  isQueryingCameras: false,
-  mirrorX: false,
-  errorState: void 0
-};
-const cameraManagerStore = createStore()(
-  // this is important! Otherwise solid-zustand will start mutating the initial state
-  subscribeWithSelector(() => structuredClone(initialState$1))
-);
-const resetCameraManagerStore = () => {
-  console.debug("Stopping all cameras and resetting the `cameraManagerStore`.");
-  cameraManagerStore.getState().cameras.forEach((camera) => {
-    camera.stopStream();
-  });
-  cameraManagerStore.setState(structuredClone(initialState$1));
-};
 const backCameraKeywords = [
   // English
   "back",
@@ -538,6 +516,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;
@@ -741,6 +726,9 @@ function findResolutionKey(videoTrackResolution) {
   return resolutionKey;
 }
 class Camera {
+  /**
+   * The device info.
+   */
   deviceInfo;
   /**
    * Stream capabilities as reported by the stream.
@@ -774,6 +762,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");
@@ -804,6 +797,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;
@@ -827,6 +826,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 {
@@ -851,6 +853,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();
@@ -892,6 +896,11 @@ class Camera {
       }
     }
   }
+  /**
+   * Toggles the torch on the camera.
+   *
+   * @returns The torch status.
+   */
   async toggleTorch() {
     const videoTrack = this.getVideoTrack();
     if (!videoTrack) {
@@ -917,6 +926,9 @@ class Camera {
     }
     return this.torchEnabled;
   }
+  /**
+   * Stops the stream on the camera.
+   */
   stopStream() {
     if (this.activeStream) {
       console.debug(`Stopping active stream on ${this.name}`);
@@ -926,6 +938,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}.`);
@@ -934,6 +951,28 @@ class Camera {
     return this.activeStream.getVideoTracks()[0];
   }
 }
+const initialState$1 = {
+  cameras: [],
+  facingFilter: void 0,
+  videoElement: void 0,
+  playbackState: "idle",
+  selectedCamera: void 0,
+  isSwappingCamera: false,
+  isQueryingCameras: false,
+  mirrorX: false,
+  errorState: void 0
+};
+const cameraManagerStore = createStore()(
+  // this is important! Otherwise solid-zustand will start mutating the initial state
+  subscribeWithSelector(() => structuredClone(initialState$1))
+);
+const resetCameraManagerStore = () => {
+  console.debug("Stopping all cameras and resetting the `cameraManagerStore`.");
+  cameraManagerStore.getState().cameras.forEach((camera) => {
+    camera.stopStream();
+  });
+  cameraManagerStore.setState(structuredClone(initialState$1));
+};
 const ORIGINAL_ATTACH_SHADOW = Element.prototype.attachShadow;
 function isShady() {
   return typeof window.ShadyDOM !== "undefined" && typeof ShadowRoot !== "undefined";
@@ -1248,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;
@@ -1275,7 +1319,7 @@ class VideoFrameProcessor {
     }
   }
   /**
-   * Initializes the 2D canvas context
+   * Initializes the 2D canvas context.
    */
   #initialize2dContext() {
     const ctx = this.#canvas.getContext("2d", {
@@ -1286,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", {
@@ -1322,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);
@@ -1341,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) {
@@ -1350,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);
@@ -1359,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() {
@@ -1368,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)
@@ -1384,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) {
@@ -1425,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) {
@@ -1440,7 +1505,7 @@ class VideoFrameProcessor {
     }
   }
   /**
-   * Clean up resources
+   * Clean up resources.
    */
   dispose() {
     if (this.#contextWebGl2) {
@@ -1481,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;
   }
@@ -1489,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) {
@@ -1499,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,
@@ -1510,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;
@@ -1521,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
@@ -1539,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;
@@ -1556,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)) {
@@ -1636,6 +1727,8 @@ class CameraManager {
   }
   /**
    * Initializes the CameraManager with a video element.
+   *
+   * @param videoElement - The video element to initialize.
    */
   initVideoElement(videoElement) {
     try {
@@ -1652,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({
@@ -1666,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;
@@ -1711,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) {
@@ -1797,6 +1896,8 @@ class CameraManager {
   }
   /**
    * Starts playback and frame capturing.
+   *
+   * @returns resolves when frame capture starts
    */
   async #startFrameCapture() {
     const state = cameraManagerStore.getState();
@@ -1827,6 +1928,8 @@ class CameraManager {
   }
   /**
    * Starts capturing frames from the video element.
+   *
+   * @returns resolves when frame capture starts
    */
   startFrameCapture = async () => {
     try {
@@ -1839,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,
@@ -1919,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 {
@@ -1931,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({
@@ -1973,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();
@@ -2014,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();
@@ -2053,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();
@@ -2075,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");
@@ -2115,7 +2238,9 @@ const CameraUiStoreProvider = (props) => {
     // eslint-disable-next-line solid/reactivity
     showTorchButton: props.showTorchButton,
     // eslint-disable-next-line solid/reactivity
-    showCloseButton: props.showCloseButton
+    showCloseButton: props.showCloseButton,
+    // eslint-disable-next-line solid/reactivity
+    showCameraErrorModal: props.showCameraErrorModal
   };
   onCleanup(() => {
     console.debug("CameraUiStoreProvider cleanup");
@@ -2942,7 +3067,8 @@ const CAPTURE_SCREEN_SHADOW_ROOT_HOST_ID = "capture-screen-host";
 const CaptureScreen = () => {
   const {
     cameraManager,
-    mountTarget
+    mountTarget,
+    showCameraErrorModal
   } = useCameraUiStore();
   const [videoRef, setVideoRef] = createSignal();
   const [feedbackRef, setFeedbackRef] = createSignal();
@@ -3049,7 +3175,12 @@ const CaptureScreen = () => {
         use(setVideoRef, _el$6);
         use(setFeedbackRef, _el$7);
         use(setOverlayLayerRef, _el$8);
-        insert(_el$5, createComponent(CameraErrorModal, {}), null);
+        insert(_el$5, createComponent(Show, {
+          when: showCameraErrorModal,
+          get children() {
+            return createComponent(CameraErrorModal, {});
+          }
+        }), null);
         effect((_$p) => (_$p = fitMode()) != null ? _el$6.style.setProperty("object-fit", _$p) : _el$6.style.removeProperty("object-fit"));
         return _el$5;
       })()];
@@ -3135,7 +3266,8 @@ function createCameraManagerUi(cameraManager, target, {
   localizationStrings,
   showMirrorCameraButton = false,
   showTorchButton = true,
-  showCloseButton = true
+  showCloseButton = true,
+  showCameraErrorModal = true
 } = {}) {
   let mountTarget;
   const dismountCallbacks = /* @__PURE__ */ new Set();
@@ -3193,6 +3325,7 @@ function createCameraManagerUi(cameraManager, target, {
         showMirrorCameraButton,
         showTorchButton,
         showCloseButton,
+        showCameraErrorModal,
         mountTarget,
         get children() {
           return createComponent(RootComponent, {});
@@ -3277,6 +3410,7 @@ if (globalThis.__CAMERA_MANAGER__ !== testSymbol) {
 }
 export {
   Camera,
+  CameraError,
   CameraManager,
   MOUNT_POINT_ID,
   VideoFrameProcessor,