AudioStretchy is a Python library and CLI tool that which performs fast, high-quality time-stretching of WAV/MP3 files without changing their pitch. Works well for speech, can time-stretch silence separately. The library is a wrapper around David Bryant’s audio-stretch C library.
Version: 1.3.5
- Fast, high-quality time stretching of audio files without changing their pitch
- Adjustable stretching ratio from 0.25 to 4.0
- Cross-platform: Windows, macOS, and Linux
- Supports WAV files and file-like objects. With
[all]installation, also supports MP3 files and file-like objects - With
[all]installation, also supports resampling
Time-domain harmonic scaling (TDHS) is a method for time-scale modification of speech (or other audio signals), allowing the apparent rate of speech articulation to be changed without affecting the pitch-contour and the time-evolution of the formant structure. TDHS differs from other time-scale modification algorithms in that time-scaling operations are performed in the time domain (not the frequency domain).
The core functionality of this package is provided by David Bryant’s excellent audio-stretch C library that performs fast, high-quality TDHS on WAV in the ratio range of 0.25 (4× slower) to 4.0 (4× faster).
The library gives very good results with speech recordings, especially with modest stretching at the ratio between 0.9 (10% slower) and 1.1 (10% faster). AudioStretchy is a Python wrapper around that library. The Python package also offers some additional, optional functionality: supports MP3 (in addition to WAV), and allows you to preform resampling.
Below are links to a short audio file (as WAV and MP3), with the same file stretched at 1.2 (20% slower):
| Input | Stretched |
|---|---|
audio.wav |
audio-1.2.wav |
audio.mp3 |
audio-1.2.mp3 |
To be able to stretch and resample both WAV and MP3 files, install AudioStretchy using pip like so:
python3 -m pip install audiostretchy[all]
This installs the package and the pre-compiled audio-stretch libraries for macOS, Windows and Linux.
This also installs optional dependencies:
On macOS, you also need to install HomeBrew and then in Terminal run:
brew install ffmpegTo only be able to stretch WAV files (no resampling, no MP3 support), install AudioStretchy with minimal dependencies like so:
python3 -m pip install audiostretchy
This only installs the package and the pre-compiled audio-stretch libraries for macOS, Windows and Linux.
To install the development version, use:
python3 -m pip install git+https://github.com/twardoch/audiostretchy#egg=audiostretchy[all]
audiostretchy INPUT_WAV OUTPUT_WAV <flags>
POSITIONAL ARGUMENTS
INPUT_PATH
The path to the input WAV or MP3 audio file.
OUTPUT_PATH
The path to save the stretched WAV or MP3 audio file.
FLAGS
-r, --ratio=RATIO
The stretch ratio, where values greater than 1.0 will extend the audio and
values less than 1.0 will shorten the audio. From 0.5 to 2.0, or with `-d`
from 0.25 to 4.0. Default is 1.0 = no stretching.
-g, --gap_ratio=GAP_RATIO
The stretch ratio for gaps (silence) in the audio.
Default is 0.0 = uses ratio.
-u, --upper_freq=UPPER_FREQ
The upper frequency limit for period detection in Hz. Default is 333 Hz.
-l, --lower_freq=LOWER_FREQ
The lower frequency limit. Default is 55 Hz.
-b, --buffer_ms=BUFFER_MS
The buffer size in milliseconds for processing the audio in chunks
(useful with `-g`). Default is 25 ms.
-t, --threshold_gap_db=THRESHOLD_GAP_DB
The threshold level in dB to determine if a section of audio is considered
a gap (for `-g`). Default is -40 dB.
-d, --double_range=DOUBLE_RANGE
If set, doubles the min/max range of stretching.
-f, --fast_detection=FAST_DETECTION
If set, enables fast period detection, which may speed up processing but
reduce the quality of the stretched audio.
-n, --normal_detection=NORMAL_DETECTION
If set, forces the algorithm to use normal period detection instead
of fast period detection.
-s, --sample_rate=SAMPLE_RATE
The target sample rate for resampling the stretched audio in Hz (if installed
with `[all]`). Default is 0 = use sample rate of the input audio.
from audiostretchy.stretch import stretch_audio
stretch_audio("input.wav", "output.wav", ratio=1.1)In this example, the input.wav file will be time-stretched by a factor of 1.1, meaning it will be 10% longer, and the result will be saved in the output.wav file.
For advanced usage, you can use the AudioStretch class that lets you open and save files provided as paths or as file-like BytesIO objects:
from audiostretchy.stretch import AudioStretch
audio_stretch = AudioStretch()
# This needs [all] installation for MP3 support
audio_stretch.open(file=MP3DataAsBytesIO, format="mp3")
audio_stretch.stretch(
ratio=1.1,
gap_ratio=1.2,
upper_freq=333,
lower_freq=55,
buffer_ms=25,
threshold_gap_db=-40,
dual_force=False,
fast_detection=False,
normal_detection=False,
)
# This needs [all] installation for soxr support
audio_stretch.resample(sample_rate=44100)
audio_stretch.save(file=WAVDataAsBytesIO, format="wav")- v1.3.5: fix for MP3 writing
- v1.3.2: fix for MP3 opening
- v1.3.0: actually working on Windows as well
- v1.2.x: working on macOS and Linux
- Original C library code: Copyright (c) 2022 David Bryant
- Python code: Copyright (c) 2023 Adam Twardoch
- Python code written with assistance from GPT-4
- Licensed under the BSD-3-Clause license