From 1dd448f4ac789bfd14760e91cd7b666dda31e4d3 Mon Sep 17 00:00:00 2001
From: ganicke <gnickel@aquent.com>
Date: Wed, 20 Sep 2023 17:58:51 -0700
Subject: [PATCH 1/3] this block is hidden now

---
 docs/reference/music.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/reference/music.md b/docs/reference/music.md
index a00685f5c94..d595b112a63 100644
--- a/docs/reference/music.md
+++ b/docs/reference/music.md
@@ -12,7 +12,6 @@ music.createSong(hex`00780004080200`)
 
 ```cards
 music.stringPlayable("", 120)
-music.melodyPlayable(music.baDing)
 ```
 
 ## Sound
@@ -36,7 +35,6 @@ music.stopAllSounds()
 [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),

From 8e05cc6446bf2f35f9a28823d4604d0647d77ad0 Mon Sep 17 00:00:00 2001
From: ganicke <gnickel@aquent.com>
Date: Wed, 20 Sep 2023 18:45:03 -0700
Subject: [PATCH 2/3] try and fix the main music page

---
 docs/reference/music.md | 37 +++++++++++++++++++++++++------------
 1 file changed, 25 insertions(+), 12 deletions(-)

diff --git a/docs/reference/music.md b/docs/reference/music.md
index d595b112a63..8f5e3aaca6d 100644
--- a/docs/reference/music.md
+++ b/docs/reference/music.md
@@ -1,24 +1,36 @@
 # Music
 
-Make music. Play melodies and tones.
+Make music! Play songs, melodies, sounds, and tones.
 
-## Songs
+## Play music
+
+Use  the ``||music:play||`` block to play a song you compose, a short melody, or a built-in sound.
 
 ```cards
-music.createSong(hex`00780004080200`)
+music.play(music.createSong(hex`00780004080200`), music.PlaybackMode.UntilDone)
 ```
 
-## Melodies
+### Play a song
 
-```cards
-music.stringPlayable("", 120)
+```block
+music.play(music.createSong(hex`0078000408020200001c00010a006400f40164000004000000000000000000000000000500000430000400080001220c001000012514001800011e1c00200001222400280001252c003000012934003800012c3c004000011e03001c0001dc00690000045e010004000000000000000000000564000104000330000400080001290c001000011e1400180001251c002000012924002800011b2c003000012234003800011e3c0040000129`), music.PlaybackMode.UntilDone)
+```
+
+### Play a melody
+
+```block
+music.play(music.stringPlayable("D F E A E A C B ", 120), music.PlaybackMode.UntilDone)
+```
+
+### Play a built-in sound
+
+```block
+music.play(music.melodyPlayable(music.wawawawaa), music.PlaybackMode.UntilDone)
 ```
 
 ## Sound
 
 ```cards
-music.play(null, music.PlaybackMode.UntilDone)
-music.tonePlayable(262, music.beat(BeatFraction.Whole))
 music.ringTone(0)
 music.rest(0)
 music.noteFrequency(Note.C)
@@ -30,16 +42,17 @@ music.setVolume(0)
 music.stopAllSounds()
 ```
 
-## See Also
+## See also
 
 [play](/reference/music/play),
-[tone playable](/reference/music/tone-playable),
-[string playable](/reference/music/string-playable),
 [create song](/reference/music/create-song),
+[string playable](/reference/music/string-playable),
+[tone playable](/reference/music/tone-playable),
 [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),
-[set voluime](/reference/music/set-volume)
+[set voluime](/reference/music/set-volume),
+[stop All Sounds](reference/music/stop-all-sounds)

From 09e383f352ea2bec9753e9dcadea5546d44e0545 Mon Sep 17 00:00:00 2001
From: Galen Nickel <gnickel@aquent.com>
Date: Mon, 25 Sep 2023 21:38:38 -0700
Subject: [PATCH 3/3] update with sound effect blocks

---
 docs/reference/music.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/docs/reference/music.md b/docs/reference/music.md
index 8f5e3aaca6d..74ae765cce0 100644
--- a/docs/reference/music.md
+++ b/docs/reference/music.md
@@ -28,6 +28,19 @@ music.play(music.stringPlayable("D F E A E A C B ", 120), music.PlaybackMode.Unt
 music.play(music.melodyPlayable(music.wawawawaa), music.PlaybackMode.UntilDone)
 ```
 
+### Play a sound effect
+
+```blocks
+music.play(music.createSoundEffect(WaveShape.Sine, 5000, 0, 255, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear), music.PlaybackMode.UntilDone)
+```
+
+## Sound effects
+
+```cards
+music.createSoundEffect(WaveShape.Sine, 5000, 0, 255, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear)
+music.randomizeSound(music.createSoundEffect(WaveShape.Sine, 5000, 0, 255, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear))
+```
+
 ## Sound
 
 ```cards
@@ -48,6 +61,8 @@ music.stopAllSounds()
 [create song](/reference/music/create-song),
 [string playable](/reference/music/string-playable),
 [tone playable](/reference/music/tone-playable),
+[create sound effect](/reference/music/create-sound-effect),
+[randomize sound](/reference/music/randomize-sound),
 [ring tone](/reference/music/ring-tone), 
 [rest](/reference/music/rest),
 [beat](/reference/music/beat),