[video_player] Move Android buffer updates to Dart (#9771)

Since ExoPlayer does not generate events for changes to the buffer position, the `video_player_android` synthesizes them via polling. This moves the logic to generate these events from Java to Dart, to reduce the amount of logic on the Java side.

This does not attempt to fix the structural problem that the workaround was piggy-backed on the fact that the app-facing package polls frequently for the playback position, generating buffer update events when that polling happens rather than via any independent internal polling system. This approach is not only fragile, as it depends on logic defined in another package, but already doesn't work in the case of a paused video. However, this refactoring will make it possible to change this behavior in Dart code in a follow-up focused on that behavioral change. This change should be behavior-neutral, except that it adds the simple improvement of not creating events if the buffer position hasn't changed, so that clients aren't getting a stream of useless buffer position events during playback.

This version will also be more efficient from a platform channel standpoint, since instead of sending a separate message with the buffer position, it's returned in the same call as the playback position.

To support synthesizing events on the Dart side, this adds a custom stream controller in Dart, instead of creating it directly from the EventChannel stream; this change will make future changes to a non-method-channel approach (e.g., FFI callbacks) straightforward. As this adds non-trivial additional per-player-instance state on the Dart side, this adds a Dart player instance class, and consolidates existing state into that class, including passthrough methods for the API calls, making it clearer which state is plugin level vs player level.

Part of flutter/flutter#172763

## Pre-Review Checklist

**Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

[^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.

Author: stuartmorgan-g

packages/video_player/video_player_android/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.8.12
+
+* Moves buffer position update event generation to Dart.
+
 ## 2.8.11
 
 * Updates kotlin version to 2.2.0 to enable gradle 8.11 support.

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

@@ -324,6 +324,100 @@ ArrayList<Object> toList() {
     }
   }
 
+  /** Generated class from Pigeon that represents data sent in messages. */
+  public static final class PlaybackState {
+    /** The current playback position, in milliseconds. */
+    private @NonNull Long playPosition;
+
+    public @NonNull Long getPlayPosition() {
+      return playPosition;
+    }
+
+    public void setPlayPosition(@NonNull Long setterArg) {
+      if (setterArg == null) {
+        throw new IllegalStateException("Nonnull field \"playPosition\" is null.");
+      }
+      this.playPosition = setterArg;
+    }
+
+    /** The current buffer position, in milliseconds. */
+    private @NonNull Long bufferPosition;
+
+    public @NonNull Long getBufferPosition() {
+      return bufferPosition;
+    }
+
+    public void setBufferPosition(@NonNull Long setterArg) {
+      if (setterArg == null) {
+        throw new IllegalStateException("Nonnull field \"bufferPosition\" is null.");
+      }
+      this.bufferPosition = setterArg;
+    }
+
+    /** Constructor is non-public to enforce null safety; use Builder. */
+    PlaybackState() {}
+
+    @Override
+    public boolean equals(Object o) {
+      if (this == o) {
+        return true;
+      }
+      if (o == null || getClass() != o.getClass()) {
+        return false;
+      }
+      PlaybackState that = (PlaybackState) o;
+      return playPosition.equals(that.playPosition) && bufferPosition.equals(that.bufferPosition);
+    }
+
+    @Override
+    public int hashCode() {
+      return Objects.hash(playPosition, bufferPosition);
+    }
+
+    public static final class Builder {
+
+      private @Nullable Long playPosition;
+
+      @CanIgnoreReturnValue
+      public @NonNull Builder setPlayPosition(@NonNull Long setterArg) {
+        this.playPosition = setterArg;
+        return this;
+      }
+
+      private @Nullable Long bufferPosition;
+
+      @CanIgnoreReturnValue
+      public @NonNull Builder setBufferPosition(@NonNull Long setterArg) {
+        this.bufferPosition = setterArg;
+        return this;
+      }
+
+      public @NonNull PlaybackState build() {
+        PlaybackState pigeonReturn = new PlaybackState();
+        pigeonReturn.setPlayPosition(playPosition);
+        pigeonReturn.setBufferPosition(bufferPosition);
+        return pigeonReturn;
+      }
+    }
+
+    @NonNull
+    ArrayList<Object> toList() {
+      ArrayList<Object> toListResult = new ArrayList<>(2);
+      toListResult.add(playPosition);
+      toListResult.add(bufferPosition);
+      return toListResult;
+    }
+
+    static @NonNull PlaybackState fromList(@NonNull ArrayList<Object> pigeonVar_list) {
+      PlaybackState pigeonResult = new PlaybackState();
+      Object playPosition = pigeonVar_list.get(0);
+      pigeonResult.setPlayPosition((Long) playPosition);
+      Object bufferPosition = pigeonVar_list.get(1);
+      pigeonResult.setBufferPosition((Long) bufferPosition);
+      return pigeonResult;
+    }
+  }
+
   private static class PigeonCodec extends StandardMessageCodec {
     public static final PigeonCodec INSTANCE = new PigeonCodec();
 
@@ -346,6 +440,8 @@ protected Object readValueOfType(byte type, @NonNull ByteBuffer buffer) {
           return PlatformVideoViewCreationParams.fromList((ArrayList<Object>) readValue(buffer));
         case (byte) 132:
           return CreateMessage.fromList((ArrayList<Object>) readValue(buffer));
+        case (byte) 133:
+          return PlaybackState.fromList((ArrayList<Object>) readValue(buffer));
         default:
           return super.readValueOfType(type, buffer);
       }
@@ -365,6 +461,9 @@ protected void writeValue(@NonNull ByteArrayOutputStream stream, Object value) {
       } else if (value instanceof CreateMessage) {
         stream.write(132);
         writeValue(stream, ((CreateMessage) value).toList());
+      } else if (value instanceof PlaybackState) {
+        stream.write(133);
+        writeValue(stream, ((PlaybackState) value).toList());
       } else {
         super.writeValue(stream, value);
       }
@@ -532,21 +631,26 @@ static void setUp(
   }
   /** Generated interface from Pigeon that represents a handler of messages from Flutter. */
   public interface VideoPlayerInstanceApi {
-
+    /** Sets whether to automatically loop playback of the video. */
     void setLooping(@NonNull Boolean looping);
-
+    /** Sets the volume, with 0.0 being muted and 1.0 being full volume. */
     void setVolume(@NonNull Double volume);
-
+    /** Sets the playback speed as a multiple of normal speed. */
     void setPlaybackSpeed(@NonNull Double speed);
-
+    /** Begins playback if the video is not currently playing. */
     void play();
-
-    @NonNull
-    Long getPosition();
-
-    void seekTo(@NonNull Long position);
-
+    /** Pauses playback if the video is currently playing. */
     void pause();
+    /** Seeks to the given playback position, in milliseconds. */
+    void seekTo(@NonNull Long position);
+    /**
+     * Returns the current playback state.
+     *
+     * <p>This is combined into a single call to minimize platform channel calls for state that
+     * needs to be polled frequently.
+     */
+    @NonNull
+    PlaybackState getPlaybackState();
 
     /** The codec used by VideoPlayerInstanceApi. */
     static @NonNull MessageCodec<Object> getCodec() {
@@ -668,16 +772,16 @@ static void setUp(
         BasicMessageChannel<Object> channel =
             new BasicMessageChannel<>(
                 binaryMessenger,
-                "dev.flutter.pigeon.video_player_android.VideoPlayerInstanceApi.getPosition"
+                "dev.flutter.pigeon.video_player_android.VideoPlayerInstanceApi.pause"
                     + messageChannelSuffix,
                 getCodec());
         if (api != null) {
           channel.setMessageHandler(
               (message, reply) -> {
                 ArrayList<Object> wrapped = new ArrayList<>();
                 try {
-                  Long output = api.getPosition();
-                  wrapped.add(0, output);
+                  api.pause();
+                  wrapped.add(0, null);
                 } catch (Throwable exception) {
                   wrapped = wrapError(exception);
                 }
@@ -716,16 +820,16 @@ static void setUp(
         BasicMessageChannel<Object> channel =
             new BasicMessageChannel<>(
                 binaryMessenger,
-                "dev.flutter.pigeon.video_player_android.VideoPlayerInstanceApi.pause"
+                "dev.flutter.pigeon.video_player_android.VideoPlayerInstanceApi.getPlaybackState"
                     + messageChannelSuffix,
                 getCodec());
         if (api != null) {
           channel.setMessageHandler(
               (message, reply) -> {
                 ArrayList<Object> wrapped = new ArrayList<>();
                 try {
-                  api.pause();
-                  wrapped.add(0, null);
+                  PlaybackState output = api.getPlaybackState();
+                  wrapped.add(0, output);
                 } catch (Throwable exception) {
                   wrapped = wrapError(exception);
                 }

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

@@ -66,10 +66,6 @@ public void setDisposeHandler(@Nullable DisposeHandler handler) {
   protected abstract ExoPlayerEventListener createExoPlayerEventListener(
       @NonNull ExoPlayer exoPlayer, @Nullable SurfaceProducer surfaceProducer);
 
-  void sendBufferingUpdate() {
-    videoPlayerEvents.onBufferingUpdate(exoPlayer.getBufferedPosition());
-  }
-
   private static void setAudioAttributes(ExoPlayer exoPlayer, boolean isMixMode) {
     exoPlayer.setAudioAttributes(
         new AudioAttributes.Builder().setContentType(C.AUDIO_CONTENT_TYPE_MOVIE).build(),
@@ -107,12 +103,11 @@ public void setPlaybackSpeed(@NonNull Double speed) {
   }
 
   @Override
-  public @NonNull Long getPosition() {
-    long position = exoPlayer.getCurrentPosition();
-    // TODO(stuartmorgan): Move this; this is relying on the fact that getPosition is called
-    //  frequently to drive buffering updates, which is a fragile hack.
-    sendBufferingUpdate();
-    return position;
+  public @NonNull Messages.PlaybackState getPlaybackState() {
+    return new Messages.PlaybackState.Builder()
+        .setPlayPosition(exoPlayer.getCurrentPosition())
+        .setBufferPosition(exoPlayer.getBufferedPosition())
+        .build();
   }
 
   @Override

packages/video_player/video_player_android/android/src/test/java/io/flutter/plugins/videoplayer/VideoPlayerTest.java

@@ -126,17 +126,6 @@ public void playsAndPausesProvidedMedia() {
     videoPlayer.dispose();
   }
 
-  @Test
-  public void sendsBufferingUpdatesOnDemand() {
-    VideoPlayer videoPlayer = createVideoPlayer();
-
-    when(mockExoPlayer.getBufferedPosition()).thenReturn(10L);
-    videoPlayer.sendBufferingUpdate();
-    verify(mockEvents).onBufferingUpdate(10L);
-
-    videoPlayer.dispose();
-  }
-
   @Test
   public void togglesLoopingEnablesAndDisablesRepeatMode() {
     VideoPlayer videoPlayer = createVideoPlayer();
@@ -177,14 +166,29 @@ public void setPlaybackSpeedSetsPlaybackParametersWithValue() {
   }
 
   @Test
-  public void seekAndGetPosition() {
+  public void seekTo() {
     VideoPlayer videoPlayer = createVideoPlayer();
 
     videoPlayer.seekTo(10L);
     verify(mockExoPlayer).seekTo(10);
 
-    when(mockExoPlayer.getCurrentPosition()).thenReturn(20L);
-    assertEquals(20L, videoPlayer.getPosition().longValue());
+    videoPlayer.dispose();
+  }
+
+  @Test
+  public void getPlaybackState() {
+    VideoPlayer videoPlayer = createVideoPlayer();
+
+    final long playbackPosition = 20L;
+    final long bufferedPosition = 10L;
+    when(mockExoPlayer.getCurrentPosition()).thenReturn(playbackPosition);
+    when(mockExoPlayer.getBufferedPosition()).thenReturn(bufferedPosition);
+
+    final Messages.PlaybackState state = videoPlayer.getPlaybackState();
+    assertEquals(playbackPosition, state.getPlayPosition().longValue());
+    assertEquals(bufferedPosition, state.getBufferPosition().longValue());
+
+    videoPlayer.dispose();
   }
 
   @Test