native-audio-player

February 1, 2026 · View on GitHub

Play native audio from a Capacitor app.

✨ Features

🔈 Toggle between Speaker and Earpiece as audio output
🎶 Audio keeps playing in the background, when app is minimized
🔓 Native players in notifications and lock screens
📱 Support for Android, iOS, Web (only Speaker)

Maintainers

Maintainer	GitHub	Social
Stefan Huber	stefanhuber	Linkedin

Install

npm install @smartcompanion/native-audio-player
npx cap sync

Configuration

Platform	Configuration
iOS	Audio has to be added as Background Mode within Signing & Capabilities of the app, in order to keep audio playing in the background
Android	The plugin has a `AndroidManifest.xml`, which includes all configurations

Usage

In folder ./example a full usage example is available. This example is also used for automated and manual testing.

Demo App	Native Audio Player

Other Audio Player Plugins

setEarpiece()

setEarpiece() => Promise<void>

Set the audio output to the earpiece.

setSpeaker()

setSpeaker() => Promise<void>

Set the audio output to the speaker.

start(...)

start(options: StartOptions) => Promise<{ id: string; }>

Initialize the audio player with a list of audio items.

Param	Type	Description
`options`	`StartOptions`	- The options for starting the audio player.

Returns: Promise<{ id: string; }>

stop()

stop() => Promise<void>

Stop the currently playing audio item and clear the playlist.

play()

play() => Promise<void>

Play the currently selected audio item.

pause()

pause() => Promise<void>

Pause the currently playing audio item.

select(...)

select(options: { id: string; }) => Promise<{ id: string; }>

Select an audio item from the playlist by its id.

Param	Type
`options`	`{ id: string; }`

Returns: Promise<{ id: string; }>

next()

next() => Promise<{ id: string; }>

Skip to the next audio item in the playlist.

Returns: Promise<{ id: string; }>

previous()

previous() => Promise<{ id: string; }>

Skip to the previous audio item in the playlist.

Returns: Promise<{ id: string; }>

seekTo(...)

seekTo(options: { position: number; }) => Promise<void>

Seek to a specific position in the currently playing audio item.

Param	Type
`options`	`{ position: number; }`

getDuration()

getDuration() => Promise<{ value: number; }>

Get the duration of the current audio item in seconds.

Returns: Promise<{ value: number; }>

getPosition()

getPosition() => Promise<{ value: number; }>

Get the current position of the audio item in seconds.

Returns: Promise<{ value: number; }>

addListener('update', ...)

addListener(eventName: 'update', listener: (result: { state: 'playing' | 'paused' | 'skip' | 'completed'; id: string; }) => void) => Promise<PluginListenerHandle>

Add an event listener for the update event. The listener should accept an event object containing the current state and id of the audio item.

Param	Type
`eventName`	`'update'`
`listener`	`(result: { state: 'playing' \| 'paused' \| 'skip' \| 'completed'; id: string; }) => void`

Returns: Promise<PluginListenerHandle>

Interfaces

StartOptions

Options for starting the audio player.

Prop	Type	Description
`items`	`Item[]`	A list of audio items to be initialized in the audio player.

Item

Represents an audio item in the playlist.

Prop	Type	Description
`id`	`string`	The unique identifier for the audio item.
`title`	`string`	The title of the audio item, which is e.g. displayed in the notification player.
`subtitle`	`string`	The subtitle of the audio item, which is e.g. displayed in the notification player.
`audioUri`	`string`	The local file URI of the audio file.
`imageUri`	`string`	The local file URI of the image associated with the audio item.

PluginListenerHandle

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