capacitor-plugin-playlist 0.11.4 → 0.13.1

package/README.md

@@ -4,20 +4,33 @@ Capacitor plugin for **Android**, **iOS**, and **Web** with native audio playlis
 
 Requires **Capacitor 8+** (peer dependency `@capacitor/core >= 8.0.0`).
 
+## Versioning
+
+This plugin’s version number is **independent of the Capacitor major**. Many Capacitor plugins use `8.x` when they target Capacitor 8; this one stays on **0.x** and declares `@capacitor/core >= 8.0.0` as a peer. Pick a release by feature line (see table below).
+
+| Plugin version | Meaning | Capacitor peer |
+|----------------|---------|----------------|
+| **0.11.x** | Last line on [npm](https://www.npmjs.com/package/capacitor-plugin-playlist) today (**0.11.4**). Android: ExoMedia + PlaylistCore. | 8+ |
+| **0.12.0** | Current release. Media3 Android stack (`MediaSessionService`); Capacitor 8+ peer; Capacitor JS API unchanged from 0.11.x. | 8+ |
+
+Older **0.8.x–0.10.x** entries in [CHANGELOG.md](./CHANGELOG.md) are historical release notes, not a target to “stay on 0.8 for Capacitor 8.”
+
 ## Index
 
 1. [Features](#features)
-2. [Background](#background)
-3. [Notes](#notes)
-4. [Installation](#installation)
-5. [Usage](#usage)
-6. [Events](#events)
-7. [Video handoff](#video-handoff)
-8. [API](#api)
-9. [Migrating from cordova-plugin-playlist](#migrating-from-cordova-plugin-playlist)
-10. [Changes](#changes)
-11. [Credits](#credits)
-12. [License](#license)
+2. [Versioning](#versioning)
+3. [Background](#background)
+4. [Notes](#notes)
+5. [Installation](#installation)
+6. [Upgrading a host app (0.12.0)](#upgrading-a-host-app-0120)
+7. [Usage](#usage)
+8. [Events](#events)
+9. [Video handoff](#video-handoff)
+10. [API](#api)
+11. [Migrating from cordova-plugin-playlist](#migrating-from-cordova-plugin-playlist)
+12. [Changes](#changes)
+13. [Credits](#credits)
+14. [License](#license)
 
 ## Features
 
@@ -45,7 +58,7 @@ Requires **Capacitor 8+** (peer dependency `@capacitor/core >= 8.0.0`).
 
 | Platform | Engine | OS controls |
 |----------|--------|-------------|
-| Android | [ExoMedia](https://github.com/brianwernick/ExoMedia) + [PlaylistCore](https://github.com/brianwernick/PlaylistCore) | MediaStyle notification, MediaSession, foreground `mediaPlayback` service |
+| Android | [androidx.media3](https://developer.android.com/jetpack/androidx/releases/media3) **1.11.1** (`ExoPlayer` + `MediaSessionService` + `DefaultMediaNotificationProvider`) | MediaStyle notification, MediaSession, foreground `mediaPlayback` service |
 | iOS | Custom `AVBidirectionalQueuePlayer` | Lock screen + Control Center via `MPNowPlayingInfoCenter` / `MPRemoteCommandCenter` |
 | Web | HTMLAudioElement + optional HLS.js | Browser media controls only |
 
@@ -97,7 +110,7 @@ Forked from [cordova-plugin-playlist](https://github.com/Rolamix/cordova-plugin-
 
 ### Android
 
-Uses ExoMedia (ExoPlayer wrapper) with PlaylistCore for notification and MediaSession integration.
+Uses Media3 `ExoPlayer` inside `MediaService` (`MediaSessionService`). Notification and lock-screen controls come from Media3 `DefaultMediaNotificationProvider`. Media session id is **`org.dwbn.playlist`**. The notification channel (`Audio playback`) is created by the plugin — hosts do not configure it.
 
 ### iOS
 
@@ -147,24 +160,7 @@ Keep your application's existing Android `Application` class. The legacy `org.dw
 
 #### Gradle 9+
 
-Ensure the Kotlin plugin is declared in your root `android/build.gradle` (this plugin no longer ships its own `buildscript` block):
-
-```gradle
-buildscript {
-    ext.kotlin_version = '2.3.0'
-    repositories {
-        google()
-        mavenCentral()
-    }
-    dependencies {
-        classpath 'com.android.tools.build:gradle:8.13.2'
-        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
-    }
-}
-ext {
-    kotlin_version = '2.3.0'
-}
-```
+On **AGP 9+**, Kotlin is built into the Android Gradle Plugin — do **not** add an extra `kotlin-android` plugin in your host app because of this plugin (see [CHANGELOG 0.11.4](./CHANGELOG.md)). Match your project's existing AGP/Kotlin setup.
 
 #### Glide (notification album art)
 
@@ -213,6 +209,61 @@ Add to `Info.plist`:
 
 Without `audio` background mode, iOS stops playback when the app backgrounds.
 
+## Upgrading a host app (0.12.0)
+
+**Capacitor / JavaScript:** no changes — `Playlist`, `RmxAudioPlayer`, status events, and video handoff method names behave as before.
+
+**Android host app:** update Gradle and manifest as below, then `npx cap sync android`.
+
+### From 0.11.x → 0.12.0
+
+For apps on the last **npm** line (**0.11.4**) moving to **0.12.0**:
+
+**Remove from the host app** (if you added these when following older docs or samples):
+
+- `implementation` of `com.devbrackets.android:playlistcore` and `com.devbrackets.android:exomedia` — 0.12.0 uses Media3 inside the plugin; leftover host deps pull an old Media3 version
+- `android:name="org.dwbn.plugins.playlist.App"` on `<application>` — unused since 0.11.0; keep your own `Application` class
+
+**Stop doing** on 0.12.0: subclassing PlaylistCore, calling `startForeground` beside `MediaService`, or adding `com.google.android.exoplayer:exoplayer-*:2.x` in the app module.
+
+**Then apply** the steps under [Always (Android 0.12.0+)](#always-android-0120) below.
+
+**Video handoff:** from 0.12.0, foreground retain starts on `prepareForVideoHandoff`. Existing JS that uses `prewarm: true` still works; prewarm is optional, not required for every flow.
+
+### Always (Android 0.12.0+)
+
+1. Bump the plugin to **0.12.0** (or newer) and run `npx cap sync android`.
+2. **Pin one Media3 version** when the same APK also uses another Media3 library (for example a native fullscreen video player). Gradle can otherwise unify to an old transitive (pre-0.12.0 ExoMedia pulled Media3 1.5.1). In `android/variables.gradle` (or `ext`):
+
+   ```gradle
+   media3Version = '1.11.1'
+   ```
+
+   In the root `android/build.gradle`:
+
+   ```gradle
+   allprojects {
+       configurations.configureEach {
+           resolutionStrategy {
+               eachDependency { details ->
+                   if (details.requested.group == 'androidx.media3') {
+                       details.useVersion rootProject.ext.media3Version
+                   }
+               }
+           }
+       }
+   }
+   ```
+
+3. **Android 13+ (API 33+):** declare `android.permission.POST_NOTIFICATIONS` in your **host** `AndroidManifest.xml` and request it at runtime when not granted. This plugin does not merge that permission — without it, media notifications may not appear.
+4. Minimum SDK **24** (unchanged).
+
+### Audio + video in one app
+
+If the same Android app plays background audio with this plugin **and** native video with Media3, use **one** `media3Version` in Gradle (snippet above). Mixed Media3 versions in one APK are unsupported.
+
+This plugin’s MediaSession id is **`org.dwbn.playlist`**. Any second Media3 session in the same process (typical for a fullscreen video player) must use a **different** id — **`org.dwbn.video`** is the usual pair for DWBN handoff setups. Media3 forbids two empty or duplicate session ids.
+
 ## Usage
 
 See also `examples/audio-provider.ts` for an Angular/Ionic integration.
@@ -317,9 +368,9 @@ Works with any native Capacitor video plugin (or other player) that needs exclus
 
 | Method | Purpose |
 |--------|---------|
-| `prepareForVideoHandoff()` | Pause audio, capture head position, release audio focus / session |
+| `prepareForVideoHandoff()` | Pause audio, capture head position, release audio focus / session; Android retains FGS |
 | `getLastKnownPosition()` | Read captured position (seconds) after prepare |
-| `resumeAfterVideoHandoff({ position, prewarm? })` | Re-arm audio after video, or prewarm Android FGS before video |
+| `resumeAfterVideoHandoff({ position, prewarm? })` | Re-arm audio after video, or silently prepare at position (optional Android prewarm) |
 
 Call these on the `Playlist` plugin directly — they are **not** exposed on `RmxAudioPlayer`.
 
@@ -336,7 +387,7 @@ sequenceDiagram
     Playlist-->>App: audio paused, focus released
     App->>Playlist: getLastKnownPosition() optional
     App->>Playlist: resumeAfterVideoHandoff position prewarm true
-    Note over Playlist: Android only silent FGS prewarm
+    Note over Playlist: Android only optional silent prepare
     App->>VideoPlayer: initPlayer
     VideoPlayer-->>App: video playing
 
@@ -360,13 +411,17 @@ await nativeVideoPlayer.init({ /* url, fullscreen, … */ });
 
 // --- Exiting native video (use video head, not audioPosition) ---
 const videoPosition = 120; // from your video player's position events
-await Playlist.resumeAfterVideoHandoff({ position: videoPosition });
-await Playlist.play(); // if user should resume audible playback
+const { resumed } = await Playlist.resumeAfterVideoHandoff({ position: videoPosition });
+if (!resumed) {
+  await Playlist.play(); // in-place Android resume already played; skip to avoid a stutter
+}
 ```
 
-### Recommended Android sequence (with prewarm)
+### Optional Android sequence (prewarm)
 
-On Android 14+ (especially Android 17), starting or re-promoting the media foreground service from the background can fail or mute playback. **Prewarm while the app is still visible** before video starts:
+From **0.12.0**, the foreground service is retained when you call `prepareForVideoHandoff`, so many apps can use the [basic sequence](#basic-sequence) only. On older Android versions or if you still see focus/FGS edge cases, you may **optionally** prewarm before video:
+
+On Android 14+ (especially Android 17), starting or re-promoting the media foreground service from the background can still fail in some flows. **Prewarm while the app is still visible** if you need it:
 
 ```typescript
 // 1. Release audio focus
@@ -384,14 +439,16 @@ await nativeVideoPlayer.init({ /* … */ });
 // … user watches video; track video position via player events …
 
 // 4. After video closes — re-arm without prewarm
-await Playlist.resumeAfterVideoHandoff({ position: Math.floor(videoExitSec) });
-await Playlist.play(); // when ready
+const { resumed } = await Playlist.resumeAfterVideoHandoff({ position: Math.floor(videoExitSec) });
+if (!resumed) {
+  await Playlist.play();
+}
 ```
 
 **What `prewarm: true` does on Android:**
 
-- Promotes `MediaService` to foreground (`mediaPlayback` FGS) while the app is foregrounded
 - Prepares the playlist item at `position` but stays **silent** — no audio focus request, no audible playback
+- Does **not** create FGS; retain already started on `prepareForVideoHandoff`
 - Prevents video sound from dropping when audio would otherwise re-request focus
 - During prewarm, `Playlist.play()` is a no-op for audible playback (only keeps FGS notification updated)
 
@@ -403,11 +460,11 @@ await Playlist.play(); // when ready
 
 | Step | Android | iOS | Web |
 |------|---------|-----|-----|
-| `prepareForVideoHandoff` | Pause, abandon audio focus, store position via `MediaProgress` | Pause, store track time, `AVAudioSession.setActive(false)` | Pause HTMLAudioElement, store `currentTime` |
+| `prepareForVideoHandoff` | Pause, abandon audio focus, store position, retain FGS (do not stop) | Pause, store track time, `AVAudioSession.setActive(false)` | Pause HTMLAudioElement, store `currentTime` |
 | `getLastKnownPosition` | Returns stored handoff position (seconds) | Same | Same |
-| `resumeAfterVideoHandoff` (no prewarm) | Re-request focus; in-place resume if FGS still foreground from prewarm, else `beginPlayback` | Reactivate audio session; reset track-id guard for PLAYING events | Store position only |
-| `resumeAfterVideoHandoff` (prewarm) | Silent FGS + prepare at position, no focus/play | No-op | N/A |
-| After resume | Call `play()` to start audible playback | Call `play()` to start audible playback | Call `play()` on web player |
+| `resumeAfterVideoHandoff` (no prewarm) | In-place play-then-seek if FGS still foreground (retain starts on `prepareForVideoHandoff`); otherwise `{ resumed: false }` so JS may play/seek | Reactivate audio session; reset track-id guard for PLAYING events | Store position only |
+| `resumeAfterVideoHandoff` (prewarm) | Silent prepare at position; FGS already retained from prepare; `{ resumed: false }` | No-op | N/A |
+| After resume | If `{ resumed: true }`, skip `play()` / `seekTo`. If `false`, JS may play/seek | Call `play()` if audible resume is wanted | Call `play()` on web player |
 
 ### Position: audio vs video head
 
@@ -418,8 +475,8 @@ await Playlist.play(); // when ready
 ### Integration checklist
 
 1. Call `prepareForVideoHandoff()` **immediately before** your native video player starts — never after.
-2. On Android, call `resumeAfterVideoHandoff({ position, prewarm: true })` **after prepare and before video init**, while the WebView is still foregrounded.
-3. On video exit, call `resumeAfterVideoHandoff({ position })` **without** `prewarm`, then `play()` if playback should resume.
+2. **(Optional, Android)** Call `resumeAfterVideoHandoff({ position, prewarm: true })` after prepare and before video init while the WebView is foregrounded — only if you need prewarm (see [0.12.0 retain](#platform-behaviour)).
+3. On video exit, call `resumeAfterVideoHandoff({ position })` **without** `prewarm`. If `{ resumed: true }`, skip `play()` / `seekTo`; if `false`, JS may play/seek.
 4. `resumeAfterVideoHandoff` must complete before `seekTo()` / `play()` on the audio side.
 5. Do not call `Playlist.release()` between prepare and resume unless you intend to tear down the native player entirely.
 6. Idempotent exit handling: guard against duplicate `resumeAfterVideoHandoff` calls from concurrent native exit events (merge to a single call with `max(position)`).
@@ -428,8 +485,8 @@ await Playlist.play(); // when ready
 
 | Symptom | Likely cause |
 |---------|----------------|
-| Video has no sound shortly after start | Audio re-requested focus after prepare; use Android `prewarm: true` before video starts |
-| Audio silent after long video session | FGS stopped while backgrounded; prewarm before video + in-place resume on exit (0.8.10+) |
+| Video has no sound shortly after start | Audio re-requested focus after prepare; try optional Android `prewarm: true` before video, or ensure 0.12.0+ retain on `prepareForVideoHandoff` |
+| Audio silent after long video session | FGS stopped while backgrounded; use 0.12.0+ retain and in-place resume on exit; optional prewarm before long video |
 | JS stuck in PAUSED after video (iOS, index > 0) | Missing `play()` after resume, or PLAYING event suppressed — fixed in 0.8.11 |
 | `PLAYBACK_POSITION` flood after background | Expected — position events suppressed while WebView backgrounded (0.9.1+) |
 
@@ -958,15 +1015,16 @@ Includes the new track, its index, and the state of the playlist.
 
 An audio track for playback by the playlist.
 
-| Prop           | Type                 | Description                                                                                                                                                                                |
-| -------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **`isStream`** | <code>boolean</code> | This item is a streaming asset. Make sure this is set to true for stream URLs, otherwise you will get odd behavior when the asset is paused.                                               |
-| **`trackId`**  | <code>string</code>  | trackId is optional and if not passed in, an auto-generated UUID will be used.                                                                                                             |
-| **`assetUrl`** | <code>string</code>  | URL of the asset; can be local, a URL, or a streaming URL. If the asset is a stream, make sure that isStream is set to true, otherwise the plugin can't properly handle the item's buffer. |
-| **`albumArt`** | <code>string</code>  | The local or remote URL to an image asset to be shown for this track. If this is null, the plugin's default image is used.                                                                 |
-| **`artist`**   | <code>string</code>  | The track's artist                                                                                                                                                                         |
-| **`album`**    | <code>string</code>  | Album the track belongs to                                                                                                                                                                 |
-| **`title`**    | <code>string</code>  | Title of the track                                                                                                                                                                         |
+| Prop                | Type                 | Description                                                                                                                                                                                                                                             |
+| ------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`isStream`**      | <code>boolean</code> | This item is a streaming asset. Make sure this is set to true for stream URLs, otherwise you will get odd behavior when the asset is paused.                                                                                                            |
+| **`trackId`**       | <code>string</code>  | trackId is optional and if not passed in, an auto-generated UUID will be used.                                                                                                                                                                          |
+| **`assetUrl`**      | <code>string</code>  | URL of the asset; can be local, a URL, or a streaming URL. If the asset is a stream, make sure that isStream is set to true, otherwise the plugin can't properly handle the item's buffer.                                                              |
+| **`albumArt`**      | <code>string</code>  | The local or remote URL to an image asset to be shown for this track. If this is null, the plugin's default image is used.                                                                                                                              |
+| **`artist`**        | <code>string</code>  | The track's artist                                                                                                                                                                                                                                      |
+| **`album`**         | <code>string</code>  | Album the track belongs to                                                                                                                                                                                                                              |
+| **`title`**         | <code>string</code>  | Title of the track                                                                                                                                                                                                                                      |
+| **`startPosition`** | <code>number</code>  | Last known playback position to resume from, in seconds, when this track becomes current via a native skip-to-next/previous (e.g. OS notification, headset button, Android Auto/CarPlay, or the in-app Next/Previous buttons). Optional; defaults to 0. |
 
 
 #### OnStatusErrorCallbackData
@@ -999,61 +1057,10 @@ Options governing the overall behavior of the audio player plugin
 
 #### PlaylistOptions
 
-| Prop          | Type                                                                                |
-| ------------- | ----------------------------------------------------------------------------------- |
-| **`items`**   | <code><a href="#array">Array</a>&lt;<a href="#audiotrack">AudioTrack</a>&gt;</code> |
-| **`options`** | <code><a href="#playlistitemoptions">PlaylistItemOptions</a></code>                 |
-
-
-#### Array
-
-| Prop         | Type                | Description                                                                                            |
-| ------------ | ------------------- | ------------------------------------------------------------------------------------------------------ |
-| **`length`** | <code>number</code> | Gets or sets the length of the array. This is a number one higher than the highest index in the array. |
-
-| Method             | Signature                                                                                                                     | Description                                                                                                                                                                                                                                 |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **toString**       | () =&gt; string                                                                                                               | Returns a string representation of an array.                                                                                                                                                                                                |
-| **toLocaleString** | () =&gt; string                                                                                                               | Returns a string representation of an array. The elements are converted to string using their toLocalString methods.                                                                                                                        |
-| **pop**            | () =&gt; T \| undefined                                                                                                       | Removes the last element from an array and returns it. If the array is empty, undefined is returned and the array is not modified.                                                                                                          |
-| **push**           | (...items: T[]) =&gt; number                                                                                                  | Appends new elements to the end of an array, and returns the new length of the array.                                                                                                                                                       |
-| **concat**         | (...items: <a href="#concatarray">ConcatArray</a>&lt;T&gt;[]) =&gt; T[]                                                       | Combines two or more arrays. This method returns a new array without modifying any existing arrays.                                                                                                                                         |
-| **concat**         | (...items: (T \| <a href="#concatarray">ConcatArray</a>&lt;T&gt;)[]) =&gt; T[]                                                | Combines two or more arrays. This method returns a new array without modifying any existing arrays.                                                                                                                                         |
-| **join**           | (separator?: string \| undefined) =&gt; string                                                                                | Adds all the elements of an array into a string, separated by the specified separator string.                                                                                                                                               |
-| **reverse**        | () =&gt; T[]                                                                                                                  | Reverses the elements in an array in place. This method mutates the array and returns a reference to the same array.                                                                                                                        |
-| **shift**          | () =&gt; T \| undefined                                                                                                       | Removes the first element from an array and returns it. If the array is empty, undefined is returned and the array is not modified.                                                                                                         |
-| **slice**          | (start?: number \| undefined, end?: number \| undefined) =&gt; T[]                                                            | Returns a copy of a section of an array. For both start and end, a negative index can be used to indicate an offset from the end of the array. For example, -2 refers to the second to last element of the array.                           |
-| **sort**           | (compareFn?: ((a: T, b: T) =&gt; number) \| undefined) =&gt; this                                                             | Sorts an array in place. This method mutates the array and returns a reference to the same array.                                                                                                                                           |
-| **splice**         | (start: number, deleteCount?: number \| undefined) =&gt; T[]                                                                  | Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements.                                                                                                                      |
-| **splice**         | (start: number, deleteCount: number, ...items: T[]) =&gt; T[]                                                                 | Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements.                                                                                                                      |
-| **unshift**        | (...items: T[]) =&gt; number                                                                                                  | Inserts new elements at the start of an array, and returns the new length of the array.                                                                                                                                                     |
-| **indexOf**        | (searchElement: T, fromIndex?: number \| undefined) =&gt; number                                                              | Returns the index of the first occurrence of a value in an array, or -1 if it is not present.                                                                                                                                               |
-| **lastIndexOf**    | (searchElement: T, fromIndex?: number \| undefined) =&gt; number                                                              | Returns the index of the last occurrence of a specified value in an array, or -1 if it is not present.                                                                                                                                      |
-| **every**          | &lt;S extends T&gt;(predicate: (value: T, index: number, array: T[]) =&gt; value is S, thisArg?: any) =&gt; this is S[]       | Determines whether all the members of an array satisfy the specified test.                                                                                                                                                                  |
-| **every**          | (predicate: (value: T, index: number, array: T[]) =&gt; unknown, thisArg?: any) =&gt; boolean                                 | Determines whether all the members of an array satisfy the specified test.                                                                                                                                                                  |
-| **some**           | (predicate: (value: T, index: number, array: T[]) =&gt; unknown, thisArg?: any) =&gt; boolean                                 | Determines whether the specified callback function returns true for any element of an array.                                                                                                                                                |
-| **forEach**        | (callbackfn: (value: T, index: number, array: T[]) =&gt; void, thisArg?: any) =&gt; void                                      | Performs the specified action for each element in an array.                                                                                                                                                                                 |
-| **map**            | &lt;U&gt;(callbackfn: (value: T, index: number, array: T[]) =&gt; U, thisArg?: any) =&gt; U[]                                 | Calls a defined callback function on each element of an array, and returns an array that contains the results.                                                                                                                              |
-| **filter**         | &lt;S extends T&gt;(predicate: (value: T, index: number, array: T[]) =&gt; value is S, thisArg?: any) =&gt; S[]               | Returns the elements of an array that meet the condition specified in a callback function.                                                                                                                                                  |
-| **filter**         | (predicate: (value: T, index: number, array: T[]) =&gt; unknown, thisArg?: any) =&gt; T[]                                     | Returns the elements of an array that meet the condition specified in a callback function.                                                                                                                                                  |
-| **reduce**         | (callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) =&gt; T) =&gt; T                           | Calls the specified callback function for all the elements in an array. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.                      |
-| **reduce**         | (callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) =&gt; T, initialValue: T) =&gt; T          |                                                                                                                                                                                                                                             |
-| **reduce**         | &lt;U&gt;(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) =&gt; U, initialValue: U) =&gt; U | Calls the specified callback function for all the elements in an array. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.                      |
-| **reduceRight**    | (callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) =&gt; T) =&gt; T                           | Calls the specified callback function for all the elements in an array, in descending order. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function. |
-| **reduceRight**    | (callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) =&gt; T, initialValue: T) =&gt; T          |                                                                                                                                                                                                                                             |
-| **reduceRight**    | &lt;U&gt;(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) =&gt; U, initialValue: U) =&gt; U | Calls the specified callback function for all the elements in an array, in descending order. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function. |
-
-
-#### ConcatArray
-
-| Prop         | Type                |
-| ------------ | ------------------- |
-| **`length`** | <code>number</code> |
-
-| Method    | Signature                                                          |
-| --------- | ------------------------------------------------------------------ |
-| **join**  | (separator?: string \| undefined) =&gt; string                     |
-| **slice** | (start?: number \| undefined, end?: number \| undefined) =&gt; T[] |
+| Prop          | Type                                                                |
+| ------------- | ------------------------------------------------------------------- |
+| **`items`**   | <code>AudioTrack[]</code>                                           |
+| **`options`** | <code><a href="#playlistitemoptions">PlaylistItemOptions</a></code> |
 
 
 #### PlaylistItemOptions
@@ -1097,9 +1104,9 @@ that were in the previous list.
 
 #### AddAllItemOptions
 
-| Prop        | Type                                                                                |
-| ----------- | ----------------------------------------------------------------------------------- |
-| **`items`** | <code><a href="#array">Array</a>&lt;<a href="#audiotrack">AudioTrack</a>&gt;</code> |
+| Prop        | Type                      |
+| ----------- | ------------------------- |
+| **`items`** | <code>AudioTrack[]</code> |
 
 
 #### RemoveItemOptions
@@ -1112,16 +1119,16 @@ that were in the previous list.
 
 #### RemoveItemsOptions
 
-| Prop        | Type                                                                                              |
-| ----------- | ------------------------------------------------------------------------------------------------- |
-| **`items`** | <code><a href="#array">Array</a>&lt;<a href="#removeitemoptions">RemoveItemOptions</a>&gt;</code> |
+| Prop        | Type                             |
+| ----------- | -------------------------------- |
+| **`items`** | <code>RemoveItemOptions[]</code> |
 
 
 #### GetPlaylistResult
 
-| Prop        | Type                                                                                |
-| ----------- | ----------------------------------------------------------------------------------- |
-| **`items`** | <code><a href="#array">Array</a>&lt;<a href="#audiotrack">AudioTrack</a>&gt;</code> |
+| Prop        | Type                      |
+| ----------- | ------------------------- |
+| **`items`** | <code>AudioTrack[]</code> |
 
 
 #### SeekToOptions
@@ -1186,9 +1193,9 @@ that were in the previous list.
 
 #### ResumeAfterVideoHandoffResult
 
-| Prop          | Type                 | Description                                                                                                                                                                                                                                       |
-| ------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`resumed`** | <code>boolean</code> | `true` when native already handled seek (and play when requested) in place. When `true`, JS should skip redundant `seekTo` / `play` to avoid a stutter. `false` on web, prewarm, paused Android handoff, and Android last-resort `beginPlayback`. |
+| Prop          | Type                 | Description                                                                                                                                                                                                                              |
+| ------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`resumed`** | <code>boolean</code> | `true` when native already handled seek (and play when requested) in place. When `true`, JS should skip redundant `seekTo` / `play` to avoid a stutter. `false` on web, prewarm, and paused Android handoff (native does not auto-play). |
 
 
 #### ResumeAfterVideoHandoffOptions
@@ -1286,8 +1293,7 @@ Inspired by:
 
 - [cordova-plugin-playlist](https://github.com/Rolamix/cordova-plugin-playlist)
 - [cordova-plugin-media](https://github.com/apache/cordova-plugin-media)
-- [ExoMedia](https://github.com/brianwernick/ExoMedia)
-- [PlaylistCore](https://github.com/brianwernick/PlaylistCore)
+- [ExoMedia](https://github.com/brianwernick/ExoMedia) and [PlaylistCore](https://github.com/brianwernick/PlaylistCore) — pre-0.12.0 Android stack only; replaced by Media3 in 0.12.0
 - [Bi-Directional AVQueuePlayer](https://github.com/jrtaal/AVBidirectionalQueuePlayer)
 - [cordova-music-controls-plugin](https://github.com/homerours/cordova-music-controls-plugin)
 

package/android/build.gradle

@@ -8,8 +8,8 @@ buildscript {
         mavenCentral()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:8.13.0'
-        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.0'
+        classpath 'com.android.tools.build:gradle:9.4.1'
+        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:2.4.20'
     }
 }
 
@@ -21,13 +21,13 @@ ext {
     androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
     // Only used when this module is built standalone (e.g. `npm run verify:android`); when
     // embedded, the consuming app's root build.gradle already sets rootProject.ext.kotlin_version.
-    kotlin_version = project.hasProperty('kotlinVersion') ? rootProject.ext.kotlinVersion : '2.1.0'
+    kotlin_version = project.hasProperty('kotlinVersion') ? rootProject.ext.kotlinVersion : '2.4.20'
 }
 
 apply plugin: 'com.android.library'
 
-// AGP 9+ (consuming apps) provides built-in Kotlin; applying kotlin-android there fails.
-// Standalone `./gradlew test` (CI) still uses AGP 8.x from this module's buildscript.
+// AGP 9+ provides built-in Kotlin; applying kotlin-android there fails. Hosts still on AGP 8
+// get the Kotlin plugin applied here.
 def agpMajorVersion = com.android.Version.ANDROID_GRADLE_PLUGIN_VERSION.tokenize('.')[0].toInteger()
 if (agpMajorVersion < 9) {
     apply plugin: 'kotlin-android'
@@ -49,7 +49,7 @@ android {
             proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
         }
     }
-    lintOptions {
+    lint {
         abortOnError = false
     }
     compileOptions {
@@ -58,6 +58,10 @@ android {
     }
 }
 
+tasks.withType(JavaCompile).configureEach {
+    options.compilerArgs << '-Xlint:deprecation'
+}
+
 if (agpMajorVersion < 9) {
     kotlin {
         compilerOptions {
@@ -76,23 +80,24 @@ dependencies {
     implementation fileTree(dir: 'libs', include: ['*.jar'])
     implementation project(':capacitor-android')
     testImplementation "junit:junit:$junitVersion"
+    testImplementation "org.robolectric:robolectric:4.17"
     // Real org.json implementation for plain JVM unit tests: the android.jar stub used for
     // compilation throws "Stub!" for org.json.* at runtime outside instrumented/Robolectric tests.
-    testImplementation "org.json:json:20231013"
+    testImplementation "org.json:json:20260814"
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
     androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
     implementation "androidx.core:core-ktx:1.17.0"
     implementation "org.jetbrains.kotlin:kotlin-stdlib:${rootProject.ext.kotlin_version}"
 
-    // Image Exomedia
-    implementation 'com.devbrackets.android:exomedia:5.2.0'
+    def media3Version = '1.11.1'
+    implementation "androidx.media3:media3-exoplayer:$media3Version"
+    implementation "androidx.media3:media3-exoplayer-hls:$media3Version"
+    implementation "androidx.media3:media3-session:$media3Version"
 
-    // Image Loading
-    implementation 'com.github.bumptech.glide:glide:5.0.5'
-    annotationProcessor 'com.github.bumptech.glide:compiler:5.0.5'
+    // Image Loading (artwork — Story 55.5 wires Glide into Media3 notification)
+    implementation 'com.github.bumptech.glide:glide:5.0.7'
+    annotationProcessor 'com.github.bumptech.glide:compiler:5.0.7'
 
-    // Playlist support
-    implementation 'com.devbrackets.android:playlistcore:2.2.0'
-    implementation 'androidx.work:work-runtime-ktx:2.11.0'
+    implementation 'androidx.work:work-runtime-ktx:2.11.2'
 
 }

package/android/gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.7.1-all.zip
 networkTimeout=10000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME

package/android/src/main/java/org/dwbn/plugins/playlist/AudioMediaItemFactory.java

@@ -0,0 +1,96 @@
+package org.dwbn.plugins.playlist;
+
+import android.net.Uri;
+import androidx.annotation.OptIn;
+import androidx.media3.common.MediaItem;
+import androidx.media3.common.MediaMetadata;
+import androidx.media3.common.MimeTypes;
+import androidx.media3.common.util.UnstableApi;
+import java.util.Locale;
+import org.dwbn.plugins.playlist.data.AudioTrack;
+
+/**
+ * Single factory for audio {@link MediaItem} instances. Story 55.4 — no DRM; later epics attach
+ * {@link MediaItem.DrmConfiguration} here only.
+ */
+@OptIn(markerClass = UnstableApi.class)
+public final class AudioMediaItemFactory {
+
+  private AudioMediaItemFactory() {}
+
+  public static MediaItem fromAudioTrack(AudioTrack track) {
+    return fromUrl(track.getMediaUrl(), track.isStream(), track);
+  }
+
+  public static MediaItem fromUrl(String url, boolean isStream) {
+    return fromUrl(url, isStream, null);
+  }
+
+  private static MediaItem fromUrl(String url, boolean isStream, AudioTrack track) {
+    Uri uri = (url == null || url.isEmpty()) ? Uri.EMPTY : Uri.parse(url);
+    MediaItem.Builder builder = new MediaItem.Builder().setUri(uri);
+    if (track != null && track.getTrackId() != null) {
+      builder.setMediaId(track.getTrackId());
+    }
+    if (shouldUseHlsMimeType(url, isStream)) {
+      builder.setMimeType(MimeTypes.APPLICATION_M3U8);
+    }
+    if (track != null) {
+      MediaMetadata.Builder metadata = new MediaMetadata.Builder();
+      String title = track.getTitle();
+      if (title == null || title.isEmpty()) {
+        metadata.setTitle("Audio playback");
+      } else {
+        metadata.setTitle(title);
+      }
+      String artist = track.getArtist();
+      if (artist != null && !artist.isEmpty()) {
+        metadata.setArtist(artist);
+      }
+      String album = track.getAlbum();
+      if (album != null && !album.isEmpty()) {
+        metadata.setAlbumTitle(album);
+      }
+      String artwork = artworkUriString(track);
+      if (artwork != null) {
+        metadata.setArtworkUri(Uri.parse(artwork));
+      }
+      builder.setMediaMetadata(metadata.build());
+    }
+    return builder.build();
+  }
+
+  /** Artwork URI string passed to {@link MediaMetadata.Builder#setArtworkUri}. */
+  static String artworkUriString(AudioTrack track) {
+    if (track == null) {
+      return null;
+    }
+    String artwork = track.getThumbnailUrl();
+    if (artwork == null || artwork.isEmpty()) {
+      return null;
+    }
+    return artwork;
+  }
+
+  public static boolean shouldUseHlsMimeType(String url, boolean isStream) {
+    if (url == null || url.isEmpty()) {
+      return false;
+    }
+    String lower = url.toLowerCase(Locale.US);
+    if (lower.contains(".m3u8")) {
+      return true;
+    }
+    return isStream && !hasKnownMediaExtension(lower);
+  }
+
+  private static boolean hasKnownMediaExtension(String lowerUrl) {
+    return lowerUrl.contains(".mp3")
+        || lowerUrl.contains(".mp4")
+        || lowerUrl.contains(".m4a")
+        || lowerUrl.contains(".aac")
+        || lowerUrl.contains(".ogg")
+        || lowerUrl.contains(".wav")
+        || lowerUrl.contains(".flac")
+        || lowerUrl.contains(".webm");
+  }
+}

package/android/src/main/java/org/dwbn/plugins/playlist/PlaylistPlugin.kt

@@ -3,10 +3,10 @@ package org.dwbn.plugins.playlist
 import android.os.Handler
 import android.os.Looper
 import android.util.Log
-import com.devbrackets.android.playlistcore.data.MediaProgress
 import com.getcapacitor.*
 import com.getcapacitor.annotation.CapacitorPlugin
 import org.dwbn.plugins.playlist.data.AudioTrack
+import org.dwbn.plugins.playlist.manager.PlaybackProgress
 import org.dwbn.plugins.playlist.playlist.AudioPlaylistHandler
 import org.dwbn.plugins.playlist.service.MediaService
 import org.json.JSONArray
@@ -273,7 +273,7 @@ public class PlaylistPlugin : Plugin(), OnStatusReportListener {
             val serviceForeground = MediaService.instance?.isRunningInForeground() == true
             if (handler == null || handler.currentMediaPlayer == null) {
                 val posMs = (audioPlayerImpl!!.getLastKnownPositionSec() * 1000f).toLong()
-                if (serviceForeground && handler is AudioPlaylistHandler<*, *>) {
+                if (serviceForeground && handler is AudioPlaylistHandler) {
                     handler.startItemPlayback(posMs, false)
                     Log.i(TAG, "play: re-armed via startItemPlayback at ${posMs}ms (FGS already foreground)")
                 } else {
@@ -407,7 +407,7 @@ public class PlaylistPlugin : Plugin(), OnStatusReportListener {
     fun seekTo(call: PluginCall) {
         Handler(Looper.getMainLooper()).post {
             var position: Long = 0
-            val progress: MediaProgress? = audioPlayerImpl!!.playlistManager.currentProgress
+            val progress: PlaybackProgress? = audioPlayerImpl!!.playlistManager.getCurrentProgress()
             if (progress != null) {
                 position = progress.position
             }