libgsm/gsm.3

   1 .\"
   2 .\" Copyright 1992 by Jutta Degener and Carsten Bormann, Technische
   3 .\" Universitaet Berlin.  See the accompanying file "COPYRIGHT" for
   4 .\" details.  THERE IS ABSOLUTELY NO WARRANTY FOR THIS SOFTWARE.
   5 .\"
   6 .PU
   7 .TH GSM 3
   8 .SH NAME
   9 gsm_create, gsm_destroy, gsm_encode, gsm_decode \(em GSM\ 06.10 lossy sound compression
  10 .SH SYNOPSIS
  11 .PP
  12 #include "gsm.h"
  13 .PP
  14 gsm gsm_create();
  15 .PP
  16 void gsm_encode(handle, src, dst)
  17 .br
  18 gsm handle;
  19 .br
  20 gsm_signal src[160];
  21 .br
  22 gsm_frame dst;
  23 .PP
  24 int gsm_decode(handle, src, dst)
  25 .br
  26 gsm handle;
  27 .br
  28 gsm_frame src;
  29 .br
  30 gsm_signal dst[160];
  31 .PP
  32 void gsm_destroy(handle)
  33 .br
  34 gsm handle;
  35 .br
  36 .SH "DESCRIPTION"
  37 Gsm is an implementation of the final draft GSM 06.10
  38 standard for full-rate speech transcoding.
  39 .PP
  40 gsm_create() initializes a gsm pass and returns a 'gsm' object
  41 which can be used as a handle in subsequent calls to gsm_decode(),
  42 gsm_encode() or gsm_destroy().
  43 .PP
  44 gsm_encode() encodes an array of 160 13-bit samples (given as
  45 gsm_signal's, signed integral values of at least 16 bits) into
  46 a gsm_frame of 33 bytes.
  47 (gsm_frame is a type defined as an array of 33 gsm_bytes in gsm.h.)
  48 .PP
  49 gsm_decode() decodes a gsm_frame into an array of 160 13-bit samples
  50 (given as gsm_signals), which sound rather like what you handed to
  51 gsm_encode() on the other side of the wire.
  52 .PP
  53 gsm_destroy() finishes a gsm pass and frees all storage associated
  54 with it.
  55 .SS "Sample format"
  56 The following scaling is assumed for input to the algorithm:
  57 .br
  58 .nf
  59    0  1                             11 12
  60    S..v..v..v..v..v..v..v..v..v..v..v..v..*..*..*
  61 .nf
  62 .br
  63 Only the top 13 bits are used as a signed input value.
  64 The output of gsm_decode() has the three lower bits set to zero.
  65 .\" .SH OPTIONS
  66 .SH "RETURN VALUE"
  67 gsm_create() returns an opaque handle object of type gsm, or 0 on error.
  68 gsm_decode() returns -1 if the passed frame is invalid, else 0.
  69 .SH EXAMPLE
  70 .nf
  71 #include "gsm.h"
  72
  73 gsm handle;
  74 gsm_frame buf;
  75 gsm_signal sample[160];
  76 int cc, soundfd;
  77
  78 play() {        /* read compressed data from standard input, write to soundfd */
  79
  80         if (!(handle = gsm_create())) error...
  81         while (cc = read(0, (char *)buf, sizeof buf)) {
  82                 if (cc != sizeof buf) error...
  83                 if (gsm_decode(handle, buf, sample) < 0) error...
  84                 if (write(soundfd, sample, sizeof sample) != sizeof sample)
  85                         error...
  86         }
  87         gsm_destroy(handle);
  88 }
  89
  90 record() {      /* read from soundfd, write compressed to standard output */
  91
  92         if (!(handle = gsm_create())) error...
  93         while (cc = read(soundfd, sample, sizeof sample)) {
  94                 if (cc != sizeof sample) error...
  95                 gsm_encode(handle, sample, buf);
  96                 if (write(1, (char *)buf, sizeof buf) != sizeof sample)
  97                         error...
  98         }
  99         gsm_destroy(handle);
 100 }
 101 .nf
 102 .SH BUGS
 103 Please direct bug reports to jutta@cs.tu-berlin.de and cabo@cs.tu-berlin.de.
 104 .SH "SEE ALSO"
 105 toast(1), gsm_print(3), gsm_explode(3), gsm_option(3)