SHORTEN(1)

NAME
shorten - fast compression for waveform files

SYNOPSIS
shorten [-hlu] [-a #bytes] [-b #samples] [-c #channels] [-d #bytes] [-m #blocks] [-n #dB] [-p #order] [-q #bits] [-r #bits] [-t filetype] [-v #version] [waveform-file [shortened-file]]

shorten -x [-hl] [ -a #bytes] [-d #bytes] [shortened-file [waveform-file]]

shorten [ -e | -i | -k | -s | -S<name> ] shortened-file

shorten [ -s | -S<name> ] < shortened-data

DESCRIPTION

shorten reduces the size of waveform files (such as audio) using Huffman coding of prediction residuals and optional additional quantisation. In lossless mode the amount of compression obtained depends on the nature of the waveform. Those composing of low frequencies and low amplitudes give the best compression, which may be 2:1 or better. Lossy compression operates by specifying a minimum acceptable segmental signal to noise ratio or a maximum bit rate. Lossy compression operates by zeroing the lower order bits of the waveform, so retaining waveform shape.

If both file names are specified then these are used as the input and output files. The first file name can be replaced by "-" to read from standard input and likewise the second filename can be replaced by "-" to write to standard output. Under UNIX, if only one file name is specified, then that name is used for input and the output file name is generated by adding the suffix ".shn" on compression and removing the ".shn" suffix on decompression. In these cases the input file is removed on completion. The use of automatic file name generation is not currently supported under DOS. If no file names are specified, shorten reads from standard input and writes to standard output. Whenever possible, the output file inherits the permissions, owner, group, access and modification times of the input file.

From release 2.3 the RIFF WAVE (Microsoft .wav) file type is the default. These files contain enough information to set most of the switches presented below, so effective operation is obtained just by setting the desired level of compression (-n or -r switch).

OPTIONS

-a align bytes
    Specify the number of bytes to be copied verbatim before compression begins. This option can be used to preserve fixed length ASCII headers on waveform files, and may be necessary if the header length is an odd number of bytes.

-b block size
    Specify the number of samples to be grouped into a block for processing. Within a block the signal elements are expected to have the same spectral characteristics. The default option works well for a large range of audio files.

-c channels
    Specify the number of independent interwoven channels. For two signals, a(t) and b(t) the original data format is assumed to be a(0),b(0),a(1),b(1)...

-d discard bytes
    Specify the number of bytes to be discarded before compression or decompression. This may be used to delete header information from a file. Refer to the -a option for storing the header information in the compressed file.

-e  Erase seek information from an existing file.

-h  Give a short message specifying usage options.

-i  Inquire as to whether the given file is an external seek table file, a file with seek tables appended to it, or neither. If seek tables are present, the seek table revision number is shown.

-k  Append seek information to an existing file.

-l  Prints the software license specifying the conditions for the distribution and usage of this software.

-m blocks
    Specify the number of past blocks to be used to estimate the mean and power of the signal. The value of zero disables this prediction and the mean is assumed to lie in the middle of the range of the relevant data type (i.e. at zero for signed quantities). The default value is non-zero for format versions 2.0 and above.

-n noise level
    Specify the minimum acceptable segmental signal to noise ratio in dB. The signal power is taken as the variance of the samples in the current block. The noise power is the quantisation noise incurred by coding the current block assuming that samples are uniformally distributed over the quantisation interval. The bit rate is dynamically changed to maintain the desired signal to noise ratio. The default value represents lossless coding.

-p prediction order
    Specify the maximum order of the linear predictive filter. The default value of zero disables the use of linear prediction and a polynomial interpolation method is used instead. The use of the linear predictive filter generally results in a small improvement in compression ratio at the expense of execution time. This is the only option to use a significant amount of floating point processing during compression. Decompression still uses a minimal number of floating point operations. Decompression time is normally about twice that of the default polynomial interpolation. For version 0 and 1, compression time is linear in the specified maximum order as all lower values are searched for the greatest expected compression (the number of bits required to transmit the prediction residual is monotonically decreasing with prediction order, but transmitting each filter coefficient requires about 7 bits). For version 2 and above, the search is started at zero order and terminated when the last two prediction orders give a larger expected bit rate than the minimum found to date. This is a reasonable strategy for many real world signals - you may revert back to the exhaustive algorithm by setting -v1 to check that this works for your signal type.

-q quantisation level
    Specify the number of low order bits in each sample which can be discarded (set to zero). This is useful if these bits carry no information, for example when the signal is corrupted by noise.

-r bit rate
    Specify the expected maximum number of bits per sample. The upper bound on the bit rate is achieved by setting the low order bits of the sample to zero, hence maximising the segmental signal to noise ratio.

-s  Write seek table information to a separate file (uses shortened file name with '.skt' extension). If the shortened data is read from standard input, then the seek table information will be saved in 'stdin.skt'.

-S<name>
    Write seek table information to a separate file given by "<name>".

-t file type
    Gives the type of the sound sample file as one of aiff, wav, s8, u8, s16, u16, s16x, u16x, s16hl, u16hl, s16lh, u16lh, ulaw, or alaw. The simple types are listed first and have an initial s or u for signed or unsigned data, followed by 8 or 16 as the number of bits per sample. No further extension means the data is in the natural byte order, a trailing x specifies byte swapped data, hl explicitly states the byte order as high byte followed by low byte and lh the converse. Hence s16 means signed 16 bit integers in the natural byte order (like C would fwrite() shorts). ulaw is the natural file type of ulaw encoded files (such as the default sun .au files) and alaw is a similar byte-packed scheme. Specific optimisations are applied to ulaw and alaw files. If lossless compression is specified with ulaw files then a check is made that the whole dynamic range is used (useful for files recorded on a SparcStation with the volume set too high). Lossless coding of both file types uses an internal format with a monotonic mapping to linear. If lossy compression is specified then the data is internally converted to linear. The lossy option "-r4" has been observed to give little degradation and provides 2:1 compression. With the types listed above you should explicitly set the number of channels (if not mono) with -c and if the file contains a header the size should be specified with -a. This is most important for lossy compression which will lead to data corruption if a file header is inadvertently lossy coded. Finally, as of version 2.3, the file type may be specified as wav (the default). In this case the file to be compressed is interogated for the specific data type (chosen from the above) and the number of channels to be used. The header length alignment (-a flag) is also automatic so lossless compression requires no switches to be set and lossy compression requires only that the compression level be set with -n or -r.

-u  The ulaw standard (ITU G711) has two codes which both map onto the zero value on a linear scale. The "-u" flag maps the negative zero onto the positive zero and so yields marginally better compression for format version 2 (the gain is significant for older format versions).

-v version
    Specify the binary format version number of compressed files. Legal values are currently 1, 2 and 3, with higher numbers generally giving better compression. 2 and 3 are identical, with the exception that 2 does not generate seek tables, while 3 does. Detection of format version on decode is automatic.

-x extract
    Reconstruct the original file. All other command line options except -a and -d are ignored.

METHODOLOGY
shorten works by blocking the signal, making a model of each block in order to remove temporal redundancy, then Huffman coding the quantised prediction residual.

  Blocking
The signal is read in a block of about 128 or 256 samples, and converted to integers with expected mean of zero. Sample-wise-interleaved data is converted to separate channels, which are assumed independent.

  Decorrelation
Four functions are computed, corresponding to the signal, difference signal, second and third order differences. The one with the lowest variance is coded. The variance is measured by summing absolute values for speed and to avoid overflow.

  Compression
It is assumed the signal has the Laplacian probability density function of exp(-abs(x)). There is a computationally efficient way of mapping this density to Huffman codes, The code is in four parts: a run of zeros; a bounding one; a fixed number of bits mantissa; and the sign bit. The number of leading zeros gives the offset from zero. Some examples for a 2 bit mantissa:

    Value  zeros  stopbit  mantissa  signbit  total code
    0             1        00        0        1000
    1             1        01        0        1010
    2             1        10        0        1010
    4      0      1        00        0        01000
    7      0      1        11        0        01110
    8      00     1        00        0        001000
    -1            1        00        1        1001
    -2            1        01        1        1011
    -7     0      1        10        1        01101
Note that negative numbers are offset by one as there is no need to have two zero codes. The technical report CUED/F-INFENG/TR.156 included with the shorten distribution as files tr154.tex and tr154.ps contains bugs in this format description and is superceeded by this man page.

EMBEDDED OPERATION
Shorten may be used embedded within other programs. shorten is a function call implemented in the file shorten.c. The file main.c provides a wrapper for stand alone operation. A simple example of ebedded operation can be found in the file embedded.c. Full windows DLL operation is provided in the windll subdirectory.

SEE ALSO
compress(1),pack(1).

DIAGNOSTICS

Exit status is normally 0. A warning is issued if the file is not properly aligned, i.e. a whole number of records could not be read at the end of the file.

BUGS
An easy way to test shorten for your system is to use "make check", if this fails, for whatever reason, please report it to <shnutils@freeshell.org>.

No check is made for increasing file size, but valid waveform files generally achieve some compression. Even compressing a file of random bytes (which represents the worst case waveform file) only results in a small increase in the file length (about 6% for 8 bit data and 3% for 16 bit data). There is one condition that is know to be problematic, that is the lossy compression of unsigned data without mean estimation - large file sizes may result if the mean is far from the middle range value. For these files the value of the -m switch should be non-zero, as it is by default in format version 2.

There is no provision for different channels containing different data types. Normally, this is not a restriction, but it does mean that if lossy coding is selected for the ulaw type, then all channels use lossy coding.

The technical report CUED/F-INFENG/TR.156 (included in the shorten distribution) report contains errors in the bitfield format description and is superceeded by this document.

See the file "ChangeLog" for a history of bug fixes and feature additions.

Please mail Jason Jordan at the address below if you find a bug in shorten involving seek tables.

Please mail Brian Willoughby at the address below if you find a bug in the AIFF implementation.

Please mail Tony Robinson immediately at the address below if you find a bug in shorten that is NOT related to seek tables or AIFF support. Make sure you can reproduce your bug using version 2.3a, the last version known to be released by him.

AVAILABILITY
The latest 2.x and 3.x versions can be obtained from <http://www.etree.org/shnutils/shorten/> or <http://shnutils.freeshell.org/shorten/>.

AUTHORS
Copyright (C) 1992-1999 by Tony Robinson and SoftSound Ltd (ajr@softsound.com)

Unix maintenance of 3.x versions by Jason Jordan <shnutils@freeshell.org>.

AIFF support and maintenance by Brian Willoughby <shorten@sounds.wa.com> of Sound Consulting <http://sounds.wa.com/>.

Shorten is available for non-commercial use without fee. See the LICENSE file for the formal copying and usage restrictions. For supported versions please see http://www.softsound.com/Shorten.html and for commercial use please contact shorten@softsound.com