Audio Player (Mobile) supports single tracks, playlists, albums, podcasts, courses, and audio libraries. It can be used as a full player, a mini player, or a hidden playback engine controlled through Bubble workflows.
## Demo App Editor

A configured test app is available for reviewing the Audio Player (Mobile) plugin setup, workflows, controls, playlist configuration, and mobile view implementation.

.................

**Bubble Editor Test App:**
https://bubble.io/page?id=ankhsmobile&app_type=mobile&tab=Design&name=Audio+Player&version=live&type=page


The test view is named **Audio Player**. It includes the AudioPlayer element, playlist setup, playback controls, queue controls, progress tracking actions, collection actions, and navigation testing.

For the public run-mode demo, use the Marketplace Demo page link.

.................


## Audio Source Setup

### Playlist or database list

Use **Playlist URLs** as the main audio source. Connect it to a dynamic list of direct audio file URLs.

For reliable metadata and progress tracking, also connect these optional lists in the exact same order:

* Playlist Track IDs
* Playlist Titles
* Playlist Artists
* Playlist Artwork URLs

Example:

* Playlist URLs = Search for Songs: each item’s audio file
* Playlist Track IDs = Search for Songs: each item’s unique ID
* Playlist Titles = Search for Songs: each item’s title
* Playlist Artists = Search for Songs: each item’s artist
* Playlist Artwork URLs = Search for Songs: each item’s cover image

No JSON is required.

### Single audio track

Use **Audio source URL**. You may also add Track Title, Artist, Album, and Artwork URL.

## Main Settings

Configure the player in this order:

1. Audio source or Playlist URLs
2. Track IDs and metadata lists
3. Autoplay, autoplay next, loop, shuffle, speed, and volume
4. Progress tracking and Collection ID
5. Player display settings
6. Colors, artwork, controls, and visualizer settings

Useful playback settings include:

* Autoplay
* Autoplay next
* Loop mode: Off, One, or All
* Shuffle
* Playback rate
* Volume
* Start muted
* Start position
* Seek step
* Fade in and fade out
* Crossfade
* Sleep timer

## Full Player and Mini Player

Use the full player for the complete listening experience with artwork, title, artist, waveform, time, visualizer, and controls.

Enable Mini Player mode for a compact player that can be placed in a reusable element, floating group, bottom navigation area, Home view, or another mobile view.

Multiple player elements can reflect the same active playback session. This allows a full player on one view and a mini player on another view.

## Progress and Completion Tracking

Set a stable **Collection ID** for each album, show, playlist, course, or series.

Examples:

* founder-mode-album
* podcast-season-1
* physics-course
* show-unique-id

The plugin can track:

* Current position
* Duration
* Progress percentage
* Current track
* Queue position
* Played and unplayed tracks
* Saved resume position
* Collection completion percentage
* Completed albums, shows, and playlists

Use Playlist Track IDs whenever possible. This ensures progress remains connected to the correct audio item even if URLs change.

## Important Workflow Actions

Use Bubble workflows to control the player.

### Playback

* Play
* Pause
* Stop
* Toggle play/pause
* Replay
* Seek to
* Skip forward or back
* Set volume
* Mute or unmute

### Playlist and Queue

* Load source
* Load playlist
* Next track
* Previous track
* Jump to track
* Toggle shuffle
* Add, remove, move, or clear queue items
* Set collection

### Progress

* Mark current track played
* Mark current track unplayed
* Save position
* Restore position
* Reset collection progress
* Get track information

### Advanced Features

* Set loop mode
* Set playback rate
* Create A-B loops
* Add chapters and bookmarks
* Start sleep timer
* Cache audio for offline use
* Set fades and crossfade

## Useful States and Events

Use states such as:

* Is playing
* Is loaded
* Is buffering
* Progress
* Position
* Duration
* Current track title
* Current track artist
* Current track artwork
* Queue length
* Current index
* Loop mode
* Shuffle state
* Error

Use events such as:

* Playback started
* Playback paused
* Track changed
* Playback ended
* Queue ended
* Position changed
* Track marked played
* Collection completed
* Error occurred

These can be used for analytics, database updates, completed badges, recently played lists, and custom controls.

## Background Playback

Enable **Background playback** and **Play in silent mode** where needed.

Also enable **Background audio playback** in your Bubble native mobile app settings.

The player can continue across mobile view navigation while the app remains open. Test background playback, lock screen behavior, audio interruptions, and cross-view syncing on a real iOS or Android device. Browser preview cannot fully test native audio behavior.

## Device Test Checklist

Before publishing, test:

* Single audio playback
* Playlist playback
* Play, pause, next, previous, shuffle, loop, mute, and volume
* Seek bar dragging
* Autoplay next
* Mini player and full player syncing
* Navigation between views while audio continues
* Background playback
* Resume position
* Track and collection completion
* Invalid audio URL handling

.................

## v1.10.0 — Expo SDK 57 Upgrade

This release upgrades Audio Player (Mobile) for Bubble's Expo SDK 57 mobile runtime while preserving existing fields, states, events, actions, and workflows.

### Background and lock-screen playback

* Multi-track queues use the native mobile playback queue while the app is backgrounded or the screen is locked/off when Background Playback is enabled.
* Background queue advancement is owned natively so track-to-track autoplay does not depend on Bubble JavaScript staying awake. System media/Now Playing integration is feature-detected per platform/runtime; verify the controls required by your app on a fresh iOS or Android build.
* Queue completion and played-history tracking remain conservative so manual skips are not automatically treated as genuine 100% completion.

