SoundManager 2 Template

# SoundManager 2 Template Example

This page covers the basics of adding SoundManager 2 to your project.

## How it works

The minimal code needed to get SoundManager 2 going is below, with configurable parts highlighted. You can copy/paste it to get started. This page is also running the template code; If available, look at your JavaScript console for debug output from SM2.

## Dependencies

You'll need to copy the files inside the script/ and swf/ subdirectories included with the SoundManager 2 package into your project.

- soundmanager2/
  - script/ - API core, soundmanager2.js
  - swf/ - API core, SoundManager 2 .SWF files

At the bare minimum, you will need soundmanager2.js, soundmanager2.swf and soundmanager2_debug.swf for the default flash 8-based configuration. (Optionally, SM2 can use a Flash 9-based audio API which has MP4 support, data visualization and a few other features.)

## Template Code: Basic Version

This is a compact version of the template you can copy/paste to get started. For new users, see the commented version.

    <script src="/path/to/soundmanager2.js"></script>
    <script>
    soundManager.setup({
      url: '/path/to/swf-files/',
      // optional: use 100% HTML5 mode where available
      // preferFlash: false,
      onready: function() {
        var mySound = soundManager.createSound({
          id: 'aSound',
          url: '/path/to/an.mp3'
        });
        mySound.play();
      },
      ontimeout: function() {
        // Hrmm, SM2 could not start. Missing SWF? Flash blocked? Show an error, etc.?
      }
    });
    </script>

## Template Code: Commented Version

    <!-- include SM2 library (see builds for optimized versions) -->
    <script type="text/javascript" src="/path/to/soundmanager2.js"></script>

    <!-- configure SM2 for your use -->
    <script type="text/javascript">

    soundManager.setup({

      // location: path to SWF files, as needed (SWF file name is appended later.)

      url: '/path/to/swf-files/',

      // optional: version of SM2 flash audio API to use (8 or 9; default is 8 if omitted, OK for most use cases.)
      // flashVersion: 9,

      // optional: use 100% HTML5 mode where available
      // preferFlash: false,

      // use soundmanager2-nodebug-jsmin.js, or disable debug mode (enabled by default) after development/testing
      // debugMode: false,

      // good to go: the onready() callback

      onready: function() {

        // SM2 has started - now you can create and play sounds!

        var mySound = soundManager.createSound({
          id: 'aSound',
          url: '/path/to/an.mp3'
          // onload: function() { console.log('sound loaded!', this); }
          // other options here..
        });

        mySound.play();

      },

      // optional: ontimeout() callback for handling start-up failure

      ontimeout: function() {

        // Hrmm, SM2 could not start. Missing SWF? Flash blocked? Show an error, etc.?
        // See the flashblock demo when you want to start getting fancy.

      }

    });

    </script>

## HTML5 Support Notes

By default, SM2 presently prefers Flash for MP3 + MP4 playback even on clients that support it natively via HTML5 due to some inconsistencies between browsers. If you'd like to go for 100% HTML5 mode, include `preferFlash: false` in your `soundManager.setup()` call.

Read up on HTML5 audio support, if you're feeling adventurous. iPad/iPhone and devices without flash installed will always use 100% HTML5 mode.

## Handling flash blockers

It's good to let users see the flash component of SM2, so those with flash blockers can unblock it and allow SM2 to start. For more info, see the Flashblock example.

## Disabling debug output

SoundManager 2 will write debug output via `console.log()` if available, by default. To disable it, simply specify `debugMode: false`.

You can also write HTML-based debug output to the DOM via `consoleOnly: false` and/or `useConsole: false`.

To see related configuration code, refer to the source of this page which basically does all of the above "for real."

## Troubleshooting ("failed to start": Viewing offline, missing SWF, flash blockers etc.)

If SM2 is failing to start and throwing errors due to flash security, timeouts or other issues, check out the troubleshooting tool for tips.

## No-debug, compressed version of soundmanager2.js

Once development is finished, you can also use the "minified" (down to ~8% of original size with gzip!) version of SM2, which has debug output and comments removed for you: soundmanager2-nodebug-jsmin.js. Serve with gzip compression wherever possible for best bandwidth savings.