annotate doc/AMR-EFR-philosophy @ 479:616b7ba1135b

doc/AMR-library-API: document AMR-EFR hybrid decoder
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 19 May 2024 22:22:40 +0000
parents ad032051166a
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
311
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
1 Relation between GSM-EFR and 12k2 mode of AMR
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
2 =============================================
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
3
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
4 What are the differences between GSM-EFR codec and the highest 12k2 mode of AMR,
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
5 or MR122 for short? The most obvious difference is in DTX: the format of SID
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
6 frames and even the very paradigm of how DTX works are completely different
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
7 between EFR and AMR. But what about non-DTX operation? If a codec session
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
8 consists solely of good speech frames, no SIDs and no BFI frame gaps, are EFR
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
9 and MR122 strictly identical?
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
10
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
11 The correct answer is that in the absence of SIDs, EFR and MR122 are directly
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
12 interoperable in that the output of an EFR encoder can be fed to the input of
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
13 an AMR decoder, and vice-versa. However, the two codecs are NOT identical at
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
14 the bit-exact level! The differences are subtle, such that finding them
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
15 requires some intense study; this article documents some of these study
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
16 findings:
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
17
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
18 https://www.freecalypso.org/hg/efr-experiments/file/tip/Theory-and-mystery
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
19
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
20 What other DSP/transcoder vendors have done
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
21 ===========================================
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
22
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
23 ETSI had a tradition of defining standard GSM codecs (FR, HR, EFR) in bit-exact
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
24 form, and every production implementation was required to match the output of
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
25 the official reference bit for bit. However, once AMR came out, the regulation
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
26 on EFR was loosened. GSM 06.54 document from 2000-08 (ETSI TS 100 725 V5.2.0)
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
27 has an appendix-like chapter (chapter 10) whose first paragraph reads:
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
28
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
29 The 12.2 kbit/s mode of the Adaptive Multi Rate speech coder described
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
30 in TS 26.071 is functionally equivalent to the GSM Enhanced Full Rate
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
31 speech coder. An alternative implementation of the Enhanced Full Rate
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
32 speech service based on the 12.2 kbit/s mode of the Adaptive Multi Rate
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
33 coder is allowed. Alternative implementations shall implement the
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
34 functionality specified in TS 26.071 for the 12.2 kbit/s mode, with the
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
35 exception that the DTX transmission format (GSM 06.81) and the comfort
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
36 noise generation (GSM 06.62) shall be used.
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
37
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
38 It appears that DSP vendors (for GSM MS or for network transcoders, or perhaps
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
39 both) weren't too happy with the prospect of having to include two different
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
40 versions of _almost_ the same codec algorithm with a bunch of interspersed
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
41 subtle diffs, and so the rules were bent: EFR implementors were given permission
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
42 to deviate from the original bit-exact definition of EFR in order to have more
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
43 commonality with MR122.
136
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44
311
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
45 Approach adopted for Themyscira GSM codec libraries suite
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
46 =========================================================
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
47
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
48 I (Mother Mychaela) previously entertained the idea of creating a unified codec
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
49 library that supports both AMR and EFR with common code, producing a published-
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
50 source, FOSS-culture equivalent of what most proprietary vendors have done.
457
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
51 However, on further reflection, that idea has been rejected. The current
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
52 situation as of 2024-05 is as follows:
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
53
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
54 * Libgsmefr is our production-oriented implementation of GSM-EFR codec. It
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
55 implements the original bit-exact definition of EFR, not the AMR-EFR hybrid
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
56 version, and it includes full support for DTX encoding and SID decoding with
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
57 comfort noise generation per GSM 06.62.
311
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
58
457
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
59 * Libtwamr is our librification of 3GPP AMR reference code. The library is
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
60 structured in such a way that libtwamr stateful encoder and decoder functions
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
61 can be combined with stateless EFR frame packing and unpacking functions from
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
62 libgsmefr, allowing AMR-EFR hybrid encoders and decoders to be built. The
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
63 decoder homing function in libtwamr can be told to trigger on EFR DHF instead
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
64 of MR122 version, and for the encoder direction there is a simple utility
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
65 function that artificially transforms MR122 DHF into EFR DHF post-encoder.
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
66 However, there is no support for AMR-EFR hybrid encoding with DTX enabled,
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
67 and the low-effort version of AMR-EFR hybrid decoder constructed in this
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
68 manner cannot grok EFR SID frames or generate CN per GSM 06.62.
311
83408f67a96c doc/AMR-EFR-philosophy: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
69
457
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
70 Production implementations of GSM network elements that need to perform EFR
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
71 speech transcoding should use libgsmefr, not libtwamr. The limited support
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
72 that is provided for AMR-EFR hybrid encoding and decoding with the combination
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
73 of libtwamr and libgsmefr is intended for experimentation and reverse
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
74 engineering of other people's implementations, for times when it becomes
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
75 necessary to model, simulate or replicate bit-exact operation of someone else's
9bcf65088006 doc/AMR-EFR-philosophy: document implemented solution
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
76 network element.