stretch(1)

NAME
stretch - time stretching tool for sound data

SYNOPSIS
stretch [options] [input [output]]

DESCRIPTION

The stretch utility allows you to lengthen or shorten the duration of an audio data stream without affecting the pitch of the sampled data. It employs phase-vocoding to achieve the effect, usually leading to better results than time-domain techniques. Input audio data can be composed of multiple channels, in which case output also is.

Both output and input can be '-', indicating that signal data is to be read from stdin or written to stdout respectively (You can also omit the file names for the same effect, starting with output). In either case, the sample format is signed 16-bit little-endian (aka CD format).

For physical file access, the utility makes use of the sndfile library. The tool tries to guess the intended output file format from the filename extension; in addition, you can specify the output bit depth (quantization) with the -b (--bits) parameter.

The tool is not capable of directly replacing the contents of the input file.

OPTIONS

The simplest invocation of the tool is:

    stretch -t 1.5 infile.wav outfile.wav

This example stretches infile.wav to 150 % duration and writes the result to outfile.wav.

  Most useful options:

-t, --times <stretch factor>
    sets the ratio by which the duration of the sound signal is scaled. Extreme values can cause audible artefacts in the output signal, usually perceived as cyclic amplitude modulation. To achieve an exact time expansion/compression ratio, the product of this and the -o (--overlap) parameter needs to be an integer value.

-a, --amplify <factor>
    sets the linear amplification factor for the output signal. The default value is 1.0 .

-q, --quiet
    makes the utility be silent about what it does.

  Processing control options:

-f, --fft <DFT length>
    sets the length of the DFT (discrete Fourier transform), which should be a power of two for best results. Odd values may cause the utility to throw up. Larger DFT sizes imply better frequency resolution at the cost of increased computational demand. The default value is 1024 samples.

-o, --overlap <overlap>
    controls the interval at which recomposition of the signal takes place. Smaller values imply a smoother result in exchange for increased computational demand. The default value is 128 samples.

  Piped input signal options:

If signal input is from stdin, the default assumption about the data format (other than the aforementioned 16-bit signed little-endian convention) is two-channel audio at 44.1 kHz sample rate. The following options override these:

-c, --channels <channel count>
    no surprises: 1 is mono, 2 stereo etc.

-r, --rate <sample rate>
    sets the sample rate.

  Output bit depth:

-b, --bits <quantization>
    sets the output bit depth (only for physical file output). 8, 16 or 24 for signed integers, 32 or 64 for floating point. The default is 16-bit. (Internal precision is 32 bit floating-point.)

-l, --limit
    this option causes the utility to clip the output signal to stay within the output quantization or the [-1,+1] range if output is in floating-point format. The use of this flag is highly recommended when output is in integer sample format (--bits less than 32 or stdout output).

  Information options:

-h, --help
    prints version information and a list of supported file formats/extensions, then quits.

-v, --version
    prints version information, then quits.

EXAMPLES
A few example invocations of the utility, all assuming source data is in CD format (signed 16-bit samples, stereo, 44.1 kHz):

stretch -o 100 -t 1.2 cdda.wav | aplay -fcd

stretches cdda.wav to exactly 120 %, piping the output to the aplay program for immediate playback.

cat file.ogg | oggdec - | stretch -t.8 | aplay -fcd

plays back an ogg stream, accelerated to 80 % duration. If you prefer mp3, an equivalent incantation is:

madplay -o raw:- file.mp3 | stretch -t.8 | aplay -f cd

BUGS
Lousy command line parsing and error feedback. Lots of combinations of output file formats and quantization untested, as is the operation on big-endian systems. Phase vocoding chews a lot of CPU cycles.

AUTHORS
The original phase vocoder implementation was done by Mark Dolson at UCSD, part of the CARL suite, skillfully converted to streaming operation by Richard Dobson.

The stretch tool and this manual page were written by Tim Goetze <tim@quitte.de>.

HOMEPAGE
The latest version of this tool can be obtained from http://quitte.de/dsp/pvoc.html .