audiosig 0.1.0__py3-none-any.whl

audiosig/__init__.py

@@ -0,0 +1,78 @@
+"""Portable, dependency-light audio signal processing for NumPy arrays."""
+
+from __future__ import annotations
+
+try:
+    from ._version import __version__  # type: ignore[import-not-found]
+except ImportError:  # pragma: no cover - only used in an unbuilt source checkout
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+
+        __version__ = version("audiosig")
+    except PackageNotFoundError:
+        __version__ = "0.1.dev0"
+
+from ._resampling import resample, resample_speed, resample_to_length
+from .amplitude import apply_gain_db, peak_normalize
+from .effects import pitch_shift, time_stretch
+from .exceptions import AudioShapeError, AudioSignalError, InvalidParameterError
+from .silence import (
+    abs2,
+    activity_to_intervals,
+    amplitude_to_db,
+    energy_based_vad,
+    find_speech_bounds,
+    find_speech_start,
+    frame_rms,
+    frame_signal,
+    frames_to_samples,
+    median_filter_numpy,
+    minmax_normalize,
+    non_silent_frames,
+    normalized_energy_vad,
+    power_to_db,
+    relative_db_vad,
+    rms,
+    short_time_energy,
+    spectral_flux,
+    split,
+    trim,
+    zero_crossing_rate,
+)
+from .speech import apply_speech_effects
+
+__all__ = [
+    "AudioShapeError",
+    "AudioSignalError",
+    "InvalidParameterError",
+    "__version__",
+    "abs2",
+    "activity_to_intervals",
+    "amplitude_to_db",
+    "apply_gain_db",
+    "apply_speech_effects",
+    "energy_based_vad",
+    "find_speech_bounds",
+    "find_speech_start",
+    "frame_rms",
+    "frame_signal",
+    "frames_to_samples",
+    "median_filter_numpy",
+    "minmax_normalize",
+    "non_silent_frames",
+    "normalized_energy_vad",
+    "peak_normalize",
+    "pitch_shift",
+    "power_to_db",
+    "relative_db_vad",
+    "resample",
+    "resample_speed",
+    "resample_to_length",
+    "rms",
+    "short_time_energy",
+    "spectral_flux",
+    "split",
+    "time_stretch",
+    "trim",
+    "zero_crossing_rate",
+]

audiosig/_framing.py

