NAME

       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 integer 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-compliant,  but  faster  compression  algorithm
              that is compatible with the regular method and does not noticeably 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 decoding.

       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  noticeable  loss  in
              quality.
              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 decoding; it will only affect the encoding
              pass, not the decoding.

       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 different 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  compile-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 optionally set
              by,
                   gsm_option(handle, GSM_OPT_FRAME_CHAIN, & value)
              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@pobox.com and cabo@tzi.org.

SEE ALSO

       toast(1), gsm(3), gsm_explode(3), gsm_print(3)

                                                                                                   GSM_OPTION(3)