pxt-common-packages 10.4.5 → 10.4.6

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

@@ -0,0 +1,132 @@
+# play
+
+Play a song, melody, or tone from a playable music source.
+
+```sig
+music.play(music.createSong(hex`00780004080200`), music.PlaybackMode.UntilDone)
+```
+
+Music is played for a simple tone, a melody, or a song. Each of these music sources is called a [playble](/types/playable) object. The ``||music:play||`` block can take any of these playable objects and play them as sound output for your game.
+
+The simpliest music source is a **tone**, on note play for a duration of time:
+
+```block
+music.play(music.tonePlayable(262, music.beat(BeatFraction.Whole)), music.PlaybackMode.UntilDone)
+```
+
+Then, there is the **melody** which is a series of notes played at a certain speed, or `tempo`. You can create your own melody of choose a built-in one to play:
+
+```block
+music.play(music.stringPlayable("D F E A E A C B ", 120), music.PlaybackMode.UntilDone)
+music.play(music.melodyPlayable(music.magicWand), music.PlaybackMode.UntilDone)
+```
+
+The most complex playabe object is a **song**. Songs are composed in the [Song Editor](/reference/music/song-editor) using many notes from different instruments.
+
+```block
+music.play(music.createSong(hex`0078000408020200001c00010a006400f40164000004000000000000000000000000000500000430000400080001220c001000012514001800011e1c00200001222400280001252c003000012934003800012c3c004000011e03001c0001dc00690000045e010004000000000000000000000564000104000330000400080001290c001000011e1400180001251c002000012924002800011b2c003000012234003800011e3c0040000129`), music.PlaybackMode.UntilDone)
+```
+
+## Parameters
+
+* **toPlay**: the [playable](/types/playable) object, or music source, to play.
+* **playbackMode**: the playback mode for continuing the program:
+>* `play until done`: play the music source in **toPlay** but wait to run the next part of the program until music play is done.
+>* `in background`: play the music source in **toPlay** but continue with the rest of the program before music play is done.
+>* `in background looping`: play the music source in **toPlay** but continue with the rest of the program before music play is done. The music will remain playing, returning to the first note of the music after its duration.
+
+### ~ hint
+
+#### Stop the music!
+
+You can stop any music currently playing with the ``||music:stop all sounds||`` block. This is useful if **playbackMode** is set to `in background looping` and you wish to stop the music for a scene change or respond to an event with a different sound.
+
+### ~
+
+## Examples #example
+
+### Play a melody
+
+Play a short melody created in the Melody Editor.
+
+```blocks
+music.play(music.stringPlayable("D F E A E A C B ", 120), music.PlaybackMode.UntilDone)
+```
+
+### Different music sources, one block to play them all
+
+Put 4 different playable music sources in an array. Play one after the other.
+
+```blocks
+let playables = [
+music.tonePlayable(262, music.beat(BeatFraction.Whole)),
+music.stringPlayable("D F E A E A C B ", 120),
+music.melodyPlayable(music.baDing),
+music.createSong(hex`0078000408020200001c00010a006400f40164000004000000000000000000000000000500000430000400080001220c001000012514001800011e1c00200001222400280001252c003000012934003800012c3c004000011e03001c0001dc00690000045e010004000000000000000000000564000104000330000400080001290c001000011e1400180001251c002000012924002800011b2c003000012234003800011e3c0040000129`)
+]
+for (let someMusic of playables) {
+    music.play(someMusic, music.PlaybackMode.UntilDone)
+    pause(500)
+}
+```
+
+### Looping music play
+
+Play a simple song in the background while a monkey moves around the screen. When the monkey hits the bubble in the middle of the screen, stop the song and play a bursting sound.
+
+```blocks
+let bubble = sprites.create(img`
+    . . . . . b b b b b b . . . . . 
+    . . . b b 9 9 9 9 9 9 b b . . . 
+    . . b b 9 9 9 9 9 9 9 9 b b . . 
+    . b b 9 d 9 9 9 9 9 9 9 9 b b . 
+    . b 9 d 9 9 9 9 9 1 1 1 9 9 b . 
+    b 9 d d 9 9 9 9 9 1 1 1 9 9 9 b 
+    b 9 d 9 9 9 9 9 9 1 1 1 9 9 9 b 
+    b 9 3 9 9 9 9 9 9 9 9 9 1 9 9 b 
+    b 5 3 d 9 9 9 9 9 9 9 9 9 9 9 b 
+    b 5 3 3 9 9 9 9 9 9 9 9 9 d 9 b 
+    b 5 d 3 3 9 9 9 9 9 9 9 d d 9 b 
+    . b 5 3 3 3 d 9 9 9 9 d d 5 b . 
+    . b d 5 3 3 3 3 3 3 3 d 5 b b . 
+    . . b d 5 d 3 3 3 3 5 5 b b . . 
+    . . . b b 5 5 5 5 5 5 b b . . . 
+    . . . . . b b b b b b . . . . . 
+    `, SpriteKind.Player)
+let monkey = sprites.create(img`
+    . . . . f f f f f . . . . . . . 
+    . . . f e e e e e f . . . . . . 
+    . . f d d d d e e e f . . . . . 
+    . c d f d d f d e e f f . . . . 
+    . c d f d d f d e e d d f . . . 
+    c d e e d d d d e e b d c . . . 
+    c d d d d c d d e e b d c . f f 
+    c c c c c d d d e e f c . f e f 
+    . f d d d d d e e f f . . f e f 
+    . . f f f f f e e e e f . f e f 
+    . . . . f e e e e e e e f f e f 
+    . . . f e f f e f e e e e f f . 
+    . . . f e f f e f e e e e f . . 
+    . . . f d b f d b f f e f . . . 
+    . . . f d d c d d b b d f . . . 
+    . . . . f f f f f f f f f . . . 
+    `, SpriteKind.Enemy)
+monkey.setBounceOnWall(true)
+monkey.x = scene.screenWidth()
+monkey.setVelocity(50, 40)
+music.play(music.stringPlayable("C5 A B G A F A C5 ", 120), music.PlaybackMode.LoopingInBackground)
+sprites.onOverlap(SpriteKind.Player, SpriteKind.Enemy, function (sprite, otherSprite) {
+    music.stopAllSounds()
+    sprites.destroy(sprite, effects.blizzard, 500)
+    music.play(music.melodyPlayable(music.zapped), music.PlaybackMode.UntilDone)
+})
+```
+
+## See also #seealso
+
+[tone playable](/reference/music/tone-playable),
+[string playable](/reference/music/string-playable),
+[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)

