SoundManager 2

Audio for Javascript

• Plain English
• Web 2.0-speak
• ZOMG WEB 3.0

Licensing

SoundManager 2 is provided free of charge under a BSD license. If you find a nifty or innovative use for it (or just want to comment), feedback is always appreciated.

SoundManager API

The following are methods, collections, properties and event handlers provided by the globally-scoped soundManager Javascript object. Both sound properties and methods can be set on a global (inherited) default, or per-sound basis.

SoundManager Core Methods

object:SMSound createSound(object:options)

Creates a sound with an arbitrary number of optional arguments. Returns a SMSound object instance.

Example:

soundManager.createSound({
 id: 'mySound', // required
 url: '/audio/mysoundfile.mp3', // required
 // optional sound parameters here, see Sound Properties for full list
 volume: 50,
 autoPlay: true,
 whileloading: soundIsLoading // remember to omit comma on the last item
});

Each createSound() call results in the creation of a SMSound object which stores all properties, methods and events relevant to that particular sound instance.

Individual sound objects can also easily be referenced as returned from createSound():

var mySoundObject = soundManager.createSound({
 id: 'mySound',
 url: '/audio/mysoundfile.mp3'
});
mySoundObject.play(); // SMSound object reference, same as soundManager.getSoundById('mySound')

(Note: Code formatting is stylistic, not necessarily recommended.) See Object Literal Format.

createSound(id:string,url:string)

Creates a sound with the specified ID and URL (simple method.)

Example: soundManager.createSound('mySound','/audio/mysoundfile.mp3');

destroySound(id:string)

Stops, unloads and destroys a sound specified by ID.

Example: soundManager.destroySound('mySound');

didCreate:boolean play(id:string,[options object])

Starts playing the sound specified by ID. (Will start loading if applicable, and will play ASAP.)

Optionally, returns a boolean value indicating "sound created", ie. if the related sound object didn't exist prior to this call and was created to do so.

Example: soundManager.play('mySound');

Note that the second parameter, options object, is not required and can take almost any argument from the object literal format (eg. volume.) These should be applied on an instance-specific basis (only overriding existing options for this play instance), but may persist due to an incomplete implementation. (To be fixed.)

Example: soundManager.play('mySound',{volume:50,onfinish:playNextSound});

setPosition(id:string,msecOffset:integer)

Seeeks to a given position within a sound, specified by miliseconds (1000 msec = 1 second.) Affects position property.

Example: soundManager.setPosition('mySound',2500);

Can only seek within loaded sound data, as defined by the duration property.

pause(id:string)

Pauses the sound specified by ID. (Does not toggle.) Affects paused property (boolean.)

Example: soundManager.pause('mySound');

resume(id:string)

Resumes the currently-paused sound specified by ID.

Example: soundManager.resume('mySound');

togglePause(id:string)

Pauses/resumes play on the sound specified by ID.

Example: soundManager.pause('mySound');

setVolume(id:string,volume:integer)

Sets the volume of the sound specified by ID. Accepted values: 0-100. Affects volume property.

Example: soundManager.setVolume('mySound',50);

mute([id:string])

Mutes the sound specified by ID. If no ID specified, all sounds will be muted.

Example: soundManager.mute('mySound');

unmute([id:string])

Unmutes the sound specified by ID. If no ID specified, all sounds will be unmuted.

Example: soundManager.unmute('mySound');

setPan(id:string,volume:integer)

Sets the stereo pan (left/right bias) of the sound specified by ID. Accepted values: -100 to 100 (L/R, 0 = center.) Affects pan property.

Example: soundManager.setPan('mySound',-80);

stop(id:string)

Stops playing the sound specified by ID.

Example: soundManager.stop('mySound');

stopAll()

Stops any currently-playing sounds.

Example: soundManager.stopAll();

unload(id:string)

Stops loading the sound specified by ID, canceling any current HTTP request.

Example: soundManager.unload('mySound');

Note that SoundManager does this by loading a new, tiny "stub" MP3 file, ./data/null.mp3, which replaces the current one from loading. This is defined in the SM2 global object as nullURL, and can be edited.

getSoundById(id:string)

Returns an SMSound object specified by ID.

Example: var mySMSound = soundManager.getSoundById('mySound');

loadFromXML(xmlURL:string)

Loads and creates sounds as defined in a SoundManager v1 XML file (legacy)

Note that per-sound options are not supported with this method, and sound objects will be created immediately upon loading and parsing of the XML. The sounds will inherit the defaultOptions settings, with the exception of the stream attribute as set in the XML (true if defined, defaultOption applied if omitted.)

