Sound Class

Matt Karl edited this page Dec 18, 2015 · 21 revisions

The Sound module is available through the springroll.Application's sound property. This is an instance of springroll.Sound. All of the loading and playing is managed by the Sound class.

Setup

Manual Context

Manually setup a context and sound manifest using addContext(). No other dependencies are required.

var app = springroll.Application({
	// options go here, like swfPath, types, etc
});

app.once('init', function()
{
	// Configure the sounds that can be played
	this.sound.addContext({
		context: "sfx",
		path: "assets/sounds/sfx/",
		sounds: [
			// will add "assets/sounds/sfx/Water.mp3" (or .ogg)
			"Water",
			"Crash",
			"Bang" 
		] 
	});

	// Sound is ready you can start playing here
	// sound will download the start playing when it's available
	// to preload the sound use this.sound.preload
	this.sound.play('Water');

	// Music can be played
	this.music = "Crash";

	// Or use the VO Player
	this.voPlayer.play("Bang");
});

Automatic Context

Contents of assets/config/config.json. Support for automatic context loading for sounds.sfx, sounds.vo and sounds.music. Below is setup for sounds.sfx only.

{
	"sounds": {
		"sfx": {
			"context": "sfx",
			"path": "assets/sounds/sfx/",
			"sounds": [
				"Water",
				"Crash",
				"Bang" 
			] 
		}
	}
}
var app = springroll.Application({
	configPath: "assets/config/config.json"
});

app.once('init', function()
{
	// Sound are already setup
	this.sound.play('Water');

	// Music can be played
	this.music = "Crash";

	// Or use the VO Player
	this.voPlayer.play("Bang");
});

options.swfPath

  • Type: string
  • Default: 'assets/swfs/'

The relative, absolute or root-relative path to the flashaudioplugin.swf provided with SoundJS. This provides the Flash-fallback support for web browsers that do not support WebAudio such as Internet Explorer.

options.types

  • Type: array
  • Default: ['ogg', 'mp3']

The priority list of file types to load. For example with the default settings, the browser will try to use the OGG audio format. If it is not supported, the browser will fallback to using MP3.

options.ready

  • Type: function
  • Default: null

The callback function when the Sound class has been fully initialized.

options.plugins

  • Type: array
  • Default: [createjs.WebAudioPlugin, createjs.FlashPlugin]

The priority list of plugins for SoundJS to use. For example with the default settings, the browser will attempt to use the WebAudioPlugin if it is support. If it is not supported, the browser will fallback to using FlashPlugin.

Configuring Sounds

Before sounds can be played, the Sound module needs know they exist. The sound property has a method called addContext to add a manifest of sound definitions. See this example:

app.sound.addContext({
	context: "sfx",
	path: "sounds/sfx/",
	sounds: [
		{id: "Water", src:"water-sound", volume:0.5},
		{id: "Crash", src:"crash-sound"},
		"Bang" // equivalent to {id: "Bang", src:"Bang", volume:1, loop:false}
	]
});

// Sound can now be played!
app.sound.play("Crash");

Configuration Properties

  • context string The user-defined sound group to add the sounds to. The Sound class can be used to call setContextMute, setContextVolume, etc to control all sounds within the context.
  • path string The relative folder-path to the audio files. If a basePath is defined on the springroll.Application instance, this is automatically prepended to this path.
  • sounds array The collection of sound definition resources (either an object or a string).

Sound Definition Properties

  • id string The alias for the sound. The alias is how a sound is played, stopped, muted, loaded, etc.
  • src string The base file name.
  • volume number (default:1) The default volume from 0 to 1.
  • loop boolean (default:false) The optional looping property, useful for music or other sounds that loop.

Preloading Sounds

If a sound is played via app.sound.play(alias) and the audio file has not been loaded, it will automatically load and play the sound. Lazy loading audio is not desirable in many situations, so the audio files should be preloaded before they're played when possible.

// no optional dependencies used
app.sound.preload("Water", function()
{
	// water sound is ready to go!
});
app.sound.preload(["Water", "Crash", "Bang"], function()
{
	// The sound aliases are ready to use!
});

Unloading Sounds

A sound that has been preloaded can be unloaded by calling the unload method and providing a list of aliases to unload or by calling unloadAll.

// Unload a list of sounds
app.sound.unload(["Water", "Crash", "Bang"]);
// Unload all sounds
app.sound.unloadAll();

Playing Sounds

The play() method is the best way to to play a sound by alias. There are a number of additional options that are provided to control the playback of sounds.

app.sound.play("Crash", {
	complete: function(){ 
		// Finished playing "Crash"
	}
});

Playing Options

  • complete function (default:null) The optional function to call when the sound is done.
  • start function (default:null) The optional function to call when the sound has started playing.
  • interrupt boolean (default:false) If the sound should interrupt previous sounds
  • delay number (default:0) The delay to play the sound at in milliseconds
  • offset number (default:0) The offset into the sound to play in milliseconds
  • loop int (default: 0) How many times the sound should loop. Use -1 (or true) for infinite loops. Default is no looping.
  • volume number (default:null) The volume to play the sound at (0 to 1). Omit to use the default specified in the sound manifest for the sound.
  • pan number (default:0) The panning to start the sound at (-1 to 1). Default is centered (0).

API Documentation

To see the full list of methods available to springroll.Sound please see the full documentation.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.