@@ -0,0 +1,35 @@
+"""NumPy stride-based signal framing."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ._validation import validate_audio, validate_integer
+
+
+def frame(
+    audio: np.ndarray,
+    *,
+    frame_length: int,
+    hop_length: int,
+    axis: int = -1,
+) -> np.ndarray:
+    """Return a read-only view shaped ``(..., frames, frame_length)``.
+
+    The sample axis is moved to the end before framing. Overlapping frames are
+    intentionally read-only so callers cannot accidentally corrupt the source
+    array through a strided view.
+    """
+    source, normalized_axis = validate_audio(audio, axis=axis)
+    length = validate_integer(frame_length, "frame_length")
+    hop = validate_integer(hop_length, "hop_length")
+    moved = np.moveaxis(source, normalized_axis, -1)
+    sample_count = moved.shape[-1]
+    frame_count = 1 + (sample_count - length) // hop if sample_count >= length else 0
+    shape = (*moved.shape[:-1], frame_count, length)
+    if frame_count == 0:
+        return np.empty(shape, dtype=source.dtype)
+    strides = (*moved.strides[:-1], hop * moved.strides[-1], moved.strides[-1])
+    result = np.lib.stride_tricks.as_strided(moved, shape=shape, strides=strides)
+    result.setflags(write=False)
+    return result

audiosig/_resampling.py

@@ -0,0 +1,132 @@
+"""Chunked windowed-sinc resampling implemented with NumPy only."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ._validation import (
+    validate_audio,
+    validate_choices,
+    validate_filter,
+    validate_integer,
+    validate_positive,
+)
+from .exceptions import AudioShapeError, InvalidParameterError
+
+
+def resample(
+    audio: np.ndarray,
+    *,
+    source_rate: float,
+    target_rate: float,
+    axis: int = -1,
+    filter_width: int = 32,
+    rolloff: float = 0.945,
+    length_mode: str = "round",
+) -> np.ndarray:
+    """Resample audio with a finite, anti-aliased windowed-sinc kernel.
+
+    ``length_mode='round'`` preserves AudioSig's historical sizing; ``ceil``
+    provides librosa-compatible output length semantics.
+    """
+    source, normalized_axis = validate_audio(audio, axis=axis, allow_empty=True)
+    source_hz = validate_positive(source_rate, "source_rate")
+    target_hz = validate_positive(target_rate, "target_rate")
+    width, cutoff = validate_filter(filter_width, rolloff)
+    mode = validate_choices(length_mode, ("round", "ceil"), "length_mode")
+    input_length = source.shape[normalized_axis]
+    if input_length == 0:
+        return np.array(source, dtype=source.dtype, copy=True)
+    requested_length = input_length * target_hz / source_hz
+    if not np.isfinite(requested_length) or requested_length > np.iinfo(np.intp).max:
+        raise InvalidParameterError("requested resampled length is too large")
+    output_length = max(
+        1, round(requested_length) if mode == "round" else int(np.ceil(requested_length))
+    )
+    if source_hz == target_hz and output_length == input_length:
+        return np.array(source, dtype=source.dtype, copy=True)
+    moved = np.moveaxis(source, normalized_axis, -1)
+    flat = moved.reshape((-1, input_length))
+    ratio = target_hz / source_hz
+    effective_cutoff = cutoff * min(1.0, ratio)
+    offsets = np.arange(-width, width + 1, dtype=np.int64)
+    window = np.kaiser(offsets.size, beta=14.0)[None, :]
+    output = np.empty((moved.size // input_length, output_length), dtype=source.dtype)
+    chunk_size = 1024
+    for start in range(0, output_length, chunk_size):
+        stop = min(output_length, start + chunk_size)
+        positions = np.arange(start, stop, dtype=np.float64) / ratio
+        centers = np.floor(positions).astype(np.int64)
+        indices = centers[:, None] + offsets[None, :]
+        clipped = np.clip(indices, 0, input_length - 1)
+        distance = indices.astype(np.float64) - positions[:, None]
+        weights = np.sinc(distance * effective_cutoff) * effective_cutoff * window
+        weights /= np.maximum(np.sum(weights, axis=1, keepdims=True), np.finfo(np.float64).eps)
+        samples = flat[:, clipped]
+        output[:, start:stop] = np.sum(samples * weights[None, :, :], axis=-1, dtype=np.float64)
+    reshaped = output.reshape((*moved.shape[:-1], output_length))
+    return np.moveaxis(reshaped, -1, normalized_axis).astype(source.dtype, copy=False)
+
+
+def resample_to_length(
+    audio: np.ndarray,
+    length: int,
+    *,
+    axis: int = -1,
+    filter_width: int = 32,
+    rolloff: float = 0.945,
+) -> np.ndarray:
+    """Resample audio to exactly ``length`` samples along ``axis``."""
+    source, normalized_axis = validate_audio(audio, axis=axis, allow_empty=True)
+    target_length = validate_integer(length, "length", minimum=0)
+    validate_filter(filter_width, rolloff)
+    input_length = source.shape[normalized_axis]
+    if target_length == input_length:
+        return np.array(source, dtype=source.dtype, copy=True)
+    if target_length == 0:
+        shape = list(source.shape)
+        shape[normalized_axis] = 0
+        return np.empty(shape, dtype=source.dtype)
+    if input_length == 0:
+        raise AudioShapeError("empty audio cannot be resampled to a non-zero length")
+    return resample(
+        source,
+        source_rate=float(input_length),
+        target_rate=float(target_length),
+        axis=normalized_axis,
+        filter_width=filter_width,
+        rolloff=rolloff,
+    )
+
+
+def resample_speed(
+    audio: np.ndarray,
+    speed: float,
+    *,
+    axis: int = -1,
+    filter_width: int = 32,
+    rolloff: float = 0.945,
+) -> np.ndarray:
+    """Change playback speed by resampling, including its pitch.
+
+    ``speed > 1`` makes audio faster, shorter, and higher pitched. ``speed < 1``
+    makes audio slower, longer, and lower pitched. Use :func:`time_stretch`
+    when pitch should remain approximately unchanged.
+    """
+    source, normalized_axis = validate_audio(audio, axis=axis, allow_empty=True)
+    multiplier = validate_positive(speed, "speed")
+    validate_filter(filter_width, rolloff)
+    input_length = source.shape[normalized_axis]
+    if input_length == 0:
+        return np.array(source, dtype=source.dtype, copy=True)
+    requested = input_length / multiplier
+    if not np.isfinite(requested) or requested > np.iinfo(np.intp).max:
+        raise InvalidParameterError("requested playback-speed length is too large")
+    target_length = max(1, round(requested))
+    return resample_to_length(
+        source,
+        target_length,
+        axis=normalized_axis,
+        filter_width=filter_width,
+        rolloff=rolloff,
+    )

audiosig/_spectral.py

@@ -0,0 +1,139 @@
+"""Small NumPy-only STFT and phase-vocoder primitives."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ._framing import frame
+from ._validation import validate_audio, validate_integer, validate_positive
+from .exceptions import AudioShapeError, InvalidParameterError
+
+_DEFAULT_DTYPE = np.dtype(np.float64)
+
+
+def _fft_settings(n_fft: int, hop_length: int) -> tuple[int, int]:
+    fft_size = validate_integer(n_fft, "n_fft", minimum=2)
+    hop = validate_integer(hop_length, "hop_length")
+    if hop > fft_size:
+        raise InvalidParameterError("hop_length must not exceed n_fft")
+    return fft_size, hop
+
+
+def _pad_for_stft(audio: np.ndarray, n_fft: int, hop_length: int, *, center: bool) -> np.ndarray:
+    """Pad short arrays safely and add centered analysis padding."""
+    source = audio
+    if center:
+        padding = n_fft // 2
+        mode = "reflect" if source.shape[-1] > 1 else "constant"
+        source = np.pad(  # type: ignore[call-overload]
+            source, [(0, 0)] * (source.ndim - 1) + [(padding, padding)], mode=mode
+        )
+    if source.shape[-1] < n_fft:
+        source = np.pad(source, [(0, 0)] * (source.ndim - 1) + [(0, n_fft - source.shape[-1])])
+    remainder = (source.shape[-1] - n_fft) % hop_length
+    if remainder:
+        source = np.pad(source, [(0, 0)] * (source.ndim - 1) + [(0, hop_length - remainder)])
+    return source
+
+
+def stft(
+    audio: np.ndarray,
+    *,
+    n_fft: int,
+    hop_length: int,
+    center: bool = True,
+) -> np.ndarray:
+    """Compute a centered Hann-windowed real-input STFT.
+
+    The returned shape is ``(..., frequency_bins, frames)``.
+    """
+    source, axis = validate_audio(audio)
+    if axis != source.ndim - 1:
+        source = np.moveaxis(source, axis, -1)
+    fft_size, hop = _fft_settings(n_fft, hop_length)
+    padded = _pad_for_stft(source, fft_size, hop, center=center)
+    frames = frame(padded, frame_length=fft_size, hop_length=hop)
+    window = np.hanning(fft_size).astype(source.dtype, copy=False)
+    spectrum = np.fft.rfft(frames * window, n=fft_size, axis=-1)
+    return np.moveaxis(spectrum, -1, -2)
+
+
+def istft(
+    spectrum: np.ndarray,
+    *,
+    n_fft: int,
+    hop_length: int,
+    length: int | None = None,
+    center: bool = True,
+    dtype: np.dtype = _DEFAULT_DTYPE,
+) -> np.ndarray:
+    """Invert a spectrum with overlap-add and squared-window normalization."""
+    fft_size, hop = _fft_settings(n_fft, hop_length)
+    if not isinstance(spectrum, np.ndarray) or spectrum.ndim < 2:
+        raise AudioShapeError("spectrum must be an array shaped (..., frequencies, frames)")
+    expected_bins = fft_size // 2 + 1
+    if spectrum.shape[-2] != expected_bins or spectrum.shape[-1] == 0:
+        raise AudioShapeError("spectrum has incompatible frequency or frame dimensions")
+    target_length = validate_integer(length, "length") if length is not None else None
+    frames = np.fft.irfft(np.moveaxis(spectrum, -2, -1), n=fft_size, axis=-1)
+    window = np.hanning(fft_size).astype(dtype, copy=False)
+    frame_count = frames.shape[-2]
+    base_length = (frame_count - 1) * hop + fft_size
+    output = np.zeros((*frames.shape[:-2], base_length), dtype=dtype)
+    envelope = np.zeros(base_length, dtype=dtype)
+    windowed = frames * window
+    for index in range(frame_count):
+        start = index * hop
+        output[..., start : start + fft_size] += windowed[..., index, :]
+        envelope[start : start + fft_size] += window * window
+    safe_envelope = np.where(envelope > np.finfo(dtype).eps, envelope, 1.0)
+    output /= safe_envelope
+    if center:
+        padding = fft_size // 2
+        if output.shape[-1] > 2 * padding:
+            output = output[..., padding:-padding]
+        else:
+            output = output[..., 0:0]
+    if target_length is not None:
+        if output.shape[-1] < target_length:
+            output = np.pad(
+                output,
+                [(0, 0)] * (output.ndim - 1) + [(0, target_length - output.shape[-1])],
+            )
+        output = output[..., :target_length]
+    return output.astype(dtype, copy=False)
+
+
+def phase_vocoder(
+    spectrum: np.ndarray,
+    *,
+    rate: float,
+    hop_length: int,
+    n_fft: int,
+) -> np.ndarray:
+    """Time-scale an STFT by interpolating magnitudes and accumulating phase."""
+    stretch = validate_positive(rate, "rate")
+    fft_size, hop = _fft_settings(n_fft, hop_length)
+    if not isinstance(spectrum, np.ndarray) or spectrum.ndim < 2:
+        raise AudioShapeError("spectrum must be an array shaped (..., frequencies, frames)")
+    expected_bins = fft_size // 2 + 1
+    if spectrum.shape[-2] != expected_bins or spectrum.shape[-1] == 0:
+        raise AudioShapeError("spectrum has incompatible frequency or frame dimensions")
+    frame_count = spectrum.shape[-1]
+    time_steps = np.arange(0, frame_count, stretch, dtype=np.float64)
+    output = np.empty((*spectrum.shape[:-1], time_steps.size), dtype=spectrum.dtype)
+    phase_advance = 2.0 * np.pi * hop * np.arange(expected_bins, dtype=np.float64) / fft_size
+    phase = np.angle(spectrum[..., 0])
+    for output_index, time in enumerate(time_steps):
+        left = min(int(np.floor(time)), frame_count - 1)
+        right = min(left + 1, frame_count - 1)
+        fraction = time - left
+        left_spectrum = spectrum[..., left]
+        right_spectrum = spectrum[..., right]
+        magnitude = (1.0 - fraction) * np.abs(left_spectrum) + fraction * np.abs(right_spectrum)
+        output[..., output_index] = magnitude * np.exp(1j * phase)
+        if right != left:
+            delta = np.angle(right_spectrum) - np.angle(left_spectrum) - phase_advance
+            delta = (delta + np.pi) % (2.0 * np.pi) - np.pi
+            phase += phase_advance + delta
+    return output

audiosig/_validation.py

@@ -0,0 +1,107 @@
+"""Shared validation helpers for public AudioSig operations."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+import numpy as np
+
+from .exceptions import AudioShapeError, InvalidParameterError
+
+FLOAT_DTYPES = (np.dtype(np.float32), np.dtype(np.float64))
+
+
+def validate_audio(
+    audio: np.ndarray,
+    *,
+    axis: int = -1,
+    allow_empty: bool = False,
+) -> tuple[np.ndarray, int]:
+    """Validate an audio array and return it with a normalized axis."""
+    if not isinstance(audio, np.ndarray):
+        raise AudioShapeError("audio must be a NumPy array")
+    if audio.ndim == 0:
+        raise AudioShapeError("audio must have at least one dimension")
+    if audio.dtype not in FLOAT_DTYPES:
+        raise AudioShapeError("audio must have dtype float32 or float64")
+    normalized_axis = validate_axis(axis, audio.ndim)
+    if audio.shape[normalized_axis] == 0 and not allow_empty:
+        raise AudioShapeError("the sample axis cannot be empty")
+    if not np.all(np.isfinite(audio)):
+        raise AudioShapeError("audio must contain only finite values")
+    return audio, normalized_axis
+
+
+def validate_positive(value: float, name: str) -> float:
+    """Return a finite positive parameter."""
+    if isinstance(value, (bool, np.bool_)):
+        raise InvalidParameterError(f"{name} must be finite and positive")
+    result = float(value)
+    if not np.isfinite(result) or result <= 0:
+        raise InvalidParameterError(f"{name} must be finite and positive")
+    return result
+
+
+def validate_finite(value: float, name: str) -> float:
+    """Return a finite scalar, rejecting booleans."""
+    if isinstance(value, (bool, np.bool_)):
+        raise InvalidParameterError(f"{name} must be finite")
+    result = float(value)
+    if not np.isfinite(result):
+        raise InvalidParameterError(f"{name} must be finite")
+    return result
+
+
+def validate_boolean(value: bool, name: str) -> bool:
+    """Return a validated boolean scalar."""
+    if not isinstance(value, (bool, np.bool_)):
+        raise InvalidParameterError(f"{name} must be a boolean")
+    return bool(value)
+
+
+def validate_gain_db(value: float, name: str = "db") -> float:
+    """Validate gain, allowing negative infinity as mute."""
+    if isinstance(value, (bool, np.bool_)):
+        raise InvalidParameterError(f"{name} must be finite or negative infinity")
+    result = float(value)
+    if np.isnan(result) or result == np.inf:
+        raise InvalidParameterError(f"{name} must be finite or negative infinity")
+    return result
+
+
+def validate_integer(value: int, name: str, *, minimum: int = 1) -> int:
+    """Validate an integer-valued parameter without accepting booleans."""
+    if isinstance(value, bool) or not isinstance(value, (int, np.integer)):
+        raise InvalidParameterError(f"{name} must be an integer")
+    result = int(value)
+    if result < minimum:
+        raise InvalidParameterError(f"{name} must be at least {minimum}")
+    return result
+
+
+def validate_axis(axis: int, ndim: int) -> int:
+    """Normalize an axis or raise an AudioShapeError."""
+    if not isinstance(axis, (int, np.integer)):
+        raise AudioShapeError("axis must be an integer")
+    normalized = int(axis)
+    if normalized < 0:
+        normalized += ndim
+    if not 0 <= normalized < ndim:
+        raise AudioShapeError(f"axis {axis} is invalid for {ndim}-D audio")
+    return normalized
+
+
+def validate_filter(filter_width: int, rolloff: float) -> tuple[int, float]:
+    """Validate resampling kernel settings."""
+    width = validate_integer(filter_width, "filter_width", minimum=1)
+    cutoff = float(rolloff)
+    if not np.isfinite(cutoff) or not 0 < cutoff <= 1:
+        raise InvalidParameterError("rolloff must be finite and in the interval (0, 1]")
+    return width, cutoff
+
+
+def validate_choices(value: str, choices: Iterable[str], name: str) -> str:
+    """Validate a string enum."""
+    if value not in choices:
+        raise InvalidParameterError(f"{name} must be one of {tuple(choices)!r}")
+    return value

audiosig/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = 'g86082542a'

audiosig/amplitude.py

@@ -0,0 +1,55 @@
+"""Simple amplitude-domain transformations."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ._validation import validate_audio, validate_boolean, validate_gain_db
+from .exceptions import InvalidParameterError
+
+
+def apply_gain_db(audio: np.ndarray, db: float, *, clip: bool = False) -> np.ndarray:
+    """Apply a decibel gain without modifying ``audio``."""
+    source, _ = validate_audio(audio, allow_empty=True)
+    gain_db = validate_gain_db(db)
+    clip_value = validate_boolean(clip, "clip")
+    if gain_db == -np.inf:
+        result = np.zeros_like(source)
+    else:
+        exponent = gain_db / 20.0
+        max_exponent = np.log10(np.finfo(np.float64).max)
+        if exponent > max_exponent:
+            raise InvalidParameterError("db produces an unrepresentable gain")
+        multiplier = 10.0**exponent
+        if source.size:
+            maximum = float(np.max(np.abs(source)))
+            dtype_limit = float(np.finfo(source.dtype).max)
+            if maximum and multiplier > dtype_limit / maximum:
+                raise InvalidParameterError("db produces a non-finite output")
+        result = np.multiply(source, multiplier, dtype=source.dtype)
+    if clip_value:
+        result = np.clip(result, -1.0, 1.0).astype(source.dtype, copy=False)
+    return np.array(result, dtype=source.dtype, copy=True)
+
+
+def peak_normalize(audio: np.ndarray, *, peak: float = 1.0, eps: float = 1e-12) -> np.ndarray:
+    """Scale audio so its absolute peak equals ``peak`` when audible."""
+    source, _ = validate_audio(audio, allow_empty=True)
+    target = float(peak)
+    tolerance = float(eps)
+    if not np.isfinite(target) or target <= 0:
+        raise InvalidParameterError("peak must be finite and positive")
+    dtype_limit = float(np.finfo(source.dtype).max)
+    if target > dtype_limit:
+        raise InvalidParameterError(f"peak exceeds the finite range of {source.dtype}")
+    if not np.isfinite(tolerance) or tolerance < 0:
+        raise InvalidParameterError("eps must be finite and non-negative")
+    if source.size == 0:
+        return np.array(source, dtype=source.dtype, copy=True)
+    maximum = float(np.max(np.abs(source)))
+    if maximum <= tolerance:
+        return np.array(source, dtype=source.dtype, copy=True)
+    result = np.asarray(source * (target / maximum), dtype=source.dtype)
+    if not np.isfinite(result).all():
+        raise InvalidParameterError("peak produces a non-finite output")
+    return np.array(result, dtype=source.dtype, copy=True)

audiosig/effects.py

@@ -0,0 +1,113 @@
+"""Speech-oriented time and pitch effects."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ._resampling import resample_to_length
+from ._spectral import istft, phase_vocoder, stft
+from ._validation import (
+    validate_audio,
+    validate_filter,
+    validate_finite,
+    validate_integer,
+    validate_positive,
+)
+from .exceptions import InvalidParameterError
+
+
+def time_stretch(
+    audio: np.ndarray,
+    rate: float,
+    *,
+    axis: int = -1,
+    n_fft: int = 2048,
+    hop_length: int | None = None,
+) -> np.ndarray:
+    """Change duration while approximately preserving pitch.
+
+    Rates above one are faster and shorter; rates below one are slower and
+    longer. This phase-vocoder implementation is intended for speech and
+    moderate prosody changes.
+    """
+    source, normalized_axis = validate_audio(audio, axis=axis, allow_empty=True)
+    stretch = validate_positive(rate, "rate")
+    fft_size = validate_integer(n_fft, "n_fft", minimum=2)
+    hop = validate_integer(hop_length if hop_length is not None else fft_size // 4, "hop_length")
+    if hop > fft_size:
+        raise InvalidParameterError("hop_length must not exceed n_fft")
+    input_length = source.shape[normalized_axis]
+    if input_length == 0:
+        return np.array(source, dtype=source.dtype, copy=True)
+    requested_length = input_length / stretch
+    if not np.isfinite(requested_length) or requested_length > np.iinfo(np.intp).max:
+        raise InvalidParameterError("requested stretched length is too large")
+    target_length = max(1, round(requested_length))
+    if stretch == 1.0:
+        return np.array(source, dtype=source.dtype, copy=True)
+    moved = np.moveaxis(source, normalized_axis, -1)
+    padded_length = max(input_length, fft_size)
+    if padded_length != input_length:
+        moved = np.pad(moved, [(0, 0)] * (moved.ndim - 1) + [(0, padded_length - input_length)])
+    spectrum = stft(moved, n_fft=fft_size, hop_length=hop, center=True)
+    transformed = phase_vocoder(spectrum, rate=stretch, hop_length=hop, n_fft=fft_size)
+    result = istft(
+        transformed,
+        n_fft=fft_size,
+        hop_length=hop,
+        length=target_length,
+        center=True,
+        dtype=source.dtype,
+    )
+    return np.moveaxis(result, -1, normalized_axis).astype(source.dtype, copy=False)
+
+
+def pitch_shift(
+    audio: np.ndarray,
+    *,
+    sample_rate: int,
+    semitones: float,
+    bins_per_octave: int = 12,
+    axis: int = -1,
+    n_fft: int = 2048,
+    hop_length: int | None = None,
+    filter_width: int = 32,
+) -> np.ndarray:
+    """Shift pitch by semitones while retaining the exact input duration."""
+    source, normalized_axis = validate_audio(audio, axis=axis, allow_empty=True)
+    validate_positive(sample_rate, "sample_rate")
+    bins = validate_integer(bins_per_octave, "bins_per_octave")
+    shift = validate_finite(semitones, "semitones")
+    fft_size = validate_integer(n_fft, "n_fft", minimum=2)
+    hop = validate_integer(hop_length if hop_length is not None else fft_size // 4, "hop_length")
+    if hop > fft_size:
+        raise InvalidParameterError("hop_length must not exceed n_fft")
+    validate_filter(filter_width, 0.945)
+    if source.shape[normalized_axis] == 0:
+        return np.array(source, dtype=source.dtype, copy=True)
+    if shift == 0.0:
+        return np.array(source, dtype=source.dtype, copy=True)
+    octaves = shift / bins
+    max_octaves = np.log2(np.finfo(np.float64).max)
+    min_octaves = np.log2(np.nextafter(0.0, 1.0))
+    if not min_octaves <= octaves <= max_octaves:
+        raise InvalidParameterError("semitones produces an unrepresentable pitch ratio")
+    ratio = float(np.exp2(octaves))
+    if not np.isfinite(ratio) or ratio <= 0.0:
+        raise InvalidParameterError("semitones produces an invalid pitch ratio")
+    rate = 1.0 / ratio
+    if not np.isfinite(rate) or rate <= 0.0:
+        raise InvalidParameterError("semitones produces an invalid pitch rate")
+    stretched = time_stretch(
+        source,
+        rate=rate,
+        axis=normalized_axis,
+        n_fft=n_fft,
+        hop_length=hop_length,
+    )
+    return resample_to_length(
+        stretched,
+        source.shape[normalized_axis],
+        axis=normalized_axis,
+        filter_width=filter_width,
+    )