@capgo/camera-preview 7.6.1 → 7.7.0

package/README.md

@@ -95,6 +95,53 @@ await CameraPreview.deleteFile({ path: filePath })
 ```
 
 
+## Exposure controls (iOS & Android)
+
+This plugin exposes camera exposure controls on iOS and Android:
+
+- Exposure modes: `"AUTO" | "LOCK" | "CONTINUOUS" | "CUSTOM"`
+- Exposure compensation (EV bias): get range `{ min, max, step }`, read current value, and set new value
+
+Platform notes:
+
+- iOS: The camera starts in `CONTINUOUS` by default. Switching to `AUTO` or `CONTINUOUS` resets EV to 0. The `step` value is approximated to 0.1 since iOS does not expose the bias step.
+- Android: AE lock/unlock and mode are handled via CameraX + Camera2 interop. The `step` value comes from CameraX `ExposureState` and may vary per device.
+
+Example (TypeScript):
+
+```ts
+import { CameraPreview } from '@capgo/camera-preview';
+
+// Query supported modes
+const { modes } = await CameraPreview.getExposureModes();
+console.log('Supported exposure modes:', modes);
+
+// Get current mode
+const { mode } = await CameraPreview.getExposureMode();
+console.log('Current exposure mode:', mode);
+
+// Set mode (AUTO | LOCK | CONTINUOUS | CUSTOM)
+await CameraPreview.setExposureMode({ mode: 'CONTINUOUS' });
+
+// Get EV range (with step)
+const { min, max, step } = await CameraPreview.getExposureCompensationRange();
+console.log('EV range:', { min, max, step });
+
+// Read current EV
+const { value: currentEV } = await CameraPreview.getExposureCompensation();
+console.log('Current EV:', currentEV);
+
+// Increment EV by one step and clamp to range
+const nextEV = Math.max(min, Math.min(max, currentEV + step));
+await CameraPreview.setExposureCompensation({ value: nextEV });
+```
+
+Example app (Ionic):
+
+- Exposure mode toggle (sun icon) cycles through modes.
+- EV controls (+/−) are placed in a top‑right floating action bar, outside the preview area.
+
+
 # Installation
 
 ```
