[video_player] Add forwardBufferDurationMs option by mhmdfathy96 · Pull Request #11950 · flutter/packages

mhmdfathy96 · 2026-06-21T02:39:27Z

Adds an optional forwardBufferDurationMs to VideoPlayerOptions, allowing apps to cap how far ahead of the playback position streamed media is buffered.

Without a cap, players read a long way ahead (ExoPlayer's default target is around 50 seconds, and AVPlayer may fetch a large portion of the file), which wastes user bandwidth when someone seeks away from or abandons playback.

The option mirrors the existing backBufferDurationMs from #11932: the same int? type with an Ms suffix, the same non-negative assertion, and the same doc comment shape. When null or zero, the platform's default buffering behavior is used, so existing behavior is unchanged.

This is the combination PR for the federated change, following Changing federated plugins. It contains all four package changes plus temporary path-based dependency overrides added with make-deps-path-based:

video_player_platform_interface 6.10.0: adds the option to VideoPlayerOptions
video_player_android 2.13.0: caps ExoPlayer's DefaultLoadControl via setBufferDurationsMsForStreaming, so local playback is unaffected
video_player_avfoundation 2.13.0: sets AVPlayerItem.preferredForwardBufferDuration
video_player 2.15.0: raises the implementation constraints to expose the option

The expected CI failures are the checks that reject the temporary overrides, including video_player_web, which carries an override but no code change. Once this is approved, I will split out the platform interface and implementation PRs and then remove the overrides here.

Fixes flutter/flutter#40931
Fixes flutter/flutter#141511

Pre-Review Checklist

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. 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.

Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling. ↩ ↩²

google-cla · 2026-06-21T02:39:45Z

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

gemini-code-assist

Code Review

This pull request adds support for a new forwardBufferDuration option to VideoPlayerOptions and VideoCreationOptions across the video_player packages, allowing users to cap network buffering. The implementation spans the platform interface, Android (ExoPlayer), and iOS/macOS (AVFoundation) implementations, along with corresponding tests. Feedback suggests adding non-negative assertions to the Dart constructors, clamping the duration on Android to prevent integer overflow, and clamping it on iOS/macOS to prevent potential crashes from negative values.

mhmdfathy96 · 2026-06-21T15:46:35Z

Thanks for the review! Addressed in bdc6655:

iOS negative clamp (high): preferredForwardBufferDuration is now max(0.0, …) to avoid the exception on negative values.
Android overflow: cappedLoadControl clamps to Integer.MAX_VALUE before the int cast.
VideoPlayerOptions assert: added the non-negative assertion on the user-facing constructor.
VideoCreationOptions assert: not added — that constructor is const, and Duration.isNegative isn't a const expression. It's only built internally from an already-validated VideoPlayerOptions, so the user-facing assert above covers it.

stuartmorgan-g · 2026-06-23T18:50:54Z

Thank you for your contribution! Because of the volume of PRs we receive, we require that new contributors use our checklist to guide them through critical steps in creating a Flutter PR. This PR's description is missing that checklist, so it is being marked as a Draft.

Please edit the PR description to add the checklist, then ensure that you have completed all of the steps. Once you've done that, please mark the PR as ready for review.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Thanks for the review!

Please make sure in particular to read the AI contribution guidelines carefully. Thanking a clearly labeled bot for doing a review suggests there is not a human in the loop on this response.

tarrinneal · 2026-06-26T04:58:44Z

Please note that a pr regarding buffer size (back buffer) is likely landing soon. #11810
You will want to make sure that the naming conventions and options match the style of this pr (such as naming fields with ms at the end if they are times measured in milliseconds.

Piinks · 2026-09-21T21:59:34Z

Greetings from stale PR triage! 👋
Is this change still on your radar?

mhmdfathy96 · 2026-09-21T22:21:08Z

Still on my radar, yes — sorry for the long silence.

Where I'm picking it up:

tarrinneal — thanks for the heads-up about #11810; it landed while I was away. I'll rebase on top of it and match it: forwardBufferDuration becomes forwardBufferDurationMs (int?, same non-negative assert as backBufferDurationMs), and the forward cap moves into the same DefaultLoadControl.Builder the back buffer already uses, instead of the separate helper I'd added.

stuartmorgan-g — I'll restore the repo's PR template and complete the checklist properly before taking this out of draft.

mhmdfathy96 · 2026-09-22T03:08:34Z

Rebased onto current main and reduced this PR to the platform interface only.

Changes since the last review:

Renamed the option to forwardBufferDurationMs (int?) to match backBufferDurationMs, which landed via [video_player_platform_interface] Improve seek performance on Android #11932 → [video_player_android] Implement backBufferDurationMs in ExoPlayer #12124 → [video_player] Improve seek performance on Android #11810. Thanks tarrinneal for the pointer.
Split into four PRs following that same sequencing, since the implementations need this version published first. The follow-ups are ready: video_player_android (caps ExoPlayer's DefaultLoadControl for streaming), video_player_avfoundation (AVPlayerItem.preferredForwardBufferDuration), then video_player for the constraint bump.
Restored the repo PR template checklist.

This PR is now 4 files: the option, its tests, the CHANGELOG entry and the version bump. null or 0 preserves current behavior on every platform.

gemini-code-assist

Code Review

This pull request adds a new forwardBufferDurationMs option to VideoPlayerOptions in the video_player_platform_interface package to support capping the forward buffer duration. It includes assertions to ensure the value is non-negative, updates the package version to 6.10.0 along with the changelog, and adds unit tests to verify the new option's behavior. There are no review comments, so no additional feedback is provided.

stuartmorgan-g · 2026-09-22T12:11:45Z

Please do not @-reference people in the PR description. That becomes the commit message, and causes a huge amount of notification spam over time for anyone referenced as people sync the commit into their forks.

stuartmorgan-g · 2026-09-22T12:13:30Z

Split into four PRs following that same sequencing, since the implementations need this version published first.

Please re-read the contribution guide section concerning changing federated plugins. We will not review or land individual sub-PRs until the combination PR has been reviewed and approved by all relevant reviewers.

Converting to a draft until this is once again a combination PR that can be reviewed. Once it's ready according to our documented process, please mark it as ready for review.

Adds an optional `forwardBufferDurationMs` to `VideoPlayerOptions`, allowing apps to cap how far ahead of the playback position streamed media is buffered. This mirrors the existing `backBufferDurationMs` option added in flutter#11932, including its non-negative assertion and documentation style. When null or zero, the platform's default buffering behavior is used, so existing behavior is unchanged. Part 1 of 4. Platform implementations follow once this is published. Fixes flutter/flutter#40931 Fixes flutter/flutter#141511

Implements `VideoPlayerOptions.forwardBufferDurationMs` by configuring ExoPlayer's `DefaultLoadControl`, following the back buffer implementation added in flutter#12124. The back buffer and forward buffer options now share a single `VideoPlayer.buildLoadControl` helper, replacing the duplicated load control setup in `TextureVideoPlayer` and `PlatformViewVideoPlayer`. The forward cap uses `setBufferDurationsMsForStreaming`, so local files and assets keep ExoPlayer's defaults. Playback start thresholds are clamped to the cap, since `DefaultLoadControl` requires them to be no larger than the buffer size. Part 2 of 4.

Implements `VideoPlayerOptions.forwardBufferDurationMs` by setting `AVPlayerItem.preferredForwardBufferDuration`. `preferredForwardBufferDuration` is exposed through the `FVPAVPlayerItem` protocol so it can be verified in unit tests. A value of 0 is AVPlayer's "automatic" default, so passing 0 matches leaving the option unset. Negative values are rejected. Part 3 of 4.

Updates the platform implementation constraints to versions that support `VideoPlayerOptions.forwardBufferDurationMs`, exposing the option to apps. `VideoPlayerOptions` is re-exported by this package, so the new field is part of its public API; no other code change is required, as the options object is already forwarded to the platform via `VideoCreationOptions`. This follows the same sequencing the back buffer option used: flutter#11932 (platform interface), flutter#12124 (Android), then flutter#11810 (app-facing). Part 4 of 4.

FOR TESTING AND INITIAL REVIEW ONLY. These overrides are removed as each package is split out and published, per the federated plugin change process.

mhmdfathy96 · 2026-09-25T18:23:59Z

Restored this as the combination PR: all four packages, with path-based dependency overrides from make-deps-path-based. The expected failures are the checks that reject those overrides (including video_player_web, which only carries an override). I'll split out the platform interface and implementation PRs once this is approved.

gemini-code-assist

Code Review

This pull request adds the forwardBufferDurationMs option to VideoPlayerOptions to limit the forward buffer duration for streamed media. The option is implemented for Android using ExoPlayer's LoadControl and for iOS/macOS using AVPlayerItem.preferredForwardBufferDuration. The changes span the platform interface, the main player package, and the Android and AVFoundation platform implementations, accompanied by corresponding unit tests and Pigeon integration updates. No review comments were provided, so there is no feedback to address.

github-actions Bot added platform-android platform-ios platform-macos p: video_player labels Jun 21, 2026

mhmdfathy96 marked this pull request as ready for review June 21, 2026 06:09

gemini-code-assist Bot reviewed Jun 21, 2026

View reviewed changes

mhmdfathy96 force-pushed the video_player_forward_buffer_duration branch from bdc6655 to fd7120c Compare June 21, 2026 16:23

stuartmorgan-g marked this pull request as draft June 23, 2026 18:51

mhmdfathy96 force-pushed the video_player_forward_buffer_duration branch from fd7120c to 4513e4c Compare September 22, 2026 02:12

github-actions Bot removed platform-android platform-ios platform-macos labels Sep 22, 2026

mhmdfathy96 changed the title ~~[video_player] Add forwardBufferDuration to cap network read-ahead~~ [video_player_platform_interface] Add forwardBufferDurationMs Sep 22, 2026

mhmdfathy96 force-pushed the video_player_forward_buffer_duration branch 2 times, most recently from 39469c4 to 4db13a4 Compare September 22, 2026 03:02

mhmdfathy96 marked this pull request as ready for review September 22, 2026 03:13

gemini-code-assist Bot reviewed Sep 22, 2026

View reviewed changes

stuartmorgan-g marked this pull request as draft September 22, 2026 12:13

mhmdfathy96 added 3 commits September 25, 2026 18:24

mhmdfathy96 added 2 commits September 25, 2026 18:24

[video_player] Use path-based dependency overrides for combined review

2420716

FOR TESTING AND INITIAL REVIEW ONLY. These overrides are removed as each package is split out and published, per the federated plugin change process.

mhmdfathy96 force-pushed the video_player_forward_buffer_duration branch from 4db13a4 to 2420716 Compare September 25, 2026 16:08

github-actions Bot added platform-android platform-ios platform-macos platform-web labels Sep 25, 2026

mhmdfathy96 changed the title ~~[video_player_platform_interface] Add forwardBufferDurationMs~~ [video_player] Add forwardBufferDurationMs option Sep 25, 2026

mhmdfathy96 marked this pull request as ready for review September 25, 2026 18:24

gemini-code-assist Bot reviewed Sep 25, 2026

View reviewed changes

Piinks requested a review from tarrinneal September 29, 2026 20:58

Conversation

mhmdfathy96 commented Jun 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-Review Checklist

Footnotes

Uh oh!

google-cla Bot commented Jun 21, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mhmdfathy96 commented Jun 21, 2026

Uh oh!

stuartmorgan-g commented Jun 23, 2026

Uh oh!

tarrinneal commented Jun 26, 2026

Uh oh!

Piinks commented Sep 21, 2026

Uh oh!

mhmdfathy96 commented Sep 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mhmdfathy96 commented Sep 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

stuartmorgan-g commented Sep 22, 2026

Uh oh!

stuartmorgan-g commented Sep 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mhmdfathy96 commented Sep 25, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mhmdfathy96 commented Jun 21, 2026 •

edited

Loading

mhmdfathy96 commented Sep 21, 2026 •

edited

Loading

mhmdfathy96 commented Sep 22, 2026 •

edited

Loading

stuartmorgan-g commented Sep 22, 2026 •

edited

Loading