Skip to content

Commit

Permalink
Updated docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@scottschiller
scottschiller committed Mar 24, 2013
1 parent 7fa4f1d commit dbcabd9
Show file tree
Hide file tree
Showing 6 changed files with 201 additions and 19 deletions.
2 changes: 2 additions & 0 deletions doc/download/archive.html
View file
Expand Up @@ -84,6 +84,8 @@ <h1>SoundManager 2: Download</h1>
<a href="../technotes/">Technical Notes</a>
<ul>
<li><a href="../technotes/#requirements">System Requirements</a></li>
<li><a href="../technotes/#serving-audio">Serving To Clients</a></li>
<li><a href="../technotes/#mobile-device-limitations">Mobile Device Limitations</a></li>
<li><a href="../technotes/#debug-output">Debug + Console Output</a></li>
</ul>
</li>
Expand Down
113 changes: 108 additions & 5 deletions doc/download/index.html 100644 → 100755
View file
Expand Up @@ -84,6 +84,8 @@ <h1>SoundManager 2: Download</h1>
<a href="../technotes/">Technical Notes</a>
<ul>
<li><a href="../technotes/#requirements">System Requirements</a></li>
<li><a href="../technotes/#serving-audio">Serving To Clients</a></li>
<li><a href="../technotes/#mobile-device-limitations">Mobile Device Limitations</a></li>
<li><a href="../technotes/#debug-output">Debug + Console Output</a></li>
</ul>
</li>
Expand Down Expand Up @@ -132,9 +134,9 @@ <h2>Get SoundManager 2</h2>

<h3>Download SoundManager 2</h3>

<p><b>Latest changes:</b> 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 <a href="#history">revision history</a> for details.</p>
<p><b>Latest changes:</b> Fix for playlist/event chaining when using <code>flashVersion = 8</code> with Flash Player 11.6.602.171. HTML5 iOS <code>load()</code> fix. Added Opus to audio formats. See <a href="#history">revision history</a> for details.</p>

<p style="padding-top:0.5em"><a href="../../download/soundmanagerv297a-20130101.zip" title="Download SoundManager 2" class="norewrite feature">Download SoundManager 2.97a.20130101</a> or see <a href="https://github.com/scottschiller/soundmanager2/" title="SoundManager 2 on GitHub">on GitHub</a></p>
<p style="padding-top:0.5em"><a href="../../download/soundmanagerv297a-20130324.zip" title="Download SoundManager 2" class="norewrite feature">Download SoundManager 2.97a.20130324</a> or see <a href="https://github.com/scottschiller/soundmanager2/" title="SoundManager 2 on GitHub">on GitHub</a></p>

<p><b>Performance tip:</b> SM2's code size varies from over 128 KB (commented, debug-enabled) down to 11 KB (optimized) over HTTP; check the <a href="../getstarted/#basic-inclusion" title="Including SoundManager 2 on your site: Script build options">pre-optimized builds</a> for details.</p>

Expand Down Expand Up @@ -171,9 +173,112 @@ <h3 id="revision-history">Revision History</h3>

<ul id="revision-list" class="standard">

<li id="sm2-20130324" class="in">

<h3><b>V2.97a.20130324</b> - Fix for playlist/event chaining when using <code>flashVersion = 8</code> with Flash Player 11.6.602.171. HTML5 iOS <code>load()</code> fix. Added Opus to audio formats.</h3>

<ul>

<li class="in">

<p class="compact">Bug fixes</p>

<ul class="nested compact flat">

<li>
<p>
Flash Player 11.6.602.171, released by Adobe on 02/26/2013, introduced an issue with SM2's default Flash 8 (<code>flashVersion: 8</code>) API-based JS/Flash interaction, where SM2 methods called from callbacks such as <code>onfinish()</code> would not work. This primarily broke methods used for playing sounds in sequence, serially loading a series of sounds and so on. (See <a href="https://getsatisfaction.com/schillmania/topics/recent_chrome_update_seems_to_have_broken_my_sm2_audio_player">discussion</a> for more.)
</p>

<p>
Note that this does not affect cases where <code>soundManager.setup({ flashVersion: 9})</code> is being used; however, SM2 does use <code>flashVersion: 8</code> by default.
</p>

<p>
Specifically, Flash-initiated events (such as a sound finishing) make Flash -&gt; JS calls to the SM2 API, which subsequently call user-specified event handlers. If the user-specified SM2 <code>onfinish()</code> handler immediately calls a SM2 method like <code>play()</code> that makes a JS -&gt; 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.
</p>

<p>
Suspecting a timing or recursion/stack issue, it was found that introducing a <code>setTimeout(callback, 0)</code> to user-specified SM2 callbacks like <code>onfinish()</code> restored sequential/playlist functionality.
</p>

<p>
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.
</p>

<p>
Alternately, this issue can be avoided by using <code>soundManager.setup({ flashVersion: 9 })</code> as the Flash 9-based API does not appear to have this problem.</code>
</p>
</li>

