FreeCalypso > hg > gsm-codec-lib

annotate doc/AMR-library-desc @ 531:c7b1e796e91b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
libgsmfr2 TFO: implement main entry point function
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 19 Sep 2024 20:35:10 +0000
parents c84bf526c7eb
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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.