Capacitor Native Audio Plugin

Capacitor plugin for native audio engine. Capacitor v3 - ✅ Support!

Click on video to see example 💥

Maintainers

| Maintainer | GitHub | Social | | ------------- | ------------------------------------------- | ----------------------------------- | | Maxim Bazuev | bazuka5801 | Telegram |

Mainteinance Status: Actively Maintained

Preparation

All audio place in specific platform folder

Andoid: android/app/src/assets

iOS: ios/App/App/sounds

Web: assets/sounds

Installation

To use npm

npm install @capacitor-community/native-audio

To use yarn

yarn add @capacitor-community/native-audio

Sync native files

npx cap sync

On iOS, Android and Web, no further steps are needed.

Configuration

No configuration required for this plugin.

Supported methods

| Name | Android | iOS | Web | | :------------- | :------ | :-- | :-- | | configure | ✅ | ✅ | ❌ | | preload | ✅ | ✅ | ✅ | | play | ✅ | ✅ | ✅ | | pause | ✅ | ✅ | ✅ | | resume | ✅ | ✅ | ✅ | | loop | ✅ | ✅ | ✅ | | stop | ✅ | ✅ | ✅ | | unload | ✅ | ✅ | ✅ | | setVolume | ✅ | ✅ | ✅ | | getDuration | ✅ | ✅ | ✅ | | getCurrentTime | ✅ | ✅ | ✅ | | isPlaying | ✅ | ✅ | ✅ |

Usage

Example repository

import {NativeAudio} from '@capacitor-community/native-audio'


/**
 * This method will load more optimized audio files for background into memory.
 * @param assetPath - relative path of the file or absolute url (file://)
 *        assetId - unique identifier of the file
 *        audioChannelNum - number of audio channels
 *        isUrl - pass true if assetPath is a `file://` url
 * @returns void
 */
NativeAudio.preload({
    assetId: "fire",
    assetPath: "fire.mp3",
    audioChannelNum: 1,
    isUrl: false
});

/**
 * This method will play the loaded audio file if present in the memory.
 * @param assetId - identifier of the asset
 * @param time - (optional) play with seek. example: 6.0 - start playing track from 6 sec
 * @returns void
 */
NativeAudio.play({
    assetId: 'fire',
    // time: 6.0 - seek time
});

/**
 * This method will loop the audio file for playback.
 * @param assetId - identifier of the asset
 * @returns void
 */
NativeAudio.loop({
  assetId: 'fire',
});


/**
 * This method will stop the audio file if it's currently playing.
 * @param assetId - identifier of the asset
 * @returns void
 */
NativeAudio.stop({
  assetId: 'fire',
});

/**
 * This method will unload the audio file from the memory.
 * @param assetId - identifier of the asset
 * @returns void
 */
NativeAudio.unload({
  assetId: 'fire',
});

/**
 * This method will set the new volume for a audio file.
 * @param assetId - identifier of the asset
 *        volume - numerical value of the volume between 0.1 - 1.0
 * @returns void
 */
NativeAudio.setVolume({
  assetId: 'fire',
  volume: 0.4,
});

/**
 * this method will get the duration of an audio file.
 * only works if channels == 1
 */
NativeAudio.getDuration({
  assetId: 'fire'
})
.then(result => {
  console.log(result.duration);
})

/**
 * this method will get the current time of a playing audio file.
 * only works if channels == 1
 */
NativeAudio.getCurrentTime({
  assetId: 'fire'
});
.then(result => {
  console.log(result.currentTime);
})

/**
 * This method will return false if audio is paused or not loaded.
 * @param assetId - identifier of the asset
 * @returns {isPlaying: boolean}
 */
NativeAudio.isPlaying({
  assetId: 'fire'
})
.then(result => {
  console.log(result.isPlaying);
})

API

configure(...)

configure(options: ConfigureOptions) => Promise<void>

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | ConfigureOptions |

preload(...)

preload(options: PreloadOptions) => Promise<void>

| Param | Type | | ------------- | --------------------------------------------------------- | | options | PreloadOptions |

play(...)

play(options: { assetId: string; time: number; }) => Promise<void>

| Param | Type | | ------------- | ----------------------------------------------- | | options | { assetId: string; time: number; } |

pause(...)

pause(options: { assetId: string; }) => Promise<void>

| Param | Type | | ------------- | --------------------------------- | | options | { assetId: string; } |

resume(...)

resume(options: { assetId: string; }) => Promise<void>

| Param | Type | | ------------- | --------------------------------- | | options | { assetId: string; } |

loop(...)

loop(options: { assetId: string; }) => Promise<void>

| Param | Type | | ------------- | --------------------------------- | | options | { assetId: string; } |

stop(...)

stop(options: { assetId: string; }) => Promise<void>

| Param | Type | | ------------- | --------------------------------- | | options | { assetId: string; } |

unload(...)

unload(options: { assetId: string; }) => Promise<void>

| Param | Type | | ------------- | --------------------------------- | | options | { assetId: string; } |

setVolume(...)

setVolume(options: { assetId: string; volume: number; }) => Promise<void>

| Param | Type | | ------------- | ------------------------------------------------- | | options | { assetId: string; volume: number; } |

getCurrentTime(...)

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

| Param | Type | | ------------- | --------------------------------- | | options | { assetId: string; } |

