#Cordova Low Latency Audio Plugin for iOS and Android

Prerequisites: A Cordova/PhoneGap 3.0+ project for iOS or Android.

Index

1. Description
2. Installation
3. Usage
4. API Methods
5. Example
6. Demo Projects
7. Credits ##Description

The low latency audio plugin is designed to enable low latency and polyphonic/background audio from Cordova/PhoneGap applications.

It was orginally developed by Andrew Trice, you can read more about this plugin at: http://www.tricedesigns.com/2012/01/25/low-latency-polyphonic-audio-in-phonegap/

##Installation

To install this plugin, follow the Command-line Interface Guide.

This plugin follows the Cordova 3.0 plugin spec, so it can be installed through the Cordova CLI in your existing Cordova project:

cordova plugin add https://github.com/floatinghotpot/cordova-plugin-lowlatencyaudio.git

##Usage

1. Preload the audio asset. You can use a relative path or absolute URL and set a lower volume. Note: Make sure to wait for the "deviceready" event before attepting to load assets.
2. Play the audio asset.
3. When done, unload the audio asset.
4. in hotjs-audio.js, the same interface also implemented for html5 audio, when code run in PC browser, it will use html5, when in cordova, it will use lowlatencyaudio plugin.

<script src='plugins/hotjs-audio.js'></script>

function onDeviceReady() {
    hotjs.Audio.init();

    // in your code, replace 'window.plugins.xxx()' with 'hotjs.Audio.xxx()'
}

##API Methods

preloadFX: function ( id, assetPath, success, fail)

The preloadFX function loads an audio file into memory. Assets that are loaded using preloadFX are managed/played using AudioServices methods from the AudioToolbox framework. These are very low-level audio methods and have minimal overhead. Audio loaded using this function is played using AudioServicesPlaySystemSound. These assets should be short, and are not intended to be looped or stopped. They are fully concurrent and polyphonic.

• params
• ID - string unique ID for the audio file
• assetPath - the relative path or absolute URL (inluding http://) to the audio asset.
• success - success callback function
• fail - error/fail callback function

preloadAudio: function ( id, assetPath, volume, voices, success, fail)

The preloadAudio function loads an audio file into memory. Assets that are loaded using preloadAudio are managed/played using AVAudioPlayer. These have more overhead than assets laoded via preloadFX, and can be looped/stopped. By default, there is a single "voice" - only one instance that will be stopped & restarted when you hit play. If there are multiple voices (number greater than 0), it will cycle through voices to play overlapping audio. The default volume is for a preloaded sound is 1.0, a lower default volume can be preset by using a numerical value from 0.1 to 1.0.

• params
• ID - string unique ID for the audio file
• assetPath - the relative path to the audio asset within the www directory
• volume - the volume of the preloaded sound (0.1 to 1.0)
• voices - the number of polyphonic voices available
• success - success callback function
• fail - error/fail callback function

play: function (id, success, fail)

Plays an audio asset.

• params:
• ID - string unique ID for the audio file
• success - success callback function
• fail - error/fail callback function

loop: function (id, success, fail)

Loops an audio asset infinitely - this only works for assets loaded via preloadAudio.

• params
• ID - string unique ID for the audio file
• success - success callback function
• fail - error/fail callback function

stop: function (id, success, fail)

Stops an audio file - this only works for assets loaded via preloadAudio.

• params:
• ID - string unique ID for the audio file
• success - success callback function
• fail - error/fail callback function

unload: function (id, success, fail)

Unloads an audio file from memory.

• params:
• ID - string unique ID for the audio file
• success - success callback function
• fail - error/fail callback function

##Example

In this example, the resources reside in a relative path under the Cordova root folder "www/". For example, if the file is under "www/audio/music.mp3", then:

// map the media id and res file
var media = {
	'music': 'audio/music.mp3',
	'click': 'audio/click.mp3'
};

The implementation goes as follows:

if( window.plugins && window.plugins.LowLatencyAudio ) {
	var lla = window.plugins.LowLatencyAudio;
	
	// preload audio resource
	lla.preloadAudio( 'music', media['music'], 1, 1, function(msg){
	}, function(msg){
		console.log( 'error: ' + msg );
	});
	
	lla.preloadFX( 'click', media['click'], function(msg){
	}, function(msg){
		console.log( 'error: ' + msg );
	});
	
	// now start playing
	lla.play( 'click' );
	lla.loop( 'music' );

	// stop after 1 min	
	window.setTimeout( function(){
		//lla.stop( 'click' );
		lla.stop( 'music' );
			
		lla.unload( 'music' );
		lla.unload( 'click' );
	}, 1000 * 60 );
}

Demo Projects

The demonstration projects in the examples directory can get you started with the plugin.

Start by creating a project. Then replace index.html with the one in the example directory and copy the assets folder into the /www/ directory.

cordova create Piano com.example.piano Piano
cd Piano
cordova platform add ios
cordova plugin add https://github.com/floatinghotpot/cordova-plugin-lowlatencyaudio.git

Credits

The first iteration of the Plugin was built by Andrew Trice. This plugin was ported to Plugman / Cordova 3 by Raymond Xie, SidneyS and other committers.