Skip to content

Commit bbe0cd2

Browse files
ganickeganicke
authored
Update music reference pages to sync with current Playable API (#6303)
* add page for newer api * update ref pages to sync with the 'playable' changes * set help path to new ref page * toss in summary update for projects * toss in strings update for loc * riknoll's corrected description
1 parent 8aa85b8 commit bbe0cd2

File tree

8 files changed

+169
-26
lines changed

8 files changed

+169
-26
lines changed

‎docs/projects/SUMMARY.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -138,7 +138,7 @@
138138
* [First Steps](https://microbit.org/get-started/first-steps/introduction/)
139139
* [Make it: code it](https://microbit.org/projects/make-it-code-it/)
140140
* [Networking with the micro:bit](https://www.digitaltechnologieshub.edu.au/search/networking-with-the-micro-bit/)
141-
* [SparkFun Videos](https://youtu.be/kaNtg1HGXbY?list=PLBcrWxTa5CS0mWJrytvii8aG5KUqMXvSk)
141+
* [SparkFun Videos](https://youtu.be/kaNtg1HGXbY)
142142
* [Logic Lab](/courses/logic-lab)
143143
* [CodeJoy Remote Robotics](https://www.codejoy.org)
144144
* [Blocks to JavaScript](/courses/blocks-to-javascript)

‎docs/reference/music/built-in-playable-melody.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,4 +47,4 @@ music.play(music.builtInPlayableMelody(Melodies.Blues), music.PlaybackMode.InBac
4747

4848
## See also
4949

50-
[built-in sound effect](/reference/music/builtin-sound-effect)
50+
[string playable](/reference/music/string-playable)

‎docs/reference/music/create-sound-expression.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# create Sound Expression
2+
3+
Create a sound expression object for a sound effect.
4+
5+
```sig
6+
music.createSoundExpression(WaveShape.Sine, 2000, 0, 1023, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear)
7+
```
8+
9+
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) to the speaker, headphones, or at an output pin.
10+
11+
## Parameters
12+
13+
* **waveShape**: the primary shape of the waveform:
14+
>* `sine`: sine wave shape
15+
>* `sawtooth`: sawtooth wave shape
16+
>* `triangle`: triangle wave shape
17+
>* `square`: square wave shape
18+
>* `noise`: random noise generated wave shape
19+
* **startFrequency**: a [number](/types/number) that is the frequency of the waveform when the sound expression starts.
20+
* **endFrequency**: a [number](/types/number) that is the frequency of the waveform when the sound expression stops.
21+
* **startVolume**: a [number](/types/number) the initial volume of the sound expression.
22+
* **endVolume**: a [number](/types/number) the ending volume of the sound expression.
23+
* **duration**: a [number](/types/number) the duration in milliseconds of the sound expression.
24+
* **effect**: an effect to add to the waveform. These are:
25+
>* `tremolo`: add slight changes in volume of the sound expression.
26+
>* `vibrato`: add slight changes in frequency to the sound expression.
27+
>* `warble`: a combination of the `tremolo` and `vibrato` effects.
28+
* **interpolation**: controls the rate of frequency change in the sound expression.
29+
>* `linear`: the change in frequency is constant for the duration of the sound.
30+
>* `curve`: the change in frequency is faster at the beginning of the sound and slows toward the end.
31+
>* `logarithmic`: the change in frequency is rapid during the very first part of the sound.
32+
33+
## Returns
34+
35+
* a [sound](/types/sound) expression with the the desired sound effect parameters.
36+
37+
## Examples
38+
39+
### Sine wave sound
40+
41+
Create a sound expression and assign it to a variable. Play the sound for the sound expression.
42+
43+
```blocks
44+
let mySound = music.createSoundExpression(WaveShape.Sine, 2000, 0, 1023, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear)
45+
music.play(mySound, music.PlaybackMode.UntilDone)
46+
```
47+
48+
### Complex waveform sound
49+
50+
Create a `triangle` wave sound expression with `vibrato` and a `curve` interpolation. Play the sound until it finishes.
51+
52+
```typescript
53+
let mySound = music.createSoundExpression(
54+
WaveShape.Triangle,
55+
1000,
56+
2700,
57+
255,
58+
255,
59+
500,
60+
SoundExpressionEffect.Vibrato,
61+
InterpolationCurve.Curve
62+
)
63+
music.play(mySound, music.PlaybackMode.UntilDone)
64+
```
65+
66+
## See also
67+
68+
[play](/reference/music/play)

‎docs/reference/music/play.md

Lines changed: 80 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,110 @@
11
# play
22

3-
Play a sound expression.
3+
Play a song, melody, tone, or a sound effect from a playable music source.
44

55
```sig
6-
soundExpression.giggle.play()
6+
music.play(music.tonePlayable(262, music.beat(BeatFraction.Whole)), music.PlaybackMode.UntilDone)
77
```
88

9-
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.
9+
Music is played for a simple tone, a melody, or a song. Each of these music sources is called a [playable](/types/playable) object. The ``||music:play||`` block can take any of these playable objects and play them as sound output for your game.
1010

1111
### ~ reminder
1212

13+
#### For micro:bit v2 only
14+
1315
![works with micro:bit V2 only image](/static/v2/v2-only.png)
1416

1517
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.
1618

1719
### ~
1820

19-
## Parameters
21+
The simplest music source is a **tone**, on note play for a duration of time:
22+
23+
```block
24+
music.play(music.tonePlayable(262, music.beat(BeatFraction.Whole)), music.PlaybackMode.UntilDone)
25+
```
2026

21-
In blocks, the sound is selected from the list in the ``||music:play sound||`` block.
27+
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:
2228

2329
```block
24-
soundExpression.giggle.play()
30+
music.play(music.stringPlayable("D F E A E A C B ", 120), music.PlaybackMode.UntilDone)
31+
music.play(music.builtInPlayableMelody(Melodies.BaDing), music.PlaybackMode.UntilDone)
2532
```
2633

27-
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()``:
34+
The most complex playable object is a **sound expression**. [Sound expressions](/reference/music/create-sound-expression) are composed in the [Sound Editor](/types/sound#sound-editing) using different parameters for making sound waves and effects..
2835

29-
```typescript
30-
soundExpression.soaring.play()
36+
```block
37+
music.play(music.createSoundExpression(WaveShape.Sine, 5000, 0, 255, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear), music.PlaybackMode.UntilDone)
3138
```
3239

33-
## Example
40+
## Parameters
41+
42+
* **toPlay**: the [playable](/types/playable) object, or music source, to play.
43+
* **playbackMode**: the playback mode for continuing the program:
44+
>* `play until done`: play the music source in **toPlay** but wait to run the next part of the program until music play is done.
45+
>* `in background`: play the music source in **toPlay** but continue with the rest of the program before music play is done.
46+
>* `looping in background`: 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.
47+
48+
### ~ hint
49+
50+
#### Stop the music!
51+
52+
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.
53+
54+
### ~
55+
56+
## Examples #example
57+
58+
### Play a melody
59+
60+
Play a short melody created in the Melody Editor.
61+
62+
```blocks
63+
music.play(music.stringPlayable("D F E A E A C B ", 120), music.PlaybackMode.UntilDone)
64+
```
65+
66+
### Different music sources, one block to play them all
67+
68+
Put 4 different playable music sources in an array. Play one after the other.
69+
70+
```blocks
71+
let playables = [
72+
music.tonePlayable(262, music.beat(BeatFraction.Whole)),
73+
music.stringPlayable("D F E A E A C B ", 120),
74+
music.builtInPlayableMelody(Melodies.BaDing),
75+
music.createSoundExpression(WaveShape.Sine, 5000, 0, 255, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear)
76+
]
77+
for (let someMusic of playables) {
78+
music.play(someMusic, music.PlaybackMode.UntilDone)
79+
basic.pause(500)
80+
}
81+
```
82+
83+
### Looping music play
84+
85+
Play a simple song in the background. When the @boardname@ is shaken, stop the song an play the `power down` melody.
86+
87+
```blocks
88+
music.play(music.stringPlayable("C5 A B G A F A C5 ", 120), music.PlaybackMode.LoopingInBackground)
89+
input.onGesture(Gesture.Shake, function () {
90+
music.stopAllSounds()
91+
music.play(music.builtInPlayableMelody(Melodies.PowerDown), music.PlaybackMode.InBackground)
92+
})
93+
```
94+
### Play a sound effect
3495

35-
Play the ``twinkle`` sound on the speaker.
96+
Play a sine wave sound effect for `5` seconds.
3697

3798
```blocks
38-
soundExpression.twinkle.play()
99+
music.play(music.createSoundExpression(WaveShape.Sine, 5000, 0, 255, 0, 5000, SoundExpressionEffect.None, InterpolationCurve.Linear), music.PlaybackMode.UntilDone)
39100
```
40101

41102
## See also
42103

43-
[play until done](/reference/music/play-until-done)
104+
[tone playable](/reference/music/tone-playable),
105+
[string playable](/reference/music/string-playable),
106+
[melody playable](/reference/music/built-in-melody-playable),
107+
[create song](/reference/music/create-song),
108+
[stop all sounds](/reference/music/stop-all-sounds),
109+
[sound editor](/reference/types/sound#sound-editing),
110+
[create sound expression](/reference/music/create-sound-expression)

‎docs/types/playable.md

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,14 @@ Melodies are a series of notes and a tempo to play them at.
2222
music.stringPlayable("D F E A E A C B ", 120)
2323
```
2424

25+
### Sound Expression
26+
27+
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.
28+
29+
```block
30+
music.play(music.createSoundExpression(WaveShape.Sine, 5000, 0, 255, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear), music.PlaybackMode.UntilDone)
31+
```
32+
2533
## Play the music
2634

2735
In your programs, you can simply use the ``||music:play||`` blocks for each playable object. Like this one for tone:
@@ -47,5 +55,5 @@ for (let someMusic of playables) {
4755

4856
## See also
4957

50-
[play](/reference/music/play), [tone playable](/reference/music/tone-playable),
51-
[string playable](/reference/music/string-playable)
58+
[play](/reference/music/play), [tone playable](/reference/music/tone-playable)
59+
[string playable](/reference/music/string-playable), [create sound expression](/reference/music/create-sound-expression)

‎docs/types/sound.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@ In code, a **Sound** type is a complex data object that includes data for all th
1515
Code for creating and playing a sound from a sound expression could look like this:
1616

1717
```typescript-ignore
18-
let mySound = music.createSoundEffect(WaveShape.Sine, 2000, 0, 1023, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear)
19-
music.playSoundEffect(mySound, SoundExpressionPlayMode.UntilDone)
18+
let mySound = music.createSoundExpression(WaveShape.Sine, 2000, 0, 1023, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear)
19+
music.play(mySound, music.PlaybackMode.UntilDone)
2020
```
2121

2222
### ~
@@ -59,7 +59,7 @@ A square wave has both verical rising and falling edges with a flat section on t
5959

6060
### Noise wave
6161

62-
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.
62+
The noise wave is created using random frequencies and volume. Setting the frequency parameters for the sound expression creates a "tuning" range for the noise sound effect.
6363

6464
![Noise wave](/static/types/sound/noise-wave.png)
6565

@@ -85,9 +85,9 @@ The volume controls the loudness (amplitude) of the sound. The sound can start w
8585

8686
## Frequency
8787

88-
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.
88+
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 frequencies that last for short periods of time in a sound.
8989

90-
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.
90+
A sound expression has both a starting frequency and an ending frequency. The frequency can start low and end high, start high and end low, or remain the same for the duration of the sound.
9191

9292
### High to low
9393

@@ -132,5 +132,5 @@ Interpolation is how the sound expression will make the changes in frequency or
132132
133133
## See also
134134

135-
[play sound effect](/reference/music/play-sound-effect),
136-
[create sound effect](/reference/music/create-sound-effect)
135+
[play](/reference/music/play),
136+
[create sound expression](/reference/music/create-sound-expression)

‎libs/core/_locales/core-strings.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -249,7 +249,7 @@
249249
"String.isEmpty|block": "%this=text| is empty",
250250
"String.length|block": "length of %VALUE",
251251
"String.split|block": "split %this=text|at %separator",
252-
"String.substr|block": "substring of %this=text|from %start|of length %length",
252+
"String.substr|block": "substring of $this|from $start||of length $length",
253253
"String|block": "String",
254254
"TouchButtonEvent.LongPressed|block": "long pressed",
255255
"TouchButtonEvent.Pressed|block": "pressed",

‎libs/core/soundexpressions.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -436,7 +436,7 @@ namespace music {
436436
* @param interpolation interpolation method for frequency scaling
437437
*/
438438
//% blockId=soundExpression_createSoundExpression
439-
//% help=music/create-sound-effect
439+
//% help=music/create-sound-expression
440440
//% block="$waveShape|| start frequency $startFrequency end frequency $endFrequency duration $duration start volume $startVolume end volume $endVolume effect $effect interpolation $interpolation"
441441
//% waveShape.defl=WaveShape.Sine
442442
//% waveShape.fieldEditor=soundeffect

0 commit comments

Comments
 (0)