1GSM_OPTION(3) Library Functions Manual GSM_OPTION(3)
2
6 gsm_option — customizing the GSM 06.10 implementation
7
9 #include "gsm.h"
10 int gsm_option(handle, option, valueP);
12 gsm handle;
13 int option;
14 int * valueP;
15
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 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 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 The following options are defined:
32 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 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 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 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 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 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
116 gsm_option() returns -1 if an option is not supported, the previous
117 value of the option otherwise.
118
120 Please direct bug reports to jutta@pobox.com and cabo@tzi.org.
121
123 toast(1), gsm(3), gsm_explode(3), gsm_print(3)
124 GSM_OPTION(3)