[video_player] Implement screen auto-lock control for video playback

packages/video_player/video_player/CHANGELOG.md

@@ -1,5 +1,9 @@
-## NEXT
+## 2.12.0
 
+* Adds `preventsDisplaySleepDuringVideoPlayback` to `VideoPlayerOptions` and
+  `VideoPlayerValue`, and `setPreventsDisplaySleepDuringVideoPlayback` to
+  `VideoPlayerController`, to control whether the display sleeps during playback
+  on iOS and macOS.
 * Updates minimum supported SDK version to Flutter 3.38/Dart 3.10.
 
 ## 2.11.1

packages/video_player/video_player/lib/video_player.dart

@@ -163,6 +163,7 @@ class VideoPlayerValue {
     this.rotationCorrection = 0,
     this.errorDescription,
     this.isCompleted = false,
+    this.preventsDisplaySleepDuringVideoPlayback = true,
   });
 
   /// Returns an instance for a video that hasn't been loaded.
@@ -224,6 +225,13 @@ class VideoPlayerValue {
   /// Does not update if video is looping.
   final bool isCompleted;
 
+  /// Whether the screen is prevented from sleeping during video playback.
+  ///
+  /// Defaults to `true`.
+  ///
+  /// This is currently only supported on iOS and macOS.
+  final bool preventsDisplaySleepDuringVideoPlayback;
+
   /// The [size] of the currently loaded video.
   final Size size;
 
@@ -272,6 +280,7 @@ class VideoPlayerValue {
     int? rotationCorrection,
     String? errorDescription = _defaultErrorDescription,
     bool? isCompleted,
+    bool? preventsDisplaySleepDuringVideoPlayback,
   }) {
     return VideoPlayerValue(
       duration: duration ?? this.duration,
@@ -291,6 +300,8 @@ class VideoPlayerValue {
           ? errorDescription
           : this.errorDescription,
       isCompleted: isCompleted ?? this.isCompleted,
+      preventsDisplaySleepDuringVideoPlayback:
+          preventsDisplaySleepDuringVideoPlayback ?? this.preventsDisplaySleepDuringVideoPlayback,
     );
   }
 
@@ -310,7 +321,8 @@ class VideoPlayerValue {
         'volume: $volume, '
         'playbackSpeed: $playbackSpeed, '
         'errorDescription: $errorDescription, '
-        'isCompleted: $isCompleted),';
+        'isCompleted: $isCompleted, '
+        'preventsDisplaySleepDuringVideoPlayback: $preventsDisplaySleepDuringVideoPlayback),';
   }
 
   @override
@@ -332,7 +344,8 @@ class VideoPlayerValue {
           size == other.size &&
           rotationCorrection == other.rotationCorrection &&
           isInitialized == other.isInitialized &&
-          isCompleted == other.isCompleted;
+          isCompleted == other.isCompleted &&
+          preventsDisplaySleepDuringVideoPlayback == other.preventsDisplaySleepDuringVideoPlayback;
 
   @override
   int get hashCode => Object.hash(
@@ -351,6 +364,7 @@ class VideoPlayerValue {
     rotationCorrection,
     isInitialized,
     isCompleted,
+    preventsDisplaySleepDuringVideoPlayback,
   );
 }
 
@@ -384,7 +398,13 @@ class VideoPlayerController extends ValueNotifier<VideoPlayerValue> {
        dataSourceType = platform_interface.DataSourceType.asset,
        formatHint = null,
        httpHeaders = const <String, String>{},
-       super(const VideoPlayerValue(duration: Duration.zero));
+       super(
+         VideoPlayerValue(
+           duration: Duration.zero,
+           preventsDisplaySleepDuringVideoPlayback:
+               videoPlayerOptions?.preventsDisplaySleepDuringVideoPlayback ?? true,
+         ),
+       );
 
   /// Constructs a [VideoPlayerController] playing a network video.
   ///
@@ -410,7 +430,13 @@ class VideoPlayerController extends ValueNotifier<VideoPlayerValue> {
   }) : _closedCaptionFileFuture = closedCaptionFile,
        dataSourceType = platform_interface.DataSourceType.network,
        package = null,
-       super(const VideoPlayerValue(duration: Duration.zero));
+       super(
+         VideoPlayerValue(
+           duration: Duration.zero,
+           preventsDisplaySleepDuringVideoPlayback:
+               videoPlayerOptions?.preventsDisplaySleepDuringVideoPlayback ?? true,
+         ),
+       );
 
   /// Constructs a [VideoPlayerController] playing a network video.
   ///
@@ -432,7 +458,13 @@ class VideoPlayerController extends ValueNotifier<VideoPlayerValue> {
        dataSource = url.toString(),
        dataSourceType = platform_interface.DataSourceType.network,
        package = null,
-       super(const VideoPlayerValue(duration: Duration.zero));
+       super(
+         VideoPlayerValue(
+           duration: Duration.zero,
+           preventsDisplaySleepDuringVideoPlayback:
+               videoPlayerOptions?.preventsDisplaySleepDuringVideoPlayback ?? true,
+         ),
+       );
 
   /// Constructs a [VideoPlayerController] playing a video from a file.
   ///
@@ -449,7 +481,13 @@ class VideoPlayerController extends ValueNotifier<VideoPlayerValue> {
        dataSourceType = platform_interface.DataSourceType.file,
        package = null,
        formatHint = null,
-       super(const VideoPlayerValue(duration: Duration.zero));
+       super(
+         VideoPlayerValue(
+           duration: Duration.zero,
+           preventsDisplaySleepDuringVideoPlayback:
+               videoPlayerOptions?.preventsDisplaySleepDuringVideoPlayback ?? true,
+         ),
+       );
 
   /// Constructs a [VideoPlayerController] playing a video from a contentUri.
   ///
@@ -470,7 +508,13 @@ class VideoPlayerController extends ValueNotifier<VideoPlayerValue> {
        package = null,
        formatHint = null,
        httpHeaders = const <String, String>{},
-       super(const VideoPlayerValue(duration: Duration.zero));
+       super(
+         VideoPlayerValue(
+           duration: Duration.zero,
+           preventsDisplaySleepDuringVideoPlayback:
+               videoPlayerOptions?.preventsDisplaySleepDuringVideoPlayback ?? true,
+         ),
+       );
 
   /// The URI to the video file. This will be in different formats depending on
   /// the [DataSourceType] of the original video.
@@ -571,6 +615,11 @@ class VideoPlayerController extends ValueNotifier<VideoPlayerValue> {
     _creatingCompleter!.complete(null);
     final initializingCompleter = Completer<void>();
 
+    await _videoPlayerPlatform.setPreventsDisplaySleepDuringVideoPlayback(
+      _playerId,
+      value.preventsDisplaySleepDuringVideoPlayback,
+    );
+
     // Apply the web-specific options
     if (kIsWeb && videoPlayerOptions?.webOptions != null) {
       await _videoPlayerPlatform.setWebOptions(_playerId, videoPlayerOptions!.webOptions!);
@@ -690,6 +739,18 @@ class VideoPlayerController extends ValueNotifier<VideoPlayerValue> {
     await _applyLooping();
   }
 
+  /// Sets whether the screen is prevented from sleeping during video playback.
+  ///
+  /// See also [VideoPlayerValue.preventsDisplaySleepDuringVideoPlayback].
+  Future<void> setPreventsDisplaySleepDuringVideoPlayback(
+    bool preventsDisplaySleepDuringVideoPlayback,
+  ) async {
+    value = value.copyWith(
+      preventsDisplaySleepDuringVideoPlayback: preventsDisplaySleepDuringVideoPlayback,
+    );
+    await _applyPreventsDisplaySleepDuringVideoPlayback();
+  }
+
   /// Pauses the video.
   Future<void> pause() async {
     value = value.copyWith(isPlaying: false);
@@ -703,6 +764,16 @@ class VideoPlayerController extends ValueNotifier<VideoPlayerValue> {
     await _videoPlayerPlatform.setLooping(_playerId, value.isLooping);
   }
 
+  Future<void> _applyPreventsDisplaySleepDuringVideoPlayback() async {
+    if (_isDisposedOrNotInitialized) {
+      return;
+    }
+    await _videoPlayerPlatform.setPreventsDisplaySleepDuringVideoPlayback(
+      _playerId,
+      value.preventsDisplaySleepDuringVideoPlayback,
+    );
+  }
+
   Future<void> _applyPlayPause() async {
     if (_isDisposedOrNotInitialized) {
       return;

packages/video_player/video_player/pubspec.yaml

@@ -3,7 +3,7 @@ description: Flutter plugin for displaying inline video with other Flutter
   widgets on Android, iOS, macOS and web.
 repository: https://github.com/flutter/packages/tree/main/packages/video_player/video_player
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+video_player%22
-version: 2.11.1
+version: 2.12.0
 
 environment:
   sdk: ^3.10.0
@@ -27,8 +27,8 @@ dependencies:
     sdk: flutter
   html: ^0.15.0
   video_player_android: ^2.9.1
-  video_player_avfoundation: ^2.9.0
-  video_player_platform_interface: ^6.6.0
+  video_player_avfoundation: ^2.11.0
+  video_player_platform_interface: ^6.8.0
   video_player_web: ^2.1.0
 
 dev_dependencies:

packages/video_player/video_player/test/video_player_test.dart

@@ -71,6 +71,9 @@ class FakeController extends ValueNotifier<VideoPlayerValue> implements VideoPla
   @override
   Future<void> setLooping(bool looping) async {}
 
+  @override
+  Future<void> setPreventsDisplaySleepDuringVideoPlayback(bool prevents) async {}
+
   @override
   VideoFormat? get formatHint => null;
 
@@ -1027,13 +1030,11 @@ void main() {
         }
 
         expect(isSorted, false, reason: 'Expected captions to be unsorted');
-        expect(captions.map((Caption c) => c.text).toList(), <String>[
-          'one',
-          'two',
-          'three',
-          'five',
-          'four',
-        ], reason: 'Captions should be in original unsorted order');
+        expect(
+          captions.map((Caption c) => c.text).toList(),
+          <String>['one', 'two', 'three', 'five', 'four'],
+          reason: 'Captions should be in original unsorted order',
+        );
       });
 
       test('works when seeking, includes all captions', () async {
@@ -1667,7 +1668,8 @@ void main() {
           'volume: 0.5, '
           'playbackSpeed: 1.5, '
           'errorDescription: null, '
-          'isCompleted: false),',
+          'isCompleted: false, '
+          'preventsDisplaySleepDuringVideoPlayback: true),',
         );
       });
 
@@ -1754,6 +1756,22 @@ void main() {
         expect(controller.videoPlayerOptions!.mixWithOthers, true);
       });
 
+      test('setPreventsDisplaySleepDuringVideoPlayback', () async {
+        final controller = VideoPlayerController.networkUrl(_localhostUri);
+        addTearDown(controller.dispose);
+
+        await controller.initialize();
+        expect(controller.value.preventsDisplaySleepDuringVideoPlayback, true);
+
+        await controller.setPreventsDisplaySleepDuringVideoPlayback(false);
+        expect(controller.value.preventsDisplaySleepDuringVideoPlayback, false);
+
+        expect(
+          fakeVideoPlayerPlatform.calls.contains('setPreventsDisplaySleepDuringVideoPlayback'),
+          true,
+        );
+      });
+
       test('true allowBackgroundPlayback continues playback', () async {
         final controller = VideoPlayerController.networkUrl(
           _localhostUri,
@@ -2004,6 +2022,14 @@ class FakeVideoPlayerPlatform extends VideoPlayerPlatform {
     calls.add('setMixWithOthers');
   }
 
+  @override
+  Future<void> setPreventsDisplaySleepDuringVideoPlayback(
+    int playerId,
+    bool preventsDisplaySleepDuringVideoPlayback,
+  ) async {
+    calls.add('setPreventsDisplaySleepDuringVideoPlayback');
+  }
+
   @override
   Widget buildView(int playerId) {
     return Texture(textureId: playerId);