package/libs/mixer/docs/reference/music/song-editor.md

@@ -0,0 +1,92 @@
+# Song Editor
+
+A song is contained inside the ``||music:song||`` block. The song is created and modified using the Song Editor which opens when you click on the song parameter window of the block.
+
+```block
+music.createSong(hex`00780004080200`)
+```
+
+More often though, you'll see the ``||music:song||`` block as part of the ``||music:play||`` block.
+
+```block
+music.play(music.createSong(hex`00780004080200`), music.PlaybackMode.UntilDone)
+```
+
+Clicking on the song parameter window opens the Song Editor. If the ``||music:song||`` block contains no song information, the Song Editor will display with an empty song.
+
+## JavaScript and Python
+
+When you edit your code in the JavaScript or Python workspaces, the musical notes symbol (♫) appears in the margin of the line containing the ``||music:song||`` equivalent function, [createSong()](/reference/music/create-song). Clicking on this symbol will open the Song Editor too.
+
+```
+   1   let mySprite = sprites.create(assets.image`myImage`, SpriteKind.Player)
+♫  2   music.play(music.createSong(hex`00780004080200`), music.PlaybackMode.InBackground)
+   3   mySprite.startEffect(effects.confetti)
+   4
+```
+
+## Music staff
+
+Notes of a song are placed on the music **staff** which is a set of horizontal lines arranged from low to high. The notes are placed at **grid** positions from left to right. The grid divides a **measure** to determine how may notes the measure contains. A grid of **1/8** has **8** note positons per measure. If a note position has no notes in it, that position is a rest (no sound). Placing notes higher or lower on the staff, of course, sets the pitch of the note.
+
+### Measures
+
+You can change the length of the song by adding or removing measures. The **Measures** control lets you choose how long your song will play for. In this example, measures is set to **4** to add 2 more measures to the song.
+
+### Bass clef
+
+You can put notes on the **Bass Clef** too. Just check the **Show base clef** option. The bass clef is displayed in the Song Editor to match the default treble clef.
+
+Notes are added to the bass clef in the same way as the treble clef.
+
+### Grid
+
+The number of note positions (divisions) in each measure is set by the **Grid** control. The grid setting will set the number of note divisions in the measures using a measure fraction. This example is using an grid setting of 1/16 so there are 16 notes shown in the measure.
+
+### Example
+
+This example contains a song with notes on both clefs having measures at 1/8 divisions.
+
+```blocks
+let mySprite = sprites.create(img`
+    ....................
+    ....................
+    ....................
+    ....2222...2222.....
+    ...222222.222222....
+    ..222222222222222...
+    ..222222222222222...
+    ..222222222222222...
+    ..222222222222222...
+    ..222222222222222...
+    ..222222222222222...
+    ...2222222222222....
+    ....22222222222.....
+    .....222222222......
+    ......2222222.......
+    .......22222........
+    ........222.........
+    .........2..........
+    .........2..........
+    ....................
+    `, SpriteKind.Player)
+music.play(music.createSong(hex`0078000408040200001c00010a006400f401640000040000000000000000000000000005000004a30000000400012a04000800012708000c0001200c001000012410001400012a14001800012018001c00011d1c002000012020002400012724002800012a28002c0001252c003000012030003400012434003800012738003c00012a3c004000012740004400012044004800012548004c00012a4c005000012050005400012454005800021e2758005c00012a5c00600001206000640001276400680001246c007000012004001c00100500640000041e000004000000000000000000000000000a040004600000000400010804000800011208000c00010c0c001000011210001400010814001800011218001c00010c1c002000011220002400010824002800011228002c00010c2c003000011230003400010834003800011238003c00010c3c0040000112`), music.PlaybackMode.InBackground)
+mySprite.startEffect(effects.confetti, 5000)
+```
+
+## Instruments
+
+You can play notes for several different **instruments**. You select an instrument from the instrument bar at the top of the editor window.
+
+The instruments are represented by various character symbols and make different sounds for the same notes. These are MakeCode intruments and don't exaclty have the same sound as typical instruments like a violin, cello, drums, or guitar.
+
+If you need to focus on placing notes for a particular instrument, you can use the **Only show selected instrument** option to temporarily remove the other instruments from the staff. This makes it easier to compose for a single instrument since only the notes for the currently selected instrument will show.
+
+## Playing the song
+
+While editing a song, you can play, stop, or loop play the music you currently have composed. Also, you can change the tempo (beats per minute) of the song with the **Tempo** setting.
+
+## See also
+
+[play](/reference/music/play),
+[create song](/reference/music/create-song)

