Project

General

Profile

GAPK (GSM Audio Pocket Knife)

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.

Supported Codecs

Codec Description Implementation
pcm Raw PCM signed 16bits samples native
hr GSM 06.20 Half Rate codec libgsmhr1 (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.

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

Source Code

You can find the source code in git:

Dependencies

The only mandatory dependency of GAPK is 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:

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

for Arch Linux:

$ pacman -S alsa-lib opencore-amr gsm

Configuration and building

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

$ cd gapk/
$ autoreconf -i
$ ./configure --help

Check out available configuration options, and generate Makefile:

$ ./configure

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

$ ./configure --enable-gsmhr

Then compile and install:

$ make
$ sudo make install
$ sudo ldconfig

Common use cases

Conversion between different codecs / formats

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

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

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

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

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:

$ osmo-gapk -I 0.0.0.0/30000 -f rtp-amr -A default -g rawpcm-s16le
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)

Contact / Mailing List

The project is too small to have it's own mailing list. Instead, we use the mailing list (subscribe). Please observe the Mailing_List_Rules.

Authors

GAPK as written by Sylvain Munaut with contributions from Harald Welte and Vadim Yanitskiy.

Add picture from clipboard (Maximum size: 48.8 MB)