Add adaptive bitrate streaming support to video_player

Adds setBandwidthLimit() to VideoPlayerController and an internal
AdaptiveBitrateManager that automatically adjusts quality based on
buffering events during HLS/DASH playback.

The AdaptiveBitrateManager:
- Monitors buffering events on a 3-second interval
- Steps down quality (1080p -> 720p -> 480p -> 360p) as buffering increases
- Recovers quality when buffering subsides (0.7x decay per cycle)
- Enforces a 5-second cooldown between quality changes
- Only activates for network data sources

Requires video_player_platform_interface ^6.7.0,
video_player_android ^2.10.0, video_player_avfoundation ^2.10.0.
Fixes flutter/flutter#183941

Author: sheershtehri7

packages/video_player/video_player/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2.12.0
+
+* Adds `setBandwidthLimit` method for adaptive bitrate streaming control.
+* Adds internal `AdaptiveBitrateManager` for automatic quality adjustment based on buffering events.
+
 ## 2.11.1
 
 * Optimizes caption retrieval with binary search.

packages/video_player/video_player/lib/src/adaptive_bitrate_manager.dart

@@ -0,0 +1,129 @@
+import 'dart:async';
+
+import 'package:video_player_platform_interface/video_player_platform_interface.dart';
+
+/// Manages adaptive bitrate selection for HLS/DASH streaming.
+///
+/// Monitors buffering events and adjusts the maximum bandwidth limit
+/// to help the native player select appropriate quality variants.
+///
+/// This acts as a supervisory controller on top of the native player's
+/// own ABR logic (ExoPlayer's [AdaptiveTrackSelection] on Android,
+/// AVFoundation on iOS). It forces quality down via [setBandwidthLimit]
+/// when persistent buffering is detected, and relaxes the limit when
+/// playback stabilizes.
+class AdaptiveBitrateManager {
+  /// Creates an [AdaptiveBitrateManager] for the given [playerId].
+  AdaptiveBitrateManager({
+    required this.playerId,
+    required VideoPlayerPlatform platform,
+  }) : _platform = platform;
+
+  /// The player ID this manager controls.
+  final int playerId;
+  final VideoPlayerPlatform _platform;
+
+  Timer? _monitoringTimer;
+  int _bufferingCount = 0;
+  int _currentBandwidthLimit = qualityUnlimited;
+  DateTime _lastQualityChange = DateTime.now();
+  bool _isMonitoring = false;
+
+  /// Bandwidth cap for 360p quality (~500 kbps).
+  static const int quality360p = 500000;
+
+  /// Bandwidth cap for 480p quality (~800 kbps).
+  static const int quality480p = 800000;
+
+  /// Bandwidth cap for 720p quality (~1.2 Mbps).
+  static const int quality720p = 1200000;
+
+  /// Bandwidth cap for 1080p quality (~2.5 Mbps).
+  static const int quality1080p = 2500000;
+
+  /// No bandwidth limit — lets the native player choose freely.
+  static const int qualityUnlimited = 0;
+
+  static const Duration _monitorInterval = Duration(seconds: 3);
+  static const Duration _qualityChangeCooldown = Duration(seconds: 5);
+
+  /// Buffering count decay factor applied each monitoring cycle.
+  ///
+  /// This allows recovery to higher quality after transient buffering.
+  static const double _bufferingDecayFactor = 0.7;
+
+  /// Starts automatic quality monitoring and adjustment.
+  ///
+  /// Removes any existing bandwidth limit and begins periodic analysis.
+  /// Safe to call multiple times — subsequent calls are no-ops.
+  Future<void> startAutoAdaptiveQuality() async {
+    if (_isMonitoring) {
+      return;
+    }
+    _isMonitoring = true;
+
+    try {
+      await _platform.setBandwidthLimit(playerId, qualityUnlimited);
+    } catch (e) {
+      _isMonitoring = false;
+      return;
+    }
+
+    _monitoringTimer = Timer.periodic(_monitorInterval, (_) {
+      _analyzeAndAdjust();
+    });
+  }
+
+  /// Records a buffering event from the player.
+  ///
+  /// Called by [VideoPlayerController] when a [bufferingStart] event occurs.
+  void recordBufferingEvent() {
+    if (_isMonitoring) {
+      _bufferingCount++;
+    }
+  }
+
+  /// Analyzes recent buffering history and adjusts the bandwidth limit.
+  Future<void> _analyzeAndAdjust() async {
+    if (DateTime.now().difference(_lastQualityChange) <
+        _qualityChangeCooldown) {
+      return;
+    }
+
+    final int newLimit = _selectOptimalBandwidth();
+
+    // Apply decay so transient buffering doesn't permanently pin quality low.
+    _bufferingCount = (_bufferingCount * _bufferingDecayFactor).floor();
+
+    if (newLimit != _currentBandwidthLimit) {
+      try {
+        await _platform.setBandwidthLimit(playerId, newLimit);
+        _currentBandwidthLimit = newLimit;
+        _lastQualityChange = DateTime.now();
+      } catch (e) {
+        // Silently ignore errors during auto-adjustment.
+      }
+    }
+  }
+
+  /// Selects optimal bandwidth based on recent buffering frequency.
+  int _selectOptimalBandwidth() {
+    if (_bufferingCount > 5) {
+      return quality360p;
+    }
+    if (_bufferingCount > 2) {
+      return quality480p;
+    }
+    if (_bufferingCount > 0) {
+      return quality720p;
+    }
+    return qualityUnlimited;
+  }
+
+  /// Stops monitoring and releases resources.
+  void dispose() {
+    _isMonitoring = false;
+    _monitoringTimer?.cancel();
+    _monitoringTimer = null;
+  }
+}

