1GSM_OPTION(3)              Library Functions Manual              GSM_OPTION(3)
2
3
4

NAME

6       gsm_option — customizing the GSM 06.10 implementation
7

SYNOPSIS

9       #include "gsm.h"
10
11       int gsm_option(handle, option, valueP);
12       gsm handle;
13       int option;
14       int * valueP;
15

DESCRIPTION

17       The gsm library is an implementation of the final draft GSM 06.10 stan‐
18       dard for full-rate speech transcoding, a lossy speech compression algo‐
19       rithm.
20
21       The  gsm_option() function can be used to set and query various options
22       or flags that are not needed for regular GSM 06.10 encoding  or  decod‐
23       ing, but might be of interest in special cases.
24
25       The  second  argument  to gsm_option specifies what parameter should be
26       changed or queried.  The third argument is either a  null  pointer,  in
27       which  case the current value of that parameter is returned; or it is a
28       pointer to an integer containing the value you want to  set,  in  which
29       case the previous value will be returned.
30
31       The following options are defined:
32
33       GSM_OPT_VERBOSE Verbosity level.
34       This  option  is only supported if the library was compiled with debug‐
35       ging turned on, and may be used by developers of compression algorithms
36       to aid debugging.
37       The  verbosity  level  can  be  changed  at any time during encoding or
38       decoding.
39
40
41       GSM_OPT_FAST Faster compression algorithm.
42       This implementation  offers  a  not  strictly  standard-compliant,  but
43       faster compression algorithm that is compatible with the regular method
44       and does not noticably degrade audio quality.
45       The value passed to
46            gsm_option(handle, GSM_OPT_FAST, & value)
47       functions as a boolean flag; if it is zero, the regular algorithm  will
48       be used, if not, the faster version will be used.
49       The  availability of this option depends on the hardware used; if it is
50       not available, gsm_option will return -1 on an attempt to set or  query
51       it.
52       This option can be set any time during encoding or decoding.
53
54
55       GSM_OPT_LTP_CUT Enable, disable, or query the LTP cut-off optimization.
56       During encoding, the search for the long-term correlation lag forms the
57       bottleneck of the algorithm.  The ltp-cut option enables an  approxima‐
58       tion  that  disregards most of the samples for purposes of finding that
59       correlation, and hence speeds up the encoding at a  noticable  loss  in
60       quality.
61       The value passed to
62            gsm_option(handle, GSM_OPT_LTP_CUT, & value)
63       turns the optimization on if nonzero, and off if zero.
64       This  option  can  be set any time during encoding or decoding; it will
65       only affect the encoding pass, not the decoding.
66
67
68       GSM_OPT_WAV49 WAV-style byte ordering.
69       A WAV file of type #49 contains  GSM  06.10-encoded  frames.   Unfortu‐
70       nately, the framing and code ordering of the WAV version are incompati‐
71       ble with the native ones of this GSM 06.10 library.  The  GSM_OPT_WAV49
72       option turns on a different packing algorithm that produces alternating
73       frames of 32 and 33 bytes (or makes it consume alternating frames of 33
74       and  32  bytes, note the opposite order of the two numbers) which, when
75       concatenated, can be used in the body of a WAV #49 frame.  It is up  to
76       the  user  program  to  write a WAV header, if any; neither the library
77       itself nor the toast program produce complete WAV files.
78       The value passed to
79            gsm_option(handle, GSM_OPT_WAV49, & value)
80       functions as a boolean flag; if it is zero, the library's native  fram‐
81       ing algorithm will be used, if nonzero, WAV-type packing is in effect.
82       This  option  should be used before any frames are encoded.  Whether or
83       not it is supported at all depends on  a  compile-time  switch,  WAV49.
84       Both option and compile time switch are new to the library as of patch‐
85       level 9, and are considerably less tested than the  well-worn  rest  of
86       the it.
87       Thanks  to Jeff Chilton for the detective work and first free implemen‐
88       tation of this version of the GSM 06.10 encoding.
89
90
91       GSM_OPT_FRAME_CHAIN Query or set the chaining byte.
92       Between the two frames of a WAV-style encoding, the GSM  06.10  library
93       must  keep track of one half-byte that is technically part of the first
94       frame, but will be written as the first four bits of the second.   This
95       half-byte  are  the  lowest  four  bits  of  the value returned by, and
96       optionally set by,
97            gsm_option(handle, GSM_OPT_FRAME_CHAIN, & value)
98       This option can be queried and set at any time.
99
100
101       GSM_OPT_FRAME_INDEX Query or set the current frame's index  in  a  for‐
102       mat's alternating list of frames.
103       The  WAV  #49 framing uses two alternating types of frames.  Which type
104       the next GSM-coded frame belongs to can be queried, or, when  decoding,
105       announced, using
106            gsm_option(handle, GSM_OPT_FRAME_INDEX, & value)
107       For  WAV-style  framing, the value should be 0 or 1; the first frame of
108       an encoding has an index of 0.  At library initialization, the index is
109       set to zero.
110       The  frame  index can be queried and set at any time.  Used in combina‐
111       tion with the GSM_OPT_FRAME_CHAIN, option, it can be used  to  position
112       on  arbitrary  GSM  frames within a format like WAV #49 (not accounting
113       for the lost internal GSM state).
114

RETURN VALUE

116       gsm_option() returns -1 if an option is  not  supported,  the  previous
117       value of the option otherwise.
118

BUGS

120       Please  direct  bug  reports  to  jutta@cs.tu-berlin.de and cabo@cs.tu-
121       berlin.de.
122

SEE ALSO

124       toast(1), gsm(3), gsm_explode(3), gsm_print(3)
125
126
127
128                                                                 GSM_OPTION(3)
Impressum