Gapk » History » Version 17
laforge, 07/25/2022 07:54 AM
gitea
1 | 5 | fixeria | h1. GAPK (GSM Audio Pocket Knife) |
---|---|---|---|
2 | 1 | laforge | |
3 | 4 | fixeria | {{>toc}} |
4 | |||
5 | The GAPK (GSM Audio Pocket Knife) is a project, the product of which is a core library (libosmogapk) and a command-line tool (osmo-gapk) for conversions between the various GSM related codecs (HR/FR/EFR/AMR) and PCM audio. It supports many different formats for the codec frames, including ETSI and IETF standardized formats, as well as vendor-specific formats like those found in the TI Calypso DSP (see [[OsmocomBB:]]) and those of Racal 6103/6113 GSM test equipment. |
||
6 | 1 | laforge | |
7 | h2. Supported Codecs |
||
8 | |||
9 | 6 | fixeria | |_.Codec|_.Description|_.Implementation| |
10 | |pcm|Raw PCM signed 16bits samples|native| |
||
11 | 7 | fixeria | |hr|GSM 06.20 Half Rate codec|libgsmhr[1] (GSM 06.06 reference code)| |
12 | 6 | fixeria | |fr|GSM 06.10 Full Rate codec (classic gsm codec)|libgsm| |
13 | |efr|GSM 06.60 Enhanced Full Rate codec|opencore-amr| |
||
14 | 1 | laforge | |amr|GSM 26.061 Adaptive Multi Rate codec|opencore-amr| |
15 | 7 | fixeria | |
16 | 8 | fixeria | [1] Note: due to the licensing problems, the GSM 06.06 reference *code is not included* as a part of GAPK. Moreover, the reference implementation has some additional problems, such as relatively low performance and poor code quality (lots of warnings, global state variables). Passing the _--enable-gsmhr_ configuration flag will enable the source code downloading, patching and compilation. |
17 | 1 | laforge | |
18 | h2. Supported Formats |
||
19 | |||
20 | |_.Format|_.Description| |
||
21 | |amr-efr |Classic .amr file containing EFR (=AMR 12.2k) data| |
||
22 | |gsm |Classic .gsm file format (and RTP payload for FR according to RFC3551)| |
||
23 | |hr-ref-dec |3GPP HR Reference decoder code parameters file format| |
||
24 | |hr-ref-enc |3GPP HR Reference encoder code parameters file format| |
||
25 | |racal-hr |Racal HR TCH/H recording| |
||
26 | |racal-fr |Racal FR TCH/F recording| |
||
27 | |racal-efr |Racal EFR TCH/F recording| |
||
28 | |rawpcm-s16le |Raw PCM samples Signed 16 bits little endian| |
||
29 | |ti-hr |Texas Instrument HR TCH/H buffer format| |
||
30 | |ti-fr |Texas Instrument FR TCH/F buffer format| |
||
31 | |ti-efr |Texas Instrument EFR TCH/F buffer format| |
||
32 | |amr-opencore |Input format to libopencore-amrnb| |
||
33 | |rtp-amr |RTP payload for AMR according to RFC4867| |
||
34 | |rtp-efr |RTP payload for EFR according to RFC3551| |
||
35 | |rtp-hr-etsi |RTP payload for HR according to ETSI TS 101 318| |
||
36 | |rtp-hr-ietf |RTP payload for HR according to IETF RFC5993| |
||
37 | |||
38 | 9 | fixeria | h2. Source Code |
39 | |||
40 | You can find the source code in git: |
||
41 | 17 | laforge | * https://gitea.osmocom.org/osmocom/gapk (gitea web interface) |
42 | * @git clone https://gitea.osmocom.org/osmocom/gapk@ for cloning the repository |
||
43 | 9 | fixeria | |
44 | 14 | fixeria | h2. Dependencies |
45 | |||
46 | The only mandatory dependency of GAPK is [[libosmocore:libosmocore]]. Make sure you have the latest version and update it if required. |
||
47 | |||
48 | Optional libraries: |
||
49 | |||
50 | * libalsa - ALSA sound capture / playback support, |
||
51 | * opencore-amrnb - AMR and EFR codec support, |
||
52 | * libgsm - FR codec support. |
||
53 | |||
54 | Install them using the package manager of your distribution, e.g. for Debian-based systems: |
||
55 | |||
56 | <pre> |
||
57 | $ apt-get install libasound2-dev libopencore-amrnb-dev libgsm1-dev |
||
58 | </pre> |
||
59 | |||
60 | for Arch Linux: |
||
61 | |||
62 | <pre> |
||
63 | $ pacman -S alsa-lib opencore-amr gsm |
||
64 | </pre> |
||
65 | |||
66 | 15 | fixeria | h2. Configuration and building |
67 | |||
68 | The project is based on Automake, so the _configure_ script needs to be generated: |
||
69 | |||
70 | <pre> |
||
71 | $ cd gapk/ |
||
72 | $ autoreconf -i |
||
73 | $ ./configure --help |
||
74 | </pre> |
||
75 | |||
76 | Check out available configuration options, and generate _Makefile_: |
||
77 | |||
78 | <pre> |
||
79 | $ ./configure |
||
80 | </pre> |
||
81 | |||
82 | In order to enable GSM HR codec support, make sure you have Python installed: |
||
83 | |||
84 | <pre> |
||
85 | $ ./configure --enable-gsmhr |
||
86 | </pre> |
||
87 | |||
88 | Then compile and install: |
||
89 | |||
90 | <pre> |
||
91 | $ make |
||
92 | $ sudo make install |
||
93 | $ sudo ldconfig |
||
94 | </pre> |
||
95 | |||
96 | 1 | laforge | h2. Common use cases |
97 | |||
98 | 11 | fixeria | h3. Conversion between different codecs / formats |
99 | |||
100 | 12 | fixeria | First of all, make sure that required codecs are supported by your build: |
101 | 11 | fixeria | |
102 | <pre> |
||
103 | $ osmo-gapk -h |
||
104 | ... |
||
105 | Supported codecs: |
||
106 | 12 | fixeria | name fmt enc dec description |
107 | pcm * Raw PCM signed 16 bits samples |
||
108 | hr * * * GSM 06.20 Half Rate codec |
||
109 | fr * * * GSM 06.10 Full Rate codec (classic gsm codec) |
||
110 | efr * * * GSM 06.60 Enhanced Full Rate codec |
||
111 | amr * * * GSM 26.071 Adaptive Multi Rate codec |
||
112 | 11 | fixeria | ... |
113 | 12 | fixeria | </pre> |
114 | |||
115 | 13 | fixeria | Example: converting .gsm (GSM FR codec) file to .amr (GSM EFR codec AMR 12.2k): |
116 | 12 | fixeria | |
117 | <pre> |
||
118 | $ osmo-gapk -i input_file.gsm -f gsm -g amr-efr -o output_file.amr |
||
119 | 11 | fixeria | </pre> |
120 | |||
121 | 1 | laforge | h3. RTP sink with audio playback on sound card |
122 | |||
123 | 10 | fixeria | You can run @gapk@ as a _RTP sink_, i.e. listening to a given UDP port for incoming RTP frames, decoding them from their respective audio codec and then playing them back via your computers' sound card: |
124 | 1 | laforge | |
125 | <pre> |
||
126 | 10 | fixeria | $ osmo-gapk -I 0.0.0.0/30000 -f rtp-amr -A default -g rawpcm-s16le |
127 | 2 | laforge | </pre> |
128 | |||
129 | where |
||
130 | * *@-I 0.0.0.0/30000@* indicates the IP adddress (any) and UDP port (30000) to bind to and receive RTP frames on |
||
131 | * *@-f rtp-amr@* indicates the codec. Use *@gsm, rtp-efr, rtp-amr, rtp-hr-etsi or rtp-hr-ietf@* depending on your use case |
||
132 | * *@-A default@* is the alsa hardware device name (default is the default sound card) |
||
133 | |||
134 | 3 | laforge | h2. Contact / Mailing List |
135 | |||
136 | The project is too small to have it's own mailing list. Instead, we use the openbsc@lists.osmocom.org mailing list ("subscribe":http://lists.osmocom.org/mailman/listinfo/OpenBSC). Please observe the [[cellular-infrastructure:Mailing_List_Rules]]. |
||
137 | |||
138 | 2 | laforge | h2. Authors |
139 | |||
140 | 16 | fixeria | GAPK as written by Sylvain Munaut with contributions from Harald Welte and Vadim Yanitskiy. |