diff --git a/docs/reference/music.md b/docs/reference/music.md index 3fb88f22..c8820093 100644 --- a/docs/reference/music.md +++ b/docs/reference/music.md @@ -7,6 +7,7 @@ music.playTone(0, 0); music.ringTone(0); music.rest(0); music.beginMelody(music.builtInMelody(Melodies.Entertainer), MelodyOptions.Once); +music.stopMelody(MelodyStopOptions.All); music.onEvent(MusicEvent.MelodyNotePlayed, () => {}); music.beat(BeatFraction.Whole); music.tempo(); @@ -17,5 +18,7 @@ music.setTempo(120); ## See Also [playTone](/reference/music/play-tone), [ringTone](/reference/music/ring-tone), [rest](/reference/music/rest), -[beginMelody](/reference/music/begin-melody), [onEvent](/reference/music/on-event), +[beginMelody](/reference/music/begin-melody), +[stop melody](/reference/music/stop-melody), +[onEvent](/reference/music/on-event), [beat](/reference/music/beat), [tempo](/reference/music/tempo), [changeTempoBy](/reference/music/change-tempo-by), [setTempo](/reference/music/set-tempo), diff --git a/docs/reference/music/stop-melody.md b/docs/reference/music/stop-melody.md new file mode 100644 index 00000000..216ff8b3 --- /dev/null +++ b/docs/reference/music/stop-melody.md @@ -0,0 +1,27 @@ +# Stop Melody + +Stops playing a musical melody. + +## Simulator + +```sig +music.stopMelody(MelodyStopOptions.All) +``` + +## Parameters + +* ``options`` specifies which melodies (foreground, background or both) need to be stopped + +## Example + +This example plays the ``Entertainer`` built-in melody. + +```blocks +music.beginMelody(music.builtInMelody(Melodies.Entertainer), MelodyOptions.Forever) +basic.pause(5000) +music.stopMelody(MelodyStopOptions.All) +``` + +## See also + +[start melody](/reference/music/begin-melody) diff --git a/libs/core/_locales/core-jsdoc-strings.json b/libs/core/_locales/core-jsdoc-strings.json index 3ff94cee..aa60dcc8 100644 --- a/libs/core/_locales/core-jsdoc-strings.json +++ b/libs/core/_locales/core-jsdoc-strings.json @@ -418,6 +418,8 @@ "music.setPlayTone": "Sets a custom playTone function for playing melodies", "music.setTempo": "Sets the tempo to the specified amount", "music.setTempo|param|bpm": "The new tempo in beats per minute, eg: 120", + "music.stopMelody": "Stops the melodies", + "music.stopMelody|param|options": "which melody to stop", "music.tempo": "Returns the tempo in beats per minute. Tempo is the speed (bpm = beats per minute) at which notes play. The larger the tempo value, the faster the notes will play.", "parseFloat": "Convert a string to a number.", "parseInt": "Convert a string to an integer.", diff --git a/libs/core/_locales/core-strings.json b/libs/core/_locales/core-strings.json index ae490659..f73f853a 100644 --- a/libs/core/_locales/core-strings.json +++ b/libs/core/_locales/core-strings.json @@ -172,6 +172,9 @@ "MelodyOptions.Forever|block": "forever", "MelodyOptions.OnceInBackground|block": "once in background", "MelodyOptions.Once|block": "once", + "MelodyStopOptions.All|block": "all", + "MelodyStopOptions.Background|block": "background", + "MelodyStopOptions.Foreground|block": "foreground", "MesDpadButtonInfo.ADown|block": "A down", "MesDpadButtonInfo.AUp|block": "A up", "MesDpadButtonInfo.BDown|block": "B down", @@ -320,6 +323,7 @@ "music.rest|block": "rest(ms)|%duration=device_beat", "music.ringTone|block": "ring tone (Hz)|%note=device_note", "music.setTempo|block": "set tempo to (bpm)|%value", + "music.stopMelody|block": "stop melody $options", "music.tempo|block": "tempo (bpm)", "music|block": "music", "parseFloat|block": "parse to number %text", diff --git a/libs/core/music.ts b/libs/core/music.ts index 38eec26d..bf0dc17f 100644 --- a/libs/core/music.ts +++ b/libs/core/music.ts @@ -127,7 +127,7 @@ enum BeatFraction { } enum MelodyOptions { - //% block="once"" + //% block="once" Once = 1, //% block="forever" Forever = 2, @@ -137,6 +137,15 @@ enum MelodyOptions { ForeverInBackground = 8 } +enum MelodyStopOptions { + //% block="all" + All = MelodyOptions.Once | MelodyOptions.OnceInBackground, + //% block="foreground" + Foreground = MelodyOptions.Once, + //% block="background" + Background = MelodyOptions.OnceInBackground +} + enum MusicEvent { //% block="melody note played" MelodyNotePlayed = 1, @@ -349,6 +358,20 @@ namespace music { } } + /** + * Stops the melodies + * @param options which melody to stop + */ + //% help=music/stop-melody weight=59 blockGap=16 + //% blockId=device_stop_melody block="stop melody $options" + //% parts="headphone" + export function stopMelody(options: MelodyStopOptions) { + if (options & MelodyStopOptions.Foreground) + beginMelody([], MelodyOptions.Once); + if (options & MelodyStopOptions.Background) + beginMelody([], MelodyOptions.OnceInBackground); + } + /** * Sets a custom playTone function for playing melodies */