gsm-codec-lib: doc/Codec-utils annotate

author	Mychaela Falconia <falcon@freecalypso.org>
date	Fri, 20 Sep 2024 00:17:35 +0000 (13 months ago)
parents	751f06541fbb
children	de333989a12b

rev	line source
136 8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	1 Standalone command line utilities for FR and EFR codecs
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	2 =======================================================
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	3
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	4 The pre-existing FOSS opencore-amr package includes amrnb-enc and amrnb-dec test
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	5 programs: the first reads linear PCM from a WAV file and emits AMR encoder
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	6 output in a .amr file (RFC 4867 AMR storage format), the second reads this .amr
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	7 format and emits AMR decoder output as WAV. Inspired by these simple test
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	8 programs, the present package offers equivalent command line utilities for GSM
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	9 FR and EFR codecs. Here they are:
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	10
305 a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	11 gsmfr-encode This utility reads linear PCM from a WAV file, runs the
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	12 bit-exact GSM 06.10 encoder and writes the output in the
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	13 classic .gsm format (directly abutted FR codec frames of 33
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	14 bytes each). We don't currently have a Tx-side DTX
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	15 implementation (VAD etc) for GSM-FR, hence the output from
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	16 gsmfr-encode will always consist of good speech frames only.
136 8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	17
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	18 gsmfr-decode This utility reads our gsmx format (see Binary-file-format
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	19 article), which is a superset of the classic libgsm format.
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	20 The input to gsmfr-decode may be a pure .gsm recording as
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	21 produced by gsmfr-encode or toast from libgsm package, or it
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	22 can also contain SID frames and/or BFI markers. The processing
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	23 performed by gsmfr-decode begins with our FR1 Rx DTX handler
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	24 preprocessor, which will be an identity transform for pure .gsm
305 a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	25 input (most of the time) but becomes important for real-world
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	26 input containing SIDs and BFIs, and is followed by the bit-exact
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	27 GSM 06.10 decoder. The decoded output is written as WAV.
136 8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	28
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	29 gsmefr-encode This utility reads linear PCM from a WAV file, runs our EFR
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	30 encoder (Themyscira libgsmefr) and writes the output in our gsmx
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	31 format. There is an option to enable or disable DTX: -d enables
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	32 DTX, otherwise it is disabled. (This option mirrors amrnb-enc.)
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	33
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	34 gsmefr-decode This utility reads our gsmx format (which must be EFR, not FR1)
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	35 and feeds all frames and BFIs to our EFR decoder. The decoded
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	36 output is written as WAV.
8eb0e7a39409 doc: document command line utilities Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	37
157 04936af99fc8 document gsm[e]fr-{en,de}code-r utilities Mychaela Falconia <falcon@freecalypso.org> parents: 144 diff changeset	38 The above are original programs that read WAV input for encoding and write WAV
04936af99fc8 document gsm[e]fr-{en,de}code-r utilities Mychaela Falconia <falcon@freecalypso.org> parents: 144 diff changeset	39 output from decoding. We now also have raw versions that read and write our
04936af99fc8 document gsm[e]fr-{en,de}code-r utilities Mychaela Falconia <falcon@freecalypso.org> parents: 144 diff changeset	40 "robe" (raw big-endian) format instead:
144 30c7bc064218 doc/Codec-utils: add note about PCM file format issue Mychaela Falconia <falcon@freecalypso.org> parents: 136 diff changeset	41
157 04936af99fc8 document gsm[e]fr-{en,de}code-r utilities Mychaela Falconia <falcon@freecalypso.org> parents: 144 diff changeset	42 gsmfr-encode-r Just like gsm[e]fr-encode, but reading "robe" instead of WAV.
04936af99fc8 document gsm[e]fr-{en,de}code-r utilities Mychaela Falconia <falcon@freecalypso.org> parents: 144 diff changeset	43 gsmefr-encode-r
04936af99fc8 document gsm[e]fr-{en,de}code-r utilities Mychaela Falconia <falcon@freecalypso.org> parents: 144 diff changeset	44
04936af99fc8 document gsm[e]fr-{en,de}code-r utilities Mychaela Falconia <falcon@freecalypso.org> parents: 144 diff changeset	45 gsmfr-decode-r Just like gsm[e]fr-decode, but writing "robe" instead of WAV.
04936af99fc8 document gsm[e]fr-{en,de}code-r utilities Mychaela Falconia <falcon@freecalypso.org> parents: 144 diff changeset	46 gsmefr-decode-r
04936af99fc8 document gsm[e]fr-{en,de}code-r utilities Mychaela Falconia <falcon@freecalypso.org> parents: 144 diff changeset	47
04936af99fc8 document gsm[e]fr-{en,de}code-r utilities Mychaela Falconia <falcon@freecalypso.org> parents: 144 diff changeset	48 Please see PCM-file-formats article for the rationale.
305 a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	49
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	50 Additions for libgsmfr2
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	51 =======================
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	52
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	53 With the introduction of libgsmfr2, gsmfr-* codec utilities have undergone some
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	54 changes:
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	55
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	56 * gsmfr-decode and gsmfr-decode-r now implement the optional decoder homing
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	57 feature, detecting and acting upon GSM 06.10 decoder homing frames.
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	58
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	59 * gsmfr-encode-r takes an optional -h flag that enables the encoder homing
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	60 function; it is disabled by default. The same feature was not replicated in
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	61 WAV-reading gsmfr-encode, as WAV format is poorly suited for tinkering-
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	62 oriented bit-exact work.
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	63
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	64 * There is a new utility named gsmfr-decode-rb, where rb stands for "raw basic".
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	65 This utility emits "robe" output like gsmfr-decode-r, but it performs only
a053cf0bac04 doc/Codec-utils: update for libgsmfr2 Mychaela Falconia <falcon@freecalypso.org> parents: 157 diff changeset	66 "basic" GSM 06.10 decoding, without the Rx DTX preprocessor step. BFI frame
485 751f06541fbb doc/Codec-utils: clarify lack of DHF in gsmfr-decode-rb Mychaela Falconia <falcon@freecalypso.org> parents: 459 diff changeset	67 gaps in input are not allowed, and there is no SID or DHF detection.
459 b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	68
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	69 Standalone command line utilities for AMR codec
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	70 ===============================================
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	71
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	72 As described above, gsm[e]fr-encode and gsm[e]fr-decode were modeled after
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	73 amrnb-enc and amrnb-dec from opencore-amr, a piece of pre-existing FOSS.
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	74 However, now that we have libtwamr, a Themyscira library for AMR codec that is
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	75 designed to serve as a replacement for libopencore-amrnb in our workflows
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	76 involving AMR, we also have our own twamr-encode and twamr-decode utilities
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	77 that directly replace amrnb-enc and amrnb-dec.
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	78
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	79 twamr-encode is a functional replacement for amrnb-enc: it reads 16-bit linear
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	80 PCM speech input from a WAV file and writes the AMR encoder output in a .amr
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	81 file (RFC 4867 storage format). However, there is a difference in the command
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	82 line structure and a small difference in operation. The command line structure
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	83 of twamr-encode is as follows:
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	84
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	85 twamr-encode [-d] [-2] input.wav mode output.amr
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	86
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	87 The middle argument specifies the codec mode to be used; there is no default.
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	88 Ordinarily the mode argument is one of these 8 keywords:
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	89
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	90 MR475
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	91 MR515
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	92 MR59
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	93 MR67
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	94 MR74
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	95 MR795
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	96 MR102
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	97 MR122
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	98
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	99 However, this mode argument can also take the form of "file:$modefile", where
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	100 $modefile is an ASCII text file giving one of the above mode keywords per line.
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	101 This form is not likely to be useful in casual twamr-encode usage, but it exists
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	102 for the sake of symmetry with twamr-tseq-enc program used for verification
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	103 testing with the official test sequences from 3GPP.
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	104
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	105 Aside from this difference in the command line structure, the small functional
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	106 difference between amrnb-enc and twamr-encode is that libopencore-amrnb (the
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	107 engine underlying amrnb-enc) omits the codec homing feature, whereas libtwamr
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	108 (the engine underlying twamr-encode) implements the homing feature as a
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	109 mandatory part of the codec definition per 3GPP specs.
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	110
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	111 twamr-encode flag options: -d enables DTX, -2 switches the VAD algorithm from
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	112 VAD1 default to VAD2 alternative. The two options can be combined as -d2.
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	113
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	114 twamr-decode is a more straightforward replacement for amrnb-dec, with this
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	115 simple command line structure:
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	116
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	117 twamr-decode input.amr output.wav
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	118
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	119 The functional difference from amrnb-dec is once again in the codec homing
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	120 feature: present in libtwamr and hence twamr-decode, but absent in
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	121 libopencore-amrnb and hence amrnb-dec.
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	122
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	123 Finally, for the sake of completeness and symmetry with the other supported
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	124 codecs, the present suite includes twamr-encode-r and twamr-decode-r utilities.
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	125 They function just like twamr-encode and twamr-decode, with the same command
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	126 line structure, but the file format for 16-bit linear PCM speech is "robe"
b094bc07051a doc/Codec-utils: document twamr-* addition Mychaela Falconia <falcon@freecalypso.org> parents: 305 diff changeset	127 instead of WAV.

136

8eb0e7a39409 doc: document command line utilities