[camerax] Add notes about Android permissions (flutter#6741)

Adds notes in the camera/camera and camera/camera_android_cameraX READMEs about the used `WRITE_EXTERNAL_STORAGE` permission used in the plugin and the foreground service permission that is required to specify if you wish to allow image streaming in the background. Fixes flutter/flutter#146935 and addresses flutter/flutter#131116 (comment).
Arctuition · May 29, 2024 · d3b60e5 · d3b60e5
1 parent 5c60fdc
commit d3b60e5
Show file tree

Hide file tree

Showing 7 changed files with 38 additions and 4 deletions.
diff --git a/packages/camera/camera/CHANGELOG.md b/packages/camera/camera/CHANGELOG.md
@@ -1,6 +1,7 @@
-## NEXT
+## 0.11.0+1
 
 * Updates minimum supported SDK version to Flutter 3.16/Dart 3.2.
+* Adds note to `README.md` about allowing image streaming in the background on Android.
 
 ## 0.11.0
 

diff --git a/packages/camera/camera/README.md b/packages/camera/camera/README.md
@@ -50,6 +50,9 @@ better support for more devices than `camera_android`, but has some limitations;
 for more details. If you wish to use the [`camera_android`][4] implementation of the camera plugin
 built with Camera2 that lacks these limitations, please follow [these instructions][5].
 
+If you wish to allow image streaming while your app is in the background, there are additional steps required;
+please see [these instructions][6] for more details.
+
 ### Web integration
 
 For web integration details, see the
@@ -174,3 +177,4 @@ For a more elaborate usage example see [here](https://github.com/flutter/package
 [3]: https://pub.dev/packages/camera_android_camerax#limitations
 [4]: https://pub.dev/packages/camera_android
 [5]: https://pub.dev/packages/camera_android#usage
+[6]: https://pub.dev/packages/camera_android_camerax#allowing-image-streaming-in-the-background
diff --git a/packages/camera/camera/pubspec.yaml b/packages/camera/camera/pubspec.yaml
@@ -4,7 +4,7 @@ description: A Flutter plugin for controlling the camera. Supports previewing
   Dart.
 repository: https://github.com/flutter/packages/tree/main/packages/camera/camera
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+camera%22
-version: 0.11.0
+version: 0.11.0+1
 
 environment:
   sdk: ^3.2.3

diff --git a/packages/camera/camera_android_camerax/CHANGELOG.md b/packages/camera/camera_android_camerax/CHANGELOG.md
@@ -1,6 +1,9 @@
-## NEXT
+## 0.6.5+3
 
 * Updates minimum supported SDK version to Flutter 3.22/Dart 3.4.
+* Adds notes to `README.md` about allowing image streaming in the background and the required
+  `WRITE_EXTERNAL_STORAGE` permission specified in the plugin to allow writing photos and videos to
+  files.
 
 ## 0.6.5+2
 

diff --git a/packages/camera/camera_android_camerax/README.md b/packages/camera/camera_android_camerax/README.md
@@ -51,6 +51,28 @@ Calling `startVideoCapturing` with `VideoCaptureOptions` configured with
 limitations of the CameraX library and the platform interface, respectively,
 and thus, those parameters will silently be ignored.
 
+## What requires Android permissions
+
+### Writing to external storage to save image files
+
+In order to save captured images and videos to files on Android 10 and below, CameraX
+requires specifying the `WRITE_EXTERNAL_STORAGE` permission (see [the CameraX documentation][10]).
+This is already done in the plugin, so no further action is required on your end. To understand
+the implications of specificying this permission, see [the `WRITE_EXTERNAL_STORAGE` documentation][11].
+
+### Allowing image streaming in the background
+
+As of Android 14, to allow for background image streaming, you will need to specify the foreground
+[`TYPE_CAMERA`][12] foreground service permission in your app's manifest. Specifically, in
+`your_app/android/app/src/main/AndroidManifest.xml` add the following:
+
+```xml
+<manifest ...>
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA" />
+  ...
+</manifest>
+```
+
 ## Contributing
 
 For more information on contributing to this plugin, see [`CONTRIBUTING.md`](CONTRIBUTING.md).
@@ -66,4 +88,7 @@ For more information on contributing to this plugin, see [`CONTRIBUTING.md`](CON
 [7]: https://developer.android.com/reference/android/hardware/camera2/CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_3
 [8]: https://developer.android.com/reference/android/hardware/camera2/CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED
 [9]: https://pub.dev/packages/camera_android#usage
+[10]: https://developer.android.com/media/camera/camerax/architecture#permissions
+[11]: https://developer.android.com/reference/android/Manifest.permission#WRITE_EXTERNAL_STORAGE
+[12]: https://developer.android.com/reference/android/Manifest.permission#FOREGROUND_SERVICE_CAMERA
 [148013]: https://github.com/flutter/flutter/issues/148013
diff --git a/packages/camera/camera_android_camerax/example/android/app/src/main/AndroidManifest.xml b/packages/camera/camera_android_camerax/example/android/app/src/main/AndroidManifest.xml
@@ -1,5 +1,6 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
     package="io.flutter.plugins.cameraxexample">
+   <uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA" />
    <application
         android:label="camera_android_camerax_example"
         android:name="${applicationName}"

diff --git a/packages/camera/camera_android_camerax/pubspec.yaml b/packages/camera/camera_android_camerax/pubspec.yaml
@@ -2,7 +2,7 @@ name: camera_android_camerax
 description: Android implementation of the camera plugin using the CameraX library.
 repository: https://github.com/flutter/packages/tree/main/packages/camera/camera_android_camerax
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+camera%22
-version: 0.6.5+2
+version: 0.6.5+3
 
 environment:
   sdk: ^3.4.0