FreeCalypso > hg > gsm-codec-lib

annotate doc/Codec-utils @ 456:4c458145e793

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
PACKAGING: new guidelines
author Mychaela Falconia <falcon@freecalypso.org>
date Fri, 10 May 2024 07:35:36 +0000
parents a053cf0bac04
children b094bc07051a
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
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.