Tristan Matthews | 0a329cc | 2013-07-17 13:20:14 -0400 | [diff] [blame] | 1 | .\" |
| 2 | .\" Copyright 1992-1995 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_OPTION 3 |
| 8 | .SH NAME |
| 9 | gsm_option \(em customizing the GSM 06.10 implementation |
| 10 | .SH SYNOPSIS |
| 11 | #include "gsm.h" |
| 12 | .PP |
| 13 | int gsm_option(handle, option, valueP); |
| 14 | .br |
| 15 | gsm handle; |
| 16 | .br |
| 17 | int option; |
| 18 | .br |
| 19 | int * valueP; |
| 20 | .SH "DESCRIPTION" |
| 21 | The gsm library is an implementation of the final draft GSM 06.10 |
| 22 | standard for full-rate speech transcoding, a lossy |
| 23 | speech compression algorithm. |
| 24 | .PP |
| 25 | The gsm_option() function can be used to set and query various |
| 26 | options or flags that are not needed for regular GSM 06.10 encoding |
| 27 | or decoding, but might be of interest in special cases. |
| 28 | .PP |
| 29 | The second argument to gsm_option specifies what parameter |
| 30 | should be changed or queried. |
| 31 | The third argument is either a null pointer, in which case |
| 32 | the current value of that parameter is returned; |
| 33 | or it is a pointer to an integer containing the value |
| 34 | you want to set, in which case the previous value will |
| 35 | be returned. |
| 36 | .PP |
| 37 | The following options are defined: |
| 38 | .PP |
| 39 | .I GSM_OPT_VERBOSE |
| 40 | Verbosity level. |
| 41 | .br |
| 42 | .in+5 |
| 43 | This option is only supported if the library was compiled |
| 44 | with debugging turned on, and may be used by developers of |
| 45 | compression algorithms to aid debugging. |
| 46 | .br |
| 47 | The verbosity level can be changed at any time during encoding or decoding. |
| 48 | .in-5 |
| 49 | .sp |
| 50 | .PP |
| 51 | .I GSM_OPT_FAST |
| 52 | Faster compression algorithm. |
| 53 | .br |
| 54 | .in+5 |
| 55 | This implementation offers a not strictly standard-compliant, but |
| 56 | faster compression algorithm that is compatible with the regular |
| 57 | method and does not noticably degrade audio quality. |
| 58 | .br |
| 59 | The value passed to |
| 60 | .br |
| 61 | .nf |
| 62 | gsm_option(handle, GSM_OPT_FAST, & value) |
| 63 | .fi |
| 64 | .br |
| 65 | functions as a boolean flag; if it is zero, the regular algorithm |
| 66 | will be used, if not, the faster version will be used. |
| 67 | .br |
| 68 | The availability of this option depends on the hardware used; |
| 69 | if it is not available, gsm_option will return -1 on an attempt |
| 70 | to set or query it. |
| 71 | .br |
| 72 | This option can be set any time during encoding or decoding. |
| 73 | .in-5 |
| 74 | .ne 5 |
| 75 | .sp |
| 76 | .PP |
| 77 | .I GSM_OPT_LTP_CUT |
| 78 | Enable, disable, or query the LTP cut-off optimization. |
| 79 | .br |
| 80 | .in+5 |
| 81 | During encoding, the search for the long-term correlation |
| 82 | lag forms the bottleneck of the algorithm. |
| 83 | The ltp-cut option enables an approximation that disregards most |
| 84 | of the samples for purposes of finding that correlation, |
| 85 | and hence speeds up the encoding at a noticable loss in quality. |
| 86 | .br |
| 87 | The value passed to |
| 88 | .br |
| 89 | .nf |
| 90 | gsm_option(handle, GSM_OPT_LTP_CUT, & value) |
| 91 | .fi |
| 92 | .br |
| 93 | turns the optimization on if nonzero, and off if zero. |
| 94 | .br |
| 95 | This option can be set any time during encoding |
| 96 | or decoding; it will only affect the encoding pass, not |
| 97 | the decoding. |
| 98 | .sp |
| 99 | .PP |
| 100 | .I GSM_OPT_WAV49 |
| 101 | WAV-style byte ordering. |
| 102 | .br |
| 103 | .in+5 |
| 104 | A WAV file of type #49 contains GSM 06.10-encoded frames. |
| 105 | Unfortunately, the framing and code ordering of the WAV version |
| 106 | are incompatible with the native ones of this GSM 06.10 library. |
| 107 | The GSM_OPT_WAV49 option turns on a different packing |
| 108 | algorithm that produces alternating frames of 32 and 33 bytes |
| 109 | (or makes it consume alternating frames of 33 and 32 bytes, note |
| 110 | the opposite order of the two numbers) which, when concatenated, |
| 111 | can be used in the body of a WAV #49 frame. |
| 112 | It is up to the user program to write a WAV header, if any; |
| 113 | neither the library itself nor the toast program produce |
| 114 | complete WAV files. |
| 115 | .br |
| 116 | The value passed to |
| 117 | .br |
| 118 | .nf |
| 119 | gsm_option(handle, GSM_OPT_WAV49, & value) |
| 120 | .fi |
| 121 | .br |
| 122 | functions as a boolean flag; if it is zero, the library's native |
| 123 | framing algorithm will be used, if nonzero, WAV-type packing is in effect. |
| 124 | .br |
| 125 | This option should be used before any frames are encoded. |
| 126 | Whether or not it is supported at all depends on a |
| 127 | compile-time switch, WAV49. |
| 128 | Both option and compile time switch are new to the library |
| 129 | as of patchlevel 9, and are considerably less tested than the |
| 130 | well-worn rest of the it. |
| 131 | .br |
| 132 | Thanks to Jeff Chilton for the detective work and first free |
| 133 | implementation of this version of the GSM 06.10 encoding. |
| 134 | .sp |
| 135 | .PP |
| 136 | .I GSM_OPT_FRAME_CHAIN |
| 137 | Query or set the chaining byte. |
| 138 | .br |
| 139 | .in+5 |
| 140 | Between the two frames of a WAV-style encoding, the GSM 06.10 library |
| 141 | must keep track of one half-byte that is technically part of the first |
| 142 | frame, but will be written as the first four bits of the second. |
| 143 | This half-byte are the lowest four bits of the value returned by, |
| 144 | and optionally set by, |
| 145 | .br |
| 146 | .nf |
| 147 | gsm_option(handle, GSM_OPT_FRAME_CHAIN, & value) |
| 148 | .fi |
| 149 | .br |
| 150 | This option can be queried and set at any time. |
| 151 | .sp |
| 152 | .PP |
| 153 | .I GSM_OPT_FRAME_INDEX |
| 154 | Query or set the current frame's index in a format's |
| 155 | alternating list of frames. |
| 156 | .br |
| 157 | .in+5 |
| 158 | The WAV #49 framing uses two alternating types of frames. |
| 159 | Which type the next GSM-coded frame belongs to can be queried, or, |
| 160 | when decoding, announced, using |
| 161 | .br |
| 162 | .nf |
| 163 | gsm_option(handle, GSM_OPT_FRAME_INDEX, & value) |
| 164 | .fi |
| 165 | .br |
| 166 | For WAV-style framing, the value should be 0 or 1; the first frame |
| 167 | of an encoding has an index of 0. |
| 168 | At library initialization, the index is set to zero. |
| 169 | .br |
| 170 | The frame index can be queried and set at any time. |
| 171 | Used in combination with the |
| 172 | .IR GSM_OPT_FRAME_CHAIN , |
| 173 | option, it can be used to position on arbitrary GSM frames |
| 174 | within a format like WAV #49 (not accounting for the lost |
| 175 | internal GSM state). |
| 176 | .in-5 |
| 177 | .SH "RETURN VALUE" |
| 178 | gsm_option() returns -1 if an option is not supported, the |
| 179 | previous value of the option otherwise. |
| 180 | .SH BUGS |
| 181 | Please direct bug reports to jutta@cs.tu-berlin.de and cabo@cs.tu-berlin.de. |
| 182 | .SH "SEE ALSO" |
| 183 | toast(1), gsm(3), gsm_explode(3), gsm_print(3) |