<li>
<p>
HTML5: Fix for iOS <code>load()</code> case when using an auto-load and looping pattern (related <a href="https://getsatisfaction.com/schillmania/topics/autoload_on_ipad_loop_error">discussion</a>).
</p>
</li>

</ul>

</li>

<li class="in">

<p class="compact">API Updates</p>

<ul class="nested compact flat">

<li>
<p>
HTML5: Added check for Opus (OGG-based audio codec, <code>audio/opus</code>).
</p>
</li>

</ul>

</li>

<li class="in">

<p class="compact">Miscellaneous</p>

<ul class="nested compact flat">

<li>

<p>
Added documentation for <a href="../technotes/#serving-audio">Serving To Clients</a>, and <a href="../technotes/#mobile-device-limitations">Mobile Device Limitations</a>.
</p>
</li>

<li>

<p>
Minor SM2 homepage + documentation CSS tweaks (design)
</p>
</li>

<li>

<p>
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.
</p>


</li>

</ul>

</li>

</ul>

</li>

<!-- previously ... -->

<li id="sm2-20130101" class="in">

<h3><b>V2.97a.20130101</b> - Strict Mode. Android 2.3 HTML5 fixes, cleaner debug output, improved default flashblock handling. Confirmed compatibility with Firefox WMF-based HTML5 MP3 support. New <code>reset()</code> method, <code>reboot()</code> tweaks.</h3>
<h3><b>V2.97a.20130101</b> - Strict Mode. Android 2.3 HTML5 fixes, cleaner debug output, improved default flashblock handling. Confirmed compatibility with Firefox WMF-based HTML5 MP3 support. New <code>reset()</code> method, <code>reboot()</code> tweaks (<a href="../../download/soundmanagerv297a-20130101.zip" class="norewrite">Download archived version</a>)</h3>

<ul>

Expand Down Expand Up @@ -288,8 +393,6 @@ <h3><b>V2.97a.20130101</b> - Strict Mode. Android 2.3 HTML5 fixes, cleaner debug

</li>

<!-- previously ... -->

<li id="sm2-20121104" class="in">

<h3><b>V2.97a.20121104</b> - HTML5 + iOS load fixes, Windows 8 App Store compatibility tweak, code pattern improvements (<a href="../../download/soundmanagerv297a-20121104.zip" class="norewrite">Download archived version</a>)</h3>
Expand Down
12 changes: 7 additions & 5 deletions doc/getstarted/index.html 100644 → 100755
View file
Expand Up @@ -92,6 +92,8 @@ <h1>SoundManager 2: Getting Started</h1>
<a href="../technotes/">Technical Notes</a>
<ul>
<li><a href="../technotes/#requirements">System Requirements</a></li>
<li><a href="../technotes/#serving-audio">Serving To Clients</a></li>
<li><a href="../technotes/#mobile-device-limitations">Mobile Device Limitations</a></li>
<li><a href="../technotes/#debug-output">Debug + Console Output</a></li>
</ul>
</li>
Expand Down Expand Up @@ -161,8 +163,8 @@ <h4 id="basic-inclusion">Including SoundManager 2</h4>
<pre>&lt;script src="<span>soundmanager2.js</span>"&gt;&lt;/script&gt;</pre>
</td>
<td>Development, testing, debugging</td>
<td class="nw">144 KB</td>
<td class="nw">38 KB</td>
<td class="nw">146 KB</td>
<td class="nw">39 KB</td>
</tr>

<tr>
Expand All @@ -172,7 +174,7 @@ <h4 id="basic-inclusion">Including SoundManager 2</h4>
</td>
<td>Production, "clean" no-debug code</td>
<td class="nw">75 KB</td>
<td class="nw">16 KB</td>
<td class="nw">17 KB</td>
</tr>

<tr>
Expand All @@ -181,7 +183,7 @@ <h4 id="basic-inclusion">Including SoundManager 2</h4>
<pre>&lt;script src="<span>soundmanager2-jsmin.js</span>"&gt;&lt;/script&gt;</pre>
</td>
<td>Production, with debug code</td>
<td class="nw">49 KB</td>
<td class="nw">47 KB</td>
<td class="nw">16 KB</td>
</tr>

Expand All @@ -191,7 +193,7 @@ <h4 id="basic-inclusion">Including SoundManager 2</h4>
<pre>&lt;script src="<span>soundmanager2-nodebug-jsmin.js</span>"&gt;&lt;/script&gt;</pre>
</td>
<td>Production-optimized, debug code removed</td>
<td class="nw">34 KB</td>
<td class="nw">33 KB</td>
<td class="nw booyaa" title="Best-case scenario for load time/performance">11 KB!</td>
</tr>

