--- a/doc/Buzzer-melodies	Mon Mar 28 06:30:09 2022 +0000
+++ b/doc/Buzzer-melodies	Tue Mar 29 07:49:05 2022 +0000
@@ -73,19 +73,73 @@
 Therefore, it makes the best sense to reckon all note durations in our buzzer
 melodies in TDMA frames to begin with.
 
-FC host tools support for buzzer melodies
-=========================================
+2022 addition: BUZM melody player engine in FC Tourmaline
+=========================================================
+
+As of 2022 our FC Tourmaline firmware includes a new buzzer melody player
+engine, implemented as a RiViera-based service named BUZM.  The new BUZM service
+sits on top of the low-level PWT buzzer driver in the same way how RiViera
+Audio service sits on top of the low-level DSP+L1 combo, and the API (directed
+toward UI firmware layers) of the new BUZM service is modeled after that of RV
+Audio service.  The primary objective of this BUZM venture is to get rid of the
+Condat audio driver layer mess which we inherited from TI (it has buzzer ringing
+and audio tone generation entangled together in a gnarly way which we need to
+move away from), but this migration also provides a secondary benefit: instead
+of being hard-coded, buzzer melodies will now be read from files in FFS, just
+like E1 melodies for loudspeaker-based ringing, allowing our UI firmware design
+to be harmonized between the two ringer configurations.
+
+The following design decisions underlie our new FC Tourmaline buzzer melody
+facility:
+
+* Regarding the choice between BU or PWT driving, PWT has been chosen.  All
+  melodies created for playing via BUZM need to consist of musical notes F4
+  through E8 (scientific pitch notation, 349 to 5274 Hz), as supported by
+  Calypso PWT block.
+
+* Each melody is a sequence of sounded tones (PWT), either directly abutted or
+  separated by pauses.  In actual implementation, each melody is a sequence of
+  directly abutted entries, where each entry can be either a sounded tone or a
+  pause.  Each entry (tone or silence) has a duration, reckoned in TDMA frames
+  as explained above.
+
+* For every sounded tone in a melody, a note volume in the range [1,64] is
+  given.  If the melody is played at maximum volume, the per-note volumes will
+  be written directly into the hardware register (PWM control in 1/64 units).
+  If the user-specified play volume is less than 64, the actual sounding volume
+  of each note is determined as (play_volume * note_volume / 64), with the
+  division step rounding up - when both play_volume and note_volume are
+  constrained in the [1,64] range, the result of the rounding-up division is
+  also constrained in the same range.
+
+In terms of tool support, each FreeCalypso PWT buzzer melody begins life as an
+ASCII text source in the format defined by us.  It is then compiled into binary
+form with our fc-pwt-comp utility, and the resulting binary melody file is
+uploaded into FreeCalypso device FFS.  For manual testing, each uploaded buzzer
+melody can be played with AT@BUZ command.  For finished phone operation, there
+will be two ringtone list files (one for play-until-answer ringing tones and
+one for non-repeating message alert tones) that will drive ringtone selection
+in the phone UI.
+
+The format of ASCII source files for PWT melodies is best documented by
+examples: see several in the ringtools/examples directory.
+
+Standalone buzzer exercising (outside of FC firmware)
+=====================================================
 
 We have a target utility (running on Calypso devices out of RAM) called
 buzplayer, and a front end host program called fc-buzplay.  If you load and run
 buzplayer manually via fc-iram, you can use it to exercise the buzzer manually,
-playing any tone at any volume, in either BU or PWT mode.  fc-buzplay is a
-higher-level tool that reads buzzer melodies from ASCII text files (our own
-simple ad hoc format), feeds them to buzplayer on the target, and commands
-buzplayer to play the uploaded melody.
+playing any tone at any volume, in either BU or PWT mode.
 
-Further documentation will be written if and when a more actual need arises for
-this functionality - right now the primary direction within FreeCalypso is
-toward our own handset hardware, and the Mother's intent for our FreeCalypso
-Libre Dumbphone handset is to use a loudspeaker and Melody E1 for ringtone
-generation, as opposed to the buzzer output.
+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.)