@capgo/camera-preview 8.4.7 → 8.5.0

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

@@ -25,7 +25,8 @@ public class CameraSessionConfiguration {
     private final boolean enableVideoMode;
     private float targetZoom = 1.0f;
     private boolean isCentered = false;
-    private final String videoQuality;
+    private String videoQuality;
+    private String videoCodec = "avc1";
     private boolean enablePhysicalDeviceSelection = false;
     private boolean barcodeScannerEnabled = false;
 
@@ -147,6 +148,18 @@ public class CameraSessionConfiguration {
         return videoQuality;
     }
 
+    public void setVideoQuality(String quality) {
+        this.videoQuality = quality != null ? quality : "high";
+    }
+
+    public String getVideoCodec() {
+        return videoCodec;
+    }
+
+    public void setVideoCodec(String codec) {
+        this.videoCodec = codec != null ? codec : "avc1";
+    }
+
     public boolean isPhysicalDeviceSelectionEnabled() {
         return enablePhysicalDeviceSelection;
     }

package/dist/docs.json

@@ -495,9 +495,9 @@
       },
       {
         "name": "stopRecordVideo",
-        "signature": "() => Promise<{ videoFilePath: string; }>",
+        "signature": "() => Promise<RecordingFinishedEvent>",
         "parameters": [],
-        "returns": "Promise<{ videoFilePath: string; }>",
+        "returns": "Promise<RecordingFinishedEvent>",
         "tags": [
           {
             "name": "returns",
@@ -509,7 +509,9 @@
           }
         ],
         "docs": "Stops an ongoing video recording.",
-        "complexTypes": [],
+        "complexTypes": [
+          "RecordingFinishedEvent"
+        ],
         "slug": "stoprecordvideo"
       },
       {
@@ -518,7 +520,7 @@
         "parameters": [
           {
             "name": "options",
-            "docs": "- The options for video recording. Only iOS.",
+            "docs": "- The options for video recording.",
             "type": "CameraPreviewOptions"
           }
         ],
@@ -526,7 +528,7 @@
         "tags": [
           {
             "name": "param",
-            "text": "options - The options for video recording. Only iOS."
+            "text": "options - The options for video recording."
           },
           {
             "name": "returns",
@@ -543,6 +545,176 @@
         ],
         "slug": "startrecordvideo"
       },
+      {
+        "name": "setVideoQuality",
+        "signature": "(options: { quality: VideoQuality; }) => Promise<void>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "- The desired video quality.",
+            "type": "{ quality: VideoQuality; }"
+          }
+        ],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "options - The desired video quality."
+          },
+          {
+            "name": "returns",
+            "text": "A promise that resolves when the quality is set."
+          },
+          {
+            "name": "since",
+            "text": "8.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
+          }
+        ],
+        "docs": "Sets the video recording quality for the active camera session.",
+        "complexTypes": [
+          "VideoQuality"
+        ],
+        "slug": "setvideoquality"
+      },
+      {
+        "name": "getVideoQuality",
+        "signature": "() => Promise<{ quality: VideoQuality; }>",
+        "parameters": [],
+        "returns": "Promise<{ quality: VideoQuality; }>",
+        "tags": [
+          {
+            "name": "returns",
+            "text": "A promise that resolves with the current quality."
+          },
+          {
+            "name": "since",
+            "text": "8.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
+          }
+        ],
+        "docs": "Gets the current video recording quality.",
+        "complexTypes": [
+          "VideoQuality"
+        ],
+        "slug": "getvideoquality"
+      },
+      {
+        "name": "getSupportedVideoQualities",
+        "signature": "() => Promise<{ qualities: VideoQuality[]; }>",
+        "parameters": [],
+        "returns": "Promise<{ qualities: VideoQuality[]; }>",
+        "tags": [
+          {
+            "name": "returns",
+            "text": "A promise that resolves with supported qualities."
+          },
+          {
+            "name": "since",
+            "text": "8.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
+          }
+        ],
+        "docs": "Returns the video qualities supported by the active camera.",
+        "complexTypes": [
+          "VideoQuality"
+        ],
+        "slug": "getsupportedvideoqualities"
+      },
+      {
+        "name": "setVideoCodec",
+        "signature": "(options: { codec: VideoCodec; }) => Promise<void>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "- The desired codec.",
+            "type": "{ codec: VideoCodec; }"
+          }
+        ],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "options - The desired codec."
+          },
+          {
+            "name": "returns",
+            "text": "A promise that resolves when the codec is set."
+          },
+          {
+            "name": "since",
+            "text": "8.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
+          }
+        ],
+        "docs": "Sets the video codec used when recording.",
+        "complexTypes": [
+          "VideoCodec"
+        ],
+        "slug": "setvideocodec"
+      },
+      {
+        "name": "getVideoCodec",
+        "signature": "() => Promise<{ codec: VideoCodec; }>",
+        "parameters": [],
+        "returns": "Promise<{ codec: VideoCodec; }>",
+        "tags": [
+          {
+            "name": "returns",
+            "text": "A promise that resolves with the current codec."
+          },
+          {
+            "name": "since",
+            "text": "8.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
+          }
+        ],
+        "docs": "Gets the current video codec used for recording.",
+        "complexTypes": [
+          "VideoCodec"
+        ],
+        "slug": "getvideocodec"
+      },
+      {
+        "name": "getSupportedVideoCodecs",
+        "signature": "() => Promise<{ codecs: VideoCodec[]; }>",
+        "parameters": [],
+        "returns": "Promise<{ codecs: VideoCodec[]; }>",
+        "tags": [
+          {
+            "name": "returns",
+            "text": "A promise that resolves with supported codecs."
+          },
+          {
+            "name": "since",
+            "text": "8.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
+          }
+        ],
+        "docs": "Returns the video codecs supported by the active camera.",
+        "complexTypes": [
+          "VideoCodec"
+        ],
+        "slug": "getsupportedvideocodecs"
+      },
       {
         "name": "isRunning",
         "signature": "() => Promise<{ isRunning: boolean; }>",
@@ -1011,6 +1183,39 @@
         ],
         "slug": "addlistenerbarcodescanerror-"
       },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'recordingFinished', listenerFunc: (data: RecordingFinishedEvent) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "",
