Skip to content

Commit 357924a

Browse files
author
Lanny McNie
committed
Updated tutorials.
Signed-off-by: Lanny McNie <[email protected]>
1 parent 8abc748 commit 357924a

File tree

7 files changed

+127
-114
lines changed

7 files changed

+127
-114
lines changed

tutorials/Basics and Best Practices/index.html

Lines changed: 42 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ <h1>SoundJS: Basics and Best Practices</h1>
2222
<p>
2323
<strong>Synopsis:</strong> Play audio with best practices.<br>
2424
<strong>Topics:</strong> sound, play, best practices, basics<br>
25-
<strong>Target:</strong> SoundJS 0.4.0+
25+
<strong>Target:</strong> SoundJS 0.5.2+
2626
</p>
2727
</header>
2828
<p class="highlight">
@@ -64,7 +64,7 @@ <h2>Basics</h2>
6464
<p>
6565
Conversely, all of our scripts are loaded at the bottom of the &lt;BODY&gt;. This is because JavaScript has a
6666
blocking behavior, preventing the display of any content following it until the script load has completed.
67-
Generally it is better to show a user something, then add functionality using JavaScript, then to make the user
67+
Generally it is better to show a user something, then add functionality using JavaScript, rather then to make the user
6868
wait for everything to load first.
6969
</p>
7070

@@ -75,21 +75,21 @@ <h2>Basics</h2>
7575
<h2>Initial Setup</h2>
7676
</header>
7777
<p>
78-
After creating a new html document, the first thing we'll need to play audio is, not surprisingly, link to the
78+
After creating a new html document, the first thing we'll need to play audio is, not surprisingly, a link to the
7979
SoundJS library. SoundJS is hosted on a <a href="http://code.createjs.com/" target=_blank>CDN</a>, so in the
80-
HTML body we create a &lt;SCRIPT&gt; tag and set it's source to <code>http://code.createjs.com/soundjs-0.4.1.min.js</code>.
80+
HTML body we create a &lt;SCRIPT&gt; tag and set it's source to <code>http://code.createjs.com/soundjs-0.5.2.min.js</code>.
8181
Note that the SoundJS library is available globally under the "createjs" namespace. For example the primary
8282
class "Sound" is accessed in code with <code>createjs.Sound</code>.
8383
</p>
8484
<textarea class="brush: js;" readonly>
85-
&lt;script src="http://code.createjs.com/soundjs-0.4.0.min.js"&gt;&lt;/script&gt;
85+
&lt;script src="http://code.createjs.com/soundjs-0.5.2.min.js"&gt;&lt;/script&gt;
8686
</textarea>
8787

8888
<p>
8989
Next, create an inline script that does the actual work of playing the sound. In general, it is a better
9090
practice to create an external JavaScript file and load it in the html. This gives the benefit of separating
9191
code into more maintainable chunks and allows browsers to cache the files for quicker loads if users revisit
92-
your site or visit different areas in your site that use the same script. However for our purposes, it is easier
92+
your site or visit different areas in your site that use the same script. However, for our purposes, it is easier
9393
to demonstrate how to play sound inline in the HTML file.</p>
9494

