[video_player] Add forwardBufferDuration to cap network read-ahead

[mhmdfathy96]

Description

Adds an optional VideoPlayerOptions.forwardBufferDuration so apps can cap how
far ahead of the playhead the player buffers from the network.

Today buffering is fully automatic and aggressive — ExoPlayer's DefaultLoadControl
buffers ~50s, and AVPlayer can prefetch most of a short file on iOS. That wastes
bandwidth whenever a user abandons a video or seeks away. This has been requested
for years without an implementation:

• [video_player] add buffering controls flutter#40931 (2019)
• [video_player] specify buffer sizes flutter#141511
• [video_player]Need to clarify the design philosophy of buffering control in video_player flutter#163918

VideoPlayerController.networkUrl(
  uri,
  videoPlayerOptions: VideoPlayerOptions(
    forwardBufferDuration: const Duration(seconds: 10), // null = unchanged default
  ),
);

The option is threaded through VideoCreationOptions and the pigeon
CreationOptions to the engines:

• Android → ExoPlayer DefaultLoadControl (VideoPlayer.cappedLoadControl,
  with playback-start thresholds clamped to the cap).
• iOS/macOS → AVPlayerItem.preferredForwardBufferDuration (exposed via the
  FVPAVPlayerItem test abstraction).

null preserves current behavior on every platform.

Tests

• Dart: umbrella forwards the option into VideoCreationOptions; android &
  avfoundation pass forwardBufferDurationMs and default to null.
• Android native (Robolectric): cappedLoadControl null/non-null + small-cap
  threshold clamping.
• iOS native (swift-testing): the value is applied to the player item and left
  untouched when null.

All pass locally.

Pre-Review Checklist

• I signed the CLA.
• Unit tests (Dart + Android + iOS) added and passing locally.
• Added/updated CHANGELOG and version bumps for all four packages.
• Listed issues fixed above.
• Verify generated pigeon files match dart run pigeon with the repo's pinned
  toolchain (generated files were edited by hand to keep a minimal diff;
  flagging for the CI generated-code check).

[google-cla]

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.

[gemini-code-assist]

If forwardBufferDurationMs is negative, preferredForwardBufferDuration will be set to a negative value. According to Apple's documentation, setting preferredForwardBufferDuration to a negative value raises an exception and will crash the app. We should clamp the value to be at least 0.0 to prevent crashes.

Suggested change

	item.preferredForwardBufferDuration = Double(forwardBufferDurationMs) / 1000.0
	item.preferredForwardBufferDuration = max(0.0, Double(forwardBufferDurationMs) / 1000.0)

[gemini-code-assist]

If forwardBufferDurationMs is extremely large (e.g., greater than Integer.MAX_VALUE), casting it directly to int will cause an integer overflow, resulting in a negative value or unexpected behavior in DefaultLoadControl. We should clamp the value to Integer.MAX_VALUE before casting to ensure robustness.

Suggested change

	int bufferMs = (int) Math.max(1L, forwardBufferDurationMs);
	int bufferMs = (int) Math.min((long) Integer.MAX_VALUE, Math.max(1L, forwardBufferDurationMs));

[gemini-code-assist]

To prevent negative durations from being passed to the platform channels, we should add an assertion in the VideoPlayerOptions constructor to ensure forwardBufferDuration is non-negative.

Suggested change

	this.mixWithOthers = false,
	this.allowBackgroundPlayback = false,
	this.webOptions,
	this.forwardBufferDuration,
	});
	this.mixWithOthers = false,
	this.allowBackgroundPlayback = false,
	this.webOptions,
	this.forwardBufferDuration,
	}) : assert(forwardBufferDuration == null || !forwardBufferDuration.isNegative, 'forwardBufferDuration must be non-negative.');

[gemini-code-assist]

Similarly, we should add an assertion in the VideoCreationOptions constructor to ensure forwardBufferDuration is non-negative.

Suggested change

	const VideoCreationOptions({
	required this.dataSource,
	required this.viewType,
	this.forwardBufferDuration,
	});
	const VideoCreationOptions({
	required this.dataSource,
	required this.viewType,
	this.forwardBufferDuration,
	}) : assert(forwardBufferDuration == null || !forwardBufferDuration.isNegative, 'forwardBufferDuration must be non-negative.');