packages/video_player/video_player/lib/video_player.dart

@@ -13,6 +13,7 @@ import 'package:flutter/services.dart';
 import 'package:video_player_platform_interface/video_player_platform_interface.dart'
     as platform_interface;
 
+import 'src/adaptive_bitrate_manager.dart';
 import 'src/closed_caption_file.dart';
 
 export 'package:video_player_platform_interface/video_player_platform_interface.dart'
@@ -524,6 +525,7 @@ class VideoPlayerController extends ValueNotifier<VideoPlayerValue> {
   Completer<void>? _creatingCompleter;
   StreamSubscription<dynamic>? _eventSubscription;
   _VideoAppLifeCycleObserver? _lifeCycleObserver;
+  AdaptiveBitrateManager? _adaptiveBitrateManager;
 
   /// The id of a player that hasn't been initialized.
   @visibleForTesting
@@ -588,6 +590,17 @@ class VideoPlayerController extends ValueNotifier<VideoPlayerValue> {
         (await _videoPlayerPlatform.createWithOptions(creationOptions)) ??
         kUninitializedPlayerId;
     _creatingCompleter!.complete(null);
+
+    // Enable adaptive bitrate management only for network streams
+    // (local files and assets don't use HLS/DASH adaptive streaming).
+    if (dataSourceType == platform_interface.DataSourceType.network) {
+      _adaptiveBitrateManager = AdaptiveBitrateManager(
+        playerId: _playerId,
+        platform: _videoPlayerPlatform,
+      );
+      await _adaptiveBitrateManager!.startAutoAdaptiveQuality();
+    }
+
     final initializingCompleter = Completer<void>();
 
     // Apply the web-specific options
@@ -638,6 +651,7 @@ class VideoPlayerController extends ValueNotifier<VideoPlayerValue> {
           value = value.copyWith(buffered: event.buffered);
         case platform_interface.VideoEventType.bufferingStart:
           value = value.copyWith(isBuffering: true);
+          _adaptiveBitrateManager?.recordBufferingEvent();
         case platform_interface.VideoEventType.bufferingEnd:
           value = value.copyWith(isBuffering: false);
         case platform_interface.VideoEventType.isPlayingStateUpdate:
@@ -684,6 +698,7 @@ class VideoPlayerController extends ValueNotifier<VideoPlayerValue> {
       if (!_isDisposed) {
         _isDisposed = true;
         _timer?.cancel();
+        _adaptiveBitrateManager?.dispose();
         await _eventSubscription?.cancel();
         await _videoPlayerPlatform.dispose(_playerId);
       }
@@ -850,6 +865,44 @@ class VideoPlayerController extends ValueNotifier<VideoPlayerValue> {
     await _applyPlaybackSpeed();
   }
 
+  /// Sets the bandwidth limit for HLS adaptive bitrate streaming.
+  ///
+  /// This method limits the maximum bandwidth used for video playback,
+  /// which affects which HLS variant streams the player can select.
+  ///
+  /// The native player will only select video variants with bitrate
+  /// less than or equal to the specified [maxBandwidthBps].
+  ///
+  /// Platforms:
+  /// - **Android**: Uses ExoPlayer's DefaultTrackSelector.setMaxVideoBitrate()
+  /// - **iOS/macOS**: Uses AVPlayer's preferredPeakBitRate property
+  /// - **Web**: Not supported (no-op)
+  ///
+  /// Parameters:
+  /// - [maxBandwidthBps]: Maximum bandwidth in bits per second.
+  ///   * 0 or negative: No limit (player auto-selects)
+  ///   * Positive value: Player selects variants ≤ this bandwidth
+  ///
+  /// Example:
+  /// ```dart
+  /// // Limit to 720p quality (~1.2 Mbps)
+  /// await controller.setBandwidthLimit(1200000);
+  ///
+  /// // No limit - let player decide
+  /// await controller.setBandwidthLimit(0);
+  /// ```
+  ///
+  /// Note: This is useful for HLS streams where you want to control
+  /// quality selection without reinitializing the player. The player
+  /// will seamlessly switch to appropriate variants as bandwidth
+  /// changes within the limit.
+  Future<void> setBandwidthLimit(int maxBandwidthBps) async {
+    if (_isDisposedOrNotInitialized) {
+      return;
+    }
+    await _videoPlayerPlatform.setBandwidthLimit(_playerId, maxBandwidthBps);
+  }
+
   /// Sets the caption offset.
   ///
   /// The [offset] will be used when getting the correct caption for a specific position.

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,9 +26,9 @@ 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_android: ^2.10.0
+  video_player_avfoundation: ^2.10.0
+  video_player_platform_interface: ^6.7.0
   video_player_web: ^2.1.0
 
 dev_dependencies:

packages/video_player/video_player/test/video_player_test.dart

@@ -130,6 +130,9 @@ class FakeController extends ValueNotifier<VideoPlayerValue>
     return true;
   }
 
+  @override
+  Future<void> setBandwidthLimit(int maxBandwidthBps) async {}
+
   String? selectedAudioTrackId;
 }
 
@@ -1106,6 +1109,34 @@ void main() {
       });
     });
 
