FreeCalypso > hg > gsm-codec-lib

comparison doc/Codec-utils @ 459:b094bc07051a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Codec-utils: document twamr-* addition
author Mychaela Falconia <falcon@freecalypso.org>
date Fri, 10 May 2024 19:50:29 +0000
parents a053cf0bac04
children 751f06541fbb
comparison
equal deleted inserted replaced
458:e26b974f7ba3 459:b094bc07051a
63 63
64 * There is a new utility named gsmfr-decode-rb, where rb stands for "raw basic". 64 * There is a new utility named gsmfr-decode-rb, where rb stands for "raw basic".
65 This utility emits "robe" output like gsmfr-decode-r, but it performs only 65 This utility emits "robe" output like gsmfr-decode-r, but it performs only
66 "basic" GSM 06.10 decoding, without the Rx DTX preprocessor step. BFI frame 66 "basic" GSM 06.10 decoding, without the Rx DTX preprocessor step. BFI frame
67 gaps in input are not allowed, and there is no SID detection. 67 gaps in input are not allowed, and there is no SID detection.
68
69 Standalone command line utilities for AMR codec
70 ===============================================
71
72 As described above, gsm[e]fr-encode and gsm[e]fr-decode were modeled after
73 amrnb-enc and amrnb-dec from opencore-amr, a piece of pre-existing FOSS.
74 However, now that we have libtwamr, a Themyscira library for AMR codec that is
75 designed to serve as a replacement for libopencore-amrnb in our workflows
76 involving AMR, we also have our own twamr-encode and twamr-decode utilities
77 that directly replace amrnb-enc and amrnb-dec.
78
79 twamr-encode is a functional replacement for amrnb-enc: it reads 16-bit linear
80 PCM speech input from a WAV file and writes the AMR encoder output in a .amr
81 file (RFC 4867 storage format). However, there is a difference in the command
82 line structure and a small difference in operation. The command line structure
83 of twamr-encode is as follows:
84
85 twamr-encode [-d] [-2] input.wav mode output.amr
86
87 The middle argument specifies the codec mode to be used; there is no default.
88 Ordinarily the mode argument is one of these 8 keywords:
89
90 MR475
91 MR515
92 MR59
93 MR67
94 MR74
95 MR795
96 MR102
97 MR122
98
99 However, this mode argument can also take the form of "file:$modefile", where
100 $modefile is an ASCII text file giving one of the above mode keywords per line.
101 This form is not likely to be useful in casual twamr-encode usage, but it exists
102 for the sake of symmetry with twamr-tseq-enc program used for verification
103 testing with the official test sequences from 3GPP.
104
105 Aside from this difference in the command line structure, the small functional
106 difference between amrnb-enc and twamr-encode is that libopencore-amrnb (the
107 engine underlying amrnb-enc) omits the codec homing feature, whereas libtwamr
108 (the engine underlying twamr-encode) implements the homing feature as a
109 mandatory part of the codec definition per 3GPP specs.
110
111 twamr-encode flag options: -d enables DTX, -2 switches the VAD algorithm from
112 VAD1 default to VAD2 alternative. The two options can be combined as -d2.
113
114 twamr-decode is a more straightforward replacement for amrnb-dec, with this
115 simple command line structure:
116
117 twamr-decode input.amr output.wav
118
119 The functional difference from amrnb-dec is once again in the codec homing
120 feature: present in libtwamr and hence twamr-decode, but absent in
121 libopencore-amrnb and hence amrnb-dec.
122
123 Finally, for the sake of completeness and symmetry with the other supported
124 codecs, the present suite includes twamr-encode-r and twamr-decode-r utilities.
125 They function just like twamr-encode and twamr-decode, with the same command
126 line structure, but the file format for 16-bit linear PCM speech is "robe"
127 instead of WAV.