capacitor-camera-view 2.0.2 → 2.2.0-rc.1

package/README.md

@@ -29,6 +29,7 @@
 
 - 📹 Embed a **live camera feed** directly into your app.
 - 📸 Capture photos or frames from the camera preview.
+- 🎥 **Video recording** with optional audio support.
 - 🔍 **Barcode detection** support.
 - 📱 **Virtual device support** for automatic lens selection based on zoom level and focus (iOS only).
 - 🔦 Control **zoom**, **flash** and **torch** modes programmatically.
@@ -62,12 +63,70 @@ Add the following keys to your app's `Info.plist` file:
 <string>To capture photos and videos</string>
 ```
 
+If you plan to use `startRecording` with `enableAudio: true`, also add:
+
+```xml
+<key>NSMicrophoneUsageDescription</key>
+<string>To record audio with video</string>
+```
+
+> [!IMPORTANT]
+> The `NSMicrophoneUsageDescription` key must be present in `Info.plist` **before** microphone permission is ever requested — even if the request happens automatically when starting a recording with audio. Omitting it will cause your app to crash at runtime.
+
 #### Android
 
-The `CAMERA` permission is automatically added by Capacitor. Ensure your `AndroidManifest.xml` includes it if needed for specific configurations:
+The `CAMERA` permission is added to your app's `AndroidManifest.xml` automatically by the plugin. If you plan to use `startRecording` with `enableAudio: true`, the `RECORD_AUDIO` permission is also declared automatically by the plugin. You can verify these in your merged manifest:
 
 ```xml
 <uses-permission android:name="android.permission.CAMERA" />
