# SoundManager 2: Technical Notes

## Requirements + Specifications

What SM2 needs, and how it works.

### Requirements + Specifications

#### Prerequisites (client)

- Flash plugin, version 8 or higher and/or HTML5 `Audio()` support
- Supported Browser

#### Supported Browsers/Platforms

JavaScript-to-flash communication is possible through Flash 8's ExternalInterface feature, which 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+, Windows
- 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 / All Windows versions (and iOS 4.0 devices, or iPad 3.2+)
- Google Chrome (All versions/OSes)
- Opera 9.10 (slightly buggy, 9.5+ ideal), Windows/Mac

For reference, see Adobe's Flash 8 documentation, under the "ExternalInterface support" page which details supported browsers.

Of course, not all possible combinations of browser/OS have been tested. Some unlisted configurations may be supported, but have not been explicitly verified to work.

### Caveats + Limitations / FAQ

#### Supported sound formats (MP3 via Flash 8 and MP4/M4A/AAC via Flash 9 "MovieStar", 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 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. 44 KHz is the standard CD-spec sample rate, and is recommended for "hi-fi" recordings.

#### Looping

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.

#### Flash 8 limitations with multiShot (overlaying/"chorus") effects

Regarding "layering" sounds (calling `play()` on a sound multiple times): Even though a multi-shot option can be specified, it does not work with Flash 8; 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.

#### Flash 9 multiShot capabilities

The Flash 9-based version of SoundManager2 can successfully layer sounds via "multiShot", truly playing a single sound multiple times on top of itself. However the API will only call certain timing-related methods such as `whileplaying()` for the first `play()` "instance" of the sound, to avoid confusion. By contrast, simpler methods such as `onfinish()` will be called multiple times, one for each instance of `play()`.

#### 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/Latency (JS + Flash, ExternalInterface-related)

JavaScript-to-Flash communication is not instantaneous on slower systems, but can be much better on more modern systems. Latency (timing lag/delays) 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.

Flash-to-OS/hardware latency (where flash reports progress, but no sound is heard for a number of milliseconds) may also be an unfortunate reality of Flash-based audio, varying between platform and OS version etc.

Additionally, MP3 files may contain audible gaps at the beginning or end by default when encoded, even if the source (eg. WAVE) file did not. Using optional "nogap" encoding options with programs such as LAME may help to remedy this.

Finally, the `useHighPerformance` option may help with JS/flash lag. Using this option causes the flash movie to be placed with position:fixed on-screen at all times (though in a small, hidden box) and has been shown to notably improve performance on Mac OS X. As well, `useFastPolling` will use a lower timer interval within Flash, making polling calls run as quickly as reasonably possible and increasing the frequency of calls to `whileplaying()`, `whileloading()` and other time-related events.

## Debug + Console Output

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

### Live Debug Output

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`".

`soundManager.consoleOnly` can be set to true to disable HTML output (using `console.log()`-only methods) as well.

Additionally, debugging within the Flash portion of SM2 is also available and set using `soundManager.debugFlash = true`. Debug messages are written to the flash movie itself.

For info on SoundManager 2 loading/initialization failures and how to fix them, see troubleshooting.

Below is a live example of debug output from SM2:

And, Flash debug output:

## Discussion / Support

Get Satisfaction support network