Registry / ai-ml / python-stretch

python-stretch

library0.3.1pypypi✓ verified 87d ago

Python Stretch is a simple library for pitch shifting and time stretching audio, currently at version 0.3.1. It acts as a wrapper for the Signalsmith Stretch C++ Library, providing high-quality audio manipulation capabilities. The library supports both mono and multichannel audio and integrates seamlessly with NumPy arrays, making it compatible with other audio processing libraries like librosa. It is also utilized as the core method for pitch and time stretching in the popular audiomentations library. The project shows active maintenance with recent PyPI uploads for version 0.3.1 in early 2025.

ai-ml data serialization

pip install python-stretch

github ↗package ↗

INSTALL

IMPORT

SIG · PYTHON-STRETCH

python-stretch

ai-mlpythonv0.3.1

Install

1.6s avg

Import

—

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.3.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 19.3MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.6s · import 0.000s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Signalsmith

✓ import python_stretch as ps stretch_obj = ps.Signalsmith.Stretch()

The main class `Stretch` is nested within `ps.Signalsmith` after importing `python_stretch` as `ps`.

This quickstart demonstrates how to load an audio file using `librosa`, initialize the `Signalsmith.Stretch` object, configure pitch shifting and time stretching parameters, and process the audio. It assumes `librosa` and `soundfile` are installed for loading/saving audio.

import numpy as np import librosa import soundfile as sf import python_stretch as ps # Load an audio example (e.g., from librosa) audio, sr = librosa.load(librosa.ex('trumpet'), sr=None) # Assure that 'audio' is a 2D array (channels, samples) if audio.ndim == 1: audio = audio[np.newaxis, :] # Create a Stretch object stretch = ps.Signalsmith.Stretch() # Configure using a preset (numChannels, sampleRate) stretch.preset(audio.shape[0], sr) # Shift pitch up by one octave (12 semitones) stretch.setTransposeSemitones(12) # Stretch time by a factor (e.g., 0.75 for faster playback) stretch.timeFactor = 0.75 # Process audio audio_processed = stretch.process(audio) # Save and listen (requires soundfile) # sf.write("audio_original.wav", np.squeeze(audio), sr) # sf.write("audio_processed.wav", np.squeeze(audio_processed), sr) print(f"Original audio shape: {audio.shape}, sample rate: {sr}") print(f"Processed audio shape: {audio_processed.shape}")

Debug

Known issues

gotchaBuilding `python-stretch` from source requires a C++ compiler and CMake. While pre-built wheels are available for most common platforms and Python versions, users needing to build from source on less common environments might face compilation challenges.

fix

Prefer `pip install python-stretch` to use pre-built wheels. If building from source is necessary, ensure a C++ compiler (like g++ or clang) and CMake are installed and correctly configured.

affects: All versions

gotchaThe library primarily operates on NumPy arrays. Input audio should be provided as a 2D NumPy array with shape (channels, samples). Passing raw Python lists or incorrectly shaped arrays will lead to errors.

fix

Always convert input audio to a NumPy array, and ensure it has the shape (channels, samples), even for mono audio (e.g., `audio[np.newaxis, :]` for a 1D array).

affects: All versions

gotchaThe quickstart example and common usage patterns rely on `librosa` for audio loading and `soundfile` for saving. These are not strict dependencies of `python-stretch` itself, but are essential for a complete audio processing workflow.

fix

Install `librosa` and `soundfile` separately if you intend to use the quickstart examples or perform typical audio I/O: `pip install librosa soundfile`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'stretch'

The Python package is installed as `python-stretch` but the module to import is named `stretch`.

fix

Use `import stretch` instead of `import python_stretch` or `import python-stretch`.

ImportError: cannot open shared object file: _stretch.cpython-310-x86_64-linux-gnu.so: No such file or directory

The C++ backend shared library required by `python-stretch` could not be found or loaded at runtime, often due to an incomplete installation or missing build dependencies.

fix

Ensure `python-stretch` is correctly installed by reinstalling with `pip install --no-cache-dir python-stretch`. On Linux, ensure `python3-dev` (or equivalent) is installed; on Windows, ensure Visual C++ Build Tools are available.

TypeError: an integer is required (got type float)

The `stretch.SignalsmithStretch` constructor expects integer values for its `channels` and `samplerate` arguments, but float values were provided.

fix

Ensure that `channels` and `samplerate` are cast to integers before being passed to the `SignalsmithStretch` constructor, e.g., `stretch.SignalsmithStretch(int(channels), int(samplerate))`.

Upgrade

Version history

0.3.1latest on PyPI · released Feb 14, 2025

Audit

Dependencies

numpyrequiredCore dependency for array manipulation.

librosaoptionalCommonly used for loading audio in examples and audio processing workflows.

soundfileoptionalUsed for saving processed audio in examples.

cmakeoptionalRequired for building from source, as it's a C++ wrapper.

nanobindoptionalUsed internally for C++ to Python binding, typically a build dependency.

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/gregogiudici/python-stretch ↗

packagehttps://pypi.org/project/python-stretch/ ↗