FreeCalypso > hg > gsm-codec-lib
annotate doc/EFR-rationale @ 437:3eadaef8b28f
implement amrefr-tseq-dec test program
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Wed, 08 May 2024 23:03:28 +0000 |
parents | 69b9a1eeb5a2 |
children |
rev | line source |
---|---|
122
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
1 Problem in need of solving |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
2 ========================== |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
3 |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
4 At the time of the undertaking of Themyscira libgsmefr project (late 2022), |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
5 there did not exist any readily available library solution for GSM EFR codec. |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
6 The community of FOSS offers classic libgsm from 1990s for FR1 codec (it's an |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
7 implementation of GSM 06.10, on top of which we had to implement our own Rx DTX |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
8 handler) and opencore-amrnb for AMR (based on Android OpenCORE framework) - but |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
9 nothing for EFR. This situation creates a problem for anyone seeking to deploy |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
10 their own GSM network with a voice interface to PSTN or other networks: such |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
11 voice interface generally requires implementing a transcoder, and doing the |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
12 latter in turn requires a library that implements the codec to be supported. |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
13 In the present situation, anyone who wishes to implement a speech transcoder |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
14 for GSM networks can easily support FR1 and AMR codecs, but not EFR. |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
15 |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
16 EFR is more than just 12k2 mode of AMR! |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
17 ======================================= |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
18 |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
19 There is a common misconception in the GSM hacker community that EFR is nothing |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
20 but the highest 12k2 mode of AMR, and that any library that implements AMR, |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
21 such as opencore-amrnb, is thus sufficient to support EFR as well. However, |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
22 the reality is more complex: |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
23 |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
24 * If an AMR encoder operates with DTX disabled, such that the output contains |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
25 only speech frames and no SID, and the mode is forced to 12k2, then indeed a |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
26 simple reshuffling of bits will produce speech frames that can be fed to an |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
27 EFR decoder on the other end. Note that the two encoders (EFR and AMR 12k2) |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
28 will produce *different* encoded speech parameters from the same input, and |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
29 the decoded speech output on the other end will also be different, but the |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
30 two versions are expected to be equally good for human ears. |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
31 |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
32 * In the other direction, if an EFR input stream contains only good speech |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
33 frames (no SID and no lost, FACCH-stolen or DTX-suppressed frames), one can |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
34 likewise do a simple bit reordering and feed these frames to an AMR decoder. |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
35 The output of this AMR decoder will once again be different from a proper |
181
3a0ee08a3b9d
doc/EFR-rationale: typo fix
Mychaela Falconia <falcon@freecalypso.org>
parents:
127
diff
changeset
|
36 (bit-exact) EFR decoder for the same speech parameter inputs, but as long as |
122
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
37 the EFR input stream is all good speech frames, the output will be good enough |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
38 for human ears. |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
39 |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
40 * The real problem occurs when the EFR input stream contains SID frames and BFI |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
41 frame gaps, as will always happen in reality if this stream is an uplink from |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
42 a GSM call. AMR SID mechanism is different from that of EFR, and an AMR |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
43 decoder will NOT recognize EFR SID frames. A quick experiment confirms that |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
44 when a real GSM EFR uplink RTP capture is converted to AMR by non-SID-aware |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
45 bit reshuffling and then fed to amrnb-dec from opencore-amrnb, unpleasant |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
46 sounds appear in the output whenever GSM uplink goes into SID. |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
47 |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
48 EFR reference code from ETSI |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
49 ============================ |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
50 |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
51 A published-source bit-exact implementation of GSM EFR encoder and decoder, |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
52 complete with all beyond-speech functions of DTX, VAD, comfort noise generation, |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
53 error concealment etc does exist in the form of reference code from ETSI. |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
54 However, this code has never been turned into a usable codec library by anyone |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
55 prior to us (at least not by anyone who freely published their work), and doing |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
56 such librification (producing an EFR analogue to what Android OpenCORE people |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
57 did with AMR) is no easy feat! The original EFR code from ETSI exhibits two |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
58 problems which need to be remedied in the librification project: |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
59 |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
60 1) The original code maintains all codec state in global variables (lots of |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
61 them) that are scattered throughout. 3GPP reference code for AMR (naturally |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
62 later than EFR in chronological order) is better in this regard (in the AMR |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
63 version they gathered their global vars into structs and pass pointers to |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
64 these structs, although still many separately-malloc'ed structs instead of |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
65 single unified encoder state and decoder state), but we need the EFR version |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
66 for correct handling of all beyond-speech aspects, and this version is all |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
67 global vars. |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
68 |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
69 2) These reference codes from ETSI/3GPP (both EFR and AMR versions, it seems) |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
70 were intended to serve as simulations, not as production code, and the code |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
71 is very inefficient. |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
72 |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
73 Themyscira libgsmefr |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
74 ==================== |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
75 |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
76 Libgsmefr presented in this code repository is our current solution for EFR. |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
77 It is a library styled after classic libgsm for FR1, but its guts consist of a |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
78 librified derivative of ETSI EFR code. The problem of global vars has been |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
79 solved in this library version - they've been gathered into one unified struct |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
80 for encoder state and another unified struct for decoder state - but the problem |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
81 of poor performance (significantly worse than opencore-amrnb) still remains for |
b33f2168fdec
doc/EFR-rationale article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
82 now. |
127
4af99bf8671a
doc/EFR-rationale: add future roadmap section
Mychaela Falconia <falcon@freecalypso.org>
parents:
122
diff
changeset
|
83 |
4af99bf8671a
doc/EFR-rationale: add future roadmap section
Mychaela Falconia <falcon@freecalypso.org>
parents:
122
diff
changeset
|
84 Future roadmap |
4af99bf8671a
doc/EFR-rationale: add future roadmap section
Mychaela Falconia <falcon@freecalypso.org>
parents:
122
diff
changeset
|
85 ============== |
4af99bf8671a
doc/EFR-rationale: add future roadmap section
Mychaela Falconia <falcon@freecalypso.org>
parents:
122
diff
changeset
|
86 |
313
69b9a1eeb5a2
doc/EFR-rationale: update future roadmap
Mychaela Falconia <falcon@freecalypso.org>
parents:
181
diff
changeset
|
87 When this article was originally written in late 2022, my thoughts were that we |
69b9a1eeb5a2
doc/EFR-rationale: update future roadmap
Mychaela Falconia <falcon@freecalypso.org>
parents:
181
diff
changeset
|
88 would go in the direction of a single library supporting both AMR and EFR, |
69b9a1eeb5a2
doc/EFR-rationale: update future roadmap
Mychaela Falconia <falcon@freecalypso.org>
parents:
181
diff
changeset
|
89 sharing most code in common and handling the differences between EFR and MR122 |
69b9a1eeb5a2
doc/EFR-rationale: update future roadmap
Mychaela Falconia <falcon@freecalypso.org>
parents:
181
diff
changeset
|
90 similarly to how most proprietary implementations have done it, following the |
69b9a1eeb5a2
doc/EFR-rationale: update future roadmap
Mychaela Falconia <falcon@freecalypso.org>
parents:
181
diff
changeset
|
91 "alternative" of GSM 06.54 chapter 10. However, that plan has been revised; |
69b9a1eeb5a2
doc/EFR-rationale: update future roadmap
Mychaela Falconia <falcon@freecalypso.org>
parents:
181
diff
changeset
|
92 our current approach (as of 2024-04) is that we are developing a separate |
69b9a1eeb5a2
doc/EFR-rationale: update future roadmap
Mychaela Falconia <falcon@freecalypso.org>
parents:
181
diff
changeset
|
93 library for AMR (libtwamr, librifying 3GPP AMR code in the same way how we |
69b9a1eeb5a2
doc/EFR-rationale: update future roadmap
Mychaela Falconia <falcon@freecalypso.org>
parents:
181
diff
changeset
|
94 librified ETSI EFR in libgsmefr), while libgsmefr remains as it is, a pristine |
69b9a1eeb5a2
doc/EFR-rationale: update future roadmap
Mychaela Falconia <falcon@freecalypso.org>
parents:
181
diff
changeset
|
95 implementation of GSM-EFR in its *original* bit-exact form. |
69b9a1eeb5a2
doc/EFR-rationale: update future roadmap
Mychaela Falconia <falcon@freecalypso.org>
parents:
181
diff
changeset
|
96 |
69b9a1eeb5a2
doc/EFR-rationale: update future roadmap
Mychaela Falconia <falcon@freecalypso.org>
parents:
181
diff
changeset
|
97 Please refer to AMR-EFR-philosophy article for more information. |