Yanap (yet another native audio plugin)

This Cordova's plugin is an alternative to the cordova-plugin-media and cordova-plugin-nativeaudio/cordova-plugin-lowlatencyaudio plugins to play audio from native on Android. It may support iOS in the future.

Main features we have in mind while developing it are:
- gapless audio loops
- low latency playback for short sounds

Basic usage

``javascript
var Yanap = cordova.plugins.Yanap;

var myBackgroundLoop = new Yanap.AudioInstance(Yanap.AUDIO_TYPE.LOOP);
myBackgroundLoop.load('audio/bg.mp3');
myBackgroundLoop.play();

// and when it is not needed anymore...
// myBackgroundLoop.stop();
// myBackgroundLoop.release();
`

API

$3

Enum of available audio instance types:

`javascript
Yanap.AUDIO_TYPE.LOOP // for -relatively- long audio tracks that need to loop
Yanap.AUDIO_TYPE.MUSIC // for -relatively- long audio tracks
Yanap.AUDIO_TYPE.SOUND // for short audio files (fx, ui...)
`

$3

Enum of possible audio instance status:
`javascript
Yanap.AUDIO_INSTANCE_STATUS.ERROR // something bad happened, instance cannot be used anymore
Yanap.AUDIO_INSTANCE_STATUS.EMPTY // instance has been initialised
Yanap.AUDIO_INSTANCE_STATUS.LOADING // currently loading
Yanap.AUDIO_INSTANCE_STATUS.LOADED // loaded successfully
Yanap.AUDIO_INSTANCE_STATUS.PLAYING // currently playing
Yanap.AUDIO_INSTANCE_STATUS.LOOPING // set when looping the first time and re-triggered at each consecutive loop
Yanap.AUDIO_INSTANCE_STATUS.STOPPED // playback reached the end or has been manually stopped
Yanap.AUDIO_INSTANCE_STATUS.RELEASED // all resources for this instance have been released
`

NB:
- LOOPING is available only for audio types LOOP
- PLAYING and STOPPED are not available for audio types SOUND

$3

Audio instance constructor.
- audioType can be any value present in Yanap.AUDIO_TYPE.
- onStatusUpdate is an optional method that will receive a Yanap.AUDIO_INSTANCE_STATUS as first parameter and a string containing additional information as second parameter (mostly used when an error happened).

`javascript
var mySong = new Yanap.AudioInstance(
Yanap.AUDIO_TYPE.MUSIC,
function onStatusUpdate(status, additionalInfo) {
if (status === Yanap.AUDIO_INSTANCE_STATUS.ERROR) {
return console.error('error: ' + additionalInfo);
}
console.log('new status: ' + status);
}
);
`

This creation is successful even if audio type is invalid (it would fail during the loading).

$3

Used to load a file.
- filePath is a string:
- relative to application asset folder if string starts with file:///android_asset/
- else an absolute path if string starts with file://
- else a relative path to application cache directory

`javascript
// example 1: if you want to be sure that audio is ready before trying to play it
var myLaserFx = new Yanap.AudioInstance(Yanap.AUDIO_TYPE.SOUND, function (status) {
if (status === Yanap.AUDIO_INSTANCE_STATUS.ERROR) {
return console.error('error: ' + additionalInfo);
}
if (status === Yanap.AUDIO_INSTANCE_STATUS.LOADED) {
myLaserFx.play();
}
});
myLaserFx.load('audio/laser.mp3');

// example 2: if you want to play automatically when loaded and don't care about errors
var myLaserFx = new Yanap.AudioInstance(Yanap.AUDIO_TYPE.SOUND);
myLaserFx.load('audio/laser.mp3');
myLaserFx.play();
`

$3

Used to start or resume an audio instance playback.

$3

Used to interrupt an audio instance playback.

$3

Set audio volume.
- channel1 and channel2 represents the left and right speakers.
- Values are in a range of 0.0 ~ 1.0.

$3

Has to be called when you don't need an audio instance anymore. It's automatically stopping playback before releasing all resources.

$3

Size of the audio file in bytes. Default is -1`.

$3

Static method used to stop and release all audio instances.