---
title: "Audio Player 8.4.0: Playlists and Media Session Support"
description: Capacitor Audio Player 8.4.0 adds playlist support and a built-in media session, bringing lock screen controls and background playback to your app.
date:
created: 2026-08-24
updated: 2026-08-24
authors:
- robingenz
categories:
- Announcements
- Capacitor
- SDKs
---
# Audio Player 8.4.0: Playlists and Media Session Support
Version 8.4.0 of the [Capacitor Audio Player plugin](../../sdks/capacitor/audio-player.md) adds the two features that turn it into a complete foundation for your own audio player: playlist support with native track advancement, and a built-in media session integration that puts your playback on the lock screen. Your users can now pause, resume, and switch tracks from the system's media controls, even while your app is in the background. Both features are available on Android, iOS, and Web, and the release is fully backward compatible.
## At a Glance
Audio Player 8.4.0 was released on August 15, 2026 and contains the following changes:
| Change | Platforms | API |
| ---------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Playlist support with native track advancement | Android, iOS, Web | [`play(...)`](../../sdks/capacitor/audio-player.md#play) with `tracks` and `startIndex` |
| Queue management during playback | Android, iOS, Web | [`addTracks(...)`](../../sdks/capacitor/audio-player.md#addtracks), [`removeTrack(...)`](../../sdks/capacitor/audio-player.md#removetrack) |
| Track navigation | Android, iOS, Web | [`skipToNextTrack()`](../../sdks/capacitor/audio-player.md#skiptonexttrack), [`skipToPreviousTrack()`](../../sdks/capacitor/audio-player.md#skiptoprevioustrack) |
| Repeat modes | Android, iOS, Web | [`setRepeatMode(...)`](../../sdks/capacitor/audio-player.md#setrepeatmode) |
| Media session integration | Android, iOS, Web | `metadata` option of [`play(...)`](../../sdks/capacitor/audio-player.md#play) |
| New events | Android, iOS, Web | [`playbackStateChanged`](../../sdks/capacitor/audio-player.md#addlistenerplaybackstatechanged-), [`trackChange`](../../sdks/capacitor/audio-player.md#addlistenertrackchange-) |
## Playlist Support
Since version 8.4.0, the Capacitor Audio Player plugin supports playlists: pass multiple tracks to [`play(...)`](../../sdks/capacitor/audio-player.md#play) and the plugin advances through them natively. The next track starts automatically when the current one ends, even while your app is in the background. Previously, you could only hand the plugin one source at a time, which meant detecting the end of a track in JavaScript and starting the next one from there — exactly the kind of logic that fails once the operating system suspends the web view.
Starting a playlist takes a single call, with an optional `startIndex` to begin somewhere other than the first track:
```typescript
import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';
const playPlaylist = async () => {
await AudioPlayer.play({
tracks: [
{ src: '/assets/audio/track-1.mp3' },
{ src: 'https://example.com/track-2.mp3' },
{ src: 'https://example.com/track-3.mp3' },
],
startIndex: 0,
});
};
```
Each track accepts the same source options as single playback: `src` for web assets and remote URLs, `uri` for files on the device (Android and iOS), or `blob` on the Web.
The queue is not fixed once playback starts. [`addTracks(...)`](../../sdks/capacitor/audio-player.md#addtracks) appends tracks to the queue or inserts them at a specific index, which is all you need for "play next" and "add to queue" actions:
```typescript
import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';
const addToQueue = async () => {
await AudioPlayer.addTracks({
tracks: [{ src: 'https://example.com/track-4.mp3' }],
});
};
```
Its counterpart [`removeTrack(...)`](../../sdks/capacitor/audio-player.md#removetrack) removes a track by index; if you remove the one currently playing, playback continues with the track that takes its place.
For navigation, [`skipToNextTrack()`](../../sdks/capacitor/audio-player.md#skiptonexttrack) and [`skipToPreviousTrack()`](../../sdks/capacitor/audio-player.md#skiptoprevioustrack) move through the queue, [`seekTo(...)`](../../sdks/capacitor/audio-player.md#seekto) accepts a new `index` option to jump directly to a track (optionally combined with a `position` within it), and [`getCurrentTrackIndex()`](../../sdks/capacitor/audio-player.md#getcurrenttrackindex) tells you where the playback currently is. [`setRepeatMode(...)`](../../sdks/capacitor/audio-player.md#setrepeatmode) rounds this out with three modes: `NONE`, `ONE` to repeat the current track, and `ALL` to restart the queue from the beginning, in which case the skip methods also wrap around at both ends.
To keep your UI in step with the queue, the new [`trackChange`](../../sdks/capacitor/audio-player.md#addlistenertrackchange-) event reports the index of every track that starts playing. It fires on manual skips and on native auto-advance alike, so your "now playing" view stays correct without polling.
## Built-In Media Session Integration
The second headline feature is the new `metadata` option. Provide a title, artist, album, and artwork for a track, and the plugin activates its media session integration: the system's media controls display your playback in the notification and on the lock screen, where the user can control it even while your app is in the background.
```typescript
import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';
const playWithMetadata = async () => {
await AudioPlayer.play({
tracks: [
{
src: 'https://example.com/track-1.mp3',
metadata: {
title: 'First Track',
artist: 'Some Artist',
album: 'Some Album',
artworkSource: '/assets/artwork.png',
},
},
{
src: 'https://example.com/track-2.mp3',
metadata: {
title: 'Second Track',
artist: 'Some Artist',
album: 'Some Album',
artworkSource: '/assets/artwork.png',
},
},
],
});
};
```
The `artworkSource` accepts a web asset path or a remote URL. On iOS, the next and previous track buttons appear when the playlist contains more than one track; a single track shows play, pause, and the position slider.
What makes this integration different from wiring up a media session yourself is where it runs. The plugin registers the session natively — a Media3 `MediaSessionService` on Android, the remote command center on iOS, and the Media Session API on the Web — so no control event ever takes a round trip through your JavaScript code. When the user taps the skip button on the lock screen, the native player reacts directly, whether the web view is awake or not.
Since control can now come from outside your app, the new [`playbackStateChanged`](../../sdks/capacitor/audio-player.md#addlistenerplaybackstatechanged-) event tells you about every state transition, for example when the user pauses the playback from the lock screen:
```typescript
import {
AudioPlayer,
PlaybackState,
} from '@capawesome-team/capacitor-audio-player';
const listenForPlaybackStateChanges = async () => {
await AudioPlayer.addListener('playbackStateChanged', (event) => {
const isPlaying = event.state === PlaybackState.Playing;
// Update your play/pause button here.
});
};
```
On Android, the media session requires a service declaration and two foreground service permissions in your `AndroidManifest.xml`; you can find the exact entries in the [Media Session](../../sdks/capacitor/audio-player.md/#media-session) setup section of the plugin documentation. On iOS, nothing changes beyond the `Background Modes` capability with `Audio` that background playback already required.
### Do You Still Need the Media Session Plugin?
Not for native audio playback. The [Capacitor Media Session plugin](../../sdks/capacitor/media-session.md) relays media control events to your JavaScript code, which is the right design for playback that runs inside the web view, such as HTML5 `
