<h1><ahref="http://www.schillmania.com/projects/soundmanager2/"style="color:#000;text-decoration:none">SoundManager 2</a> / API Demo and Code Examples</h1>
<pclass="note">You can run the API demos with <ahref="#sm2-usehtml5audio=1"onclick="window.location.replace(this.href);window.location.reload()">HTML5</a> enabled, <ahref="#flash8"onclick="window.location.replace(this.href);window.location.reload()">Flash 8</a> (API default), <ahref="#flash9"onclick="window.location.replace(this.href);window.location.reload()">Flash 9</a> (normal) or <ahref="#flash9-highperformance"onclick="window.location.replace(this.href);window.location.reload()">Flash 9 + highPerformance + fastPolling</a> modes (higher JS callback frequency).</p>
<p>Wondering where to start? This page has inline executable code examples using the SoundManager 2 API.</p>
<p>If you're wondering <em>"How to include SM2 in my page?"</em>, the <ahref="../template/"title="SoundManager 2 bare-bones template"onclick="if (!document.domain) this.href=this.href+'index.html'">basic template</a> will get you started.</p>
<span>// uh-oh, SM2 failed to start - error, unsupported etc.</span>
</span>});
</code></pre>
<p>SoundManager first processes the <code>onready</code> or <code>ontimeout</code> queue in the order items were added, and then fires <code>soundManager.onload()</code> or <code>onerror()</code>. If you call <code>onready()</code> after SM2 has loaded, your callback will be fired immediately.</p>
<pclass="compact">Keep in mind SoundManager's core methods (createSound, etc.) will not be available until soundManager.onload() fires. The initialization time for SM2 can vary across browsers/platforms, and should effectively be assumed to be "asynchronous." Because of this, it is recommended you write your code to handle soundManager.onload() being called either before or after window.onload().</p>
<pclass="compact">If you wish to have SM2 always wait for window.onload() before calling soundManager.onload()/onerror(), you can apply the following:</p>
<pre>soundManager.waitForWindowLoad = true;</pre>
<h2>Debug Output, disabling and minified versions</h2>
<pclass="compact">SoundManager 2 has debug mode enabled by default and will write to agents supporting <em>console.log</em>-style debugging, and/or a custom <div> element in the absence of a console.</p>
<p>To disable debug output, set <code>soundManager.debugMode = false;</code></p>
<p>Alternately, you may use the no-debug, minified version of the SM2 javascript library (which has internal debug code removed, and will silently return false.)</p>
<p>Creates and plays a sound with ID "mySound0", at the specified URL. The sound can then be referenced by that ID later, eg. soundManager.play('mySound0');</p>
<p>Note that this method is only provided for convenience, and allows only ID and URL as parameters. If you want to specify other options (volume, loop, event handlers), you must use the object literal syntax as given below.</p>
<p>This will play an existing sound (created in-page), and uses the "onfinish" handler to make a call to play a second, pre-existing sound.</p>
<p>Also note that the button can be clicked multiple times, and the sound will be "layered" as multiShot is enabled for both of these sounds when using Flash 9. An onfinish event will also fire as each sound finishes.</p>
<p><strong>Bug/behaviour note:</strong> Whenever "play" is called on a SMSound object, any parameters passed in will apply to all currently-playing instances of the sound if multiShot is allowed. For example, the onfinish handler from demo 4a will apply to demo 3 if 4a is started while 3 is still playing.</p>
<pclass="note">* Multishot is Flash 9+ only.</p>
<h2>Demo 4b: Create and play a sequence of new sounds via "onfinish"</h2>
<buttononclick="return doEval(document.getElementById('demo4c').innerHTML);return false">Do this</button> | <buttononclick="soundManager.stop('hhCymbal')">make it stop!</button>
<p>Note that there are issues with seamlessly-looping sounds, it is "close, but not perfect" with Flash 8/9 at this point.</p>
<h2id="looping">Demo 4d: Looping a sound ("loops" parameter method)</h2>
<preid="demo4d"class="block"><code>var s = soundManager.createSound({
id:'<span>hhCymbal</span>',
url:'<span>../mpc/audio/AMB_HHOP.mp3</span>'
});
s.play({
loops: 3
});
</code></pre>
<buttononclick="return doEval(document.getElementById('demo4d').innerHTML);return false">Do this</button> | <buttononclick="soundManager.stop('hhCymbal')">make it stop!</button>
<p>Looping is possible as shown above using Flash 9. <b>With flash 8, the sound must be preloaded before looping can begin</b> - eg. <code>autoLoad: true, onload: function() { this.play{loops:3} }</code>. For tighter looping, see See <ahref="http://www.flickr.com/photos/schill/4499319436/"title="Seamless looping MP3 sounds in Flash">Seamless Looping MP3 in Flash</a> for further details.</p>
<h2id="onposition">Demo 4e: Sound timing notifications using onposition()</h2>
<preid="demo4e"class="block"><code>var s = soundManager.getSoundById('<span>aCymbalSound</span>'); <span><span>// existing sound object</span></span>
<span><span>// register some listeners (only do this once, they will work for subsequent plays)</span></span>
if (typeof addedListeners === '<span>undefined</span>') {
addedListeners = true;
s.onposition(<span>500</span>, function(eventPosition) { <span><span>// fire at 0.5 seconds</span></span>
soundManager._writeDebug(<span>'Sound '+this.sID+' has reached position '+eventPosition</span>);
});
s.onposition(<span>1000</span>, function(eventPosition) {<span><span>// fire at 1 second</span></span>
soundManager._writeDebug(<span>'Sound '+this.sID+' has reached position '+eventPosition</span>);
});
}
s.play({
whileplaying:function() {
<span><span>// demo only: show sound position while playing, for context</span></span>
<p>onposition() allows you to add an event listener for a given time (in miliseconds, watching the position property); the event fires when that time has been reached while a sound is playing.</p>
<p>Note that for multiShot cases, the listeners will only fire for the original (first) shot because its position is the only one that is tracked within Flash.</p>
<buttononclick="soundManager._writeDebug('Demo 5 variant',1);var sound=soundManager.getSoundById('chinaCymbal');sound.play({position:500,pan:-75})">Do this</button> | <buttononclick="soundManager._writeDebug('Demo 5: variant: sound from position:0',1);var sound = soundManager.getSoundById('chinaCymbal');sound.play({position:0,pan:-75})">Play from position:0</button>
<p>Note that if planning to layer sounds with multiShot (Flash 9 only), this variant method will give best results as each new "channel" is started with parameters.</p>
<h2>Demo 5b: Global sound muting</h2>
<p>If not passed a sound ID, soundManager.mute() will mute all existing and newly-created sounds. soundManager.unmute() can also be passed a sound ID, and performs the inverse either on a single sound or all sounds.</p>
<p>In this demo, all sounds are globally muted and unmuted a few times. Different parameters are used to help audibly separate the sounds.</p>
<preid="demo5b-1"class="block"><code>soundManager.mute(); <span><span>// mute all sounds</span></span>
soundManager.createSound({
id: '<span>880hz</span>',
url: '<span>../_mp3/880hz.mp3</span>',
autoLoad:true,
onload: function() {
<span><span>// soundManager.mute(); // mute all sounds</span></span>
<span><span>// play (muted) cymbal sound..</span></span>
this.play({
volume:75, <span><span>// volume for when un-muted</span></span>
pan:-75, <span><span>// mostly on left channel</span></span>
<span><span>// .. and clean-up afterwards</span></span>
onfinish:function() {
this.destruct();
}
});
this.setVolume(25); <span><span>// new volume for when un-muted..</span></span>
<p>The Flash 9 version seems to resume the sound 1 msec earlier than it should, perhaps related to the timing/delay issue most noticeable on Windows.</p>
<pclass="in">Note that when using the Flash 9 version of SM2 with Flash 9 and 10 plugins, flash/OS-related delay conditions may result in the <code>position</code> property being less than the <code>duration</code> property, even by the end of the sound.</p>
<p>To work around a known "chipmunk" <ahref="http://bugs.adobe.com/jira/browse/FP-862">sampling rate issue with 48 KHz MP3s</a> in Flash, one can apparently load a sound using Flash 9 with stream = false, and then call play() once the sound has fully-loaded. Exactly why this works is not known.</p>
<span><span>// first time loading/playing</span></span>
fortyeight.load({
stream: false,
onload: function() {
<span><span>// sound has fully-loaded</span></span>
this.play();
}
});
} else {
<span><span>// sound has already loaded</span></span>
fortyeight.play();
}
</code></pre>
<buttononclick="return doEval(document.getElementById('demo12').innerHTML)">Do this</button><buttononclick="soundManager.stop('s-48khz')">Make it stop!</button>
<h2>Demo 13: onbeforefinish() testcase</h2>
<pclass="in">This event fires when the sound's position property is equal to or less than <code>onbeforefinishtime</code> msec from the end of the sound, as defined by <code>duration</code>. If unspecified, a default value is used (eg. 5000 msec.)</p>
<span><span>// autoLoadTest.play(); // sound will not start</span></span>
setTimeout(autoLoadTest.play,1000); <span><span>// may work with a delay?</span></span>
</code></pre>
<p>Under Flash 8, this case does not work as expected. Even with the delay, the sound does not begin playing as soon as expected - sometimes it fires after the sound loads, in fact. For this reason, avoid using <codeclass="in">autoLoad:true</code> if you intend to play the sound shortly after creating it when using Flash 8.</p>
<buttononclick="return doEval(document.getElementById('demo14').innerHTML)">Do this</button><buttononclick="soundManager.stop('autoLoadTest')">Make it stop!</button>
<h2>Demo 15: autoPlay + onfinish() testcase</h2>
<p>Bug testcase (Flash 8 version-specific): onfinish() does not fire with autoPlay:true</p>
<buttononclick="return doEval(document.getElementById('demo17').innerHTML)">Do this</button><buttononclick="soundManager.stop('demo17')">Make it stop!</button>
<spanid="flash-ram-use"title="Flash plugin RAM use (across this browser)"style="position:fixed;_position:absolute;top:0.5em;right:0.5em;background:#666;color:#fff;font-weight:bold;padding:0.3em 0.4em;cursor:pointer;cursor:hand;display:none"onclick="this.style.display='none';window.clearTimeout(t)">N/A</span>
