{"id":6211,"library":"python-stretch","title":"Python Stretch","description":"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.","status":"active","version":"0.3.1","language":"en","source_language":"en","source_url":"https://github.com/gregogiudici/python-stretch","tags":["audio","pitch-shifting","time-stretching","signalsmith","numpy"],"install":[{"cmd":"pip install python-stretch","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"Core dependency for array manipulation.","package":"numpy","optional":false},{"reason":"Commonly used for loading audio in examples and audio processing workflows.","package":"librosa","optional":true},{"reason":"Used for saving processed audio in examples.","package":"soundfile","optional":true},{"reason":"Required for building from source, as it's a C++ wrapper.","package":"cmake","optional":true},{"reason":"Used internally for C++ to Python binding, typically a build dependency.","package":"nanobind","optional":true}],"imports":[{"note":"The main class `Stretch` is nested within `ps.Signalsmith` after importing `python_stretch` as `ps`.","symbol":"Signalsmith","correct":"import python_stretch as ps\nstretch_obj = ps.Signalsmith.Stretch()"}],"quickstart":{"code":"import numpy as np\nimport librosa\nimport soundfile as sf\nimport python_stretch as ps\n\n# Load an audio example (e.g., from librosa)\naudio, sr = librosa.load(librosa.ex('trumpet'), sr=None)\n\n# Assure that 'audio' is a 2D array (channels, samples)\nif audio.ndim == 1:\n    audio = audio[np.newaxis, :]\n\n# Create a Stretch object\nstretch = ps.Signalsmith.Stretch()\n\n# Configure using a preset (numChannels, sampleRate)\nstretch.preset(audio.shape[0], sr)\n\n# Shift pitch up by one octave (12 semitones)\nstretch.setTransposeSemitones(12)\n\n# Stretch time by a factor (e.g., 0.75 for faster playback)\nstretch.timeFactor = 0.75\n\n# Process audio\naudio_processed = stretch.process(audio)\n\n# Save and listen (requires soundfile)\n# sf.write(\"audio_original.wav\", np.squeeze(audio), sr)\n# sf.write(\"audio_processed.wav\", np.squeeze(audio_processed), sr)\nprint(f\"Original audio shape: {audio.shape}, sample rate: {sr}\")\nprint(f\"Processed audio shape: {audio_processed.shape}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"Building `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.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install `librosa` and `soundfile` separately if you intend to use the quickstart examples or perform typical audio I/O: `pip install librosa soundfile`.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}