--- a/Speech-codec-selection	Tue Jun 06 01:47:36 2023 +0000
+++ b/Speech-codec-selection	Tue Jun 06 03:54:53 2023 +0000
@@ -165,3 +165,76 @@
 version, usually AT%MSCAP=37,00,00 or AT%MSCAP=B7,C7,00.
 
 Step 2: execute 'rm /pcm/MSCAP' in fc-fsio, deleting the file from FFS.
+
+Speech version preference list
+==============================
+
+Whenever a GSM MS supports any additional speech codecs beyond the always-
+required FRv1, it needs to indicate this support to the network in the Bearer
+capability IE.  However, the encoding of the relevant bits in this IE indicates
+not only which codecs the MS supports, but also their order of preference.
+Indicating the order of preference between supported codecs is not optional:
+the MS always has to transmit _some_ order-of-preference list toward the
+network.  (For GSM MS supporting FRv1 and HRv1 but no others, there is an
+abbreviated version of the Bearer capability IE with octet 3a list omitted, but
+even then the order of preference between the two supported codecs is still
+indicated via the two radio channel requirement bits.)
+
+Our current FreeCalypso TCS2/TCS3 hybrid firmware indicates the following order
+of preference to the network, between the 5 potentially supported codecs:
+
+AMR-FR > AMR-HR > EFR > FRv1 > HRv1
+
+(The '>' character in the above line indicates that the codec on the left is
+ preferred over the codec on the right.)
+
+The actual Bearer capability IE is constructed by first masking off each of the
+5 possible codecs as supported or not-supported per EF_MSCAP (see previous
+section), but those codecs that remain in the supported set are sent to the
+network in the order of preference following the above diagram.
+
+It appears that most GSM networks ignore the speech version preference order
+indicated by the MS, treating the MS-provided speech version list as an
+unordered checklist of supported or non-supported, and impose their own
+preference order set by network policy.  Such behavior is implemented in Osmocom
+CNI software, and is also observed on the legacy GSM network of T-Mobile USA as
+of this writing.  However, the world as a whole is big, there are many different
+GSM networks in different countries, and I (Mother Mychaela) deem it valuable to
+provide a mechanism whereby FreeCalypso-equipped GSM community members can test
+experimentally how their countries' GSM networks react to different speech
+version lists indicated by the MS, including peculiar preference orders.
+
+To facilitate such testing, FreeCalypso Tourmaline firmware provides a private
+debug-oriented AT command controlling the speech version list: AT%SPVER.  This
+command takes the following forms:
+
+AT%SPVER=0				-- restore standard behavior
+AT%SPVER=1,sv1[,sv2[,sv3[,sv4[,sv5]]]]]	-- set custom speech version list
+AT%SPVER?				-- query current setting
+
+In the second listed form of AT%SPVER command, arguments sv1 through sv5 are
+speech version codes as transmitted over the air in the Bearer capability IE,
+as given in Table 10.5.103/3GPP TS 24.008:
+
+0 = FRv1
+1 = HRv1
+2 = EFR
+4 = AMR-FR
+5 = AMR-HR
+
+The speech version list sent to the network will be exactly as given in the
+AT%SPVER command, in that order.  You can list just one speech version, or all
+5 of them, or any intermediate subset - but FRv1 (sv code 0) must always be
+included, or the AT%SPVER command will be rejected.  Some examples:
+
+AT%SPVER=1,0		-- declare support for FRv1 only
+AT%SPVER=1,2,0,1	-- declare support for EFR, FRv1 and HRv1 in this order
+AT%SPVER=1,1,0		-- prefer HRv1 over FRv1
+
+Unlike AT%MSCAP, the setting made with AT%SPVER is volatile: it is not saved
+anywhere in FFS, and thus does not persist across firmware boot cycles.
+
+In order to affect the Bearer capability IE in the Call confirmed message for
+MT calls, the AT%SPVER command needs to be given before the MT Setup message
+arrives from the network.  For MO call testing, it is sufficient to set AT%SPVER
+before dialing the MO call with ATD command.