Update music api reference for playable and sound effect apis (#1457)

* add jsdoc descriptions for playable api

* update sound effect api help paths

* add sound effect reference pages

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

@@ -0,0 +1,68 @@
+# 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 effect](/types/sound-effect)** 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 effect](/types/sound-effect) object and can then be [played](/reference/music/play) 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 [soundEffect](/types/sound-effect) object with the the desired sound effect parameters.
+
+## Examples
+
+### Sine wave sound
+
+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)
+```
+
+### Complex waveform sound
+
+Create a `triangle` wave sound expression with `vibrato` and a `curve` interpolation. Play the sound until it finishes.
+
+```typescript
+let mySound = music.createSoundEffect(
+    WaveShape.Triangle,
+    1000,
+    2700,
+    255,
+    255,
+    500,
+    SoundExpressionEffect.Vibrato,
+    InterpolationCurve.Curve
+    )
+music.playSoundEffect(mySound, SoundExpressionPlayMode.UntilDone)
+```
+
+## See also
+
+[play](/reference/music/play)

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

@@ -0,0 +1,59 @@
+# 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.
+
+You can also play [built-in sound effects](/reference/music/builtin-sound-effect) like `giggle`, `happy`, or `twinkle`.
+
+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`.
+
+## Examples
+
+### Simple waveform sound
+
+Play the sound effect from a sine wave sound expression for `1` second.
+
+```blocks
+music.playSoundEffect(music.createSoundEffect(WaveShape.Sine, 2000, 0, 1023, 0, 1000, SoundExpressionEffect.None, InterpolationCurve.Linear), SoundExpressionPlayMode.UntilDone)
+```
+
+### Complex waveform sound
+
+Play a `triangle` wave sound effect with `vibrato` and a `curve` interpolation.
+
+```typescript
+music.playSoundEffect(music.createSoundEffect(
+    WaveShape.Triangle,
+    1000,
+    2700,
+    255,
+    255,
+    500,
+    SoundExpressionEffect.Vibrato,
+    InterpolationCurve.Curve
+    ), SoundExpressionPlayMode.UntilDone)
+```
+
+## See also
+
+[create sound effect](/reference/music/create-sound-effect)

libs/mixer/docs/reference/music/play.md

@@ -1,6 +1,6 @@
 # play
 
-Play a song, melody, or tone from a playable music source.
+Play a song, melody, tone, or a sound effect from a playable music source.
 
 ```sig
 music.play(music.createSong(hex`00780004080200`), music.PlaybackMode.UntilDone)
@@ -121,6 +121,13 @@ sprites.onOverlap(SpriteKind.Player, SpriteKind.Enemy, function (sprite, otherSp
     music.play(music.melodyPlayable(music.zapped), music.PlaybackMode.UntilDone)
 })
 ```
+### Play a sound effect
+
+Play a sine wave sound effect for `5` seconds.
+
+```blocks
+music.play(music.createSoundEffect(WaveShape.Sine, 5000, 0, 255, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear), music.PlaybackMode.UntilDone)
+```
 
 ## See also #seealso
 
