@microblink/camera-manager 7.0.0-next.5 → 7.0.0-next.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microblink/camera-manager",
-  "version": "7.0.0-next.5",
+  "version": "7.0.0-next.8",
   "author": "Microblink",
   "type": "module",
   "main": "./dist/camera-manager.js",
@@ -16,6 +16,9 @@
     "solid-zustand": "^1.8.1",
     "zustand": "^4.5.5"
   },
+  "dependencies": {
+    "type-fest": "^4.35.0"
+  },
   "access": "public",
   "registry": "https://registry.npmjs.org/",
   "types": "./types/index.rollup.d.ts",

package/types/index.rollup.d.ts

@@ -0,0 +1,295 @@
+import { SetStoreFunction } from 'solid-js/store';
+import { StoreApi } from 'zustand/vanilla';
+
+/**
+ * Represents a camera device and its active stream.
+ */
+export declare class Camera {
+    #private;
+    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;
+    original: this;
+    notify: (reason?: unknown) => void;
+    notifyStateChange?: (camera: Camera, reason?: unknown) => void;
+    constructor(deviceInfo: InputDeviceInfo);
+    startStream(resolution: VideoResolution): Promise<MediaStream>;
+    toggleTorch(): Promise<boolean>;
+    stopStream(): void;
+    getVideoTrack(): MediaStreamTrack | undefined;
+}
+
+export declare class CameraManager {
+    #private;
+    /**
+     * Sets the resolution of the camera stream
+     */
+    setResolution: (resolution: VideoResolution) => Promise<void>;
+    get resolution(): "HD" | "FHD" | "UHD";
+    /**
+     * True if there is a video playing or capturing
+     * TODO: see if we can simplify this, by observing the video playback state
+     */
+    get isActive(): boolean;
+    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.
+     */
+    getCameras(): Camera[];
+    /**
+     * Single-time setup for a video element
+     */
+    initVideoElement(videoElement: HTMLVideoElement): void;
+    /**
+     * Adds a callback that will be triggered on each frame when the playback state
+     * is "capturing".
+     *
+     * @param frameCaptureCallback
+     * @returns a cleanup function to remove the callback
+     */
+    addFrameCaptureCallback(frameCaptureCallback: FrameCaptureCallback): () => boolean;
+    deinitVideoElement(): void;
+    /**
+     * Select a camera device from available ones.
+     */
+    selectCamera(camera: Camera): Promise<void>;
+    /**
+     * Refreshes available devices on the system and updates the state.
+     */
+    refreshCameraDevices(): Promise<void>;
+    /**
+     * Starts the video playback
+     *
+     * @returns resolves when playback starts
+     */
+    startPlayback(): Promise<void>;
+    /**
+     * Starts playback and frame capturing.
+     */
+    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>;
+    /**
+     * Pauses capturing frames without pausing 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.
+     * TODO: apply when needed
+     */
+    setMirrorX(mirrorX: boolean): void;
+    /**
+     * 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}
+     */
+    subscribe: typeof cameraManagerStore.subscribe;
+    /**
+     * Gets the current internal state of the CameraManager.
+     */
+    getState: typeof cameraManagerStore.getState;
+    /**
+     * Resets the CameraManager and stop all streams
+     */
+    destroy(): void;
+}
+
+export declare type CameraManagerComponent = {
+    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 */
+    addOnDismountCallback: (fn: DismountCallback) => void;
+    /** Removes a callback that was set with `addOnDismountCallback` */
+    removeOnDismountCallback: (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;
+};
+
+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;
+};
+
+/**
+ * ⚠️ 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.
+ *
+ * {@link https://github.com/pmndrs/zustand}
+ */
+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;
+    };
+};
+
+export declare type CameraPreference = {
+    preferredCamera: Camera;
+    preferredFacing?: never;
+} | {
+    preferredFacing: FacingMode;
+    preferredCamera?: never;
+} | {
+    preferredCamera?: never;
+    preferredFacing?: never;
+};
+
+export declare type CameraUiLocaleRecord = typeof _default;
+
+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;
+};
+
+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;
+    };
+};
+
+/**
+ * Creates a new Camera Manager UI component.
+ */
+export declare function createCameraManagerUi(cameraManager: CameraManager, target?: HTMLElement): Promise<CameraManagerComponent>;
+
+/**
+ * Copyright (c) 2025 Microblink Ltd. All rights reserved.
+ */
+declare const _default: {
+    readonly selected_camera: "Selected camera";
+    readonly select_camera: "Select camera";
+    readonly close: "Close";
+    readonly torch: "Torch";
+    readonly mirror_camera: "Mirror camera";
+    readonly modal_title: "Scan a document";
+};
+
+declare type DismountCallback = () => void;
+
+export declare type FacingMode = "front" | "back" | undefined;
+
+export declare type FrameCaptureCallback = (frame: ImageData) => void | Promise<void>;
+
+export declare const MOUNT_POINT_ID = "camera-manager-mount-point";
+
+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;
+
+export declare type VideoResolution = keyof typeof videoResolutions;
+
+/**
+ * Available video resolutions for the camera stream.
+ */
+export declare const videoResolutions: {
+    HD: {
+        width: number;
+        height: number;
+    };
+    FHD: {
+        width: number;
+        height: number;
+    };
+    UHD: {
+        width: number;
+        height: number;
+    };
+};
+
+export { }