@capgo/camera-preview 7.3.12 → 7.4.0-alpha.0

package/dist/esm/definitions.d.ts

@@ -1,175 +1,575 @@
 export type CameraPosition = "rear" | "front";
+export type FlashMode = CameraPreviewFlashMode;
+export type GridMode = "none" | "3x3" | "4x4";
+export type CameraPositioning = "center" | "top" | "bottom";
+export declare enum DeviceType {
+    ULTRA_WIDE = "ultraWide",
+    WIDE_ANGLE = "wideAngle",
+    TELEPHOTO = "telephoto",
+    TRUE_DEPTH = "trueDepth",
+    DUAL = "dual",
+    DUAL_WIDE = "dualWide",
+    TRIPLE = "triple"
+}
+/**
+ * Represents a single camera lens on a device. A {@link CameraDevice} can have multiple lenses.
+ */
+export interface CameraLens {
+    /** A human-readable name for the lens, e.g., "Ultra-Wide". */
+    label: string;
+    /** The type of the camera lens. */
+    deviceType: DeviceType;
+    /** The focal length of the lens in millimeters. */
+    focalLength: number;
+    /** The base zoom factor for this lens (e.g., 0.5 for ultra-wide, 1.0 for wide). */
+    baseZoomRatio: number;
+    /** The minimum zoom factor supported by this specific lens. */
+    minZoom: number;
+    /** The maximum zoom factor supported by this specific lens. */
+    maxZoom: number;
+}
+/**
+ * Represents a physical camera on the device (e.g., the front-facing camera).
+ */
+export interface CameraDevice {
+    /** A unique identifier for the camera device. */
+    deviceId: string;
+    /** A human-readable name for the camera device. */
+    label: string;
+    /** The physical position of the camera on the device. */
+    position: CameraPosition;
+    /** A list of all available lenses for this camera device. */
+    lenses: CameraLens[];
+    /** The overall minimum zoom factor available across all lenses on this device. */
+    minZoom: number;
+    /** The overall maximum zoom factor available across all lenses on this device. */
+    maxZoom: number;
+    /** Identifies whether the device is a logical camera (composed of multiple physical lenses). */
+    isLogical: boolean;
+}
+/**
+ * Represents the detailed information of the currently active lens.
+ */
+export interface LensInfo {
+    /** The focal length of the active lens in millimeters. */
+    focalLength: number;
+    /** The device type of the active lens. */
+    deviceType: DeviceType;
+    /** The base zoom ratio of the active lens (e.g., 0.5x, 1.0x). */
+    baseZoomRatio: number;
+    /** The current digital zoom factor applied on top of the base zoom. */
+    digitalZoom: number;
+}
+/**
+ * Defines the configuration options for starting the camera preview.
+ */
 export interface CameraPreviewOptions {
-    /** Parent element to attach the video preview element to (applicable to the web platform only) */
+    /**
+     * The parent element to attach the video preview to.
+     * @platform web
+     */
     parent?: string;
-    /** Class name to add to the video preview element (applicable to the web platform only) */
+    /**
+     * A CSS class name to add to the preview element.
+     * @platform web
+     */
     className?: string;
-    /** The preview width in pixels, default window.screen.width */
+    /**
+     * The width of the preview in pixels. Defaults to the screen width.
+     * @platform android, ios, web
+     */
     width?: number;
-    /** The preview height in pixels, default window.screen.height */
+    /**
+     * The height of the preview in pixels. Defaults to the screen height.
+     * @platform android, ios, web
+     */
     height?: number;
-    /** The x origin, default 0 (applicable to the android and ios platforms only) */
+    /**
+     * The horizontal origin of the preview, in pixels.
+     * @platform android, ios
+     */
     x?: number;
-    /** The y origin, default 0 (applicable to the android and ios platforms only) */
+    /**
+     * The vertical origin of the preview, in pixels.
+     * @platform android, ios
+     */
     y?: number;
-    /** Whether to include safe area insets in y-position calculation, default false (applicable to the ios platform only) */
+    /**
+     * The aspect ratio of the camera preview, '4:3' or '16:9' or 'fill'.
+     * Cannot be set if width or height is provided, otherwise the call will be rejected.
+     * Use setPreviewSize to adjust size after starting.
+     *
+     * @since 2.0.0
+     */
+    aspectRatio?: "4:3" | "16:9";
+    /**
+     * The grid overlay to display on the camera preview.
+     * @default "none"
+     * @since 2.1.0
+     */
+    gridMode?: GridMode;
+    /**
+     * Adjusts the y-position to account for safe areas (e.g., notches).
+     * @platform ios
+     * @default false
+     */
     includeSafeAreaInsets?: boolean;
-    /**  Brings your html in front of your preview, default false (applicable to the android only) */
+    /**
+     * If true, places the preview behind the webview.
+     * @platform android
+     * @default true
+     */
     toBack?: boolean;
-    /** The preview bottom padding in pixes. Useful to keep the appropriate preview sizes when orientation changes (applicable to the android and ios platforms only) */
+    /**
+     * Bottom padding for the preview, in pixels.
+     * @platform android, ios
+     */
     paddingBottom?: number;
-    /** Rotate preview when orientation changes (applicable to the ios platforms only; default value is true) */
+    /**
+     * Whether to rotate the preview when the device orientation changes.
+     * @platform ios
+     * @default true
+     */
     rotateWhenOrientationChanged?: boolean;
-    /** Choose the camera to use 'front' or 'rear', default 'front' */
+    /**
+     * The camera to use.
+     * @default "rear"
+     */
     position?: CameraPosition | string;
-    /** Defaults to false - Capture images to a file and return the file path instead of returning base64 encoded data */
+    /**
+     * If true, saves the captured image to a file and returns the file path.
+     * If false, returns a base64 encoded string.
+     * @default false
+     */
     storeToFile?: boolean;
-    /** Defaults to false - Android Only - Disable automatic rotation of the image, and let the browser deal with it (keep reading on how to achieve it) */
+    /**
+     * If true, prevents the plugin from rotating the image based on EXIF data.
+     * @platform android
+     * @default false
+     */
     disableExifHeaderStripping?: boolean;
-    /** Defaults to false - iOS only - Activate high resolution image capture so that output images are from the highest resolution possible on the device **/
-    enableHighResolution?: boolean;
-    /** Defaults to false - Disables audio stream to prevent permission requests and output switching */
+    /**
+     * If true, disables the audio stream, preventing audio permission requests.
+     * @default true
+     */
     disableAudio?: boolean;
-    /**  Android Only - Locks device orientation when camera is showing. */
+    /**
+     * If true, locks the device orientation while the camera is active.
+     * @platform android
+     * @default false
+     */
     lockAndroidOrientation?: boolean;
-    /** Defaults to false - Android and Web only.  Set if camera preview can change opacity. */
+    /**
+     * If true, allows the camera preview's opacity to be changed.
+     * @platform android, web
+     * @default false
+     */
     enableOpacity?: boolean;
-    /** Defaults to false - Android only.  Set if camera preview will support pinch to zoom. */
+    /**
+     * If true, enables pinch-to-zoom functionality on the preview.
+     * @platform android
+     * @default false
+     */
     enableZoom?: boolean;
-    /** default to false - IOS only. Set the CameraPreview to use the video mode preset */
-    cameraMode?: boolean;
+    /**
+     * If true, uses the video-optimized preset for the camera session.
+     * @platform ios
+     * @default false
+     */
+    enableVideoMode?: boolean;
+    /**
+     * The `deviceId` of the camera to use. If provided, `position` is ignored.
+     * @platform ios
+     */
+    deviceId?: string;
+    /**
+     * The initial zoom level when starting the camera preview.
+     * If the requested zoom level is not available, the native plugin will reject.
+     * @default 1.0
+     * @platform android, ios
+     * @since 2.2.0
+     */
+    initialZoomLevel?: number;
+    /**
+     * The vertical positioning of the camera preview.
+     * @default "center"
+     * @platform android, ios, web
+     * @since 2.3.0
+     */
+    positioning?: CameraPositioning;
 }