### Reliability

* Improved audio-session recovery, buffering and reconnect behavior across background/foreground transitions and temporary interruptions.
* Better native queue handoff and return-to-app synchronization, reducing duplicate playback and stale position/index states.

### Animation and UI performance

* Compatible native views use the upgraded animation runtime for transport feedback, artwork fade/rotation, mini-player entrance and title marquee.
* Existing animation behavior remains available as a safe fallback where the native path is unavailable.

### Compatibility

No new keys, dependencies, permissions, or workflow migrations are required. Existing apps can upgrade in place.

### Recommended device verification

Before a production app rollout, test screen-off auto-next, lock-screen controls, background-to-foreground return, shuffle/loop, animated artwork/mini player, and multiple player views on the iOS and Android devices you support.

### Background startup reliability

* On a cold start or after the audio session needs to be reclaimed, background-capable playback waits for the mobile audio session to finish configuring before foreground playback starts.
* Rapid Play, Pause, Stop, and queue replacement actions are protected against stale delayed starts, reducing duplicate or unexpected playback during startup.
* Audio-session readiness is revalidated after lifecycle changes and interruptions instead of being assumed permanently ready.
* These protections preserve the native background queue and lock-screen handoff used for screen-off autoplay.

For production background playback, the host Bubble mobile app must still have **Background audio playback** enabled and must be rebuilt after that native capability is enabled. Test the fresh iOS or Android build with the display fully off; an older installed/TestFlight binary cannot gain the native background capability from a plugin-only update.

### Autoplay and SDK 57 background ownership

* When **Autoplay** is enabled and a valid playlist is supplied, the first requested queue item starts automatically after the SDK 57 audio session is ready.
* Turning Autoplay from off to on for an already-loaded queue starts that queue once. Ordinary Bubble rerenders do not restart a queue that the user intentionally paused.
* Re-delivering the same playlist refreshes queue metadata/states without creating a false play intent or reviving stale playback.
* With **Autoplay next** enabled, foreground completion advances to the next queue item. Eligible multi-track background queues use the native AudioPlaylist path so track 1 → 2 → 3 advancement can continue without Bubble JavaScript running at each boundary.
* **Loop all** is mirrored into the native background queue. **Loop one** and A-B loop remain foreground-managed.
* Shuffle order is mirrored into the native background queue and is reconciled back to the foreground index/position when the app becomes active again.
* Bubble's SDK 57 / expo-audio 57.0.3 predates playlist lock-screen controls. For eligible multi-track background queues, AudioPlaylist remains the audible native queue while the already-working AudioPlayer is kept as a silent media-session/background anchor. If a future runtime exposes playlist lock-screen ownership, the plugin can use it through capability detection.
* The silent AudioPlayer anchor follows background play/pause and track changes, is excluded from Bubble progress/completion accounting, and is released when background ownership ends.
* SDK 57 audio-session configuration uses the supported `doNotMix` interruption mode and guards delayed Play completions so Pause, Stop, or queue replacement cannot later resurrect playback.
* Queue runtime publications are aligned with the Bubble definitions for Queue track IDs, Queue artists, Queue artwork URLs, and the queue-changed event.

### v1.11.1 - Multi-track background ownership hotfix

* Multi-track background playback preserves the SDK 57 AudioPlayer media / Now Playing owner while AudioPlaylist owns the audible native queue and native auto-advance.
* The AudioPlayer anchor stays silent and registered during native queue ownership so background media-session continuity is not discarded merely because the queue contains multiple tracks.
* Existing Bubble fields, states, events, actions, queue metadata, and stable IDs remain unchanged.

### v1.11.2 - Readiness-safe multi-track background handoff

* Eligible multi-track native queues are prepared while the app is still foregrounded, instead of being created only as the operating system begins suspending the app.
* During lock/background transfer, the already-working AudioPlayer remains audible until AudioPlaylist reports actual native playback and is no longer buffering.
* Only after native playback is proven does the plugin silence the AudioPlayer anchor and expose native-queue volume, preventing the immediate-silence race with remote media and avoiding duplicate audible streams.
* If the native queue errors, is cancelled, or cannot prove readiness, the established AudioPlayer remains the audible fallback instead of being muted prematurely.
* After a successful SDK 57 handoff, AudioPlaylist remains the audible native queue and auto-advance engine while the existing AudioPlayer stays silent and registered as the background / Now Playing proxy.
* The silent proxy mirrors supported play/pause and current-track changes without contributing audible output or duplicate Bubble progress/completion events.
* If a future runtime exposes playlist lock-screen ownership, that path is used only when the API is actually present. Exact system-control presentation remains operating-system dependent.
* Existing Bubble fields, states, events, actions, dependencies, permissions, and stable IDs remain unchanged.

### Native build requirement

Background/screen-off behavior depends on native app capabilities. **Background audio playback** must be enabled in the Bubble mobile app settings before building the app. If that capability was enabled after an installed/TestFlight build was created, build and install a fresh binary before evaluating background or screen-off playback. Plugin code alone cannot retrofit native entitlements into an older installed binary.

Browser preview is suitable for startup and public-state/event smoke checks, but it cannot prove screen-off playback, operating-system audio-session continuity, or lock-screen media controls.

### Advanced behavior note

A-B loop remains foreground-managed. Exact sleep-timer expiry may be delayed if the operating system fully suspends the app.

Built with 🤍 by ANKHARA Studios.