@microblink/camera-manager 7.0.0-next.9 → 7.0.0

package/types/index.rollup.d.ts

@@ -1,3 +1,5 @@
+import { Owner } from 'solid-js';
+import { Promisable } from 'type-fest';
 import { SetStoreFunction } from 'solid-js/store';
 import { StoreApi } from 'zustand/vanilla';
 
@@ -22,23 +24,53 @@ export declare class Camera {
     torchSupported: boolean;
     torchEnabled: boolean;
     singleShotSupported: boolean;
+    maxSupportedResolution?: VideoResolutionName;
+    /**
+     * Reference to the original instance before it was proxied.
+     */
     original: this;
     notify: (reason?: unknown) => void;
     notifyStateChange?: (camera: Camera, reason?: unknown) => void;
     constructor(deviceInfo: InputDeviceInfo);
-    startStream(resolution: VideoResolution): Promise<MediaStream>;
+    startStream(resolution: VideoResolutionName): Promise<MediaStream>;
+    /**
+     * Acquires a camera stream with the specified resolution.
+     * If acquisition fails, it tries a lower resolution as fallback.
+     */
+    private acquireStreamWithFallback;
+    /**
+     * Populates the camera instance with capabilities from the stream.
+     */
+    private populateCapabilities;
     toggleTorch(): Promise<boolean>;
     stopStream(): void;
     getVideoTrack(): MediaStreamTrack | undefined;
 }
 