+/**
+ * Defines the options for capturing a picture.
+ */
 export interface CameraPreviewPictureOptions {
-    /** The picture height, optional, default 0 (Device default) */
+    /** @deprecated,
+     * The desired height of the picture in pixels.
+     * If not specified and no aspectRatio is provided, the captured image will match the preview's visible area.
+     */
     height?: number;
-    /** The picture width, optional, default 0 (Device default) */
+    /** @deprecated,
+     * The desired width of the picture in pixels.
+     * If not specified and no aspectRatio is provided, the captured image will match the preview's visible area.
+     */
     width?: number;
-    /** The picture quality, 0 - 100, default 85 */
+    /** @deprecated,
+     * The desired aspect ratio of the captured image (e.g., '4:3', '16:9').
+     * If not specified and no width/height is provided, the aspect ratio from the camera start will be used.
+     * If no aspect ratio was set at start, defaults to '4:3'.
+     * Cannot be used together with width or height - the capture will be rejected with an error.
+     * @since 7.7.0
+     */
+    aspectRatio?: string;
+    /**
+     * The quality of the captured image, from 0 to 100.
+     * Does not apply to `png` format.
+     * @default 85
+     */
     quality?: number;
-    /** The picture format, jpeg or png, default jpeg on `Web`.
-     *
-     * quality has no effect on png */
+    /**
+     * The format of the captured image.
+     * @default "jpeg"
+     */
     format?: PictureFormat;
+    /**
+     * If true, the captured image will be saved to the user's gallery.
+     * @default false
+     * @since 7.5.0
+     */
+    saveToGallery?: boolean;
+    /**
+     * If true, the plugin will attempt to add GPS location data to the image's EXIF metadata.
+     * This may prompt the user for location permissions.
+     * @default false
+     * @since 7.6.0
+     */
+    withExifLocation?: boolean;
+}
+/** Represents EXIF data extracted from an image. */
+export interface ExifData {
+    [key: string]: any;
 }
 export type PictureFormat = "jpeg" | "png";
