183 lines
5.5 KiB
Groff
183 lines
5.5 KiB
Groff
.\"
|
|
.\" Copyright 1992-1995 by Jutta Degener and Carsten Bormann, Technische
|
|
.\" Universitaet Berlin. See the accompanying file "COPYRIGHT" for
|
|
.\" details. THERE IS ABSOLUTELY NO WARRANTY FOR THIS SOFTWARE.
|
|
.\"
|
|
.PU
|
|
.TH GSM_OPTION 3
|
|
.SH NAME
|
|
gsm_option \(em customizing the GSM 06.10 implementation
|
|
.SH SYNOPSIS
|
|
#include "gsm.h"
|
|
.PP
|
|
int gsm_option(handle, option, valueP);
|
|
.br
|
|
gsm handle;
|
|
.br
|
|
int option;
|
|
.br
|
|
int * valueP;
|
|
.SH "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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
The following options are defined:
|
|
.PP
|
|
.I GSM_OPT_VERBOSE
|
|
Verbosity level.
|
|
.br
|
|
.in+5
|
|
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.
|
|
.br
|
|
The verbosity level can be changed at any time during encoding or decoding.
|
|
.in-5
|
|
.sp
|
|
.PP
|
|
.I GSM_OPT_FAST
|
|
Faster compression algorithm.
|
|
.br
|
|
.in+5
|
|
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.
|
|
.br
|
|
The value passed to
|
|
.br
|
|
.nf
|
|
gsm_option(handle, GSM_OPT_FAST, & value)
|
|
.fi
|
|
.br
|
|
functions as a boolean flag; if it is zero, the regular algorithm
|
|
will be used, if not, the faster version will be used.
|
|
.br
|
|
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.
|
|
.br
|
|
This option can be set any time during encoding or decoding.
|
|
.in-5
|
|
.ne 5
|
|
.sp
|
|
.PP
|
|
.I GSM_OPT_LTP_CUT
|
|
Enable, disable, or query the LTP cut-off optimization.
|
|
.br
|
|
.in+5
|
|
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 quality.
|
|
.br
|
|
The value passed to
|
|
.br
|
|
.nf
|
|
gsm_option(handle, GSM_OPT_LTP_CUT, & value)
|
|
.fi
|
|
.br
|
|
turns the optimization on if nonzero, and off if zero.
|
|
.br
|
|
This option can be set any time during encoding
|
|
or decoding; it will only affect the encoding pass, not
|
|
the decoding.
|
|
.sp
|
|
.PP
|
|
.I GSM_OPT_WAV49
|
|
WAV-style byte ordering.
|
|
.br
|
|
.in+5
|
|
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.
|
|
.br
|
|
The value passed to
|
|
.br
|
|
.nf
|
|
gsm_option(handle, GSM_OPT_WAV49, & value)
|
|
.fi
|
|
.br
|
|
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.
|
|
.br
|
|
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.
|
|
.br
|
|
Thanks to Jeff Chilton for the detective work and first free
|
|
implementation of this version of the GSM 06.10 encoding.
|
|
.sp
|
|
.PP
|
|
.I GSM_OPT_FRAME_CHAIN
|
|
Query or set the chaining byte.
|
|
.br
|
|
.in+5
|
|
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,
|
|
.br
|
|
.nf
|
|
gsm_option(handle, GSM_OPT_FRAME_CHAIN, & value)
|
|
.fi
|
|
.br
|
|
This option can be queried and set at any time.
|
|
.sp
|
|
.PP
|
|
.I GSM_OPT_FRAME_INDEX
|
|
Query or set the current frame's index in a format's
|
|
alternating list of frames.
|
|
.br
|
|
.in+5
|
|
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
|
|
.br
|
|
.nf
|
|
gsm_option(handle, GSM_OPT_FRAME_INDEX, & value)
|
|
.fi
|
|
.br
|
|
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.
|
|
.br
|
|
The frame index can be queried and set at any time.
|
|
Used in combination with the
|
|
.IR 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).
|
|
.in-5
|
|
.SH "RETURN VALUE"
|
|
gsm_option() returns -1 if an option is not supported, the
|
|
previous value of the option otherwise.
|
|
.SH BUGS
|
|
Please direct bug reports to jutta@cs.tu-berlin.de and cabo@cs.tu-berlin.de.
|
|
.SH "SEE ALSO"
|
|
toast(1), gsm(3), gsm_explode(3), gsm_print(3)
|