+declare class CameraError extends Error {
+    code: CameraErrorCode;
+    constructor(message: string, code: CameraErrorCode, cause?: Error);
+}
+
+declare type CameraErrorCode = "PERMISSION_DENIED" | (string & {});
+
+declare type CameraGetter = (cameras: Camera[]) => Camera | undefined;
+
 export declare class CameraManager {
     #private;
+    get userInitiatedAbort(): boolean;
+    set userInitiatedAbort(value: boolean);
+    /**
+     * 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: ExtractionArea): void;
+    constructor(options?: Partial<CameraManagerOptions>, videoFrameProcessorOptions?: VideoFrameProcessorInitOptions);
     /**
      * Sets the resolution of the camera stream
      */
-    setResolution: (resolution: VideoResolution) => Promise<void>;
-    get resolution(): "HD" | "FHD" | "UHD";
+    setResolution: (resolution: VideoResolutionName) => Promise<void>;
+    get resolution(): "720p" | "1080p" | "4k";
     /**
      * True if there is a video playing or capturing
      * TODO: see if we can simplify this, by observing the video playback state
@@ -49,9 +81,9 @@ export declare 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.
      */
-    getCameras(): Camera[];
+    getCameraDevices(): Promise<Camera[]>;
     /**
-     * Single-time setup for a video element
+     * Initializes the CameraManager with a video element.
      */
     initVideoElement(videoElement: HTMLVideoElement): void;
     /**
@@ -62,9 +94,11 @@ export declare class CameraManager {
      * @returns a cleanup function to remove the callback
      */
     addFrameCaptureCallback(frameCaptureCallback: FrameCaptureCallback): () => boolean;
-    deinitVideoElement(): void;
+    releaseVideoElement(): void;
     /**
      * Select a camera device from available ones.
+     *
+     * TODO: might become a private method in the future as an implementation detail of `startStream`
      */
     selectCamera(camera: Camera): Promise<void>;
     /**
@@ -78,17 +112,14 @@ export declare class CameraManager {
      */
     startPlayback(): Promise<void>;
     /**
-     * Starts playback and frame capturing.
+     * Starts capturing frames from the video element.
      */
-    startFrameCapture(): Promise<void>;
+    startFrameCapture: () => Promise<void>;
     /**
      * Starts a best-effort camera stream. Will pick a camera automatically if
      * none is selected.
-     * TODO: Rename method
      */
-    startCameraStream({ autoplay, preferredCamera, preferredFacing, }?: {
-        autoplay?: boolean;
-    } & CameraPreference): Promise<void>;
+    startCameraStream(params?: StartCameraStreamOptions): Promise<void>;
     /**
      * Pauses capturing frames without pausing playback.
      */
@@ -103,9 +134,8 @@ export declare class CameraManager {
     pausePlayback(): void;
     /**
      * If true, the video and captured frames will be mirrored horizontally.
-     * TODO: apply when needed
      */
-    setMirrorX(mirrorX: boolean): void;
+    setCameraMirrorX(mirrorX: boolean): void;
     /**
      * Allows the user to subscribe to state changes inside the Camera Manager.
      * Implemented using Zustand. For usage information, see
@@ -119,7 +149,7 @@ export declare class CameraManager {
     /**
      * Resets the CameraManager and stop all streams
      */
-    destroy(): void;
+    reset(): void;
 }
 
 export declare type CameraManagerComponent = {
@@ -128,10 +158,10 @@ export declare type CameraManagerComponent = {
     updateLocalization: SetStoreFunction<CameraUiLocalizationStrings>;
     /** Dismounts the component from the DOM and unloads the SDK */
     dismount: () => void;
-    /** Sets a callback to be called when the component is unmounted */
-    addOnDismountCallback: (fn: DismountCallback) => void;
-    /** Removes a callback that was set with `addOnDismountCallback` */
-    removeOnDismountCallback: (fn: DismountCallback) => void;
+    /** Sets a callback to be called when the component is unmounted.
+     * Returns a cleanup function that removes the callback when called.
+     */
+    addOnDismountCallback: (fn: DismountCallback) => () => void;
     /**
      * The feedback layer node that can be used to append custom feedback elements
      */
@@ -140,6 +170,15 @@ export declare type CameraManagerComponent = {
      * The overlay layer node that can be used to append custom overlay elements
      */
     overlayLayerNode: HTMLDivElement;
+    /**
+     * https://docs.solidjs.com/reference/reactive-utilities/get-owner
+     */
+    owner: Owner;
+};
+
+export declare type CameraManagerOptions = {
+    /** If true, the camera stream will be mirrored horizontally when started. */
+    mirrorFrontCameras: boolean;
 };
 
 export declare type CameraManagerStore = {
@@ -179,7 +218,7 @@ export declare type CameraManagerStore = {
     /**
      * If the Camera manager has encountered an error, this will be set to the error.
      */
-    errorState?: Error;
+    errorState?: Error | CameraError;
 };
 
 /**
@@ -204,15 +243,23 @@ export declare const cameraManagerStore: Omit<StoreApi<CameraManagerStore>, "sub
     };
 };
 
+export declare type CameraManagerUiOptions = {
+    localizationStrings?: Partial<CameraUiLocalizationStrings>;
+    showMirrorCameraButton?: boolean;
+};
+
 export declare type CameraPreference = {
-    preferredCamera: Camera;
-    preferredFacing?: never;
+    preferredCamera: Camera | undefined;
+    preferredFacing?: undefined;
+} | {
+    preferredCamera: CameraGetter | undefined;
+    preferredFacing?: undefined;
 } | {
     preferredFacing: FacingMode;
-    preferredCamera?: never;
+    preferredCamera?: undefined;
 } | {
-    preferredCamera?: never;
-    preferredFacing?: never;
+    preferredCamera?: undefined;
+    preferredFacing?: undefined;
 };
 
 export declare type CameraUiLocaleRecord = typeof _default;
@@ -221,12 +268,10 @@ export declare type CameraUiLocalizationStrings = {
     [K in keyof CameraUiLocaleRecord]: CameraUiLocaleRecord[K] | (string & {});
 };
 
-/**
- * Copyright (c) 2025 Microblink Ltd. All rights reserved.
- */
 export declare type CameraUiRefs = {
     feedbackLayer: HTMLDivElement;
     overlayLayer: HTMLDivElement;
+    owner: Owner;
 };
 
 export declare const cameraUiRefStore: Omit<StoreApi<CameraUiRefs>, "subscribe"> & {
@@ -239,28 +284,74 @@ export declare const cameraUiRefStore: Omit<StoreApi<CameraUiRefs>, "subscribe">
     };
 };
 
+/**
+ * Copyright (c) 2025 Microblink Ltd. All rights reserved.
+ */
+export declare type CanvasRenderingMode = "2d" | "webgl2";
+
 /**
  * Creates a new Camera Manager UI component.
  */
-export declare function createCameraManagerUi(cameraManager: CameraManager, target?: HTMLElement): Promise<CameraManagerComponent>;
+export declare function createCameraManagerUi(cameraManager: CameraManager, target?: HTMLElement, { localizationStrings, showMirrorCameraButton, }?: CameraManagerUiOptions): Promise<CameraManagerComponent>;
 
 /**
  * Copyright (c) 2025 Microblink Ltd. All rights reserved.
  */
 declare const _default: {
     readonly selected_camera: "Selected camera";
+    readonly loading_cameras: "Loading cameras...";
+    readonly select_a_camera: "Select a camera";
     readonly select_camera: "Select camera";
     readonly close: "Close";
     readonly torch: "Torch";
     readonly mirror_camera: "Mirror camera";
-    readonly modal_title: "Scan a document";
+    readonly scan_document: "Scan a document";
+    readonly camera_error_title: "Camera permission required";
+    readonly camera_error_details: "Please allow camera access in your browser and try again.";
+    readonly camera_error_cancel_btn: "Cancel";
+    readonly camera_error_primary_btn: "Retry";
 };
 
-declare type DismountCallback = () => void;
+export declare const defaultCameraManagerOptions: CameraManagerOptions;
+
+export declare type DismountCallback = () => void;
 
+export declare type ExtractionArea = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+
+/**
+ * Copyright (c) 2025 Microblink Ltd. All rights reserved.
+ */
 export declare type FacingMode = "front" | "back" | undefined;
 
-export declare type FrameCaptureCallback = (frame: ImageData) => void | Promise<void>;
+export declare function findResolutionKey(videoTrackResolution: Resolution): VideoResolutionName;
+
+export declare type FrameCaptureCallback = (frame: ImageData) => Promisable<ArrayBufferLike | void>;
+
+/**
+ * Converts a view to a buffer, since both match the type signature of
+ * `ArrayBufferLike`.
+ * @param buffer - The buffer or view to convert
+ * @returns The actual underlying buffer
+ */
+export declare const getBuffer: (buffer: ArrayBufferLike) => ArrayBufferLike;
+
+export declare function getNormalizedResolution(resolution: Resolution): Resolution;
+
+export declare type ImageSource = HTMLVideoElement | HTMLCanvasElement | ImageBitmap;
+
+/**
+ * Check if an ArrayBuffer is detached
+ * @param buffer - ArrayBuffer to check
+ * @returns true if the buffer is detached, false otherwise
+ */
+export declare function isBufferDetached(buffer: ArrayBuffer): boolean;
+
+export declare function matchClosestResolution(resolution: Resolution): VideoResolutionName;
 
 export declare const MOUNT_POINT_ID = "camera-manager-mount-point";
 
@@ -272,23 +363,72 @@ export declare type PlaybackState = "idle" | "playback" | "capturing";
  */
 export declare const resetCameraManagerStore: () => void;
 
-export declare type VideoResolution = keyof typeof videoResolutions;
+export declare type Resolution = {
+    width: number;
+    height: number;
+};
+
+export declare function returnLongerSide(resolution: Resolution): number;
+
+export declare type StartCameraStreamOptions = {
+    autoplay?: boolean;
+} & CameraPreference;
+
+/**
+ * VideoFrameProcessor captures frames from video or image sources using either 2D or WebGL2 rendering
+ */
+export declare class VideoFrameProcessor {
+    #private;
+    constructor(options?: VideoFrameProcessorInitOptions);
+    /**
+     * 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
+     */
+    reattachArrayBuffer(arrayBuffer: ArrayBufferLike): void;
+    /**
+     * Used to check if the processor owns the buffer
+     */
+    isBufferDetached(): boolean;
+    /**
+     * Extracts image data from a source element
+     */
+    getImageData(source: ImageSource, area?: ExtractionArea): ImageData;
+    /**
+     * 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(): ImageData;
+    /**
+     * Clean up resources
+     */
+    dispose(): void;
+}
+
+export declare type VideoFrameProcessorInitOptions = {
+    canvasRenderingMode?: CanvasRenderingMode;
+    fallbackWebGlTo2d?: boolean;
+};
+
+export declare type VideoResolutionName = keyof typeof videoResolutions;
 
 /**
  * Available video resolutions for the camera stream.
  */
 export declare const videoResolutions: {
-    HD: {
-        width: number;
-        height: number;
+    readonly "720p": {
+        readonly width: 1280;
+        readonly height: 720;
     };
-    FHD: {
-        width: number;
-        height: number;
+    readonly "1080p": {
+        readonly width: 1920;
+        readonly height: 1080;
     };
-    UHD: {
-        width: number;
-        height: number;
+    readonly "4k": {
+        readonly width: 3840;
+        readonly height: 2160;
     };
 };