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

1. Features
2. Background
3. Notes
4. Installation
5. Usage
6. Events
7. Video handoff
8. API
9. Migrating from cordova-plugin-playlist
10. Changes
11. Credits
12. License

Features

Playlist management

• setPlaylistItems — replace entire playlist (optional position retention)
• addItem / addAllItems — append tracks; addItem accepts optional insert index (“play next”)
• moveItem — reorder without disrupting current playback
• replaceItem — swap track metadata/URL in place (e.g. stream → offline file)
• 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

Background audio

• Android: foreground media service with WAKE_LOCK, FOREGROUND_SERVICE, 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
• Audio ads / IMA integration (#71)
• 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

From 0.11.0, the plugin library manifest merges the media playback service and required permissions into your app automatically:

• android.permission.WAKE_LOCK
• android.permission.FOREGROUND_SERVICE
• android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK
• org.dwbn.plugins.playlist.service.MediaService (exported="false", foregroundServiceType="mediaPlayback")

After upgrading, run npx cap sync android. You do not need to copy these entries into your host AndroidManifest.xml unless you want to override plugin defaults.

Keep your application's existing Android Application class. The legacy org.dwbn.plugins.playlist.App class remains available for compatibility, but it is no longer required — remove android:name="org.dwbn.plugins.playlist.App" from <application> when upgrading from older setups.

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)

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

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

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

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

Common pitfalls

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

API

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

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

initialize() => Promise<void>

release() => Promise<void>

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

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

moveItem(options: MoveItemOptions) => Promise<void>

replaceItem(options: ReplaceItemOptions) => Promise<void>

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

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

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

clearAllItems() => Promise<void>

getPlaylist() => Promise<GetPlaylistResult>

play() => Promise<void>

pause() => Promise<void>

skipForward() => Promise<void>

skipBack() => Promise<void>

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

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

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

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

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

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

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

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

prepareForVideoHandoff() => Promise<void>

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

getLastKnownPosition() => Promise<GetLastKnownPositionResult>

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:

• cordova-plugin-playlist
• cordova-plugin-media
• ExoMedia
• PlaylistCore
• Bi-Directional AVQueuePlayer
• cordova-music-controls-plugin

License

The MIT License (MIT)