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.

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

Clears the event listener set via onPosition(), in the same way it was registered. If the callback is omitted, any and all callbacks registered for the given offset will be cleared.

Example: mySound.clearOnPosition(3000, positionHandler);

Example 2: mySound.clearOnPosition('mySound', 3000);

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.id+' reached '+eventPosition});

If you need to fire an event relative to the true duration of the sound, reference its duration once the sound has fully-loaded - ie., at or after the onload() event - as the duration will not be completely accurate until that time. durationEstimate may be referenced before onload(), but it should not be relied on when "precise" timings of say, < 1 second are desired.

Example:

mySound.load({
  onload: function() {
    this.onPosition(this.duration * 0.5, function(eventPosition) {
      console.log('the sound ' + this.id + ' is now at position ' + this.position + ' (event position: ' + eventPosition + ')');
    });
  }
});

Again, note that due to the interval / polling-based methods of both HTML5 and flash audio, sound status updates and thus precision can vary between 20 msec to perhaps 0.5 seconds and the sound's position property will reflect this delta when the onPosition() callback fires.

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

setPlaybackRate(playbackRate:number)

Sets HTML5 sound playback rate, between 0.5 and 4.0 of normal rate (1.0).

See playbackRate (Mozilla) for more information.

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 pointing the sound object to about:blank, which replaces the current one from loading.

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.id+' 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.id 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 9 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()

This method has been removed. Use the newer SMSound.onPosition() as a replacement.

onbeforefinish()

This method has been removed. Use the newer SMSound.onPosition() as a replacement.

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.id+' connected: '+(bConnect?'true':'false'));
  }
}).play(); // will result in connection being made

onerror(number:errorCode, string:description)

Fires when a sound fails to load (HTML5/flash), or fails during load or playback (HTML5-only.)

In the case of HTML5, an error code and matching description is provided when known.

This event is useful for explicit failure handling, particularly when tracking HTML5 errors. Note that HTML5 clients may fire errors after playback (or the first network request) has been initiated, so you should check the sound's loaded attribute before taking action.

Under HTML5, the loaded attribute is assigned once the HTML5 canplay event has fired - meaning that the user agent has downloaded enough of the sound to start playback.

In the case where onerror fires and loaded is true, sound playback may be resumable if the user is shown a play button and initiates playback via tap/touch/click - particularly on mobile. In this case, calling stop() within the error handler may help ensure that the sound's internal state is properly reset.

Example:

soundManager.createSound({
  url: '/404.mp3',
  onerror: function(code, description) {
    console.log(this.id + ' failed?', code, description);
    // Did the sound fail to load entirely, or failed during playback / loading partially?
    if (this.loaded) {
      // HTML5 case: network error, or client aborted download etc.?
      this.stop(); // Reset sound state, to be safe
      // Show play / retry button to user in UI?
    } else {
      // Load failed entirely. 404, bad sound format, etc.
    }
  }
}).play();

HTML5 error codes and descriptions are as follows, from whatwg.org:

• Error code 1, MEDIA_ERR_ABORTED: Client aborted download at user's request.
• Error code 2, MEDIA_ERR_NETWORK: A network error of some description caused the user agent to stop fetching the media resource, after the resource was established to be usable.
• Error code 3, MEDIA_ERR_DECODE: An error of some description occurred while decoding the media resource, after the resource was established to be usable.
• Error code 4, MEDIA_ERR_SRC_NOT_SUPPORTED: Media (audio file) not supported ("not usable.")

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.id+' 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()

This method has been removed. Use the newer SMSound.onPosition() as a replacement.

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

onsuspend()

HTML5-only event: Fires when a browser has chosen to stop downloading of an audio file.

Per spec: "The user agent is intentionally not currently fetching media data, but does not have the entire media resource downloaded."

One use case may be catching the behaviour where mobile Safari (iOS) will not auto-load or auto-play audio without user interaction, and using this event to show a message where the user can click/tap to start audio.

The HTML5 stalled event may also fire in desktop cases and might behave differently across browsers and platforms, so careful testing is recommended.

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.id+' 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.id+' playing, '+this.position+' of '+this.duration);

