Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mediagrid/capacitor-native-audio
Play audio in a Capacitor app natively from a URL/web source simultaneously with background audio and background play support.
https://github.com/mediagrid/capacitor-native-audio
android audio audio-player capacitor capacitor-android capacitor-ios capacitor-plugin ios
Last synced: 28 days ago
JSON representation
Play audio in a Capacitor app natively from a URL/web source simultaneously with background audio and background play support.
- Host: GitHub
- URL: https://github.com/mediagrid/capacitor-native-audio
- Owner: mediagrid
- License: mit
- Created: 2024-07-18T17:34:51.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2024-12-13T20:41:48.000Z (about 1 month ago)
- Last Synced: 2024-12-13T21:26:51.418Z (about 1 month ago)
- Topics: android, audio, audio-player, capacitor, capacitor-android, capacitor-ios, capacitor-plugin, ios
- Language: Java
- Homepage:
- Size: 3.45 MB
- Stars: 13
- Watchers: 2
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# @mediagrid/capacitor-native-audio
## Description
Play audio in a Capacitor app natively (Android/iOS) from a URL/web source simultaneously with background audio. Also supports background playing with an OS notification.
## Install
```bash
npm install @mediagrid/capacitor-native-audio
npx cap sync
```
## Android
### `AndroidManifest.xml` required changes
Located at `android/app/src/main/AndroidManifest.xml`
```xml
```
### `strings.xml` required changes
Located at `android/app/src/main/res/values/strings.xml`
```xml
Allows for audio to play in the background.
```
# iOS
## Enable Audio Background Mode
This can be done in XCode or by editing `Info.plist` directly.
```xml
UIBackgroundModes
audio
```
## Add Now Playing Icon (optional) - DEPRECATED
⚠️⚠️ This is DEPRECATED. Use `artworkSource` now. ⚠️⚠️
If you would like a now playing icon to show in the iOS notification, add an image with the name `NowPlayingIcon` to your Asset catalog. See [Managing assets with asset catalogs](https://developer.apple.com/documentation/xcode/managing-assets-with-asset-catalogs) on how to add a new asset.
A PNG is recommended with the size of 1024 x 1024px. The same image can be used for the three different Asset wells (1x, 2x, 3x).
# API
* [`create(...)`](#create)
* [`initialize(...)`](#initialize)
* [`changeAudioSource(...)`](#changeaudiosource)
* [`changeMetadata(...)`](#changemetadata)
* [`getDuration(...)`](#getduration)
* [`getCurrentTime(...)`](#getcurrenttime)
* [`play(...)`](#play)
* [`pause(...)`](#pause)
* [`seek(...)`](#seek)
* [`stop(...)`](#stop)
* [`setVolume(...)`](#setvolume)
* [`setRate(...)`](#setrate)
* [`isPlaying(...)`](#isplaying)
* [`destroy(...)`](#destroy)
* [`onAppGainsFocus(...)`](#onappgainsfocus)
* [`onAppLosesFocus(...)`](#onapplosesfocus)
* [`onAudioReady(...)`](#onaudioready)
* [`onAudioEnd(...)`](#onaudioend)
* [`onPlaybackStatusChange(...)`](#onplaybackstatuschange)
* [Interfaces](#interfaces)
### create(...)
```typescript
create(params: AudioPlayerPrepareParams) => Promise<{ success: boolean; }>
```
Create an audio source to be played.
| Param | Type |
| ------------ | ----------------------------------------------------------------------------- |
| **`params`** | AudioPlayerPrepareParams |
**Returns:** Promise<{ success: boolean; }>
**Since:** 1.0.0
--------------------
### initialize(...)
```typescript
initialize(params: AudioPlayerDefaultParams) => Promise<{ success: boolean; }>
```
Initialize the audio source. Prepares the audio to be played, buffers and such.
Should be called after callbacks are registered (e.g. `onAudioReady`).
| Param | Type |
| ------------ | ----------------------------------------------------------------------------- |
| **`params`** | AudioPlayerDefaultParams |
**Returns:** Promise<{ success: boolean; }>
**Since:** 1.0.0
--------------------
### changeAudioSource(...)
```typescript
changeAudioSource(params: AudioPlayerDefaultParams & { source: string; }) => Promise
```
Change the audio source on an existing audio source (`audioId`).
This is useful for changing background music while the primary audio is playing
or changing the primary audio before it is playing to accommodate different durations
that a user can choose from.
| Param | Type |
| ------------ | --------------------------------------------------------------------------------------------------- |
| **`params`** | AudioPlayerDefaultParams & { source: string; } |
**Since:** 1.0.0
--------------------
### changeMetadata(...)
```typescript
changeMetadata(params: AudioPlayerDefaultParams & { friendlyTitle?: string; artworkSource?: string; }) => Promise
```
Change the associated metadata of an existing audio source
| Param | Type |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| **`params`** | AudioPlayerDefaultParams & { friendlyTitle?: string; artworkSource?: string; } |
**Since:** 1.1.0
--------------------
### getDuration(...)
```typescript
getDuration(params: AudioPlayerDefaultParams) => Promise<{ duration: number; }>
```
Get the duration of the audio source.
Should be called once the audio is ready (`onAudioReady`).
| Param | Type |
| ------------ | ----------------------------------------------------------------------------- |
| **`params`** | AudioPlayerDefaultParams |
**Returns:** Promise<{ duration: number; }>
**Since:** 1.0.0
--------------------
### getCurrentTime(...)
```typescript
getCurrentTime(params: AudioPlayerDefaultParams) => Promise<{ currentTime: number; }>
```
Get the current time of the audio source being played.
| Param | Type |
| ------------ | ----------------------------------------------------------------------------- |
| **`params`** | AudioPlayerDefaultParams |
**Returns:** Promise<{ currentTime: number; }>
**Since:** 1.0.0
--------------------
### play(...)
```typescript
play(params: AudioPlayerDefaultParams) => Promise
```
Play the audio source.
| Param | Type |
| ------------ | ----------------------------------------------------------------------------- |
| **`params`** | AudioPlayerDefaultParams |
**Since:** 1.0.0
--------------------
### pause(...)
```typescript
pause(params: AudioPlayerDefaultParams) => Promise
```
Pause the audio source.
| Param | Type |
| ------------ | ----------------------------------------------------------------------------- |
| **`params`** | AudioPlayerDefaultParams |
**Since:** 1.0.0
--------------------
### seek(...)
```typescript
seek(params: AudioPlayerDefaultParams & { timeInSeconds: number; }) => Promise
```
Seek the audio source to a specific time.
| Param | Type |
| ------------ | ---------------------------------------------------------------------------------------------------------- |
| **`params`** | AudioPlayerDefaultParams & { timeInSeconds: number; } |
**Since:** 1.0.0
--------------------
### stop(...)
```typescript
stop(params: AudioPlayerDefaultParams) => Promise
```
Stop playing the audio source and reset the current time to zero.
| Param | Type |
| ------------ | ----------------------------------------------------------------------------- |
| **`params`** | AudioPlayerDefaultParams |
**Since:** 1.0.0
--------------------
### setVolume(...)
```typescript
setVolume(params: AudioPlayerDefaultParams & { volume: number; }) => Promise
```
Set the volume of the audio source. Should be a decimal less than or equal to `1.00`.
This is useful for background music.
| Param | Type |
| ------------ | --------------------------------------------------------------------------------------------------- |
| **`params`** | AudioPlayerDefaultParams & { volume: number; } |
**Since:** 1.0.0
--------------------
### setRate(...)
```typescript
setRate(params: AudioPlayerDefaultParams & { rate: number; }) => Promise
```
Set the rate for the audio source to be played at.
Should be a decimal. An example being `1` is normal speed, `0.5` being half the speed and `1.5` being 1.5 times faster.
| Param | Type |
| ------------ | ------------------------------------------------------------------------------------------------- |
| **`params`** | AudioPlayerDefaultParams & { rate: number; } |
**Since:** 1.0.0
--------------------
### isPlaying(...)
```typescript
isPlaying(params: AudioPlayerDefaultParams) => Promise<{ isPlaying: boolean; }>
```
Wether or not the audio source is currently playing.
| Param | Type |
| ------------ | ----------------------------------------------------------------------------- |
| **`params`** | AudioPlayerDefaultParams |
**Returns:** Promise<{ isPlaying: boolean; }>
**Since:** 1.0.0
--------------------
### destroy(...)
```typescript
destroy(params: AudioPlayerDefaultParams) => Promise
```
Destroy all resources for the audio source.
The audio source with `useForNotification = true` must be destroyed last.
| Param | Type |
| ------------ | ----------------------------------------------------------------------------- |
| **`params`** | AudioPlayerDefaultParams |
**Since:** 1.0.0
--------------------
### onAppGainsFocus(...)
```typescript
onAppGainsFocus(params: AudioPlayerListenerParams, callback: () => void) => Promise
```
Register a callback for when the app comes to the foreground.
| Param | Type |
| -------------- | ------------------------------------------------------------------------------- |
| **`params`** | AudioPlayerListenerParams |
| **`callback`** | () => void |
**Returns:** Promise<AudioPlayerListenerResult>
**Since:** 1.0.0
--------------------
### onAppLosesFocus(...)
```typescript
onAppLosesFocus(params: AudioPlayerListenerParams, callback: () => void) => Promise
```
Registers a callback from when the app goes to the background.
| Param | Type |
| -------------- | ------------------------------------------------------------------------------- |
| **`params`** | AudioPlayerListenerParams |
| **`callback`** | () => void |
**Returns:** Promise<AudioPlayerListenerResult>
**Since:** 1.0.0
--------------------
### onAudioReady(...)
```typescript
onAudioReady(params: AudioPlayerListenerParams, callback: () => void) => Promise
```
Registers a callback for when the audio source is ready to be played.
| Param | Type |
| -------------- | ------------------------------------------------------------------------------- |
| **`params`** | AudioPlayerListenerParams |
| **`callback`** | () => void |
**Returns:** Promise<AudioPlayerListenerResult>
**Since:** 1.0.0
--------------------
### onAudioEnd(...)
```typescript
onAudioEnd(params: AudioPlayerListenerParams, callback: () => void) => Promise
```
Registers a callback for when the audio source has ended (reached the end of the audio).
| Param | Type |
| -------------- | ------------------------------------------------------------------------------- |
| **`params`** | AudioPlayerListenerParams |
| **`callback`** | () => void |
**Returns:** Promise<AudioPlayerListenerResult>
**Since:** 1.0.0
--------------------
### onPlaybackStatusChange(...)
```typescript
onPlaybackStatusChange(params: AudioPlayerListenerParams, callback: (result: { status: 'playing' | 'paused' | 'stopped'; }) => void) => Promise
```
Registers a callback for when state of playback for the audio source has changed.
This should be used to update the UI when the notification controls are used to control the playback.
| Param | Type |
| -------------- | --------------------------------------------------------------------------------- |
| **`params`** | AudioPlayerListenerParams |
| **`callback`** | (result: { status: 'playing' \| 'paused' \| 'stopped'; }) => void |
**Returns:** Promise<AudioPlayerListenerResult>
**Since:** 1.0.0
--------------------
### Interfaces
#### AudioPlayerPrepareParams
| Prop | Type | Description | Default | Since |
| ------------------------ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- |
| **`audioSource`** | string | A URI for the audio file to play | | 1.0.0 |
| **`friendlyTitle`** | string | The title/name of the audio file to be used on the notification | | 1.0.0 |
| **`useForNotification`** | boolean | Whether to use this audio file for the notification. This is considered the primary audio to play. It must be created first and you may only have one at a time. | false | 1.0.0 |
| **`artworkSource`** | string | A URI for the album art image to display on the Android/iOS notification. Can also be an in-app source. Pulls from `android/app/src/assets/public` and `ios/App/App/public`. If using [Vite](https://vitejs.dev/guide/assets.html#the-public-directory), you would put the image in your `public` folder and the build process will copy to `dist` which in turn will be copied to the Android/iOS assets by Capacitor. A PNG is the best option with square dimensions. 1200 x 1200px is a good option. | | 1.0.0 |
| **`isBackgroundMusic`** | boolean | Is this audio for background music/audio. Should not be `true` when `useForNotification = true`. | false | 1.0.0 |
| **`loop`** | boolean | Whether or not to loop other audio like background music while the primary audio (`useForNotification = true`) is playing. | false | 1.0.0 |
| **`showSeekBackward`** | boolean | Whether or not to show the seek backward button on the OS's notification. Only has affect when `useForNotification = true`. | true | 1.2.0 |
| **`showSeekForward`** | boolean | Whether or not to show the seek forward button on the OS's notification. Only has affect when `useForNotification = true`. | true | 1.2.0 |
#### AudioPlayerDefaultParams
| Prop | Type | Description | Since |
| ------------- | ------------------- | -------------------------------------------------- | ----- |
| **`audioId`** | string | Any string to differentiate different audio files. | 1.0.0 |
#### AudioPlayerListenerResult
| Prop | Type |
| ---------------- | ------------------- |
| **`callbackId`** | string |
#### AudioPlayerListenerParams
| Prop | Type | Description | Since |
| ------------- | ------------------- | ------------------------------------------- | ----- |
| **`audioId`** | string | The `audioId` set when `create` was called. | 1.0.0 |