Latest changes: Strict Mode. Android 2.3 HTML5 fixes, cleaner debug output, improved default flashblock handling, compatibility with Firefox WMF-based HTML5 MP3 support, and more. See revision history for details.
+Latest changes: Fix for playlist/event chaining when using flashVersion = 8 with Flash Player 11.6.602.171. HTML5 iOS load() fix. Added Opus to audio formats. See revision history for details.
Download SoundManager 2.97a.20130101 or see on GitHub
+Download SoundManager 2.97a.20130324 or see on GitHub
Performance tip: SM2's code size varies from over 128 KB (commented, debug-enabled) down to 11 KB (optimized) over HTTP; check the pre-optimized builds for details.
@@ -171,9 +173,112 @@flashVersion = 8 with Flash Player 11.6.602.171. HTML5 iOS load() fix. Added Opus to audio formats.Bug fixes
+ +
+ Flash Player 11.6.602.171, released by Adobe on 02/26/2013, introduced an issue with SM2's default Flash 8 (flashVersion: 8) API-based JS/Flash interaction, where SM2 methods called from callbacks such as onfinish() would not work. This primarily broke methods used for playing sounds in sequence, serially loading a series of sounds and so on. (See discussion for more.)
+
+ Note that this does not affect cases where soundManager.setup({ flashVersion: 9}) is being used; however, SM2 does use flashVersion: 8 by default.
+
+ Specifically, Flash-initiated events (such as a sound finishing) make Flash -> JS calls to the SM2 API, which subsequently call user-specified event handlers. If the user-specified SM2 onfinish() handler immediately calls a SM2 method like play() that makes a JS -> Flash call, this call either silently fails or is blocked. Other JS + Flash libraries that use similar callback patterns may also be affected, if their SWF is built targeting the Flash 8 API.
+
+ Suspecting a timing or recursion/stack issue, it was found that introducing a setTimeout(callback, 0) to user-specified SM2 callbacks like onfinish() restored sequential/playlist functionality.
+
+ Flash Player 11.6.602.180, relased by Adobe on 3/12/2013, exhibits the same behaviour. To avoid additional hacks, SM2 applies this to all Flash 8-based API callbacks regardless of what version of Flash Player is installed. No regressions are anticipated as a result of this change. +
+ +
+ Alternately, this issue can be avoided by using soundManager.setup({ flashVersion: 9 }) as the Flash 9-based API does not appear to have this problem.
+
+ HTML5: Fix for iOS load() case when using an auto-load and looping pattern (related discussion).
+
API Updates
+ +
+ HTML5: Added check for Opus (OGG-based audio codec, audio/opus).
+
Miscellaneous
+ ++ Added documentation for Serving To Clients, and Mobile Device Limitations. +
++ Minor SM2 homepage + documentation CSS tweaks (design) +
++ This SM2 release is tagged "Mahalo Edition" to say thank-you, and because some SM2 work was done while on vacation in Hawai'i. Also, some new demo sound recordings from the beach on Kaua'i were added. +
+ + +reset() method, reboot() tweaks.reset() method, reboot() tweaks (Download archived version)<script src="soundmanager2.js"></script>
<script src="soundmanager2-jsmin.js"></script>
<script src="soundmanager2-nodebug-jsmin.js"></script>
This property handles "mixed-mode" HTML5 + flash cases, and may prevent 100% HTML5 mode when enabled depending on the configuration of soundManager.audioFormats. In the event HTML5 supports the default "required" formats (presently MP3), and preferFlash is true (and flash is installed), flash will be used for MP3/MP4 content while allowing HTML5 to play OGG, WAV and other supported formats.
Important note: Because HTML5 audio has some critical bugs across various browsers and operating systems, preferFlash is true by default to help ensure MP3/MP4 play consistently. If set to false or flash is not available, "HTML5-only" mode will kick in and will apply to all formats. If you prefer 100% HTML5 mode even when Flash is present, set this property to false.
Important note: Because HTML5 audio has some bugs across various browsers and operating systems, preferFlash is true by default to help ensure MP3/MP4 play consistently. If set to false or flash is not available, "HTML5-only" mode will kick in and will apply to all formats.
To encourage 100% HTML5 mode, call soundMangager.setup({ preferFlash: false }) and then Flash will not be used for MP3/MP4 playback, provided that HTML5 supports them.
soundManager.setupOptions.url specifies the "online", generally HTTP-based path which SM2 will load .SWF movies from. The "local" (current) directory will be used by default. The appropriate .SWF required (depending on the desired Flash version) will be appended to the URL.
soundManager.url, applied via soundManager.setup(), specifies the "online", generally HTTP-based path which SM2 will load .SWF movies from. The "local" (current) path of ./ will be used by default. The appropriate .SWF required (depending on the desired Flash version) will be appended to the URL.
Example: soundManager.setup({ url: '/path/to/swf-directory/' }); (Note trailing slash)
For a simple demo of this in action, see the basic template.
For cases where SM2 is being used "offline" in non-HTTP cases (eg., development environments), see altURL.
Beta notice: HTML5 support is in active development. Experimental API bits will be labeled as such, but should remain largely forward-compatible. See Revision History for the latest updates on HTML5 playback support.
+HTML5 support is in active development. See Revision History for the latest updates on HTML5 playback support.
useHTML5Audio determines whether HTML5 Audio() support is used (as available) to play sound, with flash as the fallback for playing MP3 and MP4 (AAC) formats. Browser support for HTML5 Audio varies, and format support (eg. MP3, MP4/AAC, OGG, WAV) can vary by browser/platform.
The SM2 API is effectively transparent, consistent whether using flash or HTML5 Audio() for sound playback behind the scenes. The HTML5 Audio API is roughly equivalent to the flash 8 feature set, minus ID3 tag support and a few other items. (Flash 9 features like waveform data etc. are not available in HTML5 mode.)
By default, "100% HTML5 mode" applies to Apple iPad 3.2+, iPhone / iOS 4.0+ devices and others without flash. In other cases, HTML5 support is tested and if MP3/MP4 aren't natively supported, flash will be used as a backup method of playing these "required" formats. (It is assumed MP3 playback is required by default, but this is user-configurable via soundManager.audioFormats.) HTML5 may also enable support for additional formats such as OGG and WAV.
In the case when HTML5 + Flash are present, Flash will presently get preference for MP3/MP4 because of soundManager.preferFlash = true as HTML5 audio is still buggy between browsers and platforms; where desired, you can set preferFlash = false and in some cases enjoy 100% HTML5 mode (eg., under Safari, IE 9 and Chrome.) For some browsers, Flash will be needed if support for formats like MP3 (not supported via HTML5 in Firefox) are "required."
By default, "100% HTML5 mode" applies to Apple iPad 3.2+ (iPad version 1.0), iPhone / iOS 4.0+ devices and others without flash. In other cases, HTML5 support is tested and if MP3/MP4 aren't natively supported, flash will be used as a backup method of playing these "required" formats. (It is assumed MP3 playback is required by default, but this is user-configurable via soundManager.audioFormats.) HTML5 may also enable support for additional formats such as OGG and WAV.
In the case when HTML5 + Flash are present, Flash will presently get preference for MP3/MP4 because of SM2's default preferFlash: true setup option, as HTML5 audio is still buggy between browsers and platforms; where desired, you can use soundManager.setup({ preferFlash: false }) and in some cases enjoy 100% HTML5 mode (eg., under Safari, IE 9 and Chrome.) For some browsers, Flash will be needed if support for formats like MP3 (not supported via HTML5 in Firefox) are "required."
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, flashPollingInterval will use a lower timer value, making polling calls run as quickly as reasonably possible and increasing the frequency of calls to whileplaying(), whileloading() and other time-related events.
Use these options with caution, as overly-aggressive intervals may hinder performance if event callbacks become too frequent.
A few notes on HTTP response headers, configuration and so forth.
+ +HTTP response headers from your server are important. Below is a brief list of recommended practices for serving audio content to clients using HTML5, and/or Flash.
+ +Content-Length HTTP response headers (can affect duration and playback events if missing.)audio/mpeg for MP3 content.Content-Length HTTP response headers. When missing, duration may be unknown and certain events like whileloading() / whileplaying() may not fire.In summary...
+ +Always serve a proper Content-Length HTTP response header. For HTML5, review that HTTP partials / range requests are enabled and that you are serving the correct MIME type in your response as well.
Never apply gzip or mod_deflate compression to binary assets. It causes playback problems, costs CPU and in some cases, may even increase the transfer size.
Known restrictions, quirks and annoyances relating to HTML5 + mobile Webkit (iOS / Android) software.
+Mobile devices tend to be somewhat limited in terms of battery life, network connection and other resources. Furthermore, they are unlike larger (laptop/desktop) devices in that audio is often not a "shareable" resource, and only one application may be using the sound hardware at any given time. Thus, mobile devices must be treated slightly differently in terms of playing audio via JavaScript.
+play() calls are blocked by the OS unless in direct response to a user event like touch or click. ("Auto-play" attempts will be blocked, and the sound may fire a suspend event in this case.) For the curious, setTimeout() calls will also result in playback being blocked.load() and load-related methods may also have some limitations, similar to play().onfinish event handler. Otherwise, blocking occurs.The Webkit Audio API (possibly a future standard as the Web Audio API) allows for low-level access, manipulation and control of audio from JavaScript. This API is mostly separate from the HTML5 audio API, but will ultimately allow for better fine-grained control and mixing of sound.
+Once playback is allowed, the Webkit Audio API should be able to get around many of the current HTML5 audio limitations present on iOS including multiple sound playback, volume and pan control, and dynamic filtering / processing effects. However, the API is not a standard and is not consistently supported in Webkit, let alone other browsers.
+At time of writing (March 2013), SM2 does not use the Webkit Audio API. It may be experimentally or more formally added at some point in the future, when the API is more universally-supported.
+Console-style messaging, useful for troubleshooting start-up and runtime issues.
@@ -218,9 +288,9 @@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.
With debug mode enabled via soundManager.setup({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.setup({consoleOnly: true}) can be applied 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.setup({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:
@@ -236,11 +306,11 @@