SoundManager 2: Getting Started

<script src="soundmanager2.js"></script>

<script src="soundmanager2-nodebug.js"></script>

<script src="soundmanager2-jsmin.js"></script>

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

<script>
soundManager.url = '/path/to/swf-files/';
soundManager.flashVersion = 9; // optional: shiny features (default = 8)
soundManager.useFlashBlock = false; // optionally, enable when you're ready to dive in
/*
 * read up on HTML5 audio support, if you're feeling adventurous.
 * iPad/iPhone and devices without flash installed will always attempt to use it.
*/
soundManager.onready(function() {
  // Ready to use; soundManager.createSound() etc. can now be called.
});
</script>

Startup / Initialization

In brief, here is now SM2 starts up:

• soundmanager2.js loads
• new SoundManager() constructor call, event listeners attached for dom ready/init
• document.createElement('embed') (or 'object' for IE), append Flash .SWF to document
• SWF loads, Flash makes call to JS function: "Hi, JS!"
• JS -> Flash test (JS calls Flash function): "Hello, Flash!"
• -- startup is complete, soundManager.onready() fires --

A single Javascript include will link in all of the required code for the library, which will automatically begin loading either at 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 event handlers/listeners registered via soundManager.onready(). There are also "old-skool" onload()/onerror() event handlers which you can define just as you would with window.onload().

If you want to lazy-load or defer SM2, see Lazy-loading and SM2_DEFER.

SoundManager onready() / ontimeout() and onload() / onerror() Event Handlers

onready() is a flexible method that can be used to queue numerous listeners for SM2's successful start-up. Simply pass a callback function, which will be called when SM2 has successfully started:

soundManager.onready(function() {
    // SM2 is ready to go!
    makeSomeNoise(); // soundManager.createSound(), etc.
});

ontimeout() is used to add listeners for SM2 init failures, which can happen due to missing or blocked Flash support. They are not necessarily fatal as in the flash block case, where onready() calls can follow ontimeout() if the user unblocks flash after a failed init attempt.

soundManager.ontimeout(function() {
    // SM2 could not start. Flash blocked, missing or security error? Complain, etc.?
});

SoundManager onload() + onerror()

A more traditional, less-flexible style of event handling is to assign single onload() / onerror() handlers. You should use onready() as it can be assigned at any time once soundManager has been defined, and is more robust.

soundManager.onload = function() {
  // SM2 is ready to go!
  makeSomeNoise(); // soundManager.createSound(), etc.
}

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

Lazy-loading SM2 (deferred start-up): SM2_DEFER

Let's say you wanted to load and start SM2 after your page has loaded, using Javascript to insert a script node etc., or otherwise only start SM2 conditionally. You can edit soundmanager2.js and take out the SoundManager() constructor call at the bottom, or set the global variable SM2_DEFER = true which will have the same effect.

Example:

function lazy_load_sm2() {
  window.SM2_DEFER = true;
  // -- load soundmanager2.js via <script>, createElement('script') or XHR etc. --
  // imaginary load_script() function ..
  load_script('/path/to/soundmanager2.js', function() {
    // once soundmanager2.js has loaded and has parsed, construct + init.
    window.soundManager = new SoundManager(); // Flash expects window.soundManager.
    soundManager.beginDelayedInit(); // start SM2 init.
  });
}

For a live demo, check out the deferred loading example.