2.1.28, initiation update to PXT v5.28.24 (#54)
This commit is contained in:
Amerlander
committed by
Peli de Halleux
Peli de Halleux
parent
38a964516e
commit
5c114a0c57
@ -2,21 +2,23 @@
|
||||
|
||||
Returns the duration of a beat in milli-seconds
|
||||
|
||||
## Simulator
|
||||
|
||||
This function only works on the @boardname@ and in some browsers.
|
||||
|
||||
```sig
|
||||
music.beat(BeatFraction.Whole)
|
||||
```
|
||||
|
||||
### Parameters
|
||||
## ~ hint
|
||||
|
||||
**Simulator**: This function only works on the @boardname@ and in some browsers.
|
||||
|
||||
## ~
|
||||
|
||||
## Parameters
|
||||
|
||||
* ``BeatFraction`` means fraction of a beat (BeatFraction.Whole, BeatFraction.Sixteenth etc)
|
||||
|
||||
### Returns
|
||||
## Returns
|
||||
|
||||
* a [number](/reference/types/number) that means the amount of milli-seconds a beat fraction represents.
|
||||
* a [number](/types/number) that means the amount of milli-seconds a beat fraction represents.
|
||||
|
||||
|
||||
## Example
|
||||
@ -25,6 +27,6 @@ music.beat(BeatFraction.Whole)
|
||||
music.playTone(Note.C, music.beat(BeatFraction.Quarter))
|
||||
```
|
||||
|
||||
### See also
|
||||
## See also
|
||||
|
||||
[play tone](/reference/music/play-tone), [ring tone](/reference/music/ring-tone), [rest](/reference/music/rest), [set tempo](/reference/music/set-tempo), [change tempo by](/reference/music/change-tempo-by)
|
||||
64
docs/reference/music/begin-melody.md
Normal file
64
docs/reference/music/begin-melody.md
Normal file
@ -0,0 +1,64 @@
|
||||
# begin Melody
|
||||
|
||||
Begin playing a musical melody through pin ``P0`` of the @boardname@.
|
||||
|
||||
```sig
|
||||
music.beginMelody(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.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 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.beginMelody(music.builtInMelody(Melodies.Entertainer), MelodyOptions.Once)
|
||||
```
|
||||
|
||||
### Play a composed melody forever
|
||||
|
||||
Play a made-up melody in the background forever.
|
||||
|
||||
```blocks
|
||||
music.beginMelody(['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)
|
||||
|
||||
@ -3,21 +3,23 @@
|
||||
Makes the [tempo](/reference/music/tempo) (speed of a piece of music)
|
||||
faster or slower by the amount you say.
|
||||
|
||||
## Simulator
|
||||
|
||||
This function only works on the @boardname@ and in some browsers.
|
||||
|
||||
```sig
|
||||
music.changeTempoBy(20)
|
||||
```
|
||||
|
||||
### Parameters
|
||||
## ~ hint
|
||||
|
||||
* ``bpm`` is a [number](/reference/types/number) that says how much to
|
||||
**Simulator**: This function only works on the @boardname@ and in some browsers.
|
||||
|
||||
## ~
|
||||
|
||||
## Parameters
|
||||
|
||||
* ``bpm`` is a [number](/types/number) that says how much to
|
||||
change the bpm (beats per minute, or number of beats in a minute of
|
||||
the music that the @boardname@ is playing).
|
||||
|
||||
### Examples
|
||||
## Examples
|
||||
|
||||
This program makes the music faster by 12 bpm.
|
||||
|
||||
@ -31,7 +33,7 @@ This program makes the music _slower_ by 12 bpm.
|
||||
music.changeTempoBy(-12)
|
||||
```
|
||||
|
||||
### See also
|
||||
## See also
|
||||
|
||||
[play tone](/reference/music/play-tone), [ring tone](/reference/music/ring-tone)
|
||||
|
||||
|
||||
74
docs/reference/music/making-melodies.md
Normal file
74
docs/reference/music/making-melodies.md
Normal file
@ -0,0 +1,74 @@
|
||||
# Making melodies
|
||||
|
||||
Composing some sound, or maybe some music, is done by putting tones to together, one after another. A _melody_ is a sequence of these tones each played, for some short amount of time, one after the other until all notes have played.
|
||||
|
||||
## Musical notes
|
||||
|
||||
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.
|
||||
|
||||
## ~ hint
|
||||
|
||||
Watch this video to see how speakers and headphones make sound when connected to your @boardname@.
|
||||
|
||||
https://www.youtube.com/watch?v=cxfPNc4Wefo
|
||||
|
||||
### ~
|
||||
|
||||
In history, music came from tones that seemed nice to hear. The tones were played on wood, strings, metal, and skins. These tones were given names and they became what we know today as musical notes. Notes were named so we could write them down and remember how to play them again later.
|
||||
|
||||
## How are notes named?
|
||||
|
||||
Basic notes have names that use one of the first nine letters of the alphabet. They are:
|
||||
|
||||
``|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!
|
||||
|
||||
Some of these other notes look like:
|
||||
|
||||
``|C#|``, ``|Eb|``
|
||||
|
||||
When a small amount music or even a song is written down it is called [sheet music](https://wikipedia.org/wiki/Sheet_music).
|
||||
|
||||
## 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:
|
||||
|
||||
```block
|
||||
let melody = ['E3:3', 'R:1', 'D#:3', 'R:1', 'D:4', 'R:1', 'C#:8']
|
||||
```
|
||||
|
||||
In JavaScript code, it looks like this:
|
||||
|
||||
```typescript
|
||||
let melody = ['E3:3', 'R:1', 'D#:3', 'R:1', 'D:4', 'R:1', 'C#:8']
|
||||
```
|
||||
|
||||
What you see here is not some alien language but a bunch of notes with their duration. The form of a single note is **note : duration** or ``'C:2'``. This means play the '**C**' note for **2** beats of time. The notes are placed one after the other, in an array, with a comma between them, like ``'B:2', 'C#:6'``. If you want a note to play for **4** beats, you don't need to use any duration number (a note with 4 beats is called a _whole_ note). Just say something like ``'E'`` with no colon (leave out the ``':'``) and no duration number.
|
||||
|
||||
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
|
||||
|
||||
**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
|
||||
|
||||
Compose the first few notes of Beethoven's 5th symphony.
|
||||
|
||||
```blocks
|
||||
let beet5 = ['G:1', 'G:1', 'G:1', 'Eb', 'F:1', 'F:1', 'F:1', 'D']
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
[begin melody](/reference/music/begin-melody)
|
||||
|
||||
[Tempo](https://wikipedia.org/wiki/Tempo)
|
||||
65
docs/reference/music/on-event.md
Normal file
65
docs/reference/music/on-event.md
Normal file
@ -0,0 +1,65 @@
|
||||
# On Event
|
||||
|
||||
Raises events for melodies or music events.
|
||||
|
||||
```sig
|
||||
music.onEvent(MusicEvent.MelodyNotePlayed, () => {})
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
* ``value`` the kind of event
|
||||
* ``handler`` the code to run when the event is raised.
|
||||
|
||||
## Example
|
||||
|
||||
This example prints all the events to the serial output.
|
||||
|
||||
```blocks
|
||||
music.onEvent(MusicEvent.MelodyRepeated, () => {
|
||||
serial.writeLine("melody repeated")
|
||||
})
|
||||
music.onEvent(MusicEvent.MelodyEnded, () => {
|
||||
serial.writeLine("melody ended")
|
||||
})
|
||||
music.onEvent(MusicEvent.MelodyStarted, () => {
|
||||
serial.writeLine("melody started")
|
||||
})
|
||||
music.onEvent(MusicEvent.MelodyRepeated, () => {
|
||||
serial.writeLine("background melody repeated")
|
||||
})
|
||||
music.onEvent(MusicEvent.BackgroundMelodyStarted, () => {
|
||||
serial.writeLine("background started")
|
||||
})
|
||||
music.onEvent(MusicEvent.BackgroundMelodyEnded, () => {
|
||||
serial.writeLine("background ended")
|
||||
})
|
||||
music.onEvent(MusicEvent.BackgroundMelodyPaused, () => {
|
||||
serial.writeLine("background paused")
|
||||
})
|
||||
music.onEvent(MusicEvent.BackgroundMelodyResumed, () => {
|
||||
serial.writeLine("background resumed")
|
||||
})
|
||||
music.onEvent(MusicEvent.BackgroundMelodyRepeated, () => {
|
||||
serial.writeLine("background repeated")
|
||||
})
|
||||
input.onButtonPressed(Button.A, () => {
|
||||
music.beginMelody(music.builtInMelody(Melodies.BaDing), MelodyOptions.Once)
|
||||
})
|
||||
music.setTempo(100)
|
||||
music.beginMelody(music.builtInMelody(Melodies.Ringtone), MelodyOptions.ForeverInBackground)
|
||||
```
|
||||
|
||||
## Background melody
|
||||
|
||||
The events related to background melody get triggered by a melody that is played inside a run in background block.
|
||||
|
||||
```
|
||||
control.inBackground(function () {
|
||||
basic.pause(Math.randomRange(0, 5000))
|
||||
music.beginMelody(music.builtInMelody(Melodies.Entertainer), MelodyOptions.Once)
|
||||
})
|
||||
music.onEvent(MusicEvent.BackgroundMelodyStarted, function () {
|
||||
basic.showIcon(IconNames.EigthNote)
|
||||
})
|
||||
```
|
||||
@ -2,18 +2,20 @@
|
||||
|
||||
Play a musical tone through pin ``P0`` of the @boardname@ for as long as you say.
|
||||
|
||||
## Simulator
|
||||
## ~ hint
|
||||
|
||||
This function only works on the @boardname@ and in some browsers.
|
||||
|
||||
## ~
|
||||
|
||||
```sig
|
||||
music.playTone(440, 120)
|
||||
```
|
||||
|
||||
### Parameters
|
||||
## Parameters
|
||||
|
||||
* ``frequency`` is the [number](/reference/types/number) of Hertz (how high or low the tone is).
|
||||
* ``ms`` is the [number](/reference/types/number) of milliseconds that the tone lasts
|
||||
* ``frequency`` is the [number](/types/number) of Hertz (how high or low the tone is).
|
||||
* ``ms`` is the [number](/types/number) of milliseconds that the tone lasts
|
||||
|
||||
## Example
|
||||
|
||||
@ -25,7 +27,16 @@ let freq = music.noteFrequency(Note.C)
|
||||
music.playTone(freq, 1000)
|
||||
```
|
||||
|
||||
### See also
|
||||
|
||||
## Using other pins
|
||||
|
||||
Use [analogSetPitchPin](/reference/pins/analog-set-pitch-pin) to change that pin used to generate music.
|
||||
|
||||
```blocks
|
||||
pins.analogSetPitchPin(AnalogPin.P1);
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
[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)
|
||||
|
||||
@ -2,17 +2,19 @@
|
||||
|
||||
Rest (play no sound) through pin `PO` for the amount of time you say.
|
||||
|
||||
## Simulator
|
||||
|
||||
This function only works on the @boardname@ and in some browsers.
|
||||
|
||||
```sig
|
||||
music.rest(400)
|
||||
```
|
||||
|
||||
### Parameters
|
||||
### ~ hint
|
||||
|
||||
* ``ms`` is a [number](/reference/types/number) saying how many
|
||||
**Simulator**: This function only works on the @boardname@ and in some browsers.
|
||||
|
||||
## ~
|
||||
|
||||
## Parameters
|
||||
|
||||
* ``ms`` is a [number](/types/number) saying how many
|
||||
milliseconds the @boardname@ should rest. One second is 1000
|
||||
milliseconds.
|
||||
|
||||
@ -24,7 +26,7 @@ music.playTone(frequency, 1000)
|
||||
music.rest(1000)
|
||||
```
|
||||
|
||||
### See also
|
||||
## See also
|
||||
|
||||
[play tone](/reference/music/play-tone), [ring tone](/reference/music/ring-tone) , [tempo](/reference/music/tempo), [set tempo](/reference/music/set-tempo), [change tempo by](/reference/music/change-tempo-by)
|
||||
|
||||
|
||||
@ -3,22 +3,24 @@
|
||||
Play a musical tone through pin `P0` with the pitch as high or low as you say.
|
||||
The tone will keep playing until you tell it not to.
|
||||
|
||||
## Simulator
|
||||
|
||||
This function only works on the @boardname@ and in some browsers.
|
||||
|
||||
```sig
|
||||
music.ringTone(440)
|
||||
```
|
||||
|
||||
### Parameters
|
||||
## ~ hint
|
||||
|
||||
* ``frequency`` is a [number](/reference/types/number) that says
|
||||
**Simulator**: This function only works on the @boardname@ and in some browsers.
|
||||
|
||||
## ~
|
||||
|
||||
## Parameters
|
||||
|
||||
* ``frequency`` is a [number](/types/number) that says
|
||||
how high-pitched or low-pitched the tone is. This
|
||||
number is in **Hz** (**Hertz**), which is a measurement of frequency
|
||||
or pitch.
|
||||
|
||||
### Example
|
||||
## Example
|
||||
|
||||
This program checks the **accelerometer** for the @boardname@'s
|
||||
**acceleration** (how much the @boardname@ is speeding up or slowing
|
||||
@ -32,7 +34,15 @@ basic.forever(() => {
|
||||
})
|
||||
```
|
||||
|
||||
### See also
|
||||
## Using other pins
|
||||
|
||||
Use [analogSetPitchPin](/reference/pins/analog-set-pitch-pin) to change that pin used to generate music.
|
||||
|
||||
```blocks
|
||||
pins.analogSetPitchPin(AnalogPin.P1);
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
[rest](/reference/music/rest), [play tone](/reference/music/play-tone),
|
||||
[tempo](/reference/music/tempo), [set tempo](/reference/music/set-tempo),
|
||||
|
||||
38
docs/reference/music/set-play-tone.md
Normal file
38
docs/reference/music/set-play-tone.md
Normal file
@ -0,0 +1,38 @@
|
||||
# Set Play Tone
|
||||
|
||||
Replaces the implementation of the [music play tone](/reference/music/play-tone).
|
||||
|
||||
|
||||
```sig
|
||||
music.setPlayTone((frequency: number, duration: number) => {})
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
* ``f`` the replacement function
|
||||
|
||||
## Example
|
||||
|
||||
This example send the frequency and duration over radio
|
||||
and plays it on the remote @boardname@.
|
||||
|
||||
```typescript
|
||||
input.onButtonPressed(Button.A, () => {
|
||||
music.playTone(440, 120)
|
||||
led.toggle(0, 0)
|
||||
})
|
||||
radio.onReceivedNumber(function (receivedNumber) {
|
||||
const freq = receivedNumber >> 16;
|
||||
const duration = receivedNumber & 0xffff;
|
||||
music.playTone(freq, duration);
|
||||
})
|
||||
input.onButtonPressed(Button.B, () => {
|
||||
music.setPlayTone((frequency: number, duration: number) => {
|
||||
radio.sendNumber((frequency << 16) | (duration & 0xffff));
|
||||
})
|
||||
})
|
||||
```
|
||||
## See also
|
||||
|
||||
[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)
|
||||
@ -5,15 +5,17 @@ Makes the tempo (speed of a piece of music) as fast or slow as you say.
|
||||
```sig
|
||||
music.setTempo(60)
|
||||
```
|
||||
## Simulator
|
||||
## ~ hint
|
||||
|
||||
This function only works on the @boardname@ and in some browsers.
|
||||
**Simulator**: This function only works on the @boardname@ and in some browsers.
|
||||
|
||||
### Parameters
|
||||
## ~
|
||||
|
||||
* ``bpm`` is a [number](/reference/types/number) that means the beats per minute you want (the number of beats in a minute of the music that the @boardname@ is playing).
|
||||
## Parameters
|
||||
|
||||
### See also
|
||||
* ``bpm`` is a [number](/types/number) that means the beats per minute you want (the number of beats in a minute of the music that the @boardname@ is playing).
|
||||
|
||||
## See also
|
||||
|
||||
[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)
|
||||
|
||||
|
||||
40
docs/reference/music/stop-melody.md
Normal file
40
docs/reference/music/stop-melody.md
Normal file
@ -0,0 +1,40 @@
|
||||
# stop Melody
|
||||
|
||||
Stop playing a musical melody.
|
||||
|
||||
```sig
|
||||
music.stopMelody(MelodyStopOptions.All)
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
When a melody begins, it has an option set for how the melody is to play. The melody plays just one time, ``once``, or it will 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 the foreground melody.
|
||||
|
||||
You can stop either a ``foreground`` melody, a ``background`` melody, or ``all`` melodies.
|
||||
|
||||
## ~ hint
|
||||
|
||||
**Simulator**: This function only works on the @boardname@ and in some browsers.
|
||||
|
||||
## ~
|
||||
|
||||
## Parameters
|
||||
|
||||
* **options**: specify which melodies (foreground, background or both) to stop:
|
||||
>* ``all``: stop all melodies
|
||||
>* ``foreground``: stop the foreground melody
|
||||
>* ``background``: stop the background melody
|
||||
|
||||
## Example
|
||||
|
||||
Play the ``Entertainer`` built-in melody and then stop it after 5 seconds.
|
||||
|
||||
```blocks
|
||||
music.beginMelody(music.builtInMelody(Melodies.Entertainer), MelodyOptions.Forever)
|
||||
basic.pause(5000)
|
||||
music.stopMelody(MelodyStopOptions.All)
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
[start melody](/reference/music/begin-melody)
|
||||
@ -6,12 +6,12 @@ Finds the tempo (speed of a piece of music).
|
||||
music.tempo()
|
||||
```
|
||||
|
||||
### Returns
|
||||
## Returns
|
||||
|
||||
* a [number](/reference/types/number) that means the beats per minute (number of
|
||||
* a [number](/types/number) that means the beats per minute (number of
|
||||
beats in a minute of the music that the @boardname@ is playing).
|
||||
|
||||
### See also
|
||||
## See also
|
||||
|
||||
[play tone](/reference/music/play-tone), [ring tone](/reference/music/ring-tone), [rest](/reference/music/rest), [set tempo](/reference/music/set-tempo), [change tempo by](/reference/music/change-tempo-by)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user