+            "type": "'recordingFinished'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "",
+            "type": "(data: RecordingFinishedEvent) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "8.4.7"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
+          }
+        ],
+        "docs": "Adds a listener fired when a video recording finishes natively, including automatic stops.",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "RecordingFinishedEvent"
+        ],
+        "slug": "addlistenerrecordingfinished-"
+      },
       {
         "name": "deleteFile",
         "signature": "(options: { path: string; }) => Promise<{ success: boolean; }>",
@@ -1620,9 +1825,53 @@
               "name": "default"
             }
           ],
-          "docs": "Sets the quality of video for recording.\nOptions: 'low', 'medium', 'high'",
+          "docs": "Sets the quality of video for recording.\nOptions: 'low', 'medium', 'high', '2160p', '1080p', '720p', '480p', '4:3'",
+          "complexTypes": [
+            "VideoQuality"
+          ],
+          "type": "VideoQuality"
+        },
+        {
+          "name": "maxDuration",
+          "tags": [
+            {
+              "text": "ios, android",
+              "name": "platform"
+            }
+          ],
+          "docs": "Maximum recording duration in seconds. Recording stops automatically when reached.",
+          "complexTypes": [],
+          "type": "number | undefined"
+        },
+        {
+          "name": "maxFileSize",
+          "tags": [
+            {
+              "text": "ios, android",
+              "name": "platform"
+            }
+          ],
+          "docs": "Maximum recording file size in bytes. Recording stops automatically when reached.",
           "complexTypes": [],
-          "type": "'low' | 'medium' | 'high' | undefined"
+          "type": "number | undefined"
+        },
+        {
+          "name": "videoCodec",
+          "tags": [
+            {
+              "text": "ios, android",
+              "name": "platform"
+            },
+            {
+              "text": "\"avc1\"",
+              "name": "default"
+            }
+          ],
+          "docs": "Preferred video codec for recording.",
+          "complexTypes": [
+            "VideoCodec"
+          ],
+          "type": "VideoCodec"
         },
         {
           "name": "barcodeScanner",
@@ -1983,6 +2232,31 @@
         }
       ]
     },
