Merge branch 'feature/offload' into minor

Author: ryanheise

just_audio/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.10.5
+
+* Disable Android audio offload by default to prevent playback issues.
+* Add androidAudioOffloadPreferences.
+* Deprecate androidOffloadSchedulingEnabled.
+
 ## 0.10.4
 
 * Fix bug on simultaneous loads.

just_audio/README.md

@@ -25,7 +25,7 @@ await player.stop();                            // Stop and free resources
 
 ### Migrating to 0.10.x
 
-* iOS: You may remove the compile flag `AUDIO_SESSION_MICROPHONE=0` since this is now the default.
+* iOS: As of audio_session 0.2.x, you may remove the compile flag `AUDIO_SESSION_MICROPHONE=0` as this is now the default.
 * Instead of `player.setAudioSource(ConcatenatingAudioSource(children: sources))` use `player.setAudioSources(sources)`.
 * Instead of `LoopingAudioSource(child: source, count: N)` use `...List.filled(N, source)`.
 * Instead of listening to `player.playbackEventStream.onError`, listen to `player.errorStream`.

just_audio/android/src/main/java/com/ryanheise/just_audio/AudioPlayer.java

@@ -96,6 +96,7 @@ public class AudioPlayer implements MethodCallHandler, Player.Listener, Metadata
     private AudioAttributes pendingAudioAttributes;
     private LoadControl loadControl;
     private boolean offloadSchedulingEnabled;
+    private AudioOffloadPreferences audioOffloadPreferences;
     private boolean useLazyPreparation;
     private LivePlaybackSpeedControl livePlaybackSpeedControl;
     private List<Object> rawAudioEffects;
