--- a/doc/Buzzer-melodies	Sun Apr 03 04:39:26 2022 +0000
+++ b/doc/Buzzer-melodies	Sun Apr 03 05:29:17 2022 +0000
@@ -169,6 +169,44 @@
 lists are compiled from line-based ASCII source into this binary format by our
 fc-ringlist-comp utility.
 
+Support for iMelody ringtones
+=============================
+
+Back in the olden days when dumbphones with monophonic buzzer-type ringers were
+the norm in society, there was a community of phone users who composed and
+exchanged their own ringtone melodies; the community standard format for those
+interchanges was EMS iMelody.  Searching around the Internet in 2022, I (Mother
+Mychaela) couldn't find any iMelody ringtones that sound any good - the only
+ones I could find sound like crap, nowhere near professional-quality melodies
+which we've lifted out of Motorola's firmware.  However, as a matter of due
+diligence, I felt that it would improper for FreeCalypso not to support iMelody
+ringtones, hence I wrote a program that groks iMelody files and converts those
+melodies to our native PWT format - this program is fc-imy2pwt.
+
+Right now fc-imy2pwt implements a subset of the iMelody spec; the missing
+features are:
+
+* All volume change commands in the melody are ignored: fc-imy2pwt does not
+  support per-note volume changes within the melody, and all PWT notes are
+  emitted at the maximum per-note volume of 64/64.
+
+* The STYLE setting in IMY files is ignored, and all melodies are converted as
+  if the style was S1, i.e., continuous, without automatically inserted rest
+  between notes.
+
+* All vibrator/LED/backlight control commands are ignored: in FreeCalypso
+  architecture there is no synchronization between ringtone melodies and
+  vibration cadence, instead the user selects between silent mode, ring only,
+  vibrate only or ring+vibrate alerting as needed, without interference from
+  overly-creative vanity melody composers.  Likewise, we do not support
+  melody-driven manipulation of any lights.
+
+The policies of keeping the ringer and the vibrator separate and of leaving our
+LCD and keypad backlights alone are absolute, whereas support for volume changes
+within the melody and for non-S1 styles (automatically inserted rest periods)
+can be implemented *if* someone in our community has a real use case for such
+functionality.
+
 Standalone buzzer exercising (outside of FC firmware)
 =====================================================
 

--- a/doc/Host-tools-overview	Sun Apr 03 04:39:26 2022 +0000
+++ b/doc/Host-tools-overview	Sun Apr 03 05:29:17 2022 +0000
@@ -148,6 +148,10 @@
 		the audio_vm_play_start() API or the AT@VMP command that
 		invokes the latter.
 
+fc-imy2pwt	This program converts monophonic ringtone melodies from iMelody
+		interchange format into our own native PWT format.  See the
+		Buzzer-melodies article for more details.
+
 fc-lcdemu	Moved to freecalypso-ui-dev repository; look there for more
 		info.