arnmusic-native-audio

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

npm install arnmusic-native-audio
npx cap sync

API

Android

AndroidManifest.xml required changes

Located at android/app/src/main/AndroidManifest.xml

<application>
    <!-- OTHER STUFF -->

    <!-- Add service to be used for background play -->
    <service
        android:name="us.mediagrid.capacitorjs.plugins.nativeaudio.AudioPlayerService"
        android:description="@string/audio_player_service_description"
        android:foregroundServiceType="mediaPlayback"
        android:exported="true">
        <intent-filter>
            <action android:name="androidx.media3.session.MediaSessionService"/>
        </intent-filter>
    </service>

    <!-- OTHER STUFF -->
</application>

<!-- Add required permissions -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

strings.xml required changes

Located at android/app/src/main/res/values/strings.xml

<resources>
    <!-- OTHER STUFF -->

    <!-- Describes the service in your app settings once installed -->
    <string name="audio_player_service_description">Allows for audio to play in the background.</string>
</resources>

iOS

Enable Audio Background Mode

This can be done in XCode or by editing Info.plist directly.

<!-- ios/App/App/Info.plist -->

<dict>
    <!-- OTHER STUFF -->

    <key>UIBackgroundModes</key>
    <array>
        <string>audio</string>
    </array>

    <!-- OTHER STUFF -->
</dict>

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 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(...)
• createMultiple(...)
• changeAudioSource(...)
• changeMetadata(...)
• play(...)
• pause()
• stop()
• seek(...)
• getCurrentTime()
• getDuration()
• playNext()
• playPrevious()
• setVolume(...)
• setRate(...)
• isPlaying(...)
• destroy(...)
• getCurrentAudio()
• onAudioReady(...)
• onAudioEnd(...)
• onPlaybackStatusChange(...)
• onPlayNext(...)
• onPlayPrevious(...)
• onSeek(...)
• addListener('onPlayNext' | 'onPlayPrevious' | 'onSeek' | 'onPlaybackStatusChange' | 'onAudioEnd' | 'onAirPlayEnabled', ...)
• setAudioSources(...)
• showAirPlayMenu()
• Interfaces

create(...)

create(params: AudioSource) => Promise<{ success: boolean; }>

Create a single audio source for playback.

| Param | Type | | ------------ | --------------------------------------------------- | | params | AudioSource |

Returns: Promise<{ success: boolean; }>

createMultiple(...)

createMultiple(params: { audioSources: AudioSource[]; }) => Promise<{ success: boolean; }>

Create multiple audio sources for playlist management.

| Param | Type | | ------------ | --------------------------------------------- | | params | { audioSources: AudioSource[]; } |

Returns: Promise<{ success: boolean; }>

changeAudioSource(...)

changeAudioSource(params: { audioId: string; source: string; }) => Promise<void>

Change the audio source for an existing player.

| Param | Type | | ------------ | ------------------------------------------------- | | params | { audioId: string; source: string; } |

changeMetadata(...)

changeMetadata(params: { audioId: string; title?: string; artist?: string; albumTitle?: string; artworkSource?: string; }) => Promise<void>

Change the metadata of an existing audio source.

| Param | Type | | ------------ | --------------------------------------------------------------------------------------------------------------- | | params | { audioId: string; title?: string; artist?: string; albumTitle?: string; artworkSource?: string; } |

play(...)

play(params?: { audioId?: string | null | undefined; } | undefined) => Promise<void>

Play an audio source by its ID.

| Param | Type | | ------------ | ------------------------------------------ | | params | { audioId?: string | null; } |

pause()

pause() => Promise<void>

Pause playback of an audio source.

stop()

stop() => Promise<void>

Stop playback and reset the audio source.

seek(...)

seek(params: { timeInSeconds: number; }) => Promise<void>

Seek to a specific time in the audio source.

| Param | Type | | ------------ | --------------------------------------- | | params | { timeInSeconds: number; } |

getCurrentTime()

getCurrentTime() => Promise<{ currentTime: number; }>

Get the current playback time of an audio source.

Returns: Promise<{ currentTime: number; }>

getDuration()

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

Get the duration of an audio source.

Returns: Promise<{ duration: number; }>

playNext()

playNext() => Promise<void>

Skip to the next audio source in the playlist.

playPrevious()

playPrevious() => Promise<void>

Skip to the previous audio source in the playlist.

setVolume(...)

setVolume(params: { volume: number; }) => Promise<void>

Set the volume for the audio source.

| Param | Type | | ------------ | -------------------------------- | | params | { volume: number; } |

setRate(...)

setRate(params: { rate: number; }) => Promise<void>

Set the playback rate for the audio source.

| Param | Type | | ------------ | ------------------------------ | | params | { rate: number; } |

isPlaying(...)

