@capgo/camera-preview 7.24.15 → 7.26.0

package/README.md

@@ -319,7 +319,7 @@ Documentation for the [uploader](https://github.com/Cap-go/capacitor-uploader)
 <docgen-index>
 
 * [`start(...)`](#start)
-* [`stop()`](#stop)
+* [`stop(...)`](#stop)
 * [`capture(...)`](#capture)
 * [`captureSample(...)`](#capturesample)
 * [`getSupportedFlashModes()`](#getsupportedflashmodes)
@@ -390,14 +390,18 @@ Starts the camera preview.
 --------------------
 
 
-### stop()
+### stop(...)
 
 ```typescript
-stop() => Promise<void>
+stop(options?: { force?: boolean | undefined; } | undefined) => Promise<void>
 ```
 
 Stops the camera preview.
 
+| Param         | Type                              | Description                                       |
+| ------------- | --------------------------------- | ------------------------------------------------- |
+| **`options`** | <code>{ force?: boolean; }</code> | - Optional configuration for stopping the camera. |
+
 **Since:** 0.0.1
 
 --------------------
@@ -1092,6 +1096,7 @@ Defines the configuration options for starting the camera preview.
 | **`initialZoomLevel`**             | <code>number</code>                                             | The initial zoom level when starting the camera preview. If the requested zoom level is not available, the native plugin will reject.                                                                   | <code>1.0</code>      | 2.2.0  |
 | **`positioning`**                  | <code><a href="#camerapositioning">CameraPositioning</a></code> | The vertical positioning of the camera preview.                                                                                                                                                         | <code>"center"</code> | 2.3.0  |
 | **`enableVideoMode`**              | <code>boolean</code>                                            | If true, enables video capture capabilities when the camera starts.                                                                                                                                     | <code>false</code>    | 7.11.0 |
+| **`force`**                        | <code>boolean</code>                                            | If true, forces the camera to start/restart even if it's already running or busy. This will kill the current camera session and start a new one, ignoring all state checks.                             | <code>false</code>    |        |
 
 
 #### ExifData

package/android/src/main/AndroidManifest.xml

@@ -3,5 +3,5 @@
     <uses-permission android:name="android.permission.CAMERA" />
     <uses-permission android:name="android.permission.RECORD_AUDIO" />
     <uses-feature android:name="android.hardware.camera" />
-    <uses-feature android:name="android.hardware.camera.autofocus" />
+    <uses-feature android:required="false" android:name="android.hardware.camera.autofocus" />
   </manifest>

package/android/src/main/java/app/capgo/capacitor/camera/preview/CameraPreview.java

@@ -230,8 +230,22 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
 
     @PluginMethod
     public void start(PluginCall call) {
-        // Prevent starting while an existing view is still active or stopping
-        if (cameraXView != null) {
+        boolean force = Boolean.TRUE.equals(call.getBoolean("force", false));
+
+        // If force is true, kill everything and restart no matter what
+        if (force && cameraXView != null) {
+            try {
+                Log.d(TAG, "start: force=true, force stopping camera regardless of state");
+                // Force stop the camera session no matter what state it's in
+                cameraXView.stopSession();
+                cameraXView = null;
+            } catch (Exception e) {
+                Log.w(TAG, "start: Exception while force stopping camera", e);
+                // Continue anyway - we're forcing a restart
+                cameraXView = null;
+            }
+        } else if (cameraXView != null) {
+            // Normal checks only when force is false
             try {
                 if (cameraXView.isRunning() && !cameraXView.isStopping()) {
                     call.reject("Camera is already running");
@@ -247,6 +261,7 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
                 }
             } catch (Exception ignored) {}
         }
+
         boolean disableAudio = Boolean.TRUE.equals(call.getBoolean("disableAudio", true));
         String permissionAlias = disableAudio ? CAMERA_ONLY_PERMISSION_ALIAS : CAMERA_WITH_AUDIO_PERMISSION_ALIAS;
 
@@ -366,6 +381,8 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
 
     @PluginMethod
     public void stop(final PluginCall call) {
+        boolean force = Boolean.TRUE.equals(call.getBoolean("force", false));
+
         bridge
             .getActivity()
             .runOnUiThread(() -> {
@@ -386,8 +403,9 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
 
                 if (cameraXView != null) {
                     cameraXView.stopSession();
-                    // Only drop the reference if no deferred stop is pending
-                    if (!cameraXView.isStopDeferred()) {
+                    // If force is true, always drop the reference
+                    // Otherwise only drop the reference if no deferred stop is pending
+                    if (force || !cameraXView.isStopDeferred()) {
                         cameraXView = null;
                     }
                 }

package/dist/docs.json

@@ -38,10 +38,20 @@
       },
       {
         "name": "stop",
-        "signature": "() => Promise<void>",
-        "parameters": [],
+        "signature": "(options?: { force?: boolean | undefined; } | undefined) => Promise<void>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "- Optional configuration for stopping the camera.",
+            "type": "{ force?: boolean | undefined; } | undefined"
+          }
+        ],
         "returns": "Promise<void>",
         "tags": [
+          {
+            "name": "param",
+            "text": "options - Optional configuration for stopping the camera."
+          },
           {
             "name": "returns",
             "text": "A promise that resolves when the camera preview is stopped."
@@ -1423,6 +1433,22 @@
           "docs": "If true, enables video capture capabilities when the camera starts.",
           "complexTypes": [],
           "type": "boolean | undefined"
+        },
+        {
+          "name": "force",
+          "tags": [
+            {
+              "text": "false",
+              "name": "default"
+            },
+            {
+              "text": "android, ios, web",
+              "name": "platform"
+            }
+          ],
+          "docs": "If true, forces the camera to start/restart even if it's already running or busy.\nThis will kill the current camera session and start a new one, ignoring all state checks.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
         }
       ]
     },

package/dist/esm/definitions.d.ts

@@ -211,6 +211,13 @@ export interface CameraPreviewOptions {
      * @since 7.11.0
      */
     enableVideoMode?: boolean;
+    /**
+     * If true, forces the camera to start/restart even if it's already running or busy.
+     * This will kill the current camera session and start a new one, ignoring all state checks.
+     * @default false
+     * @platform android, ios, web
+     */
+    force?: boolean;
 }
 /**
  * Defines the options for capturing a picture.
@@ -366,10 +373,14 @@ export interface CameraPreviewPlugin {
     /**
      * Stops the camera preview.
      *
+     * @param {object} options - Optional configuration for stopping the camera.
+     * @param {boolean} options.force - If true, forces the camera to stop even if busy or capturing. Default: false.
      * @returns {Promise<void>} A promise that resolves when the camera preview is stopped.
      * @since 0.0.1
      */
-    stop(): Promise<void>;
+    stop(options?: {
+        force?: boolean;
+    }): Promise<void>;
     /**
      * Captures a picture from the camera.
      *

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"AAwBA,MAAM,CAAN,IAAY,UAQX;AARD,WAAY,UAAU;IACpB,sCAAwB,CAAA;IACxB,sCAAwB,CAAA;IACxB,qCAAuB,CAAA;IACvB,sCAAwB,CAAA;IACxB,2BAAa,CAAA;IACb,oCAAsB,CAAA;IACtB,+BAAiB,CAAA;AACnB,CAAC,EARW,UAAU,KAAV,UAAU,QAQrB","sourcesContent":["import type { PermissionState, PluginListenerHandle } from '@capacitor/core';\n\nexport type CameraPosition = 'rear' | 'front';\n\nexport type FlashMode = CameraPreviewFlashMode;\n\nexport type GridMode = 'none' | '3x3' | '4x4';\n\nexport type CameraPositioning = 'center' | 'top' | 'bottom';\n\nexport interface CameraPermissionStatus {\n  camera: PermissionState;\n  microphone?: PermissionState;\n}\n\nexport interface PermissionRequestOptions {\n  disableAudio?: boolean;\n  showSettingsAlert?: boolean;\n  title?: string;\n  message?: string;\n  openSettingsButtonTitle?: string;\n  cancelButtonTitle?: string;\n}\n\nexport enum DeviceType {\n  ULTRA_WIDE = 'ultraWide',\n  WIDE_ANGLE = 'wideAngle',\n  TELEPHOTO = 'telephoto',\n  TRUE_DEPTH = 'trueDepth',\n  DUAL = 'dual',\n  DUAL_WIDE = 'dualWide',\n  TRIPLE = 'triple',\n}\n\n/**\n * Represents a single camera lens on a device. A {@link CameraDevice} can have multiple lenses.\n */\nexport interface CameraLens {\n  /** A human-readable name for the lens, e.g., \"Ultra-Wide\". */\n  label: string;\n  /** The type of the camera lens. */\n  deviceType: DeviceType;\n  /** The focal length of the lens in millimeters. */\n  focalLength: number;\n  /** The base zoom factor for this lens (e.g., 0.5 for ultra-wide, 1.0 for wide). */\n  baseZoomRatio: number;\n  /** The minimum zoom factor supported by this specific lens. */\n  minZoom: number;\n  /** The maximum zoom factor supported by this specific lens. */\n  maxZoom: number;\n}\n\n/**\n * Represents a physical camera on the device (e.g., the front-facing camera).\n */\nexport interface CameraDevice {\n  /** A unique identifier for the camera device. */\n  deviceId: string;\n  /** A human-readable name for the camera device. */\n  label: string;\n  /** The physical position of the camera on the device. */\n  position: CameraPosition;\n  /** A list of all available lenses for this camera device. */\n  lenses: CameraLens[];\n  /** The overall minimum zoom factor available across all lenses on this device. */\n  minZoom: number;\n  /** The overall maximum zoom factor available across all lenses on this device. */\n  maxZoom: number;\n  /** Identifies whether the device is a logical camera (composed of multiple physical lenses). */\n  isLogical: boolean;\n}\n\n/**\n * Represents the detailed information of the currently active lens.\n */\nexport interface LensInfo {\n  /** The focal length of the active lens in millimeters. */\n  focalLength: number;\n  /** The device type of the active lens. */\n  deviceType: DeviceType;\n  /** The base zoom ratio of the active lens (e.g., 0.5x, 1.0x). */\n  baseZoomRatio: number;\n  /** The current digital zoom factor applied on top of the base zoom. */\n  digitalZoom: number;\n}\n\n/**\n * Defines the configuration options for starting the camera preview.\n */\nexport interface CameraPreviewOptions {\n  /**\n   * The parent element to attach the video preview to.\n   * @platform web\n   */\n  parent?: string;\n  /**\n   * A CSS class name to add to the preview element.\n   * @platform web\n   */\n  className?: string;\n  /**\n   * The width of the preview in pixels. Defaults to the screen width.\n   * @platform android, ios, web\n   */\n  width?: number;\n  /**\n   * The height of the preview in pixels. Defaults to the screen height.\n   * @platform android, ios, web\n   */\n  height?: number;\n  /**\n   * The horizontal origin of the preview, in pixels.\n   * @platform android, ios\n   */\n  x?: number;\n  /**\n   * The vertical origin of the preview, in pixels.\n   * @platform android, ios\n   */\n  y?: number;\n  /**\n   * The aspect ratio of the camera preview, '4:3' or '16:9' or 'fill'.\n   * Cannot be set if width or height is provided, otherwise the call will be rejected.\n   * Use setPreviewSize to adjust size after starting.\n   *\n   * @since 2.0.0\n   */\n  aspectRatio?: '4:3' | '16:9';\n  /**\n   * The grid overlay to display on the camera preview.\n   * @default \"none\"\n   * @since 2.1.0\n   */\n  gridMode?: GridMode;\n  /**\n   * Adjusts the y-position to account for safe areas (e.g., notches).\n   * @platform ios\n   * @default false\n   */\n  includeSafeAreaInsets?: boolean;\n  /**\n   * If true, places the preview behind the webview.\n   * @platform android\n   * @default true\n   */\n  toBack?: boolean;\n  /**\n   * Bottom padding for the preview, in pixels.\n   * @platform android, ios\n   */\n  paddingBottom?: number;\n  /**\n   * Whether to rotate the preview when the device orientation changes.\n   * @platform ios\n   * @default true\n   */\n  rotateWhenOrientationChanged?: boolean;\n  /**\n   * The camera to use.\n   * @default \"rear\"\n   */\n  position?: CameraPosition | string;\n  /**\n   * If true, saves the captured image to a file and returns the file path.\n   * If false, returns a base64 encoded string.\n   * @default false\n   */\n  storeToFile?: boolean;\n  /**\n   * If true, prevents the plugin from rotating the image based on EXIF data.\n   * @platform android\n   * @default false\n   */\n  disableExifHeaderStripping?: boolean;\n  /**\n   * If true, disables the audio stream, preventing audio permission requests.\n   * @default true\n   */\n  disableAudio?: boolean;\n  /**\n   * If true, locks the device orientation while the camera is active.\n   * @platform android\n   * @default false\n   */\n  lockAndroidOrientation?: boolean;\n  /**\n   * If true, allows the camera preview's opacity to be changed.\n   * @platform android, web\n   * @default false\n   */\n  enableOpacity?: boolean;\n\n  /**\n   * If true, disables the visual focus indicator when tapping to focus.\n   * @platform android, ios\n   * @default false\n   */\n  disableFocusIndicator?: boolean;\n  /**\n   * The `deviceId` of the camera to use. If provided, `position` is ignored.\n   * @platform ios\n   */\n  deviceId?: string;\n  /**\n   * The initial zoom level when starting the camera preview.\n   * If the requested zoom level is not available, the native plugin will reject.\n   * @default 1.0\n   * @platform android, ios\n   * @since 2.2.0\n   */\n  initialZoomLevel?: number;\n  /**\n   * The vertical positioning of the camera preview.\n   * @default \"center\"\n   * @platform android, ios, web\n   * @since 2.3.0\n   */\n  positioning?: CameraPositioning;\n  /**\n   * If true, enables video capture capabilities when the camera starts.\n   * @default false\n   * @platform android\n   * @since 7.11.0\n   */\n  enableVideoMode?: boolean;\n}\n\n/**\n * Defines the options for capturing a picture.\n */\nexport interface CameraPreviewPictureOptions {\n  /**\n   * The maximum height of the picture in pixels. The image will be resized to fit within this height while maintaining aspect ratio.\n   * If not specified the captured image will match the preview's visible area.\n   */\n  height?: number;\n  /**\n   * The maximum width of the picture in pixels. The image will be resized to fit within this width while maintaining aspect ratio.\n   * If not specified the captured image will match the preview's visible area.\n   */\n  width?: number;\n  /**\n   * The quality of the captured image, from 0 to 100.\n   * Does not apply to `png` format.\n   * @default 85\n   */\n  quality?: number;\n  /**\n   * The format of the captured image.\n   * @default \"jpeg\"\n   */\n  format?: PictureFormat;\n  /**\n   * If true, the captured image will be saved to the user's gallery.\n   * @default false\n   * @since 7.5.0\n   */\n  saveToGallery?: boolean;\n  /**\n   * If true, the plugin will attempt to add GPS location data to the image's EXIF metadata.\n   * This may prompt the user for location permissions.\n   * @default false\n   * @since 7.6.0\n   */\n  withExifLocation?: boolean;\n  /**\n   * If true, the plugin will embed a timestamp in the top-right corner of the image.\n   * @default false\n   * @since 7.17.0\n   */\n  embedTimestamp?: boolean;\n  /**\n   * If true, the plugin will embed the current location in the top-right corner of the image.\n   * Requires `withExifLocation` to be enabled.\n   * @default false\n   * @since 7.18.0\n   */\n  embedLocation?: boolean;\n  /**\n   * Sets the priority for photo quality vs. capture speed.\n   * - \"speed\": Prioritizes faster capture times, may reduce image quality.\n   * - \"balanced\": Aims for a balance between quality and speed.\n   * - \"quality\": Prioritizes image quality, may reduce capture speed.\n   * See https://developer.apple.com/documentation/avfoundation/avcapturephotosettings/photoqualityprioritization for details.\n   *\n   * @since 7.21.0\n   * @platform ios\n   * @default \"speed\"\n   */\n  photoQualityPrioritization?: 'speed' | 'balanced' | 'quality';\n}\n\n/** Represents EXIF data extracted from an image. */\nexport interface ExifData {\n  [key: string]: any;\n}\n\nexport type PictureFormat = 'jpeg' | 'png';\n\n/** Defines a standard picture size with width and height. */\nexport interface PictureSize {\n  /** The width of the picture in pixels. */\n  width: number;\n  /** The height of the picture in pixels. */\n  height: number;\n}\n\n/** Represents the supported picture sizes for a camera facing a certain direction. */\nexport interface SupportedPictureSizes {\n  /** The camera direction (\"front\" or \"rear\"). */\n  facing: string;\n  /** A list of supported picture sizes for this camera. */\n  supportedPictureSizes: PictureSize[];\n}\n\n/**\n * Defines the options for capturing a sample frame from the camera preview.\n */\nexport interface CameraSampleOptions {\n  /**\n   * The quality of the captured sample, from 0 to 100.\n   * @default 85\n   */\n  quality?: number;\n}\n\n/**\n * The available flash modes for the camera.\n * 'torch' is a continuous light mode.\n */\nexport type CameraPreviewFlashMode = 'off' | 'on' | 'auto' | 'torch';\n\n/** Reusable exposure mode type for cross-platform support. */\nexport type ExposureMode = 'AUTO' | 'LOCK' | 'CONTINUOUS' | 'CUSTOM';\n\n/**\n * Defines the options for setting the camera preview's opacity.\n */\nexport interface CameraOpacityOptions {\n  /**\n   * The opacity percentage, from 0.0 (fully transparent) to 1.0 (fully opaque).\n   * @default 1.0\n   */\n  opacity?: number;\n}\n\n/**\n * Represents safe area insets for devices.\n * Android: Values are expressed in logical pixels (dp) to match JS layout units.\n * iOS: Values are expressed in physical pixels and exclude status bar.\n */\nexport interface SafeAreaInsets {\n  /** Current device orientation (1 = portrait, 2 = landscape, 0 = unknown). */\n  orientation: number;\n  /**\n   * Orientation-aware notch/camera cutout inset (excluding status bar).\n   * In portrait mode: returns top inset (notch at top).\n   * In landscape mode: returns left inset (notch at side).\n   * Android: Value in dp, iOS: Value in pixels (status bar excluded).\n   */\n  top: number;\n}\n\n/**\n * Canonical device orientation values across platforms.\n */\nexport type DeviceOrientation = 'portrait' | 'landscape-left' | 'landscape-right' | 'portrait-upside-down' | 'unknown';\n\n/**\n * The main interface for the CameraPreview plugin.\n */\nexport interface CameraPreviewPlugin {\n  /**\n   * Starts the camera preview.\n   *\n   * @param {CameraPreviewOptions} options - The configuration for the camera preview.\n   * @returns {Promise<{ width: number; height: number; x: number; y: number }>} A promise that resolves with the preview dimensions.\n   * @since 0.0.1\n   */\n  start(options: CameraPreviewOptions): Promise<{\n    /** The width of the preview in pixels. */\n    width: number;\n    /** The height of the preview in pixels. */\n    height: number;\n    /** The horizontal origin of the preview, in pixels. */\n    x: number;\n    /** The vertical origin of the preview, in pixels. */\n    y: number;\n  }>;\n\n  /**\n   * Stops the camera preview.\n   *\n   * @returns {Promise<void>} A promise that resolves when the camera preview is stopped.\n   * @since 0.0.1\n   */\n  stop(): Promise<void>;\n\n  /**\n   * Captures a picture from the camera.\n   *\n   * If `storeToFile` was set to `true` when starting the preview, the returned\n   * `value` will be an absolute file path on the device instead of a base64 string. Use getBase64FromFilePath to get the base64 string from the file path.\n   *\n   * @param {CameraPreviewPictureOptions} options - The options for capturing the picture.\n   * @returns {Promise<{ value: string; exif: ExifData }>} Resolves with:\n   *   - `value`: base64 string, or file path if `storeToFile` is true\n   *   - `exif`: extracted EXIF metadata when available\n   * @since 0.0.1\n   */\n  capture(options: CameraPreviewPictureOptions): Promise<{ value: string; exif: ExifData }>;\n\n  /**\n   * Captures a single frame from the camera preview stream.\n   *\n   * @param {CameraSampleOptions} options - The options for capturing the sample.\n   * @returns {Promise<{ value: string }>} A promise that resolves with the sample image as a base64 encoded string.\n   * @since 0.0.1\n   */\n  captureSample(options: CameraSampleOptions): Promise<{ value: string }>;\n\n  /**\n   * Gets the flash modes supported by the active camera.\n   *\n   * @returns {Promise<{ result: CameraPreviewFlashMode[] }>} A promise that resolves with an array of supported flash modes.\n   * @since 0.0.1\n   */\n  getSupportedFlashModes(): Promise<{\n    result: CameraPreviewFlashMode[];\n  }>;\n\n  /**\n   * Set the aspect ratio of the camera preview.\n   *\n   * @param {{ aspectRatio: '4:3' | '16:9'; x?: number; y?: number }} options - The desired aspect ratio and optional position.\n   *   - aspectRatio: The desired aspect ratio ('4:3' or '16:9')\n   *   - x: Optional x coordinate for positioning. If not provided, view will be auto-centered horizontally.\n   *   - y: Optional y coordinate for positioning. If not provided, view will be auto-centered vertically.\n   * @returns {Promise<{ width: number; height: number; x: number; y: number }>} A promise that resolves with the actual preview dimensions and position.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  setAspectRatio(options: { aspectRatio: '4:3' | '16:9'; x?: number; y?: number }): Promise<{\n    width: number;\n    height: number;\n    x: number;\n    y: number;\n  }>;\n\n  /**\n   * Gets the current aspect ratio of the camera preview.\n   *\n   * @returns {Promise<{ aspectRatio: '4:3' | '16:9' }>} A promise that resolves with the current aspect ratio.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  getAspectRatio(): Promise<{ aspectRatio: '4:3' | '16:9' }>;\n\n  /**\n   * Sets the grid mode of the camera preview overlay.\n   *\n   * @param {{ gridMode: GridMode }} options - The desired grid mode ('none', '3x3', or '4x4').\n   * @returns {Promise<void>} A promise that resolves when the grid mode is set.\n   * @since 8.0.0\n   */\n  setGridMode(options: { gridMode: GridMode }): Promise<void>;\n\n  /**\n   * Gets the current grid mode of the camera preview overlay.\n   *\n   * @returns {Promise<{ gridMode: GridMode }>} A promise that resolves with the current grid mode.\n   * @since 8.0.0\n   */\n  getGridMode(): Promise<{ gridMode: GridMode }>;\n\n  /**\n   * Checks the current camera (and optionally microphone) permission status without prompting the system dialog.\n   *\n   * @param options Set `disableAudio` to `false` to also include microphone status (defaults to `true`).\n   * @returns {Promise<CameraPermissionStatus>} A promise resolving to the current authorization states.\n   * @since 8.7.0\n   */\n  checkPermissions(options?: Pick<PermissionRequestOptions, 'disableAudio'>): Promise<CameraPermissionStatus>;\n\n  /**\n   * Requests camera (and optional microphone) permissions. If permissions are already granted or denied,\n   * the current status is returned without prompting. When `showSettingsAlert` is true and permissions are denied,\n   * a platform specific alert guiding the user to the app settings will be presented.\n   *\n   * @param {PermissionRequestOptions} options - Configuration for the permission request behaviour.\n   * @returns {Promise<CameraPermissionStatus>} A promise resolving to the final authorization states.\n   * @since 8.7.0\n   */\n  requestPermissions(options?: PermissionRequestOptions): Promise<CameraPermissionStatus>;\n\n  /**\n   * Gets the horizontal field of view (FoV) for the active camera.\n   * Note: This can be an estimate on some devices.\n   *\n   * @returns {Promise<{ result: number }>} A promise that resolves with the horizontal field of view in degrees.\n   * @since 0.0.1\n   */\n  getHorizontalFov(): Promise<{\n    result: number;\n  }>;\n\n  /**\n   * Gets the supported picture sizes for all cameras.\n   *\n   * @returns {Promise<{ supportedPictureSizes: SupportedPictureSizes[] }>} A promise that resolves with the list of supported sizes.\n   * @since 7.4.0\n   */\n  getSupportedPictureSizes(): Promise<{\n    supportedPictureSizes: SupportedPictureSizes[];\n  }>;\n\n  /**\n   * Sets the flash mode for the active camera.\n   *\n   * @param {{ flashMode: CameraPreviewFlashMode | string }} options - The desired flash mode.\n   * @returns {Promise<void>} A promise that resolves when the flash mode is set.\n   * @since 0.0.1\n   */\n  setFlashMode(options: { flashMode: CameraPreviewFlashMode | string }): Promise<void>;\n\n  /**\n   * Toggles between the front and rear cameras.\n   *\n   * @returns {Promise<void>} A promise that resolves when the camera is flipped.\n   * @since 0.0.1\n   */\n  flip(): Promise<void>;\n\n  /**\n   * Sets the opacity of the camera preview.\n   *\n   * @param {CameraOpacityOptions} options - The opacity options.\n   * @returns {Promise<void>} A promise that resolves when the opacity is set.\n   * @since 0.0.1\n   */\n  setOpacity(options: CameraOpacityOptions): Promise<void>;\n\n  /**\n   * Stops an ongoing video recording.\n   *\n   * @returns {Promise<{ videoFilePath: string }>} A promise that resolves with the path to the recorded video file.\n   * @since 0.0.1\n   */\n  stopRecordVideo(): Promise<{ videoFilePath: string }>;\n\n  /**\n   * Starts recording a video.\n   *\n   * @param {CameraPreviewOptions} options - The options for video recording. Only iOS.\n   * @returns {Promise<void>} A promise that resolves when video recording starts.\n   * @since 0.0.1\n   */\n  startRecordVideo(options: CameraPreviewOptions): Promise<void>;\n\n  /**\n   * Checks if the camera preview is currently running.\n   *\n   * @returns {Promise<{ isRunning: boolean }>} A promise that resolves with the running state.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  isRunning(): Promise<{ isRunning: boolean }>;\n\n  /**\n   * Gets all available camera devices.\n   *\n   * @returns {Promise<{ devices: CameraDevice[] }>} A promise that resolves with the list of available camera devices.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  getAvailableDevices(): Promise<{ devices: CameraDevice[] }>;\n\n  /**\n   * Gets the current zoom state, including min/max and current lens info.\n   *\n   * @returns {Promise<{ min: number; max: number; current: number; lens: LensInfo }>} A promise that resolves with the zoom state.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  getZoom(): Promise<{\n    min: number;\n    max: number;\n    current: number;\n    lens: LensInfo;\n  }>;\n\n  /**\n   * Returns zoom button values for quick switching.\n   * - iOS/Android: includes 0.5 if ultra-wide available; 1 and 2 if wide available; 3 if telephoto available\n   * - Web: unsupported\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  getZoomButtonValues(): Promise<{ values: number[] }>;\n\n  /**\n   * Sets the zoom level of the camera.\n   *\n   * @param {{ level: number; ramp?: boolean; autoFocus?: boolean }} options - The desired zoom level. `ramp` is currently unused. `autoFocus` defaults to true.\n   * @returns {Promise<void>} A promise that resolves when the zoom level is set.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  setZoom(options: { level: number; ramp?: boolean; autoFocus?: boolean }): Promise<void>;\n\n  /**\n   * Gets the current flash mode.\n   *\n   * @returns {Promise<{ flashMode: FlashMode }>} A promise that resolves with the current flash mode.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  getFlashMode(): Promise<{ flashMode: FlashMode }>;\n\n  /**\n   * Removes all registered listeners.\n   *\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  removeAllListeners(): Promise<void>;\n\n  /**\n   * Switches the active camera to the one with the specified `deviceId`.\n   *\n   * @param {{ deviceId: string }} options - The ID of the device to switch to.\n   * @returns {Promise<void>} A promise that resolves when the camera is switched.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  setDeviceId(options: { deviceId: string }): Promise<void>;\n\n  /**\n   * Gets the ID of the currently active camera device.\n   *\n   * @returns {Promise<{ deviceId: string }>} A promise that resolves with the current device ID.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  getDeviceId(): Promise<{ deviceId: string }>;\n\n  /**\n   * Gets the current preview size and position.\n   * @returns {Promise<{x: number, y: number, width: number, height: number}>}\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  getPreviewSize(): Promise<{\n    x: number;\n    y: number;\n    width: number;\n    height: number;\n  }>;\n  /**\n   * Sets the preview size and position.\n   * @param options The new position and dimensions.\n   * @returns {Promise<{ width: number; height: number; x: number; y: number }>} A promise that resolves with the actual preview dimensions and position.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  setPreviewSize(options: { x?: number; y?: number; width: number; height: number }): Promise<{\n    width: number;\n    height: number;\n    x: number;\n    y: number;\n  }>;\n\n  /**\n   * Sets the camera focus to a specific point in the preview.\n   *\n   * Note: The plugin does not attach any native tap-to-focus gesture handlers. Handle taps in\n   * your HTML/JS (e.g., on the overlaying UI), then pass normalized coordinates here.\n   *\n   * @param {Object} options - The focus options.\n   * @param {number} options.x - The x coordinate in the preview view to focus on (0-1 normalized).\n   * @param {number} options.y - The y coordinate in the preview view to focus on (0-1 normalized).\n   * @returns {Promise<void>} A promise that resolves when the focus is set.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  setFocus(options: { x: number; y: number }): Promise<void>;\n\n  /**\n   * Adds a listener for screen resize events.\n   * @param {string} eventName - The event name to listen for.\n   * @param {Function} listenerFunc - The function to call when the event is triggered.\n   * @returns {Promise<PluginListenerHandle>} A promise that resolves with a handle to the listener.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  addListener(\n    eventName: 'screenResize',\n    listenerFunc: (data: { width: number; height: number; x: number; y: number }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /**\n   * Adds a listener for orientation change events.\n   * @param {string} eventName - The event name to listen for.\n   * @param {Function} listenerFunc - The function to call when the event is triggered.\n   * @returns {Promise<PluginListenerHandle>} A promise that resolves with a handle to the listener.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  addListener(\n    eventName: 'orientationChange',\n    listenerFunc: (data: { orientation: DeviceOrientation }) => void,\n  ): Promise<PluginListenerHandle>;\n  /**\n   * Deletes a file at the given absolute path on the device.\n   * Use this to quickly clean up temporary images created with `storeToFile`.\n   * On web, this is not supported and will throw.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  deleteFile(options: { path: string }): Promise<{ success: boolean }>;\n\n  /**\n   * Gets the safe area insets for devices.\n   * Returns the orientation-aware notch/camera cutout inset and the current orientation.\n   * In portrait mode: returns top inset (notch at top).\n   * In landscape mode: returns left inset (notch moved to side).\n   * This specifically targets the cutout area (notch, punch hole, etc.) that all modern phones have.\n   *\n   * Android: Values returned in dp (logical pixels).\n   * iOS: Values returned in physical pixels, excluding status bar (only pure notch/cutout size).\n   *\n   * @platform android, ios\n   */\n  getSafeAreaInsets(): Promise<SafeAreaInsets>;\n\n  /**\n   * Gets the current device orientation in a cross-platform format.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  getOrientation(): Promise<{ orientation: DeviceOrientation }>;\n\n  /**\n   * Returns the exposure modes supported by the active camera.\n   * Modes can include: 'locked', 'auto', 'continuous', 'custom'.\n   * @platform android, ios\n   */\n  getExposureModes(): Promise<{ modes: ExposureMode[] }>;\n\n  /**\n   * Returns the current exposure mode.\n   * @platform android, ios\n   */\n  getExposureMode(): Promise<{ mode: ExposureMode }>;\n\n  /**\n   * Sets the exposure mode.\n   * @platform android, ios\n   */\n  setExposureMode(options: { mode: ExposureMode }): Promise<void>;\n\n  /**\n   * Returns the exposure compensation (EV bias) supported range.\n   * @platform ios, android\n   */\n  getExposureCompensationRange(): Promise<{\n    min: number;\n    max: number;\n    step: number;\n  }>;\n\n  /**\n   * Returns the current exposure compensation (EV bias).\n   * @platform ios, android\n   */\n  getExposureCompensation(): Promise<{ value: number }>;\n\n  /**\n   * Sets the exposure compensation (EV bias). Value will be clamped to range.\n   * @platform ios, android\n   */\n  setExposureCompensation(options: { value: number }): Promise<void>;\n\n  /**\n   * Get the native Capacitor plugin version\n   *\n   * @returns {Promise<{ id: string }>} an Promise with version for this device\n   * @throws An error if the something went wrong\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n}\n"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"AAwBA,MAAM,CAAN,IAAY,UAQX;AARD,WAAY,UAAU;IACpB,sCAAwB,CAAA;IACxB,sCAAwB,CAAA;IACxB,qCAAuB,CAAA;IACvB,sCAAwB,CAAA;IACxB,2BAAa,CAAA;IACb,oCAAsB,CAAA;IACtB,+BAAiB,CAAA;AACnB,CAAC,EARW,UAAU,KAAV,UAAU,QAQrB","sourcesContent":["import type { PermissionState, PluginListenerHandle } from '@capacitor/core';\n\nexport type CameraPosition = 'rear' | 'front';\n\nexport type FlashMode = CameraPreviewFlashMode;\n\nexport type GridMode = 'none' | '3x3' | '4x4';\n\nexport type CameraPositioning = 'center' | 'top' | 'bottom';\n\nexport interface CameraPermissionStatus {\n  camera: PermissionState;\n  microphone?: PermissionState;\n}\n\nexport interface PermissionRequestOptions {\n  disableAudio?: boolean;\n  showSettingsAlert?: boolean;\n  title?: string;\n  message?: string;\n  openSettingsButtonTitle?: string;\n  cancelButtonTitle?: string;\n}\n\nexport enum DeviceType {\n  ULTRA_WIDE = 'ultraWide',\n  WIDE_ANGLE = 'wideAngle',\n  TELEPHOTO = 'telephoto',\n  TRUE_DEPTH = 'trueDepth',\n  DUAL = 'dual',\n  DUAL_WIDE = 'dualWide',\n  TRIPLE = 'triple',\n}\n\n/**\n * Represents a single camera lens on a device. A {@link CameraDevice} can have multiple lenses.\n */\nexport interface CameraLens {\n  /** A human-readable name for the lens, e.g., \"Ultra-Wide\". */\n  label: string;\n  /** The type of the camera lens. */\n  deviceType: DeviceType;\n  /** The focal length of the lens in millimeters. */\n  focalLength: number;\n  /** The base zoom factor for this lens (e.g., 0.5 for ultra-wide, 1.0 for wide). */\n  baseZoomRatio: number;\n  /** The minimum zoom factor supported by this specific lens. */\n  minZoom: number;\n  /** The maximum zoom factor supported by this specific lens. */\n  maxZoom: number;\n}\n\n/**\n * Represents a physical camera on the device (e.g., the front-facing camera).\n */\nexport interface CameraDevice {\n  /** A unique identifier for the camera device. */\n  deviceId: string;\n  /** A human-readable name for the camera device. */\n  label: string;\n  /** The physical position of the camera on the device. */\n  position: CameraPosition;\n  /** A list of all available lenses for this camera device. */\n  lenses: CameraLens[];\n  /** The overall minimum zoom factor available across all lenses on this device. */\n  minZoom: number;\n  /** The overall maximum zoom factor available across all lenses on this device. */\n  maxZoom: number;\n  /** Identifies whether the device is a logical camera (composed of multiple physical lenses). */\n  isLogical: boolean;\n}\n\n/**\n * Represents the detailed information of the currently active lens.\n */\nexport interface LensInfo {\n  /** The focal length of the active lens in millimeters. */\n  focalLength: number;\n  /** The device type of the active lens. */\n  deviceType: DeviceType;\n  /** The base zoom ratio of the active lens (e.g., 0.5x, 1.0x). */\n  baseZoomRatio: number;\n  /** The current digital zoom factor applied on top of the base zoom. */\n  digitalZoom: number;\n}\n\n/**\n * Defines the configuration options for starting the camera preview.\n */\nexport interface CameraPreviewOptions {\n  /**\n   * The parent element to attach the video preview to.\n   * @platform web\n   */\n  parent?: string;\n  /**\n   * A CSS class name to add to the preview element.\n   * @platform web\n   */\n  className?: string;\n  /**\n   * The width of the preview in pixels. Defaults to the screen width.\n   * @platform android, ios, web\n   */\n  width?: number;\n  /**\n   * The height of the preview in pixels. Defaults to the screen height.\n   * @platform android, ios, web\n   */\n  height?: number;\n  /**\n   * The horizontal origin of the preview, in pixels.\n   * @platform android, ios\n   */\n  x?: number;\n  /**\n   * The vertical origin of the preview, in pixels.\n   * @platform android, ios\n   */\n  y?: number;\n  /**\n   * The aspect ratio of the camera preview, '4:3' or '16:9' or 'fill'.\n   * Cannot be set if width or height is provided, otherwise the call will be rejected.\n   * Use setPreviewSize to adjust size after starting.\n   *\n   * @since 2.0.0\n   */\n  aspectRatio?: '4:3' | '16:9';\n  /**\n   * The grid overlay to display on the camera preview.\n   * @default \"none\"\n   * @since 2.1.0\n   */\n  gridMode?: GridMode;\n  /**\n   * Adjusts the y-position to account for safe areas (e.g., notches).\n   * @platform ios\n   * @default false\n   */\n  includeSafeAreaInsets?: boolean;\n  /**\n   * If true, places the preview behind the webview.\n   * @platform android\n   * @default true\n   */\n  toBack?: boolean;\n  /**\n   * Bottom padding for the preview, in pixels.\n   * @platform android, ios\n   */\n  paddingBottom?: number;\n  /**\n   * Whether to rotate the preview when the device orientation changes.\n   * @platform ios\n   * @default true\n   */\n  rotateWhenOrientationChanged?: boolean;\n  /**\n   * The camera to use.\n   * @default \"rear\"\n   */\n  position?: CameraPosition | string;\n  /**\n   * If true, saves the captured image to a file and returns the file path.\n   * If false, returns a base64 encoded string.\n   * @default false\n   */\n  storeToFile?: boolean;\n  /**\n   * If true, prevents the plugin from rotating the image based on EXIF data.\n   * @platform android\n   * @default false\n   */\n  disableExifHeaderStripping?: boolean;\n  /**\n   * If true, disables the audio stream, preventing audio permission requests.\n   * @default true\n   */\n  disableAudio?: boolean;\n  /**\n   * If true, locks the device orientation while the camera is active.\n   * @platform android\n   * @default false\n   */\n  lockAndroidOrientation?: boolean;\n  /**\n   * If true, allows the camera preview's opacity to be changed.\n   * @platform android, web\n   * @default false\n   */\n  enableOpacity?: boolean;\n\n  /**\n   * If true, disables the visual focus indicator when tapping to focus.\n   * @platform android, ios\n   * @default false\n   */\n  disableFocusIndicator?: boolean;\n  /**\n   * The `deviceId` of the camera to use. If provided, `position` is ignored.\n   * @platform ios\n   */\n  deviceId?: string;\n  /**\n   * The initial zoom level when starting the camera preview.\n   * If the requested zoom level is not available, the native plugin will reject.\n   * @default 1.0\n   * @platform android, ios\n   * @since 2.2.0\n   */\n  initialZoomLevel?: number;\n  /**\n   * The vertical positioning of the camera preview.\n   * @default \"center\"\n   * @platform android, ios, web\n   * @since 2.3.0\n   */\n  positioning?: CameraPositioning;\n  /**\n   * If true, enables video capture capabilities when the camera starts.\n   * @default false\n   * @platform android\n   * @since 7.11.0\n   */\n  enableVideoMode?: boolean;\n  /**\n   * If true, forces the camera to start/restart even if it's already running or busy.\n   * This will kill the current camera session and start a new one, ignoring all state checks.\n   * @default false\n   * @platform android, ios, web\n   */\n  force?: boolean;\n}\n\n/**\n * Defines the options for capturing a picture.\n */\nexport interface CameraPreviewPictureOptions {\n  /**\n   * The maximum height of the picture in pixels. The image will be resized to fit within this height while maintaining aspect ratio.\n   * If not specified the captured image will match the preview's visible area.\n   */\n  height?: number;\n  /**\n   * The maximum width of the picture in pixels. The image will be resized to fit within this width while maintaining aspect ratio.\n   * If not specified the captured image will match the preview's visible area.\n   */\n  width?: number;\n  /**\n   * The quality of the captured image, from 0 to 100.\n   * Does not apply to `png` format.\n   * @default 85\n   */\n  quality?: number;\n  /**\n   * The format of the captured image.\n   * @default \"jpeg\"\n   */\n  format?: PictureFormat;\n  /**\n   * If true, the captured image will be saved to the user's gallery.\n   * @default false\n   * @since 7.5.0\n   */\n  saveToGallery?: boolean;\n  /**\n   * If true, the plugin will attempt to add GPS location data to the image's EXIF metadata.\n   * This may prompt the user for location permissions.\n   * @default false\n   * @since 7.6.0\n   */\n  withExifLocation?: boolean;\n  /**\n   * If true, the plugin will embed a timestamp in the top-right corner of the image.\n   * @default false\n   * @since 7.17.0\n   */\n  embedTimestamp?: boolean;\n  /**\n   * If true, the plugin will embed the current location in the top-right corner of the image.\n   * Requires `withExifLocation` to be enabled.\n   * @default false\n   * @since 7.18.0\n   */\n  embedLocation?: boolean;\n  /**\n   * Sets the priority for photo quality vs. capture speed.\n   * - \"speed\": Prioritizes faster capture times, may reduce image quality.\n   * - \"balanced\": Aims for a balance between quality and speed.\n   * - \"quality\": Prioritizes image quality, may reduce capture speed.\n   * See https://developer.apple.com/documentation/avfoundation/avcapturephotosettings/photoqualityprioritization for details.\n   *\n   * @since 7.21.0\n   * @platform ios\n   * @default \"speed\"\n   */\n  photoQualityPrioritization?: 'speed' | 'balanced' | 'quality';\n}\n\n/** Represents EXIF data extracted from an image. */\nexport interface ExifData {\n  [key: string]: any;\n}\n\nexport type PictureFormat = 'jpeg' | 'png';\n\n/** Defines a standard picture size with width and height. */\nexport interface PictureSize {\n  /** The width of the picture in pixels. */\n  width: number;\n  /** The height of the picture in pixels. */\n  height: number;\n}\n\n/** Represents the supported picture sizes for a camera facing a certain direction. */\nexport interface SupportedPictureSizes {\n  /** The camera direction (\"front\" or \"rear\"). */\n  facing: string;\n  /** A list of supported picture sizes for this camera. */\n  supportedPictureSizes: PictureSize[];\n}\n\n/**\n * Defines the options for capturing a sample frame from the camera preview.\n */\nexport interface CameraSampleOptions {\n  /**\n   * The quality of the captured sample, from 0 to 100.\n   * @default 85\n   */\n  quality?: number;\n}\n\n/**\n * The available flash modes for the camera.\n * 'torch' is a continuous light mode.\n */\nexport type CameraPreviewFlashMode = 'off' | 'on' | 'auto' | 'torch';\n\n/** Reusable exposure mode type for cross-platform support. */\nexport type ExposureMode = 'AUTO' | 'LOCK' | 'CONTINUOUS' | 'CUSTOM';\n\n/**\n * Defines the options for setting the camera preview's opacity.\n */\nexport interface CameraOpacityOptions {\n  /**\n   * The opacity percentage, from 0.0 (fully transparent) to 1.0 (fully opaque).\n   * @default 1.0\n   */\n  opacity?: number;\n}\n\n/**\n * Represents safe area insets for devices.\n * Android: Values are expressed in logical pixels (dp) to match JS layout units.\n * iOS: Values are expressed in physical pixels and exclude status bar.\n */\nexport interface SafeAreaInsets {\n  /** Current device orientation (1 = portrait, 2 = landscape, 0 = unknown). */\n  orientation: number;\n  /**\n   * Orientation-aware notch/camera cutout inset (excluding status bar).\n   * In portrait mode: returns top inset (notch at top).\n   * In landscape mode: returns left inset (notch at side).\n   * Android: Value in dp, iOS: Value in pixels (status bar excluded).\n   */\n  top: number;\n}\n\n/**\n * Canonical device orientation values across platforms.\n */\nexport type DeviceOrientation = 'portrait' | 'landscape-left' | 'landscape-right' | 'portrait-upside-down' | 'unknown';\n\n/**\n * The main interface for the CameraPreview plugin.\n */\nexport interface CameraPreviewPlugin {\n  /**\n   * Starts the camera preview.\n   *\n   * @param {CameraPreviewOptions} options - The configuration for the camera preview.\n   * @returns {Promise<{ width: number; height: number; x: number; y: number }>} A promise that resolves with the preview dimensions.\n   * @since 0.0.1\n   */\n  start(options: CameraPreviewOptions): Promise<{\n    /** The width of the preview in pixels. */\n    width: number;\n    /** The height of the preview in pixels. */\n    height: number;\n    /** The horizontal origin of the preview, in pixels. */\n    x: number;\n    /** The vertical origin of the preview, in pixels. */\n    y: number;\n  }>;\n\n  /**\n   * Stops the camera preview.\n   *\n   * @param {object} options - Optional configuration for stopping the camera.\n   * @param {boolean} options.force - If true, forces the camera to stop even if busy or capturing. Default: false.\n   * @returns {Promise<void>} A promise that resolves when the camera preview is stopped.\n   * @since 0.0.1\n   */\n  stop(options?: { force?: boolean }): Promise<void>;\n\n  /**\n   * Captures a picture from the camera.\n   *\n   * If `storeToFile` was set to `true` when starting the preview, the returned\n   * `value` will be an absolute file path on the device instead of a base64 string. Use getBase64FromFilePath to get the base64 string from the file path.\n   *\n   * @param {CameraPreviewPictureOptions} options - The options for capturing the picture.\n   * @returns {Promise<{ value: string; exif: ExifData }>} Resolves with:\n   *   - `value`: base64 string, or file path if `storeToFile` is true\n   *   - `exif`: extracted EXIF metadata when available\n   * @since 0.0.1\n   */\n  capture(options: CameraPreviewPictureOptions): Promise<{ value: string; exif: ExifData }>;\n\n  /**\n   * Captures a single frame from the camera preview stream.\n   *\n   * @param {CameraSampleOptions} options - The options for capturing the sample.\n   * @returns {Promise<{ value: string }>} A promise that resolves with the sample image as a base64 encoded string.\n   * @since 0.0.1\n   */\n  captureSample(options: CameraSampleOptions): Promise<{ value: string }>;\n\n  /**\n   * Gets the flash modes supported by the active camera.\n   *\n   * @returns {Promise<{ result: CameraPreviewFlashMode[] }>} A promise that resolves with an array of supported flash modes.\n   * @since 0.0.1\n   */\n  getSupportedFlashModes(): Promise<{\n    result: CameraPreviewFlashMode[];\n  }>;\n\n  /**\n   * Set the aspect ratio of the camera preview.\n   *\n   * @param {{ aspectRatio: '4:3' | '16:9'; x?: number; y?: number }} options - The desired aspect ratio and optional position.\n   *   - aspectRatio: The desired aspect ratio ('4:3' or '16:9')\n   *   - x: Optional x coordinate for positioning. If not provided, view will be auto-centered horizontally.\n   *   - y: Optional y coordinate for positioning. If not provided, view will be auto-centered vertically.\n   * @returns {Promise<{ width: number; height: number; x: number; y: number }>} A promise that resolves with the actual preview dimensions and position.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  setAspectRatio(options: { aspectRatio: '4:3' | '16:9'; x?: number; y?: number }): Promise<{\n    width: number;\n    height: number;\n    x: number;\n    y: number;\n  }>;\n\n  /**\n   * Gets the current aspect ratio of the camera preview.\n   *\n   * @returns {Promise<{ aspectRatio: '4:3' | '16:9' }>} A promise that resolves with the current aspect ratio.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  getAspectRatio(): Promise<{ aspectRatio: '4:3' | '16:9' }>;\n\n  /**\n   * Sets the grid mode of the camera preview overlay.\n   *\n   * @param {{ gridMode: GridMode }} options - The desired grid mode ('none', '3x3', or '4x4').\n   * @returns {Promise<void>} A promise that resolves when the grid mode is set.\n   * @since 8.0.0\n   */\n  setGridMode(options: { gridMode: GridMode }): Promise<void>;\n\n  /**\n   * Gets the current grid mode of the camera preview overlay.\n   *\n   * @returns {Promise<{ gridMode: GridMode }>} A promise that resolves with the current grid mode.\n   * @since 8.0.0\n   */\n  getGridMode(): Promise<{ gridMode: GridMode }>;\n\n  /**\n   * Checks the current camera (and optionally microphone) permission status without prompting the system dialog.\n   *\n   * @param options Set `disableAudio` to `false` to also include microphone status (defaults to `true`).\n   * @returns {Promise<CameraPermissionStatus>} A promise resolving to the current authorization states.\n   * @since 8.7.0\n   */\n  checkPermissions(options?: Pick<PermissionRequestOptions, 'disableAudio'>): Promise<CameraPermissionStatus>;\n\n  /**\n   * Requests camera (and optional microphone) permissions. If permissions are already granted or denied,\n   * the current status is returned without prompting. When `showSettingsAlert` is true and permissions are denied,\n   * a platform specific alert guiding the user to the app settings will be presented.\n   *\n   * @param {PermissionRequestOptions} options - Configuration for the permission request behaviour.\n   * @returns {Promise<CameraPermissionStatus>} A promise resolving to the final authorization states.\n   * @since 8.7.0\n   */\n  requestPermissions(options?: PermissionRequestOptions): Promise<CameraPermissionStatus>;\n\n  /**\n   * Gets the horizontal field of view (FoV) for the active camera.\n   * Note: This can be an estimate on some devices.\n   *\n   * @returns {Promise<{ result: number }>} A promise that resolves with the horizontal field of view in degrees.\n   * @since 0.0.1\n   */\n  getHorizontalFov(): Promise<{\n    result: number;\n  }>;\n\n  /**\n   * Gets the supported picture sizes for all cameras.\n   *\n   * @returns {Promise<{ supportedPictureSizes: SupportedPictureSizes[] }>} A promise that resolves with the list of supported sizes.\n   * @since 7.4.0\n   */\n  getSupportedPictureSizes(): Promise<{\n    supportedPictureSizes: SupportedPictureSizes[];\n  }>;\n\n  /**\n   * Sets the flash mode for the active camera.\n   *\n   * @param {{ flashMode: CameraPreviewFlashMode | string }} options - The desired flash mode.\n   * @returns {Promise<void>} A promise that resolves when the flash mode is set.\n   * @since 0.0.1\n   */\n  setFlashMode(options: { flashMode: CameraPreviewFlashMode | string }): Promise<void>;\n\n  /**\n   * Toggles between the front and rear cameras.\n   *\n   * @returns {Promise<void>} A promise that resolves when the camera is flipped.\n   * @since 0.0.1\n   */\n  flip(): Promise<void>;\n\n  /**\n   * Sets the opacity of the camera preview.\n   *\n   * @param {CameraOpacityOptions} options - The opacity options.\n   * @returns {Promise<void>} A promise that resolves when the opacity is set.\n   * @since 0.0.1\n   */\n  setOpacity(options: CameraOpacityOptions): Promise<void>;\n\n  /**\n   * Stops an ongoing video recording.\n   *\n   * @returns {Promise<{ videoFilePath: string }>} A promise that resolves with the path to the recorded video file.\n   * @since 0.0.1\n   */\n  stopRecordVideo(): Promise<{ videoFilePath: string }>;\n\n  /**\n   * Starts recording a video.\n   *\n   * @param {CameraPreviewOptions} options - The options for video recording. Only iOS.\n   * @returns {Promise<void>} A promise that resolves when video recording starts.\n   * @since 0.0.1\n   */\n  startRecordVideo(options: CameraPreviewOptions): Promise<void>;\n\n  /**\n   * Checks if the camera preview is currently running.\n   *\n   * @returns {Promise<{ isRunning: boolean }>} A promise that resolves with the running state.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  isRunning(): Promise<{ isRunning: boolean }>;\n\n  /**\n   * Gets all available camera devices.\n   *\n   * @returns {Promise<{ devices: CameraDevice[] }>} A promise that resolves with the list of available camera devices.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  getAvailableDevices(): Promise<{ devices: CameraDevice[] }>;\n\n  /**\n   * Gets the current zoom state, including min/max and current lens info.\n   *\n   * @returns {Promise<{ min: number; max: number; current: number; lens: LensInfo }>} A promise that resolves with the zoom state.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  getZoom(): Promise<{\n    min: number;\n    max: number;\n    current: number;\n    lens: LensInfo;\n  }>;\n\n  /**\n   * Returns zoom button values for quick switching.\n   * - iOS/Android: includes 0.5 if ultra-wide available; 1 and 2 if wide available; 3 if telephoto available\n   * - Web: unsupported\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  getZoomButtonValues(): Promise<{ values: number[] }>;\n\n  /**\n   * Sets the zoom level of the camera.\n   *\n   * @param {{ level: number; ramp?: boolean; autoFocus?: boolean }} options - The desired zoom level. `ramp` is currently unused. `autoFocus` defaults to true.\n   * @returns {Promise<void>} A promise that resolves when the zoom level is set.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  setZoom(options: { level: number; ramp?: boolean; autoFocus?: boolean }): Promise<void>;\n\n  /**\n   * Gets the current flash mode.\n   *\n   * @returns {Promise<{ flashMode: FlashMode }>} A promise that resolves with the current flash mode.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  getFlashMode(): Promise<{ flashMode: FlashMode }>;\n\n  /**\n   * Removes all registered listeners.\n   *\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  removeAllListeners(): Promise<void>;\n\n  /**\n   * Switches the active camera to the one with the specified `deviceId`.\n   *\n   * @param {{ deviceId: string }} options - The ID of the device to switch to.\n   * @returns {Promise<void>} A promise that resolves when the camera is switched.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  setDeviceId(options: { deviceId: string }): Promise<void>;\n\n  /**\n   * Gets the ID of the currently active camera device.\n   *\n   * @returns {Promise<{ deviceId: string }>} A promise that resolves with the current device ID.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  getDeviceId(): Promise<{ deviceId: string }>;\n\n  /**\n   * Gets the current preview size and position.\n   * @returns {Promise<{x: number, y: number, width: number, height: number}>}\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  getPreviewSize(): Promise<{\n    x: number;\n    y: number;\n    width: number;\n    height: number;\n  }>;\n  /**\n   * Sets the preview size and position.\n   * @param options The new position and dimensions.\n   * @returns {Promise<{ width: number; height: number; x: number; y: number }>} A promise that resolves with the actual preview dimensions and position.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  setPreviewSize(options: { x?: number; y?: number; width: number; height: number }): Promise<{\n    width: number;\n    height: number;\n    x: number;\n    y: number;\n  }>;\n\n  /**\n   * Sets the camera focus to a specific point in the preview.\n   *\n   * Note: The plugin does not attach any native tap-to-focus gesture handlers. Handle taps in\n   * your HTML/JS (e.g., on the overlaying UI), then pass normalized coordinates here.\n   *\n   * @param {Object} options - The focus options.\n   * @param {number} options.x - The x coordinate in the preview view to focus on (0-1 normalized).\n   * @param {number} options.y - The y coordinate in the preview view to focus on (0-1 normalized).\n   * @returns {Promise<void>} A promise that resolves when the focus is set.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  setFocus(options: { x: number; y: number }): Promise<void>;\n\n  /**\n   * Adds a listener for screen resize events.\n   * @param {string} eventName - The event name to listen for.\n   * @param {Function} listenerFunc - The function to call when the event is triggered.\n   * @returns {Promise<PluginListenerHandle>} A promise that resolves with a handle to the listener.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  addListener(\n    eventName: 'screenResize',\n    listenerFunc: (data: { width: number; height: number; x: number; y: number }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /**\n   * Adds a listener for orientation change events.\n   * @param {string} eventName - The event name to listen for.\n   * @param {Function} listenerFunc - The function to call when the event is triggered.\n   * @returns {Promise<PluginListenerHandle>} A promise that resolves with a handle to the listener.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  addListener(\n    eventName: 'orientationChange',\n    listenerFunc: (data: { orientation: DeviceOrientation }) => void,\n  ): Promise<PluginListenerHandle>;\n  /**\n   * Deletes a file at the given absolute path on the device.\n   * Use this to quickly clean up temporary images created with `storeToFile`.\n   * On web, this is not supported and will throw.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  deleteFile(options: { path: string }): Promise<{ success: boolean }>;\n\n  /**\n   * Gets the safe area insets for devices.\n   * Returns the orientation-aware notch/camera cutout inset and the current orientation.\n   * In portrait mode: returns top inset (notch at top).\n   * In landscape mode: returns left inset (notch moved to side).\n   * This specifically targets the cutout area (notch, punch hole, etc.) that all modern phones have.\n   *\n   * Android: Values returned in dp (logical pixels).\n   * iOS: Values returned in physical pixels, excluding status bar (only pure notch/cutout size).\n   *\n   * @platform android, ios\n   */\n  getSafeAreaInsets(): Promise<SafeAreaInsets>;\n\n  /**\n   * Gets the current device orientation in a cross-platform format.\n   * @since 7.5.0\n   * @platform android, ios\n   */\n  getOrientation(): Promise<{ orientation: DeviceOrientation }>;\n\n  /**\n   * Returns the exposure modes supported by the active camera.\n   * Modes can include: 'locked', 'auto', 'continuous', 'custom'.\n   * @platform android, ios\n   */\n  getExposureModes(): Promise<{ modes: ExposureMode[] }>;\n\n  /**\n   * Returns the current exposure mode.\n   * @platform android, ios\n   */\n  getExposureMode(): Promise<{ mode: ExposureMode }>;\n\n  /**\n   * Sets the exposure mode.\n   * @platform android, ios\n   */\n  setExposureMode(options: { mode: ExposureMode }): Promise<void>;\n\n  /**\n   * Returns the exposure compensation (EV bias) supported range.\n   * @platform ios, android\n   */\n  getExposureCompensationRange(): Promise<{\n    min: number;\n    max: number;\n    step: number;\n  }>;\n\n  /**\n   * Returns the current exposure compensation (EV bias).\n   * @platform ios, android\n   */\n  getExposureCompensation(): Promise<{ value: number }>;\n\n  /**\n   * Sets the exposure compensation (EV bias). Value will be clamped to range.\n   * @platform ios, android\n   */\n  setExposureCompensation(options: { value: number }): Promise<void>;\n\n  /**\n   * Get the native Capacitor plugin version\n   *\n   * @returns {Promise<{ id: string }>} an Promise with version for this device\n   * @throws An error if the something went wrong\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n}\n"]}

package/dist/esm/web.d.ts

@@ -33,7 +33,9 @@ export declare class CameraPreviewWeb extends WebPlugin implements CameraPreview
         y: number;
     }>;
     private stopStream;
-    stop(): Promise<void>;
+    stop(_options?: {
+        force?: boolean;
+    }): Promise<void>;
     capture(options: CameraPreviewPictureOptions): Promise<any>;
     captureSample(_options: CameraSampleOptions): Promise<any>;
     stopRecordVideo(): Promise<any>;

package/dist/esm/web.js

@@ -156,9 +156,13 @@ export class CameraPreviewWeb extends WebPlugin {
         if (options.aspectRatio && (options.width || options.height)) {
             throw new Error('Cannot set both aspectRatio and size (width/height). Use setPreviewSize after start.');
         }
-        if (this.isStarted) {
+        if (this.isStarted && !options.force) {
             throw new Error('camera already started');
         }
+        // If force is true and camera is already started, stop it first
+        if (this.isStarted && options.force) {
+            await this.stop({ force: true });
+        }
         this.isBackCamera = true;
         this.isStarted = false;
         const parent = document.getElementById((options === null || options === void 0 ? void 0 : options.parent) || '');
@@ -468,7 +472,8 @@ export class CameraPreviewWeb extends WebPlugin {
                 track.stop();
         }
     }
-    async stop() {
+    async stop(_options) {
+        // Force option doesn't change behavior on web - we always stop immediately
         const video = document.getElementById(DEFAULT_VIDEO_ID);
         if (video) {
             video.pause();