Adds video stabilization to camera

- Adds support for video stabilization to camera:

    Adds getSupportedVideoStabilizationModes() and
    setVideoStabilizationMode() methods to CameraController.

- Adds support for video stabilization to camera_avfoundation

- Adds support for video stabilization to camera_android_camerax

- Adds support for video stabilization to camera_platform_interface:

    - Adds getSupportedVideoStabilizationModes() and
    setVideoStabilizationMode() methods to CameraPlatform.

    - Adds VideoStabilizationMode enum to represent an
    abstraction of the available video stabilization modes,
    meant for Android and iOS, mapped as follows:

      /// Video stabilization is disabled.
      off,

      /// Least stabilized video stabilization mode with the least latency.
      level1,

      /// More stabilized video with more latency.
      level2,

      /// Most stabilized video with the most latency.
      level3;

Author: ruicraveiro

packages/camera/camera/AUTHORS

@@ -64,3 +64,4 @@ Aleksandr Yurkovskiy <[email protected]>
 Anton Borries <[email protected]>
 Alex Li <[email protected]>
 Rahul Raj <[email protected]>
+Rui Craveiro <[email protected]>

packages/camera/camera/CHANGELOG.md

@@ -3,6 +3,10 @@
 * Updates minimum supported SDK version to Flutter 3.29/Dart 3.7.
 * Updates README to reflect that only Android API 24+ is supported.
 
+## 0.12.0
+
+* Adds support for video stabilization.
+
 ## 0.11.2
 
 * Fixes overflowed toggles in the camera example.

packages/camera/camera/example/pubspec.yaml

@@ -31,3 +31,8 @@ dev_dependencies:
 
 flutter:
   uses-material-design: true
+
+# FOR TESTING AND INITIAL REVIEW ONLY. DO NOT MERGE.
+# See https://github.com/flutter/flutter/blob/master/docs/ecosystem/contributing/README.md#changing-federated-plugins
+dependency_overrides:
+   {camera: {path: ../../../camera/camera}, camera_android_camerax: {path: ../../../camera/camera_android_camerax}, camera_avfoundation: {path: ../../../camera/camera_avfoundation}, camera_platform_interface: {path: ../../../camera/camera_platform_interface}, camera_web: {path: ../../../camera/camera_web}}

packages/camera/camera/lib/camera.dart

@@ -13,6 +13,7 @@ export 'package:camera_platform_interface/camera_platform_interface.dart'
         FocusMode,
         ImageFormatGroup,
         ResolutionPreset,
+        VideoStabilizationMode,
         XFile;
 
 export 'src/camera_controller.dart';

packages/camera/camera/lib/src/camera_controller.dart

@@ -54,6 +54,7 @@ class CameraValue {
     this.recordingOrientation,
     this.isPreviewPaused = false,
     this.previewPauseOrientation,
+    this.videoStabilizationMode = VideoStabilizationMode.off,
   }) : _isRecordingPaused = isRecordingPaused;
 
   /// Creates a new camera controller state for an uninitialized controller.
@@ -72,6 +73,7 @@ class CameraValue {
         deviceOrientation: DeviceOrientation.portraitUp,
         isPreviewPaused: false,
         description: description,
+        videoStabilizationMode: VideoStabilizationMode.off,
       );
 
   /// True after [CameraController.initialize] has completed successfully.
@@ -148,6 +150,9 @@ class CameraValue {
   /// The properties of the camera device controlled by this controller.
   final CameraDescription description;
 
+  /// The video stabilization mode in
+  final VideoStabilizationMode videoStabilizationMode;
+
   /// Creates a modified copy of the object.
   ///
   /// Explicitly specified fields get the specified value, all other fields get
@@ -171,6 +176,7 @@ class CameraValue {
     bool? isPreviewPaused,
     CameraDescription? description,
     Optional<DeviceOrientation>? previewPauseOrientation,
+    VideoStabilizationMode? videoStabilizationMode,
   }) {
     return CameraValue(
       isInitialized: isInitialized ?? this.isInitialized,
@@ -201,6 +207,8 @@ class CameraValue {
           previewPauseOrientation == null
               ? this.previewPauseOrientation
               : previewPauseOrientation.orNull,
+      videoStabilizationMode:
+          videoStabilizationMode ?? this.videoStabilizationMode,
     );
   }
 
@@ -222,6 +230,7 @@ class CameraValue {
         'recordingOrientation: $recordingOrientation, '
         'isPreviewPaused: $isPreviewPaused, '
         'previewPausedOrientation: $previewPauseOrientation, '
+        'videoStabilizationMode: $videoStabilizationMode, '
         'description: $description)';
   }
 }
@@ -701,6 +710,111 @@ class CameraController extends ValueNotifier<CameraValue> {
     }
   }
 
