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 manual testing.

| Demo App | Native Audio Player | |---|---| | | |

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