--- a/doc/Buzzer-melodies	Tue Mar 29 19:38:28 2022 +0000
+++ b/doc/Buzzer-melodies	Wed Mar 30 06:25:47 2022 +0000
@@ -124,6 +124,47 @@
 The format of ASCII source files for PWT melodies is best documented by
 examples: see several in the ringtools/examples directory.
 
+Organization of melodies in FC device FFS
+=========================================
+
+We shall have two types of ringtone melodies in FreeCalypso: PWT melodies to be
+played via the buzzer, and E1 melodies to be played via the voice path
+loudspeaker.  Naturally, buzzer melodies can only be played on hardware
+platforms that have a buzzer, and voice path loudspeaker melodies can only be
+played on hw platforms that have such a speaker.  The only platforms that can
+be expected to have both hw provisions are development boards like D-Sample and
+FC Venus - but even on those development boards, each given UI firmware build
+will support one or the other ringing type, but not both at the same time.
+
+We shall have two separate FFS subtrees for these two melody types: PWT melodies
+for the buzzer will be stored under /buz, whereas E1 melodies for the voice path
+will be stored under /mel.  Both trees will be constructed on the host system
+under /opt/freecalypso/buz and /opt/freecalypso/mel, and they will be uploaded
+into FC device FFS with fc-fsio:
+
+upload-subtree /opt/freecalypso/buz /buz
+upload-subtree /opt/freecalypso/mel /mel
+
+Individual melody files (compiled binary formats produced by fc-pwt-comp and
+fc-e1gen) will be stored as /buz/melodyname.bz and /mel/melodyname.e1 for the
+two types.  There will also be melody list or index files:
+
+/buz/ringtones.mls
+/buz/msgtones.mls
+/mel/ringtones.mls
+/mel/msgtones.mls
+
+Each ringtones.mls file (for the buzzer or for Melody E1) will list the
+available melodies for the continuous play-until-answer ringing tone, and each
+msgtones.mls file will list the available melodies for the non-repeating message
+alert tone.  The melody list (.mls) file format is defined by us: it is a binary
+format consisting of fixed-length records, one 80-byte record for each listed
+melody.  Each record consists of two fields: the FFS pathname (always absolute
+as required by the RTOS environment without current directories) of the melody
+file and the name of the melody for the selection menu in the phone UI.  Melody
+lists are compiled from line-based ASCII source into this binary format by our
+fc-ringlist-comp utility.
+
 Standalone buzzer exercising (outside of FC firmware)
 =====================================================