FreeCalypso > hg > gsm-codec-lib

comparison doc/AMR-library-desc @ 476:c84bf526c7eb

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