--- a/doc/Buzzer-melodies	Sun Apr 03 08:41:34 2022 +0000
+++ b/doc/Buzzer-melodies	Sun Apr 03 08:53:53 2022 +0000
@@ -217,12 +217,13 @@
 
 fc-buzplay is a higher-level tool: it establishes out-of-firmware operation on
 a target Calypso device similarly to fc-loadtool (based on the same framework),
-but running buzplayer instead of loadagent.  The original command of meaty
-action was/is 'play' - it reads a BU (not PWT) melody from an ASCII source file
-in a format that was the predecessor of our current PWT format, feeds it to
-buzplayer on the target, and commands buzplayer to actually play it on the
-physical buzzer.  Later buzplayer (the target utility) was extended to support
-PWT in addition to BU, and fc-buzplay got a new 'playt' command - this new
-command plays PWT melodies, reading melody files in the same ASCII source format
-as fc-pwt-comp.  (In actual history this ASCII source format was invented for
-fc-buzplay first, and then later we turned it into fc-pwt-comp.)
+but running buzplayer instead of loadagent.  Once you land at the buzplay>
+prompt, the main command of interest is 'play': it takes one required argument,
+the name of the melody file to play (ASCII BU or PWT format), and a second
+optional argument, the play volume in the [1,64] range.  The current version of
+this 'play' command intuits the melody format (BU or PWT) from the filename,
+which must end in .buz or .pwt, respectively.  You can also issue explicit
+play-bu and play-pwt commands, in which case the filename can be anything.  All
+of these play command variants read the melody file in the respective format
+(ASCII in both cases, line-based), feed the melody to the target, and then
+command buzplayer to actually play it on the physical buzzer.