SoundManager 2: Documentation

Sound Object Methods

Each sound under SoundManager 2 is given a SMSound object instance which includes the following events, methods and properties.

destroy()

Stops, unloads and destroys a sound.

Example: mySound.destroy();

play([options object])

Starts playing the given sound, with an optional options object. (Will start loading if applicable, and will play ASAP.)

Note that the options object parameter is not required and can take almost any argument from the object literal format (eg. volume.)

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

setPosition(msecOffset:integer)

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

Example: mySound.setPosition(2500);

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

pause()

Pauses the given sound. (Does not toggle.) Affects paused property (boolean.)

Example: mySound.pause();

resume()

Resumes the currently-paused sound. Does not affect currently-playing sounds.

Example: mySound.resume();

toggleMute()

Mutes/unmutes the given sound. Affected muted property (boolean.)

Example: mySound.toggleMute();

togglePause()

Pauses/resumes play of the given sound. Will also start a sound if it is has not yet been played.

Example: mySound.togglePause();

setVolume(volume:integer)

Sets the volume of the given sound. Accepted values: 0-100. Affects volume property.

Example: mySound.setVolume(50);

mute()

Mutes the given sound. Affects muted property.

Example: mySound.mute();

unmute()

Unmutes the given sound. Affects muted property.

Example: mySound.unmute();

setPan(volume:integer)

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

Example: mySound.setPan(-80);

stop()

Stops playing the given sound.

Example: mySound.stop();

unload()

Stops loading the given sound, canceling any current HTTP request.

Example: mySound.unload();

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

Sound Object Events

Like native 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.

onbufferchange()

Fires when a sound's reported buffering state has changed while playing and/or loading. The current state is reflected in the boolean isBuffering property.

Flash 9+ only. Related information on Adobe, Sound.isBuffering.

ondataerror()

Fires at least once per sound play instance when Flash encounters a security error when trying to call computeSpectrum() internally. This typically happens when sounds are 'inaccessible' due to another Flash movie (eg. YouTube) in another tab which has loaded, and may (or may not be) playing sound. Flash attempts to read the "combined" output to the sound card, and must have security permissions for all sounds as a result. See areSoundsInaccessible() on Adobe for more info.

If the offending resource causing the security error is closed or becomes inactive(?), the data will become available again. Intermittent availability will result in intermittent calls to ondataerror().

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.

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.

isBuffering

Boolean value reflecting the buffering state of a playing or loading object. To be notified when this property changes, see onbufferchange().

Flash 9+ only. Related information on Adobe, Sound.isBuffering.

loaded

Boolean value indicating load success as returned from Flash. True indicates success, False is a failure.

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.

muted

Boolean indicating muted status. True/False.

Treat as read-only; use mute(), unmute() and toggleMute() methods to affect state.

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

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 contains both left and right channels, and the data represents a raw sound wave rather than a frequency spectrum.

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

Note: Flash security measures may deny access to waveformData 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 waveformData 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);
}