GSM-Tools version 0.1 
=====================

Playing and recording sound using GSM compression. 

(c) Bernhard Oemer <oemer@tph.tuwien.ac.at>

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

gsm2wav and wav2gsm use the libgsm from Jutta Degener and Carsten Bormann,
see gsm/copyright for their licence.

Installation:
-------------

The GSM-Tools require the ncurses lib and an OSS or ALSA compatible
soundcard. For ALSA, the OSS-compatibility module must be loaded.
The latest version is available from

  http://tph.tuwien.ac.at/~oemer/gsmtools/

To install the gsmtools to /usr/local/bin, do

  make
  make install

Usage:
------

GSM is one of the best freely available speech compression methods and gives a
good trade-off between sound quality, compression and CPU usage. 160 16-bit
audio samples are encoded into one GSM block of 33 bytes.

This package contains the following programs:

USAGE gsm2wav [options] [<GSM-file>]
Converts a GSM file to a 16 bit mono wave-file or replays it on the DSP.
gsmplay is a link to gsm2wav and equivalent to 'gsm2wav -p'.
Options: -s<sample rate> in Hz, kHz or f (11025 Hz) (default 8000)
         -o<output file>, -h print this message, -v verbose mode
         -p play GSM file to DSP, -q operate quietly

USAGE: wav2gsm [options] [<wave-file>]
Converts 16 bit mono wave-file to GSM or records form DSP.
gsmrec is a link to wav2gsm and equivalent to 'wav2gsm -r'.
Options: -o<output file>, -h print this message, -v verbose mode
         -r record, -t<secs>s recording time (default: until SIGINT)
         -s<sample rate> in Hz, kHz or f (11025 Hz) (default: 8000Hz)

Other sample rates than 8000 Hz (the usual sapling rate of GSM celular phones) 
are allowed, but they must be given at the commandline or via the GSM_RATE
enviroment variable. (I usually use 11025 Hz for speech recordings).
The recording of gsm-files can be stopped at any time by sending SIGINT
(e.g. by pressing Ctrl-C at the command line).

Examples:
---------

I have written the GSM-Tools a as quick and dirty hack for recording radio-
programs via cronjob. For recording a 1 hour transmission at 11025 Hz, you 
would type:

  wav2gsm -r -s 11025Hz -t 3600s -o stuff.gsm

or shorter

  gsmrec -s 1f -t 3600s -o stuff.gsm

For manual recording, you can skip the -t option and stop the recording
with Ctrl-C.

To replay GSM files which have been recorded at any other rate than 8000 Hz,
you have to specify the rate at the commandline (this is to avoid any header in
the GSM-files):

  gsmplay -s 1f stuff.gsm

All commands also works with pipes. To convert a 8000Hz GSM file to
the usual 11025 Hz, 16-bit Wavefile (using wcat from the wavetools
package), do

  gsm2wav stuff.gsm | wcat -r 1f -b 16 -o stuff.wav

To convert back again, do

  wcat -b 16 -r 8000Hz stuff.wav | wav2gsm -o stuff.gsm

cu

Bernhard Oemer