+  /// Set the video stabilization mode for the selected camera.
+  ///
+  /// When [allowFallback] is true (default) the camera will
+  /// be set to the best video stabilization mode up to,
+  /// and including, [mode].
+  ///
+  /// When [allowFallback] is false and if
+  /// [mode] is not one of the supported modes
+  /// (see [getSupportedVideoStabilizationModes]),
+  /// then it throws an [ArgumentError].
+  ///
+  /// This feature is only available on Android
+  /// (when using camera_android_camerax package)
+  /// and iOS. It is a no-op on all other platforms.
+  Future<void> setVideoStabilizationMode(
+    VideoStabilizationMode mode, {
+    bool allowFallback = true,
+  }) async {
+    _throwIfNotInitialized('setVideoStabilizationMode');
+    try {
+      final VideoStabilizationMode? modeToSet =
+          await _getVideoStabilizationModeToSet(mode, allowFallback);
+
+      // When _getVideoStabilizationModeToSet returns null
+      // it means that the device doesn't support any
+      // video stabilization mode and that doing nothing
+      // is valid because allowFallback is true or [mode]
+      // is [VideoStabilizationMode.off], so this results
+      // in a no-op.
+      if (modeToSet == null) {
+        return;
+      }
+      await CameraPlatform.instance.setVideoStabilizationMode(
+        _cameraId,
+        modeToSet,
+      );
+      value = value.copyWith(videoStabilizationMode: modeToSet);
+    } on PlatformException catch (e) {
+      throw CameraException(e.code, e.message);
+    }
+  }
+
+  Future<VideoStabilizationMode?> _getVideoStabilizationModeToSet(
+    VideoStabilizationMode requestedMode,
+    bool allowFallback,
+  ) async {
+    final Iterable<VideoStabilizationMode> supportedModes = await CameraPlatform
+        .instance
+        .getSupportedVideoStabilizationModes(_cameraId);
+
+    // In this case the device doesn't report any
+    // available stabilization mode available and
+    // if either it can fallback or if the requested mode
+    // is off, then this returns null to signal that
+    // there is nothing to be done.
+    if (supportedModes.isEmpty &&
+        (allowFallback || requestedMode == VideoStabilizationMode.off)) {
+      return null;
+    }
+
+    // If it can't fallback and the specific
+    // requested mode isn't available, then it throws.
+    if (!allowFallback && !supportedModes.contains(requestedMode)) {
+      throw ArgumentError('Unavailable video stabilization mode.', 'mode');
+    }
+
+    // The following assumes that [VideoStabilizationMode.off] will
+    // always be present if any other level is reported by the device.
+    // It iterates through all the modes returned by the device,
+    // looking for the highest mode, up to [mode].
+    VideoStabilizationMode requestMode = VideoStabilizationMode.off;
+    for (final VideoStabilizationMode supportedMode in supportedModes) {
+      if (supportedMode.index <= requestedMode.index &&
+          supportedMode.index >= requestMode.index) {
+        requestMode = supportedMode;
+      }
+    }
+
+    return requestMode;
+  }
+
+  /// Gets a list of video stabilization modes that are supported
+  /// for the selected camera.
+  ///
+  /// Will return the list of supported video stabilization modes
+  /// on Android (when using camera_android_camerax package) and
+  /// on iOS.
+  ///
+  /// [VideoStabilizationMode.off] will always be listed.
+  Future<Iterable<VideoStabilizationMode>>
+  getSupportedVideoStabilizationModes() async {
+    _throwIfNotInitialized('isVideoStabilizationModeSupported');
+    try {
+      final Set<VideoStabilizationMode> modes = <VideoStabilizationMode>{
+        VideoStabilizationMode.off,
+        ...await CameraPlatform.instance.getSupportedVideoStabilizationModes(
+          _cameraId,
+        ),
+      };
+      return modes;
+    } on PlatformException catch (e) {
+      throw CameraException(e.code, e.message);
+    }
+  }
+
   /// Sets the flash mode for taking pictures.
   Future<void> setFlashMode(FlashMode mode) async {
     try {

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.2
+version: 0.12.0
 
 environment:
   sdk: ^3.7.0
@@ -21,9 +21,9 @@ flutter:
         default_package: camera_web
 
 dependencies:
-  camera_android_camerax: ^0.6.13
-  camera_avfoundation: ^0.9.18
-  camera_platform_interface: ^2.10.0
+  camera_android_camerax: ^0.7.0
+  camera_avfoundation: ^0.10.0
+  camera_platform_interface: ^2.12.0
   camera_web: ^0.3.3
   flutter:
     sdk: flutter
@@ -38,3 +38,8 @@ dev_dependencies:
 
 topics:
   - camera
+
+# FOR TESTING AND INITIAL REVIEW ONLY. DO NOT MERGE.
+# See https://github.com/flutter/flutter/blob/master/docs/ecosystem/contributing/README.md#changing-federated-plugins
+dependency_overrides:
+   {camera_android_camerax: {path: ../../camera/camera_android_camerax}, camera_avfoundation: {path: ../../camera/camera_avfoundation}, camera_platform_interface: {path: ../../camera/camera_platform_interface}, camera_web: {path: ../../camera/camera_web}}

packages/camera/camera/test/camera_preview_test.dart

@@ -137,6 +137,16 @@ class FakeController extends ValueNotifier<CameraValue>
   @override
   CameraDescription get description => value.description;
 
+  @override
+  Future<void> setVideoStabilizationMode(
+    VideoStabilizationMode mode, {
+    bool allowFallback = true,
+  }) async {}
+
+  @override
+  Future<Iterable<VideoStabilizationMode>>
+  getSupportedVideoStabilizationModes() async => <VideoStabilizationMode>[];
+
   @override
   bool supportsImageStreaming() => true;
 }