← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.1.0/third_party/gsm/man/gsm_option.3

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (1.1.11)
  • mto: This revision was merged to the branch mainline in revision 24.
  • Revision ID: package-import@ubuntu.com-20140128182336-3xenud1kbnwmf3mz
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.1.0/third_party/gsm/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)