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. Note that most methods will return the sound object instance, allowing for method chaining if desired.

destruct()

Stops, unloads and destroys a sound, freeing resources etc.

Example: mySound.destruct();

object:SMSound load([options object])

Starts loading the given sound, with options if specified.

Example: mySound.load();

Example 2: mySound.load({volume:50,onfinish:playNextSound});

object:SMSound mute()

Mutes the given sound. Affects muted property.

Example: mySound.mute();

object:SMSound onposition(msecOffset:integer, callback:function, [scope])

Registers an event listener, fired when a sound reaches or passes a certain position while playing. Position being "listened" for is passed back to event handler. Will also fire if a sound is "rewound" (eg. via setPosition() to an earlier point) and the given position is reached again. Listeners will be removed if a sound is unloaded. An optional scope can be passed as well.

Note that for multiShot cases, only the first play instance's position is tracked in Flash; therefore, subsequent "shots" will not have onposition() events being fired.

Example: mySound.onposition(3000, function(eventPosition){console.log(this.sID+' reached '+eventPosition});

object:SMSound pause()

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

Example: mySound.pause();

object:SMSound 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});

object:SMSound setPosition(msecOffset:integer)

Seeks 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.

object:SMSound resume()

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

Example: mySound.resume();

object:SMSound 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);

object:SMSound setVolume(volume:integer)

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

Example: mySound.setVolume(50);

object:SMSound toggleMute()

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

Example: mySound.toggleMute();

object:SMSound togglePause()

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

Example: mySound.togglePause();

object:SMSound stop()

Stops playing the given sound.

Example: mySound.stop();

object:SMSound 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.

object:SMSound unmute()

Unmutes the given sound. Affects muted property.

Example: mySound.unmute();

Sound Object Events

Like native javascript objects, each SoundManager SMSound (sound instance) object can fire a number of onload-like events. Handlers cannot be "directly" assigned (eg. someSound.onload), but can be passed as option parameters to several sound methods.

soundManager.play('mySound',{
  onfinish: function() {
    alert('The sound '+this.sID+' finished playing.');
  }
});

Event handlers are scoped to the relevant sound object, so 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.

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().

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.

onconnect()

Fires when a sound using an RTMP serverURL property has attempted to connect, and has either succeeded or failed. Affects connected property. Once connected, a stream can be requested from the RTMP server.

Example:

var s = soundManager.createSound({
  id: 'rtmpTest',
  serverURL: 'rtmp://localhost/test/',
  url: 'song.mp3',
  onconnect: function(bConnect) {
    // this.connected can also be used
    soundManager._writeDebug(this.sID+' connected: '+(bConnect?'true':'false'));
  }
}).play(); // will result in connection being made

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.

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.

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.)

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].)

onpause()

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

Example: soundManager.pause('mySound');

onplay()

Fires when sound.play() is called.

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.

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.

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);

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, typically over HTTP. Can be referenced as this.url from within sound object event handlers such as onload() or whileplaying(), etc.

serverURL

Note: Experimental feature. Only for use with RTMP streaming, ie., Flash Media Server and similar servers.

The RTMP server address which Flash will connect to using a NetStream object. Only the server address is specified here, when RTMP is in use; the url property is used to point to a specific resource on the server.

Example:

soundManager.createSound({
  id: 'mySound',
  serverURL: 'rtmp://localhost/rtmpDemo/', // RTMP server
  url: 'mysong.mp3' // path to stream
}).play();

usePolicyFile

Boolean value (default: false) which instructs Flash, when loading MP3/MP4 content from remote/third party domains, to request example.com/crossdomain.xml first in order to determine permissions for access to metadata such as ID3 info, waveform, peak and/or spectrum data.

usePolicyFile will be automagically set to true if your sound options have an onid3() event handler, or uses sound data (peak/wave/spectrum) features. By default, Flash will not have access to this metadata on remote domains unless granted cross-domain security permissions via the crossdomain.xml file.

Consider additional HTTP traffic (albeit, perhaps with caching-like behaviour for subsequent checks?) and silent 404s in most cases given few hosts use crossdomain.xml files.

See Adobe's knowledge base for related ID3 + crossdomain.xml documentation.

bytesLoaded

The number of bytes currently received while loading a sound.

bytesTotal

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

didBeforeFinish

Boolean indicating whether beforeFinish() condition was reached.

didJustBeforeFinish

Boolean indicating whether justBeforeFinish() condition was reached.

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.

eqData = {left:[], right: []}

Object containing two arrays of 256 floating-point (three decimal place) values from 0 to 1, the result of an FFT on the waveform data. 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.left[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 can eat up a lot of CPU in some cases. 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.

Backward compatibility note: Up to SoundManager 2.95a.20090717, eqData was a single array containing one channel of data. In newer versions this is unchanged, except the array now has .left[] and .right[] objects attached to it. To ensure future compatibility, use eqData.left[0] instead of eqData[0] and so on.

id3

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

For property details, see onid3().

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.

connected

Boolean value reflecting the state of an RTMP server connection (when serverURL is used to connect to a Flash Media Server or similar RTMP service.) Calls to load or play will result in a connection attempt being made, and onconnect() ultimately being called.

For example code using connected, see onconnect().

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.

paused

Boolean indicating pause status. True/False.

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

peakData = {left:0.0, right:0.0}

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);
}

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.

position

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

readyState

Numeric value indicating a sound's current load status

0 = uninitialised

1 = loading

2 = failed/error

3 = loaded/success

type

A MIME type-like string eg. audio/mp3, used as a hint for SM2 to determine playability of a link with methods like canPlayURL().

This can be helpful when you have a sound URL that does not have an .mp3 extension, but serves MP3 data (eg., a PHP or other CGI script.)

Example:

var s = soundManager.createSound({
  id: 'aSound',
  url: '/path/to/some.php?songID=123',
  type: 'audio/mp3' // indicates an MP3 link, so SM2 can handle it appropriately
});

waveformData = {left:[], right:[]}

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.left[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 can eat up a lot of CPU in some cases. 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.