stftpitchshift

2.0 verified Fri May 01 auth: no python

STFT-based pitch and timbre shifting library for audio processing, supporting real-time and file-based transformations. Version 2.0 includes major API changes, improved latency, and WebAssembly support. Released under the MIT license.

pip install stftpitchshift

Common errors

error ImportError: cannot import name 'stft' from 'stftpitchshift' ↓

cause The `stft` function was removed in v2.0.

fix

Use from stftpitchshift import PitchShift and call PitchShift().shiftpitch(...).

error ValueError: Audio must be a 1D numpy array of float32 ↓

cause Input audio is not mono or not float32.

fix

Ensure audio is mono (audio.mean(axis=1)) and convert to float32: audio = audio.astype(np.float32).

error AttributeError: 'PitchShift' object has no attribute 'stft' ↓

cause The `stft` method is removed; use `shiftpitch`.

fix

Replace shifter.stft(...) with shifter.shiftpitch(audio, samplerate, factor).

Warnings

breaking In v2.0, the API changed: `PitchShift.shiftpitch` replaces the old `stft` method. The timbre shifting is now a separate `TimbreShift` class. ↓

fix Update code to use `PitchShift().shiftpitch(audio, samplerate, factor)` instead of `stft(...)`.

breaking In v2.0, the `TimbreShift` class requires explicitly enabling timbre shifting via `shiftpitch` or separate `TimbreShift.shifttimbre`. The old `PitchShift` constructor parameter `timbre` no longer exists. ↓

fix Use `TimbreShift().shifttimbre(audio, samplerate, factor)` for timbre shifting.

gotcha The input audio must be monaural (single channel) and of type `numpy.float32`. Multi-channel or different dtypes may cause errors. ↓

fix Convert audio to mono and float32 before processing: `audio = audio.mean(axis=1) if audio.ndim > 1 else audio; audio = audio.astype(np.float32)`.

deprecated The previous `stft` function and the old import path `from stftpitchshift import stft` are removed in v2.0. ↓

fix Use the new `PitchShift` and `TimbreShift` classes.

Install

pip install stftpitchshift[fft]

Imports

PitchShift
```
from stftpitchshift import PitchShift
```
Main class for pitch shifting

TimbreShift

wrong

from stftpitchshift import TimbreShift (old name was PitchShift with timbre parameter)

correct

from stftpitchshift import TimbreShift

For timbre shifting separately in v2.0

load

wrong

from scipy.io import wavfile

correct

from stftpitchshift import load

Use built-in load function for audio files

save
```
from stftpitchshift import save
```
Use built-in save function for audio files

Quickstart

Load an audio file, apply pitch shifting, and save the result.

import numpy as np
from stftpitchshift import PitchShift, load, save

# Load audio (mono, float32)
audio, samplerate = load('input.wav')

# Create pitch shifter with default settings
shifter = PitchShift()

# Shift pitch by 2 semitones (factor = 2^(2/12) ≈ 1.1225)
shifted = shifter.shiftpitch(audio, samplerate, 1.1225)

# Save result
save('output.wav', samplerate, shifted.astype(np.float32))