Example: soundManager.loadFromXML('/path/to/some.xml');

XML format example: MPC drumkit XML file

supported:boolean supported()

Returns a boolean indicating whether soundManager has attempted to and succeeded in initialising. This function will return false if called before initialisation has occurred.

Example: var isSupported = soundManager.supported();

SMSound (Sound Object) Properties

Each createSound() call generates a matching SMSound (sound instance) object, which lasts for the life of the page or until explicitly destroyed. Each instance stores stateful information (eg. playState) and provides event handlers for state changes (eg. onload().)

sID

Sound ID string as provided from the id parameter via createSound() or play(). Can be referenced as this.sID from within sound object event handlers such as onload(), whileloading() or whileplaying(), etc.

If an ID is known, the related SMSound object can be retrieved via getSoundById or directly referencing sounds[sID] on the SoundManager global object.

url

The specified URL from which the sound is loaded. Can be referenced as this.url from within sound object event handlers such as onload() or whileplaying(), etc.

id3

An object literal populated, if applicable, when ID3 data is received (related handler: onid3())

For property details, see onid3().

bytesLoaded

The number of bytes currently received while loading a sound.

bytesTotal

The total number of bytes to be downloaded, while loading a sound.

position

The current location of the "play head" within the sound, specified in milliseconds (1 sec = 1000 msec).

duration

The current length of the sound, specified in milliseconds.

Note that during loading, this property reflects the length of downloaded data, not the full length, until completely loaded (see whileloading().) For an approximate "full duration" value while loading, see durationEstimate.

durationEstimate

The estimated duration of the sound, specified in milliseconds.

Due to the dynamic nature of duration while loading, this attempts to provide the full duration by calculating parseInt((self.bytesTotal/self.bytesLoaded)*self.duration) and is updated with each whileloading() interval.

Once the sound has fully loaded, duration should be referenced as it will contain the final and accurate value.

Note that this method works only with Constant Bitrate (CBR)-encoded MP3s due to the consistent data/time assumption. VBR-encoded MP3s will give inaccurate results.

loaded

Boolean value indicating load success as returned from Flash. True indicates success, False is a failure or strangely, a successful load (?) from cache.

Because of the potential for false positives, duration and other properties could be checked as a test of whether sound data actually loaded. For more granular state information, see readyState.

playState

Numeric value indicating the current playing state of the sound.

0 = stopped/uninitialised

1 = playing or buffering sound (play has been called, waiting for data etc.)

Note that a 1 may not always guarantee that sound is being heard, given buffering and autoPlay status.

paused

Boolean indicating pause status. True/False.

Treat as read-only; use pause(), resume() and togglePause() methods to affect state.

readyState

Numeric value indicating a sound's current load status

0 = uninitialised

1 = loading

2 = failed/error

3 = loaded/success

didBeforeFinish

Boolean indicating whether beforeFinish() condition was reached.

didJustBeforeFinish

Boolean indicating whether justBeforeFinish() condition was reached.

waveformData (previously spectrumData)

Array of 256 floating-point (three decimal place) values from -1 to 1, can be used to draw a waveform while playing a sound. See Page-as-playlist demo for example implementation. Requires Flash 9+.

waveformData is set and updated during whileplaying(). A simple graph could be drawn by looping through the values and multiplying by a vertical scale value (eg. 32, which would make a graph with peaks of -32 and +32 pixels.)

Example code:

someSoundObject.whileplaying = function() {
  // Move 256 absolutely-positioned 1x1-pixel DIVs, for example (ugly, but works)
  var gPixels = document.getElementById('graphPixels').getElementsByTagName('div');
  var gScale = 32; // draw -32 to +32px from "zero" (i.e., center Y-axis point)
  for (var i=0; i<256; i++) {
    graphPixels[i].style.top = (gScale+Math.ceil(this.waveformData[i]*-gScale))+'px';
  }
}

SM2 implementation note: waveformData currently contains the left channel data only, and the data represents a raw sound wave rather than a frequency spectrum. You could edit the SM2 Flash 9 .as source for this directly, if you wish (source code is provided.)

Related Adobe technical documentation (Flash 9/AS3 Sound() object): computeSpectrum()

Note: Flash security measures may deny access to spectrumData when loading MP3s from remote domains.

Warning: This feature is experimental, and will probably eat up a lot of CPU. The amount of data passed from Flash to JS is not terribly large, but the JS-DOM updates and browser reflow can be expensive. Use with caution.

