gsm_option -- customizing the GSM 06.10 implementation
SYNOPSIS
#include "gsm.h"
int gsm_option(handle, option, valueP);
gsm handle;
int option;
int * valueP;
DESCRIPTION
The gsm library is an implementation of the final draft
GSM 06.10 standard for full-rate speech transcoding, a
lossy speech compression algorithm.
The gsm_option() function can be used to set and query
various options or flags that are not needed for regular
GSM 06.10 encoding or decoding, but might be of interest
in special cases.
The second argument to gsm_option specifies what parameter
should be changed or queried. The third argument is
either a null pointer, in which case the current value of
that parameter is returned; or it is a pointer to an inte
ger containing the value you want to set, in which case
the previous value will be returned.
The following options are defined:
GSM_OPT_VERBOSE Verbosity level.
This option is only supported if the library was compiled
with debugging turned on, and may be used by developers of
compression algorithms to aid debugging.
The verbosity level can be changed at any time during
encoding or decoding.
GSM_OPT_FAST Faster compression algorithm.
This implementation offers a not strictly standard-compli
ant, but faster compression algorithm that is compatible
with the regular method and does not noticably degrade
audio quality.
The value passed to
gsm_option(handle, GSM_OPT_FAST, & value)
functions as a boolean flag; if it is zero, the regular
algorithm will be used, if not, the faster version will be
used.
The availability of this option depends on the hardware
used; if it is not available, gsm_option will return -1 on
an attempt to set or query it.
This option can be set any time during encoding or decod
GSM_OPT_LTP_CUT Enable, disable, or query the LTP cut-off
optimization.
During encoding, the search for the long-term correlation
lag forms the bottleneck of the algorithm. The ltp-cut
option enables an approximation that disregards most of
the samples for purposes of finding that correlation, and
hence speeds up the encoding at a noticable loss in qual
ity.
The value passed to
gsm_option(handle, GSM_OPT_LTP_CUT, & value)
turns the optimization on if nonzero, and off if zero.
This option can be set any time during encoding or decod
ing; it will only affect the encoding pass, not the decod
ing.
GSM_OPT_WAV49 WAV-style byte ordering.
A WAV file of type #49 contains GSM 06.10-encoded frames.
Unfortunately, the framing and code ordering of the WAV
version are incompatible with the native ones of this GSM
06.10 library. The GSM_OPT_WAV49 option turns on a dif
ferent packing algorithm that produces alternating frames
of 32 and 33 bytes (or makes it consume alternating frames
of 33 and 32 bytes, note the opposite order of the two
numbers) which, when concatenated, can be used in the body
of a WAV #49 frame. It is up to the user program to write
a WAV header, if any; neither the library itself nor the
toast program produce complete WAV files.
The value passed to
gsm_option(handle, GSM_OPT_WAV49, & value)
functions as a boolean flag; if it is zero, the library's
native framing algorithm will be used, if nonzero, WAV-
type packing is in effect.
This option should be used before any frames are encoded.
Whether or not it is supported at all depends on a com
pile-time switch, WAV49. Both option and compile time
switch are new to the library as of patchlevel 9, and are
considerably less tested than the well-worn rest of the
it.
Thanks to Jeff Chilton for the detective work and first
free implementation of this version of the GSM 06.10
encoding.
GSM_OPT_FRAME_CHAIN Query or set the chaining byte.
Between the two frames of a WAV-style encoding, the GSM
06.10 library must keep track of one half-byte that is
technically part of the first frame, but will be written
as the first four bits of the second. This half-byte are
the lowest four bits of the value returned by, and option
ally set by,
This option can be queried and set at any time.
GSM_OPT_FRAME_INDEX Query or set the current frame's index
in a format's alternating list of frames.
The WAV #49 framing uses two alternating types of frames.
Which type the next GSM-coded frame belongs to can be
queried, or, when decoding, announced, using
gsm_option(handle, GSM_OPT_FRAME_INDEX, & value)
For WAV-style framing, the value should be 0 or 1; the
first frame of an encoding has an index of 0. At library
initialization, the index is set to zero.
The frame index can be queried and set at any time. Used
in combination with the GSM_OPT_FRAME_CHAIN, option, it
can be used to position on arbitrary GSM frames within a
format like WAV #49 (not accounting for the lost internal
GSM state).
RETURN VALUE
gsm_option() returns -1 if an option is not supported, the
previous value of the option otherwise.
BUGS
Please direct bug reports to jutta@cs.tu-berlin.de and
cabo@cs.tu-berlin.de.
SEE ALSO
toast(1), gsm(3), gsm_explode(3), gsm_print(3)
Man(1) output converted with
man2html