+/** Defines a standard picture size with width and height. */
+export interface PictureSize {
+    /** The width of the picture in pixels. */
+    width: number;
+    /** The height of the picture in pixels. */
+    height: number;
+}
+/** Represents the supported picture sizes for a camera facing a certain direction. */
+export interface SupportedPictureSizes {
+    /** The camera direction ("front" or "rear"). */
+    facing: string;
+    /** A list of supported picture sizes for this camera. */
+    supportedPictureSizes: PictureSize[];
+}
+/**
+ * Defines the options for capturing a sample frame from the camera preview.
+ */
 export interface CameraSampleOptions {
-    /** The picture quality, 0 - 100, default 85 */
+    /**
+     * The quality of the captured sample, from 0 to 100.
+     * @default 85
+     */
     quality?: number;
 }
-export type CameraPreviewFlashMode = "off" | "on" | "auto" | "red-eye" | "torch";
+/**
+ * The available flash modes for the camera.
+ * 'torch' is a continuous light mode.
+ */
+export type CameraPreviewFlashMode = "off" | "on" | "auto" | "torch";
+/**
+ * Defines the options for setting the camera preview's opacity.
+ */
 export interface CameraOpacityOptions {
-    /** The percent opacity to set for camera view, default 1 */
+    /**
+     * The opacity percentage, from 0.0 (fully transparent) to 1.0 (fully opaque).
+     * @default 1.0
+     */
     opacity?: number;
 }
