https://github.com/gregogiudici/python-stretch
Simple python library for pitch shifting and time stretching. Wrapper of Signalsmith Stretch C++ Library
https://github.com/gregogiudici/python-stretch
audio augmentation nanobind python
Last synced: 6 months ago
JSON representation
Simple python library for pitch shifting and time stretching. Wrapper of Signalsmith Stretch C++ Library
- Host: GitHub
- URL: https://github.com/gregogiudici/python-stretch
- Owner: gregogiudici
- License: mit
- Created: 2024-09-19T09:20:39.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-19T11:49:20.000Z (7 months ago)
- Last Synced: 2025-03-29T12:03:00.350Z (6 months ago)
- Topics: audio, augmentation, nanobind, python
- Language: C++
- Homepage: https://pypi.org/project/python-stretch/
- Size: 17.2 MB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ***python-stretch***: pitch shifting and time stretching
[](https://github.com/gregogiudici/python-stretch/blob/main/LICENSE)
[](https://pypi.org/project/python-stretch)
[![Pip Action Status][actions-pip-badge]][actions-pip-link]
[![Pip Action Status][actions-wheels-badge]][actions-wheels-link]
[](https://pepy.tech/projects/python-stretch)
[actions-pip-link]: https://github.com/gregogiudici/python-stretch/actions?query=workflow%3APip
[actions-pip-badge]: https://github.com/gregogiudici/python-stretch/workflows/Pip/badge.svg
[actions-wheels-link]: https://github.com/gregogiudici/python-stretch/actions?query=workflow%3AWheels
[actions-wheels-badge]: https://github.com/gregogiudici/python-stretch/workflows/Wheels/badge.svg
A simple Python Wrapper of the Signalsmith Stretch C++ library for pitch and time stretching.
## Features
- **Multichannel support**: Works with mono and multichannel audio files.
- **Seamless integration**: Works natively with NumPy arrays for compatibility with libraries such as [`librosa`](https://librosa.org/doc/latest/index.html) and many others used in audio processing pipelines.
- **Backend of Audiomentations**: `python-stretch` is used as the core method for pitch shifting and time stretching in the popular [`audiomentations`](https://github.com/iver56/audiomentations) library since version [0.39.0](https://iver56.github.io/audiomentations/changelog/#:~:text=Semantic%20Versioning.-,0.39.0%20%2D%202025%2D02%2D12,-Changed).
## Installation
`python-stretch` is available in [PyPI](https://pypi.org/project/python-stretch/) (via [Platform Wheels](https://packaging.python.org/guides/distributing-packages-using-setuptools/#platform-wheels)):
```
pip install python-stretch
```
Alternatevly, you can easly build it from source (You need a c++ compiler and cmake).
```
# Clone from github
git clone --recurse-submodules https://github.com/gregogiudici/python-stretch.git
# Install
pip install ./python-stretch
```
# Examples
## Quick Start
```
import numpy as np
import librosa
import python_stretch as ps
# Load an audio example from librosa (e.g., 'trumpet', 'brahms',...)
audio, sr = librosa.load(librosa.ex('trumpet'), sr=None)
# Assure that "audio" is a 2d array
if (audio.ndim == 1):
audio = audio[np.newaxis, :]
# Create a Stretch object
stretch = ps.Signalsmith.Stretch()
# Configure using a preset
stretch.preset(audio.shape[0], sr) # numChannels, sampleRate
# Shift up by one octave
stretch.setTransposeSemitones(12)
# Stretch time
stretch.timeFactor = 0.75
# Process
audio_processed = stretch.process(audio)
# Save and listen
import soundfile as sf
sf.write("audio_original.wav", np.squeeze(audio), sr)
sf.write("audio_processed.wav", np.squeeze(audio_processed), sr)
```
# Acknowledgements
- [Signalsmith Stretch](https://github.com/Signalsmith-Audio/signalsmith-stretch): `python-stretch` is built on top of the Signalsmith Stretch C++ library, which provides the core algorithms for time stretching and pitch shifting.
- [nanobind](https://github.com/wjakob/nanobind): This project utilizes `nanobind` for easily binding the C++ code to Python.