diff doc/Codec-utils @ 305:a053cf0bac04

doc/Codec-utils: update for libgsmfr2
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 15 Apr 2024 23:41:39 +0000
parents 04936af99fc8
children b094bc07051a
line wrap: on
line diff
--- a/doc/Codec-utils	Mon Apr 15 23:12:10 2024 +0000
+++ b/doc/Codec-utils	Mon Apr 15 23:41:39 2024 +0000
@@ -8,12 +8,12 @@
 programs, the present package offers equivalent command line utilities for GSM
 FR and EFR codecs.  Here they are:
 
-gsmfr-encode	This utility reads linear PCM from a WAV file, runs libgsm
-		06.10 encoder and writes the output in the classic .gsm format
-		(directly abutted FR codec frames of 33 bytes each).  We don't
-		currently have a Tx-side DTX implementation (VAD etc) for GSM
-		FR, hence the output from gsmfr-encode will always consist of
-		good speech frames only.
+gsmfr-encode	This utility reads linear PCM from a WAV file, runs the
+		bit-exact GSM 06.10 encoder and writes the output in the
+		classic .gsm format (directly abutted FR codec frames of 33
+		bytes each).  We don't currently have a Tx-side DTX
+		implementation (VAD etc) for GSM-FR, hence the output from
+		gsmfr-encode will always consist of good speech frames only.
 
 gsmfr-decode	This utility reads our gsmx format (see Binary-file-format
 		article), which is a superset of the classic libgsm format.
@@ -22,9 +22,9 @@
 		can also contain SID frames and/or BFI markers.  The processing
 		performed by gsmfr-decode begins with our FR1 Rx DTX handler
 		preprocessor, which will be an identity transform for pure .gsm
-		input but becomes important for real-world input containing SIDs
-		and BFIs, and is followed by gsm_decode() from libgsm.  The
-		decoded output is written as WAV.
+		input (most of the time) but becomes important for real-world
+		input containing SIDs and BFIs, and is followed by the bit-exact
+		GSM 06.10 decoder.  The decoded output is written as WAV.
 
 gsmefr-encode	This utility reads linear PCM from a WAV file, runs our EFR
 		encoder (Themyscira libgsmefr) and writes the output in our gsmx
@@ -46,3 +46,22 @@
 gsmefr-decode-r
 
 Please see PCM-file-formats article for the rationale.
+
+Additions for libgsmfr2
+=======================
+
+With the introduction of libgsmfr2, gsmfr-* codec utilities have undergone some
+changes:
+
+* gsmfr-decode and gsmfr-decode-r now implement the optional decoder homing
+  feature, detecting and acting upon GSM 06.10 decoder homing frames.
+
+* gsmfr-encode-r takes an optional -h flag that enables the encoder homing
+  function; it is disabled by default.  The same feature was not replicated in
+  WAV-reading gsmfr-encode, as WAV format is poorly suited for tinkering-
+  oriented bit-exact work.
+
+* There is a new utility named gsmfr-decode-rb, where rb stands for "raw basic".
+  This utility emits "robe" output like gsmfr-decode-r, but it performs only
+  "basic" GSM 06.10 decoding, without the Rx DTX preprocessor step.  BFI frame
+  gaps in input are not allowed, and there is no SID detection.