+    {
+      "name": "RecordingFinishedEvent",
+      "slug": "recordingfinishedevent",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "videoFilePath",
+          "tags": [],
+          "docs": "The path to the recorded video file.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "reason",
+          "tags": [],
+          "docs": "Why the recording stopped.",
+          "complexTypes": [
+            "RecordingFinishedReason"
+          ],
+          "type": "RecordingFinishedReason"
+        }
+      ]
+    },
     {
       "name": "CameraDevice",
       "slug": "cameradevice",
@@ -2373,6 +2647,72 @@
         }
       ]
     },
+    {
+      "name": "VideoQuality",
+      "slug": "videoquality",
+      "docs": "",
+      "types": [
+        {
+          "text": "'low'",
+          "complexTypes": []
+        },
+        {
+          "text": "'medium'",
+          "complexTypes": []
+        },
+        {
+          "text": "'high'",
+          "complexTypes": []
+        },
+        {
+          "text": "'2160p'",
+          "complexTypes": []
+        },
+        {
+          "text": "'1080p'",
+          "complexTypes": []
+        },
+        {
+          "text": "'720p'",
+          "complexTypes": []
+        },
+        {
+          "text": "'480p'",
+          "complexTypes": []
+        },
+        {
+          "text": "'4:3'",
+          "complexTypes": []
+        }
+      ]
+    },
+    {
+      "name": "VideoCodec",
+      "slug": "videocodec",
+      "docs": "Video codec identifiers used when recording.\n- `avc1`: H.264\n- `hvc1`: HEVC / H.265",
+      "types": [
+        {
+          "text": "'avc1'",
+          "complexTypes": []
+        },
+        {
+          "text": "'hvc1'",
+          "complexTypes": []
+        },
+        {
+          "text": "'jpeg'",
+          "complexTypes": []
+        },
+        {
+          "text": "'apcn'",
+          "complexTypes": []
+        },
+        {
+          "text": "'ap4h'",
+          "complexTypes": []
+        }
+      ]
+    },
     {
       "name": "BarcodeScannerFormat",
       "slug": "barcodescannerformat",
@@ -2508,6 +2848,25 @@
         }
       ]
     },
