[video_player] Improve seek performance on Android

Adds `backBufferDurationMs` to `VideoPlayerOptions` and configures ExoPlayer's `DefaultLoadControl` to retain the back buffer from keyframes. This significantly improves seek performance and responsiveness during video playback on Android.

Author: Sailendra Bathi

packages/video_player/video_player/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 * Updates minimum supported SDK version to Flutter 3.38/Dart 3.10.
 
+## 2.12.0
+
+* Passes `backBufferDurationMs` from `VideoPlayerOptions` to the underlying platform interface.
+
 ## 2.11.1
 
 * Optimizes caption retrieval with binary search.

packages/video_player/video_player/example/lib/main.dart

@@ -316,7 +316,7 @@ class _BumbleBeeRemoteVideoState extends State<_BumbleBeeRemoteVideo> {
         'https://flutter.github.io/assets-for-api-docs/assets/videos/bee.mp4',
       ),
       closedCaptionFile: _loadCaptions(),
-      videoPlayerOptions: VideoPlayerOptions(mixWithOthers: true),
+      videoPlayerOptions: const VideoPlayerOptions(mixWithOthers: true),
       viewType: widget.viewType,
     );
 

packages/video_player/video_player/lib/video_player.dart

@@ -576,6 +576,7 @@ class VideoPlayerController extends ValueNotifier<VideoPlayerValue> {
     final creationOptions = platform_interface.VideoCreationOptions(
       dataSource: dataSourceDescription,
       viewType: viewType,
+      videoPlayerOptions: videoPlayerOptions,
     );
 
     if (videoPlayerOptions?.mixWithOthers != null) {

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
@@ -26,10 +26,10 @@ dependencies:
   flutter:
     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_web: ^2.1.0
+  video_player_android: ^2.10.0
+  video_player_avfoundation: ^2.10.0
+  video_player_platform_interface: ^6.8.0
+  video_player_web: ^2.5.0
 
 dev_dependencies:
   flutter_test:

packages/video_player/video_player/test/video_player_initialization_test.dart

@@ -36,7 +36,7 @@ void main() {
 
     final controller = VideoPlayerController.networkUrl(
       Uri.parse('https://127.0.0.1'),
-      videoPlayerOptions: VideoPlayerOptions(webOptions: expected),
+      videoPlayerOptions: const VideoPlayerOptions(webOptions: expected),
     );
     await controller.initialize();
 
@@ -80,4 +80,24 @@ void main() {
       reason: 'view type must be passed to the platform',
     );
   });
+
+  test('back buffer duration is forwarded to platform', () async {
+    const expectedBackBufferDurationMs = 20000;
+
+    final controller = VideoPlayerController.networkUrl(
+      Uri.parse('https://127.0.0.1'),
+      videoPlayerOptions: const VideoPlayerOptions(
+        backBufferDurationMs: expectedBackBufferDurationMs,
+      ),
+    );
+
+    await controller.initialize();
+
+    expect(
+      fakeVideoPlayerPlatform.videoPlayerOptions.last?.backBufferDurationMs,
+      expectedBackBufferDurationMs,
+      reason:
+          'backBufferDurationMs must be forwarded to the platform via VideoCreationOptions.videoPlayerOptions',
+    );
+  });
 }

packages/video_player/video_player/test/video_player_test.dart

@@ -582,35 +582,51 @@ void main() {
         expect(uri.endsWith('/a.avi'), true, reason: 'Actual string: $uri');
       }, skip: kIsWeb /* Web does not support file assets. */);
 