eqData

Array of 256 floating-point (three decimal place) values from 0 to 1, can be used to draw a spectrum (frequency range) graph while playing a sound. See Page-as-playlist demo for example implementation. Requires Flash 9+.

A spectrum frequency graph reflects the level of frequencies being played, from left to right, low to high (i.e., 0 to 20,000 Hz.)

eqData is set and updated during whileplaying(). A simple graph could be drawn by looping through the values and multiplying by a vertical scale value (eg. 32, thus a graph with peaks of 32 pixels.)

Example code:

someSoundObject.whileplaying = function() {
  // Move 256 absolutely-positioned 1x1-pixel DIVs, for example (ugly, but works)
  var gPixels = document.getElementById('graphPixels').getElementsByTagName('div');
  var gScale = 32; // draw 0 to 32px from bottom
  for (var i=0; i<256; i++) {
    graphPixels[i].style.top = (32-(gScale+Math.ceil(this.waveformData[i]*gScale)))+'px';
  }
}

Related Adobe technical documentation (Flash 9/AS3 Sound() object): computeSpectrum()

Note: Flash security measures may deny access to spectrumData when loading MP3s from remote domains.

Warning: This feature is experimental, and will probably eat up a lot of CPU. The amount of data passed from Flash to JS is not terribly large, but the JS-DOM updates and browser reflow can be expensive. Use with caution.

peakData

Object literal format including left and right properties with floating-point values ranging from 0 to 1, indicating "peak" (volume) level. Updated during whileplaying(). See Page-as-playlist demo as one example. Requires Flash 9+.

Example (within relevant sound object handler):

someSoundObject.whileplaying = function() {
  soundManager._writeDebug('Peaks, L/R: '+this.peakData.left+'/'+this.peakData.right);
}

SMSound (Sound Object) Events

Not unlike common javascript objects, each SoundManager SMSound (sound instance) object can fire a number of events including onload and others. Functions can be assigned and will be called as needed, and are scoped to the relevant sound object. Specifically, the this keyword will point to the sound object on which the event fired such that its properties can easily be accessed - eg. within an SMSound event handler, this.sID will give the sound ID.

onload(boolean:success)

Fires on sound load. Boolean reflects successful load (true), or fail/load from cache (false).

False value should seemingly only be for failure, but appears to be returned for load from cache as well. This strange behaviour comes from Flash. More detail may be available from the Flash 8 sound object documentation.

Failure can occur if the Flash sandbox (security) model is preventing access, for example loading SoundManager 2 on the local file system and trying to access an MP3 on a network (or internet) URL. (Security can be configured in the Flash security panel, [see here].)

whileloading()

Fires at a regular interval when a sound is loading and new data has been received. The relevant, updated property is bytesLoaded.

Example handler code: soundManager._writeDebug('sound '+this.sID+' loading, '+this.bytesLoaded+' of '+this.bytesTotal);

Note that the duration property starts from 0 and is updated during whileloading() to reflect the duration of currently-loaded sound data (ie. when a 4:00 MP3 has loaded 50%, the duration will be reported as 2:00 in milliseconds.) However, an estimate of final duration can be calculated using bytesLoaded, bytesTotal and duration while loading. Once fully-loaded, duration will reflect the true and accurate value.

onplay()

Fires when sound.play() is called.

whileplaying()

Fires at a regular interval when a sound is playing, and a position (time) change is detected. The relevant, updated property is position.

Example handler code: soundManager._writeDebug('sound '+this.sID+' playing, '+this.position+' of '+this.duration);

onpause()

Fires when a sound pauses, eg. via sound.pause().

Example: soundManager.pause('mySound');

onresume()

Fires when a sound resumes playing, eg. via sound.resume().

Example: soundManager.resume('mySound');

onstop()

Fires when sound.stop() is explicitly called. For natural "sound finished" onfinish() case, see below.

onfinish()

Fires when a playing sound has reached its end. By this point, relevant properties like playState will have been reset to non-playing status.

onbeforefinishcomplete()

Fires when a sound has finished, onfinish() has been called, but before the sound play state and other meta data (position, etc.) are reset.

onbeforefinish()

Fires when a playing, fully-loaded sound has reached onbeforefinishtime (eg. 5000 msec) from its end.

onjustbeforefinish()

Fires approximately justbeforefinishtime before the end of a fully-loaded, playing sound.

This is based on a polling approach given SM2 must track the sound's position, and is approximated (eg. a 200 msec value may fire at 187 msec before the end of the sound.)

