Merge f52e29d into master

Author: sbaechler

doc/music.adoc

@@ -1,20 +1,20 @@
 Music and Bass Shake[[music]]
 -----------------------------
 
-In Hexagon, the music is an important element of the game. It is even part of the game mechanics:
+In Hexagon, the music is an important element of the game. It is even part of the physical game mechanics:
 Whenever there is a bass sequence, the whole stage is shaking.
 
 The original game music is copyrighted. Therefore we provide an alternative track
 for this tutorial that has a Creative Commons license.
 
-There is an issue with Safari, so use a different Browser for this.
+There is also an issue with Safari, so use a different browser for this like Google Chrome or the newest Internet Explorer.
 
 ## Download the Music
 The track that we are going to use is called "Shiny Tech" by Kevin MacLeod.
-Download it from the
-http://incompetech.com/music/royalty-free/index.html?collection=12&page=1[Incompetech] website.
+Download it here:
+http://incompetech.com/music/royalty-free/index.html?collection=12&page=1[Incompetech] 
 
-Rename it to `shinytech.mp3` and copy it into a `src/music` folder.
+Rename it `shinytech.mp3` and copy it into a `src/music` folder.
 
 ---
 
@@ -30,9 +30,10 @@ Rename the downloaded file to "music.mp3" and copy it into the music folder.
 
 
 ## Install the audio library
+
 The audio library abstracts the HTML5 Audio tag for the elm language. It uses native bindings.
 Unfortunately Elm discourages the use of native bindings for 3rd party libraries. But until audio
-support is available in core we have to use one.
+support is available in core, we have to use one.
 
 It is not possible to install such libraries through elm-package. So we have to use git
 or download it ourselves. We copy the `elm-audio` library in a folder called `lib/elm-audio`.
@@ -46,16 +47,16 @@ If you are already using git for this tutorial, then you can add it as a submodu
 
     git submodule add https://github.com/xarvh/elm-audio.git lib/elm-audio
 
-This is not enogh though. Elm expects the native module to be named after the package.
+This is not enough information though. Elm expects the native module to be named after the package.
 So open the file `elm-audio/src/Native/Audio.js` and change the name of the global function
 to match the name that you gave your project in `elm-package.json` in the `repository` field.