@@ -129,4 +136,5 @@ sprites.onOverlap(SpriteKind.Player, SpriteKind.Enemy, function (sprite, otherSp
 [melody playable](/reference/music/melody-playable),
 [create song](/reference/music/create-song),
 [stop all sounds](/reference/music/stop-all-sounds),
-[song editor](/reference/music/song-editor)
+[song editor](/reference/music/song-editor),
+[create sound effect](/reference/music/create-sound-effect)

libs/mixer/docs/reference/music/randomize-sound.md

@@ -0,0 +1,30 @@
+# randomize Sound
+
+Make a new sound similar to the original one but with some variations.
+
+```sig
+music.randomizeSound(music.createSoundEffect(WaveShape.Sine, 5000, 0, 255, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear))
+```
+
+The resulting sound effect will randomize some of the parameters of the original sound effect to create differences from the original sound.
+
+## Parameters
+
+* **sound**: the original [sound-effect](/types/sound-effect).
+
+## Returns
+
+* a new [sound-effect](/types/sound-effect) with some differences from the oringal **sound**.
+
+## Example
+
+Randomize and play a sine wave sound effect.
+
+```blocks
+music.play(music.randomizeSound(music.createSoundEffect(WaveShape.Sine, 5000, 0, 255, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear)), music.PlaybackMode.UntilDone)
+```
+
+## See also
+
+[play](/reference/music/play),
+[create sound effect](/reference/music/create-sound-effect)

libs/mixer/docs/types/sound-effect.md

@@ -0,0 +1,136 @@
+# sound Effect
+
+A **sound effect** is a data object that is created from a sound expression. A sound expression is group of parameters that define a sound, such as wave shape, sound volume, frequency, and duration.
+
+A sound is generated from an expression based on a fundamental wave shape, or waveform. To make a sound wave, the sound data must change from a high peak to a low trough over a period of time and repeat. The peaks and troughs are the positive amplitudes and negative amplitudes of the wave across the zero line. The volume controls the amplitude of the wave.
+
+When the sound is played on a speaker or headphones, the vibrations create the pressures our ears detect as sound.
+
+### ~ hint
+
+#### Sounds and Sound Expressions
+
+In code, a **sound effect** type is a complex data object that includes data for all the elements that represent a sound. This includes information about the frequencies and volumes at various points in time for the duration of the sound. A **SoundExpression** is another data type that helps create a **sound effect**. It has the elements of how to make the sound. Many of them you specify when you edit a sound.
+
+Code for creating and playing a sound from a sound expression could look like this:
+
+```typescript-ignore
+let mySound = music.createSoundEffect(WaveShape.Sine, 2000, 0, 1023, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear)
+music.playSoundEffect(mySound, SoundExpressionPlayMode.UntilDone)
+```
+
+### ~
+
+## Sound Editing
+
+When you click on the waveform in the ``||music:play sound||`` block, the sound editor will display. The sound editor defines the sound expression parameter with choices for the **waveform**, sound **duration** time, **frequency** range, **volume** range, **effect**, and **interpolation**.
+
+![Sound Editor](/static/types/sound/sound-editor.png)
+
+Both the frequency and volume can start and end with different values across the duration of the sound.
+
+## Wave shape
+
+The wave shape is chosen to create a natural sound or a synthetic sound. Some wave shapes can also serve to generate signals when played to a pin instead of a speaker or headphones.
+
+### Sine wave
+
+The waveform that matches natural sound is the sine wave. This is the wave type in music and voice.
+
+![Sine wave](/static/types/sound/sine-wave.png)
+
+### Sawtooth wave
+
+A sawtooth wave has a vertical rising edge and a linear falling edge. It's shape looks like the teeth on a saw.
+
+![Sawtooth wave](/static/types/sound/sawtooth-wave.png)
+
+### Triangle wave
+
+The triangle wave is has symmetrical a rising and a falling edge. It makes the shape of triangles in the waveform.
+
+![Triangle wave](/static/types/sound/triangle-wave.png)
+
+### Square wave
+
+A square wave has both verical rising and falling edges with a flat section on the top and bottom. The flat sections match the volume set for the sound. Square waves are sometimes used to represent digital data and will make an "electronic" sound.
+
+![Square wave](/static/types/sound/square-wave.png)
+
+### Noise wave
+
+The noise wave is created using random frequenices and volume. Setting the frequency parameters for the sound expression creates a "tuning" range for the noise sound effect.
+
+![Noise wave](/static/types/sound/noise-wave.png)
+
+## Duration
+
+The sound has a length of time that it plays for. This is set as a number of milliseconds (**ms**).
+
+## Volume
+
+The volume controls the loudness (amplitude) of the sound. The sound can start with one volume setting and end with another. It can begin loud and end quiet, or the other way around. The volume control has start and end points that can be adjusted higher and lower. Grab them and move them up or down.
+
+### High to low
+
+![Volume from high to low](/static/types/sound/volume-hilo.png)
+
+### Low to High
+
+![Volume from low to high](/static/types/sound/volume-lohi.png)
+
+### Constant volume
+
+![Constant volume](/static/types/sound/volume-constant.png)
+
+## Frequency
+
+Frequency is how fast a wave repeats itself from the zero line to its peak down to its trough and back to the zero line. If it does this 1000 times in one second then the frequency has 1000 cycles per second and is measured in units of Hertz (1000 Hz). The frequency of the sound at any point in time is its current _pitch_. Musical notes and parts of speech are different frequecies that last for short periods of time in a sound.
+
+A sound expression has both a starting frequency and an ending frequecy. The frequency can start low and end high, start high and end low, or remain the same for the duration of the sound.
+
+### High to low
+
+![Frequency from high to low](/static/types/sound/freq-hilo.png)
+
+### Low to High
+
+![Frequency from low to high](/static/types/sound/freq-lohi.png)
+
+### Effect
+
+Effects add small changes to the waveform but can make a big change in how it sounds to a listener. There are a few effects available to apply to a sound.
+
+* **Tremolo**: add slight changes in volume of the sound expression.
+
+>![Tremolo effect setting](/static/types/sound/effect-tremolo.png)
+
+* **Vibrato**: add slight changes in frequency to the sound expression.
+
+>![Vibrato effect setting](/static/types/sound/effect-vibrato.png)
+
+* **Warble**: similar to Vibrato but with faster variations in the frequency changes.
+
+>![Warble effect setting](/static/types/sound/effect-warble.png)
+
+### Interpolation
+
+Interpolation is how the sound expression will make the changes in frequency or volume of the sound. These changes can occur at a constant rate along duration of the sound or more suddenly at the beginning.
+
+* **Linear**: The change in frequency is constant for the duration of the sound.
+
+>![Frequency from low to high](/static/types/sound/interp-linear.png)
+
+* **Curve**: The change in frequency is faster at the beginning of the sound and slows toward the end.
+
+>![Frequency from low to high](/static/types/sound/interp-curve.png)
+
+* **Logarithmic**: The change in frequency is rapid during the very first part of the sound.
+
+
+>![Frequency from low to high](/static/types/sound/interp-log.png)
+
+## See also
+
+[play sound effect](/reference/music/play-sound-effect),
+[create sound effect](/reference/music/create-sound-effect)

libs/mixer/playable.ts

@@ -104,6 +104,12 @@ namespace music {
         }
     }
 
+    /**
+     * Play a song, melody, or other sound. The music plays until finished or can play as a
+     * background task.
+     * @param toPlay the song or melody to play
+     * @param playbackMode play the song or melody until it's finished or as background task
+     */
     //% blockId="music_playable_play"
     //% block="play $toPlay $playbackMode"
     //% toPlay.shadow=music_melody_playable
@@ -113,6 +119,10 @@ namespace music {
         toPlay.play(playbackMode);
     }
 
+    /**
+     * Create a Playable object for a melody.
+     * @param melody the melody to make playable
+     */
     //% blockId="music_melody_playable"
     //% block="sound $melody"
     //% toolboxParent=music_playable_play
@@ -125,7 +135,10 @@ namespace music {
         return new MelodyPlayable(melody);
     }
 
-
+    /**
+     * Create a Playable object for a melody string containg notes.
+     * @param melody the melody string to make playable
+     */
     //% blockId="music_string_playable"
     //% block="melody $melody at tempo $tempo|(bpm)"
     //% toolboxParent=music_playable_play
@@ -165,6 +178,11 @@ namespace music {
         return new MelodyPlayable(new Melody(formattedMelody));
     }
 
+    /**
+     * Create a Playable object for a single tone and its duration.
+     * @param note the note or tone frequency to play
+     * @param duration the duration of the tone in milliseconds (ms)
+     */
     //% blockId="music_tone_playable"
     //% block="tone $note for $duration"
     //% toolboxParent=music_playable_play

libs/mixer/soundEffect.ts

@@ -284,7 +284,7 @@ namespace music {
     //% blockId=soundExpression_generateSimilarSound
     //% block="randomize $sound"
     //% sound.shadow=soundExpression_createSoundEffect
-    //% weight=0 help=music/generate-similar-sound
+    //% weight=0 help=music/randomize-sound
     //% blockGap=8
     //% group="Sounds"
     export function randomizeSound(sound: SoundEffect) {