+<uses-permission android:name="android.permission.RECORD_AUDIO" />
+```
+
+> [!IMPORTANT]
+> Declaring a permission in `AndroidManifest.xml` is required for the system to allow requesting it at runtime. The plugin handles this for you, but make sure you are not accidentally stripping the permission in your build configuration.
+
+## 🔒 Permissions
+
+The plugin handles permissions for you automatically when a feature that requires them is used. However, you can also request permissions explicitly in advance.
+
+### Requesting permissions explicitly
+
+By default, `requestPermissions()` only requests **camera** permission, preserving backward compatibility:
+
+```typescript
+// Request camera permission only (default behavior)
+const status = await CameraView.requestPermissions();
+console.log(status.camera); // 'granted' | 'denied' | 'prompt'
+```
+
+To also request **microphone** permission (needed for video recording with audio), pass the `permissions` option:
+
+```typescript
+// Request both camera and microphone permissions
+const status = await CameraView.requestPermissions({
+  permissions: ['camera', 'microphone'],
+});
+console.log(status.camera);     // 'granted' | 'denied' | 'prompt'
+console.log(status.microphone); // 'granted' | 'denied' | 'prompt'
+```
+
+### Automatic permission requests
+
+You do not need to call `requestPermissions()` manually. The plugin will automatically request the required permissions when a feature is first used:
+
+- **Camera** permission is requested automatically when `start()` is called.
+- **Microphone** permission is requested automatically when `startRecording({ enableAudio: true })` is called.
+
+Regardless of whether you request permissions manually or rely on the automatic flow, the corresponding entries **must** be declared in your app's platform configuration (`Info.plist` on iOS, `AndroidManifest.xml` on Android) as described above.
+
+### Checking permission status
+
+Use `checkPermissions()` to query the current permission state without triggering a system prompt:
+
+```typescript
+const status = await CameraView.checkPermissions();
+console.log(status.camera);     // 'granted' | 'denied' | 'prompt'
+console.log(status.microphone); // 'granted' | 'denied' | 'prompt'
 ```
 
 ## ▶️ Basic Usage
@@ -174,6 +233,54 @@ CameraView.addListener('barcodeDetected', (data) => {
 
 See the [`BarcodeDetectionData`](#barcodedetectiondata) interface for details on the event payload.
 
+## 🎥 Video Recording
+
+This plugin supports recording video directly from the live camera feed.
+
+**How it works:**
+*   **iOS:** Uses `AVCaptureMovieFileOutput` on top of the existing `AVCaptureSession`. Output is saved as `.mp4`.
+*   **Android:** Uses the CameraX `VideoCapture` use case via `LifecycleCameraController`. Output is saved as `.mp4`.
+*   **Web:** Uses the browser `MediaRecorder` API on the existing `MediaStream`. Output is a `.webm` blob URL (MP4 is not broadly supported by browsers).
+
+**Basic usage:**
+
+```typescript
+import { CameraView } from 'capacitor-camera-view';
+
+// Start recording (camera must already be running)
+await CameraView.startRecording({ enableAudio: false });
+
+// Stop recording and get the result
+const result = await CameraView.stopRecording();
+console.log('Video saved to:', result.webPath);
+```
+
+**Playing back the recorded video:**
+
+```html
+<video [src]="videoPath" controls></video>
+```
+
+**Recording with audio:**
+
+```typescript
+await CameraView.startRecording({ enableAudio: true });
+```
+
+**Recording with explicit quality preset (native):**
+
+```typescript
+await CameraView.startRecording({
+  enableAudio: true,
+  videoQuality: 'fhd', // lowest | sd | hd | fhd | uhd | highest
+});
+```
+
+> [!NOTE]
+> When `enableAudio: true` is used, the plugin automatically requests microphone permission from the user if it has not been granted yet. The permission declaration must still be present in your platform configuration — see the [Permissions](#-permissions) section for details.
+
+See the [`VideoRecordingOptions`](#videorecordingoptions) and [`VideoRecordingResponse`](#videorecordingresponse) interfaces in the API section for the full set of options.
+
 ## 🧪 Example App
 
 To see the plugin in action, check out the example app in the `example-app` folder. The app demonstrates how to integrate and use the Capacitor Camera View plugin in an Ionic Angular project.
@@ -206,6 +313,8 @@ chore: update dependencies
 * [`isRunning()`](#isrunning)
 * [`capture(...)`](#capture)
 * [`captureSample(...)`](#capturesample)
+* [`startRecording(...)`](#startrecording)
+* [`stopRecording()`](#stoprecording)
 * [`flipCamera()`](#flipcamera)
 * [`getAvailableDevices()`](#getavailabledevices)
 * [`getZoom()`](#getzoom)
@@ -217,7 +326,7 @@ chore: update dependencies
 * [`getTorchMode()`](#gettorchmode)
 * [`setTorchMode(...)`](#settorchmode)
 * [`checkPermissions()`](#checkpermissions)
-* [`requestPermissions()`](#requestpermissions)
+* [`requestPermissions(...)`](#requestpermissions)
 * [`addListener('barcodeDetected', ...)`](#addlistenerbarcodedetected-)
 * [`removeAllListeners(...)`](#removealllisteners)
 * [Interfaces](#interfaces)
@@ -321,6 +430,40 @@ not yet well supported on the web.
 --------------------
 
 
+### startRecording(...)
+
+```typescript
+startRecording(options?: VideoRecordingOptions | undefined) => Promise<void>
+```
+
+Start recording video from the current camera.
+Camera must be running. Throws if already recording.
+
+| Param         | Type                                                                    | Description                        |
+| ------------- | ----------------------------------------------------------------------- | ---------------------------------- |
+| **`options`** | <code><a href="#videorecordingoptions">VideoRecordingOptions</a></code> | - Optional recording configuration |
+
+**Since:** 2.2.0
+
+--------------------
+
+
+### stopRecording()
+
+```typescript
+stopRecording() => Promise<VideoRecordingResponse>
+```
+
+Stop the current video recording and return the result.
+Throws if no recording is in progress.
+
+**Returns:** <code>Promise&lt;<a href="#videorecordingresponse">VideoRecordingResponse</a>&gt;</code>
+
+**Since:** 2.2.0
+
+--------------------
+
+
 ### flipCamera()
 
 ```typescript
@@ -481,7 +624,7 @@ Set the torch (flashlight) mode and intensity.
 checkPermissions() => Promise<PermissionStatus>
 ```
 
-Check camera permission status without requesting permissions.
+Check camera and microphone permission status without requesting permissions.
 
 **Returns:** <code>Promise&lt;<a href="#permissionstatus">PermissionStatus</a>&gt;</code>
 
@@ -490,13 +633,20 @@ Check camera permission status without requesting permissions.
 --------------------
 
 
-### requestPermissions()
+### requestPermissions(...)
 
 ```typescript
