capacitor-plugin-playlist

Capacitor plugin for Android, iOS, and Web with native audio playlist playback, background support, lock-screen / notification controls, and video handoff.

Requires Capacitor 8+ (peer dependency @capacitor/core >= 8.0.0).

Index

Features
Background
Notes
Installation
Usage
Events
Video handoff
API
Migrating from cordova-plugin-playlist
Changes
Credits
License

Features

Playlist management

setPlaylistItems — replace entire playlist (optional position retention)
addItem / addAllItems — append tracks
removeItem / removeItems / clearAllItems — remove tracks
getPlaylist — snapshot of current items
setLoop — loop entire playlist when the last track completes

Playback controls

play / pause
skipForward / skipBack
seekTo (seconds)
playTrackByIndex / playTrackById — jump and play
selectTrackByIndex / selectTrackById — select without playing
setPlaybackVolume (0–1)
setPlaybackRate (0 pauses, 1 = normal speed)

Native platform integration

Platform	Engine	OS controls
Android	ExoMedia + PlaylistCore	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

Background audio

Android: foreground media service with WAKE_LOCK and FOREGROUND_SERVICE_MEDIA_PLAYBACK (Android 14+)
iOS: UIBackgroundModes → audio
Position events throttled while WebView is backgrounded; one live snapshot emitted on foreground resume (0.9.1+)

Tracks and sources

Remote URLs, local files (file:// or app-resolved paths), and streams
Set isStream: true on streaming URLs so pause/resume buffering behaves correctly
albumArt shown in notification / lock screen (Glide on Android)
No built-in download manager — resolve offline paths in your app and pass them as assetUrl

Status event stream

Single status listener with RmxAudioStatusMessage events (see Events).

Video handoff

When switching from background audio to native fullscreen video:

prepareForVideoHandoff() — release audio focus / session
getLastKnownPosition() — saved head position (seconds)
resumeAfterVideoHandoff({ position, prewarm? }) — re-arm audio after video

See Video handoff.

Cordova-compatible wrapper

RmxAudioPlayer (src/RmxAudioPlayer.ts) is a drop-in replacement for cordova-plugin-playlist with on('status') / off('status') and state getters (isPlaying, currentTrack, etc.).

Not exposed on RmxAudioPlayer: getPlaylist, video handoff methods — call Playlist directly for those.

Not supported

Shuffle
Reorder API
Mixable / low-latency game audio (use cordova-plugin-nativeaudio instead)
Simultaneous audio mixing (lock-screen controls require exclusive audio focus)

Background

Forked from cordova-plugin-playlist for Capacitor.

Notes

Android

Uses ExoMedia (ExoPlayer wrapper) with PlaylistCore for notification and MediaSession integration.

iOS

Uses a customized AVQueuePlayer (AVBidirectionalQueuePlayer) for track-change feedback and continuous audio session between songs. Minimum iOS 18 (0.9.4+). Swift Package Manager supported (0.10.0+).

Installation

npm i capacitor-plugin-playlist
npx cap sync

Web

Include HLS.js in your build for HLS streams.

Angular example

npm i hls.js

Add to angular.json → architect → build → options → scripts:

"scripts": [
  {
    "input": "node_modules/hls.js/dist/hls.min.js"
  }
]

Android

AndroidManifest.xml

<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
<application android:name="org.dwbn.plugins.playlist.App">
    <service android:enabled="true" android:exported="false"
             android:foregroundServiceType="mediaPlayback"
             android:name="org.dwbn.plugins.playlist.service.MediaService">
    </service>
</application>

Gradle 9+

Ensure the Kotlin plugin is declared in your root android/build.gradle (this plugin no longer ships its own buildscript block):

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'
}

Glide (notification album art)

Create MyAppGlideModule.java:

package org.your.package.namespace;

import com.bumptech.glide.annotation.GlideModule;
import com.bumptech.glide.module.AppGlideModule;

@GlideModule
public final class MyAppGlideModule extends AppGlideModule {}

See https://guides.codepath.com/android/Displaying-Images-with-the-Glide-Library

Notification icon

Create a transparent silhouette icon (e.g. ic_notification.png) and pass it via setOptions:

await Playlist.setOptions({
  verbose: !environment.production,
  options: { icon: 'ic_notification' },
});

In Android Studio: right-click res → New → Image Asset → Notification Icons.

