annotate README @ 483:4f13db3a7086

doc/Utils-overview: document new utilities
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 20 May 2024 01:26:12 +0000
parents 614ae8dc6807
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
206
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1 Themyscira Wireless GSM codec libraries & utilities package
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
2 ===========================================================
0
b45bb0f9bdfc README: indicate purpose and scope of this repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3
206
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
4 Themyscira Wireless, a technical initiative of the Women's Republic of
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
5 Themyscira, is proud to present this package of GSM codec libraries and
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
6 associated command line test and development utilities. The present package
451
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
7 provides the following linkable C libraries, intended to be usable by any
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
8 application that needs GSM codec functionality:
0
b45bb0f9bdfc README: indicate purpose and scope of this repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9
451
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
10 libgsmfr2 This library implements the original GSM-FR codec, consisting
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
11 of not only the basic transcoding functions of GSM 06.10, but
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
12 also all Rx DTX handler functions that are required for a speech
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
13 decoder receiving a stream of frames from a radio interface,
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
14 either MS or network side. This library is a replacement for
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
15 classic libgsm, providing proper reset logic, homing functions
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
16 and the Rx DTX handler block.
206
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
17
451
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
18 libgsmefr This library implements GSM-EFR codec, based on the reference
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
19 code from ETSI (GSM 06.53). The bit-exact version of GSM-EFR
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
20 implemented here is the original one, not the AMR-EFR hybrid
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
21 that was made into a permissible implementation option after
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
22 the development of AMR.
206
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
23
451
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
24 libtwamr This library implements 3GPP AMR-NB codec, based on the official
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
25 reference code (TS 26.073). Both VAD versions are included,
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
26 selected by the user application at run time, and I/O functions
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
27 are provided for both 3GPP test sequence format and the more
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
28 practical format of IETF RFC 4867. This library can also be
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
29 used to implement AMR-EFR hybrid operation if no DTX is needed
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
30 in the encoder and if the input to the decoder contains no SID
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
31 frames.
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
32
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
33 The only GSM codec for which no implementation library is currently provided is
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
34 GSM-HR, also known as HRv1. Librification of HRv1 reference code from ETSI is
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
35 a planned work item for future development.
0
b45bb0f9bdfc README: indicate purpose and scope of this repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36
451
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
37 The libraries provided here are intended for two primary purposes:
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
38
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
39 1) They are used as part of Themyscira Wireless MGW (media gateway)
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
40 implementation, providing the necessary speech transcoder between a GSM
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
41 network and G.711-based PSTN.
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
42
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
43 2) They are useful in many varied study and exploration workings, as part of
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
44 experiments where it becomes necessary to model, simulate or replicate
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
45 bit-exact operation of someone else's network element.
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
46
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
47 Each of our Themyscira core libraries is free-standing and independent of the
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
48 others. The dependency on classic libgsm (by way of <gsm.h> header file) that
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
49 existed in previous versions of Themyscira gsm-codec-lib suite has been
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
50 eliminated; the present version has zero dependencies.
206
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
51
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
52 Included command line utilities
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
53 ===============================
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
54
451
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
55 In addition to the set of core libraries, the present package includes a number
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
56 of command line utilities, falling into the following groups:
206
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
57
451
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
58 * Some utilities specifically exercise and test our core libraries;
206
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
59
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
60 * Some utilities are not specifically for library testing but make use of
451
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
61 these libraries;
206
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
62
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
63 * Some utilities are included because they implement some closely related and
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
64 relevant debug and development functionality, even though they don't link
451
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
65 with any of the included core libraries.
206
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
66
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
67 Please see the included documentation in the doc subdirectory.