# HG changeset patch
# User Mychaela Falconia <falcon@freecalypso.org>
# Date 1681631721 0
# Node ID 5216e7fb1c9e5405d6a8a5d58358fba13d5071b7
# Parent  50aa973a91ef3ca04d169c919cc07ce9ebe2e9b3
doc: update for new FR/EFR RTP payload formats

diff -r 50aa973a91ef -r 5216e7fb1c9e doc/FR-EFR-formats
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/FR-EFR-formats	Sun Apr 16 07:55:21 2023 +0000
@@ -0,0 +1,21 @@
+The two RTP analysis utilities rtp-gsmfr-dump and rtp-gsmfr-extr support the
+following RTP payload formats for FR/EFR codec frames and BFI markers:
+
+* Standard RFC 3551 (same as TS 101 318) format for good frames
+
+* TRAUlike RTP payload format defined here:
+
+https://www.freecalypso.org/hg/themwi-system-sw/file/tip/doc/RTP-TRAUlike-format
+
+* Old BFI marker format defined here:
+
+https://www.freecalypso.org/hg/themwi-system-sw/file/tip/doc/RTP-BFI-extension
+
+* Zero-length RTP payload serving as a BFI marker
+
+All of these formats are distinguished by rtp-gsmfr-dump in its human-oriented
+dump output, but not all of them can be represented losslessly in the gsmx
+binary file format defined in our Themyscira Wireless GSM codec libraries and
+utilities package.  The latter on-disk file format requires plain RFC 3551
+format for good frames and the old Themyscira 2-byte BFI marker format for bad
+frames; rtp-gsmfr-extr converts everything into this fixed format.
diff -r 50aa973a91ef -r 5216e7fb1c9e doc/RTP-analysis
--- a/doc/RTP-analysis	Sun Apr 16 06:43:18 2023 +0000
+++ b/doc/RTP-analysis	Sun Apr 16 07:55:21 2023 +0000
@@ -29,17 +29,18 @@
 		selected G.711 RTP stream is then extracted and written into a
 		raw binary file.
 
-rtp-gsmfr-extr	This program focuses on a single selected RTP stream like the
-		others, enforces its continuity just like rtp-cont-check, but
-		then further enforces that every RTP packet be one of these 3
-		possibilities: a GSM FR1 codec frame, a GSM EFR codec frame or
-		a Themyscira BFI marker as defined in the RTP-BFI-extension
-		document.  (The payload type number is NOT considered, only the
-		payload length and the characteristic signature of each of the
-		3 allowed possibilities.)  The selected RTP stream is then
-		extracted and written into a gsmx file (see Binary-file-format),
-		which can then be analyzed with gsmrec-dump or decoded to
-		playable WAV with gsmfr-decode or gsmefr-decode.
+rtp-gsmfr-dump	This program focuses on a single selected RTP stream like the
+		others, enforces its continuity just like rtp-cont-check, and
+		then expects the RTP payload to be one of GSM FR or EFR formats
+		listed in the FR-EFR-formats document.  Each recognized FR/EFR
+		or BFI payload is then dumped in human-readable form on stdout,
+		similarly to the gsmrec-dump utility from Themyscira Wireless
+		GSM codec libraries & utilities package.
+
+rtp-gsmfr-extr	This program operates like rtp-gsmfr-dump, imposing the same
+		expectations on the selected RTP stream, but the latter stream
+		is then extracted and written into a gsmx binary file, as
+		defined in the GSM codec libraries and utilities package.
 
 rtp-jitter-view	This program analyzes a single selected RTP stream just like
 		rtp-cont-check, but instead of reporting minimum and maximum