Native Audio
@capacitor-community/native-audio
Capacitor community plugin for playing sounds.
Capacitor Native Audio Plugin
Capacitor plugin for native audio engine.
Capacitor v3 - ✅ Support!
Click on video to see example 💥
Maintainers
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
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>
preload(...)
preload(options: PreloadOptions) => Promise<void>
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>
playPreviousQueueTrack(...)
playPreviousQueueTrack(id: string) => Promise<void>
getQueueTrackCurrentTime(...)
getQueueTrackCurrentTime(id: string) => Promise<number>
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>
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 |