+    {
+      "name": "RecordingFinishedReason",
+      "slug": "recordingfinishedreason",
+      "docs": "",
+      "types": [
+        {
+          "text": "'manual'",
+          "complexTypes": []
+        },
+        {
+          "text": "'maxDuration'",
+          "complexTypes": []
+        },
+        {
+          "text": "'maxFileSize'",
+          "complexTypes": []
+        }
+      ]
+    },
     {
       "name": "FlashMode",
       "slug": "flashmode",

package/dist/esm/definitions.d.ts

@@ -107,6 +107,24 @@ export interface LensInfo {
     /** The current digital zoom factor applied on top of the base zoom. */
     digitalZoom: number;
 }
+export type VideoQuality = 'low' | 'medium' | 'high' | '2160p' | '1080p' | '720p' | '480p' | '4:3';
+/**
+ * Video codec identifiers used when recording.
+ * - `avc1`: H.264
+ * - `hvc1`: HEVC / H.265
+ */
+export type VideoCodec = 'avc1' | 'hvc1' | 'jpeg' | 'apcn' | 'ap4h';
+export type RecordingFinishedReason = 'manual' | 'maxDuration' | 'maxFileSize';
+export interface RecordingFinishedEvent {
+    /**
+     * The path to the recorded video file.
+     */
+    videoFilePath: string;
+    /**
+     * Why the recording stopped.
+     */
+    reason: RecordingFinishedReason;
+}
 /**
  * Defines the configuration options for starting the camera preview.
  */
@@ -269,13 +287,29 @@ export interface CameraPreviewOptions {
     force?: boolean;
     /**
      * Sets the quality of video for recording.
-     * Options: 'low', 'medium', 'high'
+     * Options: 'low', 'medium', 'high', '2160p', '1080p', '720p', '480p', '4:3'
      * @note On Android requires 'enableVideoMode' to be true
      * @note Will affect the entire preview stream for iOS
      * @platform ios, android
      * @default "high"
      */
-    videoQuality?: 'low' | 'medium' | 'high';
+    videoQuality?: VideoQuality;
+    /**
+     * Maximum recording duration in seconds. Recording stops automatically when reached.
+     * @platform ios, android
+     */
+    maxDuration?: number;
+    /**
+     * Maximum recording file size in bytes. Recording stops automatically when reached.
+     * @platform ios, android
+     */
+    maxFileSize?: number;
+    /**
+     * Preferred video codec for recording.
+     * @platform ios, android
+     * @default "avc1"
+     */
+    videoCodec?: VideoCodec;
     /**
      * Starts barcode scanning together with the camera preview.
      * Set to `true` or pass options to scan all supported formats.
@@ -617,20 +651,80 @@ export interface CameraPreviewPlugin {
     /**
      * Stops an ongoing video recording.
      *
-     * @returns {Promise<{ videoFilePath: string }>} A promise that resolves with the path to the recorded video file.
+     * @returns {Promise<RecordingFinishedEvent>} A promise that resolves with the path to the recorded video file.
      * @since 0.0.1
      */
-    stopRecordVideo(): Promise<{
-        videoFilePath: string;
-    }>;
+    stopRecordVideo(): Promise<RecordingFinishedEvent>;
     /**
      * Starts recording a video.
      *
-     * @param {CameraPreviewOptions} options - The options for video recording. Only iOS.
+     * @param {CameraPreviewOptions} options - The options for video recording.
      * @returns {Promise<void>} A promise that resolves when video recording starts.
      * @since 0.0.1
      */
     startRecordVideo(options: CameraPreviewOptions): Promise<void>;
+    /**
+     * Sets the video recording quality for the active camera session.
+     *
+     * @param {{ quality: VideoQuality }} options - The desired video quality.
+     * @returns {Promise<void>} A promise that resolves when the quality is set.
+     * @since 8.5.0
+     * @platform android, ios
+     */
+    setVideoQuality(options: {
+        quality: VideoQuality;
+    }): Promise<void>;
+    /**
+     * Gets the current video recording quality.
+     *
+     * @returns {Promise<{ quality: VideoQuality }>} A promise that resolves with the current quality.
+     * @since 8.5.0
+     * @platform android, ios
+     */
+    getVideoQuality(): Promise<{
+        quality: VideoQuality;
+    }>;
+    /**
+     * Returns the video qualities supported by the active camera.
+     *
+     * @returns {Promise<{ qualities: VideoQuality[] }>} A promise that resolves with supported qualities.
+     * @since 8.5.0
+     * @platform android, ios
+     */
+    getSupportedVideoQualities(): Promise<{
+        qualities: VideoQuality[];
+    }>;
+    /**
+     * Sets the video codec used when recording.
+     *
+     * @param {{ codec: VideoCodec }} options - The desired codec.
+     * @returns {Promise<void>} A promise that resolves when the codec is set.
+     * @since 8.5.0
+     * @platform android, ios
+     */
+    setVideoCodec(options: {
+        codec: VideoCodec;
+    }): Promise<void>;
+    /**
+     * Gets the current video codec used for recording.
+     *
+     * @returns {Promise<{ codec: VideoCodec }>} A promise that resolves with the current codec.
+     * @since 8.5.0
+     * @platform android, ios
+     */
+    getVideoCodec(): Promise<{
+        codec: VideoCodec;
+    }>;
+    /**
+     * Returns the video codecs supported by the active camera.
+     *
+     * @returns {Promise<{ codecs: VideoCodec[] }>} A promise that resolves with supported codecs.
+     * @since 8.5.0
+     * @platform android, ios
+     */
+    getSupportedVideoCodecs(): Promise<{
+        codecs: VideoCodec[];
+    }>;
     /**
      * Checks if the camera preview is currently running.
      *
@@ -812,6 +906,13 @@ export interface CameraPreviewPlugin {
      * @platform android, web
      */
     addListener(eventName: 'barcodeScanError', listenerFunc: (data: BarcodeScanErrorEvent) => void): Promise<PluginListenerHandle>;
+    /**
+     * Adds a listener fired when a video recording finishes natively, including automatic stops.
+     *
+     * @since 8.4.7
+     * @platform android, ios
+     */
+    addListener(eventName: 'recordingFinished', listenerFunc: (data: RecordingFinishedEvent) => void): Promise<PluginListenerHandle>;
     /**
      * Deletes a file at the given absolute path on the device.
      * Use this to quickly clean up temporary images created with `storeToFile`.