-It uses the syntax `_<username>$<project>$Native_Audio` so if you left it at the default the first
+It uses the syntax `_<username>$<project>$Native_Audio`, so if you left it at the default setting the first
 line of the module is:
 
     var _sbaechler$polygon$Native_Audio = function() {
 
 While we are here, we can add a few strategic console.log statements for debugging:
- * Inside the `oncanplaythrough()` method which fires when the audio has been loaded completely
+ * Inside the `oncanplaythrough()` method that fires when the audio has been completely loaded
  * Inside the `playSound` and `stopSound` method.
 
 
@@ -85,9 +86,9 @@ Add a `hasBass : Bool` property as well.
 The music property is initialized with the value `Nothing` in the `init` method. `hasBass` is set to
 `False`.
 
-The loading of the music file is a Task as well. It sends of the message `MusicLoaded` when the
-mp3 has been downloaded (When the browser has fired the `canplaythrough` event).
-The task could also fail, therefore we add an `Error` message. A `Noop`
+The loading of the music file is a task as well. It sends the message `MusicLoaded` when the
+mp3 has been downloaded (when the browser has fired the `canplaythrough` event).
+The task could also fail, therefore we need to add an `Error` message. A `Noop`
 message is needed as well as a callback for the stop command.
 
 // type Msg
@@ -98,8 +99,8 @@ We curry the `loadSound` method with the file name for the audio file:
 // loadSound
 {% codesnippet "https://raw.githubusercontent.com/macrozone/elm-hexagon-tutorial/chapter/music/src/Hexagon.elm", lines="120:121" %}{% endcodesnippet %}
 
-The audio library exposes a `Sound` type wich is a reference to a HTML5 Audio tag. The
-`PlaybackOptions` object has three attributes: Volume, start and loop.
+The audio library exposes a `Sound` type, which is a reference to a HTML5 Audio tag. The
+`PlaybackOptions` object has three attributes: volume, start and loop.
 
 We set loop to True and startAt to Nothing, which means that it continues playing from its current
 position.
@@ -108,7 +109,7 @@ position.
 {% codesnippet "https://raw.githubusercontent.com/macrozone/elm-hexagon-tutorial/chapter/music/src/Hexagon.elm", lines="124:125" %}{% endcodesnippet %}
 
 The `playSound` and `stopSound` functions start and stop the music. They take a reference to the
-sound object and an options object and return a command of type message.
+sound object and an options object, then returning a command of type message.
 
 They are tasks because playing audio is a side-effect. In case of an error, the Error message is
 sent. In case of success (the audio is done playing) the Noop message is sent.
@@ -120,13 +121,13 @@ We use anonymous functions to define the callbacks.
 With all the new states the update methods become a bit more complex. However, they are still
 easily readable and understandable.
 
-We add the new intermediate helper states. In the `onUserInput` function, update the `nextState`
+We now add the new intermediate helper states. In the `onUserInput` function, update the `nextState`
 assignment so it uses the new states.
 
 In the `onFrame` function we are going to output new commands as well, so we assign those in the
-`let` block. At first we have to make sure, that the music is not `Nothing`. (It won't compile if
+`let` block. At first we have to make sure that the music is not `Nothing`. (It won't compile if
 this check was missing.) +
-In the `Starting` state the music is played from the beginning. The `startAt` value is a `Maybe` as
+In the `Starting` state, the music is played from the beginning. The `startAt` value is a `Maybe` as
 well so we have to use `Just 0` here.
 The other states should be self-explanatory.
 
@@ -135,7 +136,7 @@ The other states should be self-explanatory.
 
 The update method needs to handle the new states. When the `MusicLoaded` message arrives,
 the game state is set to `NewGame` and the music is stored in the model. +
-In case of an error we just throw it.
+In case of an error, we add another line of programming.
 
 // update
 {% codesnippet "https://raw.githubusercontent.com/macrozone/elm-hexagon-tutorial/chapter/music/src/Hexagon.elm", lines="302:314" %}{% endcodesnippet %}
@@ -149,7 +150,7 @@ commands.
 
 
 ## Bass pump
-The playing field should pump in sync with the beat. Therefore we have to define
+The playing field should pump in sync with the beat. Therefore, we have to define
 the speed of the track and the sections where there is a bass part.
 
 Add three variables for beat, amplitude and phase:
@@ -198,7 +199,7 @@ hasBass time =
   else False
 ----
 
-For the original track use those values:
+For the original track use these values:
 
 [source,elm]
 ----
@@ -236,15 +237,15 @@ The `beatPhase` value is used to adjust the timing so it matches with the music.
 {% codesnippet "https://raw.githubusercontent.com/macrozone/elm-hexagon-tutorial/chapter/music/src/Hexagon.elm", lines="103:105" %}{% endcodesnippet %}
 
 The center hole is always pulsating but it should be in sync with the rest of the
-stage during a bass sequence. For that we adjust the `makeCenterHole` function.
-Whenever there is a bass sequence the radius of the center piece should remain constant
+stage during a bass sequence. For that effect we adjust the `makeCenterHole` function.
+Whenever there is a bass sequence the radius of the center hole should remain constant, or
 otherwise it should be pumping.
 
 // makeCenterHole
 {% codesnippet "https://raw.githubusercontent.com/macrozone/elm-hexagon-tutorial/chapter/music/src/Hexagon.elm", lines="389:404" %}{% endcodesnippet %}
 
 That was the last piece of the puzzle. Now it is time to test it out. The music should start
-playing when the game starts. The stage starts pumping after 21 around seconds.
+playing when the game starts. The stage starts pumping after 21 seconds.
 
 If something is not working, compare your code with the full source code
 https://github.com/macrozone/elm-hexagon-tutorial/blob/chapter/music/src/Hexagon.elm[here].