Neurophysiologically Pseudoscientific Manatee
    Wondering what’s next for npm?Check out our public roadmap! »

    cordova-plugin-nativeaudio-fix

    3.0.9 • Public • Published

    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. Supported Platforms
    6. Installation
    7. Usage
    8. API
    9. Demo

    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 and Sidney Bofah.

    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.

    Supported Platforms

    • iOS (tested with 7.1.2, 8.1.3)
    • Android (tested in API levels 14 - 21)

    Installation

    Via Cordova CLI:

    cordova plugin add 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

    Example Code

    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, 0, 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 );
    }

    Demo

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

    [sudo] npm install plugin-verify -g
    plugin-verify cordova-plugin-nativeaudio ios
    plugin-verify cordova-plugin-nativeaudio android

    Or, type the commands step by step:

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

    Install

    npm i cordova-plugin-nativeaudio-fix

    DownloadsWeekly Downloads

    0

    Version

    3.0.9

    License

    MIT

    Unpacked Size

    2.15 MB

    Total Files

    22

    Last publish

    Collaborators

    • avatar