9595
<p>Inside this script, create an <code>init</code> function, which will be called by adding an onload handler to the
@@ -98,7 +98,7 @@ <h2>Initial Setup</h2>
9898
</p>
9999
<textarea class="brush: js;" readonly>
100100
&lt;body onload="init()"&gt;
101-
&lt;script src="http://code.createjs.com/soundjs-0.4.0.min.js"/&gt;
101+
&lt;script src="http://code.createjs.com/soundjs-0.5.2.min.js"/&gt;
102102
&lt;script&gt;
103103
function init() {
104104

@@ -115,9 +115,9 @@ <h2>Plugins</h2>
115115
</header>
116116
<p>
117117
Once setup is complete, we can get directly to loading and playing sounds. It is important to know, however,
118-
that SoundJS uses a number of plugins to playback audio in different browsers. There are no additional steps to
119-
initialize the plugins, and the default plugin set (Web Audio and HTML Elements) will work in the majority of
120-
modern browsers. For this tutorial, the default plugin set will be fine.
118+
that SoundJS uses a number of plugins to enable audio playback in different browsers. There are no additional
119+
steps to initialize the plugins, and the default plugin set (Web Audio and HTML Elements) will work in the
120+
majority of modern browsers. For this tutorial, the default plugin set will be fine.
121121
</p>
122122
<p>
123123
Plugin selection will happen automatically the first time audio is preloaded or played, however if you need to
@@ -137,7 +137,7 @@ <h2>Internal Preloading</h2>
137137
</header>
138138
<p>
139139
It is a best practice to preload audio so it is ready for immediate playback. We have an <a href="../SoundJS%20and%20PreloadJS/index.html" target="_blank">
140-
excellent tutorial on preloading techniques</a>, but for this example we'll only be doing a basic internal
140+
excellent tutorial on preloading techniques</a>, but for this example we'll only be using a basic internal
141141
preloading approach.
142142
</p>
143143
<p>
@@ -149,37 +149,36 @@ <h2>Internal Preloading</h2>
149149
We store the relative path to our audio assets as a variable as a best practice, which allows us to make a
150150
single change when moving the files, rather than trying to track down every individual use. Another best
151151
practice is to include both an mp3 and ogg version of your audio to give the broadest playback support possible.
152-
SoundJS enables you to do this by adding a delimiter (the default is "|") character between audio files. The
153-
code should look like this:
152+
SoundJS enables you to do this by adding a setting the
153+
<a href="http://www.createjs.com/Docs/SoundJS/classes/Sound.html#property_alternateExtensions" target="_blank">
154+
alternateExtensions property</a>. The code will look like this:
154155
</p>
155156
<textarea class="brush: js;" readonly>
156157
var audioPath = "assets/";
157158
var manifest = [
158-
{id:"Music",
159-
src:audioPath+"18-machinae_supremacy-lord_krutors_dominion.mp3|"+audioPath+"18-machinae_supremacy-lord_krutors_dominion.ogg"},
160-
{id:"Thunder", src:audioPath + "Thunder1.mp3|"+audioPath + "Thunder1.ogg"}
159+
{id:"Music", src:"18-machinae_supremacy-lord_krutors_dominion.ogg},
160+
{id:"Thunder", src:"Thunder1.ogg"}
161161
];
162+
createjs.Sound.alternateExtensions = ["mp3"];
162163
</textarea>
163164

164-
<!-- TODO replace loadComplete event with current fileload when updated -->
165165
<p>
166-
With our audio comfortably defined in a manifest, let's move on to loading the audio. SoundJS introduced an
167-
Event model in 0.4.0, and we can add an event listener for the <a href="http://www.createjs.com/Docs/SoundJS/classes/Sound.html#event_fileload" target="_blank">
168-
<code>fileload</code> event</a> (Note that SoundJS 0.4.0 uses a inconsistently-named <code>loadComplete</code>
169-
event instead). It is a best practice to add this <em>before</em> we begin loading the audio to avoid a race
166+
With our audio comfortably defined in a manifest, let's move on to loading the audio. SoundJS uses an
167+
Event model, so we can add an event listener for the <a href="http://www.createjs.com/Docs/SoundJS/classes/Sound.html#event_fileload" target="_blank">
168+
<code>fileload</code> event</a>. It is a best practice to add this <em>before</em> we begin loading the audio to avoid a race
170169
condition where audio can load from cache immediately. The second parameter of the listener is the function to
171170
call back. Once this is ready, the audio load can be kicked off using the <a href="http://www.createjs.com/Docs/SoundJS/classes/Sound.html#method_registerManifest" target="_blank">
172171
<code>registerManifest</code> method</a>. Our deceptively simple and clean code should look like this:
173172
</p>
174173
<textarea class="brush: js;" readonly>
175174
function init() {
176-
// create a manifest (above)
177-
createjs.Sound.addEventListener("loadComplete", handleLoad);
178-
createjs.Sound.registerManifest(manifest);
175+
// create a manifest and audioPath (above)
176+
createjs.Sound.addEventListener("loadComplete", handleLoad);
177+
createjs.Sound.registerManifest(manifest, audioPath);
179178
}
180179

181180
function handleLoad(event) {
182-
// Do something with the loaded sound
181+
// Do something with the loaded sound
183182
}
184183
</textarea>
185184

@@ -197,7 +196,7 @@ <h2>Playback</h2>
197196
</p>
198197
<textarea class="brush: js;" readonly>
199198
function handleLoad(event) {
200-
createjs.Sound.play(event.src);
199+
createjs.Sound.play(event.src);
201200
}
202201
</textarea>
203202

@@ -207,30 +206,31 @@ <h2>Playback</h2>
207206
</p>
208207
<textarea class="brush: js;" readonly>
209208
&lt;body onload="init()"&gt;
210-
&lt;script src="http://code.createjs.com/soundjs-0.4.0.min.js"/&gt;
209+
&lt;script src="http://code.createjs.com/soundjs-0.5.2.min.js"/&gt;
211210
&lt;script&gt;
212211
function init() {
213-
// if initializeDefaultPlugins returns false, we cannot play sound in this browser
214-
if (!createjs.Sound.initializeDefaultPlugins()) {return;}
215-
var audioPath = "assets/";
216-
var manifest = [
217-
{id:"Music",
218-
src:audioPath+"18-machinae_supremacy-lord_krutors_dominion.mp3|"+audioPath+"18-machinae_supremacy-lord_krutors_dominion.ogg"},
219-
{id:"Thunder", src:audioPath + "Thunder1.mp3|"+audioPath + "Thunder1.ogg"}
220-
];
212+
// if initializeDefaultPlugins returns false, we cannot play sound in this browser
213+
if (!createjs.Sound.initializeDefaultPlugins()) {return;}
214+
215+
var audioPath = "assets/";
216+
var manifest = [
217+
{id:"Music", src:"18-machinae_supremacy-lord_krutors_dominion.ogg"},
218+
{id:"Thunder", src:"Thunder1.ogg"}
219+
];
221220

222-
createjs.Sound.addEventListener("loadComplete", handleLoad);
223-
createjs.Sound.registerManifest(manifest);
221+
createjs.Sound.alternateExtensions = ["mp3"];
222+
createjs.Sound.addEventListener("fileload", handleLoad);
223+
createjs.Sound.registerManifest(manifest, audioPath);
224224
}
225225

226226
function handleLoad(event) {
227-
createjs.Sound.play(event.src);
227+
createjs.Sound.play(event.src);
228228
}
229229
&lt;/script&gt;
230230
&lt;/body&gt;
231231
</textarea>
232232

233-
<p>Check out the sample.html provided in this tutorial's directory.</p>
233+
<p>Check out sample.html provided in this tutorial's directory.</p>
234234
</section>
235235

236236
<section>
@@ -240,9 +240,9 @@ <h2>Conclusion</h2>
240240

241241
<p>
242242
This wraps up the tutorial on basics and best practices, which should give you a great start. The above example
243-
will not work on mobile devices (phones and tablets), due to security requirements that require user input to
243+
will not work on all mobile devices (phones and tablets), due to security requirements that require user input to
244244
play audio. This topic is the focus of the <a href="../Mobile%20Safe%20Approach/index.html" target="_blank">
245-
Mobile Safe tutorial</a>. Good places to learn more are the SoundJS are the
245+
Mobile Safe tutorial</a>. Good places to learn more are SoundJS are the
246246
<a href="http://createjs.com/Docs/SoundJS" target="_blank">online documentation</a>
247247
and <a href="https://github.com/CreateJS/SoundJS/tree/master/examples" target="_blank">examples in GitHub</a>.
248248
</p>
@@ -257,7 +257,7 @@ <h2>Related Links</h2>
257257
</header>
258258
<ol>
259259
<li>Download CreateJS from the <a href="http://code.createjs.com" target="_blank">Adobe CDN</a>.</li>
260-
<li>Get the SoundJS source code, including minified versions of SoundJS and FlashPlugin from <a
260+
<li>Get the latest SoundJS source code, including minified versions of SoundJS and FlashPlugin from <a
261261
href="http://github.com/CreateJS/SoundJS/" target="_blank">GitHub</a>.
262262
</li>
263263
<li>Read more about SoundJS in the <a href="http://createjs.com/Docs/SoundJS" target="_blank">online

tutorials/Basics and Best Practices/sample.html

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,21 @@
44
<title></title>
55
</head>
66
<body onload="init()">
7-
<script src="http://code.createjs.com/soundjs-0.4.0.min.js"></script>
7+
<script src="http://code.createjs.com/soundjs-0.5.2.min.js"></script>
88

99
<script>
1010
function init() {
1111
if (!createjs.Sound.initializeDefaultPlugins()) {return;}
1212

1313
var audioPath = "../_assets_soundjs/";
1414
var manifest = [
15-
{id:"Music", src:audioPath+"18-machinae_supremacy-lord_krutors_dominion.mp3|"+audioPath+"18-machinae_supremacy-lord_krutors_dominion.ogg"},
16-
{id:"Thunder", src:audioPath + "Thunder1.mp3|"+audioPath + "Thunder1.ogg"}
15+
{id:"Music", src:"18-machinae_supremacy-lord_krutors_dominion.ogg"},
16+
{id:"Thunder", src:"Thunder1.ogg"}
1717
];
1818

19-
createjs.Sound.addEventListener("loadComplete", handleLoad);
20-
createjs.Sound.registerManifest(manifest);
19+
createjs.Sound.alternateExtensions = ["mp3"];
20+
createjs.Sound.addEventListener("fileload", handleLoad);
21+
createjs.Sound.registerManifest(manifest, audioPath);
2122
}
2223

2324
function handleLoad(event) {

tutorials/Mobile Safe Approach/index.html

Lines changed: 35 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ <h1>SoundJS: Mobile Safe Approach</h1>
2121
<p>
2222
<strong>Synopsis:</strong> An approach to playing audio that also works on mobile devices<br>
2323
<strong>Topics:</strong> sound, play, mobile safe approaches, best practices<br>
24-
<strong>Target:</strong> SoundJS 0.4.0+
24+
<strong>Target:</strong> SoundJS 0.5.2+
2525
</p>
2626
</header>
2727
<p class="highlight">
@@ -48,19 +48,22 @@ <h2>Introduction</h2>
4848
&lt;/head&gt;
4949

5050
&lt;body onload="init()"&gt;
51-
&lt;script src="http://code.createjs.com/soundjs-0.4.0.min.js"/&gt;
51+
&lt;script src="http://code.createjs.com/soundjs-0.5.2.min.js"/&gt;
5252

5353
&lt;script&gt;
5454
function init() {
55+
// if initializeDefaultPlugins returns false, we cannot play sound in this browser
5556
if (!createjs.Sound.initializeDefaultPlugins()) {return;}
57+
5658
var audioPath = "assets/";
5759
var manifest = [
58-
{id:"Music", src:audioPath+"18-machinae_supremacy-lord_krutors_dominion.mp3|"+audioPath+"18-machinae_supremacy-lord_krutors_dominion.ogg"},
59-
{id:"Thunder", src:audioPath + "Thunder1.mp3|"+audioPath + "Thunder1.ogg"}
60+
{id:"Music", src:"18-machinae_supremacy-lord_krutors_dominion.ogg"},
61+
{id:"Thunder", src:"Thunder1.ogg"}
6062
];
6163

62-
createjs.Sound.addEventListener("loadComplete", handleLoad);
63-
createjs.Sound.registerManifest(manifest);
64+
createjs.Sound.alternateExtensions = ["mp3"];
65+
createjs.Sound.addEventListener("fileload", handleLoad);
66+
createjs.Sound.registerManifest(manifest, audioPath);
6467
}
6568

6669
function handleLoad(event) {
@@ -157,7 +160,7 @@ <h3>Ready to Rock</h3>
157160
&lt;body onload="init()"&gt;
158161
&lt;h1 id="status"&gt;Hello World.&lt;/h1&gt;
159162

160-
&lt;script src="http://code.createjs.com/soundjs-0.4.0.min.js"&gt;&lt;/script&gt;
163+
&lt;script src="http://code.createjs.com/soundjs-0.5.2.min.js"&gt;&lt;/script&gt;
161164

162165
&lt;script&gt;
163166
var displayMessage = null;
@@ -169,12 +172,14 @@ <h3>Ready to Rock</h3>
169172

170173
var audioPath = "assets/";
171174
var manifest = [
172-
{id:"Music", src:audioPath+"18-machinae_supremacy-lord_krutors_dominion.mp3|"+audioPath+"18-machinae_supremacy-lord_krutors_dominion.ogg"},
173-
{id:"Thunder", src:audioPath + "Thunder1.mp3|"+audioPath + "Thunder1.ogg"}
175+
{id:"Music", src:"18-machinae_supremacy-lord_krutors_dominion.ogg"},
176+
{id:"Thunder", src:"Thunder1.ogg"}
174177
];
175178

176-
createjs.Sound.addEventListener("loadComplete", handleLoad);
177-
createjs.Sound.registerManifest(manifest);
179+
displayMessage.innerHTML = "Loading Audio";
180+
createjs.Sound.alternateExtensions = ["mp3"];
181+
createjs.Sound.addEventListener("fileload", handleLoad);
182+
createjs.Sound.registerManifest(manifest, audioPath);
178183
}
179184

180185
function handleLoad(event) {
@@ -207,7 +212,7 @@ <h2>Playing After Touch</h2>
207212

208213
<h3>Namespace and Closure</h3>
209214
<p>
210-
The first changes we want to make is to set up our code more like an application. If you are building something
215+
The first change we want to make is to set up our code more like an application. If you are building something
211216
more complex, hopefully you have already taken these steps.
212217
</p>
213218
<ol>
@@ -272,13 +277,14 @@ <h3>Change Scope</h3>
272277

273278
var audioPath = "assets/";
274279
var manifest = [
275-
{id:"Music", src:audioPath+"18-machinae_supremacy-lord_krutors_dominion.mp3|"+audioPath+"18-machinae_supremacy-lord_krutors_dominion.ogg"},
276-
{id:"Thunder", src:audioPath + "Thunder1.mp3|"+audioPath + "Thunder1.ogg"}
280+
{id:"Music", src:"18-machinae_supremacy-lord_krutors_dominion.ogg"},
281+
{id:"Thunder", src:"Thunder1.ogg"}
277282
];
278283

279-
this.displayMessage.innerHTML = "loading audio";
280-
createjs.Sound.addEventListener("loadComplete", this.handleLoad);
281-
createjs.Sound.registerManifest(manifest);
284+
this.displayMessage.innerHTML = "Loading Audio";
285+
createjs.Sound.alternateExtensions = ["mp3"];
286+
createjs.Sound.addEventListener("fileload", handleLoad);
287+
createjs.Sound.registerManifest(manifest, audioPath);
282288
}
283289

284290
handleLoad: function(event) {
@@ -318,14 +324,14 @@ <h3>Apply Application Scope</h3>
318324
more essential step: Currently, our <code>handleLoad</code> function is not called in the MyApp scope. That
319325
means it will not have access to the MyApp object (this), and that the audio is not played inside of the touch
320326
scope. We need this function to execute in our application scope to fix these problems, which we do using the
321-
handy <code>createjs.proxy</code> method. This function uses <a href="https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Function/apply" target="_blank">
322-
<code>Function.apply</code></a> to set the scope that a function executes in, which sets the "this" reference.
323-
Function scope is a very important topic with JavaScript application development, so invest some time in
324-
research if you want to understand it better.
327+
handy <code>createjs.proxy</code> method. Createjs.proxy uses <a href="https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Function/apply" target="_blank">
328+
<code>Function.apply</code></a> to set the scope that a function executes in, setting the reference of "this".
329+
Function scope is a very important topic of JavaScript application development, so it can be worth investing
330+
some time in research to understand it better.
325331
</p>
326332
<textarea class="brush: js;" readonly>
327333
var loadProxyMethod = createjs.proxy(this.handleLoad, this);
328-
createjs.Sound.addEventListener("loadComplete", loadProxyMethod);
334+
createjs.Sound.addEventListener("fileload", loadProxyMethod);
329335

330336
</textarea>
331337

@@ -345,7 +351,7 @@ <h3>Ready to Rock Everywhere</h3>
345351
&lt;body onload="init()"&gt;
346352
&lt;h1 id="status"&gt;Hello World.&lt;/h1&gt;
347353

348-
&lt;script src="http://code.createjs.com/soundjs-0.4.0.min.js"&gt;&lt;/script&gt;
354+
&lt;script src="http://code.createjs.com/soundjs-0.5.2.min.js"&gt;&lt;/script&gt;
349355

350356
&lt;script&gt;
351357
var display;
@@ -377,14 +383,15 @@ <h3>Ready to Rock Everywhere</h3>
377383

378384
var audioPath = "assets/";
379385
var manifest = [
380-
{id:"Music", src:audioPath+"18-machinae_supremacy-lord_krutors_dominion.mp3|"+audioPath+"18-machinae_supremacy-lord_krutors_dominion.ogg"},
381-
{id:"Thunder", src:audioPath + "Thunder1.mp3|"+audioPath + "Thunder1.ogg"}
386+
{id:"Music", src:"18-machinae_supremacy-lord_krutors_dominion.ogg"},
387+
{id:"Thunder", src:"Thunder1.ogg"}
382388
];
383389

384390
this.displayMessage.innerHTML = "loading audio";
391+
createjs.Sound.alternateExtensions = ["mp3"];
385392
var loadProxy = createjs.proxy(this.handleLoad, this);
386-
createjs.Sound.addEventListener("loadComplete", loadProxy);
387-
createjs.Sound.registerManifest(manifest);
393+
createjs.Sound.addEventListener("fileload", loadProxy);
394+
createjs.Sound.registerManifest(manifest, audioPath);
388395
},
389396

390397
handleLoad: function(event) {
@@ -428,6 +435,7 @@ <h2>Related Links</h2>
428435
<li>Get involved in active <a href="http://community.createjs.com/discussions/soundjs" target="_blank">community discussion</a>.</li>
429436
</ol>
430437
</section>
438+
</section>
431439

432440
</article>
433441
</body>

0 commit comments

Comments
 (0)