@capgo/camera-preview 8.5.1 → 8.7.1

package/README.md

@@ -382,6 +382,10 @@ Documentation for the [uploader](https://github.com/Cap-go/capacitor-uploader)
 * [`setVideoCodec(...)`](#setvideocodec)
 * [`getVideoCodec()`](#getvideocodec)
 * [`getSupportedVideoCodecs()`](#getsupportedvideocodecs)
+* [`isVideoStabilizationSupported()`](#isvideostabilizationsupported)
+* [`getSupportedVideoStabilizationModes()`](#getsupportedvideostabilizationmodes)
+* [`getVideoStabilizationMode()`](#getvideostabilizationmode)
+* [`setVideoStabilizationMode(...)`](#setvideostabilizationmode)
 * [`isRunning()`](#isrunning)
 * [`getAvailableDevices()`](#getavailabledevices)
 * [`getZoom()`](#getzoom)
@@ -408,6 +412,9 @@ Documentation for the [uploader](https://github.com/Cap-go/capacitor-uploader)
 * [`getExposureCompensationRange()`](#getexposurecompensationrange)
 * [`getExposureCompensation()`](#getexposurecompensation)
 * [`setExposureCompensation(...)`](#setexposurecompensation)
+* [`getSupportedVideoFrameRates()`](#getsupportedvideoframerates)
+* [`getVideoFrameRate()`](#getvideoframerate)
+* [`setVideoFrameRate(...)`](#setvideoframerate)
 * [`getPluginVersion()`](#getpluginversion)
 * [Interfaces](#interfaces)
 * [Type Aliases](#type-aliases)
@@ -755,6 +762,8 @@ startRecordVideo(options: CameraPreviewOptions) => Promise<void>
 
 Starts recording a video.
 
+Supports `frameRate`, `videoCodec`, `videoStabilizationMode`, `maxDuration`, `maxFileSize`, and `disableAudio` on each call.
+
 | Param         | Type                                                                  | Description                        |
 | ------------- | --------------------------------------------------------------------- | ---------------------------------- |
 | **`options`** | <code><a href="#camerapreviewoptions">CameraPreviewOptions</a></code> | - The options for video recording. |
@@ -858,6 +867,70 @@ Returns the video codecs supported by the active camera.
 --------------------
 
 
+### isVideoStabilizationSupported()
+
+```typescript
+isVideoStabilizationSupported() => Promise<{ supported: boolean; }>
+```
+
+Checks whether video stabilization is supported by the active camera.
+
+**Returns:** <code>Promise&lt;{ supported: boolean; }&gt;</code>
+
+**Since:** 8.5.2
+
+--------------------
+
+
+### getSupportedVideoStabilizationModes()
+
+```typescript
+getSupportedVideoStabilizationModes() => Promise<{ modes: VideoStabilizationMode[]; }>
+```
+
+Returns the video stabilization modes supported by the active camera.
+
+**Returns:** <code>Promise&lt;{ modes: VideoStabilizationMode[]; }&gt;</code>
+
+**Since:** 8.5.2
+
+--------------------
+
+
+### getVideoStabilizationMode()
+
+```typescript
+getVideoStabilizationMode() => Promise<{ mode: VideoStabilizationMode; }>
+```
+
+Gets the current video stabilization mode.
+
+**Returns:** <code>Promise&lt;{ mode: <a href="#videostabilizationmode">VideoStabilizationMode</a>; }&gt;</code>
+
+**Since:** 8.5.2
+
+--------------------
+
+
+### setVideoStabilizationMode(...)
+
+```typescript
+setVideoStabilizationMode(options: { mode: VideoStabilizationMode; }) => Promise<void>
+```
+
+Sets the video stabilization mode for recording.
+Cannot be changed while a recording is in progress.
+You can also pass `videoStabilizationMode` in `startRecordVideo()` options.
+
+| Param         | Type                                                                                 | Description                       |
+| ------------- | ------------------------------------------------------------------------------------ | --------------------------------- |
+| **`options`** | <code>{ mode: <a href="#videostabilizationmode">VideoStabilizationMode</a>; }</code> | - The desired stabilization mode. |
+
+**Since:** 8.5.2
+
+--------------------
+
+
 ### isRunning()
 
 ```typescript
@@ -1291,6 +1364,57 @@ Sets the exposure compensation (EV bias). Value will be clamped to range.
 --------------------
 
 
+### getSupportedVideoFrameRates()
+
+```typescript
+getSupportedVideoFrameRates() => Promise<{ frameRates: number[]; }>
+```
+
+Lists the video frame rates supported by the active camera for the current format.
+Supported values depend on the selected camera, lens, and video quality.
+
+**Returns:** <code>Promise&lt;{ frameRates: number[]; }&gt;</code>
+
+**Since:** 8.6.0
+
+--------------------
+
+
+### getVideoFrameRate()
+
+```typescript
+getVideoFrameRate() => Promise<{ frameRate: number; }>
+```
+
+Returns the configured video frame rate for the active camera.
+On Android the actual recording frame rate can still vary in low light or under thermal pressure.
+
+**Returns:** <code>Promise&lt;{ frameRate: number; }&gt;</code>
+
+**Since:** 8.6.0
+
+--------------------
+
+
+### setVideoFrameRate(...)
+
+```typescript
+setVideoFrameRate(options: { frameRate: number; }) => Promise<void>
+```
+
+Sets the target video frame rate for the active camera session.
+Prefer passing `frameRate` to `startRecordVideo()` when starting a recording.
+Rejects unsupported values with a clear error.
+
+| Param         | Type                                |
+| ------------- | ----------------------------------- |
+| **`options`** | <code>{ frameRate: number; }</code> |
+
+**Since:** 8.6.0
+
+--------------------
+
+
 ### getPluginVersion()
 
 ```typescript
@@ -1343,6 +1467,8 @@ Defines the configuration options for starting the camera preview.
 | **`maxDuration`**                   | <code>number</code>                                                                | Maximum recording duration in seconds. Recording stops automatically when reached.                                                                                                                                                  |                        |        |
 | **`maxFileSize`**                   | <code>number</code>                                                                | Maximum recording file size in bytes. Recording stops automatically when reached.                                                                                                                                                   |                        |        |
 | **`videoCodec`**                    | <code><a href="#videocodec">VideoCodec</a></code>                                  | Preferred video codec for recording.                                                                                                                                                                                                | <code>"avc1"</code>    |        |
+| **`frameRate`**                     | <code>number</code>                                                                | Target video frame rate in frames per second. Applied when recording starts. Use `getSupportedVideoFrameRates()` to list supported values.                                                                                          |                        | 8.6.0  |
+| **`videoStabilizationMode`**        | <code><a href="#videostabilizationmode">VideoStabilizationMode</a></code>          | Preferred video stabilization mode for recording.                                                                                                                                                                                   | <code>"off"</code>     |        |
 | **`barcodeScanner`**                | <code>boolean \| <a href="#barcodescanneroptions">BarcodeScannerOptions</a></code> | Starts barcode scanning together with the camera preview. Set to `true` or pass options to scan all supported formats. Omit this option to keep barcode scanning disabled at startup.                                               |                        | 8.8.0  |
 
 
@@ -1563,6 +1689,16 @@ Video codec identifiers used when recording.
 <code>'avc1' | 'hvc1' | 'jpeg' | 'apcn' | 'ap4h'</code>
 
 
+#### VideoStabilizationMode
+
+Video stabilization modes used when recording.
+
+On Android only `off` and `standard` are supported.
+On iOS all listed modes may be available when the device supports video stabilization.
+
+<code>'off' | 'standard' | 'cinematic' | 'cinematicExtended' | 'previewOptimized' | 'cinematicExtendedEnhanced' | 'auto' | 'lowLatency'</code>
+
+
 #### BarcodeScannerFormat
 
 <code>'aztec' | 'codabar' | 'code_39' | 'code_93' | 'code_128' | 'data_matrix' | 'ean_8' | 'ean_13' | 'itf' | 'pdf417' | 'qr_code' | 'upc_a' | 'upc_e'</code>

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

@@ -52,6 +52,7 @@ import com.google.android.gms.location.FusedLocationProviderClient;
 import com.google.android.gms.location.LocationServices;
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.Collections;
 import java.util.List;
 import java.util.Locale;
 import java.util.Objects;
@@ -290,6 +291,56 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
         }
     }
 
+    @PluginMethod
+    public void getSupportedVideoFrameRates(PluginCall call) {
+        if (cameraXView == null || !cameraXView.isRunning()) {
+            call.reject("Camera is not running");
+            return;
+        }
+        try {
+            List<Integer> frameRates = cameraXView.getSupportedVideoFrameRates();
+            JSObject ret = new JSObject();
+            JSONArray frameRatesArray = new JSONArray();
+            for (Integer frameRate : frameRates) {
+                frameRatesArray.put(frameRate);
+            }
+            ret.put("frameRates", frameRatesArray);
+            call.resolve(ret);
+        } catch (Exception e) {
+            call.reject("Failed to get supported video frame rates: " + e.getMessage());
+        }
+    }
+
+    @PluginMethod
+    public void getVideoFrameRate(PluginCall call) {
+        if (cameraXView == null || !cameraXView.isRunning()) {
+            call.reject("Camera is not running");
+            return;
+        }
+        try {
+            int frameRate = cameraXView.getVideoFrameRate();
+            JSObject ret = new JSObject();
+            ret.put("frameRate", frameRate);
+            call.resolve(ret);
+        } catch (Exception e) {
+            call.reject("Failed to get video frame rate: " + e.getMessage());
+        }
+    }
+
+    @PluginMethod
+    public void setVideoFrameRate(PluginCall call) {
+        if (cameraXView == null || !cameraXView.isRunning()) {
+            call.reject("Camera is not running");
+            return;
+        }
+        Integer frameRate = call.getInt("frameRate");
+        if (frameRate == null) {
+            call.reject("frameRate parameter is required");
+            return;
+        }
+        cameraXView.setVideoFrameRate(frameRate, call::resolve, call::reject);
+    }
+
     @PluginMethod
     public void getOrientation(PluginCall call) {
         String o = getDeviceOrientationString();
@@ -2701,6 +2752,63 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
         call.resolve(ret);
     }
 
+    @PluginMethod
+    public void isVideoStabilizationSupported(PluginCall call) {
+        if (cameraXView == null || !cameraXView.isRunning()) {
+            call.reject("Camera is not running");
+            return;
+        }
+        JSObject ret = new JSObject();
+        ret.put("supported", cameraXView.isVideoStabilizationSupported());
+        call.resolve(ret);
+    }
+
+    @PluginMethod
+    public void getSupportedVideoStabilizationModes(PluginCall call) {
+        List<String> modes = cameraXView != null ? cameraXView.getSupportedVideoStabilizationModes() : Collections.singletonList("off");
+        JSONArray arr = new JSONArray();
+        for (String mode : modes) {
+            arr.put(mode);
+        }
+        JSObject ret = new JSObject();
+        ret.put("modes", arr);
+        call.resolve(ret);
+    }
+
+    @PluginMethod
+    public void getVideoStabilizationMode(PluginCall call) {
+        if (cameraXView == null || !cameraXView.isRunning()) {
+            call.reject("Camera is not running");
+            return;
+        }
+        JSObject ret = new JSObject();
+        ret.put("mode", cameraXView.getVideoStabilizationModeSetting());
+        call.resolve(ret);
+    }
+
+    @PluginMethod
+    public void setVideoStabilizationMode(PluginCall call) {
+        if (cameraXView == null || !cameraXView.isRunning()) {
+            call.reject("Camera is not running");
+            return;
+        }
+        String mode = call.getString("mode");
+        if (mode == null) {
+            call.reject("mode is required");
+            return;
+        }
+        try {
+            cameraXView.setVideoStabilizationModeSetting(mode);
+            call.resolve();
+        } catch (IllegalArgumentException e) {
+            call.reject(e.getMessage());
+        } catch (IllegalStateException e) {
+            call.reject(e.getMessage());
+        } catch (Exception e) {
+            call.reject("Failed to set video stabilization mode: " + e.getMessage());
+        }
+    }
+
     @PluginMethod
     public void startRecordVideo(PluginCall call) {
         if (cameraXView == null || !cameraXView.isRunning()) {
@@ -2715,13 +2823,7 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
         String permissionAlias = disableAudio ? CAMERA_ONLY_PERMISSION_ALIAS : CAMERA_WITH_AUDIO_PERMISSION_ALIAS;
 
         if (PermissionState.GRANTED.equals(getPermissionState(permissionAlias))) {
-            try {
-                applyVideoCodecFromCall(call);
-                cameraXView.startRecordVideo(getMaxDurationMillis(call), getMaxFileSize(call));
-                call.resolve();
-            } catch (Exception e) {
-                call.reject("Failed to start video recording: " + e.getMessage());
-            }
+            beginVideoRecording(call);
         } else {
             requestPermissionForAlias(permissionAlias, call, "handleVideoRecordingPermissionResult");
         }
@@ -2773,6 +2875,13 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
         }
     }
 
+    private void applyVideoStabilizationFromCall(PluginCall call) {
+        String mode = call.getString("videoStabilizationMode");
+        if (mode != null && cameraXView != null) {
+            cameraXView.setVideoStabilizationModeSetting(mode);
+        }
+    }
+
     private Long getMaxDurationMillis(PluginCall call) {
         if (!call.getData().has("maxDuration") || call.getData().isNull("maxDuration")) {
             return null;
@@ -2792,6 +2901,23 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
         return bytes > 0L ? bytes : null;
     }
 
+    private void beginVideoRecording(PluginCall call) {
+        if (cameraXView == null || !cameraXView.isRunning()) {
+            call.reject("Camera is not running");
+            return;
+        }
+        try {
+            applyVideoCodecFromCall(call);
+            applyVideoStabilizationFromCall(call);
+            Integer frameRate = call.getInt("frameRate");
+            cameraXView.startRecordVideo(getMaxDurationMillis(call), getMaxFileSize(call), frameRate, call::resolve, (message) ->
+                call.reject("Failed to start video recording: " + message)
+            );
+        } catch (Exception e) {
+            call.reject("Failed to start video recording: " + e.getMessage());
+        }
+    }
+
     @PermissionCallback
     private void handleVideoRecordingPermissionResult(PluginCall call) {
         // Use the persisted session value to determine which permission we requested
@@ -2802,13 +2928,7 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
             PermissionState.GRANTED.equals(getPermissionState(CAMERA_ONLY_PERMISSION_ALIAS)) ||
             PermissionState.GRANTED.equals(getPermissionState(CAMERA_WITH_AUDIO_PERMISSION_ALIAS))
         ) {
-            try {
-                applyVideoCodecFromCall(call);
-                cameraXView.startRecordVideo(getMaxDurationMillis(call), getMaxFileSize(call));
-                call.resolve();
-            } catch (Exception e) {
-                call.reject("Failed to start video recording: " + e.getMessage());
-            }
+            beginVideoRecording(call);
         } else {
             call.reject("camera permission denied. enable camera access in Settings.", "cameraPermissionDenied");
         }