Expand Down
13 changes: 8 additions & 5 deletions doc/index.html 100644 → 100755
View file
Expand Up @@ -86,6 +86,8 @@ <h1>SoundManager 2: Documentation</h1>
<a href="technotes/">Technical Notes</a>
<ul>
<li><a href="technotes/#requirements">System Requirements</a></li>
<li><a href="technotes/#serving-audio">Serving To Clients</a></li>
<li><a href="technotes/#mobile-device-limitations">Mobile Device Limitations</a></li>
<li><a href="technotes/#debug-output">Debug + Console Output</a></li>
</ul>
</li>
Expand Down Expand Up @@ -567,12 +569,13 @@ <h4 id="soundmanager-html5pollinginterval">html5PollingInterval</h4>
<div class="f-block f-preferflash">
<h4 id="soundmanager-preferflash">preferFlash</h4>
<p>This property handles "mixed-mode" HTML5 + flash cases, and may prevent 100% HTML5 mode when enabled depending on the configuration of <a href="#soundmanager-audioformats">soundManager.audioFormats</a>. In the event HTML5 supports the default "required" formats (presently MP3), and <code>preferFlash</code> 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.</p>
<p><em>Important note:</em> Because HTML5 audio has some critical bugs across various browsers and operating systems, <code>preferFlash</code> is <code>true</code> by default to help ensure MP3/MP4 play consistently. If set to <code>false</code> 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 <code>false</code>.</p>
<p><em>Important note:</em> Because HTML5 audio has some bugs across various browsers and operating systems, <code>preferFlash</code> is <code>true</code> by default to help ensure MP3/MP4 play consistently. If set to <code>false</code> or flash is not available, "HTML5-only" mode will kick in and will apply to all formats.</p>
<p>To encourage 100% HTML5 mode, call <code>soundMangager.setup({ preferFlash: false })</code> and then Flash will not be used for MP3/MP4 playback, provided that HTML5 supports them.</p>
</div>

<div class="f-block f-url">
<h4 id="soundmanager-url">url</h4>
<p class="in"><code>soundManager.setupOptions.url</code> 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.</p>
<p class="in"><code>soundManager.url</code>, applied via <code>soundManager.setup()</code>, specifies the "online", generally HTTP-based path which SM2 will load .SWF movies from. The "local" (current) path of <code>./</code> will be used by default. The appropriate .SWF required (depending on the desired Flash version) will be appended to the URL.</p>
<p class="in">Example: <code>soundManager.setup({ url: '<span>/path/to/swf-directory/</span>' });</code> (Note trailing slash)</p>
<p>For a simple demo of this in action, see the <a href="../demo/template/">basic template</a>.</p>
<p class="in">For cases where SM2 is being used "offline" in non-HTTP cases (eg., development environments), see <code>altURL</code>.</p>
Expand Down Expand Up @@ -648,14 +651,14 @@ <h4 id="soundmanager-highperformance">useHighPerformance</h4>

<h4 id="soundmanager-usehtml5audio">useHTML5Audio</h4>

<p style="background:#f0f9ff"><b style="color:#993333">Beta notice</b>: HTML5 support is in active development. Experimental API bits will be labeled as such, but should remain largely forward-compatible. See <a href="download/#revision-history">Revision History</a> for the latest updates on HTML5 playback support.</p>
<p style="background:#f0f9ff">HTML5 support is in active development. See <a href="download/#revision-history">Revision History</a> for the latest updates on HTML5 playback support.</p>

<p><code>useHTML5Audio</code> determines whether HTML5 <code>Audio()</code> 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.</p>

<p>The SM2 API is effectively transparent, consistent whether using flash or HTML5 <code>Audio()</code> 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.)</p>

<p>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 <code><a href="#soundmanager-audioformats">soundManager.audioFormats</a></code>.) HTML5 may also enable support for additional formats such as OGG and WAV.</p>
<p>In the case when HTML5 + Flash are present, Flash will presently get preference for MP3/MP4 because of <code>soundManager.preferFlash = true</code> as HTML5 audio is still buggy between browsers and platforms; where desired, you can set <code>preferFlash = false</code> 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."</p>
<p>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 <code><a href="#soundmanager-audioformats">soundManager.audioFormats</a></code>.) HTML5 may also enable support for additional formats such as OGG and WAV.</p>
<p>In the case when HTML5 + Flash are present, Flash will presently get preference for MP3/MP4 because of SM2's default <code>preferFlash: true</code> setup option, as HTML5 audio is still buggy between browsers and platforms; where desired, you can use <code>soundManager.setup({ preferFlash: false })</code> 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."</p>

<h5>SoundManager 2 + useHTML5Audio: Init Process</h5>

Expand Down
2 changes: 2 additions & 0 deletions doc/resources/index.html 100644 → 100755
View file
Expand Up @@ -84,6 +84,8 @@ <h1>SoundManager 2: Resources</h1>
<a href="../technotes/">Technical Notes</a>
<ul>
<li><a href="../technotes/#requirements">System Requirements</a></li>
<li><a href="../technotes/#serving-audio">Serving To Clients</a></li>
<li><a href="../technotes/#mobile-device-limitations">Mobile Device Limitations</a></li>
<li><a href="../technotes/#debug-output">Debug + Console Output</a></li>
</ul>
</li>
Expand Down

0 comments on commit dbcabd9

Please sign in to comment.