| Tristan Matthews | 0a329cc | 2013-07-17 13:20:14 -0400 | [diff] [blame^] | 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) |