@@ -267,6 +314,12 @@ Documentation for the [uploader](https://github.com/Cap-go/capacitor-uploader)
 * [`deleteFile(...)`](#deletefile)
 * [`getSafeAreaInsets()`](#getsafeareainsets)
 * [`getOrientation()`](#getorientation)
+* [`getExposureModes()`](#getexposuremodes)
+* [`getExposureMode()`](#getexposuremode)
+* [`setExposureMode(...)`](#setexposuremode)
+* [`getExposureCompensationRange()`](#getexposurecompensationrange)
+* [`getExposureCompensation()`](#getexposurecompensation)
+* [`setExposureCompensation(...)`](#setexposurecompensation)
 * [Interfaces](#interfaces)
 * [Type Aliases](#type-aliases)
 * [Enums](#enums)
@@ -828,6 +881,89 @@ Gets the current device orientation in a cross-platform format.
 --------------------
 
 
+### getExposureModes()
+
+```typescript
+getExposureModes() => Promise<{ modes: ExposureMode[]; }>
+```
+
+Returns the exposure modes supported by the active camera.
+Modes can include: 'locked', 'auto', 'continuous', 'custom'.
+
+**Returns:** <code>Promise&lt;{ modes: ExposureMode[]; }&gt;</code>
+
+--------------------
+
+
+### getExposureMode()
+
+```typescript
+getExposureMode() => Promise<{ mode: ExposureMode; }>
+```
+
+Returns the current exposure mode.
+
+**Returns:** <code>Promise&lt;{ mode: <a href="#exposuremode">ExposureMode</a>; }&gt;</code>
+
+--------------------
+
+
+### setExposureMode(...)
+
+```typescript
+setExposureMode(options: { mode: ExposureMode; }) => Promise<void>
+```
+
+Sets the exposure mode.
+
+| Param         | Type                                                             |
+| ------------- | ---------------------------------------------------------------- |
+| **`options`** | <code>{ mode: <a href="#exposuremode">ExposureMode</a>; }</code> |
+
+--------------------
+
+
+### getExposureCompensationRange()
+
+```typescript
+getExposureCompensationRange() => Promise<{ min: number; max: number; step: number; }>
+```
+
+Returns the exposure compensation (EV bias) supported range.
+
+**Returns:** <code>Promise&lt;{ min: number; max: number; step: number; }&gt;</code>
+
+--------------------
+
+
+### getExposureCompensation()
+
+```typescript
+getExposureCompensation() => Promise<{ value: number; }>
+```
+
+Returns the current exposure compensation (EV bias).
+
+**Returns:** <code>Promise&lt;{ value: number; }&gt;</code>
+
+--------------------
+
+
+### setExposureCompensation(...)
+
+```typescript
+setExposureCompensation(options: { value: number; }) => Promise<void>
+```
+
+Sets the exposure compensation (EV bias). Value will be clamped to range.
+
+| Param         | Type                            |
+| ------------- | ------------------------------- |
+| **`options`** | <code>{ value: number; }</code> |
+
+--------------------
+
+
 ### Interfaces
 
 
@@ -1023,6 +1159,13 @@ Canonical device orientation values across platforms.
 <code>"portrait" | "landscape" | "landscape-left" | "landscape-right" | "portrait-upside-down" | "unknown"</code>
 
 
+#### ExposureMode
+
+Reusable exposure mode type for cross-platform support.
+
+<code>"AUTO" | "LOCK" | "CONTINUOUS" | "CUSTOM"</code>
+
+
 ### Enums
 
 

package/android/src/main/java/com/ahm/capacitor/camera/preview/CameraPreview.java

@@ -82,6 +82,103 @@ public class CameraPreview
   private int lastOrientation = Configuration.ORIENTATION_UNDEFINED;
 
   @PluginMethod
+  public void getExposureModes(PluginCall call) {
+    if (cameraXView == null || !cameraXView.isRunning()) {
+      call.reject("Camera is not running");
+      return;
+    }
+    JSArray arr = new JSArray();
+    for (String m : cameraXView.getExposureModes()) arr.put(m);
+    JSObject ret = new JSObject();
+    ret.put("modes", arr);
+    call.resolve(ret);
+  }
+
+  @PluginMethod
+  public void getExposureMode(PluginCall call) {
+    if (cameraXView == null || !cameraXView.isRunning()) {
+      call.reject("Camera is not running");
+      return;
+    }
+    JSObject ret = new JSObject();
+    ret.put("mode", cameraXView.getExposureMode());
+    call.resolve(ret);
+  }
+
+  @PluginMethod
+  public void setExposureMode(PluginCall call) {
+    if (cameraXView == null || !cameraXView.isRunning()) {
+      call.reject("Camera is not running");
+      return;
+    }
+    String mode = call.getString("mode");
+    if (mode == null || mode.isEmpty()) {
+      call.reject("mode parameter is required");
+      return;
+    }
+    try {
+      cameraXView.setExposureMode(mode);
+      call.resolve();
+    } catch (Exception e) {
+      call.reject("Failed to set exposure mode: " + e.getMessage());
+    }
+  }
+
+  @PluginMethod
+  public void getExposureCompensationRange(PluginCall call) {
+    if (cameraXView == null || !cameraXView.isRunning()) {
+      call.reject("Camera is not running");
+      return;
+    }
+    try {
+      float[] range = cameraXView.getExposureCompensationRange();
+      JSObject ret = new JSObject();
+      ret.put("min", range[0]);
+      ret.put("max", range[1]);
+      ret.put("step", range.length > 2 ? range[2] : 0.1);
+      call.resolve(ret);
+    } catch (Exception e) {
+      call.reject(
+        "Failed to get exposure compensation range: " + e.getMessage()
+      );
+    }
+  }
+
+  @PluginMethod
+  public void getExposureCompensation(PluginCall call) {
+    if (cameraXView == null || !cameraXView.isRunning()) {
+      call.reject("Camera is not running");
+      return;
+    }
+    try {
+      float value = cameraXView.getExposureCompensation();
+      JSObject ret = new JSObject();
+      ret.put("value", value);
+      call.resolve(ret);
+    } catch (Exception e) {
+      call.reject("Failed to get exposure compensation: " + e.getMessage());
+    }
+  }
+
+  @PluginMethod
+  public void setExposureCompensation(PluginCall call) {
+    if (cameraXView == null || !cameraXView.isRunning()) {
+      call.reject("Camera is not running");
+      return;
+    }
+    Float value = call.getFloat("value");
+    if (value == null) {
+      call.reject("value parameter is required");
+      return;
+    }
+    try {
+      cameraXView.setExposureCompensation(value);
+      call.resolve();
+    } catch (Exception e) {
+      call.reject("Failed to set exposure compensation: " + e.getMessage());
+    }
+  }
+
   public void getOrientation(PluginCall call) {
     int orientation = getContext()
       .getResources()

package/android/src/main/java/com/ahm/capacitor/camera/preview/CameraXView.java

@@ -12,6 +12,7 @@ import android.graphics.drawable.GradientDrawable;
 import android.hardware.camera2.CameraAccessException;
 import android.hardware.camera2.CameraCharacteristics;
 import android.hardware.camera2.CameraManager;
+import android.hardware.camera2.CaptureRequest;
 import android.location.Location;
 import android.media.MediaScannerConnection;
 import android.os.Build;
@@ -19,6 +20,8 @@ import android.os.Environment;
 import android.util.Base64;
 import android.util.DisplayMetrics;
 import android.util.Log;
+import android.util.Range;
+import android.util.Rational;
 import android.util.Size;
 import android.view.MotionEvent;
 import android.view.View;
@@ -30,12 +33,15 @@ import android.widget.FrameLayout;
 import androidx.annotation.NonNull;
 import androidx.annotation.OptIn;
 import androidx.annotation.RequiresApi;
+import androidx.camera.camera2.interop.Camera2CameraControl;
 import androidx.camera.camera2.interop.Camera2CameraInfo;
+import androidx.camera.camera2.interop.CaptureRequestOptions;
 import androidx.camera.camera2.interop.ExperimentalCamera2Interop;
 import androidx.camera.core.AspectRatio;
 import androidx.camera.core.Camera;
 import androidx.camera.core.CameraInfo;
 import androidx.camera.core.CameraSelector;
+import androidx.camera.core.ExposureState;
 import androidx.camera.core.FocusMeteringAction;
 import androidx.camera.core.FocusMeteringResult;
 import androidx.camera.core.ImageCapture;
@@ -69,6 +75,7 @@ import java.nio.ByteBuffer;
 import java.text.SimpleDateFormat;
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
 import java.util.Locale;
@@ -115,6 +122,7 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
   private boolean isRunning = false;
   private Size currentPreviewResolution = null;
   private ListenableFuture<FocusMeteringResult> currentFocusFuture = null; // Track current focus operation
+  private String currentExposureMode = "CONTINUOUS"; // Default behavior
 
   public CameraXView(Context context, WebView webView) {
     this.context = context;
@@ -1807,6 +1815,22 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
       currentFocusFuture.cancel(true);
     }
 
+    // Reset exposure compensation to 0 on tap-to-focus
+    try {
+      ExposureState state = camera.getCameraInfo().getExposureState();
+      Range<Integer> range = state.getExposureCompensationRange();
+      int zeroIdx = 0;
+      if (range != null && !range.contains(0)) {
+        // Choose the closest index to 0 if 0 is not available
+        zeroIdx = Math.abs(range.getLower()) < Math.abs(range.getUpper())
+          ? range.getLower()
+          : range.getUpper();
+      }
+      camera.getCameraControl().setExposureCompensationIndex(zeroIdx);
+    } catch (Exception e) {
+      Log.w(TAG, "setFocus: Failed to reset exposure compensation to 0", e);
+    }
+
     int viewWidth = previewView.getWidth();
     int viewHeight = previewView.getHeight();
 
@@ -1878,6 +1902,108 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
     }
   }
 
+  // ===================== Exposure APIs =====================
+  public java.util.List<String> getExposureModes() {
+    return Arrays.asList("LOCK", "CONTINUOUS");
+  }
+
+  public String getExposureMode() {
+    return currentExposureMode;
+  }
+
+  @OptIn(markerClass = ExperimentalCamera2Interop.class)
+  public void setExposureMode(String mode) throws Exception {
+    if (camera == null) {
+      throw new Exception("Camera not initialized");
+    }
+    if (mode == null) {
+      throw new Exception("mode is required");
+    }
+    String normalized = mode.toUpperCase(Locale.US);
+
+    try {
+      Camera2CameraControl c2 = Camera2CameraControl.from(
+        camera.getCameraControl()
+      );
+      switch (normalized) {
+        case "LOCK": {
+          CaptureRequestOptions opts = new CaptureRequestOptions.Builder()
+            .setCaptureRequestOption(CaptureRequest.CONTROL_AE_LOCK, true)
+            .setCaptureRequestOption(
+              CaptureRequest.CONTROL_AE_MODE,
+              CaptureRequest.CONTROL_AE_MODE_ON
+            )
+            .build();
+          mainExecutor.execute(() -> c2.setCaptureRequestOptions(opts));
+          currentExposureMode = "LOCK";
+          break;
+        }
+        case "CONTINUOUS": {
+          CaptureRequestOptions opts = new CaptureRequestOptions.Builder()
+            .setCaptureRequestOption(CaptureRequest.CONTROL_AE_LOCK, false)
+            .setCaptureRequestOption(
+              CaptureRequest.CONTROL_AE_MODE,
+              CaptureRequest.CONTROL_AE_MODE_ON
+            )
+            .build();
+          mainExecutor.execute(() -> c2.setCaptureRequestOptions(opts));
+          currentExposureMode = "CONTINUOUS";
+          break;
+        }
+        default:
+          throw new Exception("Unsupported exposure mode: " + mode);
+      }
+    } catch (Exception e) {
+      throw e;
+    }
+  }
+
+  public float[] getExposureCompensationRange() throws Exception {
+    if (camera == null) {
+      throw new Exception("Camera not initialized");
+    }
+    ExposureState state = camera.getCameraInfo().getExposureState();
+    Range<Integer> idxRange = state.getExposureCompensationRange();
+    Rational step = state.getExposureCompensationStep();
+    float evStep = step != null
+      ? (float) step.getNumerator() / (float) step.getDenominator()
+      : 1.0f;
+    float min = idxRange.getLower() * evStep;
+    float max = idxRange.getUpper() * evStep;
+    return new float[] { min, max, evStep };
+  }
+
+  public float getExposureCompensation() throws Exception {
+    if (camera == null) {
+      throw new Exception("Camera not initialized");
+    }
+    ExposureState state = camera.getCameraInfo().getExposureState();
+    int idx = state.getExposureCompensationIndex();
+    Rational step = state.getExposureCompensationStep();
+    float evStep = step != null
+      ? (float) step.getNumerator() / (float) step.getDenominator()
+      : 1.0f;
+    return idx * evStep;
+  }
+
+  public void setExposureCompensation(float ev) throws Exception {
+    if (camera == null) {
+      throw new Exception("Camera not initialized");
+    }
+    ExposureState state = camera.getCameraInfo().getExposureState();
+    Range<Integer> idxRange = state.getExposureCompensationRange();
+    Rational step = state.getExposureCompensationStep();
+    float evStep = step != null
+      ? (float) step.getNumerator() / (float) step.getDenominator()
+      : 1.0f;
+    if (evStep <= 0f) evStep = 1.0f;
+    int idx = Math.round(ev / evStep);
+    // clamp
+    if (idx < idxRange.getLower()) idx = idxRange.getLower();
+    if (idx > idxRange.getUpper()) idx = idxRange.getUpper();
+    camera.getCameraControl().setExposureCompensationIndex(idx);
+  }
+
   private void showFocusIndicator(float x, float y) {
     if (disableFocusIndicator || sessionConfig.getDisableFocusIndicator()) {
       return;

package/dist/docs.json

@@ -882,6 +882,114 @@
           "DeviceOrientation"
         ],
         "slug": "getorientation"
+      },
+      {
+        "name": "getExposureModes",
+        "signature": "() => Promise<{ modes: ExposureMode[]; }>",
+        "parameters": [],
+        "returns": "Promise<{ modes: ExposureMode[]; }>",
+        "tags": [
+          {
+            "name": "platform",
+            "text": "android, ios"
+          }
+        ],
+        "docs": "Returns the exposure modes supported by the active camera.\nModes can include: 'locked', 'auto', 'continuous', 'custom'.",
+        "complexTypes": [
+          "ExposureMode"
+        ],
+        "slug": "getexposuremodes"
+      },
+      {
+        "name": "getExposureMode",
+        "signature": "() => Promise<{ mode: ExposureMode; }>",
+        "parameters": [],
+        "returns": "Promise<{ mode: ExposureMode; }>",
+        "tags": [
+          {
+            "name": "platform",
+            "text": "android, ios"
+          }
+        ],
+        "docs": "Returns the current exposure mode.",
+        "complexTypes": [
+          "ExposureMode"
+        ],
+        "slug": "getexposuremode"
+      },
+      {
+        "name": "setExposureMode",
+        "signature": "(options: { mode: ExposureMode; }) => Promise<void>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "",
+            "type": "{ mode: ExposureMode; }"
+          }
+        ],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "platform",
+            "text": "android, ios"
+          }
+        ],
+        "docs": "Sets the exposure mode.",
+        "complexTypes": [
+          "ExposureMode"
+        ],
+        "slug": "setexposuremode"
+      },
+      {
+        "name": "getExposureCompensationRange",
+        "signature": "() => Promise<{ min: number; max: number; step: number; }>",
+        "parameters": [],
+        "returns": "Promise<{ min: number; max: number; step: number; }>",
+        "tags": [
+          {
+            "name": "platform",
+            "text": "ios"
+          }
+        ],
+        "docs": "Returns the exposure compensation (EV bias) supported range.",
+        "complexTypes": [],
+        "slug": "getexposurecompensationrange"
+      },
+      {
+        "name": "getExposureCompensation",
+        "signature": "() => Promise<{ value: number; }>",
+        "parameters": [],
+        "returns": "Promise<{ value: number; }>",
+        "tags": [
+          {
+            "name": "platform",
+            "text": "ios"
+          }
+        ],
+        "docs": "Returns the current exposure compensation (EV bias).",
+        "complexTypes": [],
+        "slug": "getexposurecompensation"
+      },
+      {
+        "name": "setExposureCompensation",
+        "signature": "(options: { value: number; }) => Promise<void>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "",
+            "type": "{ value: number; }"
+          }
+        ],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "platform",
+            "text": "ios"
+          }
+        ],
+        "docs": "Sets the exposure compensation (EV bias). Value will be clamped to range.",
+        "complexTypes": [],
+        "slug": "setexposurecompensation"
       }
     ],
     "properties": []
@@ -1804,6 +1912,29 @@
           "complexTypes": []
         }
       ]
+    },
+    {
+      "name": "ExposureMode",
+      "slug": "exposuremode",
+      "docs": "Reusable exposure mode type for cross-platform support.",
+      "types": [
+        {
+          "text": "\"AUTO\"",
+          "complexTypes": []
+        },
+        {
+          "text": "\"LOCK\"",
+          "complexTypes": []
+        },
+        {
+          "text": "\"CONTINUOUS\"",
+          "complexTypes": []
+        },
+        {
+          "text": "\"CUSTOM\"",
+          "complexTypes": []
+        }
+      ]
     }
   ],
   "pluginConfigs": []