@@ -145,13 +146,32 @@ public AudioPlayer(
         final String id,
         Map<?, ?> audioLoadConfiguration,
         List<Object> rawAudioEffects,
+        Map<?, ?> audioOffloadPreferences,
         Boolean offloadSchedulingEnabled,
         boolean useLazyPreparation
     ) {
         this.context = applicationContext;
         this.rawAudioEffects = rawAudioEffects;
         this.offloadSchedulingEnabled = offloadSchedulingEnabled != null ? offloadSchedulingEnabled : false;
         this.useLazyPreparation = useLazyPreparation;
+
+        if (audioOffloadPreferences != null) {
+            this.audioOffloadPreferences = new AudioOffloadPreferences.Builder()
+                .setIsGaplessSupportRequired((Boolean)audioOffloadPreferences.get("isGaplessSupportRequired"))
+                .setIsSpeedChangeSupportRequired((Boolean)audioOffloadPreferences.get("isSpeedChangeSupportRequired"))
+                .setAudioOffloadMode((Integer)audioOffloadPreferences.get("audioOffloadMode"))
+                .build();
+        } else {
+            final int offloadMode = offloadSchedulingEnabled
+                ? AudioOffloadPreferences.AUDIO_OFFLOAD_MODE_ENABLED
+                : AudioOffloadPreferences.AUDIO_OFFLOAD_MODE_DISABLED;
+            this.audioOffloadPreferences = new AudioOffloadPreferences.Builder()
+                .setIsGaplessSupportRequired(!offloadSchedulingEnabled)
+                .setIsSpeedChangeSupportRequired(!offloadSchedulingEnabled)
+                .setAudioOffloadMode(offloadMode)
+                .build();
+        }
+
         methodChannel = new MethodChannel(messenger, "com.ryanheise.just_audio.methods." + id);
         methodChannel.setMethodCallHandler(this);
         eventChannel = new BetterEventChannel(messenger, "com.ryanheise.just_audio.events." + id);
@@ -772,27 +792,10 @@ private void ensurePlayerInitialized() {
                 builder.setLivePlaybackSpeedControl(livePlaybackSpeedControl);
             }
             player = builder.build();
-            // The latest ExoPlayer enables offload scheduling by default but
-            // it doesn't support gapless playback below SDK level 33 or speec
-            // changing. To maintain backwards compatibility within just_audio,
-            // we set gapless playback and speed changing support as required,
-            // and let ExoPlayer choose whether it can enable offload
-            // scheduling depending on device support. If the app passes in
-            // androidOffloadSchedulingEnabled: true, we simply remove these
-            // requirements which may prevent gapless and speed changing from
-            // working, but will allow offload to work. A future release may
-            // expose more parameters to the app concerning offloading
-            // preferences.
             player.setTrackSelectionParameters(
                 player.getTrackSelectionParameters()
                     .buildUpon()
-                    .setAudioOffloadPreferences(
-                        new AudioOffloadPreferences.Builder()
-                            .setIsGaplessSupportRequired(!offloadSchedulingEnabled)
-                            .setIsSpeedChangeSupportRequired(!offloadSchedulingEnabled)
-                            .setAudioOffloadMode(AudioOffloadPreferences.AUDIO_OFFLOAD_MODE_ENABLED)
-                            .build()
-                    )
+                    .setAudioOffloadPreferences(audioOffloadPreferences)
                     .build()
             );
             setAudioSessionId(player.getAudioSessionId());

just_audio/android/src/main/java/com/ryanheise/just_audio/MainMethodCallHandler.java

@@ -42,6 +42,7 @@ public void onMethodCall(MethodCall call, @NonNull Result result) {
                     id,
                     call.argument("audioLoadConfiguration"),
                     rawAudioEffects,
+                    call.argument("androidAudioOffloadPreferences"),
                     call.argument("androidOffloadSchedulingEnabled"),
 		    call.argument("useLazyPreparation")
                 )

just_audio/lib/just_audio.dart

@@ -70,6 +70,8 @@ class AudioPlayer {
 
   final bool _androidOffloadSchedulingEnabled;
 
+  final AndroidAudioOffloadPreferences? _androidAudioOffloadPreferences;
+
   /// This is `true` when the audio player needs to engage the native platform
   /// side of the plugin to decode or play audio, and is `false` when the native
   /// resources are not needed (i.e. after initial instantiation and after [stop]).
@@ -231,13 +233,18 @@ class AudioPlayer {
   /// next audio source on load errors, and will give up after [maxSkipsOnError]
   /// attempts. This is supported on Android, iOS and web. For other platforms,
   /// check the documentation of the respective platform implementation.
+  ///
+  /// [androidAudioOffloadPreferences] specifies whether audio offload is enabled
+  /// on Android.
   AudioPlayer({
     String? userAgent,
     bool handleInterruptions = true,
     bool androidApplyAudioAttributes = true,
     bool handleAudioSessionActivation = true,
     AudioLoadConfiguration? audioLoadConfiguration,
     AudioPipeline? audioPipeline,
+    AndroidAudioOffloadPreferences? androidAudioOffloadPreferences,
+    @Deprecated('Use androidAudioOffloadPreferences instead')
     bool androidOffloadSchedulingEnabled = false,
     bool useProxyForRequestHeaders = true,
     bool useLazyPreparation = true,
@@ -251,6 +258,7 @@ class AudioPlayer {
         _audioLoadConfiguration = audioLoadConfiguration,
         _audioPipeline = audioPipeline ?? AudioPipeline(),
         _androidOffloadSchedulingEnabled = androidOffloadSchedulingEnabled,
+        _androidAudioOffloadPreferences = androidAudioOffloadPreferences,
         _useProxyForRequestHeaders = useProxyForRequestHeaders,
         // ignore: deprecated_member_use_from_same_package
         _playlist = ConcatenatingAudioSource._playlist(
@@ -1640,6 +1648,8 @@ class AudioPlayer {
                     : [],
                 androidOffloadSchedulingEnabled:
                     _androidOffloadSchedulingEnabled,
+                androidAudioOffloadPreferences:
+                    _androidAudioOffloadPreferences?._toMessage(),
                 useLazyPreparation: _playlist.useLazyPreparation,
               )))
             : (_idlePlatform = _IdleAudioPlayer(
@@ -2360,6 +2370,47 @@ class AndroidLivePlaybackSpeedControl {
       );
 }
 
+/// Audio offload modes for Android.
+enum AndroidAudioOffloadMode { disabled, enabled }
+
+/// Audio offload preferences for Android.
+///
+/// IMPORTANT: activation of audio offload depends on a negotiation between
+/// ExoPlayer and the device to determine whether offload can be supported for a
+/// given format and with given constraints (gapless, speed change). However,
+/// several instances have been reported where the device incorrectly confirms
+/// support for audio offload when it doesn't, and this can result in buggy
+/// audio playback. Therefore, it is advised that you programmatically enable
+/// audio offload only on device/OS combinations that you have tested and
+/// verified to work.
+class AndroidAudioOffloadPreferences {
+  /// The preferred audio offload mode.
+  final AndroidAudioOffloadMode audioOffloadMode;
+
+  /// Constrains enablement of audio offload to happen only if the device
+  /// can fulfill any gapless transitions that might exist in the playlist
+  /// during offload.
+  final bool isGaplessSupportRequired;
+
+  /// Constrains enablement of audio offload to happen only if the device
+  /// can fulfill any speed change request during offload.
+  final bool isSpeedChangeSupportRequired;
+
+  const AndroidAudioOffloadPreferences({
+    this.audioOffloadMode = AndroidAudioOffloadMode.disabled,
+    this.isGaplessSupportRequired = false,
+    this.isSpeedChangeSupportRequired = false,
+  });
+
+  AndroidAudioOffloadPreferencesMessage _toMessage() =>
+      AndroidAudioOffloadPreferencesMessage(
+        audioOffloadMode:
+            AndroidAudioOffloadModeMessage.values[audioOffloadMode.index],
+        isGaplessSupportRequired: isGaplessSupportRequired,
+        isSpeedChangeSupportRequired: isSpeedChangeSupportRequired,
+      );
+}
+
 class ProgressiveAudioSourceOptions {
   final AndroidExtractorOptions? androidExtractorOptions;
   final DarwinAssetOptions? darwinAssetOptions;

just_audio/pubspec.yaml

@@ -1,6 +1,6 @@
 name: just_audio
 description: A feature-rich audio player for Flutter. Loop, clip and sequence any sound from any source (asset/file/URL/stream) in gapless playlists.
-version: 0.10.4
+version: 0.10.5
 repository: https://github.com/ryanheise/just_audio/tree/minor/just_audio
 issue_tracker: https://github.com/ryanheise/just_audio/issues
 topics:
@@ -14,7 +14,7 @@ environment:
   flutter: ">=3.27.0"
 
 dependencies:
-  just_audio_platform_interface: ^4.5.0
+  just_audio_platform_interface: ^4.6.0
   # just_audio_platform_interface:
   #   path: ../just_audio_platform_interface
   just_audio_web: ^0.4.15

just_audio_platform_interface/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 4.6.0
+
+* Add androidAudioOffloadPreferences.
+
 ## 4.5.0
 
 * Add errorCode/errorMessage to PlaybackEventMessage.

just_audio_platform_interface/lib/just_audio_platform_interface.dart

@@ -413,6 +413,8 @@ class InitRequest {
   final AudioLoadConfigurationMessage? audioLoadConfiguration;
   final List<AudioEffectMessage> androidAudioEffects;
   final List<AudioEffectMessage> darwinAudioEffects;
+
+  final AndroidAudioOffloadPreferencesMessage? androidAudioOffloadPreferences;
   final bool? androidOffloadSchedulingEnabled;
   final bool useLazyPreparation;
 
@@ -421,6 +423,7 @@ class InitRequest {
     this.audioLoadConfiguration,
     this.androidAudioEffects = const [],
     this.darwinAudioEffects = const [],
+    this.androidAudioOffloadPreferences,
     this.androidOffloadSchedulingEnabled,
     this.useLazyPreparation = true,
   });
@@ -434,6 +437,8 @@ class InitRequest {
         'darwinAudioEffects': darwinAudioEffects
             .map((audioEffect) => audioEffect.toMap())
             .toList(),
+        'androidAudioOffloadPreferences':
+            androidAudioOffloadPreferences?.toMap(),
         'androidOffloadSchedulingEnabled': androidOffloadSchedulingEnabled,
         'useLazyPreparation': useLazyPreparation,
       };
@@ -1055,6 +1060,29 @@ class AndroidLivePlaybackSpeedControlMessage {
       };
 }
 
+/// The loop mode communicated to the platform implementation.
+enum AndroidAudioOffloadModeMessage { disabled, enabled }
+
+/// Information communicated to the platform implementation when setting the
+/// audio offload preferences.
+class AndroidAudioOffloadPreferencesMessage {
+  final AndroidAudioOffloadModeMessage audioOffloadMode;
+  final bool isGaplessSupportRequired;
+  final bool isSpeedChangeSupportRequired;
+
+  AndroidAudioOffloadPreferencesMessage({
+    required this.audioOffloadMode,
+    required this.isGaplessSupportRequired,
+    required this.isSpeedChangeSupportRequired,
+  });
+
+  Map<dynamic, dynamic> toMap() => <dynamic, dynamic>{
+        'audioOffloadMode': audioOffloadMode.index,
+        'isGaplessSupportRequired': isGaplessSupportRequired,
+        'isSpeedChangeSupportRequired': isSpeedChangeSupportRequired,
+      };
+}
+
 /// Progressive audio source options to be communicated with the platform
 /// implementation.
 class ProgressiveAudioSourceOptionsMessage {

just_audio_platform_interface/pubspec.yaml

@@ -3,7 +3,7 @@ description: A common platform interface for the just_audio plugin. Different pl
 homepage: https://github.com/ryanheise/just_audio/tree/master/just_audio_platform_interface
 # NOTE: We strongly prefer non-breaking changes, even at the expense of a
 # less-clean API. See https://flutter.dev/go/platform-interface-breaking-changes
-version: 4.5.0
+version: 4.6.0
 
 dependencies:
   flutter: