diff options
author | David M. Lee <dlee@digium.com> | 2013-01-07 14:24:28 -0600 |
---|---|---|
committer | David M. Lee <dlee@digium.com> | 2013-01-07 14:24:28 -0600 |
commit | f3ab456a17af1c89a6e3be4d20c5944853df1cb0 (patch) | |
tree | d00e1a332cd038a6d906a1ea0ac91e1a4458e617 /third_party/gsm/man |
Import pjproject-2.0.1
Diffstat (limited to 'third_party/gsm/man')
-rw-r--r-- | third_party/gsm/man/bitter.1 | 70 | ||||
-rw-r--r-- | third_party/gsm/man/gsm.3 | 105 | ||||
-rw-r--r-- | third_party/gsm/man/gsm_explode.3 | 47 | ||||
-rw-r--r-- | third_party/gsm/man/gsm_option.3 | 183 | ||||
-rw-r--r-- | third_party/gsm/man/gsm_print.3 | 52 | ||||
-rw-r--r-- | third_party/gsm/man/toast.1 | 156 |
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 0000000..2dad78b --- /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 0000000..e465762 --- /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 0000000..ef89984 --- /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 0000000..8df7da0 --- /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 0000000..48d6883 --- /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 0000000..e54647b --- /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". |