FreeCalypso > hg > gsm-codec-lib

annotate doc/Codec-utils @ 282:9ee8ad3d4d30

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
frtest: rm gsmfr-hand-test and gsmfr-max-out utils These hack programs were never properly documented and were written only as part of a debug chase, in pursuit of a bug that ultimately turned out to be in our then-hacky patch to osmo-bts-sysmo, before beginning of proper patches in Osmocom. These hack programs need to be dropped from the present sw package because they depend on old libgsm, and we are eliminating that dependency.
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 14 Apr 2024 05:44:47 +0000
parents 04936af99fc8
children a053cf0bac04
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 gsmfr-encode This utility reads linear PCM from a WAV file, runs libgsm
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 06.10 encoder and writes the output in the classic .gsm format
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 (directly abutted FR codec frames of 33 bytes each). We don't
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 currently have a Tx-side DTX implementation (VAD etc) for GSM
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 FR, hence the output from gsmfr-encode will always consist of
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 good speech frames only.
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
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 input but becomes important for real-world input containing SIDs
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 and BFIs, and is followed by gsm_decode() from libgsm. The
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 decoded output is written as WAV.
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.