feat(android): ExoPlayer for Android (#1691)

# Description

Closes #1526

Author: Gustl22

.github/workflows/test.yml

@@ -208,9 +208,9 @@ jobs:
         # Need to execute lib and app tests one by one, see: https://github.com/flutter/flutter/issues/101031
         run: |
           ( cd server; dart run bin/server.dart ) &
-          flutter test integration_test/platform_test.dart --dart-define USE_LOCAL_SERVER=true --dart-define TEST_FEATURE_BYTES_SOURCE=false --dart-define TEST_FEATURE_PLAYBACK_RATE=false
-          flutter test integration_test/lib_test.dart --dart-define USE_LOCAL_SERVER=true --dart-define TEST_FEATURE_BYTES_SOURCE=false --dart-define TEST_FEATURE_PLAYBACK_RATE=false
-          flutter test integration_test/app_test.dart --dart-define USE_LOCAL_SERVER=true --dart-define TEST_FEATURE_BYTES_SOURCE=false --dart-define TEST_FEATURE_PLAYBACK_RATE=false
+          flutter test integration_test/platform_test.dart --dart-define USE_LOCAL_SERVER=true --dart-define TEST_FEATURE_LOW_LATENCY=false --dart-define TEST_FEATURE_BYTES_SOURCE=false --dart-define TEST_FEATURE_PLAYBACK_RATE=false
+          flutter test integration_test/lib_test.dart --dart-define USE_LOCAL_SERVER=true --dart-define TEST_FEATURE_LOW_LATENCY=false --dart-define TEST_FEATURE_BYTES_SOURCE=false --dart-define TEST_FEATURE_PLAYBACK_RATE=false
+          flutter test integration_test/app_test.dart --dart-define USE_LOCAL_SERVER=true --dart-define TEST_FEATURE_LOW_LATENCY=false --dart-define TEST_FEATURE_BYTES_SOURCE=false --dart-define TEST_FEATURE_PLAYBACK_RATE=false
 
   android:
     runs-on: ubuntu-latest
@@ -231,9 +231,9 @@ jobs:
         # Need to execute lib and app tests one by one, see: https://github.com/flutter/flutter/issues/101031
         run: |
           ( cd server; dart run bin/server.dart ) &
-          flutter test integration_test/platform_test.dart --dart-define USE_LOCAL_SERVER=true
-          flutter test integration_test/lib_test.dart --dart-define USE_LOCAL_SERVER=true
-          flutter test integration_test/app_test.dart --dart-define USE_LOCAL_SERVER=true
+          flutter test integration_test/platform_test.dart --dart-define USE_LOCAL_SERVER=true --dart-define TEST_FEATURE_LOW_LATENCY=false
+          flutter test integration_test/lib_test.dart --dart-define USE_LOCAL_SERVER=true --dart-define TEST_FEATURE_LOW_LATENCY=false
+          flutter test integration_test/app_test.dart --dart-define USE_LOCAL_SERVER=true --dart-define TEST_FEATURE_LOW_LATENCY=false
       - name: Run Android unit tests
         working-directory: ./packages/audioplayers/example/android
         run: ./gradlew test

feature_parity_table.md

@@ -4,9 +4,28 @@ Not every feature is available on every platform yet. Use this table to keep tra
 
 If you would like to assist us implement a missing feature, please browse the [issue tracker](https://github.com/bluefireteam/audioplayers/issues) and reach out to us on our [Discord](https://discord.gg/pxrBmy4) server so we can coordinate efforts.
 
-## Note on Android Support
+## Note on Android
 
-Giving support to old Android devices is very hard, on this plugin we set the minSdk as 16, but we only ensure support >= 23 as that is the minimum version that the team has devices available to test changes and new features.
+### Media3 ExoPlayer
+
+We are going to switch from the internal [Android MediaPlayer](https://developer.android.com/reference/android/media/MediaPlayer) to the recommended [Media3 ExoPlayer](https://developer.android.com/media/media3).
+We still endorse the old media player until we are sure, the Media3 implementation fulfills all the needs.
+
+You already can try the Media3 implementation by adding `audioplayers_android_exo` to your apps `pubspec.yaml`.
+This [overrides](https://docs.flutter.dev/packages-and-plugins/developing-packages#non-endorsed-federated-plugin) our endorsed Android plugin implementation `audioplayers_android`:
+
+```yaml
+dependencies:
+  # ...
+  audioplayers: any
+  audioplayers_android_exo: any
+```
+
+For more, see the [audioplayers_android_exo](https://github.com/bluefireteam/audioplayers/blob/main/packages/audioplayers_android_exo/README.md) package.
+
+### Support for old SDKs
+
+Giving support to old Android devices is very hard, on this plugin we set the minSdk as 19, but we only ensure support >= 23 as that is the minimum version that the team has devices available to test changes and new features.
 
 This mean that, audioplayers should work on older devices, but we can't give any guarantees, we will not be able to look after issues regarding API < 23. But we would gladly take any pull requests from the community that fixes or improve support on those old versions.
 
@@ -35,7 +54,7 @@ Note: LLM means Low Latency Mode.
         <tr><td colspan="7"><strong>Audio Config</strong></td></tr>
         <tr><td>set url</td><td>yes</td><td>yes</td><td>yes</td><td>yes</td><td>yes</td><td>yes</td></tr>
         <tr><td>audio cache (pre-load)</td><td>yes</td><td>yes</td><td>yes</td><td>yes</td><td>yes</td><td>yes</td></tr>
-        <tr><td>low latency mode</td><td>SDK >=21</td><td>no</td><td>no</td><td>no</td><td>no</td><td>no</td></tr>
+        <tr><td>low latency mode</td><td>SDK >=21 (except `audioplayers_android_exo`) </td><td>no</td><td>no</td><td>no</td><td>no</td><td>no</td></tr>
         <tr><td colspan="7"><strong>Audio Control Commands</strong></td></tr>
         <tr><td>resume / pause / stop</td><td>yes</td><td>yes</td><td>yes</td><td>yes</td><td>yes</td><td>yes</td></tr>
         <tr><td>release</td><td>yes</td><td>yes</td><td>yes</td><td>yes</td><td>yes</td><td>yes</td></tr>

packages/audioplayers/example/integration_test/lib_test.dart

@@ -398,6 +398,6 @@ void main() async {
         await player.stop();
       });
     },
-    skip: !isAndroid,
+    skip: !features.hasLowLatency,
   );
 }

packages/audioplayers/example/integration_test/platform_features.dart

@@ -10,6 +10,11 @@ const testFeaturePlaybackRate = bool.fromEnvironment(
   defaultValue: true,
 );
 
+const testFeatureLowLatency = bool.fromEnvironment(
+  'TEST_FEATURE_LOW_LATENCY',
+  defaultValue: true,
+);
+
 /// Specify supported features for a platform.
 class PlatformFeatures {
   static const webPlatformFeatures = PlatformFeatures(
@@ -30,6 +35,8 @@ class PlatformFeatures {
     hasBytesSource: testFeatureBytesSource,
     // ignore: avoid_redundant_argument_values
     hasPlaybackRate: testFeaturePlaybackRate,
+    // ignore: avoid_redundant_argument_values
+    hasLowLatency: testFeatureLowLatency,
   );
 
   static const iosPlatformFeatures = PlatformFeatures(

packages/audioplayers/example/integration_test/platform_test.dart

@@ -118,7 +118,10 @@ void main() async {
             platform: platform,
             testData: td,
           );
-          expect(await platform.getCurrentPosition(playerId), 0);
+          if (!td.isLiveStream) {
+            // Live stream position is not aligned yet.
+            expect(await platform.getCurrentPosition(playerId), 0);
+          }
           final durationMs = await platform.getDuration(playerId);
           expect(
             durationMs != null ? Duration(milliseconds: durationMs) : null,

packages/audioplayers/example/lib/tabs/sources.dart

@@ -23,7 +23,7 @@ final mp3Url1 = '$host/files/audio/ambient_c_motion.mp3';
 final mp3Url2 = '$host/files/audio/nasa_on_a_mission.mp3';
 final m3u8StreamUrl = useLocalServer
     ? '$host/files/live_streams/nasa_power_of_the_rovers.m3u8'
-    : 'https://a.files.bbci.co.uk/media/live/manifesto/audio/simulcast/hls/nonuk/sbr_low/ak/bbc_world_service.m3u8';
+    : 'https://ll-hls-test.cdn-apple.com/llhls4/ll-hls-test-04/multi.m3u8';
 final mpgaStreamUrl = useLocalServer
     ? '$host/stream/mpeg'
     : 'https://timesradio.wireless.radio/stream';
@@ -150,7 +150,7 @@ class _SourcesTabState extends State<SourcesTab>
         _createSourceTile(
           setSourceKey: const Key('setSource-url-remote-m3u8'),
           title: 'Remote URL M3U8',
-          subtitle: 'BBC stream',
+          subtitle: 'HLS Low-Latency Live Stream',
           source: UrlSource(m3u8StreamUrl),
         ),
         _createSourceTile(

packages/audioplayers/example/pubspec.yaml

@@ -4,6 +4,7 @@ publish_to: none
 
 dependencies:
   audioplayers: ^6.2.0
+  audioplayers_android_exo: ^0.1.0
   collection: ^1.16.0
   file_picker: ^8.0.3
   flutter:

…audioplayers/player/MediaPlayerPlayer.kt …udioplayers/player/MediaPlayerWrapper.ktpackages/audioplayers_android/android/src/main/kotlin/xyz/luan/audioplayers/player/MediaPlayerPlayer.kt renamed to packages/audioplayers_android/android/src/main/kotlin/xyz/luan/audioplayers/player/MediaPlayerWrapper.kt packages/audioplayers_android/android/src/main/kotlin/xyz/luan/audioplayers/player/MediaPlayerPlayer.kt renamed to packages/audioplayers_android/android/src/main/kotlin/xyz/luan/audioplayers/player/MediaPlayerWrapper.kt

@@ -6,9 +6,9 @@ import android.os.PowerManager
 import xyz.luan.audioplayers.AudioContextAndroid
 import xyz.luan.audioplayers.source.Source
 
-class MediaPlayerPlayer(
+class MediaPlayerWrapper(
     private val wrappedPlayer: WrappedPlayer,
-) : Player {
+) : PlayerWrapper {
     private val mediaPlayer = createMediaPlayer(wrappedPlayer)
 
     private fun createMediaPlayer(wrappedPlayer: WrappedPlayer): MediaPlayer {

…n/xyz/luan/audioplayers/player/Player.kt …uan/audioplayers/player/PlayerWrapper.ktpackages/audioplayers_android/android/src/main/kotlin/xyz/luan/audioplayers/player/Player.kt renamed to packages/audioplayers_android/android/src/main/kotlin/xyz/luan/audioplayers/player/PlayerWrapper.kt packages/audioplayers_android/android/src/main/kotlin/xyz/luan/audioplayers/player/Player.kt renamed to packages/audioplayers_android/android/src/main/kotlin/xyz/luan/audioplayers/player/PlayerWrapper.kt

@@ -3,7 +3,7 @@ package xyz.luan.audioplayers.player
 import xyz.luan.audioplayers.AudioContextAndroid
 import xyz.luan.audioplayers.source.Source
 
-interface Player {
+interface PlayerWrapper {
     fun getDuration(): Int?
     fun getCurrentPosition(): Int?
     fun isLiveStream(): Boolean
@@ -12,7 +12,6 @@ interface Player {
     fun pause()
     fun stop()
     fun seekTo(position: Int)
-    fun release()
 
     fun setVolume(leftVolume: Float, rightVolume: Float)
     fun setRate(rate: Float)
@@ -21,5 +20,6 @@ interface Player {
     fun setSource(source: Source)
 
     fun prepare()
+    fun release()
     fun reset()
 }

packages/audioplayers_android/android/src/main/kotlin/xyz/luan/audioplayers/player/SoundPoolPlayer.kt

@@ -20,7 +20,7 @@ private const val MAX_STREAMS = 32
 class SoundPoolPlayer(
     val wrappedPlayer: WrappedPlayer,
     private val soundPoolManager: SoundPoolManager,
-) : Player {
+) : PlayerWrapper {
     private val mainScope = CoroutineScope(Dispatchers.Main)
 
     /** The id of the sound of source which will be played */