https://github.com/smartcompanion-app/native-audio-player
Play native audio from a Capacitor app
https://github.com/smartcompanion-app/native-audio-player
android audio audio-player background-audio capacitor capacitor-android capacitor-community capacitor-ios capacitor-plugin cross-platform ios
Last synced: 3 months ago
JSON representation
Play native audio from a Capacitor app
- Host: GitHub
- URL: https://github.com/smartcompanion-app/native-audio-player
- Owner: smartcompanion-app
- License: bsd-2-clause
- Created: 2025-03-15T15:25:02.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-02-07T22:17:48.000Z (5 months ago)
- Last Synced: 2026-02-08T05:51:57.860Z (5 months ago)
- Topics: android, audio, audio-player, background-audio, capacitor, capacitor-android, capacitor-community, capacitor-ios, capacitor-plugin, cross-platform, ios
- Language: Swift
- Homepage:
- Size: 1.26 MB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-capacitorjs - @smartcompanion/native-audio-player - Play audio that keeps playing in the background, player is shown in system controls, audio output can be switched between speaker/earpiece. (Plugins / Community Plugins)
- awesome-capacitor - Native Audio Player - Play audio that keeps playing in the background, player is shown in system controls, audio output can be switched between speaker/earpiece. (Other plugins / Specialized Hardware)
README
# 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](https://github.com/stefanhuber) | [Linkedin](https://www.linkedin.com/in/stefan-huber/) |
## Install
```bash
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](https://github.com/capacitor-community/native-audio)
- [@capawesome-team/capacitor-audio-player](https://capawesome.io/plugins/audio-player/)
- [@capgo/native-audio](https://github.com/Cap-go/capacitor-native-audio)
- [@mediagrid/capacitor-native-audio](https://github.com/mediagrid/capacitor-native-audio)
## API
* [`setEarpiece()`](#setearpiece)
* [`setSpeaker()`](#setspeaker)
* [`start(...)`](#start)
* [`stop()`](#stop)
* [`play()`](#play)
* [`pause()`](#pause)
* [`select(...)`](#select)
* [`next()`](#next)
* [`previous()`](#previous)
* [`seekTo(...)`](#seekto)
* [`getDuration()`](#getduration)
* [`getPosition()`](#getposition)
* [`addListener('update', ...)`](#addlistenerupdate-)
* [Interfaces](#interfaces)
### setEarpiece()
```typescript
setEarpiece() => Promise
```
Set the audio output to the earpiece.
--------------------
### setSpeaker()
```typescript
setSpeaker() => Promise
```
Set the audio output to the speaker.
--------------------
### start(...)
```typescript
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()
```typescript
stop() => Promise
```
Stop the currently playing audio item and clear the playlist.
--------------------
### play()
```typescript
play() => Promise
```
Play the currently selected audio item.
--------------------
### pause()
```typescript
pause() => Promise
```
Pause the currently playing audio item.
--------------------
### select(...)
```typescript
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()
```typescript
next() => Promise<{ id: string; }>
```
Skip to the next audio item in the playlist.
**Returns:** Promise<{ id: string; }>
--------------------
### previous()
```typescript
previous() => Promise<{ id: string; }>
```
Skip to the previous audio item in the playlist.
**Returns:** Promise<{ id: string; }>
--------------------
### seekTo(...)
```typescript
seekTo(options: { position: number; }) => Promise
```
Seek to a specific position in the currently playing audio item.
| Param | Type |
| ------------- | ---------------------------------- |
| **`options`** | { position: number; } |
--------------------
### getDuration()
```typescript
getDuration() => Promise<{ value: number; }>
```
Get the duration of the current audio item in seconds.
**Returns:** Promise<{ value: number; }>
--------------------
### getPosition()
```typescript
getPosition() => Promise<{ value: number; }>
```
Get the current position of the audio item in seconds.
**Returns:** Promise<{ value: number; }>
--------------------
### addListener('update', ...)
```typescript
addListener(eventName: 'update', listener: (result: { state: 'playing' | 'paused' | 'skip' | 'completed'; id: string; }) => void) => Promise
```
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> |