iOS

Add to Info.plist:

<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
    <string>fetch</string>
</array>

Without audio background mode, iOS stops playback when the app backgrounds.

Usage

See also examples/audio-provider.ts for an Angular/Ionic integration.

Basic flow (`Playlist` API)

import { Playlist, AudioTrack, RmxAudioStatusMessage } from 'capacitor-plugin-playlist';

await Playlist.setOptions({
  verbose: true,
  resetStreamOnPause: true,
  options: { icon: 'ic_notification' },
});

await Playlist.initialize();

const handle = await Playlist.addListener('status', ({ status }) => {
  if (status.msgType === RmxAudioStatusMessage.RMXSTATUS_PLAYBACK_POSITION) {
    // update UI progress
  }
});

const track: AudioTrack = {
  trackId: 'track-1',
  assetUrl: 'https://example.com/audio.mp3',
  title: 'Track title',
  artist: 'Artist name',
  album: 'Album name',
  albumArt: 'https://example.com/cover.jpg',
  isStream: false,
};

await Playlist.setPlaylistItems({
  items: [track],
  options: { startPaused: false },
});

await Playlist.play();
// later: handle.remove();

`RmxAudioPlayer` wrapper (Cordova migration)

import { RmxAudioPlayer, AudioTrack } from 'capacitor-plugin-playlist';

const player = new RmxAudioPlayer();
await player.initialize();

player.on('status', (data) => {
  console.log('status', data.msgType, data);
});

await player.setLoop(true);
await player.setPlaylistItems([track], { retainPosition: true, playFromId: track.trackId });
await player.play();

Events

Subscribe via Playlist.addListener('status', …) or RmxAudioPlayer.on('status', …).

Each callback receives { action: 'status', status: OnStatusCallbackData } where:

status.trackId — current track id, "NONE" when idle, "INVALID" when playlist completed
status.msgType — RmxAudioStatusMessage enum value
status.value — payload (shape depends on msgType)

msgType	Name	When	Payload
5	ERROR	Playback or network failure	`OnStatusErrorCallbackData` (`code`, `message`)
10	LOADING	Track loading started	`OnStatusCallbackUpdateData`
11	CANPLAY	Track ready to play	`OnStatusCallbackUpdateData`
15	LOADED	Track fully loaded	`OnStatusCallbackUpdateData`
20	STALLED	iOS: network stall	`OnStatusCallbackUpdateData`
25	BUFFERING	Buffer progress update	`OnStatusCallbackUpdateData`
30	PLAYING	Playback started/resumed	`OnStatusCallbackUpdateData`
35	PAUSE	Playback paused	`OnStatusCallbackUpdateData`
40	PLAYBACK_POSITION	Periodic position tick	`OnStatusCallbackUpdateData` (suppressed while WebView backgrounded)
45	SEEK	User or app seeked	`OnStatusCallbackUpdateData`
50	COMPLETED	Current track finished	`OnStatusCallbackUpdateData`
55	DURATION	Duration first known	`OnStatusCallbackUpdateData`
60	STOPPED	All playback stopped	`OnStatusCallbackUpdateData`
90	SKIP_FORWARD	Skipped to next track	`OnStatusCallbackUpdateData`
95	SKIP_BACK	Skipped to previous track	`OnStatusCallbackUpdateData`
100	TRACK_CHANGED	Active track changed	`OnStatusTrackChangedData`
105	PLAYLIST_COMPLETED	Entire playlist finished	`OnStatusCallbackUpdateData`
110	ITEM_ADDED	Track added	`OnStatusCallbackUpdateData`
115	ITEM_REMOVED	Track removed	`OnStatusCallbackUpdateData`
120	PLAYLIST_CLEARED	All tracks removed	`OnStatusCallbackUpdateData`

For track changes, prefer handling TRACK_CHANGED over SKIP_FORWARD / SKIP_BACK.

Video handoff

Native audio and native fullscreen video cannot share audio focus. These three methods coordinate a clean handoff when the user opens video while audio was playing (or when switching back to audio after video).

Works with any native Capacitor video plugin (or other player) that needs exclusive audio focus.

Methods

Method	Purpose
`prepareForVideoHandoff()`	Pause audio, capture head position, release audio focus / session
`getLastKnownPosition()`	Read captured position (seconds) after prepare
`resumeAfterVideoHandoff({ position, prewarm? })`	Re-arm audio after video, or prewarm Android FGS before video

