FreeCalypso > hg > gsm-codec-lib
annotate doc/Codec-utils @ 436:e80632ccb745
simplify test program Makefiles
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Wed, 08 May 2024 05:32:27 +0000 |
parents | a053cf0bac04 |
children | b094bc07051a |
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 |
a053cf0bac04
doc/Codec-utils: update for libgsmfr2
Mychaela Falconia <falcon@freecalypso.org>
parents:
157
diff
changeset
|
67 gaps in input are not allowed, and there is no SID detection. |