Returns: Promise<{ currentTime: number; }>

getDuration(...)

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

| Param | Type | | ------------- | --------------------------------- | | options | { assetId: string; } |

Returns: Promise<{ duration: number; }>

isPlaying(...)

isPlaying(options: { assetId: string; }) => Promise<{ isPlaying: boolean; }>

| Param | Type | | ------------- | --------------------------------- | | options | { assetId: string; } |

Returns: Promise<{ isPlaying: boolean; }>

playQueue(...)

playQueue(options: { id: string; tracks: QueueTrack[]; startTrackId: string; startTime: number; trailingTime: number; timerUpdateInterval: number; volume: number; useFade: boolean; loop: boolean; }) => Promise<void>

| Param | Type | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | options | { id: string; tracks: QueueTrack[]; startTrackId: string; startTime: number; trailingTime: number; timerUpdateInterval: number; volume: number; useFade: boolean; loop: boolean; } |

pauseQueue(...)

pauseQueue(options: { id: string; }) => Promise<void>

| Param | Type | | ------------- | ---------------------------- | | options | { id: string; } |

resumeQueue(...)

resumeQueue(options: { id: string; }) => Promise<void>

| Param | Type | | ------------- | ---------------------------- | | options | { id: string; } |

isQueuePlaying(...)

isQueuePlaying(options: { id: string; }) => Promise<{ isQueuePlaying: boolean; }>

| Param | Type | | ------------- | ---------------------------- | | options | { id: string; } |

Returns: Promise<{ isQueuePlaying: boolean; }>

isQueuePaused(...)

isQueuePaused(options: { id: string; }) => Promise<{ isQueuePaused: boolean; }>

| Param | Type | | ------------- | ---------------------------- | | options | { id: string; } |

Returns: Promise<{ isQueuePaused: boolean; }>

seekQueue(...)

seekQueue(options: { id: string; time: number; }) => Promise<void>

| Param | Type | | ------------- | ------------------------------------------ | | options | { id: string; time: number; } |

playNextQueueTrack(...)

playNextQueueTrack(id: string) => Promise<void>

| Param | Type | | -------- | ------------------- | | id | string |

playPreviousQueueTrack(...)

playPreviousQueueTrack(id: string) => Promise<void>

| Param | Type | | -------- | ------------------- | | id | string |

getQueueTrackCurrentTime(...)

getQueueTrackCurrentTime(id: string) => Promise<number>

| Param | Type | | -------- | ------------------- | | id | string |

Returns: Promise<number>

getQueuePlayingIndex(...)

getQueuePlayingIndex(options: { id: string; }) => Promise<number>

| Param | Type | | ------------- | ---------------------------- | | options | { id: string; } |

Returns: Promise<number>

getQueuePlayingTrackId(...)

getQueuePlayingTrackId(options: { id: string; }) => Promise<string>

| Param | Type | | ------------- | ---------------------------- | | options | { id: string; } |

Returns: Promise<string>

setQueueLoopIndex(...)

setQueueLoopIndex(options: { id: string; index: number; set: boolean; }) => Promise<number>

| Param | Type | | ------------- | --------------------------------------------------------- | | options | { id: string; index: number; set: boolean; } |

Returns: Promise<number>

setQueueVolume(...)

setQueueVolume(options: { id: string; volume: number; }) => Promise<void>

| Param | Type | | ------------- | -------------------------------------------- | | options | { id: string; volume: number; } |

updateQueue(...)

updateQueue(options: { id: string; tracks: QueueTrack[]; }) => Promise<void>

| Param | Type | | ------------- | -------------------------------------------------- | | options | { id: string; tracks: QueueTrack[]; } |

queueHasTrackWith(...)

queueHasTrackWith(options: { id: string; url: string; }) => Promise<{ has: boolean; }>

| Param | Type | | ------------- | ----------------------------------------- | | options | { id: string; url: string; } |

Returns: Promise<{ has: boolean; }>

unloadQueue(...)

unloadQueue(options: { id: string; }) => Promise<void>

| Param | Type | | ------------- | ---------------------------- | | options | { id: string; } |

setSleepTimer(...)

setSleepTimer(options: { time: number; }) => Promise<void>

| Param | Type | | ------------- | ------------------------------ | | options | { time: number; } |

cancelSleepTimer(...)

cancelSleepTimer(options: {}) => Promise<void>

| Param | Type | | ------------- | --------------- | | options | {} |

requestNotificationPermission(...)

requestNotificationPermission(options: { mode: number; text: string; positiveText: string; negativeText: string; }) => Promise<{ acquired: boolean; }>

| Param | Type | | ------------- | ---------------------------------------------------------------------------------------- | | options | { mode: number; text: string; positiveText: string; negativeText: string; } |

Returns: Promise<{ acquired: boolean; }>

Interfaces

ConfigureOptions

| Prop | Type | | ----------- | -------------------- | | fade | boolean | | focus | boolean |

PreloadOptions

| Prop | Type | | --------------------- | -------------------- | | assetPath | string | | assetId | string | | volume | number | | audioChannelNum | number | | isUrl | boolean |

QueueTrack

| Prop | Type | | --------------- | -------------------- | | id | string | | url | string | | name | string | | isMusic | boolean | | forcePlay | boolean |