Call these on the Playlist plugin directly — they are not exposed on RmxAudioPlayer.

Lifecycle

sequenceDiagram
    participant App
    participant Playlist
    participant VideoPlayer

    Note over App,VideoPlayer: Entering video
    App->>Playlist: prepareForVideoHandoff()
    Playlist-->>App: audio paused, focus released
    App->>Playlist: getLastKnownPosition() optional
    App->>Playlist: resumeAfterVideoHandoff position prewarm true
    Note over Playlist: Android only silent FGS prewarm
    App->>VideoPlayer: initPlayer
    VideoPlayer-->>App: video playing

    Note over App,VideoPlayer: Exiting video
    App->>Playlist: resumeAfterVideoHandoff position
    Note over Playlist: re-arm session no prewarm
    App->>Playlist: play optional
    Playlist-->>App: audio resumes

Basic sequence

import { Playlist } from 'capacitor-plugin-playlist';

// --- Entering native video ---
await Playlist.prepareForVideoHandoff();
const { position: audioPosition } = await Playlist.getLastKnownPosition();

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

Recommended Android sequence (with 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:

// 1. Release audio focus
await Playlist.prepareForVideoHandoff();

// 2. Prewarm FGS silently at the video start position (Android)
await Playlist.resumeAfterVideoHandoff({
  position: Math.floor(videoStartSec),
  prewarm: true,
});

// 3. Start native video
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

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
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)

iOS: prewarm is accepted but ignored. Use prepareForVideoHandoff() → video → resumeAfterVideoHandoff({ position }) → play().

Web: Both methods are stubs (pause + store position). No native session handoff.

Platform behaviour

Step	Android	iOS	Web
`prepareForVideoHandoff`	Pause, abandon audio focus, store position via `MediaProgress`	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

Position: audio vs video head

getLastKnownPosition() after prepareForVideoHandoff — last audio head before video opened. Useful if video never started or for debugging.
On video exit — pass the video playback position (from your video player's position events), not the stale audio position, so audio resumes where the user left off in the video timeline.
Track video head while video plays and persist it if the app may cold-start (e.g. after PiP dismiss on Android).

Integration checklist

Call prepareForVideoHandoff() immediately before your native video player starts — never after.
On Android, call resumeAfterVideoHandoff({ position, prewarm: true }) after prepare and before video init, while the WebView is still foregrounded.
On video exit, call resumeAfterVideoHandoff({ position }) without prewarm, then play() if playback should resume.
resumeAfterVideoHandoff must complete before seekTo() / play() on the audio side.
Do not call Playlist.release() between prepare and resume unless you intend to tear down the native player entirely.
Idempotent exit handling: guard against duplicate resumeAfterVideoHandoff calls from concurrent native exit events (merge to a single call with max(position)).

Common pitfalls

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+)
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+)

See CHANGELOG.md for version-specific fixes (0.8.8–0.10.3).

API

addListener('status', ...)
setOptions(...)
initialize()
release()
setPlaylistItems(...)
addItem(...)
addAllItems(...)
removeItem(...)
removeItems(...)
clearAllItems()
getPlaylist()
play()
pause()
skipForward()
skipBack()
seekTo(...)
playTrackByIndex(...)
playTrackById(...)
selectTrackByIndex(...)
selectTrackById(...)
setPlaybackVolume(...)
setLoop(...)
setPlaybackRate(...)
prepareForVideoHandoff()
resumeAfterVideoHandoff(...)
getLastKnownPosition()
Interfaces
Type Aliases
Enums

addListener('status', ...)

addListener(eventName: 'status', listenerFunc: PlaylistStatusChangeCallback) => Promise<PluginListenerHandle>

Subscribe to native playback status events (track changes, position, errors, etc.).

Param	Type	Description
`eventName`	`'status'`	Must be `'status'`.
`listenerFunc`	`PlaylistStatusChangeCallback`	Callback receiving `{ action, status }` where `status.msgType` is a `RmxAudioStatusMessage`.

Returns: Promise<PluginListenerHandle>

setOptions(...)

setOptions(options: AudioPlayerOptions) => Promise<void>

Configure plugin behaviour (verbose logging, stream pause handling, notification icon). Can be called at any time; not required before playback.

Param	Type
`options`	`AudioPlayerOptions`

initialize()

initialize() => Promise<void>

Initialise the native player, register status callbacks, and arm lock-screen / notification controls. Call once before playback (e.g. on app start).

release()

release() => Promise<void>

Tear down native resources (audio session, media service, observers). Call when the app no longer needs background audio (e.g. on logout).

setPlaylistItems(...)

setPlaylistItems(options: PlaylistOptions) => Promise<void>

Replace the entire playlist. Clears all previous items. Use options.retainPosition to keep the current track and playback position.

Param	Type
`options`	`PlaylistOptions`

addItem(...)

addItem(options: AddItemOptions) => Promise<void>

Append a single track to the end of the playlist.

Param	Type
`options`	`AddItemOptions`

addAllItems(...)

addAllItems(options: AddAllItemOptions) => Promise<void>

Append multiple tracks to the end of the playlist. Raises one RMXSTATUS_ITEM_ADDED event per track.

Param	Type
`options`	`AddAllItemOptions`

removeItem(...)

removeItem(options: RemoveItemOptions) => Promise<void>

Remove a track by index (preferred) or id. If the removed track is currently playing, the next track starts automatically.

Param	Type
`options`	`RemoveItemOptions`

removeItems(...)

removeItems(options: RemoveItemsOptions) => Promise<void>

Remove multiple tracks in a single batch. If the currently playing track is removed, the next available track starts automatically.

Param	Type
`options`	`RemoveItemsOptions`

clearAllItems()

clearAllItems() => Promise<void>

Remove all tracks from the playlist. Raises RMXSTATUS_PLAYLIST_CLEARED and RMXSTATUS_STOPPED.

getPlaylist()

getPlaylist() => Promise<GetPlaylistResult>

Return a snapshot of the current playlist items.

Returns: Promise<GetPlaylistResult>

play()

play() => Promise<void>

Start or resume playback of the current track. No-op if the playlist is empty.

pause()

pause() => Promise<void>

Pause playback of the current track.

skipForward()

skipForward() => Promise<void>

Skip to the next track. At the end of the playlist, wraps to the beginning when loop is enabled.

skipBack()

skipBack() => Promise<void>

Skip to the previous track. No-op when already at the first track.

seekTo(...)

seekTo(options: SeekToOptions) => Promise<void>

Seek to a position (seconds) in the currently playing track. If the position exceeds track length, playback advances to the next track.

Param	Type
`options`	`SeekToOptions`

playTrackByIndex(...)

playTrackByIndex(options: PlayByIndexOptions) => Promise<void>

Jump to the track at the given 0-based index and start playback.

Param	Type
`options`	`PlayByIndexOptions`

playTrackById(...)

playTrackById(options: PlayByIdOptions) => Promise<void>

Jump to the track with the given id and start playback.

Param	Type
`options`	`PlayByIdOptions`

selectTrackByIndex(...)

selectTrackByIndex(options: SelectByIndexOptions) => Promise<void>

Select the track at the given index without necessarily starting playback.

Param	Type
`options`	`SelectByIndexOptions`

selectTrackById(...)

selectTrackById(options: SelectByIdOptions) => Promise<void>

Select the track with the given id without necessarily starting playback.

Param	Type
`options`	`SelectByIdOptions`

setPlaybackVolume(...)

setPlaybackVolume(options: SetPlaybackVolumeOptions) => Promise<void>

Set media stream volume. Float in range [0, 1]. Hardware volume controls still apply on top of this value.

Param	Type
`options`	`SetPlaybackVolumeOptions`

setLoop(...)

setLoop(options: SetLoopOptions) => Promise<void>

When true, the playlist loops back to the first track after the last track completes.

Param	Type
`options`	`SetLoopOptions`

setPlaybackRate(...)

setPlaybackRate(options: SetPlaybackRateOptions) => Promise<void>

Set playback speed. Float value; 0 pauses, 1 is normal speed.

Param	Type
`options`	`SetPlaybackRateOptions`

prepareForVideoHandoff()

prepareForVideoHandoff() => Promise<void>

Release native audio session / focus so a video player can own playback.

Android: pauses current track, abandons audio focus, stores head position. Does not stop the foreground media service. iOS: pauses, captures head position, deactivates AVAudioSession with notifyOthersOnDeactivation. Web: pauses HTMLAudioElement and stores currentTime.

