Awesome
<p align="center"><br><img src="https://user-images.githubusercontent.com/236501/85893648-1c92e880-b7a8-11ea-926d-95355b8175c7.png" width="128" height="128" /></p>
<h3 align="center">Native Audio</h3>
<p align="center"><strong><code>@capacitor-community/native-audio</code></strong></p>
<p align="center">
Capacitor community plugin for playing sounds natively.
</p>
<p align="center">
<img src="https://img.shields.io/maintenance/yes/2024?style=flat-square" />
<a href="https://github.com/capacitor-community/native-audio/actions?query=workflow%3A%22Test+and+Build+Plugin%22"><img src="https://img.shields.io/github/actions/workflow/status/capacitor-community/native-audio/test-build.yml?style=flat-square" /></a>
<a href="https://www.npmjs.com/package/@capacitor-community/native-audio"><img src="https://img.shields.io/npm/l/@capacitor-community/native-audio?style=flat-square" /></a>
<br>
<a href="https://www.npmjs.com/package/@capacitor-community/native-audio"><img src="https://img.shields.io/npm/dw/@capacitor-community/native-audio?style=flat-square" /></a>
<a href="https://www.npmjs.com/package/@capacitor-community/native-audio"><img src="https://img.shields.io/npm/v/@capacitor-community/native-audio?style=flat-square" /></a>
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
<a href="#contributors-"><img src="https://img.shields.io/badge/all%20contributors-6-orange?style=flat-square" /></a>
<!-- ALL-CONTRIBUTORS-BADGE:END -->
</p>
Capacitor Native Audio Plugin
Capacitor plugin for native audio engine.
Capacitor v6 - β
Support!
Click on video to see example π₯
![YouTube Example](https://img.youtube.com/vi/XpUGlWWtwHs/0.jpg)
Maintainers
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.
<docgen-config>
<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
</docgen-config>
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
<docgen-index>
<docgen-api>
<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
configure(...)
configure(options: ConfigureOptions) => Promise<void>
Param | Type |
---|
options | <code><a href="#configureoptions">ConfigureOptions</a></code> |
preload(...)
preload(options: PreloadOptions) => Promise<void>
Param | Type |
---|
options | <code><a href="#preloadoptions">PreloadOptions</a></code> |
play(...)
play(options: { assetId: string; time?: number; }) => Promise<void>
Param | Type |
---|
options | <code>{ assetId: string; time?: number; }</code> |
pause(...)
pause(options: { assetId: string; }) => Promise<void>
Param | Type |
---|
options | <code>{ assetId: string; }</code> |
resume(...)
resume(options: { assetId: string; }) => Promise<void>
Param | Type |
---|
options | <code>{ assetId: string; }</code> |
loop(...)
loop(options: { assetId: string; }) => Promise<void>
Param | Type |
---|
options | <code>{ assetId: string; }</code> |
stop(...)
stop(options: { assetId: string; }) => Promise<void>
Param | Type |
---|
options | <code>{ assetId: string; }</code> |
unload(...)
unload(options: { assetId: string; }) => Promise<void>
Param | Type |
---|
options | <code>{ assetId: string; }</code> |
setVolume(...)
setVolume(options: { assetId: string; volume: number; }) => Promise<void>
Param | Type |
---|
options | <code>{ assetId: string; volume: number; }</code> |
getCurrentTime(...)
getCurrentTime(options: { assetId: string; }) => Promise<{ currentTime: number; }>
Param | Type |
---|
options | <code>{ assetId: string; }</code> |
Returns: <code>Promise<{ currentTime: number; }></code>
getDuration(...)
getDuration(options: { assetId: string; }) => Promise<{ duration: number; }>
Param | Type |
---|
options | <code>{ assetId: string; }</code> |
Returns: <code>Promise<{ duration: number; }></code>
isPlaying(...)
isPlaying(options: { assetId: string; }) => Promise<{ isPlaying: boolean; }>
Param | Type |
---|
options | <code>{ assetId: string; }</code> |
Returns: <code>Promise<{ isPlaying: boolean; }></code>
addListener('complete', ...)
addListener(eventName: 'complete', listenerFunc: (event: { assetId: string; }) => void) => Promise<PluginListenerHandle>
Listen for asset completed playing event
Param | Type |
---|
eventName | <code>'complete'</code> |
listenerFunc | <code>(event: { assetId: string; }) => void</code> |
Returns: <code>Promise<<a href="#pluginlistenerhandle">PluginListenerHandle</a>></code>
Since: 5.0.1
Interfaces
ConfigureOptions
Prop | Type | Description | Default |
---|
fade | <code>boolean</code> | Indicating whether or not to fade audio. | <code>false</code> |
focus | <code>boolean</code> | Indicating whether or not to disable mixed audio. | <code>false</code> |
PreloadOptions
Prop | Type |
---|
assetPath | <code>string</code> |
assetId | <code>string</code> |
volume | <code>number</code> |
audioChannelNum | <code>number</code> |
isUrl | <code>boolean</code> |
PluginListenerHandle
Prop | Type |
---|
remove | <code>() => Promise<void></code> |
</docgen-api>