FreeCalypso > hg > gsm-codec-lib

annotate doc/AMR-library-desc @ 585:3c6bf0d26ee7 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
TW-TS-005 reader: fix maximum line length bug TW-TS-005 section 4.1 states: The maximum allowed length of each line is 80 characters, not including the OS-specific newline encoding. The implementation of this line length limit in the TW-TS-005 hex file reader function in the present suite was wrong, such that lines of the full maximum length could not be read. Fix it. Note that this bug affects comment lines too, not just actual RTP payloads. Neither Annex A nor Annex B features an RTP payload format that goes to the maximum of 40 bytes, but if a comment line goes to the maximum allowed length of 80 characters not including the terminating newline, the bug will be triggered, necessitating the present fix.
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 25 Feb 2025 07:49:28 +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.