PhoneGap Low Latency Audio

  • 18 favourites


2,608 visits, 4,250 views



This tutorial hasn't been translated.


This tutorial is licensed under CC BY 4.0. Please refer to the license text if you wish to reuse, share or remix the content contained within this tutorial.

Currently: 4th April 2012 the audio in PhoneGap is broken. and it's not the fault of Construct2, it's a problem of PhoneGap and the way it handles sound.

Broken means:

1) No concurrency (on most phones): meaning that one sound will stop the previous one (so no background music).

2) High Latency: When an event is supposed to play a sound, you application will hang until played. In a game environment this means an unplayable game.

3) No hooks to native phone commands. On iPhone for example the sound will not stop when you put the phone on vibrate using the switch on the side.

Some of these errors are mitigated on some phones, but still, since with html5 you can deploy to a vast array of phones it's better to know what problems may rise on all platforms.

This tutorial is for advanced users a basic understanding of paths, js and code is mandatory as you MUST compile the code yourself, not use the PhoneGap online service.

Be sure that your game is finished, because once you start this process the game will work only inside PhoneGap, which means "compiling" each time you need to test, so be sure your game is flawless otherwise you'll lose a lot of time.

Download and install this plugin for construct: CallJS

Add it to your first layer (just like the array object this plugin MUST be inside a layout) and make it global (very important). Then create a blank myScripts.js file in the root of your game. This file will not be used in this tutorial but is apparently needed by the plugin so leave it there.

Download and install PhoneGap 1.4.1 (this link contains a list of all version of PG) be warned that the later versions have been renamed to Cordova and most of the plugins, including the one we need don't work anymore! If you are reading this in a future where the LowLatencyAudio plugin has been converted to Cordova feel free to use Cordova (PG will become CDV in the js commands that you'll find later).

Now download this plugin LowLatencyAudio (iOS / Android) and install it using the included readme file instructions and be sure that the project compile before proceeding further.

Now that everything is installed, if you haven't done it already add the PGLowLatencyAudio.js to your index.html just after PhoneGap. I suggest you also delete the phonegap.js file that c2 provided and use instead the one from the version of PhoneGap you are using (in this case: phonegap-1.4.1.js).

Now locate this line in index.html


Before this line we start to preload audio. Why not on c2 you may ask?

The reason is simple, if we were to do it on c2 we would also need to check if audio has preloaded to avoid preloading it every time the layout is displayed, plus if we preload it before c2 is initialized we can be sure that the audio has preloaded before c2 has even started meaning that we can be sure that the audio objects are ready.

To preload you do this (extensions: m4a on iOS, ogg on Android):


    PGLowLatencyAudio.preloadAudio('music', 'media/music.m4a', 1);


    PGLowLatencyAudio.preloadFX('sfx', 'media/sfx.m4a');

you repeat these commands for how many sfx/music you have (remember to change the extension accordingly).

Remember to assign an unique name (just like the tag in the audio object of c2) to each sound.

NOTE: Even if you don't use the audio object on c2 you can still use c2 as your media encoder (which is a very nice one).

Now. Go back to construct and add an action.


In the text field INSIDE the "". Paste these codes:






Putting between the '' the name of sound you initialized earlier.

Be warned that there is no easy way to debug a PhoneGap application, meaning that a js error somewhere will result in a blank screen. If this happens, remove one line of js at a time until you find the culprit of the error. It helps if you have experience in js because even a missing " will result in an error. I suggest you do this tutorial in steps. Add plugin, compile try. Add preloading, compile try. Add one play even, compile try. And so on.. This way you'll always know at what point the error appeared. Note that PhoneGap supports console.log() to log events inside the debugger (both xCode and Eclipse).

If you followed this tutorial you'll have NATIVE audio in your game, meaning that there will be 0 latency, audio concurrency and native controls.

I can't stress enough that this is currently the only way to have audio for a game in PhoneGap, the c2 audio object will result in a constant unplayable lag each time a sound is played.

I hope this has been helpful.



  • Order by
Want to leave a comment? Login or Register an account!