+/**
+ * The main interface for the CameraPreview plugin.
+ */
 export interface CameraPreviewPlugin {
     /**
-     * Start the camera preview instance.
-     * @param {CameraPreviewOptions} options the options to start the camera preview with
-     * @returns {Promise<void>} an Promise that resolves when the instance is started
-     * @throws An error if the something went wrong
+     * Starts the camera preview.
+     *
+     * @param {CameraPreviewOptions} options - The configuration for the camera preview.
+     * @returns {Promise<{ width: number; height: number; x: number; y: number }>} A promise that resolves with the preview dimensions.
      * @since 0.0.1
      */
-    start(options: CameraPreviewOptions): Promise<void>;
+    start(options: CameraPreviewOptions): Promise<{
+        /** The width of the preview in pixels. */
+        width: number;
+        /** The height of the preview in pixels. */
+        height: number;
+        /** The horizontal origin of the preview, in pixels. */
+        x: number;
+        /** The vertical origin of the preview, in pixels. */
+        y: number;
+    }>;
     /**
-     * Stop the camera preview instance.
-     * @returns {Promise<void>} an Promise that resolves when the instance is stopped
-     * @throws An error if the something went wrong
+     * Stops the camera preview.
+     *
+     * @returns {Promise<void>} A promise that resolves when the camera preview is stopped.
      * @since 0.0.1
      */
     stop(): Promise<void>;
     /**
-     * Switch camera.
-     * @param {CameraPreviewOptions} options the options to switch the camera with
-     * @returns {Promise<void>} an Promise that resolves when the camera is switched
-     * @throws An error if the something went wrong
+     * Captures a picture from the camera.
+     *
+     * @param {CameraPreviewPictureOptions} options - The options for capturing the picture.
+     * @returns {Promise<{ value: string }>} A promise that resolves with the captured image data.
+     * The `value` is a base64 encoded string unless `storeToFile` is true, in which case it's a file path.
      * @since 0.0.1
      */
     capture(options: CameraPreviewPictureOptions): Promise<{
         value: string;
+        exif: ExifData;
     }>;
     /**
-     * Capture a sample image.
-     * @param {CameraSampleOptions} options the options to capture the sample image with
-     * @returns {Promise<string>} an Promise that resolves with the sample image as a base64 encoded string
-     * @throws An error if the something went wrong
+     * Captures a single frame from the camera preview stream.
+     *
+     * @param {CameraSampleOptions} options - The options for capturing the sample.
+     * @returns {Promise<{ value: string }>} A promise that resolves with the sample image as a base64 encoded string.
      * @since 0.0.1
      */
     captureSample(options: CameraSampleOptions): Promise<{
         value: string;
     }>;
     /**
-     * Get supported flash modes.
-     * @returns {Promise<CameraPreviewFlashMode[]>} an Promise that resolves with the supported flash modes
-     * @throws An error if the something went wrong
+     * Gets the flash modes supported by the active camera.
+     *
+     * @returns {Promise<{ result: CameraPreviewFlashMode[] }>} A promise that resolves with an array of supported flash modes.
      * @since 0.0.1
      */
     getSupportedFlashModes(): Promise<{
         result: CameraPreviewFlashMode[];
     }>;
     /**
-     * Get horizontal field of view.
-     * @returns {Promise<any>} an Promise that resolves with the horizontal field of view
-     * @throws An error if the something went wrong
+     * Set the aspect ratio of the camera preview.
+     *
+     * @param {{ aspectRatio: '4:3' | '16:9'; x?: number; y?: number }} options - The desired aspect ratio and optional position.
+     *   - aspectRatio: The desired aspect ratio ('4:3' or '16:9')
+     *   - x: Optional x coordinate for positioning. If not provided, view will be auto-centered horizontally.
+     *   - y: Optional y coordinate for positioning. If not provided, view will be auto-centered vertically.
+     * @returns {Promise<{ width: number; height: number; x: number; y: number }>} A promise that resolves with the actual preview dimensions and position.
+     * @since 7.4.0
+     */
+    setAspectRatio(options: {
+        aspectRatio: "4:3" | "16:9";
+        x?: number;
+        y?: number;
+    }): Promise<{
+        width: number;
+        height: number;
+        x: number;
+        y: number;
+    }>;
+    /**
+     * Gets the current aspect ratio of the camera preview.
+     *
+     * @returns {Promise<{ aspectRatio: '4:3' | '16:9' }>} A promise that resolves with the current aspect ratio.
+     * @since 7.4.0
+     */
+    getAspectRatio(): Promise<{
+        aspectRatio: "4:3" | "16:9";
+    }>;
+    /**
+     * Sets the grid mode of the camera preview overlay.
+     *
+     * @param {{ gridMode: GridMode }} options - The desired grid mode ('none', '3x3', or '4x4').
+     * @returns {Promise<void>} A promise that resolves when the grid mode is set.
+     * @since 8.0.0
+     */
+    setGridMode(options: {
+        gridMode: GridMode;
+    }): Promise<void>;
+    /**
+     * Gets the current grid mode of the camera preview overlay.
+     *
+     * @returns {Promise<{ gridMode: GridMode }>} A promise that resolves with the current grid mode.
+     * @since 8.0.0
+     */
+    getGridMode(): Promise<{
+        gridMode: GridMode;
+    }>;
+    /**
+     * Gets the horizontal field of view (FoV) for the active camera.
+     * Note: This can be an estimate on some devices.
+     *
+     * @returns {Promise<{ result: number }>} A promise that resolves with the horizontal field of view in degrees.
      * @since 0.0.1
      */
     getHorizontalFov(): Promise<{
-        result: any;
+        result: number;
     }>;
     /**
-     * Gets the supported picture sizes for a given device.
-     * @returns {Promise<any>} an Promise that resolves with the supported picture sizes for a given device
-     * @throws An error if the something goes wrong
+     * Gets the supported picture sizes for all cameras.
+     *
+     * @returns {Promise<{ supportedPictureSizes: SupportedPictureSizes[] }>} A promise that resolves with the list of supported sizes.
+     * @since 7.4.0
      */
     getSupportedPictureSizes(): Promise<{
-        supportedPictureSizes: {
-            facing: string;
-            supportedPictureSizes: {
-                width: number;
-                height: number;
-            }[];
-        }[];
-    }>;
-    /**
-     * Set flash mode.
-     * @param options the options to set the flash mode with
-     * @returns {Promise<void>} an Promise that resolves when the flash mode is set
-     * @throws An error if the something went wrong
+        supportedPictureSizes: SupportedPictureSizes[];
+    }>;
+    /**
+     * Sets the flash mode for the active camera.
+     *
+     * @param {{ flashMode: CameraPreviewFlashMode | string }} options - The desired flash mode.
+     * @returns {Promise<void>} A promise that resolves when the flash mode is set.
      * @since 0.0.1
      */
     setFlashMode(options: {
         flashMode: CameraPreviewFlashMode | string;
     }): Promise<void>;
     /**
-     * Flip camera.
-     * @returns {Promise<void>} an Promise that resolves when the camera is flipped
-     * @throws An error if the something went wrong
+     * Toggles between the front and rear cameras.
+     *
+     * @returns {Promise<void>} A promise that resolves when the camera is flipped.
      * @since 0.0.1
      */
     flip(): Promise<void>;
     /**
-     * Set opacity.
-     * @param {CameraOpacityOptions} options the options to set the camera opacity with
-     * @returns {Promise<void>} an Promise that resolves when the camera color effect is set
-     * @throws An error if the something went wrong
+     * Sets the opacity of the camera preview.
+     *
+     * @param {CameraOpacityOptions} options - The opacity options.
+     * @returns {Promise<void>} A promise that resolves when the opacity is set.
      * @since 0.0.1
      */
     setOpacity(options: CameraOpacityOptions): Promise<void>;
     /**
-     * Stop recording video.
-     * @param {CameraPreviewOptions} options the options to stop recording video with
-     * @returns {Promise<{videoFilePath: string}>} an Promise that resolves when the camera zoom is set
-     * @throws An error if the something went wrong
+     * Stops an ongoing video recording.
+     *
+     * @returns {Promise<{ videoFilePath: string }>} A promise that resolves with the path to the recorded video file.
      * @since 0.0.1
      */
     stopRecordVideo(): Promise<{
         videoFilePath: string;
     }>;
     /**
-     * Start recording video.
-     * @param {CameraPreviewOptions} options the options to start recording video with
-     * @returns {Promise<void>} an Promise that resolves when the video recording is started
-     * @throws An error if the something went wrong
+     * Starts recording a video.
+     *
+     * @param {CameraPreviewOptions} options - The options for video recording.
+     * @returns {Promise<void>} A promise that resolves when video recording starts.
      * @since 0.0.1
      */
     startRecordVideo(options: CameraPreviewOptions): Promise<void>;
+    /**
+     * Checks if the camera preview is currently running.
+     *
+     * @returns {Promise<{ isRunning: boolean }>} A promise that resolves with the running state.
+     * @since 7.4.0
+     */
+    isRunning(): Promise<{
+        isRunning: boolean;
+    }>;
+    /**
+     * Gets all available camera devices.
+     *
+     * @returns {Promise<{ devices: CameraDevice[] }>} A promise that resolves with the list of available camera devices.
+     * @since 7.4.0
+     */
+    getAvailableDevices(): Promise<{
+        devices: CameraDevice[];
+    }>;
+    /**
+     * Gets the current zoom state, including min/max and current lens info.
+     *
+     * @returns {Promise<{ min: number; max: number; current: number; lens: LensInfo }>} A promise that resolves with the zoom state.
+     * @since 7.4.0
+     */
+    getZoom(): Promise<{
+        min: number;
+        max: number;
+        current: number;
+        lens: LensInfo;
+    }>;
+    /**
+     * Sets the zoom level of the camera.
+     *
+     * @param {{ level: number; ramp?: boolean; autoFocus?: boolean }} options - The desired zoom level. `ramp` is currently unused. `autoFocus` defaults to true.
+     * @returns {Promise<void>} A promise that resolves when the zoom level is set.
+     * @since 7.4.0
+     */
+    setZoom(options: {
+        level: number;
+        ramp?: boolean;
+        autoFocus?: boolean;
+    }): Promise<void>;
+    /**
+     * Gets the current flash mode.
+     *
+     * @returns {Promise<{ flashMode: FlashMode }>} A promise that resolves with the current flash mode.
+     * @since 7.4.0
+     */
+    getFlashMode(): Promise<{
+        flashMode: FlashMode;
+    }>;
+    /**
+     * Removes all registered listeners.
+     *
+     * @since 7.4.0
+     */
+    removeAllListeners(): Promise<void>;
+    /**
+     * Switches the active camera to the one with the specified `deviceId`.
+     *
+     * @param {{ deviceId: string }} options - The ID of the device to switch to.
+     * @returns {Promise<void>} A promise that resolves when the camera is switched.
+     * @since 7.4.0
+     */
+    setDeviceId(options: {
+        deviceId: string;
+    }): Promise<void>;
+    /**
+     * Gets the ID of the currently active camera device.
+     *
+     * @returns {Promise<{ deviceId: string }>} A promise that resolves with the current device ID.
+     * @since 7.4.0
+     */
+    getDeviceId(): Promise<{
+        deviceId: string;
+    }>;
+    /**
+     * Gets the current preview size and position.
+     * @returns {Promise<{x: number, y: number, width: number, height: number}>}
+     */
+    getPreviewSize(): Promise<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    /**
+     * Sets the preview size and position.
+     * @param options The new position and dimensions.
+     * @returns {Promise<{ width: number; height: number; x: number; y: number }>} A promise that resolves with the actual preview dimensions and position.
+     */
+    setPreviewSize(options: {
+        x?: number;
+        y?: number;
+        width: number;
+        height: number;
+    }): Promise<{
+        width: number;
+        height: number;
+        x: number;
+        y: number;
+    }>;
+    /**
+     * Sets the camera focus to a specific point in the preview.
+     *
+     * @param {Object} options - The focus options.
+     * @param {number} options.x - The x coordinate in the preview view to focus on (0-1 normalized).
+     * @param {number} options.y - The y coordinate in the preview view to focus on (0-1 normalized).
+     * @returns {Promise<void>} A promise that resolves when the focus is set.
+     * @since 8.1.0
+     */
+    setFocus(options: {
+        x: number;
+        y: number;
+    }): Promise<void>;
 }

package/dist/esm/definitions.js

@@ -1,2 +1,11 @@
-export {};
+export var DeviceType;
+(function (DeviceType) {
+    DeviceType["ULTRA_WIDE"] = "ultraWide";
+    DeviceType["WIDE_ANGLE"] = "wideAngle";
+    DeviceType["TELEPHOTO"] = "telephoto";
+    DeviceType["TRUE_DEPTH"] = "trueDepth";
+    DeviceType["DUAL"] = "dual";
+    DeviceType["DUAL_WIDE"] = "dualWide";
+    DeviceType["TRIPLE"] = "triple";
+})(DeviceType || (DeviceType = {}));
 //# sourceMappingURL=definitions.js.map