Split speex, portaudio, and gsm into third_party directory

git-svn-id: http://svn.pjsip.org/repos/pjproject/branches/split-3rd-party@1168 74dad513-b988-da41-8d7b-12977e46ad98

6 files changed, 613 insertions, 0 deletions

diff --git a/third_party/gsm/man/bitter.1 b/third_party/gsm/man/bitter.1
new file mode 100644
index 00000000..2dad78b0
--- /dev/null
+++ b/third_party/gsm/man/bitter.1
@@ -0,0 +1,70 @@
+.\"
+.\" Copyright 1992 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 BITTER 1 
+.SH NAME
+bitter, sweet \(em code-generators for packing bits
+.SH SYNOPSIS
+bitter < input > output
+.br
+sweet < input > output
+.SH "DESCRIPTION"
+Bitter and sweet are two filters which turn a description of the
+form 
+.nf
+	name	number-of-bits
+	name 	number-of-bits
+	...
+.nf
+into code.
+.PP
+Bitter generates code that packs the specified bits from their
+variables into an array of unsigned char referenced by an
+advancing pointer c.
+.PP
+Sweet generates code that unpacks the specified bits from an array
+of unsigned char referenced by a mutable pointer c into the
+named variables.
+.\" .SH OPTIONS
+.\" .SH "RETURN VALUE"
+.\" .SH ERRORS
+.SH EXAMPLES
+.nf
+% cat in
+amaretto 1
+banana 2
+cherry 3
+strawberry 4
+vanilla 15
+walnut 15
+
+% bitter < in
+	*c++ =   ((amaretto & 0x1) << 7)
+	       | ((banana & 0x3) << 5)
+	       | ((cherry & 0x7) << 2)
+	       | ((strawberry >> 2) & 0x3);
+	*c++ =   ((strawberry & 0x3) << 6)
+	       | ((vanilla >> 9) & 0x3F);
+	*c++ =   ((vanilla >> 1) & 0xFF);
+	*c++ =   ((vanilla & 0x1) << 7)
+	       | ((walnut >> 8) & 0x7F);
+	*c++ =   walnut & 0xFF;
+
+% sweet < in
+	amaretto  = (*c >> 7) & 0x1;
+	banana  = (*c >> 5) & 0x3;
+	cherry  = (*c >> 2) & 0x7;
+	strawberry  = (*c++ & 0x3) << 2;
+	strawberry |= (*c >> 6) & 0x3;
+	vanilla  = (*c++ & 0x3F) << 9;
+	vanilla |= (*c++ & 0xFF) << 1;
+	vanilla |= (*c >> 7) & 0x1;
+	walnut  = (*c++ & 0x7F) << 8;
+	walnut |= *c++;
+.SH NOTES
+This is a quick hack for the gsm_encode() and gsm_decode() routines.
+.SH BUGS
+Please direct bug reports to jutta@cs.tu-berlin.de and cabo@cs.tu-berlin.de.
diff --git a/third_party/gsm/man/gsm.3 b/third_party/gsm/man/gsm.3
new file mode 100644
index 00000000..e465762b
--- /dev/null
+++ b/third_party/gsm/man/gsm.3
@@ -0,0 +1,105 @@
+.\"
+.\" Copyright 1992 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 3 
+.SH NAME
+gsm_create, gsm_destroy, gsm_encode, gsm_decode \(em GSM\ 06.10 lossy sound compression
+.SH SYNOPSIS
+.PP
+#include "gsm.h"
+.PP
+gsm gsm_create();
+.PP
+void gsm_encode(handle, src, dst)
+.br
+gsm handle;
+.br
+gsm_signal src[160];
+.br
+gsm_frame dst;
+.PP
+int gsm_decode(handle, src, dst)
+.br
+gsm handle;
+.br
+gsm_frame src;
+.br
+gsm_signal dst[160];
+.PP
+void gsm_destroy(handle)
+.br
+gsm handle;
+.br
+.SH "DESCRIPTION"
+Gsm is an implementation of the final draft GSM 06.10
+standard for full-rate speech transcoding.
+.PP
+gsm_create() initializes a gsm pass and returns a 'gsm' object
+which can be used as a handle in subsequent calls to gsm_decode(),
+gsm_encode() or gsm_destroy().
+.PP
+gsm_encode() encodes an array of 160 13-bit samples (given as
+gsm_signal's, signed integral values of at least 16 bits) into
+a gsm_frame of 33 bytes.
+(gsm_frame is a type defined as an array of 33 gsm_bytes in gsm.h.)
+.PP
+gsm_decode() decodes a gsm_frame into an array of 160 13-bit samples
+(given as gsm_signals), which sound rather like what you handed to
+gsm_encode() on the other side of the wire.
+.PP
+gsm_destroy() finishes a gsm pass and frees all storage associated
+with it.
+.SS "Sample format"
+The following scaling is assumed for input to the algorithm:
+.br
+.nf
+   0  1                             11 12
+   S..v..v..v..v..v..v..v..v..v..v..v..v..*..*..*
+.nf
+.br
+Only the top 13 bits are used as a signed input value.
+The output of gsm_decode() has the three lower bits set to zero.
+.\" .SH OPTIONS
+.SH "RETURN VALUE"
+gsm_create() returns an opaque handle object of type gsm, or 0 on error.
+gsm_decode() returns -1 if the passed frame is invalid, else 0.
+.SH EXAMPLE
+.nf
+#include "gsm.h"
+
+gsm handle;
+gsm_frame buf;
+gsm_signal sample[160];
+int cc, soundfd;
+
+play() {	/* read compressed data from standard input, write to soundfd */
+
+	if (!(handle = gsm_create())) error...
+	while (cc = read(0, (char *)buf, sizeof buf)) {
+		if (cc != sizeof buf) error...
+		if (gsm_decode(handle, buf, sample) < 0) error... 
+		if (write(soundfd, sample, sizeof sample) != sizeof sample)
+			error...
+	}
+	gsm_destroy(handle);
+}
+
+record() {	/* read from soundfd, write compressed to standard output */
+
+	if (!(handle = gsm_create())) error...
+	while (cc = read(soundfd, sample, sizeof sample)) {
+		if (cc != sizeof sample) error...
+		gsm_encode(handle, sample, buf);
+		if (write(1, (char *)buf, sizeof buf) != sizeof sample) 
+			error...
+	}
+	gsm_destroy(handle);
+}
+.nf
+.SH BUGS
+Please direct bug reports to jutta@cs.tu-berlin.de and cabo@cs.tu-berlin.de.
+.SH "SEE ALSO"
+toast(1), gsm_print(3), gsm_explode(3), gsm_option(3)
diff --git a/third_party/gsm/man/gsm_explode.3 b/third_party/gsm/man/gsm_explode.3
new file mode 100644
index 00000000..ef899842
--- /dev/null
+++ b/third_party/gsm/man/gsm_explode.3
@@ -0,0 +1,47 @@
+.\"
+.\" Copyright 1992 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_EXPLODE 3 
+.SH NAME
+gsm_explode, gsm_implode \(em GSM\ 06.10 supplementary
+functions for testing
+.SH SYNOPSIS
+#include "gsm.h"
+.PP
+void gsm_explode(g, frame, xframe)
+.br
+gsm        g;
+.br
+gsm_frame  frame;
+.br
+gsm_signal xframe[ 76 ];
+.PP
+void gsm_implode(g, xframe, frame)
+.br
+gsm        g;
+.br
+gsm_signal xframe[ 76 ];
+.br
+gsm_frame  frame;
+.SH "DESCRIPTION"
+Gsm is an implementation of the final draft GSM 06.10
+standard for full-rate speech transcoding.
+Test data for implementations of this particular document
+can be bought and used to verify an implementation.
+.PP
+The encoded test data uses a format different from what
+one would use to transmit frames with the least number
+of bits.
+Gsm_explode() and gsm_implode() convert between the
+internal, small, 33-byte format and the 76-word format
+used by the test data.
+.PP
+.SH "RETURN VALUE"
+gsm_explode() returns -1 if the passed frame is invalid, else 0.
+.SH BUGS
+Please direct bug reports to jutta@cs.tu-berlin.de and cabo@cs.tu-berlin.de.
+.SH "SEE ALSO"
+gsm(3)
diff --git a/third_party/gsm/man/gsm_option.3 b/third_party/gsm/man/gsm_option.3
new file mode 100644
index 00000000..8df7da08
--- /dev/null
+++ b/third_party/gsm/man/gsm_option.3
@@ -0,0 +1,183 @@
+.\"
+.\" 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)
diff --git a/third_party/gsm/man/gsm_print.3 b/third_party/gsm/man/gsm_print.3
new file mode 100644
index 00000000..48d68831
--- /dev/null
+++ b/third_party/gsm/man/gsm_print.3
@@ -0,0 +1,52 @@
+.\"
+.\" Copyright 1992 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_PRINT 3 
+.SH NAME
+gsm_print \(em GSM\ 06.10 supplementary function for debugging
+.SH SYNOPSIS
+#include "gsm.h"
+#include <stdio.h>
+
+int gsm_print(f, g, frame);
+.br
+FILE * f;
+.br
+gsm    g;
+.br
+gsm_frame frame;
+.SH "DESCRIPTION"
+Gsm is an implementation of the final draft GSM 06.10
+standard for full-rate speech transcoding, a lossy
+speech compression algorithm.
+The compressed form involves 76 variables with different numbers
+of significant bits packed into 33 bytes.
+.PP
+If you are interested in investigating the details of this
+coding scheme, gsm_print() can be used to dump the contents
+of individual gsm_frames to a file pointer provided by
+the application.
+.PP
+.SH "RETURN VALUE"
+gsm_print() returns -1 if the frame is invalid, else 0.
+.SH EXAMPLE
+A single frame looks like this:
+.br
+.nf
+LARc:   29  32  20  11  08  05  06  07
+#1:     Nc 0040    bc 0    Mc 1    xmaxc 60
+        06 04 00 03 03 06 04 02 02 04 05 04 01
+#2:     Nc 0045    bc 1    Mc 1    xmaxc 48
+        03 07 01 03 04 04 07 01 03 02 04 05 03
+#3:     Nc 0091    bc 1    Mc 1    xmaxc 46
+        00 03 03 07 01 06 02 04 05 03 03 02 04
+#4:     Nc 0120    bc 0    Mc 1    xmaxc 47
+        07 03 06 00 03 03 06 05 00 03 02 07 04
+.nf
+.SH BUGS
+Please direct bug reports to jutta@cs.tu-berlin.de and cabo@cs.tu-berlin.de.
+.SH "SEE ALSO"
+gsm(3), gsm_explode(3) 
diff --git a/third_party/gsm/man/toast.1 b/third_party/gsm/man/toast.1
new file mode 100644
index 00000000..e54647b5
--- /dev/null
+++ b/third_party/gsm/man/toast.1
@@ -0,0 +1,156 @@
+.\"
+.\" Copyright 1992 by Jutta Degener and Carsten Bormann, Technische
+.\" Universitaet Berlin.  See the accompanying file "COPYRIGHT" for
+.\" details.  THERE IS ABSOLUTELY NO WARRANTY FOR THIS SOFTWARE.
+.\"
+.if n .ds mU u
+.if t .ds mU \(*m
+.\"
+.TH TOAST 1 local
+.SH NAME
+toast \(em GSM\ 06.10 lossy sound compression
+.SH SYNOPSIS
+.ll +8
+.B toast
+[
+.B \-cdfpvhualsFC
+] [
+.I "filename...\&"
+]
+.LP
+.B untoast
+[
+.B \-cfpvhuaslF
+] [
+.I "filename...\&"
+]
+.LP
+.B tcat
+[
+.B \-vhuaslF
+] [
+.I "filename...\&"
+]
+.ll -8
+.SH DESCRIPTION
+Toast compresses the sound files given on its command line.
+Each file is replaced by a file with the extension
+.I \&.gsm .
+If no files are specified, the compression is applied to the
+standard input, and its result is written to standard output.
+.PP
+Toasted files can be restored to something not quite unlike
+their original form by running toast
+.I "\-d"
+, or 
+.I untoast
+, on the \&.gsm-files or standard input.
+.PP
+The program 
+.I tcat
+(the same as running
+.I "untoast \-c"
+)  uncompresses its input on standard output,
+but leaves the compressed .gsm\-files alone.
+.PP
+When files are compressed or uncompressed into other files,
+the ownership (if run by root), modes, accessed and modified times
+are maintained between both versions.
+.SH OPTIONS
+.TP
+.B \-c
+(cat)
+Write to the standard output; no files are changed.
+.TP
+.B \-d
+(decode)
+Decode, rather than encode, the files.
+.TP
+.B \-f
+(force)
+Force replacement of output files if they exist.
+If \-f is omitted and toast (or untoast) is run interactively from
+a terminal, the user is prompted as to whether the file should be replaced.
+.TP
+.B \-p
+(precious)
+Do not delete the source files.
+Source files are implicitly left alone whenever \-c is
+specified or tcat is run.
+.TP
+.B \-C
+(LTP cut-off)
+Ignore most sample values when calculating the GSM long-term
+correlation lag during encoding.
+(The multiplications that do this are a bottleneck
+of the algorithm.)
+The resulting encoding process will not produce
+exactly the same results as GSM 06.10 would,
+but remains close enough to be compatible.
+.br
+The
+.B \-C
+option applies only to the encoder and is silently
+ignored by the decoder.
+.TP
+.B \-F
+(fast)
+On systems with a floating point processor, but without
+a multiplication instruction, \-F sacrifices standard conformance to
+performance and nearly doubles the speed of the algorithm.
+.br
+The resulting encoding and decoding process will not produce
+exactly the same results as GSM 06.10 would, but remains close
+enough to be compatible.
+.br
+The default is standard-conforming operation.
+.TP
+.B \-v
+(version)\ 
+outputs the version of toast (or untoast or tcat) to stdout and exits.
+.TP
+.B \-h
+(help)\ 
+prints a short overview of the options.
+.PP
+Toast, untoast and tcat try to guess the appropriate audio data 
+format from the file suffix.
+Command line options can also specify a format to be used for 
+all files.
+.br
+The following formats are supported:
+.TP
+.B "\-u"
+(\(*mU-law)
+8 kHz, 8 bit \(*mU-law encoding (file suffix .u)
+.TP
+.B "\-a"
+(A-law)
+8 kHz, 8 bit A-law encoding (file suffix .A)
+.TP
+.B "\-s"
+(Sun audio)
+8 kHz, 8 bit \(*mU-law encoding with audio header (file suffix .au)
+.TP
+.B "-l"
+(linear)
+8 kHz, 16 bit signed linear encoding in host byte order
+with 13 significant bits (file suffix .l)
+.PP
+In absence of options or suffixes to specify a format, 
+\(*mU-law encoding as forced by \-u is assumed.
+.PP
+.SH PECULIARITIES
+A four bit magic number is prefixed to each 32 1/2-byte GSM frame,
+mainly because 32 1/2-bytes are rather clumsy to handle.
+.SH WARNING
+The compression algorithm used is a lossy compression algorithm
+devised especially for speech; on no account should it be used
+for text, pictures or any other non-speech-data you consider
+valuable.
+.SH BUGS
+Please direct bug reports to jutta@cs.tu-berlin.de.
+.SH "SEE ALSO"
+gsm(3)
+.\"
+.\" Toast is dedicated to Bill Sienkiewicz, author of "Stray Toasters".