Skip to content

Cordova audio extension for concurrent (multi-channel), polyphonic (multi-voice) and latency-reduced (caching) audio playback, designed for games and audio applications.

License

Notifications You must be signed in to change notification settings

RussellTaylor83/cordova-plugin-nativeaudio

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

#Cordova Native Audio Plugin

Cordova / PhoneGap 3.5+ extension for Native Audio playback, aimed at HTML5 gaming and audio applications which require minimum latency, polyphony and concurrency.

=======================

Contents

  1. Description
  2. History
  3. Roadmap
  4. Integration
  5. Platform Support
  6. Installation
  7. Usage
  8. API
  9. Demo
  10. Example

=======================

Description

This Cordova / PhoneGap (3.5+) plugin enables concurrency (multi-channel playback), polyphony (multi-voice playback) and minimized latency (via caching) in audio-based applications, by leveraging native audio APIs. Designed for the use in HTML5-based cross-platform games and mobile/hybrid audio applications.

=======================

History

Community-driven, clean fork of the Low Latency Audio Plugin for Cordova / PhoneGap, initially published by Andrew Trice and then maintained by Raymond Xie.

This project cleans up a lot of legacy code, and adds success, error and completion callbacks. It also features integration in AngularJS projects via ngCordova.

=======================

Roadmap

Following the Cordova philosophy, this is a shim for a web audio implementation (on mobile) which is as fast and feature-rich as native mobile APIs. Currently, neither HTML5 Audio or the more recent Web Audio API offer a cross-platform solution which 1) is fast, 2) supports polyphony, 3) concurrency and 4) maintains a low overhead.

It should be replaced by a standardised W3C solution as soon as such an implementation offers comparable performance across (mobile) devices, which is crucial for HTML5-based games.

=======================

Integration

This plugin is available as an AngularJS service module, facilitating the usage in AngularJS-based Cordova/PhoneGap projects.

It extends the ngCordova project, an effort by the great guys at Drifty, creators of the Ionic Framework. Download it at the ngCordova website or the repository.

=======================

Platform Support

  • iOS, tested (6.1, 7.1.2)
  • Android, tested (4+)

=======================

Installation

Via Cordova CLI:

cordova plugin add de.neofonie.cordova.plugin.nativeaudio

=======================

##Usage

  1. Wait for deviceReady.
  2. Preload an audio asset and assign an id - either optimized for single-shot style short clips (preloadSimple()) or looping, ambient background audio (preloadComplex())
  3. play() the audio asset via its id.
  4. unload() the audio asset via its id.

=======================

##API

###Preloading

preloadSimple: function ( id, assetPath, successCallback, errorCallback)

Loads an audio file into memory. Optimized for short clips / single shots (up to five seconds). Cannot be stopped / looped.

Uses lower-level native APIs with small footprint (iOS: AudioToolbox/AudioServices). Fully concurrent and multichannel.

  • params
  • id - string unique ID for the audio file
  • assetPath - the relative path or absolute URL (inluding http://) to the audio asset.
  • successCallback - success callback function
  • errorCallback - error callback function
preloadComplex: function ( id, assetPath, volume, voices, delay, successCallback, errorCallback)

Loads an audio file into memory. Optimized for background music / ambient sound. Uses highlevel native APIs with a larger footprint. (iOS: AVAudioPlayer). Can be stopped / looped and used with multiple voices. Can be faded in and out using the delay parameter.

####Volume & Voices

The default volume is 1.0, a lower default can be set by using a numerical value from 0.1 to 1.0.

By default, there is 1 vice, that is: one instance that will be stopped & restarted on play(). If there are multiple voices (number greater than 0), it will cycle through voices to play overlapping audio.

Change the float-based delay parameter to increase the fade-in/fade-out timing.

###Playback

  • 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 multichannel voices available
  • successCallback - success callback function
  • errorCallback - error callback function
play: function (id, successCallback, errorCallback, completeCallback)

Plays an audio asset.

  • params:
  • id - string unique ID for the audio file
  • successCallback - success callback function
  • errorCallback - error callback function
  • completeCallback - error callback function
loop: function (id, successCallback, errorCallback)

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

  • params
  • ID - string unique ID for the audio file
  • successCallback - success callback function
  • errorCallback - error callback function
stop: function (id, successCallback, errorCallback)

Stops an audio file. Only works for assets loaded via preloadComplex.

  • params:
  • ID - string unique ID for the audio file
  • successCallback - success callback function
  • errorCallback - error callback function
unload: function (id, successCallback, errorCallback)

Unloads an audio file from memory.

  • params:
  • ID - string unique ID for the audio file
  • successCallback - success callback function
  • errorCallback - error callback function
setVolumeForComplexAsset: function (id, volume, successCallback, errorCallback)

Changes the volume for preloaded complex assets.

  • params:
  • ID - string unique ID for the audio file
  • volume - the volume of the audio asset (0.1 to 1.0)
  • successCallback - success callback function
  • errorCallback - error callback function

=======================

##Demo

In this example, the resources reside in a relative path under the Cordova root folder "www/".

if( window.plugins && window.plugins.NativeAudio ) {
	
	// Preload audio resources
	window.plugins.NativeAudio.preloadComplex( 'music', 'audio/music.mp3', 1, 1, function(msg){
	}, function(msg){
		console.log( 'error: ' + msg );
	});
	
	window.plugins.NativeAudio.preloadSimple( 'click', 'audio/click.mp3', function(msg){
	}, function(msg){
		console.log( 'error: ' + msg );
	});


	// Play
	window.plugins.NativeAudio.play( 'click' );
	window.plugins.NativeAudio.loop( 'music' );


	// Stop multichannel clip after 60 seconds
	window.setTimeout( function(){

		window.plugins.NativeAudio.stop( 'music' );
			
		window.plugins.NativeAudio.unload( 'music' );
		window.plugins.NativeAudio.unload( 'click' );

	}, 1000 * 60 );
}

=======================

Example

The Drumpad in the examples directory is a first starting point.

cordova create drumpad com.example.nativeaudio drumpad
cd drumpad
cordova platform add ios
cordova plugin add de.neofonie.cordova.plugin.nativeaudio
rm -R www/*
cp -r plugins/de.neofonie.cordova.plugin.nativeaudio/examples/drumpad/* www
cordova build ios
cordova emulate ios

About

Cordova audio extension for concurrent (multi-channel), polyphonic (multi-voice) and latency-reduced (caching) audio playback, designed for games and audio applications.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Objective-C 52.6%
  • Java 31.8%
  • JavaScript 11.2%
  • CSS 4.4%