Miscellaneous Projects » GSM Audio Pocket Knife

h1. GAPK (GSM Audio Pocket Knife)

{{>toc}}

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.

h2. Supported Codecs

|_.Codec|_.Description|_.Implementation|

|pcm|Raw PCM signed 16bits samples|native|

|hr|GSM 06.20 Half Rate codec|libgsmhr[1] (GSM 06.06 reference code)|

|fr|GSM 06.10 Full Rate codec (classic gsm codec)|libgsm|

|efr|GSM 06.60 Enhanced Full Rate codec|opencore-amr|

|amr|GSM 26.061 Adaptive Multi Rate codec|opencore-amr|

[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.

h2. Supported Formats

|_.Format|_.Description|

|amr-efr             |Classic .amr file containing EFR (=AMR 12.2k) data|

|gsm                 |Classic .gsm file format (and RTP payload for FR according to RFC3551)|

|hr-ref-dec          |3GPP HR Reference decoder code parameters file format|

|hr-ref-enc          |3GPP HR Reference encoder code parameters file format|

|racal-hr            |Racal HR TCH/H recording|

|racal-fr            |Racal FR TCH/F recording|

|racal-efr           |Racal EFR TCH/F recording|

|rawpcm-s16le        |Raw PCM samples Signed 16 bits little endian|

|ti-hr               |Texas Instrument HR TCH/H buffer format|

|ti-fr               |Texas Instrument FR TCH/F buffer format|

|ti-efr              |Texas Instrument EFR TCH/F buffer format|

|amr-opencore        |Input format to libopencore-amrnb|

|rtp-amr             |RTP payload for AMR according to RFC4867|

|rtp-efr             |RTP payload for EFR according to RFC3551|

|rtp-hr-etsi         |RTP payload for HR according to ETSI TS 101 318|

|rtp-hr-ietf         |RTP payload for HR according to IETF RFC5993|

h2. Source Code

You can find the source code in git:

* http://git.osmocom.org/gapk/ (cgit web interface)

* @git clone git://git.osmocom.org/gapk@ for cloning the repository

h2. Dependencies

The only mandatory dependency of GAPK is [[libosmocore:libosmocore]]. Make sure you have the latest version and update it if required.

Optional libraries:

* libalsa - ALSA sound capture / playback support,

* opencore-amrnb - AMR and EFR codec support,

* libgsm - FR codec support.

Install them using the package manager of your distribution, e.g. for Debian-based systems:

<pre>

$ apt-get install libasound2-dev libopencore-amrnb-dev libgsm1-dev

</pre>

for Arch Linux:

<pre>

$ pacman -S alsa-lib opencore-amr gsm

</pre>

h2. Configuration and building

The project is based on Automake, so the _configure_ script needs to be generated:

<pre>

$ cd gapk/

$ autoreconf -i

$ ./configure --help

</pre>

Check out available configuration options, and generate _Makefile_:

<pre>

$ ./configure

</pre>

In order to enable GSM HR codec support, make sure you have Python installed:

<pre>

$ ./configure --enable-gsmhr

</pre>

Then compile and install:

<pre>

$ make

$ sudo make install

$ sudo ldconfig

</pre>

h2. Common use cases

h3. Conversion between different codecs / formats

First of all, make sure that required codecs are supported by your build:

<pre>

$ osmo-gapk -h

...

Supported codecs:

 name	fmt enc dec		description

  pcm	 *         		Raw PCM signed 16 bits samples

   hr	 *   *   * 		GSM 06.20 Half Rate codec

   fr	 *   *   * 		GSM 06.10 Full Rate codec (classic gsm codec)

  efr	 *   *   * 		GSM 06.60 Enhanced Full Rate codec

  amr	 *   *   * 		GSM 26.071 Adaptive Multi Rate codec

...

</pre>

Example: converting .gsm (GSM FR codec) file to .amr (GSM EFR codec AMR 12.2k):

<pre>

$ osmo-gapk -i input_file.gsm -f gsm -g amr-efr -o output_file.amr

</pre>

h3. RTP sink with audio playback on sound card

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:

<pre>

$ osmo-gapk -I 0.0.0.0/30000 -f rtp-amr -A default -g rawpcm-s16le

</pre>

where

* *@-I 0.0.0.0/30000@* indicates the IP adddress (any) and UDP port (30000) to bind to and receive RTP frames on

* *@-f rtp-amr@* indicates the codec. Use *@gsm, rtp-efr, rtp-amr, rtp-hr-etsi or rtp-hr-ietf@* depending on your use case

* *@-A default@* is the alsa hardware device name (default is the default sound card)

h2. Contact / Mailing List

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]].

h2. Authors

@gapk@ as written by Sylvain Munaut with contributions from Harald Welte. 

It uses external libraries for the actual audio codecs, such as @libgsm@, @libopencore-amrnb@ nd the ETSI reference implementation for GSM-HR.