package/dist/esm/definitions.d.ts

@@ -278,6 +278,8 @@ export interface CameraSampleOptions {
  * 'torch' is a continuous light mode.
  */
 export type CameraPreviewFlashMode = "off" | "on" | "auto" | "torch";
+/** Reusable exposure mode type for cross-platform support. */
+export type ExposureMode = "AUTO" | "LOCK" | "CONTINUOUS" | "CUSTOM";
 /**
  * Defines the options for setting the camera preview's opacity.
  */
@@ -678,4 +680,49 @@ export interface CameraPreviewPlugin {
     getOrientation(): Promise<{
         orientation: DeviceOrientation;
     }>;
+    /**
+     * Returns the exposure modes supported by the active camera.
+     * Modes can include: 'locked', 'auto', 'continuous', 'custom'.
+     * @platform android, ios
+     */
+    getExposureModes(): Promise<{
+        modes: ExposureMode[];
+    }>;
+    /**
+     * Returns the current exposure mode.
+     * @platform android, ios
+     */
+    getExposureMode(): Promise<{
+        mode: ExposureMode;
+    }>;
+    /**
+     * Sets the exposure mode.
+     * @platform android, ios
+     */
+    setExposureMode(options: {
+        mode: ExposureMode;
+    }): Promise<void>;
+    /**
+     * Returns the exposure compensation (EV bias) supported range.
+     * @platform ios
+     */
+    getExposureCompensationRange(): Promise<{
+        min: number;
+        max: number;
+        step: number;
+    }>;
+    /**
+     * Returns the current exposure compensation (EV bias).
+     * @platform ios
+     */
+    getExposureCompensation(): Promise<{
+        value: number;
+    }>;
+    /**
+     * Sets the exposure compensation (EV bias). Value will be clamped to range.
+     * @platform ios
+     */
+    setExposureCompensation(options: {
+        value: number;
+    }): Promise<void>;
 }