Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GSM_OPTION(3)		   Library Functions Manual		 GSM_OPTION(3)

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 stan-
       dard for	full-rate speech transcoding, a	lossy speech compression algo-
       rithm.

       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	decod-
       ing, 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	debug-
       ging 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 de-
       coding.

       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 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 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  approxima-
       tion  that  disregards most of the samples for purposes of finding that
       correlation, and	hence speeds up	the encoding at	a  noticable  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.   Unfortu-
       nately, the framing and code ordering of	the WAV	version	are incompati-
       ble 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 it-
       self 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	 fram-
       ing 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	patch-
       level 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 implemen-
       tation 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 op-
       tionally	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  for-
       mat'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 combina-
       tion 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)

								 GSM_OPTION(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | BUGS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=gsm_option&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help