Updates for V4 (#197)

* update yotta defaults for 16kb devices

* refactor deprecated blocks

* updates for button events

* update button events

* update refference

* update docs

* update docs

* update button event blocks

* update docs

* update block id

docs/reference/music/begin-melody.md

@@ -22,7 +22,7 @@ Melodies are a sequence of notes, each played for some small amount time, one af
 music.beginMelody(['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 interrupted, 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.
+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``.
 

docs/reference/music/builtin-sound-effect.md

@@ -0,0 +1,40 @@
+# builtin Sound Effect
+
+Get a sound expression string for a built-in sound effect.
+
+```sig
+music.builtinSoundEffect(soundExpression.giggle)
+```
+
+A collection of built-in sound effects are available as sound expressions. You choose one by selecting the name of the effect
+
+## Parameters
+
+* **soundExpression**: A sound expression name. The available effects are:
+>* `giggle`
+>* `happy`
+>* `hello`
+>* `mysterious`
+>* `sad`
+>* `slide`
+>* `soaring`
+>* `spring`
+>* `twinkle`
+>* `yawn`
+
+## Returns
+
+* a [sound](/types/sound) expression [string](/types/string) with the the named sound effect.
+
+## Example
+
+Play the built-in sound effect for `giggle`.
+
+```blocks
+music.playSoundEffect(music.builtinSoundEffect(soundExpression.giggle), SoundExpressionPlayMode.UntilDone)
+```
+
+## See also
+
+[play sound effect](/reference/music/play-sound-effect),
+[create sound effect](/reference/music/create-sound-effect)

docs/reference/music/create-sound-effect.md

@@ -0,0 +1,48 @@
+# create Sound Effect
+
+Create a sound expression string for a sound effect.
+
+```sig
+music.createSoundEffect(WaveShape.Sine, 2000, 0, 1023, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear)
+```
+
+A sound expression is set of parameters that describe a **[Sound](/types/sound)** that will last for some amount of time. These parameters specify a base waveform, frequency range, sound volume, and effects. Sound data is created as a [Sound](/types/sound) object and can then be [played](/reference/music/play-sound-effect) to the speaker, headphones, or at an output pin.
+
+## Parameters
+
+* **waveShape**: the primary shape of the waveform:
+>* `sine`: sine wave shape
+>* `sawtooth`: sawtooth wave shape
+>* `triangle`: triangle wave shape
+>* `square`: square wave shape
+>* `noise`: random noise generated wave shape
+* **startFrequency**: a [number](/types/number) that is the frequency of the waveform when the sound expression starts.
+* **endFrequency**: a [number](/types/number) that is the frequency of the waveform when the sound expression stops.
+* **startVolume**: a [number](/types/number) the initial volume of the sound expression.
+* **endVolume**: a [number](/types/number) the ending volume of the sound expression.
+* **duration**: a [number](/types/number) the duration in milliseconds of the sound expression.
+* **effect**: an effect to add to the waveform. These are:
+>* `tremolo`: add slight changes in volume of the sound expression.
+>* `vibrato`: add slight changes in frequency to the sound expression.
+>* `warble`: similar to `vibrato` but with faster variations in the frequency changes.
+* **interpolation**: controls the rate of frequency change in the sound expression.
+>* `linear`: the change in frequency is constant for the duration of the sound.
+>* `curve`: the change in frequency is faster at the beginning of the sound and slows toward the end.
+>* `logarithmic`: the change in frequency is rapid during the very first part of the sound.
+
+## Returns
+
+* a [sound](/types/sound) expression [string](/types/string) with the the desired sound effect parameters.
+
+## Example
+
+Create a sound expression string and assign it to a variable. Play the sound for the sound expression.
+
+```blocks
+let mySound = music.createSoundEffect(WaveShape.Sine, 2000, 0, 1023, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear)
+music.playSoundEffect(mySound, SoundExpressionPlayMode.UntilDone)
+```
+
+## See also
+
+[play sound effect](/reference/music/play-sound-effect), [built-in sound effect](/reference/music/builtin-sound-effect)

docs/reference/music/note-frequency.md

@@ -0,0 +1,31 @@
+# note Frequency
+
+Get the frequency of a musical note.
+
+```sig
+music.noteFrequency(Note.C)
+```
+
+## Parameters
+
+* ``name`` is the name of the **Note** you want a frequency value for.
+
+## Returns
+
+* a [number](/types/number) that is the frequency (in [Hertz](https://wikipedia.org/wiki/Hertz))
+of a note you chose.
+
+## Example #example
+
+Play a 'C' note for one second, rest for one second, and then play an 'A' note for one second.
+
+```blocks
+music.playTone(music.noteFrequency(Note.C), 1000)
+music.rest(1000)
+music.playTone(music.noteFrequency(Note.A), 1000)
+```
+## See also #seealso
+
+[play tone](/reference/music/play-tone), [ring tone](/reference/music/ring-tone),
+[rest](/reference/music/rest), [tempo](/reference/music/tempo),
+[change tempo by](/reference/music/change-tempo-by)

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.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     music.beginMelody(music.builtInMelody(Melodies.BaDing), MelodyOptions.Once)
 })
 music.setTempo(100)

docs/reference/music/play-melody.md

@@ -0,0 +1,38 @@
+# play Melody
+
+Play a short melody of notes composed in a string.
+
+```sig
+music.playMelody("", 120);
+```
+
+The melody is short series of notes composed in a string. The melody is played at a rate set by the **tempo** value you give. The melody string contains a sequence of notes formatted like this:
+
+``"E B C5 A B G A F "``
+
+The melody is shown in the ``||music:play melody||`` block as note symbols which also appear in the Melody Editor.
+
+```block
+music.playMelody("E B C5 A B G A F ", 120);
+```
+
+The melodies are most often created in the Melody Editor from the block so that valid notes are chosen and the correct melody length is set.
+
+## Parameters
+
+* **melody**: a [string](/types/string) which contains the notes of the melody.
+* **tempo**: a [number](/types/number) which is the rate to play the melody at in beats per minute.
+
+## Example #example
+
+Play the ``Mystery`` melody continuously.
+
+```blocks
+basic.forever(function () {
+    music.playMelody("E F G F E G B C5 ", 120)
+})
+```
+
+## See also #seealso
+
+[set tempo](/reference/music/set-tempo), [play](/reference/music/play), [play until done](/reference/music/play-until-done)

docs/reference/music/play-sound-effect.md

@@ -0,0 +1,40 @@
+# play Sound Effect
+
+Play a sound that is generated from a sound expression.
+
+```sig
+music.playSoundEffect("", SoundExpressionPlayMode.UntilDone)
+```
+
+This will play a **[Sound](/types/sound)** object created from a sound expression. The sound will play for the duration that was set in the sound expression. The sound can play on the speaker or at a pin that is set for sound output.
+
+Your program can wait for the sound to finish before it runs its next step. To do this, set the play mode to `until done`. Otherwise, use `background` for the program to continue immediately after the sound starts.
+
+### ~ reminder
+
+#### Works with micro:bit V2
+
+![works with micro:bit V2 only image](/static/v2/v2-only.png)
+
+This block requires the [micro:bit V2](/device/v2) hardware. If you use this block with a micro:bit v1 board, you will see the **927** error code on the screen.
+
+### ~
+
+## Parameters
+
+* **sound**: a [string](/types/string) that is the sound expression for the sound you want to play.
+* **mode**: the play mode for the sound, either `until done` or `background`.
+
+## Example
+
+Play a sound from a sound expression for `1` second.
+
+```blocks
+music.playSoundEffect(music.createSoundEffect(WaveShape.Sine, 2000, 0, 1023, 0, 1000, SoundExpressionEffect.None, InterpolationCurve.Linear), SoundExpressionPlayMode.UntilDone)
+```
+
+## See also
+
+[create sound effect](/reference/music/create-sound-effect),
+[built-in sound effect](/reference/music/builtin-sound-effect),
+[analog set pitch pin](/reference/pins/analog-set-pitch-pin)

docs/reference/music/play-until-done.md

@@ -0,0 +1,44 @@
+# play Until Done
+
+Play a sound expression until it finishes.
+
+```sig
+soundExpression.giggle.playUntilDone()
+```
+
+A sound expression is a preformatted set of tones that create a certain sound. There are several sounds to choose from. The sound is started and your program waits until the sound stops playing.
+
+### ~ reminder
+
+![works with micro:bit V2 only image](/static/v2/v2-only.png)
+
+This block requires the [micro:bit V2](/device/v2) hardware. If you use this block with a micro:bit v1 board, you will see the **927** error code on the screen.
+
+### ~
+
+## Parameters
+
+In blocks, the sound is selected from the list in the ``||music:play sound until done||`` block.
+
+```block
+soundExpression.giggle.playUntilDone()
+```
+
+When coding in JavaScript or Python, the sound is a ``soundExpression`` object which from which you run the ``playUntilDone()`` function from. For example, to play the ``soaring`` sound, select ``soaring`` from the ``soundExpression`` namespace and run ``playUntilDone()``:
+
+```typescript
+soundExpression.soaring.playUntilDone()
+```
+
+## Example
+
+Play the ``twinkle`` sound on the speaker and wait until it finishes.
+
+```blocks
+soundExpression.twinkle.playUntilDone()
+basic.showString("twinkle has stopped")
+```
+
+## See also
+
+[play](/reference/music/play)

docs/reference/music/play.md

@@ -0,0 +1,43 @@
+# play
+
+Play a sound expression.
+
+```sig
+soundExpression.giggle.play()
+```
+
+A sound expression is a preformatted set of tones that create a certain sound. There are several sounds to choose from. The sound is started and your program then continues.
+
+### ~ reminder
+
+![works with micro:bit V2 only image](/static/v2/v2-only.png)
+
+This block requires the [micro:bit V2](/device/v2) hardware. If you use this block with a micro:bit v1 board, you will see the **927** error code on the screen.
+
+### ~
+
+## Parameters
+
+In blocks, the sound is selected from the list in the ``||music:play sound||`` block.
+
+```block
+soundExpression.giggle.play()
+```
+
+When coding in JavaScript or Python, the sound is a ``soundExpression`` object which from which you run the ``play()`` function from. For example, to play the ``soaring`` sound, select ``soaring`` from the ``soundExpression`` namespace and run ``play()``:
+
+```typescript
+soundExpression.soaring.play()
+```
+
+## Example
+
+Play the ``twinkle`` sound on the speaker.
+
+```blocks
+soundExpression.twinkle.play()
+```
+
+## See also
+
+[play until done](/reference/music/play-until-done)

docs/reference/music/set-built-in-speaker-enabled.md

@@ -0,0 +1,37 @@
+# set Built In Speaker Enabled
+
+Enable the speaker on the @boardname@ to play music and sounds.
+
+```sig
+music.setBuiltInSpeakerEnabled(false)
+```
+
+The microbit v2 has a speaker on the board itself. You can enable the built-in speaker to play sounds instead having them an external speaker connected to the pitch pin.
+
+### ~ reminder
+
+![works with micro:bit V2 only image](/static/v2/v2-only.png)
+
+This block requires the [micro:bit V2](/device/v2) hardware. If you use this block with a micro:bit v1 board, you will see the **927** error code on the screen.
+
+### ~
+
+## Parameters
+
+* **enabled**: a [boolean](/types/boolean) value that is ``true`` to enable the built-in speaker, or ``false`` to send sounds to the pitch pin.
+
+## Example #example
+
+Enable the built-in speaker play sounds.
+
+```blocks
+music.setBuiltInSpeakerEnabled(true)
+```
+
+## See also
+
+[analog-set-pitch-pin](/reference/pins/analog-set-pitch-pin)
+
+```package
+music
+```

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.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     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.onButtonEvent(Button.B, input.buttonEventClick(), () => {
     music.setPlayTone((frequency: number, duration: number) => {
         radio.sendNumber((frequency << 16) | (duration & 0xffff));
     })    

docs/reference/music/set-silence-level.md

@@ -0,0 +1,40 @@
+# set Silence Level
+
+Set the level for audio pin output during periods of silence.
+
+```sig
+music.setSilenceLevel(1000)
+```
+
+### ~ reminder
+
+![works with micro:bit V2 only image](/static/v2/v2-only.png)
+
+This function requires the [micro:bit V2](/device/v2) hardware. If you use this function with a micro:bit v1 board, you will see the **927** error code on the screen.
+
+### ~
+
+Normally the output signal level at the audio pin is `0` when no sounds are playing. This is the silence level and it stays constant since actual tones have varying levels over a period of time. Some devices (headphones, external speakers, etc.) which are sensitive to slight signal changes might play sounds from signal noise encountered along the connection between the audio pin and the audio device. 
+
+To reduce the effect of this signal noise it can be helpful to set an constant signal level for silence that is greater than `0`.
+
+## Parameters
+
+* **level**: a [number](/types/number) between `0` and `1024` to use as the silence level for the audio pin output when no sounds are playing. The default level is `0`.
+
+## Example #example
+
+Set silence level to `512` for the current audio pin.
+
+```typescript
+pins.setAudioPin(AnalogPin.P1)
+music.setSilenceLevel(512)
+```
+
+## See also
+
+[volume](/reference/music/volume), [set audio pin](/reference/pins/set-audio-pin)
+
+```package
+music
+```

docs/reference/music/stop-all-sounds.md

@@ -0,0 +1,34 @@
+# stop All Sounds
+
+Stop all the sounds that are playing right now and any others waiting to play.
+
+```sig
+music.stopAllSounds()
+```
+
+If you play sounds or sound effects more than once, the sounds you asked to play later have to wait until the sounds played earlier finish. You can stop the sound that is playing now and all the sounds waiting to play with ``||music:stop all sounds||``.
+
+## #simnote
+
+### ~hint
+
+#### Simulator
+
+``||music:stop all sounds||`` works on the @boardname@. It might not work in the simulator on every browser.
+
+### ~
+
+## Example #example
+
+Play a tone but stop it right away.
+
+```blocks
+let freq = music.noteFrequency(Note.C);
+music.playTone(freq, 1000)
+music.stopAllSounds()
+```
+
+## See also #seealso
+
+[play melody](/reference/music/play-melody), [play](/reference/music/play),
+[play tone](/reference/music/play-tone)