SoundManager 2

What is SoundManager?

(Choose your language)

• Web 2.0-speak
• Plain English

Demos

Less Talk, More Show.

Some examples of Javascript-driven sound, and applications implementing SoundManager 2:

• jsAMP MP3 Player Preview Demo | jsAMP with debug output
• SoundManager 2 MPC demo
• SoundManager 2 animation demo
• SoundManager 2 basic demo (simple API call examples)

Getting Started

"I'd like to use this on my site. Where do I start?"

No problem! See this template example which shows the basic requirements of SoundManager 2. (For technical requirements, refer to Requirements + Specifications.)

Like a fine whiskey, SoundManager should come with a disclaimer that reads, "Use Responsibly." You should know when to stop, too.

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.

Download

Current version: 2.0b.20070415

SoundManager v2.0b.20070415 (1.4 MB, .zip)

Includes API, ActionScript source, documentation, examples and demos.

Basic Use

<script type="text/javascript" src="soundmanager2.js"></script>

<script type="text/javascript">soundManager.createMovie();</script>

<script type="text/javascript">soundManager.createMovie('/path/to/soundmanager2.swf');</script>

soundManager.play('mySound','/path/to/some.mp3');

soundManager.createSound('myNewSound','/path/to/some.mp3');

soundManager.play('myNewSound');
soundManager.setVolume('myNewSound',50);
soundManager.setPan('myNewSound',-100);

soundManager.onload = function() {
  // soundManager should be ready to use/call at this point
  soundManager.createSound('mySound','/path/to/mysoundfile.mp3');
  soundManager.play('mySound');
}

soundManager.onerror = function() {
  // soundManager failed to initialise (security restrictions, no support, missing SWF etc.)
  // Notify user if needed, disable sound-specific functionality etc.
}

soundManager.createSound({
  id: 'mySound',
  url: '/path/to/some.mp3',
  autoLoad: true,
  autoPlay: false,
  onload: function() {
    alert('The sound '+this.sID+' loaded!');
  },
  volume: 50
});

This object can also be passed as an optional argument to the play method, overriding options set at creation time.

For a full list of available options, see Sound Properties Object

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

createSound(object:options)

Creates a sound with an arbitrary number of optional arguments.

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.

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

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

pause(id:string)

Pauses the sound specified by ID. (Does not toggle.)

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

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

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

Sound Properties Object

The soundManager.defaultOptions object contains parameters which are inherited by default when sounds are made via createSound. They can be overridden on a per-sound basis at create time, or changed dynamically in some cases. Note that none of these options are required when calling createSound, as the defaults will be inherited if unspecified.

soundManager.defaultOptions apply the properties and event handlers as specified above. Defaults are shown below as an example.

soundManager.defaultOptions = {
  'autoLoad': false,             // enable automatic loading (otherwise .load() will be called on demand with .play()..)
  'stream': true,                // allows playing before entire file has loaded (recommended)
  'autoPlay': false,             // enable playing of file as soon as possible (much faster if "stream" is true)
  'onid3': null,                 // callback function for "ID3 data is added/available"
  'onload': null,                // callback function for "load finished"
  'whileloading': null,          // callback function for "download progress update" (X of Y bytes received)
  'onplay': null,                // callback for "play" start
  'whileplaying': null,          // callback during play (position update)
  'onstop': null,                // callback for "user stop"
  'onfinish': null,              // callback function for "sound finished playing"
  'onbeforefinish': null,        // callback for "before sound finished playing (at [time])"
  'onbeforefinishtime': 5000,    // offset (milliseconds) before end of sound to trigger beforefinish..
  'onbeforefinishcomplete':null, // function to call when said sound finishes playing
  'onjustbeforefinish':null,     // callback for [n] msec before end of current sound
  'onjustbeforefinishtime':200,  // [n] - if not using, set to 0 (or null handler) and event will not fire.
  'multiShot': true,             // let sounds "restart" or layer on top of each other when played multiple times..
  'pan': 0,                      // "pan" settings, left-to-right, -100 to 100
  'volume': 100                  // self-explanatory. 0-100, the latter being the max.
}

Note: For live examples, see the code behind the jsAMP MP3 Player demo which uses much of this functionality.

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 such as onload().

sID

Sound ID string as provided from createSound() or play().

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.

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.

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 seemingly-strange behaviour comes from Flash. More detail may be available from the Flash 8 sound object documentation.

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

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

SoundManager Global Properties

SoundManager includes a few global parameters which configure debug mode, flash movie path and other behaviours.

soundManager.url = '/path/to/soundmanager2.swf';
soundManager.debugMode = true;      // enable debugging output (div#soundmanager-debug, OR console..)
soundManager.useConsole = true;     // use firebug/safari console.log()-type debug console if available
soundManager.consoleOnly = false;   // if console is being used, do not create/write to #soundmanager-debug
soundManager.allowPolling = true;   // allow flash to poll for status update..
soundManager.nullURL = '/null.mp3'; // URL of silent/blank MP3 to use when unloading/canceling a loaded/loading sound

To modify global SoundManager defaults, edit the main soundmanager2.js file (look for above section in code) or assign new values in your own application script before window.onload() fires.

Example per-application override:

soundManager.debugMode = false;          // disable debug mode
soundManager.defaultOptions.volume = 33; // set global default volume

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.

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 load and/or initialise.

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

This handler will be called if there are security restrictions preventing Javascript from talking to Flash, a missing .swf file, lack of browser support, 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.

Requirements + Specifications

Prerequisites (client)

• Flash plugin, version 8 or higher
• Supported Browser

