--- a/doc/Calypso-TCH-downlink	Wed May 15 06:20:59 2024 +0000
+++ b/doc/Calypso-TCH-downlink	Sat May 18 00:13:26 2024 +0000
@@ -117,3 +117,83 @@
   parsed bits, the correct approach is to convert the VM file to gsmx with
   fc-vm2gsmx, and then decode with gsmfr-decode.  Using fc-vm2hex followed by
   gsmfr-dlcap-gsmx instead of fc-vm2gsmx won't work!
+
+Catching the output of the network-side speech encoder
+======================================================
+
+The set of FR1 test sequences included with later versions of GSM 06.10 specs
+and the set of EFR test sequences in GSM 06.54 include special synchronization
+sequences that can be fed to the G.711 PCMA or PCMU input of the TRAU in the
+downlink direction, and the set of 160 possible speech encoder outputs for each
+codec that can result from the TRAU processing that DL input, depending on the
+alignment between the input and the location of 20 ms frame boundaries for the
+encoder.  In the case of EFR, there is a second dimension of uncertainty when
+experimenting with GSM networks that aren't your own: in addition to the unknown
+alignment of G.711 input (160 possibilities), there is the unknown of whether
+the network transcoder implements classic EFR or an AMR-EFR hybrid - see our
+AMR-EFR-philosophy and AMR-EFR-hybrid-emu articles.  However, thanks to the work
+we did in vband-misc Hg repository, we now have a fully backward-compatible
+extended version of ETSI's seqsync[au].inp TRAU DL inputs (the last frame of
+160 samples that isn't EHF is simply repeated twice) that allows us to
+distinguish between two possible styles of EFR implementation in the network
+transcoder, producing 320 possible outputs on GSM Um DL for 160 possible
+alignments times two possible EFR implementation options.
+
+However, tools are still needed on the GSM MS side of the test setup, reading
+the TCH DL capture produced with FreeCalypso tools and detecting which of the
+possible 160 (FR1) or 320 (EFR) encoded frames have been produced.  (320 or
+even 160 possible frames is too many to check by hand!)  These tools are
+provided in gsmfr-dlcap-sync and gsmefr-dlcap-sync, added to Themyscira GSM
+codec libraries and utilities suite as of gsm-codec-lib-r3.  Each of these
+utilities takes two command line arguments: the name of TCH DL capture file to
+read and analyze, and an "alaw" or "ulaw" keyword argument selecting the match
+table to use.  Specify alaw if you are feeding seqsynca.inp to a PCMA-native
+TRAU or other GSM network speech transcoder, or ulaw if you are feeding
+seqsyncu.inp to a PCMU-native network.  The program will read the entire TCH DL
+capture, looking for matches, and will report any matches it finds.
+
+Both gsmfr-dlcap-sync and gsmefr-dlcap-sync implement the logic of looking for
+the respective codec's DHF followed by one of 160 (FR1) or 320 (EFR) distinct
+encoded frames.  In the case of EFR, if the network transcoder implements
+AMR-EFR and the alignment shift happens to be in the [120,159] range, there
+will also be an MR122 DHF sandwiched between the standard EFR DHF and the
+distinct encoded frame (unique for each of the 40 possible alignments in this
+range) if the AMR-EFR hybrid is implemented like our amr_dhf_subst_efr2()
+function, matching the network of T-Mobile USA.  gsmefr-dlcap-sync looks for
+both EFR and MR122 DHF; in the case of matches to AMR-EFR offset [120,159], the
+tool's indication whether the unique frame was preceded by EFR or MR122 DHF
+indicates how the alien network transcoder implements its DHF transformation;
+in the case of other matches, seeing MR122 DHF is an unexpected error condition,
+and it is reported as such.
+
+These tools cover just one step in the workflow of reverse-engineering an alien
+GSM network's speech transcoder and confirming if it matches standard EFR or
+the AMR-EFR hybrid as currently found in the wild.  The complete workflow in
+the GSM downlink direction will typically be as follows:
+
+1) Using sipout-test-voice utility from the sipout-test-utils suite, establish
+   a test call from IP-PSTN to a test MS served by the GSM network under study.
+   AT%SPVER will typically need to be used to cause the network to assign the
+   desired codec on this call.
+
+2) While making a TCH DL recording on the FreeCalypso MS used in this test,
+   play seqsync[au].inp (or the extended version with the last frame sent twice)
+   into the G.711 PCM stream from IP-PSTN side, using 'play' command of
+   sipout-test-voice.
+
+3) Run gsmfr-dlcap-sync or gsmefr-dlcap-sync on the DL recording from the
+   previous step, as appropriate.
+
+4) Once the alignment is known, use 'play-offset' command in sipout-test-voice
+   to play a longer test sequence into the same call, and have another TCH DL
+   recording running on the test MS.
+
+5) If the longer test sequence begins with the same seqsync[au].inp preamble
+   (which is recommended), playing it with the correct offset from IP-PSTN side
+   should result in gsm[e]fr-dlcap-sync reporting zero offset on the new DL
+   recording.  However, gsm[e]fr-dlcap-sync on this second DL capture should
+   indicate the line number where the interesting part begins.
+
+6) Extract the part of interest identified in the previous step, convert it to
+   gsmx format with gsm[e]fr-dlcap-gsmx, and compare it against the expected
+   encoded frame sequence.