From 60ec3f1c99636095baabed189d8f5fdf1e7be1eb Mon Sep 17 00:00:00 2001 From: Galen Nickel Date: Thu, 22 Feb 2018 16:23:07 -0800 Subject: [PATCH] Add 'playSound' api docs (#340) * Add 'playSound' api docs * Linkup summary --- docs/SUMMARY.md | 12 +++++ libs/music/docs/reference/music.md | 15 ++++++ .../music/play-sound-effect-until-done.md | 54 +++++++++++++++++++ .../docs/reference/music/play-sound-effect.md | 29 ++++++++++ libs/music/sounds.ts | 4 +- 5 files changed, 113 insertions(+), 1 deletion(-) create mode 100644 libs/music/docs/reference/music.md create mode 100644 libs/music/docs/reference/music/play-sound-effect-until-done.md create mode 100644 libs/music/docs/reference/music/play-sound-effect.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index e8ffade5..880e1b33 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -111,6 +111,18 @@ * [pause for light](/reference/sensors/color-sensor/pause-for-light) * [color](/reference/sensors/color-sensor/color) * [light](/reference/sensors/color-sensor/ambient-light) + * [Music](/reference/music) + * [play sound effect](/reference/music/play-sound-effect) + * [play sound effect until done](/reference/music/play-sound-effect-until-done) + * [play tone](/reference/music/play-tone) + * [ring tone](/reference/music/ring-tone) + * [stop all sounds](/reference/music/stop-all-sounds) + * [rest](/reference/music/rest) + * [change tempo by](/reference/music/change-tempo-by) + * [set tempo](/reference/music/set-tempo) + * [note frequency](/reference/music/note-frequency) + * [beat](/reference/music/beat) + * [set volume](/reference/music/set-volume) * [Control](/reference/control) * [Timer](/reference/control/timer) * [seconds](/reference/control/timer/seconds) diff --git a/libs/music/docs/reference/music.md b/libs/music/docs/reference/music.md new file mode 100644 index 00000000..b722fe1c --- /dev/null +++ b/libs/music/docs/reference/music.md @@ -0,0 +1,15 @@ +# Music + +```cards +music.playSoundEffect(null) +music.playSoundEffectUntilDone(null) +music.stopAllSounds() +music.playTone(0, 0) +music.ringTone(Note.C) +music.rest(100) +music.changeTempoBy(20) +music.setTempo(120) +music.noteFrequency(Note.C) +music.beat() +music.setVolume(50) +``` \ No newline at end of file diff --git a/libs/music/docs/reference/music/play-sound-effect-until-done.md b/libs/music/docs/reference/music/play-sound-effect-until-done.md new file mode 100644 index 00000000..55981e8a --- /dev/null +++ b/libs/music/docs/reference/music/play-sound-effect-until-done.md @@ -0,0 +1,54 @@ +# play Sound Effect Until Done + +Play a sound from one of the built-in sound effect until it completes. + +```sig +music.playSoundEffectUntilDone(null) +``` + +There are several sound effects you can play. Use the sounds list in the block to pick the sound you want to play. The sound plays and this part of your program waits until the sound finishes. Other parts of your program, like code in **forever** loops and **runInParallel** blocks will continue to run though. + +Many of the built-in sound effects make sounds match to the actions that your @boardname@ is doing. For example, you can add the ``mechanical motor start`` sound your program to indicate that your motors are running. + +## Parameters + +* **sound**: a built-in sound effect from the list of available sounds. + +## Example + +Make a game where the buttons on the brick are used to guess a number from `1` to `4` that your program randomly chooses. On the correct guess, flash a ``green`` status light and play a cheering sound. The ``enter`` button resets the game to play again. + +```blocks +let pick = 0 +brick.buttonEnter.onEvent(ButtonEvent.Pressed, function () { + pick = 0 + music.stopAllSounds() + brick.setStatusLight(StatusLight.Off) +}) +brick.buttonDown.onEvent(ButtonEvent.Pressed, function () { + pick = 1 +}) +brick.buttonLeft.onEvent(ButtonEvent.Pressed, function () { + pick = 2 +}) +brick.buttonRight.onEvent(ButtonEvent.Pressed, function () { + pick = 3 +}) +brick.buttonUp.onEvent(ButtonEvent.Pressed, function () { + pick = 4 +}) +forever(function () { + if (pick > 0) { + if (Math.randomRange(0, 3) + 1 == pick) { + brick.setStatusLight(StatusLight.GreenFlash) + music.playSoundEffectUntilDone(sounds.expressionsCheering) + } + pick = 0 + } + pause(300) +}) +``` + +## See also + +[play sound effect](/reference/music/play-sound-effect), [stop all sounds](/reference/music/stop-all-sounds) \ No newline at end of file diff --git a/libs/music/docs/reference/music/play-sound-effect.md b/libs/music/docs/reference/music/play-sound-effect.md new file mode 100644 index 00000000..af9e7937 --- /dev/null +++ b/libs/music/docs/reference/music/play-sound-effect.md @@ -0,0 +1,29 @@ +# play Sound Effect + +Play a sound from one of the built-in sound effects. + +```sig +music.playSoundEffect(null) +``` + +There are several sound effects you can play. Use the sounds list in the block to pick the sound you want to play. When the sounds starts, your program continues on and doesn't wait for the sound to finish. This lets your program do other things while your sound plays in the _background_. + +Many of the built-in sound effects make sounds match to the actions that your @boardname@ is doing. For example, you can add the ``mechanical motor start`` sound to your program to indicate that your motors are running. + +## Parameters + +* **sound**: a built-in sound effect from the list of available sounds. + +## Example + +Drive the brick backwards and play a backup alert sound. + +```blocks +music.playSoundEffect(sounds.mechanicalBackingAlert); +motors.largeBC.tank(-50, -50, 15, MoveUnit.Rotations); +music.stopAllSounds(); +``` + +## See also + +[play sound effect until done](/reference/music/play-sound-effect-until-done), [stop all sounds](/reference/music/stop-all-sounds) \ No newline at end of file diff --git a/libs/music/sounds.ts b/libs/music/sounds.ts index b073970f..6d2f35a1 100644 --- a/libs/music/sounds.ts +++ b/libs/music/sounds.ts @@ -260,11 +260,12 @@ namespace music { const soundsLimit = 1; /** - * Plays a sound + * Play a sound and wait until it finishes * @param sound the sound to play */ //% blockId=music_play_sound_effect_until_done block="play sound effect %sound|until done" //% weight=98 blockGap=8 + //% help=music/play-sound-effect-until-done export function playSoundEffectUntilDone(sound: Sound) { if (!sound || numSoundsPlaying >= soundsLimit) return; numSoundsPlaying++; @@ -288,6 +289,7 @@ namespace music { */ //% blockId=music_play_sound_effect block="play sound effect %sound" //% weight=99 blockGap=8 + //% help=music/play-sound-effect export function playSoundEffect(sound: Sound) { if (!sound || numSoundsPlaying >= soundsLimit) return; numSoundsPlaying++;