-      test('file with special characters', () async {
-        final controller = VideoPlayerController.file(File('A #1 Hit.avi'));
-        await controller.initialize();
+      test(
+        'file with special characters',
+        () async {
+          final controller = VideoPlayerController.file(File('A #1 Hit.avi'));
+          await controller.initialize();
 
-        final String uri = fakeVideoPlayerPlatform.dataSources[0].uri!;
-        expect(uri.startsWith('file:///'), true, reason: 'Actual string: $uri');
-        expect(
-          uri.endsWith('/A%20%231%20Hit.avi'),
-          true,
-          reason: 'Actual string: $uri',
-        );
-      }, skip: kIsWeb /* Web does not support file assets. */);
+          final String uri = fakeVideoPlayerPlatform.dataSources[0].uri!;
+          expect(
+            uri.startsWith('file:///'),
+            true,
+            reason: 'Actual string: $uri',
+          );
+          expect(
+            uri.endsWith('/A%20%231%20Hit.avi'),
+            true,
+            reason: 'Actual string: $uri',
+          );
+        },
+        skip: kIsWeb /* Web does not support file assets. */,
+      );
 
-      test('file with headers (m3u8)', () async {
-        final controller = VideoPlayerController.file(
-          File('a.avi'),
-          httpHeaders: <String, String>{'Authorization': 'Bearer token'},
-        );
-        await controller.initialize();
+      test(
+        'file with headers (m3u8)',
+        () async {
+          final controller = VideoPlayerController.file(
+            File('a.avi'),
+            httpHeaders: <String, String>{'Authorization': 'Bearer token'},
+          );
+          await controller.initialize();
 
-        final String uri = fakeVideoPlayerPlatform.dataSources[0].uri!;
-        expect(uri.startsWith('file:///'), true, reason: 'Actual string: $uri');
-        expect(uri.endsWith('/a.avi'), true, reason: 'Actual string: $uri');
+          final String uri = fakeVideoPlayerPlatform.dataSources[0].uri!;
+          expect(
+            uri.startsWith('file:///'),
+            true,
+            reason: 'Actual string: $uri',
+          );
+          expect(uri.endsWith('/a.avi'), true, reason: 'Actual string: $uri');
 
-        expect(
-          fakeVideoPlayerPlatform.dataSources[0].httpHeaders,
-          <String, String>{'Authorization': 'Bearer token'},
-        );
-      }, skip: kIsWeb /* Web does not support file assets. */);
+          expect(
+            fakeVideoPlayerPlatform.dataSources[0].httpHeaders,
+            <String, String>{'Authorization': 'Bearer token'},
+          );
+        },
+        skip: kIsWeb /* Web does not support file assets. */,
+      );
 
       test(
         'successful initialize on controller with error clears error',
@@ -1151,13 +1167,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 {
@@ -2096,6 +2110,7 @@ class FakeVideoPlayerPlatform extends VideoPlayerPlatform {
   List<String> calls = <String>[];
   List<DataSource> dataSources = <DataSource>[];
   List<VideoViewType> viewTypes = <VideoViewType>[];
+  List<VideoPlayerOptions?> videoPlayerOptions = <VideoPlayerOptions?>[];
   final Map<int, StreamController<VideoEvent>> streams =
       <int, StreamController<VideoEvent>>{};
   bool forceInitError = false;
@@ -2152,6 +2167,7 @@ class FakeVideoPlayerPlatform extends VideoPlayerPlatform {
     }
     dataSources.add(options.dataSource);
     viewTypes.add(options.viewType);
+    videoPlayerOptions.add(options.videoPlayerOptions);
     return nextPlayerId++;
   }
 

packages/video_player/video_player_android/CHANGELOG.md

@@ -3,6 +3,10 @@
 * Migrates to Built-in Kotlin to support AGP 9.
 * Updates minimum supported SDK version to Flutter 3.44/Dart 3.12.
 
+## 2.10.0
+
+* Adds `backBufferDurationMs` to `CreationOptions` to configure ExoPlayer `DefaultLoadControl` back buffer duration.
+
 ## 2.9.5
 
 * Updates build files from Groovy to Kotlin.

packages/video_player/video_player_android/android/src/main/java/io/flutter/plugins/videoplayer/VideoPlayerOptions.java

@@ -6,4 +6,17 @@
 
 public class VideoPlayerOptions {
   public boolean mixWithOthers;
+
+  /**
+   * The duration of the back buffer in milliseconds, used to configure ExoPlayer's load control.
+   */
+  public Long backBufferDurationMs;
+
+  public VideoPlayerOptions() {}
+
+  /** Copy constructor to ensure all options are reliably copied. */
+  public VideoPlayerOptions(VideoPlayerOptions other) {
+    this.mixWithOthers = other.mixWithOthers;
+    this.backBufferDurationMs = other.backBufferDurationMs;
+  }
 }

packages/video_player/video_player_android/android/src/main/java/io/flutter/plugins/videoplayer/VideoPlayerPlugin.java

@@ -87,12 +87,15 @@ public long createForPlatformView(@NonNull CreationOptions options) {
 
     long id = nextPlayerIdentifier++;
     final String streamInstance = Long.toString(id);
+    VideoPlayerOptions playerOptions = new VideoPlayerOptions(sharedOptions);
+    playerOptions.backBufferDurationMs = options.getBackBufferDurationMs();
+
     VideoPlayer videoPlayer =
         PlatformViewVideoPlayer.create(
             flutterState.applicationContext,
             VideoPlayerEventCallbacks.bindTo(flutterState.binaryMessenger, streamInstance),
             videoAsset,
-            sharedOptions);
+            playerOptions);
 
     registerPlayerInstance(videoPlayer, id);
     return id;
@@ -106,13 +109,16 @@ public long createForPlatformView(@NonNull CreationOptions options) {
     long id = nextPlayerIdentifier++;
     final String streamInstance = Long.toString(id);
     TextureRegistry.SurfaceProducer handle = flutterState.textureRegistry.createSurfaceProducer();
+    VideoPlayerOptions playerOptions = new VideoPlayerOptions(sharedOptions);
+    playerOptions.backBufferDurationMs = options.getBackBufferDurationMs();
+
     VideoPlayer videoPlayer =
         TextureVideoPlayer.create(
             flutterState.applicationContext,
             VideoPlayerEventCallbacks.bindTo(flutterState.binaryMessenger, streamInstance),
             handle,
             videoAsset,
-            sharedOptions);
+            playerOptions);
 
     registerPlayerInstance(videoPlayer, id);
     return new TexturePlayerIds(id, handle.id());

packages/video_player/video_player_android/android/src/main/java/io/flutter/plugins/videoplayer/platformview/PlatformViewVideoPlayer.java

@@ -10,6 +10,7 @@
 import androidx.annotation.VisibleForTesting;
 import androidx.media3.common.MediaItem;
 import androidx.media3.common.util.UnstableApi;
+import androidx.media3.exoplayer.DefaultLoadControl;
 import androidx.media3.exoplayer.ExoPlayer;
 import io.flutter.plugins.videoplayer.ExoPlayerEventListener;
 import io.flutter.plugins.videoplayer.VideoAsset;
@@ -56,12 +57,23 @@ public static PlatformViewVideoPlayer create(
         asset.getMediaItem(),
         options,
         () -> {
+          ExoPlayer.Builder builder = new ExoPlayer.Builder(context);
+          if (options.backBufferDurationMs != null && options.backBufferDurationMs > 0) {
+            // Clamp the value to ensure it fits within the int range expected by
+            // DefaultLoadControl.
+            int backBufferInt =
+                (int) Math.min(options.backBufferDurationMs.longValue(), Integer.MAX_VALUE);
+            DefaultLoadControl loadControl =
+                new DefaultLoadControl.Builder()
+                    .setBackBuffer(backBufferInt, /* retainBackBufferFromKeyframe= */ true)
+                    .build();
+            builder.setLoadControl(loadControl);
+          }
           androidx.media3.exoplayer.trackselection.DefaultTrackSelector trackSelector =
               new androidx.media3.exoplayer.trackselection.DefaultTrackSelector(context);
-          ExoPlayer.Builder builder =
-              new ExoPlayer.Builder(context)
-                  .setTrackSelector(trackSelector)
-                  .setMediaSourceFactory(asset.getMediaSourceFactory(context));
+          builder
+              .setTrackSelector(trackSelector)
+              .setMediaSourceFactory(asset.getMediaSourceFactory(context));
           return builder.build();
         });
   }