spilgames/audio51

A device-agnostic approach to snappy soundFX

Audio51, a no-nonsense solution for Audio in HTML5

Copyright (C) 2014, SpilGames
all rights reserved
licensed under the BSD 3-Clause license, see the license file
created by Martin Reurings

Get Started

1. Current implementation requires the use of an AMD compatible library. The most popular one (as far as I can tell) would be requirejs. So, until Audio51 has been refactored, this is a requirement.

2. A second requirement is RSVP, which has been packaged in liblocal. This is not a recent version and does not need AMD. Simply include the liblocal/rsvp.js.

3. All you need to play audio-clips at this point is to require audio51 (as defined in audio51.js). All other requirements are then pulled in. In code it would look something like this:

require(["audio51"], function(audio51) {
	audio51.loadSoundSet('sounds.json');
	audio51.play("thunder");
});

4. To create a 'sound set' this library makes use of a format generated by audiosprite, which is an node-based tool. It is recommended to install audiosprite and then, from your project directory run the following command to generate a sound set: audiosprite -p mp3,ogg,ac3 -o [destination] -e mp3,ogg,ac3 -c 2 [comma-separated list of sounds].

The above example is verry simplistic and will not work on mobile because unfortunately on mobile the audio needs to be 'unlocked' by user-interaction before it can be used. The audio51 code handles this transparently by simply unlocking your audio at the first user-interaction. However, depending on the audio-support available on the target device, playing audio before this has happend may lock your audio into silence.

The unrestrict module can be used to detect when the unlocking is executed, allowing you carefull control over your scripts. Simply create a listener using:

require(["unrestrict"], function(unrestrict) {
	unrestrict.on("userInteraction", function() {
		//place your code here...
	});
});

This document is intended to be an up to date affair, so check back often to see if any improvements to the library have made it even easier to use!

Unit testing

Currently there are still some bugs in the WebAudio API implmentation. Some of these came up while attempting to create an easy to use unit-testing environment. Most notably:

1. Safari failed to fire canPlay event if the first audio would be generated by an AudioTag node.
2. After generating sound through an Oscillator Source, after stopping and disconnecting the Oscillator, the analyzer node registers a volume of up to 100, while it should be 0.

The first of these should be taken into account when testing AudioTag implementations and they fail only in Safari. The second can easily be prevented in our current API, we only intend to support playing sound from files...

audio51's Issues

Make use of audio sprites

From the documentation one would assume the library makes use of audio sprites (as audiosprite is referenced), but it doesn't actually use it. It loads seperate sound files and translates the names according to a JSON file. Using audio sprites in HTML5 would be very benificial (https://hacks.mozilla.org/2012/04/html5-audio-and-audio-sprites-this-should-be-simple/)

Update: it appears that audio sprites are implemented in a way, but only for mobile devices where Web Audio is not supported. Moreover, it is incomplete and poorly implemented.

Too many sounds loaded

Fix the for in loop

Prepend namespace name

Prepend namespace name so audio51 can be imported more easily into other projects

Import sounds

Audio51 only has methods to load sounds by making new XMLHttpRequests. There should be a method to provide sounds which were loaded in by other means (outside the library).
Also, adding callbacks for loaded sounds would be a plus.

Get end of sound

Sound object needs a functionality to get the playing state

Add volume controls

There is no functionality for controlling the volume