FreeCalypso > hg > gsm-codec-lib
annotate doc/AMR-library-desc @ 519:6f8abfe253a4 default tip
gsmhr-dec-craft: works after bugfix
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Sun, 01 Sep 2024 20:00:01 +0000 |
parents | c84bf526c7eb |
children |
rev | line source |
---|---|
476
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
1 Themyscira libtwamr general description |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
2 ======================================= |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
3 |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
4 Libtwamr is a librification of the official AMR reference C code from 3GPP, |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
5 produced by Themyscira Wireless and styled to match our libraries for more |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
6 classic GSM codecs. This library has been created with the following two goals |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
7 in mind: |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
8 |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
9 1) At the present time we (ThemWi) operate our GSM network with only GSM-FR and |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
10 GSM-EFR codecs, with the latter being preferred. We do not currently operate |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
11 with AMR because the conditions under which AMR becomes advantageous do not |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
12 currently exist in our network operation. However, we need to be prepared |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
13 for the possibility that the conditions which make AMR desirable may arise |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
14 some day, and we may need to start deploying AMR. In order to make AMR |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
15 deployment a possibility, many parts will need to be implemented, one of |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
16 which is a speech transcoding library that implements the AMR codec in the |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
17 same way how libgsmfr2 and libgsmefr implement the more classic codecs which |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
18 we use currently. |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
19 |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
20 2) Many other commercial GSM networks have implemented EFR speech service using |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
21 a type of AMR-EFR hybrid described in AMR-EFR-philosophy and |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
22 AMR-EFR-hybrid-emu articles. As part of certain behavioral reverse |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
23 engineering experiments, we sometimes need to model the bit-exact operation |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
24 of those other-people-controlled commercial implementations of AMR-EFR, and |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
25 our current libtwamr provides one way to do so. Knowing that a proper |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
26 implementation of an AMR codec library is likely to be needed some day for |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
27 reason 1 above, justification was obtained for expending the effort to |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
28 produce the present libtwamr. |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
29 |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
30 Compared to other plausible ways in which someone could reasonably approach the |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
31 task of librifying the AMR reference code from 3GPP, the design of libtwamr |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
32 includes two somewhat original choices: |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
33 |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
34 * Separation of core and I/O: the stateful encoder and decoder engines in |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
35 libtwamr operate on a custom frame structure that includes the array of codec |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
36 parameters in their broken-down form (e.g., 57 parameters for MR122), the |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
37 frame type as in original RXFrameType and TXFrameType, and the codec mode. |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
38 Conversion between this internal canonical form (which is most native to the |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
39 guts of the encoder and decoder engines) and external I/O formats (the 3GPP |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
40 test sequence format and the more practical RFC 4867 format used in RTP and |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
41 in .amr recording files) is relegated to stateless utility functions. |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
42 |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
43 * Both VAD1 and VAD2 included: the reference code from 3GPP includes two |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
44 alternative versions of Voice Activity Detection algorithm, VAD1 and VAD2. |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
45 Implementors are allowed to use either version and be compliant; 3GPP code |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
46 uses conditional compilation to select between the two, and it appears that |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
47 no thought was given to the possibility that a real implementation would |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
48 incorporate both VAD versions, to be selected at run time. However, given our |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
49 (ThemWi) desire for bit-exact testing against other people's implementations, |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
50 it made no sense for us to arbitrarily select one VAD version and drop the |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
51 other - hence we took the unconventional route of incorporating both VAD1 and |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
52 VAD2 into libtwamr, and designing our encoder API so that library users get |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
53 to select which VAD they wish to apply. |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
54 |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
55 Like all other Themyscira GSM codec libraries, libtwamr includes the codec |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
56 homing feature in both encoder and decoder directions, as required by 3GPP |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
57 specs. Furthermore, libtwamr implementation of this codec homing feature |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
58 includes the following simple extensions (simple in terms of low implementation |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
59 cost) to facilitate construction of an AMR-EFR hybrid encoder and decoder: |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
60 |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
61 * In the decoder direction, the main AMR frame decoder function includes a DHF |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
62 detector as required by 3GPP architecture. In libtwamr this function can be |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
63 told to trigger on EFR DHF instead of MR122 version, by way of a flag set in |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
64 the mode field of the frame structure passed to amr_decode_frame(). |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
65 |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
66 * In the encoder direction, the regular call to amr_encode_frame() - standard |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
67 for AMR - can be followed with a call to amr_dhf_subst_efr() or |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
68 amr_dhf_subst_efr2() before passing the array of encoded parameters to |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
69 EFR_params2frame() from libgsmefr. See AMR-EFR-hybrid-emu article for more |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
70 information. The AMR-EFR hybrid test sequences in amr122_efr.zip pass on |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
71 both amr_dhf_subst_efr() and amr_dhf_subst_efr2() versions, but the latter |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
72 additionally matches the observable behavior of T-Mobile USA. |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
73 |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
74 The mechanism that allows libtwamr to be used for AMR-EFR hybrid implementation |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
75 (as opposed to the more conventional use case of implementing standard AMR-NB) |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
76 is kept out of the main stateful paths: there are no separate AMR-EFR hybrid |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
77 encoder or decoder sessions that are distinguishable from regular AMR encoding |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
78 and decoding in terms of state. In the decoder direction, the main AMR frame |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
79 decoder function needs to know which DHF it should check for, but this |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
80 indication is embedded in the mode field in struct amr_param_frame and not in |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
81 the state. In the encoder direction, the mechanism is a separate function |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
82 (stateless) that needs to be called between amr_encode_frame() and |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
83 EFR_params2frame(). This approach dovetails nicely with the core vs I/O |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
84 separation: the option of AMR-EFR hybrid can be viewed as a different I/O front |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
85 end to the same AMR engine, alongside with 3GPP AMR test sequence and RFC 4867 |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
86 I/O options. |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
87 |
c84bf526c7eb
beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
88 Please refer to AMR-library-API article for further details. |