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
This commit is contained in:
Juri Wolf
2022-08-10 18:36:19 +02:00
committed by GitHub
parent 32783f38ba
commit 5f7a8e5301
107 changed files with 1218 additions and 706 deletions

View File

@ -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``.

View File

@ -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)

View File

@ -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)

View File

@ -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)

View File

@ -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)

View File

@ -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)

View File

@ -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)

View File

@ -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)

View File

@ -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)

View File

@ -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
```

View File

@ -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));
})

View File

@ -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
```

View File

@ -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)