Call immediately before native video starts (e.g. your video plugin's init method).

resumeAfterVideoHandoff(...)

resumeAfterVideoHandoff(options: ResumeAfterVideoHandoffOptions) => Promise<ResumeAfterVideoHandoffResult>

Re-arm native audio after video ends or, on Android, prewarm the media service before video starts.

Without prewarm (typical exit path):

Android: when play is true (default), re-acquires focus and resumes at position. When resumed is true, JS should skip redundant seekTo/play. When play is false, clears handoff retain and returns { resumed: false } so JS can seek without playing.
iOS: restores pinned track, reactivates AVAudioSession, seeks to position, and when play is true starts playback (seek-then-play). Returns { resumed: true } when native handled the handoff.
Web: stores position only (no native session); returns { resumed: false }.

With prewarm: true (Android, before video): starts MediaService in foreground at position but stays silent — no audio focus, no audible playback. Always returns { resumed: false }.

Param	Type
`options`	`ResumeAfterVideoHandoffOptions`

Returns: Promise<ResumeAfterVideoHandoffResult>

getLastKnownPosition()

getLastKnownPosition() => Promise<GetLastKnownPositionResult>

Return the audio head position (seconds) captured during the most recent prepareForVideoHandoff or passed to resumeAfterVideoHandoff.

Returns: Promise<GetLastKnownPositionResult>

Interfaces

PluginListenerHandle

Prop	Type
`remove`	`() => Promise<void>`

PlaylistStatusChangeCallbackArg

Prop	Type
`action`	`string`
`status`	`OnStatusCallbackData`

OnStatusCallbackData

Encapsulates the data received by an onStatus callback

Prop	Type	Description
`trackId`	`string`	The ID of this track. If the track is null or has completed, this value is "NONE" If the playlist is completed, this value is "INVALID"
`msgType`	`RmxAudioStatusMessage`	The type of status update
`value`	`OnStatusCallbackUpdateData \| OnStatusTrackChangedData \| OnStatusErrorCallbackData`	The status payload. For all updates except ERROR, the data package is described by OnStatusCallbackUpdateData. For Errors, the data is shaped as OnStatusErrorCallbackData

OnStatusCallbackUpdateData

Contains the current track status as of the moment an onStatus update event is emitted.

Prop	Type	Description
`trackId`	`string`	The ID of this track corresponding to this event. If the track is null or has completed, this value is "NONE". This will happen when skipping to the beginning or end of the playlist. If the playlist is completed, this value is "INVALID"
`isStream`	`boolean`	Boolean indicating whether this is a streaming track.
`currentIndex`	`number`	The current index of the track in the playlist.
`status`	`'error' \| 'unknown' \| 'ready' \| 'playing' \| 'loading' \| 'paused'`	The current status of the track, as a string. This is used to summarize the various event states that a track can be in; e.g. "playing" is true for any number of track statuses. The Javascript interface takes care of this for you; this field is here only for reference.
`currentPosition`	`number`	Current playback position of the reported track.
`duration`	`number`	The known duration of the reported track. For streams or malformed MP3's, this value will be 0.
`playbackPercent`	`number`	Progress of track playback, as a percent, in the range 0 - 100
`bufferPercent`	`number`	Buffering progress of the track, as a percent, in the range 0 - 100
`bufferStart`	`number`	The starting position of the buffering progress. For now, this is always reported as 0.
`bufferEnd`	`number`	The maximum position, in seconds, of the track buffer. For now, only the buffer with the maximum playback position is reported, even if there are other segments (due to seeking, for example). Practically speaking you don't need to worry about that, as in both implementations the minor gaps are automatically filled in by the underlying players.

OnStatusTrackChangedData

Reports information about the playlist state when a track changes. Includes the new track, its index, and the state of the playlist.

Prop	Type	Description
`currentItem`	`AudioTrack`	The new track that has been selected. May be null if you are at the end of the playlist, or the playlist has been emptied.
`currentIndex`	`number`	The 0-based index of the new track. If the playlist has ended or been cleared, this will be -1.
`isAtEnd`	`boolean`	Indicates whether the playlist is now currently at the last item in the list.
`isAtBeginning`	`boolean`	Indicates whether the playlist is now at the first item in the list
`hasNext`	`boolean`	Indicates if there are additional playlist items after the current item.
`hasPrevious`	`boolean`	Indicates if there are any items before this one in the playlist.

AudioTrack

An audio track for playback by the playlist.

Prop	Type	Description
`isStream`	`boolean`	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`	`string`	trackId is optional and if not passed in, an auto-generated UUID will be used.
`assetUrl`	`string`	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`	`string`	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`	`string`	The track's artist
`album`	`string`	Album the track belongs to
`title`	`string`	Title of the track

OnStatusErrorCallbackData

Represents an error reported by the onStatus callback.

Prop	Type	Description
`code`	`RmxAudioErrorType`	Error code
`message`	`string`	The error, as a message

AudioPlayerOptions

Options governing the overall behavior of the audio player plugin

Prop	Type	Description
`verbose`	`boolean`	Should the plugin's javascript dump the status message stream to the javascript console?
`resetStreamOnPause`	`boolean`	If true, when pausing a live stream, play will continue from the LIVE POSITION (e.g. the stream jumps forward to the current point in time, rather than picking up where it left off when you paused). If false, the stream will continue where you paused. The drawback of doing this is that when the audio buffer fills, it will jump forward to the current point in time, cause a disjoint in playback. Default is true.
`options`	`NotificationOptions`	Further options for notifications

NotificationOptions

Prop	Type
`icon`	`string`

PlaylistOptions

Prop	Type
`items`	`Array<AudioTrack>`
`options`	`PlaylistItemOptions`

Array

Prop	Type	Description
`length`	`number`	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	() => string	Returns a string representation of an array.
toLocaleString	() => string	Returns a string representation of an array. The elements are converted to string using their toLocalString methods.
pop	() => 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[]) => number	Appends new elements to the end of an array, and returns the new length of the array.
concat	(...items: ConcatArray<T>[]) => T[]	Combines two or more arrays. This method returns a new array without modifying any existing arrays.
concat	(...items: (T \| ConcatArray<T>)[]) => T[]	Combines two or more arrays. This method returns a new array without modifying any existing arrays.
join	(separator?: string \| undefined) => string	Adds all the elements of an array into a string, separated by the specified separator string.
reverse	() => T[]	Reverses the elements in an array in place. This method mutates the array and returns a reference to the same array.
shift	() => 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) => 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) => number) \| undefined) => 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) => 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[]) => T[]	Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements.
unshift	(...items: T[]) => number	Inserts new elements at the start of an array, and returns the new length of the array.
indexOf	(searchElement: T, fromIndex?: number \| undefined) => 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) => number	Returns the index of the last occurrence of a specified value in an array, or -1 if it is not present.
every	<S extends T>(predicate: (value: T, index: number, array: T[]) => value is S, thisArg?: any) => this is S[]	Determines whether all the members of an array satisfy the specified test.
every	(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any) => boolean	Determines whether all the members of an array satisfy the specified test.
some	(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any) => boolean	Determines whether the specified callback function returns true for any element of an array.
forEach	(callbackfn: (value: T, index: number, array: T[]) => void, thisArg?: any) => void	Performs the specified action for each element in an array.
map	<U>(callbackfn: (value: T, index: number, array: T[]) => U, thisArg?: any) => U[]	Calls a defined callback function on each element of an array, and returns an array that contains the results.
filter	<S extends T>(predicate: (value: T, index: number, array: T[]) => value is S, thisArg?: any) => S[]	Returns the elements of an array that meet the condition specified in a callback function.
filter	(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any) => 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[]) => T) => 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[]) => T, initialValue: T) => T
reduce	<U>(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U) => 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[]) => T) => 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[]) => T, initialValue: T) => T
reduceRight	<U>(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U) => 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`	`number`

Method	Signature
join	(separator?: string \| undefined) => string
slice	(start?: number \| undefined, end?: number \| undefined) => T[]

PlaylistItemOptions

Options governing how the items are managed when using setPlaylistItems to update the playlist. This is typically useful if you are retaining items that were in the previous list.

Prop	Type	Description
`retainPosition`	`boolean`	If true, the plugin will continue playback from the current playback position after setting the items to the playlist.
`playFromPosition`	`number`	If retainPosition is true, this value will tell the plugin the exact time to start from, rather than letting the plugin decide based on current playback.
`playFromId`	`string`	If retainPosition is true, this value will tell the plugin the uid of the "current" item to start from, rather than letting the plugin decide based on current playback.
`startPaused`	`boolean`	If playback should immediately begin when calling setPlaylistItems on the plugin. Default is false;

AddItemOptions

Prop	Type
`item`	`AudioTrack`

AddAllItemOptions

Prop	Type
`items`	`Array<AudioTrack>`

RemoveItemOptions

Prop	Type
`id`	`string`
`index`	`number`

RemoveItemsOptions

Prop	Type
`items`	`Array<RemoveItemOptions>`

GetPlaylistResult

Prop	Type
`items`	`Array<AudioTrack>`

SeekToOptions

Prop	Type
`position`	`number`

PlayByIndexOptions

Prop	Type
`index`	`number`
`position`	`number`

PlayByIdOptions

Prop	Type
`id`	`string`
`position`	`number`

SelectByIndexOptions

Prop	Type
`index`	`number`
`position`	`number`

SelectByIdOptions

Prop	Type
`id`	`string`
`position`	`number`

SetPlaybackVolumeOptions

Prop	Type
`volume`	`number`

SetLoopOptions

Prop	Type
`loop`	`boolean`

SetPlaybackRateOptions

Prop	Type
`rate`	`number`

ResumeAfterVideoHandoffResult

Prop	Type	Description
`resumed`	`boolean`	`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`.

ResumeAfterVideoHandoffOptions

Prop	Type	Description
`position`	`number`	Resume position in seconds (video exit head or saved audio position).
`prewarm`	`boolean`	Android only. When `true`, promote `MediaService` to foreground and prepare at `position` without requesting audio focus or playing audio. Use immediately after `prepareForVideoHandoff` and before native video starts, while the app is still foregrounded. Ignored on iOS (no-op). Not applicable on web.
`play`	`boolean`	When `true`, native starts audible playback after seeking to `position`. When `false` (paused video exit), native must not start playback. iOS defaults to `false` when omitted; Android defaults to `true` for legacy callers.

GetLastKnownPositionResult

Prop	Type
`position`	`number`

Type Aliases

PlaylistStatusChangeCallback

(data: PlaylistStatusChangeCallbackArg): void

Enums

RmxAudioStatusMessage

Members	Value	Description
`RMXSTATUS_NONE`	`0`	The starting state of the plugin. You will never see this value; it changes before the callbacks are even registered to report changes to this value.
`RMXSTATUS_REGISTER`	`1`	Raised when the plugin registers the callback handler for onStatus callbacks. You will probably not be able to see this (nor do you need to).
`RMXSTATUS_INIT`	`2`	Reserved for future use
`RMXSTATUS_ERROR`	`5`	Indicates an error is reported in the 'value' field.
`RMXSTATUS_LOADING`	`10`	The reported track is being loaded by the player
`RMXSTATUS_CANPLAY`	`11`	The reported track is able to begin playback
`RMXSTATUS_LOADED`	`15`	The reported track has loaded 100% of the file (either from disc or network)
`RMXSTATUS_STALLED`	`20`	(iOS only): Playback has stalled due to insufficient network
`RMXSTATUS_BUFFERING`	`25`	Reports an update in the reported track's buffering status
`RMXSTATUS_PLAYING`	`30`	The reported track has started (or resumed) playing
`RMXSTATUS_PAUSE`	`35`	The reported track has been paused, either by the user or by the system. (iOS only): This value is raised when MP3's are malformed (but still playable). These require the user to explicitly press play again. This can be worked around and is on the TODO list.
`RMXSTATUS_PLAYBACK_POSITION`	`40`	Reports a change in the reported track's playback position.
`RMXSTATUS_SEEK`	`45`	The reported track has seeked. On Android, only the plugin consumer can generate this (Notification controls on Android do not include a seek bar). On iOS, the Command Center includes a seek bar so this will be reported when the user has seeked via Command Center.
`RMXSTATUS_COMPLETED`	`50`	The reported track has completed playback.
`RMXSTATUS_DURATION`	`55`	The reported track's duration has changed. This is raised once, when duration is updated for the first time. For streams, this value is never reported.
`RMXSTATUS_STOPPED`	`60`	All playback has stopped, probably because the plugin is shutting down.
`RMX_STATUS_SKIP_FORWARD`	`90`	The playlist has skipped forward to the next track. On both Android and iOS, this will be raised if the notification controls/Command Center were used to skip. It is unlikely you need to consume this event: RMXSTATUS_TRACK_CHANGED is also reported when this occurs, so you can generalize your track change handling in one place.
`RMX_STATUS_SKIP_BACK`	`95`	The playlist has skipped back to the previous track. On both Android and iOS, this will be raised if the notification controls/Command Center were used to skip. It is unlikely you need to consume this event: RMXSTATUS_TRACK_CHANGED is also reported when this occurs, so you can generalize your track change handling in one place.
`RMXSTATUS_TRACK_CHANGED`	`100`	Reported when the current track has changed in the native player. This event contains full data about the new track, including the index and the actual track itself. The type of the 'value' field in this case is OnStatusTrackChangedData.
`RMXSTATUS_PLAYLIST_COMPLETED`	`105`	The entire playlist has completed playback. After this event has been raised, the current item is set to null and the current index to -1.
`RMXSTATUS_ITEM_ADDED`	`110`	An item has been added to the playlist. For the setPlaylistItems and addAllItems methods, this status is raised once for every track in the collection.
`RMXSTATUS_ITEM_REMOVED`	`115`	An item has been removed from the playlist. For the removeItems and clearAllItems methods, this status is raised once for every track that was removed.
`RMXSTATUS_PLAYLIST_CLEARED`	`120`	All items have been removed from the playlist
`RMXSTATUS_VIEWDISAPPEAR`	`200`	Just for testing.. you don't need this and in fact can never receive it, the plugin is destroyed before it can be raised.

RmxAudioErrorType

Members	Value
`RMXERR_NONE_ACTIVE`	`0`
`RMXERR_ABORTED`	`1`
`RMXERR_NETWORK`	`2`
`RMXERR_DECODE`	`3`
`RMXERR_NONE_SUPPORTED`	`4`

Migrating from cordova-plugin-playlist

Use the shipped RmxAudioPlayer class — in the best case you only change your import:

// before
import { RmxAudioPlayer } from 'cordova-plugin-playlist';

// after
import { RmxAudioPlayer } from 'capacitor-plugin-playlist';

For new code or video handoff, prefer the Playlist plugin object directly.

Changes

See CHANGELOG.md for version history.

Credits

Inspired by:

License

The MIT License (MIT)

Name		Name	Last commit message	Last commit date
Latest commit History 333 Commits
.github/workflows		.github/workflows
android		android
docs		docs
examples		examples
ios		ios
src		src
.eslintignore		.eslintignore
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
CapacitorPluginPlaylist.podspec		CapacitorPluginPlaylist.podspec
Package.swift		Package.swift
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
rollup.config.mjs		rollup.config.mjs
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

capacitor-plugin-playlist

Index

Features

Playlist management

Playback controls

Native platform integration

Background audio

Tracks and sources

Status event stream

Video handoff

Cordova-compatible wrapper

Not supported

Background

Notes

Android

iOS

Installation

Web

Angular example

Android

AndroidManifest.xml

Gradle 9+

Glide (notification album art)

Notification icon

iOS

Usage

Basic flow (Playlist API)

RmxAudioPlayer wrapper (Cordova migration)

Events

Video handoff

Methods

Lifecycle

Basic sequence

Recommended Android sequence (with prewarm)

Platform behaviour

Position: audio vs video head

Integration checklist

Common pitfalls

API

addListener('status', ...)

setOptions(...)

initialize()

release()

setPlaylistItems(...)

addItem(...)

addAllItems(...)

removeItem(...)

removeItems(...)

clearAllItems()

getPlaylist()

play()

pause()

skipForward()

skipBack()

seekTo(...)

playTrackByIndex(...)

playTrackById(...)

selectTrackByIndex(...)

selectTrackById(...)

setPlaybackVolume(...)

setLoop(...)

setPlaybackRate(...)

prepareForVideoHandoff()

resumeAfterVideoHandoff(...)

getLastKnownPosition()

Interfaces

PluginListenerHandle

PlaylistStatusChangeCallbackArg

OnStatusCallbackData

OnStatusCallbackUpdateData

OnStatusTrackChangedData

AudioTrack

OnStatusErrorCallbackData

AudioPlayerOptions

NotificationOptions

PlaylistOptions

Basic flow (`Playlist` API)

`RmxAudioPlayer` wrapper (Cordova migration)