onid3()

Fires when ID3 data has been received. Relevant property is id3, which is an object literal (JSON)-style object. Only fields with data will be populated.

Note that ID3V2 data is located at the beginning (header) of an MP3 file and will load almost immediately, whereas ID3V1 data is at the end and will not be received until the MP3 has fully loaded.

Example handler code:

soundManager._writeDebug('sound '+this.sID+' ID3 data received');
var prop = null;
var data = '';
for (prop in this.id3) {
  data += prop+': '+this.id3[prop]+','; // eg. title: Loser, artist: Beck
}

Refer to the Flash 8 Sound.id3 documentation for a list of ID3 properties.

When parsing ID3 data, it is best to check for the existance of ID3V1 data first, and apply ID3V2 if no matching ID3V1 data is defined. (V1 should "inherit" from V2, ideally, if available.)

Note that Flash's cross-domain security restrictions may prevent access to ID3 information, even though the MP3 itself can be loaded. (crossdomain.xml files on the remote host can grant Flash permission to access this.)

Also note some issues with parsing ID3 from iTunes.

SMSound (Sound Object) Methods

SoundManager provides wrappers for all SMSound methods - eg. soundManager.play('mySound') checks for a valid sound object, and then calls soundManager.sounds['mySound'].play() on that particular object.

The following methods can be called directly on a SMSound instance. The method calls are the same as the SoundManager global methods documented above for existing sound objects, minus the sound ID parameter.

play([options object])

setPosition(msecOffset:integer)

pause()

resume()

togglePause()

mute()

unmute()

setVolume(volume:integer)

setPan(pan:integer)

stop()

unload()

destruct() (called via soundManager.destroySound())

SoundManager Core Events

The following events are attached to the soundManager global object and are useful for detecting the success/failure of the API's initialisation.

Keep in mind that these core events are effectively asynchronous (ie., they may fire long before or after window.onload()) and therefore should not be relied on as the "ready" event for starting your application. Use the standard "DOM content loaded" or window load events for your own initialization routines.

onload()

Function called when SoundManager has successfully loaded.

Example: soundManager.onload = function() { alert('SoundManager ready to use'); }

Once this function has been called, all core methods will be available to use.

Note that onload() is not called when SoundManager fails to load; instead, onerror() is called.

onerror()

Function called when SoundManager fails to successfully initialise after Flash attempts an init call via ExternalInterface.

Example: soundManager.onerror = function() { alert('SoundManager failed to load'); }

This handler should be called if there is an ExternalInterface problem or other exceptions that fire when the initialisation function is called.

SoundManager Object Collections

soundIDs[]

An array of sound ID strings, ordered by creation. Can be used to iterate through sounds{} by ID.

sounds{}

An object literal/JSON-style instance of SMSound objects indexed by sound ID (as in sounds['mySound'] or sounds.mySound), used internally by SoundManager. soundManager.getSoundById() may be used as an alternate to directly accessing this object.

"Use Responsibly"

A Word Of Vice

Not every button, link, element or paragraph on the web needs to zoom, move, change colour and be noisy, repetitive and annoying all at the same time. Use your own discretion!

Sites which automatically start playing background sound, and/or don't have volume or mute controls are the kind of things you should avoid building. As a developer, gentle reader, you may eventually find yourself in such a situation. Please do your part in enhancing the web with sound if you use SM2, while at the same time keeping it audibly usable. :)

Demo Credits

Background Tile

Modified from squidfingers.com (free patterns)

Sound Sources

MPC Demo Sounds downloaded from AKAI.com

Theme switch: User pempi, freesoundproject (Creative Commons Sampling Plus 1.0 License)

Tab switch: User TicTacShutUp, freesoundproject (Creative Commons Sampling Plus 1.0 License)

Related Projects

JavaScript/DHTML/Flash MP3 players

If you're searching for an included/embedded-type media player, these related projects might of use.

• Yahoo! Media Player supports a number of different formats depending on installed plugins (WMA etc.), can display artist / album information and so on.
• JSSoundkit, an MP3 player with a simple UI.

Links

• SoundManager 2 Project Page (schillmania.com)
• Flash 8 sound object documentation (livedocs.macromedia.com)
• Flash Player Global Security Settings Panel - Configure your Flash Player security, eg., allow SM2 .swf on your local filesystem to have internet access for testing by whitelisting its location eg. file://Users/Administrator/Desktop/soundmanager... etc. Alternately, view the page over HTTP and access internet resources that way.