fix build issue and env

Dockerfile

@@ -30,7 +30,9 @@ COPY constantq.py /usr/local/lib/python3.10/site-packages/librosa/core/constantq
 COPY filters.py /usr/local/lib/python3.10/site-packages/librosa/filters.py
 COPY sequence.py /usr/local/lib/python3.10/site-packages/librosa/sequence.py
 COPY utils.py /usr/local/lib/python3.10/site-packages/librosa/feature/utils.py
-
+COPY utils/utils.py /usr/local/lib/python3.10/site-packages/librosa/util/utils.py
+COPY matching.py /usr/local/lib/python3.10/site-packages/librosa/util/matching.py
+COPY spectrum.py /usr/local/lib/python3.10/site-packages/librosa/core/spectrum.py
 # RUN cd /tmp && mkdir cache1
 
 ENV NUMBA_CACHE_DIR=/tmp

matching.py

@@ -0,0 +1,385 @@
+
+
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""Matching functions"""
+
+import numpy as np
+import numba
+
+from .exceptions import ParameterError
+from .utils import valid_intervals
+from .._typing import _SequenceLike
+
+__all__ = ["match_intervals", "match_events"]
+
+
+@numba.jit(nopython=True, cache=False)  # type: ignore
+def __jaccard(int_a: np.ndarray, int_b: np.ndarray):  # pragma: no cover
+    """Jaccard similarity between two intervals
+
+    Parameters
+    ----------
+    int_a, int_b : np.ndarrays, shape=(2,)
+
+    Returns
+    -------
+    Jaccard similarity between intervals
+    """
+    ends = [int_a[1], int_b[1]]
+    if ends[1] < ends[0]:
+        ends.reverse()
+
+    starts = [int_a[0], int_b[0]]
+    if starts[1] < starts[0]:
+        starts.reverse()
+
+    intersection = ends[0] - starts[1]
+    if intersection < 0:
+        intersection = 0.0
+
+    union = ends[1] - starts[0]
+
+    if union > 0:
+        return intersection / union
+
+    return 0.0
+
+
+@numba.jit(nopython=True, cache=False)
+def __match_interval_overlaps(query, intervals_to, candidates):  # pragma: no cover
+    """Find the best Jaccard match from query to candidates"""
+
+    best_score = -1
+    best_idx = -1
+    for idx in candidates:
+        score = __jaccard(query, intervals_to[idx])
+
+        if score > best_score:
+            best_score, best_idx = score, idx
+    return best_idx
+
+
+@numba.jit(nopython=True, cache=False)  # type: ignore
+def __match_intervals(
+    intervals_from: np.ndarray, intervals_to: np.ndarray, strict: bool = True
+) -> np.ndarray:  # pragma: no cover
+    """Numba-accelerated interval matching algorithm."""
+    # sort index of the interval starts
+    start_index = np.argsort(intervals_to[:, 0])
+
+    # sort index of the interval ends
+    end_index = np.argsort(intervals_to[:, 1])
+
+    # and sorted values of starts
+    start_sorted = intervals_to[start_index, 0]
+    # and ends
+    end_sorted = intervals_to[end_index, 1]
+
+    search_ends = np.searchsorted(start_sorted, intervals_from[:, 1], side="right")
+    search_starts = np.searchsorted(end_sorted, intervals_from[:, 0], side="left")
+
+    output = np.empty(len(intervals_from), dtype=numba.uint32)
+    for i in range(len(intervals_from)):
+        query = intervals_from[i]
+
+        # Find the intervals that start after our query ends
+        after_query = search_ends[i]
+        # And the intervals that end after our query begins
+        before_query = search_starts[i]
+
+        # Candidates for overlapping have to (end after we start) and (begin before we end)
+        candidates = set(start_index[:after_query]) & set(end_index[before_query:])
+
+        # Proceed as before
+        if len(candidates) > 0:
+            output[i] = __match_interval_overlaps(query, intervals_to, candidates)
+        elif strict:
+            # Numba only lets us use compile-time constants in exception messages
+            raise ParameterError
+        else:
+            # Find the closest interval
+            # (start_index[after_query] - query[1]) is the distance to the next interval
+            # (query[0] - end_index[before_query])
+            dist_before = np.inf
+            dist_after = np.inf
+            if search_starts[i] > 0:
+                dist_before = query[0] - end_sorted[search_starts[i] - 1]
+            if search_ends[i] + 1 < len(intervals_to):
+                dist_after = start_sorted[search_ends[i] + 1] - query[1]
+            if dist_before < dist_after:
+                output[i] = end_index[search_starts[i] - 1]
+            else:
+                output[i] = start_index[search_ends[i] + 1]
+    return output
+
+
+def match_intervals(
+    intervals_from: np.ndarray, intervals_to: np.ndarray, strict: bool = True
+) -> np.ndarray:
+    """Match one set of time intervals to another.
+
+    This can be useful for tasks such as mapping beat timings
+    to segments.
+
+    Each element ``[a, b]`` of ``intervals_from`` is matched to the
+    element ``[c, d]`` of ``intervals_to`` which maximizes the
+    Jaccard similarity between the intervals::
+
+        max(0, |min(b, d) - max(a, c)|) / |max(d, b) - min(a, c)|
+
+    In ``strict=True`` mode, if there is no interval with positive
+    intersection with ``[a,b]``, an exception is thrown.
+
+    In ``strict=False`` mode, any interval ``[a, b]`` that has no
+    intersection with any element of ``intervals_to`` is instead
+    matched to the interval ``[c, d]`` which minimizes::
+
+        min(|b - c|, |a - d|)
+
+    that is, the disjoint interval [c, d] with a boundary closest
+    to [a, b].
+
+    .. note:: An element of ``intervals_to`` may be matched to multiple
+       entries of ``intervals_from``.
+
+    Parameters
+    ----------
+    intervals_from : np.ndarray [shape=(n, 2)]
+        The time range for source intervals.
+        The ``i`` th interval spans time ``intervals_from[i, 0]``
+        to ``intervals_from[i, 1]``.
+        ``intervals_from[0, 0]`` should be 0, ``intervals_from[-1, 1]``
+        should be the track duration.
+    intervals_to : np.ndarray [shape=(m, 2)]
+        Analogous to ``intervals_from``.
+    strict : bool
+        If ``True``, intervals can only match if they intersect.
+        If ``False``, disjoint intervals can match.
+
+    Returns
+    -------
+    interval_mapping : np.ndarray [shape=(n,)]
+        For each interval in ``intervals_from``, the
+        corresponding interval in ``intervals_to``.
+
+    See Also
+    --------
+    match_events
+
+    Raises
+    ------
+    ParameterError
+        If either array of input intervals is not the correct shape
+
+        If ``strict=True`` and some element of ``intervals_from`` is disjoint from
+        every element of ``intervals_to``.
+
+    Examples
+    --------
+    >>> ints_from = np.array([[3, 5], [1, 4], [4, 5]])
+    >>> ints_to = np.array([[0, 2], [1, 3], [4, 5], [6, 7]])
+    >>> librosa.util.match_intervals(ints_from, ints_to)
+    array([2, 1, 2], dtype=uint32)
+    >>> # [3, 5] => [4, 5]  (ints_to[2])
+    >>> # [1, 4] => [1, 3]  (ints_to[1])
+    >>> # [4, 5] => [4, 5]  (ints_to[2])
+
+    The reverse matching of the above is not possible in ``strict`` mode
+    because ``[6, 7]`` is disjoint from all intervals in ``ints_from``.
+    With ``strict=False``, we get the following:
+
+    >>> librosa.util.match_intervals(ints_to, ints_from, strict=False)
+    array([1, 1, 2, 2], dtype=uint32)
+    >>> # [0, 2] => [1, 4]  (ints_from[1])
+    >>> # [1, 3] => [1, 4]  (ints_from[1])
+    >>> # [4, 5] => [4, 5]  (ints_from[2])
+    >>> # [6, 7] => [4, 5]  (ints_from[2])
+    """
+
+    if len(intervals_from) == 0 or len(intervals_to) == 0:
+        raise ParameterError("Attempting to match empty interval list")
+
+    # Verify that the input intervals has correct shape and size
+    valid_intervals(intervals_from)
+    valid_intervals(intervals_to)
+
+    try:
+        # Suppress type check because of numba wrapper
+        return __match_intervals(intervals_from, intervals_to, strict=strict)  # type: ignore
+    except ParameterError as exc:
+        raise ParameterError(f"Unable to match intervals with strict={strict}") from exc
+
+
+def match_events(
+    events_from: _SequenceLike,
+    events_to: _SequenceLike,
+    left: bool = True,
+    right: bool = True,
+) -> np.ndarray:
+    """Match one set of events to another.
+
+    This is useful for tasks such as matching beats to the nearest
+    detected onsets, or frame-aligned events to the nearest zero-crossing.
+
+    .. note:: A target event may be matched to multiple source events.
+
+    Examples
+    --------
+    >>> # Sources are multiples of 7
+    >>> s_from = np.arange(0, 100, 7)
+    >>> s_from
+    array([ 0,  7, 14, 21, 28, 35, 42, 49, 56, 63, 70, 77, 84, 91,
+           98])
+    >>> # Targets are multiples of 10
+    >>> s_to = np.arange(0, 100, 10)
+    >>> s_to
+    array([ 0, 10, 20, 30, 40, 50, 60, 70, 80, 90])
+    >>> # Find the matching
+    >>> idx = librosa.util.match_events(s_from, s_to)
+    >>> idx
+    array([0, 1, 1, 2, 3, 3, 4, 5, 6, 6, 7, 8, 8, 9, 9])
+    >>> # Print each source value to its matching target
+    >>> zip(s_from, s_to[idx])
+    [(0, 0), (7, 10), (14, 10), (21, 20), (28, 30), (35, 30),
+     (42, 40), (49, 50), (56, 60), (63, 60), (70, 70), (77, 80),
+     (84, 80), (91, 90), (98, 90)]
+
+    Parameters
+    ----------
+    events_from : ndarray [shape=(n,)]
+        Array of events (eg, times, sample or frame indices) to match from.
+    events_to : ndarray [shape=(m,)]
+        Array of events (eg, times, sample or frame indices) to
+        match against.
+    left : bool
+    right : bool
+        If ``False``, then matched events cannot be to the left (or right)
+        of source events.
+
+    Returns
+    -------
+    event_mapping : np.ndarray [shape=(n,)]
+        For each event in ``events_from``, the corresponding event
+        index in ``events_to``::
+
+            event_mapping[i] == arg min |events_from[i] - events_to[:]|
+
+    See Also
+    --------
+    match_intervals
+
+    Raises
+    ------
+    ParameterError
+        If either array of input events is not the correct shape
+    """
+    if len(events_from) == 0 or len(events_to) == 0:
+        raise ParameterError("Attempting to match empty event list")
+
+    # If we can't match left or right, then only strict equivalence
+    # counts as a match.
+    if not (left or right) and not np.all(np.in1d(events_from, events_to)):
+        raise ParameterError(
+            "Cannot match events with left=right=False "
+            "and events_from is not contained "
+            "in events_to"
+        )
+
+    # If we can't match to the left, then there should be at least one
+    # target event greater-equal to every source event
+    if (not left) and max(events_to) < max(events_from):
+        raise ParameterError(
+            "Cannot match events with left=False "
+            "and max(events_to) < max(events_from)"
+        )
+
+    # If we can't match to the right, then there should be at least one
+    # target event less-equal to every source event
+    if (not right) and min(events_to) > min(events_from):
+        raise ParameterError(
+            "Cannot match events with right=False "
+            "and min(events_to) > min(events_from)"
+        )
+
+    # array of matched items
+    output = np.empty_like(events_from, dtype=np.int32)
+
+    # Suppress type check because of numba
+    return __match_events_helper(output, events_from, events_to, left, right)  # type: ignore
+
+
+@numba.jit(nopython=True, cache=False)  # type: ignore
+def __match_events_helper(
+    output: np.ndarray,
+    events_from: np.ndarray,
+    events_to: np.ndarray,
+    left: bool = True,
+    right: bool = True,
+):  # pragma: no cover
+    # mock dictionary for events
+    from_idx = np.argsort(events_from)
+    sorted_from = events_from[from_idx]
+
+    to_idx = np.argsort(events_to)
+    sorted_to = events_to[to_idx]
+
+    # find the matching indices
+    matching_indices = np.searchsorted(sorted_to, sorted_from)
+
+    # iterate over indices in matching_indices
+    for ind, middle_ind in enumerate(matching_indices):
+        left_flag = False
+        right_flag = False
+
+        left_ind = -1
+        right_ind = len(matching_indices)
+
+        left_diff = 0
+        right_diff = 0
+        mid_diff = 0
+
+        middle_ind = matching_indices[ind]
+        sorted_from_num = sorted_from[ind]
+
+        # Prevent oob from chosen index
+        if middle_ind == len(sorted_to):
+            middle_ind -= 1
+
+        # Permitted to look to the left
+        if left and middle_ind > 0:
+            left_ind = middle_ind - 1
+            left_flag = True
+
+        # Permitted to look to right
+        if right and middle_ind < len(sorted_to) - 1:
+            right_ind = middle_ind + 1
+            right_flag = True
+
+        mid_diff = abs(sorted_to[middle_ind] - sorted_from_num)
+        if left and left_flag:
+            left_diff = abs(sorted_to[left_ind] - sorted_from_num)
+        if right and right_flag:
+            right_diff = abs(sorted_to[right_ind] - sorted_from_num)
+
+        if left_flag and (
+            not right
+            and (sorted_to[middle_ind] > sorted_from_num)
+            or (not right_flag and left_diff < mid_diff)
+            or (left_diff < right_diff and left_diff < mid_diff)
+        ):
+            output[ind] = to_idx[left_ind]
+
+        # Check if right should be chosen
+        elif right_flag and (right_diff < mid_diff):
+            output[ind] = to_idx[right_ind]
+
+        # Selected index wins
+        else:
+            output[ind] = to_idx[middle_ind]
+
+    # Undo sorting
+    solutions = np.empty_like(output)
+    solutions[from_idx] = output
+
+    return solutions

utils/utils.py

@@ -0,0 +1,2609 @@
+
+
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""Utility functions"""
+
+from __future__ import annotations
+
+import scipy.ndimage
+import scipy.sparse
+
+import numpy as np
+import numba
+from numpy.lib.stride_tricks import as_strided
+
+from .._cache import cache
+from .exceptions import ParameterError
+from .deprecation import Deprecated
+from numpy.typing import ArrayLike, DTypeLike
+from typing import (
+    Any,
+    Callable,
+    Iterable,
+    List,
+    Dict,
+    Optional,
+    Sequence,
+    Tuple,
+    TypeVar,
+    Union,
+    overload,
+)
+from typing_extensions import Literal
+from .._typing import _SequenceLike, _FloatLike_co, _ComplexLike_co
+
+# Constrain STFT block sizes to 256 KB
+MAX_MEM_BLOCK = 2**8 * 2**10
+
+__all__ = [
+    "MAX_MEM_BLOCK",
+    "frame",
+    "pad_center",
+    "expand_to",
+    "fix_length",
+    "valid_audio",
+    "valid_int",
+    "is_positive_int",
+    "valid_intervals",
+    "fix_frames",
+    "axis_sort",
+    "localmax",
+    "localmin",
+    "normalize",
+    "peak_pick",
+    "sparsify_rows",
+    "shear",
+    "stack",
+    "fill_off_diagonal",
+    "index_to_slice",
+    "sync",
+    "softmask",
+    "buf_to_float",
+    "tiny",
+    "cyclic_gradient",
+    "dtype_r2c",
+    "dtype_c2r",
+    "count_unique",
+    "is_unique",
+    "abs2",
+    "phasor",
+]
+
+
+def frame(
+    x: np.ndarray,
+    *,
+    frame_length: int,
+    hop_length: int,
+    axis: int = -1,
+    writeable: bool = False,
+    subok: bool = False,
+) -> np.ndarray:
+    """Slice a data array into (overlapping) frames.
+
+    This implementation uses low-level stride manipulation to avoid
+    making a copy of the data.  The resulting frame representation
+    is a new view of the same input data.
+
+    For example, a one-dimensional input ``x = [0, 1, 2, 3, 4, 5, 6]``
+    can be framed with frame length 3 and hop length 2 in two ways.
+    The first (``axis=-1``), results in the array ``x_frames``::
+
+        [[0, 2, 4],
+         [1, 3, 5],
+         [2, 4, 6]]
+
+    where each column ``x_frames[:, i]`` contains a contiguous slice of
+    the input ``x[i * hop_length : i * hop_length + frame_length]``.
+
+    The second way (``axis=0``) results in the array ``x_frames``::
+
+        [[0, 1, 2],
+         [2, 3, 4],
+         [4, 5, 6]]
+
+    where each row ``x_frames[i]`` contains a contiguous slice of the input.
+
+    This generalizes to higher dimensional inputs, as shown in the examples below.
+    In general, the framing operation increments by 1 the number of dimensions,
+    adding a new "frame axis" either before the framing axis (if ``axis < 0``)
+    or after the framing axis (if ``axis >= 0``).
+
+    Parameters
+    ----------
+    x : np.ndarray
+        Array to frame
+    frame_length : int > 0 [scalar]
+        Length of the frame
+    hop_length : int > 0 [scalar]
+        Number of steps to advance between frames
+    axis : int
+        The axis along which to frame.
+    writeable : bool
+        If ``True``, then the framed view of ``x`` is read-only.
+        If ``False``, then the framed view is read-write.  Note that writing to the framed view
+        will also write to the input array ``x`` in this case.
+    subok : bool
+        If True, sub-classes will be passed-through, otherwise the returned array will be
+        forced to be a base-class array (default).
+
+    Returns
+    -------
+    x_frames : np.ndarray [shape=(..., frame_length, N_FRAMES, ...)]
+        A framed view of ``x``, for example with ``axis=-1`` (framing on the last dimension)::
+
+            x_frames[..., j] == x[..., j * hop_length : j * hop_length + frame_length]
+
+        If ``axis=0`` (framing on the first dimension), then::
+
+            x_frames[j] = x[j * hop_length : j * hop_length + frame_length]
+
+    Raises
+    ------
+    ParameterError
+        If ``x.shape[axis] < frame_length``, there is not enough data to fill one frame.
+
+        If ``hop_length < 1``, frames cannot advance.
+
+    See Also
+    --------
+    numpy.lib.stride_tricks.as_strided
+
+    Examples
+    --------
+    Extract 2048-sample frames from monophonic signal with a hop of 64 samples per frame
+
+    >>> y, sr = librosa.load(librosa.ex('trumpet'))
+    >>> frames = librosa.util.frame(y, frame_length=2048, hop_length=64)
+    >>> frames
+    array([[-1.407e-03, -2.604e-02, ..., -1.795e-05, -8.108e-06],
+           [-4.461e-04, -3.721e-02, ..., -1.573e-05, -1.652e-05],
+           ...,
+           [ 7.960e-02, -2.335e-01, ..., -6.815e-06,  1.266e-05],
+           [ 9.568e-02, -1.252e-01, ...,  7.397e-06, -1.921e-05]],
+          dtype=float32)
+    >>> y.shape
+    (117601,)
+
+    >>> frames.shape
+    (2048, 1806)
+
+    Or frame along the first axis instead of the last:
+
+    >>> frames = librosa.util.frame(y, frame_length=2048, hop_length=64, axis=0)
+    >>> frames.shape
+    (1806, 2048)
+
+    Frame a stereo signal:
+
+    >>> y, sr = librosa.load(librosa.ex('trumpet', hq=True), mono=False)
+    >>> y.shape
+    (2, 117601)
+    >>> frames = librosa.util.frame(y, frame_length=2048, hop_length=64)
+    (2, 2048, 1806)
+
+    Carve an STFT into fixed-length patches of 32 frames with 50% overlap
+
+    >>> y, sr = librosa.load(librosa.ex('trumpet'))
+    >>> S = np.abs(librosa.stft(y))
+    >>> S.shape
+    (1025, 230)
+    >>> S_patch = librosa.util.frame(S, frame_length=32, hop_length=16)
+    >>> S_patch.shape
+    (1025, 32, 13)
+    >>> # The first patch contains the first 32 frames of S
+    >>> np.allclose(S_patch[:, :, 0], S[:, :32])
+    True
+    >>> # The second patch contains frames 16 to 16+32=48, and so on
+    >>> np.allclose(S_patch[:, :, 1], S[:, 16:48])
+    True
+    """
+
+    # This implementation is derived from numpy.lib.stride_tricks.sliding_window_view (1.20.0)
+    # https://numpy.org/doc/stable/reference/generated/numpy.lib.stride_tricks.sliding_window_view.html
+
+    x = np.array(x, copy=False, subok=subok)
+
+    if x.shape[axis] < frame_length:
+        raise ParameterError(
+            f"Input is too short (n={x.shape[axis]:d}) for frame_length={frame_length:d}"
+        )
+
+    if hop_length < 1:
+        raise ParameterError(f"Invalid hop_length: {hop_length:d}")
+
+    # put our new within-frame axis at the end for now
+    out_strides = x.strides + tuple([x.strides[axis]])
+
+    # Reduce the shape on the framing axis
+    x_shape_trimmed = list(x.shape)
+    x_shape_trimmed[axis] -= frame_length - 1
+
+    out_shape = tuple(x_shape_trimmed) + tuple([frame_length])
+    xw = as_strided(
+        x, strides=out_strides, shape=out_shape, subok=subok, writeable=writeable
+    )
+
+    if axis < 0:
+        target_axis = axis - 1
+    else:
+        target_axis = axis + 1
+
+    xw = np.moveaxis(xw, -1, target_axis)
+
+    # Downsample along the target axis
+    slices = [slice(None)] * xw.ndim
+    slices[axis] = slice(0, None, hop_length)
+    return xw[tuple(slices)]
+
+
+@cache(level=20)
+def valid_audio(y: np.ndarray, *, mono: Union[bool, Deprecated] = Deprecated()) -> bool:
+    """Determine whether a variable contains valid audio data.
+
+    The following conditions must be satisfied:
+
+    - ``type(y)`` is ``np.ndarray``
+    - ``y.dtype`` is floating-point
+    - ``y.ndim != 0`` (must have at least one dimension)
+    - ``np.isfinite(y).all()`` samples must be all finite values
+
+    If ``mono`` is specified, then we additionally require
+    - ``y.ndim == 1``
+
+    Parameters
+    ----------
+    y : np.ndarray
+        The input data to validate
+
+    mono : bool
+        Whether or not to require monophonic audio
+
+        .. warning:: The ``mono`` parameter is deprecated in version 0.9 and will be
+          removed in 0.10.
+
+    Returns
+    -------
+    valid : bool
+        True if all tests pass
+
+    Raises
+    ------
+    ParameterError
+        In any of the conditions specified above fails
+
+    Notes
+    -----
+    This function caches at level 20.
+
+    Examples
+    --------
+    >>> # By default, valid_audio allows only mono signals
+    >>> filepath = librosa.ex('trumpet', hq=True)
+    >>> y_mono, sr = librosa.load(filepath, mono=True)
+    >>> y_stereo, _ = librosa.load(filepath, mono=False)
+    >>> librosa.util.valid_audio(y_mono), librosa.util.valid_audio(y_stereo)
+    True, False
+
+    >>> # To allow stereo signals, set mono=False
+    >>> librosa.util.valid_audio(y_stereo, mono=False)
+    True
+
+    See Also
+    --------
+    numpy.float32
+    """
+
+    if not isinstance(y, np.ndarray):
+        raise ParameterError("Audio data must be of type numpy.ndarray")
+
+    if not np.issubdtype(y.dtype, np.floating):
+        raise ParameterError("Audio data must be floating-point")
+
+    if y.ndim == 0:
+        raise ParameterError(
+            f"Audio data must be at least one-dimensional, given y.shape={y.shape}"
+        )
+
+    if isinstance(mono, Deprecated):
+        mono = False
+
+    if mono and y.ndim != 1:
+        raise ParameterError(
+            f"Invalid shape for monophonic audio: ndim={y.ndim:d}, shape={y.shape}"
+        )
+
+    if not np.isfinite(y).all():
+        raise ParameterError("Audio buffer is not finite everywhere")
+
+    return True
+
+
+def valid_int(x: float, *, cast: Optional[Callable[[float], float]] = None) -> int:
+    """Ensure that an input value is integer-typed.
+    This is primarily useful for ensuring integrable-valued
+    array indices.
+
+    Parameters
+    ----------
+    x : number
+        A scalar value to be cast to int
+    cast : function [optional]
+        A function to modify ``x`` before casting.
+        Default: `np.floor`
+
+    Returns
+    -------
+    x_int : int
+        ``x_int = int(cast(x))``
+
+    Raises
+    ------
+    ParameterError
+        If ``cast`` is provided and is not callable.
+    """
+
+    if cast is None:
+        cast = np.floor
+
+    if not callable(cast):
+        raise ParameterError("cast parameter must be callable")
+
+    return int(cast(x))
+
+
+def is_positive_int(x: float) -> bool:
+    """Checks that x is a positive integer, i.e. 1 or greater.
+
+    Parameters
+    ----------
+    x : number
+
+    Returns
+    -------
+    positive : bool
+
+    """
+
+    # Check type first to catch None values.
+    return isinstance(x, (int, np.integer)) and (x > 0)
+
+
+def valid_intervals(intervals: np.ndarray) -> bool:
+    """Ensure that an array is a valid representation of time intervals:
+
+        - intervals.ndim == 2
+        - intervals.shape[1] == 2
+        - intervals[i, 0] <= intervals[i, 1] for all i
+
+    Parameters
+    ----------
+    intervals : np.ndarray [shape=(n, 2)]
+        set of time intervals
+
+    Returns
+    -------
+    valid : bool
+        True if ``intervals`` passes validation.
+    """
+
+    if intervals.ndim != 2 or intervals.shape[-1] != 2:
+        raise ParameterError("intervals must have shape (n, 2)")
+
+    if np.any(intervals[:, 0] > intervals[:, 1]):
+        raise ParameterError(f"intervals={intervals} must have non-negative durations")
+
+    return True
+
+
+def pad_center(
+    data: np.ndarray, *, size: int, axis: int = -1, **kwargs: Any
+) -> np.ndarray:
+    """Pad an array to a target length along a target axis.
+
+    This differs from `np.pad` by centering the data prior to padding,
+    analogous to `str.center`
+
+    Examples
+    --------
+    >>> # Generate a vector
+    >>> data = np.ones(5)
+    >>> librosa.util.pad_center(data, size=10, mode='constant')
+    array([ 0.,  0.,  1.,  1.,  1.,  1.,  1.,  0.,  0.,  0.])
+
+    >>> # Pad a matrix along its first dimension
+    >>> data = np.ones((3, 5))
+    >>> librosa.util.pad_center(data, size=7, axis=0)
+    array([[ 0.,  0.,  0.,  0.,  0.],
+           [ 0.,  0.,  0.,  0.,  0.],
+           [ 1.,  1.,  1.,  1.,  1.],
+           [ 1.,  1.,  1.,  1.,  1.],
+           [ 1.,  1.,  1.,  1.,  1.],
+           [ 0.,  0.,  0.,  0.,  0.],
+           [ 0.,  0.,  0.,  0.,  0.]])
+    >>> # Or its second dimension
+    >>> librosa.util.pad_center(data, size=7, axis=1)
+    array([[ 0.,  1.,  1.,  1.,  1.,  1.,  0.],
+           [ 0.,  1.,  1.,  1.,  1.,  1.,  0.],
+           [ 0.,  1.,  1.,  1.,  1.,  1.,  0.]])
+
+    Parameters
+    ----------
+    data : np.ndarray
+        Vector to be padded and centered
+    size : int >= len(data) [scalar]
+        Length to pad ``data``
+    axis : int
+        Axis along which to pad and center the data
+    **kwargs : additional keyword arguments
+        arguments passed to `np.pad`
+
+    Returns
+    -------
+    data_padded : np.ndarray
+        ``data`` centered and padded to length ``size`` along the
+        specified axis
+
+    Raises
+    ------
+    ParameterError
+        If ``size < data.shape[axis]``
+
+    See Also
+    --------
+    numpy.pad
+    """
+
+    kwargs.setdefault("mode", "constant")
+
+    n = data.shape[axis]
+
+    lpad = int((size - n) // 2)
+
+    lengths = [(0, 0)] * data.ndim
+    lengths[axis] = (lpad, int(size - n - lpad))
+
+    if lpad < 0:
+        raise ParameterError(
+            f"Target size ({size:d}) must be at least input size ({n:d})"
+        )
+
+    return np.pad(data, lengths, **kwargs)
+
+
+def expand_to(
+    x: np.ndarray, *, ndim: int, axes: Union[int, slice, Sequence[int], Sequence[slice]]
+) -> np.ndarray:
+    """Expand the dimensions of an input array with
+
+    Parameters
+    ----------
+    x : np.ndarray
+        The input array
+    ndim : int
+        The number of dimensions to expand to.  Must be at least ``x.ndim``
+    axes : int or slice
+        The target axis or axes to preserve from x.
+        All other axes will have length 1.
+
+    Returns
+    -------
+    x_exp : np.ndarray
+        The expanded version of ``x``, satisfying the following:
+            ``x_exp[axes] == x``
+            ``x_exp.ndim == ndim``
+
+    See Also
+    --------
+    np.expand_dims
+
+    Examples
+    --------
+    Expand a 1d array into an (n, 1) shape
+
+    >>> x = np.arange(3)
+    >>> librosa.util.expand_to(x, ndim=2, axes=0)
+    array([[0],
+       [1],
+       [2]])
+
+    Expand a 1d array into a (1, n) shape
+
+    >>> librosa.util.expand_to(x, ndim=2, axes=1)
+    array([[0, 1, 2]])
+
+    Expand a 2d array into (1, n, m, 1) shape
+
+    >>> x = np.vander(np.arange(3))
+    >>> librosa.util.expand_to(x, ndim=4, axes=[1,2]).shape
+    (1, 3, 3, 1)
+    """
+
+    # Force axes into a tuple
+    axes_tup: Tuple[int]
+    try:
+        axes_tup = tuple(axes)  # type: ignore
+    except TypeError:
+        axes_tup = tuple([axes])  # type: ignore
+
+    if len(axes_tup) != x.ndim:
+        raise ParameterError(
+            f"Shape mismatch between axes={axes_tup} and input x.shape={x.shape}"
+        )
+
+    if ndim < x.ndim:
+        raise ParameterError(
+            f"Cannot expand x.shape={x.shape} to fewer dimensions ndim={ndim}"
+        )
+
+    shape: List[int] = [1] * ndim
+    for i, axi in enumerate(axes_tup):
+        shape[axi] = x.shape[i]
+
+    return x.reshape(shape)
+
+
+def fix_length(
+    data: np.ndarray, *, size: int, axis: int = -1, **kwargs: Any
+) -> np.ndarray:
+    """Fix the length an array ``data`` to exactly ``size`` along a target axis.
+
+    If ``data.shape[axis] < n``, pad according to the provided kwargs.
+    By default, ``data`` is padded with trailing zeros.
+
+    Examples
+    --------
+    >>> y = np.arange(7)
+    >>> # Default: pad with zeros
+    >>> librosa.util.fix_length(y, size=10)
+    array([0, 1, 2, 3, 4, 5, 6, 0, 0, 0])
+    >>> # Trim to a desired length
+    >>> librosa.util.fix_length(y, size=5)
+    array([0, 1, 2, 3, 4])
+    >>> # Use edge-padding instead of zeros
+    >>> librosa.util.fix_length(y, size=10, mode='edge')
+    array([0, 1, 2, 3, 4, 5, 6, 6, 6, 6])
+
+    Parameters
+    ----------
+    data : np.ndarray
+        array to be length-adjusted
+    size : int >= 0 [scalar]
+        desired length of the array
+    axis : int, <= data.ndim
+        axis along which to fix length
+    **kwargs : additional keyword arguments
+        Parameters to ``np.pad``
+
+    Returns
+    -------
+    data_fixed : np.ndarray [shape=data.shape]
+        ``data`` either trimmed or padded to length ``size``
+        along the specified axis.
+
+    See Also
+    --------
+    numpy.pad
+    """
+
+    kwargs.setdefault("mode", "constant")
+
+    n = data.shape[axis]
+
+    if n > size:
+        slices = [slice(None)] * data.ndim
+        slices[axis] = slice(0, size)
+        return data[tuple(slices)]
+
+    elif n < size:
+        lengths = [(0, 0)] * data.ndim
+        lengths[axis] = (0, size - n)
+        return np.pad(data, lengths, **kwargs)
+
+    return data
+
+
+def fix_frames(
+    frames: _SequenceLike[int],
+    *,
+    x_min: Optional[int] = 0,
+    x_max: Optional[int] = None,
+    pad: bool = True,
+) -> np.ndarray:
+    """Fix a list of frames to lie within [x_min, x_max]
+
+    Examples
+    --------
+    >>> # Generate a list of frame indices
+    >>> frames = np.arange(0, 1000.0, 50)
+    >>> frames
+    array([   0.,   50.,  100.,  150.,  200.,  250.,  300.,  350.,
+            400.,  450.,  500.,  550.,  600.,  650.,  700.,  750.,
+            800.,  850.,  900.,  950.])
+    >>> # Clip to span at most 250
+    >>> librosa.util.fix_frames(frames, x_max=250)
+    array([  0,  50, 100, 150, 200, 250])
+    >>> # Or pad to span up to 2500
+    >>> librosa.util.fix_frames(frames, x_max=2500)
+    array([   0,   50,  100,  150,  200,  250,  300,  350,  400,
+            450,  500,  550,  600,  650,  700,  750,  800,  850,
+            900,  950, 2500])
+    >>> librosa.util.fix_frames(frames, x_max=2500, pad=False)
+    array([  0,  50, 100, 150, 200, 250, 300, 350, 400, 450, 500,
+           550, 600, 650, 700, 750, 800, 850, 900, 950])
+
+    >>> # Or starting away from zero
+    >>> frames = np.arange(200, 500, 33)
+    >>> frames
+    array([200, 233, 266, 299, 332, 365, 398, 431, 464, 497])
+    >>> librosa.util.fix_frames(frames)
+    array([  0, 200, 233, 266, 299, 332, 365, 398, 431, 464, 497])
+    >>> librosa.util.fix_frames(frames, x_max=500)
+    array([  0, 200, 233, 266, 299, 332, 365, 398, 431, 464, 497,
+           500])
+
+    Parameters
+    ----------
+    frames : np.ndarray [shape=(n_frames,)]
+        List of non-negative frame indices
+    x_min : int >= 0 or None
+        Minimum allowed frame index
+    x_max : int >= 0 or None
+        Maximum allowed frame index
+    pad : boolean
+        If ``True``, then ``frames`` is expanded to span the full range
+        ``[x_min, x_max]``
+
+    Returns
+    -------
+    fixed_frames : np.ndarray [shape=(n_fixed_frames,), dtype=int]
+        Fixed frame indices, flattened and sorted
+
+    Raises
+    ------
+    ParameterError
+        If ``frames`` contains negative values
+    """
+
+    frames = np.asarray(frames)
+
+    if np.any(frames < 0):
+        raise ParameterError("Negative frame index detected")
+
+    # TODO: this whole function could be made more efficient
+
+    if pad and (x_min is not None or x_max is not None):
+        frames = np.clip(frames, x_min, x_max)
+
+    if pad:
+        pad_data = []
+        if x_min is not None:
+            pad_data.append(x_min)
+        if x_max is not None:
+            pad_data.append(x_max)
+        frames = np.concatenate((np.asarray(pad_data), frames))
+
+    if x_min is not None:
+        frames = frames[frames >= x_min]
+
+    if x_max is not None:
+        frames = frames[frames <= x_max]
+
+    unique: np.ndarray = np.unique(frames).astype(int)
+    return unique
+
+
+@overload
+def axis_sort(
+    S: np.ndarray,
+    *,
+    axis: int = ...,
+    index: Literal[False] = ...,
+    value: Optional[Callable[..., Any]] = ...,
+) -> np.ndarray:
+    ...
+
+
+@overload
+def axis_sort(
+    S: np.ndarray,
+    *,
+    axis: int = ...,
+    index: Literal[True],
+    value: Optional[Callable[..., Any]] = ...,
+) -> Tuple[np.ndarray, np.ndarray]:
+    ...
+
+
+def axis_sort(
+    S: np.ndarray,
+    *,
+    axis: int = -1,
+    index: bool = False,
+    value: Optional[Callable[..., Any]] = None,
+) -> Union[np.ndarray, Tuple[np.ndarray, np.ndarray]]:
+    """Sort an array along its rows or columns.
+
+    Examples
+    --------
+    Visualize NMF output for a spectrogram S
+
+    >>> # Sort the columns of W by peak frequency bin
+    >>> y, sr = librosa.load(librosa.ex('trumpet'))
+    >>> S = np.abs(librosa.stft(y))
+    >>> W, H = librosa.decompose.decompose(S, n_components=64)
+    >>> W_sort = librosa.util.axis_sort(W)
+
+    Or sort by the lowest frequency bin
+
+    >>> W_sort = librosa.util.axis_sort(W, value=np.argmin)
+
+    Or sort the rows instead of the columns
+
+    >>> W_sort_rows = librosa.util.axis_sort(W, axis=0)
+
+    Get the sorting index also, and use it to permute the rows of H
+
+    >>> W_sort, idx = librosa.util.axis_sort(W, index=True)
+    >>> H_sort = H[idx, :]
+
+    >>> import matplotlib.pyplot as plt
+    >>> fig, ax = plt.subplots(nrows=2, ncols=2)
+    >>> img_w = librosa.display.specshow(librosa.amplitude_to_db(W, ref=np.max),
+    ...                                  y_axis='log', ax=ax[0, 0])
+    >>> ax[0, 0].set(title='W')
+    >>> ax[0, 0].label_outer()
+    >>> img_act = librosa.display.specshow(H, x_axis='time', ax=ax[0, 1])
+    >>> ax[0, 1].set(title='H')
+    >>> ax[0, 1].label_outer()
+    >>> librosa.display.specshow(librosa.amplitude_to_db(W_sort,
+    ...                                                  ref=np.max),
+    ...                          y_axis='log', ax=ax[1, 0])
+    >>> ax[1, 0].set(title='W sorted')
+    >>> librosa.display.specshow(H_sort, x_axis='time', ax=ax[1, 1])
+    >>> ax[1, 1].set(title='H sorted')
+    >>> ax[1, 1].label_outer()
+    >>> fig.colorbar(img_w, ax=ax[:, 0], orientation='horizontal')
+    >>> fig.colorbar(img_act, ax=ax[:, 1], orientation='horizontal')
+
+    Parameters
+    ----------
+    S : np.ndarray [shape=(d, n)]
+        Array to be sorted
+
+    axis : int [scalar]
+        The axis along which to compute the sorting values
+
+        - ``axis=0`` to sort rows by peak column index
+        - ``axis=1`` to sort columns by peak row index
+
+    index : boolean [scalar]
+        If true, returns the index array as well as the permuted data.
+
+    value : function
+        function to return the index corresponding to the sort order.
+        Default: `np.argmax`.
+
+    Returns
+    -------
+    S_sort : np.ndarray [shape=(d, n)]
+        ``S`` with the columns or rows permuted in sorting order
+    idx : np.ndarray (optional) [shape=(d,) or (n,)]
+        If ``index == True``, the sorting index used to permute ``S``.
+        Length of ``idx`` corresponds to the selected ``axis``.
+
+    Raises
+    ------
+    ParameterError
+        If ``S`` does not have exactly 2 dimensions (``S.ndim != 2``)
+    """
+
+    if value is None:
+        value = np.argmax
+
+    if S.ndim != 2:
+        raise ParameterError("axis_sort is only defined for 2D arrays")
+
+    bin_idx = value(S, axis=np.mod(1 - axis, S.ndim))
+    idx = np.argsort(bin_idx)
+
+    sort_slice = [slice(None)] * S.ndim
+    sort_slice[axis] = idx  # type: ignore
+
+    if index:
+        return S[tuple(sort_slice)], idx
+    else:
+        return S[tuple(sort_slice)]
+
+
+@cache(level=40)
+def normalize(
+    S: np.ndarray,
+    *,
+    norm: Optional[float] = np.inf,
+    axis: Optional[int] = 0,
+    threshold: Optional[_FloatLike_co] = None,
+    fill: Optional[bool] = None,
+) -> np.ndarray:
+    """Normalize an array along a chosen axis.
+
+    Given a norm (described below) and a target axis, the input
+    array is scaled so that::
+
+        norm(S, axis=axis) == 1
+
+    For example, ``axis=0`` normalizes each column of a 2-d array
+    by aggregating over the rows (0-axis).
+    Similarly, ``axis=1`` normalizes each row of a 2-d array.
+
+    This function also supports thresholding small-norm slices:
+    any slice (i.e., row or column) with norm below a specified
+    ``threshold`` can be left un-normalized, set to all-zeros, or
+    filled with uniform non-zero values that normalize to 1.
+
+    Note: the semantics of this function differ from
+    `scipy.linalg.norm` in two ways: multi-dimensional arrays
+    are supported, but matrix-norms are not.
+
+    Parameters
+    ----------
+    S : np.ndarray
+        The array to normalize
+
+    norm : {np.inf, -np.inf, 0, float > 0, None}
+        - `np.inf`  : maximum absolute value
+        - `-np.inf` : minimum absolute value
+        - `0`    : number of non-zeros (the support)
+        - float  : corresponding l_p norm
+            See `scipy.linalg.norm` for details.
+        - None : no normalization is performed
+
+    axis : int [scalar]
+        Axis along which to compute the norm.
+
+    threshold : number > 0 [optional]
+        Only the columns (or rows) with norm at least ``threshold`` are
+        normalized.
+
+        By default, the threshold is determined from
+        the numerical precision of ``S.dtype``.
+
+    fill : None or bool
+        If None, then columns (or rows) with norm below ``threshold``
+        are left as is.
+
+        If False, then columns (rows) with norm below ``threshold``
+        are set to 0.
+
+        If True, then columns (rows) with norm below ``threshold``
+        are filled uniformly such that the corresponding norm is 1.
+
+        .. note:: ``fill=True`` is incompatible with ``norm=0`` because
+            no uniform vector exists with l0 "norm" equal to 1.
+
+    Returns
+    -------
+    S_norm : np.ndarray [shape=S.shape]
+        Normalized array
+
+    Raises
+    ------
+    ParameterError
+        If ``norm`` is not among the valid types defined above
+
+        If ``S`` is not finite
+
+        If ``fill=True`` and ``norm=0``
+
+    See Also
+    --------
+    scipy.linalg.norm
+
+    Notes
+    -----
+    This function caches at level 40.
+
+    Examples
+    --------
+    >>> # Construct an example matrix
+    >>> S = np.vander(np.arange(-2.0, 2.0))
+    >>> S
+    array([[-8.,  4., -2.,  1.],
+           [-1.,  1., -1.,  1.],
+           [ 0.,  0.,  0.,  1.],
+           [ 1.,  1.,  1.,  1.]])
+    >>> # Max (l-infinity)-normalize the columns
+    >>> librosa.util.normalize(S)
+    array([[-1.   ,  1.   , -1.   ,  1.   ],
+           [-0.125,  0.25 , -0.5  ,  1.   ],
+           [ 0.   ,  0.   ,  0.   ,  1.   ],
+           [ 0.125,  0.25 ,  0.5  ,  1.   ]])
+    >>> # Max (l-infinity)-normalize the rows
+    >>> librosa.util.normalize(S, axis=1)
+    array([[-1.   ,  0.5  , -0.25 ,  0.125],
+           [-1.   ,  1.   , -1.   ,  1.   ],
+           [ 0.   ,  0.   ,  0.   ,  1.   ],
+           [ 1.   ,  1.   ,  1.   ,  1.   ]])
+    >>> # l1-normalize the columns
+    >>> librosa.util.normalize(S, norm=1)
+    array([[-0.8  ,  0.667, -0.5  ,  0.25 ],
+           [-0.1  ,  0.167, -0.25 ,  0.25 ],
+           [ 0.   ,  0.   ,  0.   ,  0.25 ],
+           [ 0.1  ,  0.167,  0.25 ,  0.25 ]])
+    >>> # l2-normalize the columns
+    >>> librosa.util.normalize(S, norm=2)
+    array([[-0.985,  0.943, -0.816,  0.5  ],
+           [-0.123,  0.236, -0.408,  0.5  ],
+           [ 0.   ,  0.   ,  0.   ,  0.5  ],
+           [ 0.123,  0.236,  0.408,  0.5  ]])
+
+    >>> # Thresholding and filling
+    >>> S[:, -1] = 1e-308
+    >>> S
+    array([[ -8.000e+000,   4.000e+000,  -2.000e+000,
+              1.000e-308],
+           [ -1.000e+000,   1.000e+000,  -1.000e+000,
+              1.000e-308],
+           [  0.000e+000,   0.000e+000,   0.000e+000,
+              1.000e-308],
+           [  1.000e+000,   1.000e+000,   1.000e+000,
+              1.000e-308]])
+
+    >>> # By default, small-norm columns are left untouched
+    >>> librosa.util.normalize(S)
+    array([[ -1.000e+000,   1.000e+000,  -1.000e+000,
+              1.000e-308],
+           [ -1.250e-001,   2.500e-001,  -5.000e-001,
+              1.000e-308],
+           [  0.000e+000,   0.000e+000,   0.000e+000,
+              1.000e-308],
+           [  1.250e-001,   2.500e-001,   5.000e-001,
+              1.000e-308]])
+    >>> # Small-norm columns can be zeroed out
+    >>> librosa.util.normalize(S, fill=False)
+    array([[-1.   ,  1.   , -1.   ,  0.   ],
+           [-0.125,  0.25 , -0.5  ,  0.   ],
+           [ 0.   ,  0.   ,  0.   ,  0.   ],
+           [ 0.125,  0.25 ,  0.5  ,  0.   ]])
+    >>> # Or set to constant with unit-norm
+    >>> librosa.util.normalize(S, fill=True)
+    array([[-1.   ,  1.   , -1.   ,  1.   ],
+           [-0.125,  0.25 , -0.5  ,  1.   ],
+           [ 0.   ,  0.   ,  0.   ,  1.   ],
+           [ 0.125,  0.25 ,  0.5  ,  1.   ]])
+    >>> # With an l1 norm instead of max-norm
+    >>> librosa.util.normalize(S, norm=1, fill=True)
+    array([[-0.8  ,  0.667, -0.5  ,  0.25 ],
+           [-0.1  ,  0.167, -0.25 ,  0.25 ],
+           [ 0.   ,  0.   ,  0.   ,  0.25 ],
+           [ 0.1  ,  0.167,  0.25 ,  0.25 ]])
+    """
+
+    # Avoid div-by-zero
+    if threshold is None:
+        threshold = tiny(S)
+
+    elif threshold <= 0:
+        raise ParameterError(f"threshold={threshold} must be strictly positive")
+
+    if fill not in [None, False, True]:
+        raise ParameterError(f"fill={fill} must be None or boolean")
+
+    if not np.all(np.isfinite(S)):
+        raise ParameterError("Input must be finite")
+
+    # All norms only depend on magnitude, let's do that first
+    mag = np.abs(S).astype(float)
+
+    # For max/min norms, filling with 1 works
+    fill_norm = 1
+
+    if norm is None:
+        return S
+
+    elif norm == np.inf:
+        length = np.max(mag, axis=axis, keepdims=True)
+
+    elif norm == -np.inf:
+        length = np.min(mag, axis=axis, keepdims=True)
+
+    elif norm == 0:
+        if fill is True:
+            raise ParameterError("Cannot normalize with norm=0 and fill=True")
+
+        length = np.sum(mag > 0, axis=axis, keepdims=True, dtype=mag.dtype)
+
+    elif np.issubdtype(type(norm), np.number) and norm > 0:
+        length = np.sum(mag**norm, axis=axis, keepdims=True) ** (1.0 / norm)
+
+        if axis is None:
+            fill_norm = mag.size ** (-1.0 / norm)
+        else:
+            fill_norm = mag.shape[axis] ** (-1.0 / norm)
+
+    else:
+        raise ParameterError(f"Unsupported norm: {repr(norm)}")
+
+    # indices where norm is below the threshold
+    small_idx = length < threshold
+
+    Snorm = np.empty_like(S)
+    if fill is None:
+        # Leave small indices un-normalized
+        length[small_idx] = 1.0
+        Snorm[:] = S / length
+
+    elif fill:
+        # If we have a non-zero fill value, we locate those entries by
+        # doing a nan-divide.
+        # If S was finite, then length is finite (except for small positions)
+        length[small_idx] = np.nan
+        Snorm[:] = S / length
+        Snorm[np.isnan(Snorm)] = fill_norm
+    else:
+        # Set small values to zero by doing an inf-divide.
+        # This is safe (by IEEE-754) as long as S is finite.
+        length[small_idx] = np.inf
+        Snorm[:] = S / length
+
+    return Snorm
+
+
+@numba.stencil
+def _localmax_sten(x):  # pragma: no cover
+    """Numba stencil for local maxima computation"""
+    return (x[0] > x[-1]) & (x[0] >= x[1])
+
+
+@numba.stencil
+def _localmin_sten(x):  # pragma: no cover
+    """Numba stencil for local minima computation"""
+    return (x[0] < x[-1]) & (x[0] <= x[1])
+
+
+@numba.guvectorize(
+    [
+        "void(int16[:], bool_[:])",
+        "void(int32[:], bool_[:])",
+        "void(int64[:], bool_[:])",
+        "void(float32[:], bool_[:])",
+        "void(float64[:], bool_[:])",
+    ],
+    "(n)->(n)",
+    cache=True,
+    nopython=True,
+)
+def _localmax(x, y):  # pragma: no cover
+    """Vectorized wrapper for the localmax stencil"""
+    y[:] = _localmax_sten(x)
+
+
+@numba.guvectorize(
+    [
+        "void(int16[:], bool_[:])",
+        "void(int32[:], bool_[:])",
+        "void(int64[:], bool_[:])",
+        "void(float32[:], bool_[:])",
+        "void(float64[:], bool_[:])",
+    ],
+    "(n)->(n)",
+    cache=True,
+    nopython=True,
+)
+def _localmin(x, y):  # pragma: no cover
+    """Vectorized wrapper for the localmin stencil"""
+    y[:] = _localmin_sten(x)
+
+
+def localmax(x: np.ndarray, *, axis: int = 0) -> np.ndarray:
+    """Find local maxima in an array
+
+    An element ``x[i]`` is considered a local maximum if the following
+    conditions are met:
+
+    - ``x[i] > x[i-1]``
+    - ``x[i] >= x[i+1]``
+
+    Note that the first condition is strict, and that the first element
+    ``x[0]`` will never be considered as a local maximum.
+
+    Examples
+    --------
+    >>> x = np.array([1, 0, 1, 2, -1, 0, -2, 1])
+    >>> librosa.util.localmax(x)
+    array([False, False, False,  True, False,  True, False,  True], dtype=bool)
+
+    >>> # Two-dimensional example
+    >>> x = np.array([[1,0,1], [2, -1, 0], [2, 1, 3]])
+    >>> librosa.util.localmax(x, axis=0)
+    array([[False, False, False],
+           [ True, False, False],
+           [False,  True,  True]], dtype=bool)
+    >>> librosa.util.localmax(x, axis=1)
+    array([[False, False,  True],
+           [False, False,  True],
+           [False, False,  True]], dtype=bool)
+
+    Parameters
+    ----------
+    x : np.ndarray [shape=(d1,d2,...)]
+        input vector or array
+    axis : int
+        axis along which to compute local maximality
+
+    Returns
+    -------
+    m : np.ndarray [shape=x.shape, dtype=bool]
+        indicator array of local maximality along ``axis``
+
+    See Also
+    --------
+    localmin
+    """
+    # Rotate the target axis to the end
+    xi = x.swapaxes(-1, axis)
+
+    # Allocate the output array and rotate target axis
+    lmax = np.empty_like(x, dtype=bool)
+    lmaxi = lmax.swapaxes(-1, axis)
+
+    # Call the vectorized stencil
+    _localmax(xi, lmaxi)
+
+    # Handle the edge condition not covered by the stencil
+    lmaxi[..., -1] = xi[..., -1] > xi[..., -2]
+
+    return lmax
+
+
+def localmin(x: np.ndarray, *, axis: int = 0) -> np.ndarray:
+    """Find local minima in an array
+
+    An element ``x[i]`` is considered a local minimum if the following
+    conditions are met:
+
+    - ``x[i] < x[i-1]``
+    - ``x[i] <= x[i+1]``
+
+    Note that the first condition is strict, and that the first element
+    ``x[0]`` will never be considered as a local minimum.
+
+    Examples
+    --------
+    >>> x = np.array([1, 0, 1, 2, -1, 0, -2, 1])
+    >>> librosa.util.localmin(x)
+    array([False,  True, False, False,  True, False,  True, False])
+
+    >>> # Two-dimensional example
+    >>> x = np.array([[1,0,1], [2, -1, 0], [2, 1, 3]])
+    >>> librosa.util.localmin(x, axis=0)
+    array([[False, False, False],
+           [False,  True,  True],
+           [False, False, False]])
+
+    >>> librosa.util.localmin(x, axis=1)
+    array([[False,  True, False],
+           [False,  True, False],
+           [False,  True, False]])
+
+    Parameters
+    ----------
+    x : np.ndarray [shape=(d1,d2,...)]
+        input vector or array
+    axis : int
+        axis along which to compute local minimality
+
+    Returns
+    -------
+    m : np.ndarray [shape=x.shape, dtype=bool]
+        indicator array of local minimality along ``axis``
+
+    See Also
+    --------
+    localmax
+    """
+    # Rotate the target axis to the end
+    xi = x.swapaxes(-1, axis)
+
+    # Allocate the output array and rotate target axis
+    lmin = np.empty_like(x, dtype=bool)
+    lmini = lmin.swapaxes(-1, axis)
+
+    # Call the vectorized stencil
+    _localmin(xi, lmini)
+
+    # Handle the edge condition not covered by the stencil
+    lmini[..., -1] = xi[..., -1] < xi[..., -2]
+
+    return lmin
+
+
+def peak_pick(
+    x: np.ndarray,
+    *,
+    pre_max: int,
+    post_max: int,
+    pre_avg: int,
+    post_avg: int,
+    delta: float,
+    wait: int,
+) -> np.ndarray:
+    """Uses a flexible heuristic to pick peaks in a signal.
+
+    A sample n is selected as an peak if the corresponding ``x[n]``
+    fulfills the following three conditions:
+
+    1. ``x[n] == max(x[n - pre_max:n + post_max])``
+    2. ``x[n] >= mean(x[n - pre_avg:n + post_avg]) + delta``
+    3. ``n - previous_n > wait``
+
+    where ``previous_n`` is the last sample picked as a peak (greedily).
+
+    This implementation is based on [#]_ and [#]_.
+
+    .. [#] Boeck, Sebastian, Florian Krebs, and Markus Schedl.
+        "Evaluating the Online Capabilities of Onset Detection Methods." ISMIR.
+        2012.
+
+    .. [#] https://github.com/CPJKU/onset_detection/blob/master/onset_program.py
+
+    Parameters
+    ----------
+    x : np.ndarray [shape=(n,)]
+        input signal to peak picks from
+    pre_max : int >= 0 [scalar]
+        number of samples before ``n`` over which max is computed
+    post_max : int >= 1 [scalar]
+        number of samples after ``n`` over which max is computed
+    pre_avg : int >= 0 [scalar]
+        number of samples before ``n`` over which mean is computed
+    post_avg : int >= 1 [scalar]
+        number of samples after ``n`` over which mean is computed
+    delta : float >= 0 [scalar]
+        threshold offset for mean
+    wait : int >= 0 [scalar]
+        number of samples to wait after picking a peak
+
+    Returns
+    -------
+    peaks : np.ndarray [shape=(n_peaks,), dtype=int]
+        indices of peaks in ``x``
+
+    Raises
+    ------
+    ParameterError
+        If any input lies outside its defined range
+
+    Examples
+    --------
+    >>> y, sr = librosa.load(librosa.ex('trumpet'))
+    >>> onset_env = librosa.onset.onset_strength(y=y, sr=sr,
+    ...                                          hop_length=512,
+    ...                                          aggregate=np.median)
+    >>> peaks = librosa.util.peak_pick(onset_env, pre_max=3, post_max=3, pre_avg=3, post_avg=5, delta=0.5, wait=10)
+    >>> peaks
+    array([  3,  27,  40,  61,  72,  88, 103])
+
+    >>> import matplotlib.pyplot as plt
+    >>> times = librosa.times_like(onset_env, sr=sr, hop_length=512)
+    >>> fig, ax = plt.subplots(nrows=2, sharex=True)
+    >>> D = np.abs(librosa.stft(y))
+    >>> librosa.display.specshow(librosa.amplitude_to_db(D, ref=np.max),
+    ...                          y_axis='log', x_axis='time', ax=ax[1])
+    >>> ax[0].plot(times, onset_env, alpha=0.8, label='Onset strength')
+    >>> ax[0].vlines(times[peaks], 0,
+    ...              onset_env.max(), color='r', alpha=0.8,
+    ...              label='Selected peaks')
+    >>> ax[0].legend(frameon=True, framealpha=0.8)
+    >>> ax[0].label_outer()
+    """
+
+    if pre_max < 0:
+        raise ParameterError("pre_max must be non-negative")
+    if pre_avg < 0:
+        raise ParameterError("pre_avg must be non-negative")
+    if delta < 0:
+        raise ParameterError("delta must be non-negative")
+    if wait < 0:
+        raise ParameterError("wait must be non-negative")
+
+    if post_max <= 0:
+        raise ParameterError("post_max must be positive")
+
+    if post_avg <= 0:
+        raise ParameterError("post_avg must be positive")
+
+    if x.ndim != 1:
+        raise ParameterError("input array must be one-dimensional")
+
+    # Ensure valid index types
+    pre_max = valid_int(pre_max, cast=np.ceil)
+    post_max = valid_int(post_max, cast=np.ceil)
+    pre_avg = valid_int(pre_avg, cast=np.ceil)
+    post_avg = valid_int(post_avg, cast=np.ceil)
+    wait = valid_int(wait, cast=np.ceil)
+
+    # Get the maximum of the signal over a sliding window
+    max_length = pre_max + post_max
+    max_origin = np.ceil(0.5 * (pre_max - post_max))
+    # Using mode='constant' and cval=x.min() effectively truncates
+    # the sliding window at the boundaries
+    mov_max = scipy.ndimage.filters.maximum_filter1d(
+        x, int(max_length), mode="constant", origin=int(max_origin), cval=x.min()
+    )
+
+    # Get the mean of the signal over a sliding window
+    avg_length = pre_avg + post_avg
+    avg_origin = np.ceil(0.5 * (pre_avg - post_avg))
+    # Here, there is no mode which results in the behavior we want,
+    # so we'll correct below.
+    mov_avg = scipy.ndimage.filters.uniform_filter1d(
+        x, int(avg_length), mode="nearest", origin=int(avg_origin)
+    )
+
+    # Correct sliding average at the beginning
+    n = 0
+    # Only need to correct in the range where the window needs to be truncated
+    while n - pre_avg < 0 and n < x.shape[0]:
+        # This just explicitly does mean(x[n - pre_avg:n + post_avg])
+        # with truncation
+        start = n - pre_avg
+        start = start if start > 0 else 0
+        mov_avg[n] = np.mean(x[start : n + post_avg])
+        n += 1
+    # Correct sliding average at the end
+    n = x.shape[0] - post_avg
+    # When post_avg > x.shape[0] (weird case), reset to 0
+    n = n if n > 0 else 0
+    while n < x.shape[0]:
+        start = n - pre_avg
+        start = start if start > 0 else 0
+        mov_avg[n] = np.mean(x[start : n + post_avg])
+        n += 1
+
+    # First mask out all entries not equal to the local max
+    detections = x * (x == mov_max)
+
+    # Then mask out all entries less than the thresholded average
+    detections = detections * (detections >= (mov_avg + delta))
+
+    # Initialize peaks array, to be filled greedily
+    peaks = []
+
+    # Remove onsets which are close together in time
+    last_onset = -np.inf
+
+    for i in np.nonzero(detections)[0]:
+        # Only report an onset if the "wait" samples was reported
+        if i > last_onset + wait:
+            peaks.append(i)
+            # Save last reported onset
+            last_onset = i
+
+    return np.array(peaks)
+
+
+@cache(level=40)
+def sparsify_rows(
+    x: np.ndarray, *, quantile: float = 0.01, dtype: Optional[DTypeLike] = None
+) -> scipy.sparse.csr_matrix:
+    """Return a row-sparse matrix approximating the input
+
+    Parameters
+    ----------
+    x : np.ndarray [ndim <= 2]
+        The input matrix to sparsify.
+    quantile : float in [0, 1.0)
+        Percentage of magnitude to discard in each row of ``x``
+    dtype : np.dtype, optional
+        The dtype of the output array.
+        If not provided, then ``x.dtype`` will be used.
+
+    Returns
+    -------
+    x_sparse : ``scipy.sparse.csr_matrix`` [shape=x.shape]
+        Row-sparsified approximation of ``x``
+
+        If ``x.ndim == 1``, then ``x`` is interpreted as a row vector,
+        and ``x_sparse.shape == (1, len(x))``.
+
+    Raises
+    ------
+    ParameterError
+        If ``x.ndim > 2``
+
+        If ``quantile`` lies outside ``[0, 1.0)``
+
+    Notes
+    -----
+    This function caches at level 40.
+
+    Examples
+    --------
+    >>> # Construct a Hann window to sparsify
+    >>> x = scipy.signal.hann(32)
+    >>> x
+    array([ 0.   ,  0.01 ,  0.041,  0.09 ,  0.156,  0.236,  0.326,
+            0.424,  0.525,  0.625,  0.72 ,  0.806,  0.879,  0.937,
+            0.977,  0.997,  0.997,  0.977,  0.937,  0.879,  0.806,
+            0.72 ,  0.625,  0.525,  0.424,  0.326,  0.236,  0.156,
+            0.09 ,  0.041,  0.01 ,  0.   ])
+    >>> # Discard the bottom percentile
+    >>> x_sparse = librosa.util.sparsify_rows(x, quantile=0.01)
+    >>> x_sparse
+    <1x32 sparse matrix of type '<type 'numpy.float64'>'
+        with 26 stored elements in Compressed Sparse Row format>
+    >>> x_sparse.todense()
+    matrix([[ 0.   ,  0.   ,  0.   ,  0.09 ,  0.156,  0.236,  0.326,
+              0.424,  0.525,  0.625,  0.72 ,  0.806,  0.879,  0.937,
+              0.977,  0.997,  0.997,  0.977,  0.937,  0.879,  0.806,
+              0.72 ,  0.625,  0.525,  0.424,  0.326,  0.236,  0.156,
+              0.09 ,  0.   ,  0.   ,  0.   ]])
+    >>> # Discard up to the bottom 10th percentile
+    >>> x_sparse = librosa.util.sparsify_rows(x, quantile=0.1)
+    >>> x_sparse
+    <1x32 sparse matrix of type '<type 'numpy.float64'>'
+        with 20 stored elements in Compressed Sparse Row format>
+    >>> x_sparse.todense()
+    matrix([[ 0.   ,  0.   ,  0.   ,  0.   ,  0.   ,  0.   ,  0.326,
+              0.424,  0.525,  0.625,  0.72 ,  0.806,  0.879,  0.937,
+              0.977,  0.997,  0.997,  0.977,  0.937,  0.879,  0.806,
+              0.72 ,  0.625,  0.525,  0.424,  0.326,  0.   ,  0.   ,
+              0.   ,  0.   ,  0.   ,  0.   ]])
+    """
+
+    if x.ndim == 1:
+        x = x.reshape((1, -1))
+
+    elif x.ndim > 2:
+        raise ParameterError(
+            f"Input must have 2 or fewer dimensions. Provided x.shape={x.shape}."
+        )
+
+    if not 0.0 <= quantile < 1:
+        raise ParameterError(f"Invalid quantile {quantile:.2f}")
+
+    if dtype is None:
+        dtype = x.dtype
+
+    x_sparse = scipy.sparse.lil_matrix(x.shape, dtype=dtype)
+
+    mags = np.abs(x)
+    norms = np.sum(mags, axis=1, keepdims=True)
+
+    mag_sort = np.sort(mags, axis=1)
+    cumulative_mag = np.cumsum(mag_sort / norms, axis=1)
+
+    threshold_idx = np.argmin(cumulative_mag < quantile, axis=1)
+
+    for i, j in enumerate(threshold_idx):
+        idx = np.where(mags[i] >= mag_sort[i, j])
+        x_sparse[i, idx] = x[i, idx]
+
+    return x_sparse.tocsr()
+
+
+def buf_to_float(
+    x: np.ndarray, *, n_bytes: int = 2, dtype: DTypeLike = np.float32
+) -> np.ndarray:
+    """Convert an integer buffer to floating point values.
+    This is primarily useful when loading integer-valued wav data
+    into numpy arrays.
+
+    Parameters
+    ----------
+    x : np.ndarray [dtype=int]
+        The integer-valued data buffer
+    n_bytes : int [1, 2, 4]
+        The number of bytes per sample in ``x``
+    dtype : numeric type
+        The target output type (default: 32-bit float)
+
+    Returns
+    -------
+    x_float : np.ndarray [dtype=float]
+        The input data buffer cast to floating point
+    """
+
+    # Invert the scale of the data
+    scale = 1.0 / float(1 << ((8 * n_bytes) - 1))
+
+    # Construct the format string
+    fmt = f"<i{n_bytes:d}"
+
+    # Rescale and format the data buffer
+    return scale * np.frombuffer(x, fmt).astype(dtype)
+
+
+def index_to_slice(
+    idx: _SequenceLike[int],
+    *,
+    idx_min: Optional[int] = None,
+    idx_max: Optional[int] = None,
+    step: Optional[int] = None,
+    pad: bool = True,
+) -> List[slice]:
+    """Generate a slice array from an index array.
+
+    Parameters
+    ----------
+    idx : list-like
+        Array of index boundaries
+    idx_min, idx_max : None or int
+        Minimum and maximum allowed indices
+    step : None or int
+        Step size for each slice.  If `None`, then the default
+        step of 1 is used.
+    pad : boolean
+        If `True`, pad ``idx`` to span the range ``idx_min:idx_max``.
+
+    Returns
+    -------
+    slices : list of slice
+        ``slices[i] = slice(idx[i], idx[i+1], step)``
+        Additional slice objects may be added at the beginning or end,
+        depending on whether ``pad==True`` and the supplied values for
+        ``idx_min`` and ``idx_max``.
+
+    See Also
+    --------
+    fix_frames
+
+    Examples
+    --------
+    >>> # Generate slices from spaced indices
+    >>> librosa.util.index_to_slice(np.arange(20, 100, 15))
+    [slice(20, 35, None), slice(35, 50, None), slice(50, 65, None), slice(65, 80, None),
+     slice(80, 95, None)]
+    >>> # Pad to span the range (0, 100)
+    >>> librosa.util.index_to_slice(np.arange(20, 100, 15),
+    ...                             idx_min=0, idx_max=100)
+    [slice(0, 20, None), slice(20, 35, None), slice(35, 50, None), slice(50, 65, None),
+     slice(65, 80, None), slice(80, 95, None), slice(95, 100, None)]
+    >>> # Use a step of 5 for each slice
+    >>> librosa.util.index_to_slice(np.arange(20, 100, 15),
+    ...                             idx_min=0, idx_max=100, step=5)
+    [slice(0, 20, 5), slice(20, 35, 5), slice(35, 50, 5), slice(50, 65, 5), slice(65, 80, 5),
+     slice(80, 95, 5), slice(95, 100, 5)]
+    """
+
+    # First, normalize the index set
+    idx_fixed = fix_frames(idx, x_min=idx_min, x_max=idx_max, pad=pad)
+
+    # Now convert the indices to slices
+    return [slice(start, end, step) for (start, end) in zip(idx_fixed, idx_fixed[1:])]
+
+
+@cache(level=40)
+def sync(
+    data: np.ndarray,
+    idx: Union[Sequence[int], Sequence[slice]],
+    *,
+    aggregate: Optional[Callable[..., Any]] = None,
+    pad: bool = True,
+    axis: int = -1,
+) -> np.ndarray:
+    """Synchronous aggregation of a multi-dimensional array between boundaries
+
+    .. note::
+        In order to ensure total coverage, boundary points may be added
+        to ``idx``.
+
+        If synchronizing a feature matrix against beat tracker output, ensure
+        that frame index numbers are properly aligned and use the same hop length.
+
+    Parameters
+    ----------
+    data : np.ndarray
+        multi-dimensional array of features
+    idx : sequence of ints or slices
+        Either an ordered array of boundary indices, or
+        an iterable collection of slice objects.
+    aggregate : function
+        aggregation function (default: `np.mean`)
+    pad : boolean
+        If `True`, ``idx`` is padded to span the full range ``[0, data.shape[axis]]``
+    axis : int
+        The axis along which to aggregate data
+
+    Returns
+    -------
+    data_sync : ndarray
+        ``data_sync`` will have the same dimension as ``data``, except that the ``axis``
+        coordinate will be reduced according to ``idx``.
+
+        For example, a 2-dimensional ``data`` with ``axis=-1`` should satisfy::
+
+            data_sync[:, i] = aggregate(data[:, idx[i-1]:idx[i]], axis=-1)
+
+    Raises
+    ------
+    ParameterError
+        If the index set is not of consistent type (all slices or all integers)
+
+    Notes
+    -----
+    This function caches at level 40.
+
+    Examples
+    --------
+    Beat-synchronous CQT spectra
+
+    >>> y, sr = librosa.load(librosa.ex('choice'))
+    >>> tempo, beats = librosa.beat.beat_track(y=y, sr=sr, trim=False)
+    >>> C = np.abs(librosa.cqt(y=y, sr=sr))
+    >>> beats = librosa.util.fix_frames(beats)
+
+    By default, use mean aggregation
+
+    >>> C_avg = librosa.util.sync(C, beats)
+
+    Use median-aggregation instead of mean
+
+    >>> C_med = librosa.util.sync(C, beats,
+    ...                              aggregate=np.median)
+
+    Or sub-beat synchronization
+
+    >>> sub_beats = librosa.segment.subsegment(C, beats)
+    >>> sub_beats = librosa.util.fix_frames(sub_beats)
+    >>> C_med_sub = librosa.util.sync(C, sub_beats, aggregate=np.median)
+
+    Plot the results
+
+    >>> import matplotlib.pyplot as plt
+    >>> beat_t = librosa.frames_to_time(beats, sr=sr)
+    >>> subbeat_t = librosa.frames_to_time(sub_beats, sr=sr)
+    >>> fig, ax = plt.subplots(nrows=3, sharex=True, sharey=True)
+    >>> librosa.display.specshow(librosa.amplitude_to_db(C,
+    ...                                                  ref=np.max),
+    ...                          x_axis='time', ax=ax[0])
+    >>> ax[0].set(title='CQT power, shape={}'.format(C.shape))
+    >>> ax[0].label_outer()
+    >>> librosa.display.specshow(librosa.amplitude_to_db(C_med,
+    ...                                                  ref=np.max),
+    ...                          x_coords=beat_t, x_axis='time', ax=ax[1])
+    >>> ax[1].set(title='Beat synchronous CQT power, '
+    ...                 'shape={}'.format(C_med.shape))
+    >>> ax[1].label_outer()
+    >>> librosa.display.specshow(librosa.amplitude_to_db(C_med_sub,
+    ...                                                  ref=np.max),
+    ...                          x_coords=subbeat_t, x_axis='time', ax=ax[2])
+    >>> ax[2].set(title='Sub-beat synchronous CQT power, '
+    ...                 'shape={}'.format(C_med_sub.shape))
+    """
+
+    if aggregate is None:
+        aggregate = np.mean
+
+    shape = list(data.shape)
+
+    if np.all([isinstance(_, slice) for _ in idx]):
+        slices = idx
+    elif np.all([np.issubdtype(type(_), np.integer) for _ in idx]):
+        slices = index_to_slice(
+            np.asarray(idx), idx_min=0, idx_max=shape[axis], pad=pad
+        )
+    else:
+        raise ParameterError(f"Invalid index set: {idx}")
+
+    agg_shape = list(shape)
+    agg_shape[axis] = len(slices)
+
+    data_agg = np.empty(
+        agg_shape, order="F" if np.isfortran(data) else "C", dtype=data.dtype
+    )
+
+    idx_in = [slice(None)] * data.ndim
+    idx_agg = [slice(None)] * data_agg.ndim
+
+    for i, segment in enumerate(slices):
+        idx_in[axis] = segment  # type: ignore
+        idx_agg[axis] = i  # type: ignore
+        data_agg[tuple(idx_agg)] = aggregate(data[tuple(idx_in)], axis=axis)
+
+    return data_agg
+
+
+def softmask(
+    X: np.ndarray, X_ref: np.ndarray, *, power: float = 1, split_zeros: bool = False
+) -> np.ndarray:
+    """Robustly compute a soft-mask operation.
+
+        ``M = X**power / (X**power + X_ref**power)``
+
+    Parameters
+    ----------
+    X : np.ndarray
+        The (non-negative) input array corresponding to the positive mask elements
+
+    X_ref : np.ndarray
+        The (non-negative) array of reference or background elements.
+        Must have the same shape as ``X``.
+
+    power : number > 0 or np.inf
+        If finite, returns the soft mask computed in a numerically stable way
+
+        If infinite, returns a hard (binary) mask equivalent to ``X > X_ref``.
+        Note: for hard masks, ties are always broken in favor of ``X_ref`` (``mask=0``).
+
+    split_zeros : bool
+        If `True`, entries where ``X`` and ``X_ref`` are both small (close to 0)
+        will receive mask values of 0.5.
+
+        Otherwise, the mask is set to 0 for these entries.
+
+    Returns
+    -------
+    mask : np.ndarray, shape=X.shape
+        The output mask array
+
+    Raises
+    ------
+    ParameterError
+        If ``X`` and ``X_ref`` have different shapes.
+
+        If ``X`` or ``X_ref`` are negative anywhere
+
+        If ``power <= 0``
+
+    Examples
+    --------
+    >>> X = 2 * np.ones((3, 3))
+    >>> X_ref = np.vander(np.arange(3.0))
+    >>> X
+    array([[ 2.,  2.,  2.],
+           [ 2.,  2.,  2.],
+           [ 2.,  2.,  2.]])
+    >>> X_ref
+    array([[ 0.,  0.,  1.],
+           [ 1.,  1.,  1.],
+           [ 4.,  2.,  1.]])
+    >>> librosa.util.softmask(X, X_ref, power=1)
+    array([[ 1.   ,  1.   ,  0.667],
+           [ 0.667,  0.667,  0.667],
+           [ 0.333,  0.5  ,  0.667]])
+    >>> librosa.util.softmask(X_ref, X, power=1)
+    array([[ 0.   ,  0.   ,  0.333],
+           [ 0.333,  0.333,  0.333],
+           [ 0.667,  0.5  ,  0.333]])
+    >>> librosa.util.softmask(X, X_ref, power=2)
+    array([[ 1. ,  1. ,  0.8],
+           [ 0.8,  0.8,  0.8],
+           [ 0.2,  0.5,  0.8]])
+    >>> librosa.util.softmask(X, X_ref, power=4)
+    array([[ 1.   ,  1.   ,  0.941],
+           [ 0.941,  0.941,  0.941],
+           [ 0.059,  0.5  ,  0.941]])
+    >>> librosa.util.softmask(X, X_ref, power=100)
+    array([[  1.000e+00,   1.000e+00,   1.000e+00],
+           [  1.000e+00,   1.000e+00,   1.000e+00],
+           [  7.889e-31,   5.000e-01,   1.000e+00]])
+    >>> librosa.util.softmask(X, X_ref, power=np.inf)
+    array([[ True,  True,  True],
+           [ True,  True,  True],
+           [False, False,  True]], dtype=bool)
+    """
+    if X.shape != X_ref.shape:
+        raise ParameterError(f"Shape mismatch: {X.shape}!={X_ref.shape}")
+
+    if np.any(X < 0) or np.any(X_ref < 0):
+        raise ParameterError("X and X_ref must be non-negative")
+
+    if power <= 0:
+        raise ParameterError("power must be strictly positive")
+
+    # We're working with ints, cast to float.
+    dtype = X.dtype
+    if not np.issubdtype(dtype, np.floating):
+        dtype = np.float32
+
+    # Re-scale the input arrays relative to the larger value
+    Z = np.maximum(X, X_ref).astype(dtype)
+    bad_idx = Z < np.finfo(dtype).tiny
+    Z[bad_idx] = 1
+
+    # For finite power, compute the softmask
+    mask: np.ndarray
+
+    if np.isfinite(power):
+        mask = (X / Z) ** power
+        ref_mask = (X_ref / Z) ** power
+        good_idx = ~bad_idx
+        mask[good_idx] /= mask[good_idx] + ref_mask[good_idx]
+        # Wherever energy is below energy in both inputs, split the mask
+        if split_zeros:
+            mask[bad_idx] = 0.5
+        else:
+            mask[bad_idx] = 0.0
+    else:
+        # Otherwise, compute the hard mask
+        mask = X > X_ref
+
+    return mask
+
+
+def tiny(x: Union[float, np.ndarray]) -> _FloatLike_co:
+    """Compute the tiny-value corresponding to an input's data type.
+
+    This is the smallest "usable" number representable in ``x.dtype``
+    (e.g., float32).
+
+    This is primarily useful for determining a threshold for
+    numerical underflow in division or multiplication operations.
+
+    Parameters
+    ----------
+    x : number or np.ndarray
+        The array to compute the tiny-value for.
+        All that matters here is ``x.dtype``
+
+    Returns
+    -------
+    tiny_value : float
+        The smallest positive usable number for the type of ``x``.
+        If ``x`` is integer-typed, then the tiny value for ``np.float32``
+        is returned instead.
+
+    See Also
+    --------
+    numpy.finfo
+
+    Examples
+    --------
+    For a standard double-precision floating point number:
+
+    >>> librosa.util.tiny(1.0)
+    2.2250738585072014e-308
+
+    Or explicitly as double-precision
+
+    >>> librosa.util.tiny(np.asarray(1e-5, dtype=np.float64))
+    2.2250738585072014e-308
+
+    Or complex numbers
+
+    >>> librosa.util.tiny(1j)
+    2.2250738585072014e-308
+
+    Single-precision floating point:
+
+    >>> librosa.util.tiny(np.asarray(1e-5, dtype=np.float32))
+    1.1754944e-38
+
+    Integer
+
+    >>> librosa.util.tiny(5)
+    1.1754944e-38
+    """
+
+    # Make sure we have an array view
+    x = np.asarray(x)
+
+    # Only floating types generate a tiny
+    if np.issubdtype(x.dtype, np.floating) or np.issubdtype(
+        x.dtype, np.complexfloating
+    ):
+        dtype = x.dtype
+    else:
+        dtype = np.dtype(np.float32)
+
+    return np.finfo(dtype).tiny
+
+
+def fill_off_diagonal(x: np.ndarray, *, radius: float, value: float = 0) -> None:
+    """Sets all cells of a matrix to a given ``value``
+    if they lie outside a constraint region.
+
+    In this case, the constraint region is the
+    Sakoe-Chiba band which runs with a fixed ``radius``
+    along the main diagonal.
+
+    When ``x.shape[0] != x.shape[1]``, the radius will be
+    expanded so that ``x[-1, -1] = 1`` always.
+
+    ``x`` will be modified in place.
+
+    Parameters
+    ----------
+    x : np.ndarray [shape=(N, M)]
+        Input matrix, will be modified in place.
+    radius : float
+        The band radius (1/2 of the width) will be
+        ``int(radius*min(x.shape))``
+    value : float
+        ``x[n, m] = value`` when ``(n, m)`` lies outside the band.
+
+    Examples
+    --------
+    >>> x = np.ones((8, 8))
+    >>> librosa.util.fill_off_diagonal(x, radius=0.25)
+    >>> x
+    array([[1, 1, 0, 0, 0, 0, 0, 0],
+           [1, 1, 1, 0, 0, 0, 0, 0],
+           [0, 1, 1, 1, 0, 0, 0, 0],
+           [0, 0, 1, 1, 1, 0, 0, 0],
+           [0, 0, 0, 1, 1, 1, 0, 0],
+           [0, 0, 0, 0, 1, 1, 1, 0],
+           [0, 0, 0, 0, 0, 1, 1, 1],
+           [0, 0, 0, 0, 0, 0, 1, 1]])
+    >>> x = np.ones((8, 12))
+    >>> librosa.util.fill_off_diagonal(x, radius=0.25)
+    >>> x
+    array([[1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0],
+           [1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0],
+           [0, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0],
+           [0, 0, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0],
+           [0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 0, 0],
+           [0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 0],
+           [0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1],
+           [0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1]])
+    """
+    nx, ny = x.shape
+
+    # Calculate the radius in indices, rather than proportion
+    radius = int(np.round(radius * np.min(x.shape)))
+
+    nx, ny = x.shape
+    offset = np.abs((x.shape[0] - x.shape[1]))
+
+    if nx < ny:
+        idx_u = np.triu_indices_from(x, k=radius + offset)
+        idx_l = np.tril_indices_from(x, k=-radius)
+    else:
+        idx_u = np.triu_indices_from(x, k=radius)
+        idx_l = np.tril_indices_from(x, k=-radius - offset)
+
+    # modify input matrix
+    x[idx_u] = value
+    x[idx_l] = value
+
+
+def cyclic_gradient(
+    data: np.ndarray, *, edge_order: Literal[1, 2] = 1, axis: int = -1
+) -> np.ndarray:
+    """Estimate the gradient of a function over a uniformly sampled,
+    periodic domain.
+
+    This is essentially the same as `np.gradient`, except that edge effects
+    are handled by wrapping the observations (i.e. assuming periodicity)
+    rather than extrapolation.
+
+    Parameters
+    ----------
+    data : np.ndarray
+        The function values observed at uniformly spaced positions on
+        a periodic domain
+    edge_order : {1, 2}
+        The order of the difference approximation used for estimating
+        the gradient
+    axis : int
+        The axis along which gradients are calculated.
+
+    Returns
+    -------
+    grad : np.ndarray like ``data``
+        The gradient of ``data`` taken along the specified axis.
+
+    See Also
+    --------
+    numpy.gradient
+
+    Examples
+    --------
+    This example estimates the gradient of cosine (-sine) from 64
+    samples using direct (aperiodic) and periodic gradient
+    calculation.
+
+    >>> import matplotlib.pyplot as plt
+    >>> x = 2 * np.pi * np.linspace(0, 1, num=64, endpoint=False)
+    >>> y = np.cos(x)
+    >>> grad = np.gradient(y)
+    >>> cyclic_grad = librosa.util.cyclic_gradient(y)
+    >>> true_grad = -np.sin(x) * 2 * np.pi / len(x)
+    >>> fig, ax = plt.subplots()
+    >>> ax.plot(x, true_grad, label='True gradient', linewidth=5,
+    ...          alpha=0.35)
+    >>> ax.plot(x, cyclic_grad, label='cyclic_gradient')
+    >>> ax.plot(x, grad, label='np.gradient', linestyle=':')
+    >>> ax.legend()
+    >>> # Zoom into the first part of the sequence
+    >>> ax.set(xlim=[0, np.pi/16], ylim=[-0.025, 0.025])
+    """
+    # Wrap-pad the data along the target axis by `edge_order` on each side
+    padding = [(0, 0)] * data.ndim
+    padding[axis] = (edge_order, edge_order)
+    data_pad = np.pad(data, padding, mode="wrap")
+
+    # Compute the gradient
+    grad = np.gradient(data_pad, edge_order=edge_order, axis=axis)
+
+    # Remove the padding
+    slices = [slice(None)] * data.ndim
+    slices[axis] = slice(edge_order, -edge_order)
+    grad_slice: np.ndarray = grad[tuple(slices)]
+    return grad_slice
+
+
+@numba.jit(nopython=True, cache=False)  # type: ignore
+def __shear_dense(X: np.ndarray, *, factor: int = +1, axis: int = -1) -> np.ndarray:
+    """Numba-accelerated shear for dense (ndarray) arrays"""
+
+    if axis == 0:
+        X = X.T
+
+    X_shear = np.empty_like(X)
+
+    for i in range(X.shape[1]):
+        X_shear[:, i] = np.roll(X[:, i], factor * i)
+
+    if axis == 0:
+        X_shear = X_shear.T
+
+    return X_shear
+
+
+def __shear_sparse(
+    X: scipy.sparse.spmatrix, *, factor: int = +1, axis: int = -1
+) -> scipy.sparse.spmatrix:
+    """Fast shearing for sparse matrices
+
+    Shearing is performed using CSC array indices,
+    and the result is converted back to whatever sparse format
+    the data was originally provided in.
+    """
+    fmt = X.format
+    if axis == 0:
+        X = X.T
+
+    # Now we're definitely rolling on the correct axis
+    X_shear = X.tocsc(copy=True)
+
+    # The idea here is to repeat the shear amount (factor * range)
+    # by the number of non-zeros for each column.
+    # The number of non-zeros is computed by diffing the index pointer array
+    roll = np.repeat(factor * np.arange(X_shear.shape[1]), np.diff(X_shear.indptr))
+
+    # In-place roll
+    np.mod(X_shear.indices + roll, X_shear.shape[0], out=X_shear.indices)
+
+    if axis == 0:
+        X_shear = X_shear.T
+
+    # And convert back to the input format
+    return X_shear.asformat(fmt)
+
+
+_ArrayOrSparseMatrix = TypeVar(
+    "_ArrayOrSparseMatrix", bound=Union[np.ndarray, scipy.sparse.spmatrix]
+)
+
+
+@overload
+def shear(X: np.ndarray, *, factor: int = ..., axis: int = ...) -> np.ndarray:
+    ...
+
+
+@overload
+def shear(
+    X: scipy.sparse.spmatrix, *, factor: int = ..., axis: int = ...
+) -> scipy.sparse.spmatrix:
+    ...
+
+
+def shear(
+    X: _ArrayOrSparseMatrix, *, factor: int = 1, axis: int = -1
+) -> _ArrayOrSparseMatrix:
+    """Shear a matrix by a given factor.
+
+    The column ``X[:, n]`` will be displaced (rolled)
+    by ``factor * n``
+
+    This is primarily useful for converting between lag and recurrence
+    representations: shearing with ``factor=-1`` converts the main diagonal
+    to a horizontal.  Shearing with ``factor=1`` converts a horizontal to
+    a diagonal.
+
+    Parameters
+    ----------
+    X : np.ndarray [ndim=2] or scipy.sparse matrix
+        The array to be sheared
+    factor : integer
+        The shear factor: ``X[:, n] -> np.roll(X[:, n], factor * n)``
+    axis : integer
+        The axis along which to shear
+
+    Returns
+    -------
+    X_shear : same type as ``X``
+        The sheared matrix
+
+    Examples
+    --------
+    >>> E = np.eye(3)
+    >>> librosa.util.shear(E, factor=-1, axis=-1)
+    array([[1., 1., 1.],
+           [0., 0., 0.],
+           [0., 0., 0.]])
+    >>> librosa.util.shear(E, factor=-1, axis=0)
+    array([[1., 0., 0.],
+           [1., 0., 0.],
+           [1., 0., 0.]])
+    >>> librosa.util.shear(E, factor=1, axis=-1)
+    array([[1., 0., 0.],
+           [0., 0., 1.],
+           [0., 1., 0.]])
+    """
+
+    if not np.issubdtype(type(factor), np.integer):
+        raise ParameterError(f"factor={factor} must be integer-valued")
+
+    # Suppress type checks because mypy doesn't like numba jitting
+    # or scipy sparse conversion
+    if scipy.sparse.isspmatrix(X):
+        return __shear_sparse(X, factor=factor, axis=axis)  # type: ignore
+    else:
+        return __shear_dense(X, factor=factor, axis=axis)  # type: ignore
+
+
+def stack(arrays: List[np.ndarray], *, axis: int = 0) -> np.ndarray:
+    """Stack one or more arrays along a target axis.
+
+    This function is similar to `np.stack`, except that memory contiguity is
+    retained when stacking along the first dimension.
+
+    This is useful when combining multiple monophonic audio signals into a
+    multi-channel signal, or when stacking multiple feature representations
+    to form a multi-dimensional array.
+
+    Parameters
+    ----------
+    arrays : list
+        one or more `np.ndarray`
+    axis : integer
+        The target axis along which to stack.  ``axis=0`` creates a new first axis,
+        and ``axis=-1`` creates a new last axis.
+
+    Returns
+    -------
+    arr_stack : np.ndarray [shape=(len(arrays), array_shape) or shape=(array_shape, len(arrays))]
+        The input arrays, stacked along the target dimension.
+
+        If ``axis=0``, then ``arr_stack`` will be F-contiguous.
+        Otherwise, ``arr_stack`` will be C-contiguous by default, as computed by
+        `np.stack`.
+
+    Raises
+    ------
+    ParameterError
+        - If ``arrays`` do not all have the same shape
+        - If no ``arrays`` are given
+
+    See Also
+    --------
+    numpy.stack
+    numpy.ndarray.flags
+    frame
+
+    Examples
+    --------
+    Combine two buffers into a contiguous arrays
+
+    >>> y_left = np.ones(5)
+    >>> y_right = -np.ones(5)
+    >>> y_stereo = librosa.util.stack([y_left, y_right], axis=0)
+    >>> y_stereo
+    array([[ 1.,  1.,  1.,  1.,  1.],
+           [-1., -1., -1., -1., -1.]])
+    >>> y_stereo.flags
+      C_CONTIGUOUS : False
+      F_CONTIGUOUS : True
+      OWNDATA : True
+      WRITEABLE : True
+      ALIGNED : True
+      WRITEBACKIFCOPY : False
+      UPDATEIFCOPY : False
+
+    Or along the trailing axis
+
+    >>> y_stereo = librosa.util.stack([y_left, y_right], axis=-1)
+    >>> y_stereo
+    array([[ 1., -1.],
+           [ 1., -1.],
+           [ 1., -1.],
+           [ 1., -1.],
+           [ 1., -1.]])
+    >>> y_stereo.flags
+      C_CONTIGUOUS : True
+      F_CONTIGUOUS : False
+      OWNDATA : True
+      WRITEABLE : True
+      ALIGNED : True
+      WRITEBACKIFCOPY : False
+      UPDATEIFCOPY : False
+    """
+
+    shapes = {arr.shape for arr in arrays}
+    if len(shapes) > 1:
+        raise ParameterError("all input arrays must have the same shape")
+    elif len(shapes) < 1:
+        raise ParameterError("at least one input array must be provided for stack")
+
+    shape_in = shapes.pop()
+
+    if axis != 0:
+        return np.stack(arrays, axis=axis)
+    else:
+        # If axis is 0, enforce F-ordering
+        shape = tuple([len(arrays)] + list(shape_in))
+
+        # Find the common dtype for all inputs
+        dtype = np.find_common_type([arr.dtype for arr in arrays], [])
+
+        # Allocate an empty array of the right shape and type
+        result = np.empty(shape, dtype=dtype, order="F")
+
+        # Stack into the preallocated buffer
+        np.stack(arrays, axis=axis, out=result)
+
+        return result
+
+
+def dtype_r2c(d: DTypeLike, *, default: Optional[type] = np.complex64) -> DTypeLike:
+    """Find the complex numpy dtype corresponding to a real dtype.
+
+    This is used to maintain numerical precision and memory footprint
+    when constructing complex arrays from real-valued data
+    (e.g. in a Fourier transform).
+
+    A `float32` (single-precision) type maps to `complex64`,
+    while a `float64` (double-precision) maps to `complex128`.
+
+    Parameters
+    ----------
+    d : np.dtype
+        The real-valued dtype to convert to complex.
+        If ``d`` is a complex type already, it will be returned.
+    default : np.dtype, optional
+        The default complex target type, if ``d`` does not match a
+        known dtype
+
+    Returns
+    -------
+    d_c : np.dtype
+        The complex dtype
+
+    See Also
+    --------
+    dtype_c2r
+    numpy.dtype
+
+    Examples
+    --------
+    >>> librosa.util.dtype_r2c(np.float32)
+    dtype('complex64')
+
+    >>> librosa.util.dtype_r2c(np.int16)
+    dtype('complex64')
+
+    >>> librosa.util.dtype_r2c(np.complex128)
+    dtype('complex128')
+    """
+    mapping: Dict[DTypeLike, type] = {
+        np.dtype(np.float32): np.complex64,
+        np.dtype(np.float64): np.complex128,
+        np.dtype(float): np.dtype(complex).type,
+    }
+
+    # If we're given a complex type already, return it
+    dt = np.dtype(d)
+    if dt.kind == "c":
+        return dt
+
+    # Otherwise, try to map the dtype.
+    # If no match is found, return the default.
+    return np.dtype(mapping.get(dt, default))
+
+
+def dtype_c2r(d: DTypeLike, *, default: Optional[type] = np.float32) -> DTypeLike:
+    """Find the real numpy dtype corresponding to a complex dtype.
+
+    This is used to maintain numerical precision and memory footprint
+    when constructing real arrays from complex-valued data
+    (e.g. in an inverse Fourier transform).
+
+    A `complex64` (single-precision) type maps to `float32`,
+    while a `complex128` (double-precision) maps to `float64`.
+
+    Parameters
+    ----------
+    d : np.dtype
+        The complex-valued dtype to convert to real.
+        If ``d`` is a real (float) type already, it will be returned.
+    default : np.dtype, optional
+        The default real target type, if ``d`` does not match a
+        known dtype
+
+    Returns
+    -------
+    d_r : np.dtype
+        The real dtype
+
+    See Also
+    --------
+    dtype_r2c
+    numpy.dtype
+
+    Examples
+    --------
+    >>> librosa.util.dtype_r2c(np.complex64)
+    dtype('float32')
+
+    >>> librosa.util.dtype_r2c(np.float32)
+    dtype('float32')
+
+    >>> librosa.util.dtype_r2c(np.int16)
+    dtype('float32')
+
+    >>> librosa.util.dtype_r2c(np.complex128)
+    dtype('float64')
+    """
+    mapping: Dict[DTypeLike, type] = {
+        np.dtype(np.complex64): np.float32,
+        np.dtype(np.complex128): np.float64,
+        np.dtype(complex): np.dtype(float).type,
+    }
+
+    # If we're given a real type already, return it
+    dt = np.dtype(d)
+    if dt.kind == "f":
+        return dt
+
+    # Otherwise, try to map the dtype.
+    # If no match is found, return the default.
+    return np.dtype(mapping.get(dt, default))
+
+
+@numba.jit(nopython=True, cache=False)
+def __count_unique(x):
+    """Counts the number of unique values in an array.
+
+    This function is a helper for `count_unique` and is not
+    to be called directly.
+    """
+    uniques = np.unique(x)
+    return uniques.shape[0]
+
+
+def count_unique(data: np.ndarray, *, axis: int = -1) -> np.ndarray:
+    """Count the number of unique values in a multi-dimensional array
+    along a given axis.
+
+    Parameters
+    ----------
+    data : np.ndarray
+        The input array
+    axis : int
+        The target axis to count
+
+    Returns
+    -------
+    n_uniques
+        The number of unique values.
+        This array will have one fewer dimension than the input.
+
+    See Also
+    --------
+    is_unique
+
+    Examples
+    --------
+    >>> x = np.vander(np.arange(5))
+    >>> x
+    array([[  0,   0,   0,   0,   1],
+       [  1,   1,   1,   1,   1],
+       [ 16,   8,   4,   2,   1],
+       [ 81,  27,   9,   3,   1],
+       [256,  64,  16,   4,   1]])
+    >>> # Count unique values along rows (within columns)
+    >>> librosa.util.count_unique(x, axis=0)
+    array([5, 5, 5, 5, 1])
+    >>> # Count unique values along columns (within rows)
+    >>> librosa.util.count_unique(x, axis=-1)
+    array([2, 1, 5, 5, 5])
+    """
+    return np.apply_along_axis(__count_unique, axis, data)
+
+
+@numba.jit(nopython=True, cache=False)
+def __is_unique(x):
+    """Determines if the input array has all unique values.
+
+    This function is a helper for `is_unique` and is not
+    to be called directly.
+    """
+
+    uniques = np.unique(x)
+    return uniques.shape[0] == x.size
+
+
+def is_unique(data: np.ndarray, *, axis: int = -1) -> np.ndarray:
+    """Determine if the input array consists of all unique values
+    along a given axis.
+
+    Parameters
+    ----------
+    data : np.ndarray
+        The input array
+    axis : int
+        The target axis
+
+    Returns
+    -------
+    is_unique
+        Array of booleans indicating whether the data is unique along the chosen
+        axis.
+        This array will have one fewer dimension than the input.
+
+    See Also
+    --------
+    count_unique
+
+    Examples
+    --------
+    >>> x = np.vander(np.arange(5))
+    >>> x
+    array([[  0,   0,   0,   0,   1],
+       [  1,   1,   1,   1,   1],
+       [ 16,   8,   4,   2,   1],
+       [ 81,  27,   9,   3,   1],
+       [256,  64,  16,   4,   1]])
+    >>> # Check uniqueness along rows
+    >>> librosa.util.is_unique(x, axis=0)
+    array([ True,  True,  True,  True, False])
+    >>> # Check uniqueness along columns
+    >>> librosa.util.is_unique(x, axis=-1)
+    array([False, False,  True,  True,  True])
+
+    """
+
+    return np.apply_along_axis(__is_unique, axis, data)
+
+
+@numba.vectorize(
+    ["float32(complex64)", "float64(complex128)"], nopython=True, cache=True, identity=0
+)  # type: ignore
+def _cabs2(x: _ComplexLike_co) -> _FloatLike_co:  # pragma: no cover
+    """Helper function for efficiently computing abs2 on complex inputs"""
+    return x.real**2 + x.imag**2
+
+
+_Number = Union[complex, "np.number[Any]"]
+_NumberOrArray = TypeVar("_NumberOrArray", bound=Union[_Number, np.ndarray])
+
+
+def abs2(x: _NumberOrArray, dtype: Optional[DTypeLike] = None) -> _NumberOrArray:
+    """Compute the squared magnitude of a real or complex array.
+
+    This function is equivalent to calling `np.abs(x)**2` but it
+    is slightly more efficient.
+
+    Parameters
+    ----------
+    x : np.ndarray or scalar, real or complex typed
+        The input data, either real (float32, float64) or complex (complex64, complex128) typed
+    dtype : np.dtype, optional
+        The data type of the output array.
+        If not provided, it will be inferred from `x`
+
+    Returns
+    -------
+    p : np.ndarray or scale, real
+        squared magnitude of `x`
+
+    Examples
+    --------
+    >>> librosa.util.abs2(3 + 4j)
+    25.0
+
+    >>> librosa.util.abs2((0.5j)**np.arange(8))
+    array([1.000e+00, 2.500e-01, 6.250e-02, 1.562e-02, 3.906e-03, 9.766e-04,
+       2.441e-04, 6.104e-05])
+    """
+    if np.iscomplexobj(x):
+        # suppress type check, mypy doesn't like vectorization
+        y = _cabs2(x)
+        if dtype is None:
+            return y  # type: ignore
+        else:
+            return y.astype(dtype)  # type: ignore
+    else:
+        # suppress type check, mypy doesn't know this is real
+        return np.power(x, 2, dtype=dtype)  # type: ignore
+
+
+@numba.vectorize(
+    ["complex64(float32)", "complex128(float64)"], nopython=True, cache=False, identity=1
+)  # type: ignore
+def _phasor_angles(x) -> np.complex_:  # pragma: no cover
+    return np.cos(x) + 1j * np.sin(x)  # type: ignore
+
+
+_Real = Union[float, "np.integer[Any]", "np.floating[Any]"]
+
+
+@overload
+def phasor(angles: np.ndarray, *, mag: Optional[np.ndarray] = ...) -> np.ndarray:
+    ...
+
+
+@overload
+def phasor(angles: _Real, *, mag: Optional[_Number] = ...) -> np.complex_:
+    ...
+
+
+def phasor(
+    angles: Union[np.ndarray, _Real],
+    *,
+    mag: Optional[Union[np.ndarray, _Number]] = None,
+) -> Union[np.ndarray, np.complex_]:
+    """Construct a complex phasor representation from angles.
+
+    When `mag` is not provided, this is equivalent to:
+
+        z = np.cos(angles) + 1j * np.sin(angles)
+
+    or by Euler's formula:
+
+        z = np.exp(1j * angles)
+
+    When `mag` is provided, this is equivalent to:
+
+        z = mag * np.exp(1j * angles)
+
+    This function should be more efficient (in time and memory) than the equivalent'
+    formulations above, but produce numerically identical results.
+
+    Parameters
+    ----------
+    angles : np.ndarray or scalar, real-valued
+        Angle(s), measured in radians
+
+    mag : np.ndarray or scalar, optional
+        If provided, phasor(s) will be scaled by `mag`.
+
+        If not provided (default), phasors will have unit magnitude.
+
+        `mag` must be of compatible shape to multiply with `angles`.
+
+    Returns
+    -------
+    z : np.ndarray or scalar, complex-valued
+        Complex number(s) z corresponding to the given angle(s)
+        and optional magnitude(s).
+
+    Examples
+    --------
+    Construct unit phasors at angles 0, pi/2, and pi:
+
+    >>> librosa.util.phasor([0, np.pi/2, np.pi])
+    array([ 1.000e+00+0.000e+00j,  6.123e-17+1.000e+00j,
+           -1.000e+00+1.225e-16j])
+
+    Construct a phasor with magnitude 1/2:
+
+    >>> librosa.util.phasor(np.pi/2, mag=0.5)
+    (3.061616997868383e-17+0.5j)
+
+    Or arrays of angles and magnitudes:
+
+    >>> librosa.util.phasor(np.array([0, np.pi/2]), mag=np.array([0.5, 1.5]))
+    array([5.000e-01+0.j , 9.185e-17+1.5j])
+    """
+    z = _phasor_angles(angles)
+
+    if mag is not None:
+        z *= mag
+
+    return z  # type: ignore