native-audio-player

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

• @capacitor-community/native-audio
• @capawesome-team/capacitor-audio-player
• @capgo/native-audio
• @mediagrid/capacitor-native-audio

API

• setEarpiece()
• setSpeaker()
• start(...)
• stop()
• play()
• pause()
• select(...)
• next()
• previous()
• seekTo(...)
• getDuration()
• getPosition()
• addListener('update', ...)
• Interfaces

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>