doc22940 / audiomanager

play sounds using Web Audio, fallback on HTML5 Audio

AudioManager

Play sounds using Web Audio, fallback on HTML5 Audio. AudioManager is specifically designed to works for games that have a big quantity of audio assets. Loading and unloading is made easy and transparent.

API

// initialisation
var audioManager = new AudioManager(channelIds);
audioManager.init();
audioManager.setVolume(channelId, volume);

// play simple sound
audioManager.playSound(channelId, soundId, volume, panoramic, pitch);

// sound group
audioManager.createSoundGroups(soundGroupDefs, channelId);
audioManager.createSoundGroup(soundGroupId, soundGroupDef, muted);
audioManager.playSoundGroup(channelId, groupId, volume, panoramic, pitch);

// loop
audioManager.playLoopSound(channelId, soundId, volume);
audioManager.stopLoopSound(channelId);
audioManager.stopAllLoopSounds();

// release memory
audioManager.release();

Documentation

Create audioManager object and channels

Pass the list of channels to the constructor as an array of strings.

var channels = ['music', 'sfx', 'ui'];
var audioManager = new AudioManager(channels);

Setup audioManager path to sound assets folder

audioManager.settings.audioPath = 'assets/audio/';

Start audio engine.

To work correctly on iOS, this must be called on an user interaction e.g. user pressing a button. (C.f. this page to understand how this work.)

gameStartButton.on('tap', function () {
	audioManager.init();
});

Set channel volume

By default, channel volume is set to 0 and channel is muted. No sounds will play until channel volume is set.

var volume = 1.0; // volume is a float in range ]0..1]
audioManager.setVolume('ui', volume);

Create and play a simple sound.

Create a sound and playing it in a channel. Sound is created and loaded automatically.

var fileName = 'laser1';
audioManager.playSound('sfx', fileName);

// volume and panoramic can be set optionally
var volume    = 0.7; // volume is a float in range ]0..1]
var panoramic = 0.9; // panoramic is a float in range [-1..1], 0 is the center
audioManager.playSound('sfx', fileName, volume, panoramic);

Sounds creation and preloading can be forced.

audioManager.createSound(fileName).load();

Alternatively, sounds can be played outside channels.

var sound = audioManager.createSound(fileName);
sound.play(volume, panoramic, pitch); // all parameters are optional.

Detect playback end

An onEnd callback function can be set to be triggered everytime the playback ends. Set it back to null to remove it.

sound.onEnd = function () {
	console.log('sound playback ended');
	sound.onEnd = null;
};

Change pitch

This feature is only available with WebAudio.

var pitch = -7.0; // in semi-tone
sound.setPitch(pitch);

The pitch can be set at play.

audioManager.playSound('ui', fileName, volume, panoramic, pitch);

While a sound is playing, the pitch can be changed dynamically

var portamento = 3.0;
sound.setPitch(pitch, portamento);

Create and play sound groups.

A sound group is a collection of sounds that will play alternatively in a round-robin pattern on each play call.

var soundGroupDef = {
	id:  ['punch1', 'punch2'],
	vol: [1.0, 0.8],
	pitch: [0.0]
};
audioManager.createSoundGroups('punch', soundGroupDef);

var volume    = 0.8; // volume is a float in range ]0..1]
var panoramic = 0.3; // panoramic is a float in range [-1..1], 0 is the center
var pitch     = 3.0; // in semi-tone
audioManager.playSoundGroup('sfx', 'punch', volume, panoramic, pitch);

You can create several sound groups in one function call

var soundGroupDefs = {
	groupId1: { id: ['sound1', 'sound2'], vol: [1.0, 0.8], pitch: [0.0] },
	groupId2: { ... },
	...
};
audioManager.createSoundGroups(soundGroupDefs, 'sfx');

Play and stop looped sounds

Only one loop can play per channel. Playing a new looped sound in the same channel will stop current playing sound before starting new one.

var volume   = 1.0; // volume is a float in range ]0..1]
var fileName = 'bgm1';
audioManager.playLoopSound('music', fileName, volume);
audioManager.stopLoopSound('music'); // stop looped sound in channel 'music'
audioManager.stopAllLoopSounds();    // stop all looped sounds in all channel

How looped sound fades and mixes can be set by modifying audioManager settings:

audioManager.settings.defaultFade = 3;    // value in second
audioManager.settings.crossFade   = true; // default is false

Release memory

audioManager.release();

Custom loader function

audioManager.settings.getFileUri can be overriden if you want more control on how to resolve files uri from sound id. The function have one on the following synchronous or asynchronous profile:

function getFileUriSync(audioPath, id) {
	var uri;
	// ...
	return uri;
}

function getFileUriAsync(audioPath, id, callback) {
	var uri;
	var error = null;
	// ...
	return callback(error, uri);
}

For instance, here's how you can add wizAssets to cache files on disc in a PhoneGap application:

if (window.wizAssets) {
    audioManager.settings.getFileUri = function wizAssetsGetUri(audioPath, id, cb) {
        window.wizAssets.downloadFile(audioPath + id + '.mp3', 'audio/' + id + '.mp3', 
            function onSuccess(uri) {
                cb(null, uri)
            }, 
            cb // onFail callback
        );
    }
}