libgsmfr/man/gsm_option.3

   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)