bump V3

docs/reference/music/making-melodies.md

@@ -6,9 +6,11 @@ Composing some sound, or maybe some music, is done by putting tones to together,
 
 A _note_ is a tone that is recognized as part of music. A note has a name like '**C**'. A note is played for an amount of time called its _duration_. 
 
-On your @boardname@, a note is played on the speaker by sending a signal to a it with a certain _frequency_ called [Hertz](http://wikipedia.org/Hertz). Frequency is how fast something vibrates during one second. If you ring a bell that was made to play an '**A**' note, the bell will vibrate at 440 Hertz (440 times per second). So, notes are just certain frequencies that have special names.
+On your @boardname@, a note is played on the speaker by sending a signal to it with a certain _frequency_ called [Hertz](http://wikipedia.org/Hertz). Frequency is how fast something vibrates during one second. If you ring a bell that was made to play an '**A**' note, the bell will vibrate at 440 Hertz (440 times per second). So, notes are just certain frequencies that have special names.
 
-## ~ hint
+### ~ hint
+
+#### Listen to music with headphones
 
 Watch this video to see how speakers and headphones make sound when connected to your @boardname@.
 
@@ -24,7 +26,7 @@ Basic notes have names that use one of the first nine letters of the alphabet. T
 
 ``|A|``, ``|B|``, ``|C|``, ``|D|``, ``|E|``, ``|F|``, ``|G|``
 
-Ther are other notes named like the basic notes but have extra parts to the name called _sharp_ and _flat_. These other notes are just a bit different from the basic notes and have frequencies a little higher or lower than the basic note. This makes music a little more complicated but much more interesting!
+There are other notes named like the basic notes but have extra parts to the name called _sharp_ and _flat_. These other notes are just a bit different from the basic notes and have frequencies a little higher or lower than the basic note. This makes music a little more complicated but much more interesting!
 
 Some of these other notes look like:
 
@@ -32,6 +34,14 @@ Some of these other notes look like:
 
 When a small amount music or even a song is written down it is called [sheet music](https://wikipedia.org/wiki/Sheet_music).
 
+### ~ hint
+
+#### Note names in different languages
+
+Many languages other than English use different names for some or all of the musical notes. MakeCode uses English for names in code.
+
+### ~
+
 ## Sounds and music in code
 
 Of course, we can't use written music in our code. We can make music another way. The way to do it is to put names of notes in [strings](/types/string). We make our notes using letters, symbols, and numbers. The notes of a melody are put together in an array like:
@@ -51,13 +61,13 @@ What you see here is not some alien language but a bunch of notes with their dur
 You might notice that the sound string has an ``'R:1'`` in it. The '**R**` means _rest_ and to rest for one beat. A rest is a pause, or a time of silence, in the sound.
 
 
-#### ~ hint
+### ~ hint
 
-**Duration**
+#### Duration
 
 The amount of time a note is played (duration) is measured as _beats_. The standard number _beats per minute_ (bpm) in music is 120 bpm which is one-half of a second of time. A _whole_ note lasts for 4 beats and a _quarter_ note takes just one beat.
 
-#### ~
+### ~
 
 ## Example
 

docs/reference/music/on-event.md

@@ -43,7 +43,7 @@ music.onEvent(MusicEvent.BackgroundMelodyResumed, () => {
 music.onEvent(MusicEvent.BackgroundMelodyRepeated, () => {
     serial.writeLine("background repeated")
 })
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.A, () => {
     music.beginMelody(music.builtInMelody(Melodies.BaDing), MelodyOptions.Once)
 })
 music.setTempo(100)
@@ -56,7 +56,7 @@ The events related to background melody get triggered by a melody that is played
 
 ```
 control.inBackground(function () {
-    basic.pause(Math.randomRange(0, 5000))
+    basic.pause(randint(0, 5000))
     music.beginMelody(music.builtInMelody(Melodies.Entertainer), MelodyOptions.Once)
 })
 music.onEvent(MusicEvent.BackgroundMelodyStarted, function () {

docs/reference/music/set-play-tone.md

@@ -17,7 +17,7 @@ This example send the frequency and duration over radio
 and plays it on the remote @boardname@.
 
 ```typescript
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.A, () => {
     music.playTone(440, 120)
     led.toggle(0, 0)
 })
@@ -26,7 +26,7 @@ radio.onReceivedNumber(function (receivedNumber) {
     const duration = receivedNumber & 0xffff;
     music.playTone(freq, duration);
 })
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.B, () => {
     music.setPlayTone((frequency: number, duration: number) => {
         radio.sendNumber((frequency << 16) | (duration & 0xffff));
     })    

docs/reference/music/set-volume.md

@@ -0,0 +1,35 @@
+# set Volume
+
+Set the volume for the sound synthesizer.
+
+```sig
+music.setVolume(128)
+```
+
+### ~hint
+
+#### Simulator
+
+``||music:set volume||`` works on the @boardname@. It might not work in the simulator on every browser.
+
+### ~
+
+## Parameters
+
+* ``volume``: the volume of of the sounds played to the sound output. The volume [number](/types/number) can be between `0` for silent and `255` for the loudest sound.
+
+## Example #example
+
+Set the synthesizer volume to something quieter.
+
+```blocks
+music.setVolume(50)
+```
+
+## See also
+
+[volume](/reference/music/volume)
+
+```package
+music
+```

docs/reference/music/start-melody.md

@@ -0,0 +1,64 @@
+# start Melody
+
+Start playing a musical melody through pin ``P0`` of the @boardname@.
+
+```sig
+music.startMelody(music.builtInMelody(Melodies.Entertainer), MelodyOptions.Once)
+```
+
+## ~ hint
+
+**Simulator**: This function only works on the @boardname@ and in some browsers.
+
+## ~
+
+There are built-in melodies that you can choose from the ``||start melody||`` block. These are already composed for you and are easy to use by just selecting the one you want. If you want to play your own melody, you can [compose](/reference/music/making-melodies) one and use it instead of one of the built-in ones.
+
+Melodies are a sequence of notes, each played for some small amount time, one after the other. The notes in a melody are held in an [array](/types/array) of [strings](/types/string). Each string in the array is a note of the melody. You make a melody by assembling the notes along with the _duration_ that the note plays for. The melody is [formed](/reference/music/making-melodies) like this:
+
+``NOTE[octave][:duration] eg: ['g5:1']``
+
+```block
+music.startMelody(['g4:1', 'c5', 'e', 'g:2', 'e:1', 'g:3'], MelodyOptions.Once)
+```
+
+Melodies are played either in the _foreground_ or _background_. This allows more than one melody to be active at once. If a melody is set to play in the background, it can be interrupeted, or paused, temporarily while a melody set for the foreground is played. If the foreground melody is not set to play ``forever``, then the background melody resumes when the foreground melody is finished.
+
+You can set options for how you want the melody to play. You can ask that the melody plays just one time, ``once``, or have it keep repeating, ``forever``. With these options the melody will play in the foreground either once or continue to repeat. Of course, if you set ``forever``, any melody that was started in background will never play unless you [stop](/reference/music/stop-melody) the foreground melody. To make a background melody, set the option to ``once in background`` or ``forever in background``.
+
+## Parameters
+
+* **melody**: A built-in melody or an [array](/types/array) representation of a [melody](reference/music/making-melodies) you wish to play.
+* **options**: the play option for the melody:
+>* ``once``: play the melody in the foreground one time
+>* ``forever``: play the melody in the foreground and keep repeating it
+>* ``once in background``: play the melody in the background one time
+>* ``forever in background``: play the melody in the background and keep repeating it
+
+## Examples
+
+### Play the "Entertainer"
+
+This example plays the ``Entertainer`` built-in melody.
+
+```blocks
+music.startMelody(music.builtInMelody(Melodies.Entertainer), MelodyOptions.Once)
+```
+
+### Play a composed melody forever
+
+Play a made-up melody in the background forever.
+
+```blocks
+music.startMelody(['g4:1', 'c5', 'e', 'g:2', 'e:1', 'g:3'], MelodyOptions.ForeverInBackground)
+```
+
+## See also
+
+[stop melody](/reference/music/stop-melody), [play tone](/reference/music/play-tone),
+[rest](/reference/music/rest), [ring tone](/reference/music/ring-tone),
+[tempo](/reference/music/tempo), [set tempo](/reference/music/set-tempo),
+[change tempo by](/reference/music/change-tempo-by)
+
+[Making Melodies](/reference/music/making-melodies)
+

docs/reference/music/volume.md

@@ -0,0 +1,27 @@
+# volume
+
+Get the current volume level of the sound synthesizer.
+
+```sig
+music.volume()
+```
+
+### ~hint
+
+#### Simulator
+
+Using ``||music:volume||`` works on the @boardname@. It might not work in the simulator on every browser.
+
+### ~
+
+## Returns
+
+* a [number](/types/number) that is the current volume level of output from the sound synthesizer. The value can be between `0` for silent and `255` for the loudest sound.
+
+## See also
+
+[set volume](/reference/music/set-volume)
+
+```package
+music
+```