@microblink/camera-manager 7.2.4 → 7.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microblink/camera-manager",
-  "version": "7.2.4",
+  "version": "7.2.5",
   "author": "Microblink",
   "type": "module",
   "main": "./dist/camera-manager.js",

package/types/index.rollup.d.ts

@@ -0,0 +1,711 @@
+import { Owner } from 'solid-js';
+import { Promisable } from 'type-fest';
+import { SetStoreFunction } from 'solid-js/store';
+import { StoreApi } from 'zustand/vanilla';
+
+/**
+ * Represents a camera device and its active stream.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/getCapabilities for more details.
+ */
+export declare class Camera {
+    #private;
+    /**
+     * The device info.
+     */
+    deviceInfo: InputDeviceInfo;
+    /**
+     * Stream capabilities as reported by the stream.
+     *
+     * On iOS it's the same as `deviceCapabilities`. Firefox is only reporting
+     * rudimentary capabilities, so we can't rely on this for picking the right
+     * camera.
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/getCapabilities
+     */
+    streamCapabilities?: ReturnType<MediaStreamTrack["getCapabilities"]>;
+    activeStream: MediaStream | undefined;
+    name: string;
+    facingMode: FacingMode;
+    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;
+    /**
+     * Creates a new Camera instance.
+     *
+     * @param deviceInfo - The device info.
+     */
+    constructor(deviceInfo: InputDeviceInfo);
+    /**
+     * Starts a stream with the specified resolution.
+     *
+     * @param resolution - The resolution to start the stream with.
+     * @returns The stream.
+     */
+    startStream(resolution: VideoResolutionName): Promise<MediaStream>;
+    /**
+     * 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.
+     */
+    private acquireStreamWithFallback;
+    /**
+     * Populates the camera instance with capabilities from the stream.
+     *
+     * @param stream - The stream to populate the capabilities from.
+     */
+    private populateCapabilities;
+    /**
+     * Toggles the torch on the camera.
+     *
+     * @returns The torch status.
+     */
+    toggleTorch(): Promise<boolean>;
+    /**
+     * Stops the stream on the camera.
+     */
+    stopStream(): void;
+    /**
+     * Gets the video track on the camera.
+     *
+     * @returns The video track.
+     */
+    getVideoTrack(): MediaStreamTrack | undefined;
+}
+
+/**
+ * A camera error.
+ */
+export declare class CameraError extends Error {
+    code: CameraErrorCode;
+    /**
+     * Creates a new camera error.
+     *
+     * @param message - The error message.
+     * @param code - The error code.
+     * @param cause - The cause of the error.
+     */
+    constructor(message: string, code: CameraErrorCode, cause?: Error);
+}
+
+/**
+ * Copyright (c) 2025 Microblink Ltd. All rights reserved.
+ */
+/**
+ * A camera error code.
+ */
+export declare type CameraErrorCode = "PERMISSION_DENIED" | (string & {});
+
+/**
+ * A camera getter.
+ *
+ * @param cameras - The cameras to get.
+ * @returns The camera.
+ */
+declare type CameraGetter = (cameras: Camera[]) => Camera | undefined;
+
+/**
+ * The CameraManager class.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/getCapabilities for more details.
+ */
+export declare class CameraManager {
+    #private;
+    /**
+     * If true, the user has initiated an abort. This will prevent the
+     * CameraManager from throwing errors when the user interrupts the process.
+     */
+    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;
+    /**
+     * Creates a new CameraManager instance.
+     *
+     * @param options - The options for the CameraManager.
+     * @param videoFrameProcessorOptions - The options for the VideoFrameProcessor.
+     */
+    constructor(options?: Partial<CameraManagerOptions>, videoFrameProcessorOptions?: VideoFrameProcessorInitOptions);
+    /**
+     * Sets the desired video resolution for camera streams. This is used as the ideal resolution
+     * when starting camera streams. If a camera doesn't support the specified resolution,
+     * the camera will automatically fall back to the next lower supported resolution in this order:
+     * 4k → 1080p → 720p. If there's an active stream, it will be restarted with the new resolution.
+     *
+     * @param resolution - The ideal resolution to set for camera streams.
+     */
+    setResolution: (resolution: VideoResolutionName) => Promise<void>;
+    /**
+     * The desired video resolution for camera streams. This is used as the ideal resolution
+     * when starting camera streams. If a camera doesn't support the specified resolution,
+     * the camera will automatically fall back to the next lower supported resolution in this order:
+     * 4k → 1080p → 720p. The actual resolution used may differ from this setting based on
+     * camera capabilities and system constraints.
+     */
+    get resolution(): "720p" | "1080p" | "4k";
+    /**
+     * True if there is a video playing or capturing
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaSession/playbackState for more details.
+     */
+    get isActive(): boolean;
+    /**
+     * Sets the facing filter.
+     *
+     * @param facingFilter - The facing filter.
+     */
+    setFacingFilter(facingFilter: FacingMode[]): void;
+    /**
+     * 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.
+     */
+    getCameraDevices(): Promise<Camera[]>;
+    /**
+     * Initializes the CameraManager with a video element.
+     *
+     * @param videoElement - The video element to initialize.
+     */
+    initVideoElement(videoElement: HTMLVideoElement): void;
+    /**
+     * Adds a callback that will be triggered on each frame when the playback state
+     * is "capturing".
+     *
+     * @param frameCaptureCallback - The callback to add.
+     * @returns a cleanup function to remove the callback
+     */
+    addFrameCaptureCallback(frameCaptureCallback: FrameCaptureCallback): () => boolean;
+    /**
+     * Cleans up the video element, and stops the stream.
+     */
+    releaseVideoElement(): void;
+    /**
+     * Select a camera device from available ones.
+     *
+     * @param camera - The camera to select.
+     */
+    selectCamera(camera: Camera): Promise<void>;
+    /**
+     * Refreshes available devices on the system and updates the state.
+     *
+     * @returns resolves when the camera devices are refreshed
+     */
+    refreshCameraDevices(): Promise<void>;
+    /**
+     * Starts the video playback
+     *
+     * @returns resolves when playback starts
+     */
+    startPlayback(): Promise<void>;
+    /**
+     * Starts capturing frames from the video element.
+     *
+     * @returns resolves when frame capture starts
+     */
+    startFrameCapture: () => Promise<void>;
+    /**
+     * 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
+     */
+    startCameraStream(params?: StartCameraStreamOptions): Promise<void>;
+    /**
+     * Pauses capturing frames, without stopping playback.
+     */
+    stopFrameCapture(): void;
+    /**
+     * Stops the currently active stream. Also stops the video playback and capturing process.
+     */
+    stopStream(): void;
+    /**
+     * Pauses the video playback. This will also stop the capturing process.
+     */
+    pausePlayback(): void;
+    /**
+     * 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: boolean): void;
+    /**
+     * Allows the user to subscribe to state changes inside the Camera Manager.
+     * Implemented using Zustand. For usage information, see
+     * @see https://github.com/pmndrs/zustand#using-subscribe-with-selector for more details.
+     *
+     * @returns a cleanup function to remove the subscription
+     */
+    subscribe: typeof cameraManagerStore.subscribe;
+    /**
+     * Gets the current internal state of the CameraManager.
+     *
+     * @returns the current state of the CameraManager
+     */
+    getState: typeof cameraManagerStore.getState;
+    /**
+     * Resets the CameraManager and stops all streams.
+     */
+    reset(): void;
+}
+
+/**
+ * The camera manager component.
+ */
+export declare type CameraManagerComponent = {
+    /** The camera manager. */
+    cameraManager: CameraManager;
+    /** Updates the localization strings */
+    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.
+     * 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
+     */
+    feedbackLayerNode: HTMLDivElement;
+    /**
+     * The overlay layer node that can be used to append custom overlay elements
+     */
+    overlayLayerNode: HTMLDivElement;
+    /**
+     * The owner of the component.
+     *
+     * @see https://docs.solidjs.com/reference/reactive-utilities/get-owner
+     */
+    owner: Owner;
+};
+
+/**
+ * Options for the CameraManager.
+ *
+ * @param mirrorFrontCameras - If true, front-facing cameras will be mirrored horizontally when started.
+ * @param preferredResolution - The desired video resolution for camera streams. This is used as the ideal resolution when starting camera streams. If a camera doesn't support the specified resolution, the camera will automatically fall back to the next lower supported resolution in this order: 4k → 1080p → 720p.
+ */
+export declare type CameraManagerOptions = {
+    /** If true, the camera stream will be mirrored horizontally when started. */
+    mirrorFrontCameras: boolean;
+    /**
+     * The desired video resolution for camera streams. This is used as the ideal resolution
+     * when starting camera streams. If a camera doesn't support the specified resolution,
+     * the camera will automatically fall back to the next lower supported resolution in this order:
+     * 4k → 1080p → 720p. The actual resolution used may differ from this setting based on
+     * camera capabilities and system constraints.
+     */
+    preferredResolution: VideoResolutionName;
+};
+
+/**
+ * The camera manager store.
+ */
+export declare type CameraManagerStore = {
+    /**
+     * The video element that will display the camera stream.
+     */
+    videoElement?: HTMLVideoElement;
+    /**
+     * The list of cameras that are available to the user.
+     */
+    cameras: Camera[];
+    /**
+     * The facing mode filter that will be used to filter the available cameras.
+     * Can be a single facing mode or an array of facing modes.
+     */
+    facingFilter?: FacingMode[];
+    /**
+     * The currently selected camera.
+     */
+    selectedCamera?: Camera;
+    /**
+     * Capturing / playing / idle.
+     */
+    playbackState: PlaybackState;
+    /**
+     * Indicates if the camera is currently being swapped.
+     */
+    isSwappingCamera: boolean;
+    /**
+     * Indicates if camera list is currently being queried.
+     */
+    isQueryingCameras: boolean;
+    /**
+     * Indicates if the captured frames will be mirrored horizontally
+     */
+    mirrorX: boolean;
+    /**
+     * If the Camera manager has encountered an error, this will be set to the error.
+     */
+    errorState?: Error | CameraError;
+};
+
+/**
+ * ⚠️ DANGER AHEAD ⚠️
+ *
+ * The Zustand store. Use only if you know what you're doing.
+ *
+ * Never set the state as this will break the application logic. We do not have
+ * two-way binding. Make sure you only observe the state.
+ *
+ * Prefer using subscriptions if you require observable state.
+ *
+ * @see https://github.com/pmndrs/zustand for more details.
+ */
+export declare const cameraManagerStore: Omit<StoreApi<CameraManagerStore>, "subscribe"> & {
+    subscribe: {
+        (listener: (selectedState: CameraManagerStore, previousSelectedState: CameraManagerStore) => void): () => void;
+        <U>(selector: (state: CameraManagerStore) => U, listener: (selectedState: U, previousSelectedState: U) => void, options?: {
+            equalityFn?: ((a: U, b: U) => boolean) | undefined;
+            fireImmediately?: boolean;
+        } | undefined): () => void;
+    };
+};
+
+/**
+ * The camera manager UI options.
+ */
+export declare type CameraManagerUiOptions = {
+    /**
+     * The localization strings.
+     */
+    localizationStrings?: Partial<CameraUiLocalizationStrings>;
+    /**
+     * If set to `true`, the mirror camera button will be shown.
+     *
+     * @defaultValue false
+     */
+    showMirrorCameraButton?: boolean;
+    /**
+     * If set to `true`, the torch button will be shown.
+     *
+     * @defaultValue true
+     */
+    showTorchButton?: boolean;
+    /**
+     * If set to `true`, the close button will be shown.
+     *
+     * @defaultValue true
+     */
+    showCloseButton?: boolean;
+    /**
+     * If set to `true`, the camera error modal will be shown.
+     *
+     * @defaultValue true
+     */
+    showCameraErrorModal?: boolean;
+};
+
+/**
+ * A camera preference.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/facingMode for facing mode details.
+ */
+export declare type CameraPreference = {
+    preferredCamera: Camera | undefined;
+    preferredFacing?: undefined;
+} | {
+    preferredCamera: CameraGetter | undefined;
+    preferredFacing?: undefined;
+} | {
+    preferredFacing: FacingMode;
+    preferredCamera?: undefined;
+} | {
+    preferredCamera?: undefined;
+    preferredFacing?: undefined;
+};
+
+/**
+ * The camera UI locale record.
+ */
+export declare type CameraUiLocaleRecord = typeof _default;
+
+/**
+ * The camera UI localization strings.
+ */
+export declare type CameraUiLocalizationStrings = {
+    [K in keyof CameraUiLocaleRecord]: CameraUiLocaleRecord[K] | (string & {});
+};
+
+/**
+ * The camera UI refs.
+ */
+export declare type CameraUiRefs = {
+    /** The feedback layer. */
+    feedbackLayer: HTMLDivElement;
+    /** The overlay layer. */
+    overlayLayer: HTMLDivElement;
+    /** The owner of the component. */
+    owner: Owner;
+};
+
+/**
+ * The camera UI ref store.
+ */
+export declare const cameraUiRefStore: Omit<StoreApi<CameraUiRefs>, "subscribe"> & {
+    subscribe: {
+        (listener: (selectedState: CameraUiRefs, previousSelectedState: CameraUiRefs) => void): () => void;
+        <U>(selector: (state: CameraUiRefs) => U, listener: (selectedState: U, previousSelectedState: U) => void, options?: {
+            equalityFn?: ((a: U, b: U) => boolean) | undefined;
+            fireImmediately?: boolean;
+        } | undefined): () => void;
+    };
+};
+
+/**
+ * Copyright (c) 2025 Microblink Ltd. All rights reserved.
+ */
+export declare type CanvasRenderingMode = "2d" | "webgl2";
+
+/**
+ * Creates a new Camera Manager UI component.
+ *
+ * @param cameraManager - The camera manager.
+ * @param target - The target element to mount the component to.
+ * @param options - The options for the camera manager UI.
+ * @returns The camera manager UI component.
+ */
+export declare function createCameraManagerUi(cameraManager: CameraManager, target?: HTMLElement, { localizationStrings, showMirrorCameraButton, showTorchButton, showCloseButton, showCameraErrorModal, }?: CameraManagerUiOptions): Promise<CameraManagerComponent>;
+
+/**
+ * The default English localization strings.
+ */
+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 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";
+};
+
+/**
+ * Default options for the CameraManager.
+ */
+export declare const defaultCameraManagerOptions: CameraManagerOptions;
+
+/**
+ * A dismount callback.
+ */
+export declare type DismountCallback = () => void;
+
+/**
+ * The extraction area.
+ */
+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;
+
+/**
+ * Finds the closest resolution key to the given resolution.
+ *
+ * @param videoTrackResolution - The resolution to find the closest key for.
+ * @returns The closest resolution key.
+ */
+export declare function findResolutionKey(videoTrackResolution: Resolution): VideoResolutionName;
+
+/**
+ * A callback that will be triggered on each frame when the playback state is
+ * "capturing".
+ *
+ * @param frame - The frame to capture.
+ * @returns The frame.
+ */
+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;
+
+/**
+ * Normalizes a resolution to the longer side.
+ *
+ * @param resolution - The resolution to normalize.
+ * @returns The normalized resolution.
+ */
+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;
+
+/**
+ * Matches the closest resolution to the given resolution.
+ *
+ * @param resolution - The resolution to match.
+ * @returns The closest resolution.
+ */
+export declare function matchClosestResolution(resolution: Resolution): VideoResolutionName;
+
+/**
+ * The default mount point ID.
+ */
+export declare const MOUNT_POINT_ID = "camera-manager-mount-point";
+
+/**
+ * The playback state of the camera manager.
+ */
+export declare type PlaybackState = "idle" | "playback" | "capturing";
+
+/**
+ * Resets the store to its initial state.
+ *
+ * Stops all camera streams as a side effect.
+ */
+export declare const resetCameraManagerStore: () => void;
+
+/**
+ * Represents a video resolution.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/width for width details.
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/height for height details.
+ */
+export declare type Resolution = {
+    width: number;
+    height: number;
+};
+
+/**
+ * Returns the longer side of a resolution.
+ *
+ * @param resolution - The resolution to get the longer side of.
+ * @returns The longer side of the resolution.
+ */
+export declare function returnLongerSide(resolution: Resolution): number;
+
+/**
+ * Options for starting a camera stream.
+ *
+ * @param autoplay - If true, the camera stream will be started automatically.
+ * @param preferredCamera - The camera to start the stream with.
+ * @param preferredFacing - The facing mode to start the stream with.
+ */
+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;
+    /**
+     * Creates a new VideoFrameProcessor.
+     *
+     * @param options - The options for the VideoFrameProcessor.
+     */
+    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.
+     *
+     * @param arrayBuffer - The array buffer to reattach.
+     */
+    reattachArrayBuffer(arrayBuffer: ArrayBufferLike): void;
+    /**
+     * Used to check if the processor owns the buffer.
+     *
+     * @returns true if the processor owns the buffer, false otherwise.
+     */
+    isBufferDetached(): boolean;
+    /**
+     * 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: 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;
+}
+
+/**
+ * Options for the VideoFrameProcessor.
+ */
+export declare type VideoFrameProcessorInitOptions = {
+    canvasRenderingMode?: CanvasRenderingMode;
+    fallbackWebGlTo2d?: boolean;
+};
+
+/**
+ * Represents a video resolution name.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/width for width details.
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/height for height details.
+ */
+export declare type VideoResolutionName = keyof typeof videoResolutions;
+
+/**
+ * Available video resolutions for the camera stream.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/width for width details.
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/height for height details.
+ */
+export declare const videoResolutions: {
+    readonly "720p": {
+        readonly width: 1280;
+        readonly height: 720;
+    };
+    readonly "1080p": {
+        readonly width: 1920;
+        readonly height: 1080;
+    };
+    readonly "4k": {
+        readonly width: 3840;
+        readonly height: 2160;
+    };
+};
+
+export { }