stretch(1)

📦 version 0.1.12, in arch rolling

✨ stretch(1) — Sound Data Time Stretching ✨

ok so bestie, welcome to the stretch manual page 💖 (that's section 1 of the manual, the "Sound Data Time Stretching" one, iykyk). grab a snack, we're gonna talk about making audio longer and shorter without the pitch going all weird 🎀

🌸 NAME 🌸

stretch — literally the time stretching tool for sound data. that's the whole vibe 💅

🦋 SYNOPSIS 🦋

stretch [options] [input [output]]

⭐ DESCRIPTION ⭐

okay so here's the tea ☕ — the stretch utility lets you lengthen or shorten the duration of an audio data stream without affecting the pitch of the sampled data. iconic behaviour honestly 👑

how does it do it? it employs phase-vocoding to achieve the effect, which usually leads to better results than time-domain techniques. no cap, that's the good stuff ✨

your input audio data can be made of multiple channels, and in that case the output is multichannel too. we match, we serve 🫶

now, both output and input can be '-', which means the signal data gets read from stdin or written to stdout respectively. (you can also just 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, the classic 💿

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 🕵️‍♀️ and on top of that, you can specify the output bit depth (quantization) with the -b (--bits) parameter.

⚠️ heads up bestie: the tool is not capable of directly replacing the contents of the input file. so don't even try to overwrite your source, it's not gonna happen 🙈

💜 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. cute, right? 🎀

🌈 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 😭 (yes that's the wobbly robot voice thing). to achieve an exact time expansion/compression ratio, the product of this and the -o (--overlap) parameter needs to be an integer value. math is math, periodt 🧮
  • -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. it's giving "no thoughts, head empty" 🤫

🧚 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 💀 (not even kidding, that's the actual wording). 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. simple as that bestie 💫
  • -r, --rate <sample rate> — sets the sample rate. yes, that's it. that's the whole thing 🎶

💅 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, fyi 👀)
  • -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). seriously bestie, use it. it's giving self-care 🫶

🔥 Information options:

  • -h, --help — prints version information and a list of supported file formats/extensions, then quits. the "who am i and what can i do" moment 🌟
  • -v, --version — prints version information, then quits. short and sweet 💌

🎀 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. instant gratification, we love to see it 🔥

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

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

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

(i know, -f cd with a space vs -fcd without — that's literally how it's written in here, so i'm keeping it exactly as-is, don't come for me 🙈)

💀 BUGS 💀

ok so the honest section, and it's giving struggle:

  • 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. it's a hungry girl, she eats your processor for breakfast 🍳

👑 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>. respect the icons 🫶

🌐 HOMEPAGE 🌐

the latest version of this tool can be obtained from http://quitte.de/dsp/pvoc.html 💖 go get it bestie, it's right there

<div align="center">🌸</div>

and that's the whole page!! 💜 this version landed on March 25, 2004 (vintage, honestly — she's an elder millennial tool but the vibes are immaculate), and it's dated as such at the bottom of the original. mwah, go stretch some audio 🎀✨💅

📦 where this page comes from