Skip to content

Wizcorp/cordova-plugin-yanap

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

34 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

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

Yanap.AUDIO_TYPE

Enum of available audio instance types:

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...)

Yanap.AUDIO_INSTANCE_STATUS

Enum of possible audio instance status:

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

Yanap.AudioInstance(audioType, onStatusUpdate)

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).
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).

Yanap.AudioInstance.load(filePath)

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
// 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();

Yanap.AudioInstance.play()

Used to start or resume an audio instance playback.

Yanap.AudioInstance.stop()

Used to interrupt an audio instance playback.

Yanap.AudioInstance.setVolume(channel1, channel2)

Set audio volume.

  • channel1 and channel2 represents the left and right speakers.
  • Values are in a range of 0.0 ~ 1.0.

Yanap.AudioInstance.release()

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

Yanap.AudioInstance.fileLength

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

Yanap.releaseAll()

Static method used to stop and release all audio instances.

About

Yet Another Native Audio Plugin for Cordova

Resources

License

Stars

Watchers

Forks

Packages

No packages published