id

Sound ID string as provided from the id parameter via createSound(). Can be referenced as this.id 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[id] on the SoundManager global object.

Legacy note: The sound ID property used to be referenced as sID from within the sound object; this name is maintained for backward compatibility.

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.

Experimental feature: Multiple formats/encodings can now be applied to the url parameter by specifying an array instead of a single string.

Example:

soundManager.createSound({
  id: 'foo',
  url: ['bar.ogg','bar.mp3']
});

SoundManager 2 will use the first playable URL it finds (according to canPlayURL() and/or canPlayType()), and the URL property will then reflect the playable URL after that point. Note that this means the original array data will be lost.

In this alternate format, the array accepts "type" attributes.

soundManager.createSound({
  id: 'foo',
  // useful for URLs without obvious filetype extensions
  url: [
    {type:'audio/mp3',url:'/path/to/play.php?song=123'},
    {type:'audio/mp4',url:'/path/to/play.php?song=256'}
  ]
});

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.

buffered

Based loosely on the native HTML5 attribute, SM2 defines buffered as an array of objects which include start and end position (time) values. This property is updated during the SM2 whileloading event; internally, SM2 uses HTML5's progress event to track changes.

It is important to note that the buffered values may not always be contiguous and can change, particularly if the user seeks within the file during downloading. With ranges, you can draw highlighted segments on a progress bar UI which would reflect the current "slices" of buffered data.

Example: a buffered array of [{ start: 0, end: 2 }, { start: 5, end: 7 }]; shows a sound that has buffered data for the ranges 0-2 seconds, and 5-7 seconds.

In order to determine the total buffered data and thus "total percent loaded" under HTML5, you can loop through the buffered array and sum the total of (buffered[i].end - buffered[i].start). If you want to draw ranges, you can use the start and end values of each buffered item and draw that relative to the total duration (normalized as durationEstimate for flash compatibility).

Example:

var i, total = 0;
for (i=0, j=this.buffered.length; i<j; i++) {
  // draw current range in progress bar UI?
  drawProgressUI(this.buffered[i].start, this.buffered[i].end);
  // sum of all ranges vs. whole file duration
  total += (this.buffered[i].end - this.buffered[i].start);
}

Note that under Flash, downloading is always sequential and thus the buffered array will always be a single item with start: 0 and an end value of duration (eg., the amount of currently-downloaded "time").

Additional behaviour note: A browser might download additional bytes of a sound in advance under HTML5, but may only update the buffered state to reflect the newly-downloaded range(s) when the "playback head" reaches near the end of the current buffer. This can also be affected if the user seeks within the file.

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

This property has been removed. Use the newer SMSound.onPosition() as a replacement.

didJustBeforeFinish

This property has been removed. Use the newer SMSound.onPosition() as a replacement.

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.

(Flash-only): Once the sound has fully loaded (onload() has fired), durationEstimate will be updated with the final, Flash-calculated value of duration.

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

HTML5 behaviour: Both duration and durationEstimate are updated at regular intervals during loading of HTML5 audio, directly referencing the duration property provided on the native HTML5 object. Unlike Flash, HTML5 typically gets the true and final duration value by the time playback begins.

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.

isHTML5

Boolean property indicating whether a sound object is using HTML5 Audio for playback. Treat as read-only.

This should not really be relied on for anything, but it is provided as an indicator of support on a per-sound basis.

isHTML5 is set based on the URL provided to createSound(), and is updated when the URL changes.

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.

playbackRate

Number affecting HTML5 sound playback rate, between 0.5 and 4.0 of normal rate (1.0).

Can also be set via setPlaybackRate().

See playbackRate (Mozilla) for more information.

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

Under Flash, readyState will move from 0 to 1, and then change to 3 when the sound's onload() event fires (and all bytes have loade.)

Under HTML5, readyState will move from 0 to 1 when initializing the HTTP request (from load()), and will quickly change to 3 when the sound is ready to play. Note that HTML5 is buffer-based and onload() means "enough audio data has buffered to begin playback".

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.