-requestPermissions() => Promise<PermissionStatus>
+requestPermissions(options?: { permissions?: CameraPermissionType[] | undefined; } | undefined) => Promise<PermissionStatus>
 ```
 
-Request camera permission from the user.
+Request camera and/or microphone permissions from the user.
+
+By default, only camera permission is requested. To also request microphone
+permission (needed for video recording with audio), pass `{ permissions: ['camera', 'microphone'] }`.
+
+| Param         | Type                                                   | Description                                               |
+| ------------- | ------------------------------------------------------ | --------------------------------------------------------- |
+| **`options`** | <code>{ permissions?: CameraPermissionType[]; }</code> | - Optional object specifying which permissions to request |
 
 **Returns:** <code>Promise&lt;<a href="#permissionstatus">PermissionStatus</a>&gt;</code>
 
@@ -550,15 +700,16 @@ Remove all listeners for this plugin.
 
 Configuration options for starting a camera session.
 
-| Prop                             | Type                                                      | Description                                                                                                                                                                                                                                                                                                                                                              | Default                                                                |
-| -------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
-| **`enableBarcodeDetection`**     | <code>boolean</code>                                      | Enables the barcode detection functionality                                                                                                                                                                                                                                                                                                                              | <code>false</code>                                                     |
-| **`position`**                   | <code><a href="#cameraposition">CameraPosition</a></code> | Position of the camera to use                                                                                                                                                                                                                                                                                                                                            | <code>'back'</code>                                                    |
-| **`deviceId`**                   | <code>string</code>                                       | Specific device ID of the camera to use If provided, takes precedence over position                                                                                                                                                                                                                                                                                      |                                                                        |
-| **`useTripleCameraIfAvailable`** | <code>boolean</code>                                      | Whether to use the triple camera if available (iPhone Pro models only)                                                                                                                                                                                                                                                                                                   | <code>false</code>                                                     |
-| **`preferredCameraDeviceTypes`** | <code>CameraDeviceType[]</code>                           | Ordered list of preferred camera device types to use (iOS only). The system will attempt to use the first available camera type in the list. If position is also provided, the system will use the first available camera type that matches the position and is in the list. This will fallback to the default camera type if none of the preferred types are available. | <code>undefined - system will decide based on position/deviceId</code> |
-| **`zoomFactor`**                 | <code>number</code>                                       | The initial zoom factor to use                                                                                                                                                                                                                                                                                                                                           | <code>1.0</code>                                                       |
-| **`containerElementId`**         | <code>string</code>                                       | Optional HTML ID of the container element where the camera view should be rendered. If not provided, the camera view will be appended to the document body. Web only.                                                                                                                                                                                                    |                                                                        |
+| Prop                             | Type                                                      | Description                                                                                                                                                                                                                                                                                                                                                              | Default                                                                | Since |
+| -------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | ----- |
+| **`enableBarcodeDetection`**     | <code>boolean</code>                                      | Enables the barcode detection functionality                                                                                                                                                                                                                                                                                                                              | <code>false</code>                                                     |       |
+| **`barcodeTypes`**               | <code>BarcodeType[]</code>                                | Specific barcode types to detect. If not provided, all supported types are detected. Specifying only the types you need can significantly improve performance and reduce battery consumption, especially on mobile devices.                                                                                                                                              | <code>undefined - all supported types are detected</code>              | 2.1.0 |
+| **`position`**                   | <code><a href="#cameraposition">CameraPosition</a></code> | Position of the camera to use                                                                                                                                                                                                                                                                                                                                            | <code>'back'</code>                                                    |       |
+| **`deviceId`**                   | <code>string</code>                                       | Specific device ID of the camera to use If provided, takes precedence over position                                                                                                                                                                                                                                                                                      |                                                                        |       |
+| **`useTripleCameraIfAvailable`** | <code>boolean</code>                                      | Whether to use the triple camera if available (iPhone Pro models only)                                                                                                                                                                                                                                                                                                   | <code>false</code>                                                     |       |
+| **`preferredCameraDeviceTypes`** | <code>CameraDeviceType[]</code>                           | Ordered list of preferred camera device types to use (iOS only). The system will attempt to use the first available camera type in the list. If position is also provided, the system will use the first available camera type that matches the position and is in the list. This will fallback to the default camera type if none of the preferred types are available. | <code>undefined - system will decide based on position/deviceId</code> |       |
+| **`zoomFactor`**                 | <code>number</code>                                       | The initial zoom factor to use                                                                                                                                                                                                                                                                                                                                           | <code>1.0</code>                                                       |       |
+| **`containerElementId`**         | <code>string</code>                                       | Optional HTML ID of the container element where the camera view should be rendered. If not provided, the camera view will be appended to the document body. Web only.                                                                                                                                                                                                    |                                                                        |       |
 
 
 #### IsRunningResponse
@@ -580,6 +731,25 @@ Configuration options for capturing photos and samples.
 | **`saveToFile`** | <code>boolean</code> | If true, saves to a temporary file and returns the web path instead of base64. The web path can be used to set the src attribute of an image for efficient loading and rendering. This reduces the data that needs to be transferred over the bridge, which can improve performance especially for high-resolution images. | <code>false</code> | 1.1.0 |
 
 
+#### VideoRecordingOptions
+
+Configuration options for video recording.
+
+| Prop               | Type                                                                    | Description                                                                          | Default                | Since |
+| ------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------- | ----- |
+| **`enableAudio`**  | <code>boolean</code>                                                    | Whether to record audio with the video. Requires microphone permission.              | <code>false</code>     | 2.2.0 |
+| **`videoQuality`** | <code><a href="#videorecordingquality">VideoRecordingQuality</a></code> | Video recording quality preset. Native platforms only (iOS/Android). Ignored on web. | <code>'highest'</code> | 2.2.0 |
+
+
+#### VideoRecordingResponse
+
+Response from stopping a video recording.
+
+| Prop          | Type                | Description                                                                                                                                       | Since |
+| ------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| **`webPath`** | <code>string</code> | Web-accessible path to the recorded video file. On web, this is a blob URL. On iOS/Android, this is a path accessible via Capacitor's filesystem. | 2.2.0 |
+
+
 #### GetAvailableDevicesResponse
 
 Response for getting available camera devices.
@@ -651,11 +821,12 @@ Response for getting the current torch mode.
 
 #### PermissionStatus
 
-Response for the camera permission status.
+Response for the camera and microphone permission status.
 
-| Prop         | Type                                                        | Description                        |
-| ------------ | ----------------------------------------------------------- | ---------------------------------- |
-| **`camera`** | <code><a href="#permissionstate">PermissionState</a></code> | The state of the camera permission |
+| Prop             | Type                                                        | Description                            |
+| ---------------- | ----------------------------------------------------------- | -------------------------------------- |
+| **`camera`**     | <code><a href="#permissionstate">PermissionState</a></code> | The state of the camera permission     |
+| **`microphone`** | <code><a href="#permissionstate">PermissionState</a></code> | The state of the microphone permission |
 
 
 #### PluginListenerHandle
@@ -693,6 +864,15 @@ Coordinates are normalized between 0 and 1 relative to the camera frame.
 ### Type Aliases
 
 
+#### BarcodeType
+
+Supported barcode types for detection.
+Specifying only the barcode types you need can improve performance
+and reduce battery consumption.
+
+<code>'qr' | 'code128' | 'code39' | 'code39Mod43' | 'code93' | 'ean8' | 'ean13' | 'interleaved2of5' | 'itf14' | 'pdf417' | 'aztec' | 'dataMatrix' | 'upce'</code>
+
+
 #### CameraPosition
 
 Position options for the camera.
@@ -719,6 +899,13 @@ depending on the `saveToFile` option in the <a href="#captureoptions">CaptureOpt
 <code>T['saveToFile'] extends true ? { /** The web path to the captured photo that can be used to set the src attribute of an image for efficient loading and rendering (when saveToFile is true) */ webPath: string; } : { /** The base64 encoded string of the captured photo (when saveToFile is false or undefined) */ photo: string; }</code>
 
 
+#### VideoRecordingQuality
+
+Video recording quality presets.
+
+<code>'lowest' | 'sd' | 'hd' | 'fhd' | 'uhd' | 'highest'</code>
+
+
 #### FlashMode
 
 Flash mode options for the camera.
@@ -733,4 +920,13 @@ Flash mode options for the camera.
 
 <code>'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'</code>
 
+
+#### CameraPermissionType
+
+Permission types that can be requested.
+- 'camera': Camera access permission
+- 'microphone': Microphone access permission (needed for video recording with audio)
+
+<code>'camera' | 'microphone'</code>
+
 </docgen-api>

package/android/build.gradle

@@ -16,7 +16,7 @@ buildscript {
         mavenCentral()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:8.13.0'
+        classpath 'com.android.tools.build:gradle:8.13.2'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
     }
 }
@@ -37,10 +37,10 @@ android {
     buildTypes {
         release {
             minifyEnabled false
-            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
         }
     }
-    lintOptions {
+    lint {
         abortOnError = false
     }
     compileOptions {
@@ -66,19 +66,23 @@ dependencies {
     implementation project(':capacitor-android')
     implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
     implementation 'androidx.core:core-ktx:1.16.0'
-    implementation 'androidx.compose.material3:material3-android:1.3.2'
+    implementation 'androidx.compose.material3:material3-android:1.4.0'
     testImplementation "junit:junit:$junitVersion"
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
     androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
 
     // CameraX dependencies
-    def camerax_version = "1.4.2"
+    def camerax_version = "1.5.3"
     implementation "androidx.camera:camera-core:${camerax_version}"
     implementation "androidx.camera:camera-camera2:${camerax_version}"
     implementation "androidx.camera:camera-lifecycle:${camerax_version}"
     implementation "androidx.camera:camera-view:${camerax_version}"
     implementation "androidx.camera:camera-mlkit-vision:${camerax_version}"
+    implementation "androidx.camera:camera-video:${camerax_version}"
 
     // ML Kit for barcode scanning
     implementation "com.google.mlkit:barcode-scanning:17.3.0"
+
+    // Kotlin coroutines for modern async handling
+    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2"
 }

package/android/src/main/AndroidManifest.xml

@@ -1,2 +1,3 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
 </manifest>