<metaname="description"content="SoundManager 2 tutorial, example code, how to get started guide including and configuring SoundManager 2 for playing MP3 audio via Javascript."/>
<pstyle="margin-top:1px"><strong><strong>SoundManager 2 makes it easier to play MP3 audio cross browser / platform, using Javascript.</strong></strong></p>
<p><strong>Problem:</strong> Browsers lack good, consistent native audio support. (HTML 5's <code>Audio()</code> is the future, but does not have majority support yet.)</p>
<p><strong>Solution:</strong> Javascript API via Flash + ExternalInterface, works almost everywhere. If HTML5 audio support is enabled, flash fallback used for browsers that don't support "non-free" MP3 + MP4 formats.</p>
<p>SoundManager 2 wraps and extends both the Flash and HTML Audio Sound APIs, providing a single, unified sound API to Javascript; the API is the same, whether HTML or Flash is ultimately used to play sound. (The flash portion is hidden, transparent to both developers and end users.)</p>
<p>The soundmanager2.js core can get down to 10 KB over the wire, depending on what version you use. A few versions of the SM2 script are available, balancing code size between commented, debug-enabled and production-optimized builds.</p>
<p>Regardless of which build you use, take advantage of <ahref="http://developer.yahoo.com/performance/rules.html#gzip"title="Best Practices for Speeding Up Your Web Site (Yahoo Developer Network)">gzip compression</a> on your server for big savings. As shown below, SoundManager 2 compresses quite well with gzip; the full debug-enabled version served <i>with</i> gzip is smaller than even the minified, no-debug version served without it.</p>
<thclass="nw">+ <ahref="http://www.sergeychernyshev.com/blog/speed-up-your-site-drop-in-htaccess-file/"title="Friends don't let friends run websites without gzip!">gzip</a></th>
</tr>
<tr>
<td>
<p>Original, formatted debug-enabled version with comments. Passes <ahref="http://jslint.com"title="jslint, the JavaScript code quality tool.">jslint</a>.</p>
<p>You then need to tell SM2 where to find the flash .SWF it will need (if no HTML5 support), and optionally what version of Flash (~3 KB for flash 8, ~10 KB for flash 9) depending on what API features you want, as well as other features:</p>
soundManager.flashVersion = 9; <span><span>// optional: shiny features (default = 8)</span></span>
soundManager.useFlashBlock = false; <span><span>// optionally, enable when you're ready to <ahref="../../demo/flashblock/"title="SoundManager 2 flash block handling demo">dive in</a></span></span>
<span><span>// enable <ahref="../#soundmanager-usehtml5audio">HTML5 audio support</a>, if you're feeling adventurous. iPad/iPhone will always get this.</span></span>
<span><span>// Ready to use; soundManager.createSound() etc. can now be called.</span></span>
});
</script></pre>
<p>If you plan to eventually use the flash block handling feature (disabled in this example), you'll want to look at the <ahref="../../demo/flashblock/"title="SoundManager 2 flash block handling demo">flash block demo</a> and include the relevant CSS it uses.</p>
<p>For a live example of a page including SoundManager 2, check the <ahref="../../demo/template/"title="SoundManager 2 template example"onclick="checkDomain(this)">bare-bones template</a>.</p>
<p>The core audio API bits require <code>script/soundmanager2.js</code> and the SWF files <code>swf/soundmanager2.swf</code> and <code>swf/soundmanager2_flash9.swf</code>, as well as the <code>_debug</code> versions of the SWFs. The flash 9 SWF enables some extra API features, and is only used if you set <code>soundManager.flashVersion = 9</code> (the default is 8.)</p>
<ulclass="file-structure">
<li>
soundmanager2/
<ul>
<li>
demo/ <span>- Examples, MP3 player UIs etc.</span>
</li>
<li>
doc/ <span>- API method documentation, notes, troubleshooting</span>
</li>
<liclass="core">
script/ <span>- API core, soundmanager2.js</span>
</li>
<li>
src/ <span>- AS2/AS3 Flash source used to build SWFs (for flash development)</span>
</li>
<liclass="core">
swf/ <span>- API core, SoundManager 2 .SWF files</span>
</li>
<li>
troubleshoot/ <span>- Tool for finding/fixing startup issues</span>
<p>SoundManager 2 is the result of Javascript talking to a hidden Flash movie. The Flash layer is not something you have to work with directly, but it is the component which makes audio control possible behind the scenes.</p>
<p>Flash can expose methods to Javascript via ExternalInterface, allowing bi-directional calls to be made and thus providing additional functionality to Javascript.</p>
<p>For the real gory details on the behind-the-scenes action of JS + Flash, see <ahref="http://www.schillmania.com/content/entries/2010/how-soundmanager2-works/"title="How SoundManager 2 works (JS + ExternalInterface + Flash)">How SoundManager 2 Works</a> on schillmania.com.</p>
<pclass="in">A single Javascript include will link in all of the required code for the library, which will automatically begin loading either at <code>onDOMContentLoaded()</code> if supported, or alternately, after <code>window.onload()</code> (eg., IE 6 and others.) The default behaviour is to start "as soon as possible", but the library can be configured to wait for <code>window.onload()</code> in all cases as well. Loading and initialisation are separate events.</p>
<pclass="in">Once initialised, SM2 will call event handlers/listeners registered via <code>soundManager.onready()</code>. There are also "old-skool" onload()/onerror() event handlers which you can define just as you would with <code>window.onload()</code>.</p>
<p><code>onready()</code> 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:</p>
<p><code>ontimeout()</code> 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 <code>onready()</code> calls can follow <code>ontimeout()</code> if the user unblocks flash after a failed init attempt.</p>
<span><span>// SM2 could not start. Flash blocked, missing or security error? Complain, etc.?</span></span>
});</code></pre>
<h4>SoundManager onload() + onerror()</h4>
<p>A more traditional, less-flexible style of event handling is to assign single onload() / onerror() handlers. You should use <code>onready()</code> as it can be assigned at any time once soundManager has been defined, and is more robust.</p>
<p>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, <i>or</i> set the global variable SM2_DEFER = true which will have the same effect.</p>
<p>For a live demo, check out the <ahref="../../demo/template/deferred-example.html"title="SoundManager 2 deferred loading example">deferred loading example</a>.</p>
<p>Sounds can be created with instance-specific parameters in an object literal (JSON-style) format, where omitted parameters inherit default values as defined in soundManager.</p>
<p>This object can also be passed as an optional argument to the <codeclass="in">play</code> method, overriding options set at creation time.</p>
<p>For a full list of available options, see <ahref="../#sound-properties"title="SoundManager 2 API info: Sound Properties"onclick="resetFilter()">Sound Properties Object</a></p>
<p>Not every button, link, element or paragraph on the web needs to zoom, move, change colour <em>and</em> be noisy, repetitive and annoying all at the same time. Use your own discretion!</p>
<p>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. :)</p>
<p>The Flash 8 plugin is a minimal requirement for SoundManager 2, but the exact requirement varies based on soundManager.flashVersion. You are currently using <bid="d-flashversion">[unknown]</b>.</p>
<p>SoundManager 2 must load a flash movie before initialisation can proceed. If you have errors here, check that soundManager.url is correctly defined and that the URL being loaded is correct.</p>
<p>If the Flash movie URL is OK, Flash security or flash blockers are the likely cause. Check the section below.</p>
<p>Once the flash component of SM2 has loaded, it tries to make a call to Javascript-land. This is a common point of failure, for security reasons.</p>
<ul>
<li>
<p><b>Have a flash blocker?</b> Check that the <ahref="#flashdebug">SM2 flash movie</a> (below) is loading and is not being blocked.</p>
</li>
<li>
First time opening SM2 after downloading it? Is your browser URL at file:// or c:/path/ or otherwise not using HTTP? Flash security "whitelisting" is required to allow Flash + JS to work when offline, placing it in the "LocalTrusted" Flash security sandbox rather than "localWithFile".
<h4>Offline viewing: Adding a "trusted location" to the Flash Security Settings Panel</h4>
<p>The Flash Player Global Security Settings Panel is a web-based control panel which allows you to configure Flash security. You will need to add the path of the SoundManager 2 project in order for it to work "offline" (ie., when viewing via file:// or c:/)</p>
<pid="ss"><ahref="#screenshots"onclick="document.getElementById('ss-box').style.display = 'block';document.getElementById('ss').style.display='none';return false">Show me how</a>: Adding a "trusted location"</p>
<divid="ss-box"style="display:none">
<h4>Illustrated guide: Adding a "trusted location" in Flash</h4>
<p>Below: Adding a location, and selecting "Browse for folder" (or directory), to whitelist the SoundManager 2 project directory for offline viewing.</p>
<p><imgsrc="../../troubleshoot/fpgss-add-location.png"alt="Adding a location: Browse for the file or directory to whitelist"style="width:100%;_width:auto;min-width:72px;max-width:396px"/></p>
<p><imgsrc="../../troubleshoot/fpgss-added-location.png"alt="Whitelisted location has now been added, JS + Flash will work under this path"style="width:100%;_width:auto;min-width:72px;max-width:396px"/></p>
</div>
<p><ahref="http://www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager04.html"target="_blank"class="feature">Launch the Flash Security Settings Panel</a></p>
<listyle="margin-top:0.5em">Flash blockers (FlashBlock, "click to flash" etc.) preventing flash load and start-up - need whitelisting/"allow this domain" to work smoothly. If you suspect blocking is the issue, try the <ahref="../../demo/flashblock/">SoundManager 2 Flashblock demo</a>.</li>
<listyle="margin-top:0.5em">Online viewing (HTTP/S): Same-domain security rules apply to HTML + Flash content by default (crossdomain.xml/allowDomain() in .AS source required to override.)</li>
</ul>
<p>See <ahref="#flashdebug"title="SoundManager 2 flash debug output">Flash debug output</a> for more security error details.</p>
<p>HTML page on domain A loading .SWF from domain B: Flash security prevents JS + Flash when a cross-domain XML permission file is not available on domain B, and/or flash movie was not compiled with allowDomain('domainA') or allowDomain('*') - note that the SWF distributed with SM2 does not use this by default; try using the cross-domain version of the SWF, or compile your own which whitelists your own domain(s).</p>
<h4>Flash Blockers</h4>
<p>Browser extensions/add-ons like "FlashBlock" and "click to flash" can prevent the .SWF from loading, and this will mean SM2 will time-out and fail waiting for a response from Flash. For development, it's best to whitelist the domain(s) or the .SWF for SM2 to allow it to work.</p>
<p>Have a flash blocker installed? Want to test it? Try the <ahref="../../demo/flashblock">SoundManager 2 Flashblock demo</a>.</p>
<p>At this point, Javascript attempts to respond to Flash's initial outgoing Flash -> JS call, completing the test for JS/flash communication. If SM2 does not receive a response from flash, it will eventually fail.</p>
<p>Offline viewing conditions and cross-domain security rules will prevent Flash <-> JS communication. See the details of Flash -> JS for information.</p>
<p>Here, a simple createSound() call is made to test SM2's actual operation. A sound should load and play provided SM2 was able to start successfully.</p>
<p>Flash detection code from <ahref="http://www.featureblend.com/javascript-flash-detection-library.html"title="Javascript flash detection library">Flash Detect</a> (featureblend.com)</p>
<h3id="flashdebug">Flash Movie Debug Output</h3>
<p>When <code>soundManager.debugFlash = true</code>, Flash will write debug info as text to the flash movie. This can be helpful for troubleshooting Flash/JS issues when timeouts or security errors are involved which prevent Flash from talking to Javascript, potentially hiding useful debug information. A CSS class of <code>flash_debug</code> will also be appended to the Flash <code>#sm2-container</code> DIV element when enabled, if you wish to style it differently.</p>
<p>You can also specify ?debug=1 in the URL to the SWF, and it will write debug output. Try <ahref="../../swf/soundmanager2_debug.swf?debug=1"title="Test debug output"class="norewrite">soundmanager2_debug.swf?debug=1</a>, or <ahref="../../swf/soundmanager2_flash9_debug.swf?debug=1"title="Test debug output, Flash 9"class="norewrite">soundmanager2_flash9_debug.swf?debug=1</a>.
<divid="sm2-container">
<!-- flash movie with debug output goes here -->
</div>
<h3>Live Debug Output</h3>
<p>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.</p>
<pclass="in">With debug mode enabled via <code>soundManager.debugMode = true</code>, SM2 can write helpful troubleshooting information to javascript <code>console.log()</code>-style interfaces. Additionally, output can be written to an optional DIV element with the ID of "<code>soundmanager-debug</code>".</p>
<p>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 <ahref="http://www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager04.html">Flash global security settings panel</a>, or simply view this page over HTTP.</p>
<p>Below is a live example of debug output.</p>
<divid="live-debug"class="block">
<divid="soundmanager-debug"class="code">
<!-- live debug goes here -->
</div>
</div>
<p>For more examples of live debug output, see the <ahref="../../demo/template/"title="Basic SoundManager 2 template">Basic Template</a>, <ahref="../../demo/api/"title="API demo">API demo</a> and other demos in the top navigation.</p>
<h3>Standalone version of troubleshooting tool</h3>
<pclass="in">For debugging your development/production environment with this widget, see the <ahref="../../troubleshoot/"title="SoundManager 2: Standalone debug widget">troubleshooting</a> subdirectory of the SoundManager 2 package.</p>
<h2><ahref="http://getsatisfaction.com/schillmania/products/schillmania_soundmanager_2/"title="User discussion, FAQs and support for SoundManager 2"rel="nofollow">Discussion / Support</a><spanclass="l"></span><spanclass="r"></span></h2>
<divid="gsfn_content"></div>
<divclass="powered_by"><ahref="http://getsatisfaction.com/">Get Satisfaction support network</a></div>