isPlaying(params: { audioId: string; }) => Promise<{ isPlaying: boolean; }>

Determine if the audio source is currently playing.

| Param | Type | | ------------ | --------------------------------- | | params | { audioId: string; } |

Returns: Promise<{ isPlaying: boolean; }>

destroy(...)

destroy(params: { audioId: string; }) => Promise<void>

Destroy all resources associated with the audio source.

| Param | Type | | ------------ | --------------------------------- | | params | { audioId: string; } |

getCurrentAudio()

getCurrentAudio() => Promise<CurrentAudio>

Get details about the currently active audio source.

Returns: Promise<CurrentAudio>

onAudioReady(...)

onAudioReady(params: { audioId: string; }, callback: () => void) => Promise<{ callbackId: string; }>

Register a callback for when the audio source is ready for playback.

| Param | Type | | -------------- | --------------------------------- | | params | { audioId: string; } | | callback | () => void |

Returns: Promise<{ callbackId: string; }>

onAudioEnd(...)

onAudioEnd(params: { audioId: string; }, callback: () => void) => Promise<{ callbackId: string; }>

Register a callback for when playback of the audio source ends.

| Param | Type | | -------------- | --------------------------------- | | params | { audioId: string; } | | callback | () => void |

Returns: Promise<{ callbackId: string; }>

onPlaybackStatusChange(...)

onPlaybackStatusChange(callback: (result: { status: "stopped" | "paused" | "playing"; }) => void) => Promise<{ callbackId: string; }>

Register a callback for playback status changes.

| Param | Type | | -------------- | --------------------------------------------------------------------------------- | | callback | (result: { status: 'stopped' | 'paused' | 'playing'; }) => void |

Returns: Promise<{ callbackId: string; }>

onPlayNext(...)

onPlayNext(callback: () => void) => Promise<{ callbackId: string; }>

Register a callback for when the next track is played.

| Param | Type | | -------------- | -------------------------- | | callback | () => void |

Returns: Promise<{ callbackId: string; }>

onPlayPrevious(...)

onPlayPrevious(callback: () => void) => Promise<{ callbackId: string; }>

Register a callback for when the previous track is played.

| Param | Type | | -------------- | -------------------------- | | callback | () => void |

Returns: Promise<{ callbackId: string; }>

onSeek(...)

onSeek(callback: (result: { time: number; }) => void) => Promise<{ callbackId: string; }>

Register a callback for seek events.

| Param | Type | | -------------- | --------------------------------------------------- | | callback | (result: { time: number; }) => void |

Returns: Promise<{ callbackId: string; }>

addListener('onPlayNext' | 'onPlayPrevious' | 'onSeek' | 'onPlaybackStatusChange' | 'onAudioEnd' | 'onAirPlayEnabled', ...)

addListener(eventName: 'onPlayNext' | 'onPlayPrevious' | 'onSeek' | 'onPlaybackStatusChange' | 'onAudioEnd' | 'onAirPlayEnabled', listenerFunc: (data: any) => void) => Promise<PluginListenerHandle>

Add listeners for events

| Param | Type | | ------------------ | --------------------------------------------------------------------------------------------------------------------------- | | eventName | 'onPlayNext' | 'onPlayPrevious' | 'onSeek' | 'onPlaybackStatusChange' | 'onAudioEnd' | 'onAirPlayEnabled' | | listenerFunc | (data: any) => void |

Returns: Promise<PluginListenerHandle>

setAudioSources(...)

setAudioSources(options: { audioSources: AudioSource[]; }) => Promise<void>

Set all audio sources (useful for setting a new playlist without creating a new AudioPlayer)

| Param | Type | | ------------- | --------------------------------------------- | | options | { audioSources: AudioSource[]; } |

showAirPlayMenu()

showAirPlayMenu() => Promise<void>

Displays the AirPlay menu for streaming audio to AirPlay-compatible devices.

Interfaces

AudioSource

| Prop | Type | Description | | ------------------- | ------------------- | --------------------------------------------- | | audioId | string | Unique identifier for the audio source. | | audioSource | string | A URI for the audio file to play. | | title | string | Title of the audio track. | | artist | string | Artist of the audio track. | | albumTitle | string | Album title of the audio track. | | artworkSource | string | URI for the artwork image of the audio track. |

CurrentAudio

| Prop | Type | Description | | ------------------- | -------------------- | ----------------------------------------------------- | | audioId | string | Unique identifier for the current audio source. | | title | string | Title of the current audio track. | | artist | string | Artist of the current audio track. | | albumTitle | string | Album title of the current audio track. | | artworkSource | string | URI for the artwork image of the current audio track. | | duration | number | Duration of the current audio track in seconds. | | currentTime | number | Current playback time of the audio track in seconds. | | isPlaying | boolean | Whether the current audio is playing. |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |