SoundManager 2: Getting Started

How SoundManager Works

It starts out easy, but you can go down the rabbit hole if you want.

SoundManager 2 makes it easier to play MP3 audio cross-browser using Javascript.

Problem: Browsers lack good, consistent native audio/video support. (HTML 5's <audio> and <video> are on the way, but not universal yet.)

Solution: Javascript API via Flash + ExternalInterface, works almost everywhere

SoundManager 2 wraps and extends the Flash Sound API, and exposes it to Javascript. (The flash portion is hidden, transparent to both developers and end users.)

Including SoundManager

Within <head>:

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

Alternate "minified" version (no debug output nor comments, 60% reduction in file size, as light as 6 KB with gzip):

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

Basic SoundManager Template

For a live example of a page including SoundManager 2, check the bare-bones template.

Startup / Initialization

A single Javascript include will link in all of the required code for the library, which will automatically begin loading either at document.onDOMContentLoaded() if supported, or alternately, after window.onload() (eg., IE 6 and others.) The default behaviour is to start "as soon as possible", but the library can be configured to wait for window.onload() in all cases as well. Loading and initialisation are separate events.

Once initialised, SM2 will call either soundManager.onload() or soundManager.onerror(), event handlers which you can define just as with window.onload().

SoundManager onload/onerror Event Handlers

soundManager.onload = function() {
  // SM2 is ready to go!
  var mySound = soundManager.createSound({
    id: 'aSound',
    url: '/path/to/an.mp3',
    volume: 50
  });
  mySound.play();
}

soundManager.onerror = function() {
  // SM2 could not start, no sound support, something broke etc. Handle gracefully.
  disableSoundInMyApp(); // for example
}

Sound Options Object Format

Object Literal, JSON-style form passed to createSound() and play()

Object Literal Format

Sounds can be created with instance-specific parameters in an object literal (JSON) format, where omitted parameters inherit default values as defined in soundManager.

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

"Use Responsibly"

Only you can prevent audio pollution?

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

Troubleshooting

Console-style messaging, useful for troubleshooting start-up and runtime issues.

Live Debug Output

SoundManager 2 relies on Javascript and Flash communicating via ExternalInterface, and this is subject to a number of timing, loading and browser security conditions. Because of this complexity, debug information is essential for troubleshooting start-up, loading, initialization and error conditions between Flash and Javascript.

With debug mode enabled via soundManager.debugMode = true, SM2 can write helpful troubleshooting information to javascript console.log()-style interfaces. Additionally, output can be written to an optional DIV element with the ID of "soundmanager-debug".

If loading from the local filesystem (offline eg. file://, not over HTTP), Flash security is likely preventing SM2 from talking to Javascript. You will need to add this project's directory to the trusted locations in the Flash global security settings panel, or simply view this page over HTTP.

Below is a live example of debug output.

For more examples of live debug output, see the Basic Template, API demo and other demos in the top navigation.