Supported Browsers/Platforms

Javascript-to-flash communication is possible through Flash 8's ExternalInterface feature, which (as I understand) uses a standard browser plugin architecture implemented by each browser manufacturer (see NPAPI.) As a result, the following browsers should be supported:

• IE 5.0+, Win32
• Netscape 8.0+, Windows/Mac
• Mozilla 1.7.5+, Windows/Mac
• Firefox 1.0+, Windows/Mac
• Firefox 1.5+, Linux (Flash 9 beta)
• Safari 1.3+, Mac
• Opera 9.10+, Windows

For reference, see Adobe's ExternalInterface support page which documents supported browsers.

At this time, not all combinations of browser/OS have been tested. Some unlisted configurations may be supported, but have not been explicitly verified to work.

Unsupported Configurations

The following browser/OS combinations have been reported as buggy, or may be unsupported:

• Konqueror (version unknown)

Caveats + Limitations / FAQ

Supported sound format (MP3-only, with caveats)

SM2 uses Flash's native Sound object for loading and managing sound, so it is subject to the same limitations that Flash 8 is. Perhaps a design decision, the Flash 8 sound object only supports MP3 files through the loadSound() ActionScript method. SM2 is not able to load other sound formats, including audio-only SWF files, due to this limitation. Refer to the Flash 8 sound object documentation for details.

MP3 Format Caveats

Additionally, some very low and very high bitrate MP3s, and Variable Bitrate (VBR) MP3s may play either too quickly or too slowly (see "the chipmunk problem"); if you are encountering this issue, try re-encoding at a different bitrate (between 64 kbps and 192 kbps, for example.) Using Constant Bitrate (CBR) encoding may also alleviate this problem.

It has been suggested that sample rates that are neither 22/44 KHz can also contribute to this issue.

Looping + multi-shot (overlaying)

Perhaps due to the way Flash dynamically loads and decodes MP3 data, seamless looping doesn't seem to be fully implemented. Loops have a noticeable gap between the finish and start. This has been an issue since the original version of SoundManager. Rather than have a broken feature, the funcionality has been omitted until a solid workaround is found.

Regarding overlaying, even though a multi-shot option can be specified, it does not work in practice; a single instance of a sound can only have one timeline. The current behaviour is that when multiShot is specified and play() is called on a currently-playing sound, it will restart from the beginning without an overlay.

However, the API does provide some creative ways (onbeforefinish for looping, multiple sound objects for multi-shot layering) of working around these Flash limitations.

It should be noted that sounds can loop seamlessly and be layered when linked and exported to SWF from within the Flash IDE, but SoundManager does not support SWF-based audio.

ID3 Parsing

ID3 data can differ in formatting, version and subsequently be oddly-parsed by Flash. Values may sometimes be repeated across different fields.

ID3 info seems to fail to load for iTunes 7-edited files, perhaps due to the format or inclusion of album artwork (image data)

Performance Notes: Caching + RAM Obeservations

Flash appears to use the browser cache (presumably the OS' native, or closest browser,) so the browser's cache size and other settings may affect Flash's cache behaviour. It is safe to assume a 100 MB MP3 will probably not be cached, for example, but a 16 MB one most likely will be.

MP3s appear to be loaded and stored in RAM while loading over HTTP, so memory use needs to be considered for both large MP3s and streaming radio-type applications.

Timing (JS + Flash, ExternalInterface-related)

Javascript-to-Flash communication is not instantaneous on slower systems, but feels much more near real-time on more modern systems. "Lag" can be noted in some cases from function call to sound execution. It is possible some performance analysis can help to speed up this area for timing-critical applications involving animation etc., but this area has not been thoroughly investigated yet. Brad Neuberg has some notes on speeding up ExternalInterface which may be relevant.

Revision History

• V2.0b.20070415 (current)

  The latest and greatest. (download)

  Changelog:

  • Added destroySound() method
  • Made debug output slightly less-verbose (commented out)
  • Safety tweak for position-related Flash bug when loading new sounds
  • Highly-expanded documentation (SMSound events + properties, examples, caveats, FAQs etc.)
  • Added time-sensitive light/dark theme for documentation

  V2.0b.20070201

  Second beta?

  Changelog:

  • Fixed stopAll() bug (previously broken)
  • Added nullURL parameter
  • Updated documentation

  V2.0b.20070123

  V2.0b.20070118

  V2.0b.20070115

• V2.0b.20070107

  First beta

• V2.0a.20060904

  Prerelease alpha

"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! :)

Demo Credits

Background Tile

Modified from squidfingers.com (free patterns)

Sound Sources

MPC Demo Sounds downloaded from AKAI.com

Theme switch SFX from user pempi, freesoundproject (Creative Commons Sampling Plus 1.0 License)

General

SoundManager was written to meet a desire to have Javascript-driven sound for interactive web-based projects. It is free for use in both personal and commercial projects (see Licensing.) It was originally developed for personal use and has been packaged with the hopes of being useful to others.

Links

• SoundManager 2 Project Page (schillmania.com)
• Flash 8 sound object documentation (livedocs.macromedia.com)

About

Scott Schiller (contact) is a Front-end Engineer (previously "Web Developer") who builds fun creative and technical stuff on the web - or failing that, tries - when he has free time. He likes building cool things which contribute to, yet enjoys mocking, the Web 2.0 meme. (See How Web 2.0-Aware Are You?)

Debug Output

Live debug info from SoundManager 2, active on this page for demo tests.

If you're seeing errors here or in demos, this info can help in troubleshooting.