+    group('setBandwidthLimit', () {
+      test('delegates to platform', () async {
+        final controller = VideoPlayerController.networkUrl(_localhostUri);
+        addTearDown(controller.dispose);
+        await controller.initialize();
+
+        await controller.setBandwidthLimit(5000000);
+
+        expect(fakeVideoPlayerPlatform.calls, contains('setBandwidthLimit'));
+        expect(
+          fakeVideoPlayerPlatform.bandwidthLimits[controller.playerId],
+          5000000,
+        );
+      });
+
+      test('does nothing when not initialized', () async {
+        final controller = VideoPlayerController.networkUrl(_localhostUri);
+        addTearDown(controller.dispose);
+
+        await controller.setBandwidthLimit(5000000);
+
+        expect(
+          fakeVideoPlayerPlatform.calls,
+          isNot(contains('setBandwidthLimit')),
+        );
+      });
+    });
+
     group('caption', () {
       test('works when position updates', () async {
         final controller = VideoPlayerController.networkUrl(
@@ -2289,4 +2320,12 @@ class FakeVideoPlayerPlatform extends VideoPlayerPlatform {
   }
 
   final Map<int, String> selectedAudioTrackIds = <int, String>{};
+
+  @override
+  Future<void> setBandwidthLimit(int playerId, int maxBandwidthBps) async {
+    calls.add('setBandwidthLimit');
+    bandwidthLimits[playerId] = maxBandwidthBps;
+  }
+
+  final Map<int, int> bandwidthLimits = <int, int>{};
 }