# HG changeset patch
# User Mychaela Falconia <falcon@freecalypso.org>
# Date 1649998526 0
# Node ID 78d4d362c08688f2dbc987fb9c4716af106e2edf
# Parent  8df29c96327adda645c7a92f30551ff782fcefc7
FC-handset-spec section 2.4.1: update for PWT melodies and BUZM

diff -r 8df29c96327a -r 78d4d362c086 FC-handset-spec
--- a/FC-handset-spec	Fri Apr 15 01:40:32 2022 +0000
+++ b/FC-handset-spec	Fri Apr 15 04:55:26 2022 +0000
@@ -1300,15 +1300,41 @@
    way of the same loudspeaker that will be used for hands-free calls, using the
    Melody E1 feature of Calypso DSP for ringtone melody generation.
 
-2.4.1. Scope limitation on buzzer melodies
+2.4.1. Approach to buzzer melodies
+
+My (Mother Mychaela's) original intention was to limit buzzer ringing support
+to the extremely crude implementation contained in the Condat audio "driver"
+abstraction layer - this demo/prototype/PoC code uses BU mode rather than PWT,
+and it only has one extremely basic ringing sound: alternating 800 Hz and 900 Hz
+tones, no melodies.  However, I have subsequently changed my mind on this point:
+upon further reflection, I realized that the audio "driver" in the Condat
+abstraction layer is a horrendous mess that needs to be cleaned up, and one
+very helpful step in cleaning it up will be to remove buzzer functionality from
+it.  Toward this end, I came up with a new architecture:
+
+* What little remains of the Condat audio "driver" layer (it will be thinned
+  significantly) will be only for simple audio tones (call waiting, busy,
+  ringing code for the calling party when the GSM network provides no IBT), and
+  it won't be involved in ringing, neither in the buzzer config nor in the
+  Melody E1 loudspeaker config.
 
-Because the option of ringing via Calypso buzzer output is retained only for
-lorekeeping and for minimal-support alien targets, no effort will be expended
-toward playing more musical melodies via the buzzer.  Our current code (bugfixed
-from TI's original) implements just one buzzer ringing sound, consisting of
-alternating 800 Hz and 900 Hz tones, using BU mode rather than PWT, and the
-Mother currently has no plans to implement anything more for the buzzer
-configuration.
+* For platforms that feature a magnetic buzzer, there is a new BUZM (buzzer
+  melody) service implemented in RiViera land (the part of fw architecture
+  where such application services properly belong), and this BUZM service plays
+  PWT buzzer melodies, rather than BU mode.  The bit-level format for these PWT
+  melodies is an original FreeCalypso invention, the necessary tool support for
+  it has been added to the FC host tools package as of fc-host-tools-r17, and
+  the necessary documentation is maintained in the same place.
+
+For the end user of a FreeCalypso phone that features an old-fashioned buzzer
+(e.g., FreeCalypso Lite aftermarket fw on Mot C139), the visible effect of this
+architecture change is that a decent selection of varied ringtone melodies can
+be implemented.  A basic ring that sounds just like TI's original BU version is
+still available in PWT mode (it is now composed of alternating G5 and A5 musical
+notes, rather than alternating 800 Hz and 900 Hz tones, but it sounds just the
+same at least to my ear), but we are now also able to play ringtone melodies of
+the same rich kind as those offered by Motorola in their official firmwares for
+buzzer-equipped phones.
 
 2.4.2. Melody E1 ringer