package/libs/mixer/docs/reference/music/string-playable.md

@@ -0,0 +1,41 @@
+# string Playable
+
+Created a short melody of notes composed in a string.
+
+```sig
+music.stringPlayable("D F E A E A C B ", 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:melody||`` block as note symbols which also appear in the Melody Editor.
+
+```block
+music.stringPlayable("E F G F E G B C5 ", 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.
+
+## Returns
+
+* a [playable](/types/playable) object that contains the **melody** and **tempo**.
+
+## Example #example
+
+Play the ``Mystery`` melody continuously.
+
+```blocks
+music.play(music.stringPlayable("E F G F E G B C5 ", 120), music.PlaybackMode.LoopingInBackground)
+```
+
+## See also #seealso
+
+[tone playable](/reference/music/tone-playable),
+[melody playable](/reference/music/melody-playable)

package/libs/mixer/docs/reference/music/tone-playable.md

@@ -0,0 +1,30 @@
+# tone Playable
+
+Create a musical tone that will play for some amount of time.
+
+```sig
+music.tonePlayable(262, music.beat(BeatFraction.Whole))
+```
+
+## Parameters
+
+* **note**: is the note frequency as a [number](/types/number) of [Hertz](https://wikipedia.org/wiki/Hertz) (how high or low the tone is, also known as _pitch_). If **note** is less or equal to zero, no sound is played.
+* **duration**: is the [number](/types/number) of milliseconds (one-thousandth of a second) that the tone lasts for. If **duration** is negative or zero, the sound will play continuously.
+
+## Returns
+
+* a [playable](/types/playable) object that contains the tone.
+
+## Example #example
+
+Store the musical note 'C' in the variable `note` and play that note for 1000 milliseconds (one second).
+
+```blocks
+let note = music.noteFrequency(Note.C);
+music.play(music.tonePlayable(note, music.beat(BeatFraction.Whole)), music.PlaybackMode.UntilDone)
+```
+
+## See also #seealso
+
+[melody playable](/reference/music/melody-playable),
+[string playable](/reference/music/string-playable)

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

@@ -2,20 +2,24 @@
 
 Make music and play tones.
 
+## Songs
+
+```cards
+music.createSong(hex`00780004080200`)
+```
+
 ## Melodies
 
 ```cards
-music.playMelody("", 120);
-music.baDing.play()
-music.baDing.playUntilDone()
-music.baDing.loop()
-music.baDing.stop()
+music.stringPlayable("", 120)
+music.melodyPlayable(music.baDing)
 ```
 
 ## Sound
 
 ```cards
-music.playTone(0, 0);
+music.play(null, music.PlaybackMode.UntilDone)
+music.tonePlayable(262, music.beat(BeatFraction.Whole))
 music.ringTone(0);
 music.rest(0);
 music.noteFrequency(Note.C);
@@ -29,7 +33,8 @@ music.stopAllSounds()
 
 ## See Also
 
-[play melody](/reference/music/play-melody), [play tone](/reference/music/play-tone),
+[play](/reference/music/play), [tone playable](/reference/music/tone-playable),
+[string playable](/reference/music/string-playable), [melody playable](/reference/music/melody-playable), [create song](/reference/music/create-song),
 [ring tone](/reference/music/ring-tone), [rest](/reference/music/rest),
 [beat](/reference/music/beat), [tempo](/reference/music/tempo),
 [change tempo by](/reference/music/change-tempo-by),[set tempo](/reference/music/set-tempo)

package/libs/mixer/docs/types/playable.md

@@ -0,0 +1,76 @@
+# playable
+
+The **playable** data object provides a common format to play tones, melodies, and songs. Each of these music sources are created in different ways but are transformed into playable objects so that a single playback method is used to [play](/refernece/music/play) them.
+
+## Music sources for playable objects
+
+The blocks used to create playable music soucres are the following:
+
+### Tone
+
+A tone is a musical note, or a sound frequency, and a duration. The duration is often set as the length of a `beat`.
+
+```block
+music.tonePlayable(262, music.beat(BeatFraction.Whole))
+```
+
+### Melody
+
+Melodies are a series of notes and a tempo to play them at.
+
+```block
+music.stringPlayable("D F E A E A C B ", 120)
+```
+
+### Built-in sound
+
+A built-in sound is a simple melody already composed for you. There are several you can choose from.
+
+```block
+music.melodyPlayable(music.baDing)
+```
+
+### Song
+
+Songs are complex music sources which have many notes from different instruments. Songs are made in the Song Editor.
+
+```block
+music.createSong(hex`0078000408020200001c00010a006400f40164000004000000000000000000000000000500000430000400080001220c001000012514001800011e1c00200001222400280001252c003000012934003800012c3c004000011e03001c0001dc00690000045e010004000000000000000000000564000104000330000400080001290c001000011e1400180001251c002000012924002800011b2c003000012234003800011e3c0040000129`)
+```
+
+## Play the music
+
+In your programs, you can simply use the ``||music:play||`` blocks for each playable object. Like this one for tone:
+
+```block
+music.play(music.tonePlayable(262, music.beat(BeatFraction.Whole)), music.PlaybackMode.UntilDone)
+```
+
+Or, this one for song:
+
+```block
+music.play(music.createSong(hex`0078000408020200001c00010a006400f40164000004000000000000000000000000000500000430000400080001220c001000012514001800011e1c00200001222400280001252c003000012934003800012c3c004000011e03001c0001dc00690000045e010004000000000000000000000564000104000330000400080001290c001000011e1400180001251c002000012924002800011b2c003000012234003800011e3c0040000129`), music.PlaybackMode.UntilDone)
+```
+
+## Example #example
+
+Put 4 different playable music sources in an array. Play one after the other.
+
+```blocks
+let playables = [
+music.tonePlayable(262, music.beat(BeatFraction.Whole)),
+music.stringPlayable("D F E A E A C B ", 120),
+music.melodyPlayable(music.baDing),
+music.createSong(hex`0078000408020200001c00010a006400f40164000004000000000000000000000000000500000430000400080001220c001000012514001800011e1c00200001222400280001252c003000012934003800012c3c004000011e03001c0001dc00690000045e010004000000000000000000000564000104000330000400080001290c001000011e1400180001251c002000012924002800011b2c003000012234003800011e3c0040000129`)
+]
+for (let someMusic of playables) {
+    music.play(someMusic, music.PlaybackMode.UntilDone)
+    pause(500)
+}
+```
+
+## See also #seealso
+
+[play](/reference/music/play), [tone playable](/reference/music/tone-playable),
+[string playable](/reference/music/string-playable), [melody playable](/reference/music/melody-playable),
+[create song](/reference/music/create-song)

package/libs/mixer/melody.ts

@@ -602,6 +602,7 @@ namespace music {
     //% toolboxParentArgument=toPlay
     //% group="Songs"
     //% duplicateShadowOnDrag
+    //% help=music/create-song
     export function createSong(song: Buffer): Playable {
         return new sequencer.Song(song);
     }

package/libs/mixer/playable.ts

@@ -108,6 +108,7 @@ namespace music {
     //% block="play $toPlay $playbackMode"
     //% toPlay.shadow=music_melody_playable
     //% group="Sounds"
+    //% help="music/play"
     export function play(toPlay: Playable, playbackMode: PlaybackMode) {
         toPlay.play(playbackMode);
     }
@@ -119,6 +120,7 @@ namespace music {
     //% group="Sounds"
     //% duplicateShadowOnDrag
     //% blockHidden
+    //% help=music/melody-playable
     export function melodyPlayable(melody: Melody): Playable {
         return new MelodyPlayable(melody);
     }
@@ -135,6 +137,7 @@ namespace music {
     //% melody.shadow=melody_editor
     //% tempo.min=40 tempo.max=500
     //% tempo.defl=120
+    //% help=music/string-playable
     export function stringPlayable(melody: string, tempo: number): Playable {
         let notes: string[] = melody.split(" ").filter(n => !!n);
         let formattedMelody = "";
@@ -171,6 +174,7 @@ namespace music {
     //% note.shadow=device_note
     //% duration.shadow=device_beat
     //% parts="headphone"
+    //% help=music/tone-playable
     export function tonePlayable(note: number, duration: number): Playable {
         return new TonePlayable(note, duration);
     }