o
    rôj- ã                   @  sþ  d Z ddlmZ ddlZddlZddlZddlZddl	m
Z
 ddlmZ ddlmZ dd	lmZ dd
lmZmZ ddlmZmZmZmZmZmZmZmZmZmZmZ ddl m!Z! ddl"m#Z#m$Z$m%Z% dZ&g d¢Z'ddddœdïdd„Z(edd �eƒ d!œdðd%d&„ƒZ)dd'œdñd+d,„Z*dòd-d.„Z+dód0d1„Z,dd2œdôd7d8„Z-dõd<d=„Z.dd2œdôd>d?„Z/ddd@dAœdödHdI„Z0edJdJdJdKœd÷dQdR„ƒZ1edJdJdSœdødVdR„ƒZ1ddddKœdùdXdR„Z1edYd �ej2ddddZœdúdadb„ƒZ3ej4dcdd„ ƒZ5ej4dedf„ ƒZ6ej7g dg¢dhd@d@di�djdk„ ƒZ8ej7g dg¢dhd@d@di�dldm„ ƒZ9dd2œdûdndo„Z:dd2œdûdpdq„Z;ej7g dr¢dsd@d@dt�dudv„ ƒZ<d@ddwœdüdd€„Z=edYd �d�dd‚œdýd‡dˆ„ƒZ>dej?d‰œdþdŒd�„Z@dddd@dŽœdÿd”d•„ZAedYd �dd@dd–œ�d d™dš„ƒZBddd›œ�dd d¡„ZC�dd¤d¥„ZDdd¦œ�dd©dª„ZEddd«œ�dd®d¯„ZFejGd@d@dt�ddd°œ�dd²d³„ƒZHddd°œ�ddµd¶„ZIed·eejJejKjLf d¸�ZMedJdJd°œ�dd¹dº„ƒZNedJdJd°œ�dd»dº„ƒZNddd°œ�dd¼dº„ZNdd2œ�dd¿dÀ„ZOejPdÁœ�d	dÅdÆ„ZQej?dÁœ�d	dÇdÈ„ZRejGd@d@dt�dÉdÊ„ ƒZSdd2œ�d
dËdÌ„ZTejGd@d@dt�dÍdÎ„ ƒZUdd2œ�d
dÏdÐ„ZVejWdÑdÒgd@d@ddÓ��ddÕdÖ„ƒZXeeYd×f ZZedØeeZejJf d¸�Z[�d�ddÙdÚ„Z\ejWdÛdÜgd@d@ddÓ��ddÞdß„ƒZ]ee^dàdáf Z_edJdâœ�ddædç„ƒZ`edJdâœ�ddêdç„ƒZ`ddâœ�ddîdç„Z`dS (  zUtility functionsé    )ÚannotationsN)Ú
as_stridedé   )Úcacheé   )ÚParameterError)Ú
Deprecated)Ú	ArrayLikeÚ	DTypeLike)ÚAnyÚCallableÚIterableÚListÚDictÚOptionalÚSequenceÚTupleÚTypeVarÚUnionÚoverload)ÚLiteral)Ú_SequenceLikeÚ_FloatLike_coÚ_ComplexLike_coi   )Ú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éÿÿÿÿF)ÚaxisÚ	writeableÚsubokÚxú
np.ndarrayÚframe_lengthÚintÚ
hop_lengthr:   r;   Úboolr<   Úreturnc                C  s   t j| d|d�} | j| |k rtd| j| d›d|d›�ƒ‚|dk r*td|d›�ƒ‚| jt| j| gƒ }t| jƒ}||  |d 8  < t|ƒt|gƒ }t| ||||d�}	|d	k r_|d }
n|d }
t  |	d
|
¡}	t	dƒg|	j
 }t	d	d|ƒ||< |	t|ƒ S )aì  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 ``False``, then the framed view of ``x`` is read-only.
        If ``True``, 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
    F)Úcopyr<   zInput is too short (n=Údz) for frame_length=r   zInvalid hop_length: )ÚstridesÚshaper<   r;   r   r9   N)ÚnpÚarrayrG   r   rF   ÚtupleÚlistr   ÚmoveaxisÚsliceÚndim)r=   r?   rA   r:   r;   r<   Úout_stridesÚx_shape_trimmedÚ	out_shapeZxwZtarget_axisÚslices© rS   úc/var/www/html/academy/tools/voices/clone/sv-venv/lib/python3.10/site-packages/librosa/util/utils.pyr   H   s,    ÿ

ÿ
r   é   )Úlevel)ÚmonoÚyrW   úUnion[bool, Deprecated]c                C  s–   t | tjƒs
tdƒ‚t | jtj¡stdƒ‚| jdkr#td| j› �ƒ‚t |t	ƒr*d}|r>| jdkr>td| jd›d	| j› �ƒ‚t 
| ¡ ¡ sItd
ƒ‚dS )af  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
    z(Audio data must be of type numpy.ndarrayz!Audio data must be floating-pointr   z;Audio data must be at least one-dimensional, given y.shape=Fr   z)Invalid shape for monophonic audio: ndim=rE   z, shape=z%Audio buffer is not finite everywhereT)Ú
isinstancerH   Úndarrayr   Ú
issubdtypeÚdtypeÚfloatingrN   rG   r   ÚisfiniteÚall)rX   rW   rS   rS   rT   r   î   s"   8

ÿ
ÿr   ©ÚcastÚfloatrb   ú"Optional[Callable[[float], float]]c                C  s*   |du rt j}t|ƒstdƒ‚t|| ƒƒS )aî  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.
    Nzcast parameter must be callable)rH   ÚfloorÚcallabler   r@   )r=   rb   rS   rS   rT   r    ?  s
   r    c                 C  s   t | ttjfƒo| dkS )z–Check that x is a positive integer, i.e. 1 or greater.

    Parameters
    ----------
    x : number

    Returns
    -------
    positive : bool
    r   )rZ   r@   rH   Úinteger©r=   rS   rS   rT   r!   _  s   r!   Ú	intervalsc                 C  sZ   | j dks| jd dkrtdƒ‚t | dd…df | dd…df k¡r+td| › d�ƒ‚d	S )
a€  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.
    r   r9   z intervals must have shape (n, 2)Nr   r   z
intervals=z! must have non-negative durationsT)rN   rG   r   rH   Úany)ri   rS   rS   rT   r"   n  s
   &r"   ©r:   ÚdataÚsizeÚkwargsr   c                K  s€   |  dd¡ | j| }t|| d ƒ}dg| j }|t|| | ƒf||< |dk r6td|d›d|d›d	�ƒ‚tj| |fi |¤ŽS )
a(  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
    ÚmodeÚconstantr   ©r   r   r   zTarget size (rE   z) must be at least input size (ú))Ú
setdefaultrG   r@   rN   r   rH   Úpad)rl   rm   r:   rn   ÚnZlpadÚlengthsrS   rS   rT   r   ˆ  s   9
ÿr   rN   Úaxesú1Union[int, slice, Sequence[int], Sequence[slice]]c                C  s¢   zt |ƒ}W n ty   t |gƒ}Y nw t|ƒ| jkr'td|› d| j› �ƒ‚|| jk r7td| j› d|› �ƒ‚dg| }t|ƒD ]\}}| j| ||< q@|  |¡S )a  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)
    zShape mismatch between axes=z and input x.shape=zCannot expand x.shape=z to fewer dimensions ndim=r   )rJ   Ú	TypeErrorÚlenrN   r   rG   Ú	enumerateÚreshape)r=   rN   rw   Zaxes_tuprG   ÚiZaxirS   rS   rT   r   Ò  s"   1ÿÿ
ÿ

r   c                K  s„   |  dd¡ | j| }||kr$tdƒg| j }td|ƒ||< | t|ƒ S ||k r@dg| j }d|| f||< tj| |fi |¤ŽS | S )am  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
    ro   rp   Nr   rq   )rs   rG   rM   rN   rJ   rH   rt   )rl   rm   r:   rn   ru   rR   rv   rS   rS   rT   r     s   *
r   T©Úx_minÚx_maxrt   Úframesú_SequenceLike[int]r   úOptional[int]r€   rt   c                C  s¾   t  | ¡} t  | dk ¡rtdƒ‚|r!|dus|dur!t  | ||¡} |rAg }|dur.| |¡ |dur7| |¡ t  t  |¡| f¡} |durK| | |k } |durU| | |k } t  | ¡ t	¡}|S )av  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
    r   zNegative frame index detectedN)
rH   Úasarrayrj   r   ÚclipÚappendÚconcatenateÚuniqueÚastyper@   )r�   r   r€   rt   Zpad_datarˆ   rS   rS   rT   r#   T  s$   
=

r#   .)r:   ÚindexÚvalueÚSrŠ   úLiteral[False]r‹   úOptional[Callable[..., Any]]c                C  ó   d S ©NrS   ©rŒ   r:   rŠ   r‹   rS   rS   rT   r$   ­  ó   r$   )r:   r‹   úLiteral[True]úTuple[np.ndarray, np.ndarray]c                C  r�   r�   rS   r‘   rS   rS   rT   r$   ¸  r’   ú0Union[np.ndarray, Tuple[np.ndarray, np.ndarray]]c                C  s|   |du rt j}| jdkrtdƒ‚|| t  d| | j¡d�}t  |¡}tdƒg| j }|||< |r8| t|ƒ |fS | t|ƒ S )a6
  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``)
    Nr   z'axis_sort is only defined for 2D arraysr   rk   )rH   ÚargmaxrN   r   ÚmodÚargsortrM   rJ   )rŒ   r:   rŠ   r‹   Zbin_idxÚidxZ
sort_slicerS   rS   rT   r$   Ã  s   R

é(   )Únormr:   Ú	thresholdÚfillr›   úOptional[float]rœ   úOptional[_FloatLike_co]r�   úOptional[bool]c          
      C  sÞ  |du r	t | ƒ}n|dkrtd|› d�ƒ‚|dvr!td|› d�ƒ‚t t | ¡¡s-tdƒ‚t | ¡ t¡}d	}|du r=| S |tjkrKtj	||d
d�}nb|tj krZtj
||d
d�}nS|dkrs|d
u rftdƒ‚tj|dk|d
|jd�}n:t t|ƒtj¡r¤|dkr¤tj|| |d
d�d|  }|du rš|jd|  }n|j| d|  }n	tdt|ƒ› �ƒ‚||k }t | ¡}	|du rÈd||< | | |	dd…< |	S |ràtj||< | | |	dd…< ||	t |	¡< |	S tj||< | | |	dd…< |	S )až  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 ]])
    Nr   z
threshold=z must be strictly positive)NFTzfill=z must be None or booleanzInput must be finiter   T©r:   Úkeepdimsz*Cannot normalize with norm=0 and fill=True)r:   r¢   r]   ç      ð?g      ð¿zUnsupported norm: )r1   r   rH   r`   r_   Úabsr‰   rc   ÚinfÚmaxÚminÚsumr]   r\   ÚtypeÚnumberrm   rG   ÚreprÚ
empty_likeÚnanÚisnan)
rŒ   r›   r:   rœ   r�   ÚmagZ	fill_normÚlengthZ	small_idxZSnormrS   rS   rT   r'   '  sR    $


ó

ýr'   c                 C  s    | d | d k| d | d k@ S )z*Numba stencil for local maxima computationr   r9   r   rS   rh   rS   rS   rT   Ú_localmax_sten  ó    r±   c                 C  s    | d | d k | d | d k@ S )z*Numba stencil for local minima computationr   r9   r   rS   rh   rS   rS   rT   Ú_localmin_sten  r²   r³   )zvoid(int16[:], bool_[:])zvoid(int32[:], bool_[:])zvoid(int64[:], bool_[:])zvoid(float32[:], bool_[:])zvoid(float64[:], bool_[:])z(n)->(n))r   Únopythonc                 C  ó   t | ƒ|dd…< dS )z+Vectorized wrapper for the localmax stencilN)r±   ©r=   rX   rS   rS   rT   Ú	_localmax  ó   r·   c                 C  rµ   )z+Vectorized wrapper for the localmin stencilN)r³   r¶   rS   rS   rT   Ú	_localmin,  r¸   r¹   c                C  sH   |   d|¡}tj| td�}|  d|¡}t||ƒ |d |d k|d< |S )aÙ  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
    r9   ©r]   ©.r9   ©.éþÿÿÿ)ÚswapaxesrH   r¬   rB   r·   )r=   r:   ÚxiÚlmaxZlmaxirS   rS   rT   r%   =  s   .
r%   c                C  sH   |   d|¡}tj| td�}|  d|¡}t||ƒ |d |d k |d< |S )a¶  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
    r9   rº   r»   r¼   )r¾   rH   r¬   rB   r¹   )r=   r:   r¿   ÚlminZlminirS   rS   rT   r&   z  s   /
r&   )zKvoid(float32[:], uint32, uint32, uint32, uint32, float32, uint32, bool_[:])zKvoid(float64[:], uint32, uint32, uint32, uint32, float32, uint32, bool_[:])zIvoid(int32[:], uint32, uint32, uint32, uint32, float32, uint32, bool_[:])zIvoid(int64[:], uint32, uint32, uint32, uint32, float32, uint32, bool_[:])z(n),(),(),(),(),(),()->(n))r´   r   c                 C  sN  | d t  | dt|| jd ƒ… ¡k|d< |d  | d t  | dt|| jd ƒ… ¡| kM  < |d r9|d }nd}|| jd k r¥t  | td|| ƒt|| | jd ƒ… ¡}	| | |	k||< || si|d7 }q;t  | td|| ƒt|| | jd ƒ… ¡}
||  | | |
| kM  < || s–|d7 }q;||d 7 }|| jd k sBdS dS )z&Vectorized wrapper for the peak-pickerr   Nr   )rH   r¦   r§   rG   Úmean)r=   Úpre_maxÚpost_maxÚpre_avgÚpost_avgÚdeltaÚwaitÚpeaksru   ÚmaxnZavgnrS   rS   rT   Ú__peak_pick¹  s$   *6
,,îrË   )Úsparser:   rÃ   rÄ   rÅ   rÆ   rÇ   rÈ   rÌ   c          
      C  s  |dk rt dƒ‚|dk rt dƒ‚|dk rt dƒ‚|dk r t dƒ‚|dkr(t dƒ‚|dkr0t dƒ‚|r@| jdkr@t d	| j› d
�ƒ‚t|tjd�}t|tjd�}t|tjd�}t|tjd�}t|tjd�}tj| td�}	t|  |d¡|||||||	 |d¡ƒ |r„t 	|	¡S |	S )aÂ  Use 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
        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
    sparse : bool [scalar]
        If `True`, the output are indices of detected peaks.
        If `False`, the output is a dense boolean array of the same
        shape as ``x``.
    axis : int [scalar]
        the axis over which to detect peaks.

    Returns
    -------
    peaks : np.ndarray [shape=(n_peaks,) or shape=x.shape, dtype=int or bool]
        indices of peaks in ``x`` (sparse=True)
        or a boolean array where `peaks[..., n]` indicates a peak at frame index `n` (sparse=False)

    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])

    Using dense output to make a boolean array of peak indicators
    >>> librosa.util.peak_pick(onset_env, pre_max=3, post_max=3, pre_avg=3, post_avg=5,
    ...                        delta=0.5, wait=10, sparse=False)
    array([False, False, ..., False, False])

    >>> 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()
    r   zpre_max must be non-negativezpre_avg must be non-negativezdelta must be non-negativezwait must be non-negativezpost_max must be positivezpost_avg must be positiver   z'sparse=True (default) does not support zU-dimensional inputs. Either set sparse=False or process each dimension independently.ra   rº   r9   )
r   rN   r    rH   ÚceilÚ
zeros_likerB   rË   r¾   Úflatnonzero)
r=   rÃ   rÄ   rÅ   rÆ   rÇ   rÈ   rÌ   r:   rÉ   rS   rS   rT   r(   â  s4   ]
ÿ&
r(   g{®Gáz„?)Úquantiler]   rÐ   r]   úOptional[DTypeLike]úscipy.sparse.csr_matrixc                C  s  | j dkr|  d¡} n| j dkrtd| j› d�ƒ‚d|  kr#dk s,n td|d›�ƒ‚|d	u r3| j}tjj| j|d
�}t 	| ¡}tj
|ddd�}tj|dd�}tj|| dd�}tj||k dd�}t|ƒD ]\}	}
t ||	 ||	|
f k¡}| |	|f ||	|f< qf| ¡ S )a~	  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.   ]])
    r   )r   r9   r   z8Input must have 2 or fewer dimensions. Provided x.shape=Ú.ç        zInvalid quantile z.2fNrº   Tr¡   rk   )rN   r|   r   rG   r]   ÚscipyrÌ   Z
lil_matrixrH   r¤   r¨   ÚsortÚcumsumÚargminr{   ÚwhereZtocsr)r=   rÐ   r]   Zx_sparseZmagsÚnormsZmag_sortZcumulative_magZthreshold_idxr}   Újr™   rS   rS   rT   r)   `  s(   
D
ÿ
r)   )Ún_bytesr]   rÜ   r
   c                C  s:   dt dd| d > ƒ }d|d›�}|t | |¡ |¡ S )a  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
    r£   r   é   z<irE   )rc   rH   Ú
frombufferr‰   )r=   rÜ   r]   ÚscaleÚfmtrS   rS   rT   r0   Ã  s   r0   )Úidx_minÚidx_maxÚsteprt   r™   rá   râ   rã   úList[slice]c                  s0   t | |||d�}‡ fdd„t||dd… ƒD ƒS )aK  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)]
    r~   c                   s   g | ]
\}}t ||ˆ ƒ‘qS rS   )rM   )Ú.0ÚstartÚend©rã   rS   rT   Ú
<listcomp>  s    z"index_to_slice.<locals>.<listcomp>r   N)r#   Úzip)r™   rá   râ   rã   rt   Z	idx_fixedrS   rè   rT   r-   â  s   4 r-   )Ú	aggregatert   r:   ú%Union[Sequence[int], Sequence[slice]]rë   c                C  s  |du rt j}t| jƒ}t  dd„ |D ƒ¡r|}nt  dd„ |D ƒ¡r1tt  |¡d|| |d�}ntd|› �ƒ‚t|ƒ}t|ƒ||< t j	|t  
| ¡rLdnd	| jd
�}tdƒg| j }	tdƒg|j }
t|ƒD ]\}}||	|< ||
|< || t|	ƒ |d�|t|
ƒ< qf|S )aÑ  Aggregate a multi-dimensional array between specified 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))
    Nc                 S  s   g | ]}t |tƒ‘qS rS   )rZ   rM   ©rå   Ú_rS   rS   rT   ré   ƒ  s    zsync.<locals>.<listcomp>c                 S  s   g | ]}t  t|ƒt j¡‘qS rS   )rH   r\   r©   rg   rí   rS   rS   rT   ré   …  s    r   )rá   râ   rt   zInvalid index set: ÚFÚC)Úorderr]   rk   )rH   rÂ   rK   rG   r`   r-   r„   r   rz   ÚemptyÚ	isfortranr]   rM   rN   r{   rJ   )rl   r™   rë   rt   r:   rG   rR   Z	agg_shapeZdata_aggZidx_inZidx_aggr}   ÚsegmentrS   rS   rT   r.     s,   b
ÿÿr.   )ÚpowerÚsplit_zerosÚXÚX_refrõ   rö   c          
      C  s  | j |j krtd| j › d|j › �ƒ‚t | dk ¡s t |dk ¡r$tdƒ‚|dkr,tdƒ‚| j}t |tj¡s9tj}t | |¡ 	|¡}|t 
|¡jk }d||< t |¡r~| | | }|| | }| }	||	  ||	 ||	    < |rxd||< |S d||< |S | |k}|S )	au	  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)
    zShape mismatch: z!=r   z X and X_ref must be non-negativezpower must be strictly positiver   g      à?rÔ   )rG   r   rH   rj   r]   r\   r^   Úfloat32Úmaximumr‰   Úfinfor1   r_   )
r÷   rø   rõ   rö   r]   ÚZZbad_idxÚmaskZref_maskZgood_idxrS   rS   rT   r/   ž  s0   O
ûþr/   úUnion[float, np.ndarray]r   c                 C  sJ   t  | ¡} t  | jt j¡st  | jt j¡r| j}nt  t j¡}t  |¡jS )aØ  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
    )	rH   r„   r\   r]   r^   Úcomplexfloatingrù   rû   r1   )r=   r]   rS   rS   rT   r1     s   
6ÿr1   )r‹   ÚradiusÚNonec                C  sª   | j \}}tt |t | j ¡ ¡ƒ}| j \}}t | j d | j d  ¡}||k r:tj| || d�}tj| | d�}ntj| |d�}tj| | | d�}|| |< || |< dS )a/  Set 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]])
    r   r   )ÚkN)rG   r@   rH   Úroundr§   r¤   Útriu_indices_fromÚtril_indices_from)r=   r   r‹   ÚnxÚnyÚoffsetZidx_uZidx_lrS   rS   rT   r,   W  s   
0
r,   ©Ú
edge_orderr:   r
  úLiteral[1, 2]c                C  sh   dg| j  }||f||< tj| |dd�}tj|||d�}tdƒg| j  }t|| ƒ||< |t|ƒ }|S )a.  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])
    rq   Úwrap)ro   r	  N)rN   rH   rt   ÚgradientrM   rJ   )rl   r
  r:   ÚpaddingZdata_padÚgradrR   Z
grad_slicerS   rS   rT   r2   ›  s   4r2   ©Úfactorr:   r  c                C  sf   |dkr| j } t | ¡}t| jd ƒD ]}t | dd…|f || ¡|dd…|f< q|dkr1|j }|S )z2Numba-accelerated shear for dense (ndarray) arraysr   r   N)ÚTrH   r¬   ÚrangerG   Úroll)r÷   r  r:   ÚX_shearr}   rS   rS   rT   Ú__shear_denseÝ  s   
*r  úscipy.sparse.spmatrixc                C  sz   | j }|dkr
| j} | jdd�}t |t |jd ¡ t |j¡¡}tj	|j
| |jd |j
d� |dkr8|j}| |¡S )zÂ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.
    r   T)rD   r   )Úout)Úformatr  ZtocscrH   ÚrepeatÚarangerG   ÚdiffZindptrr—   ÚindicesZasformat)r÷   r  r:   rà   r  r  rS   rS   rT   Ú__shear_sparseî  s   	$
r  Ú_ArrayOrSparseMatrix)Úboundc                C  r�   r�   rS   ©r÷   r  r:   rS   rS   rT   r*     ó   r*   c                C  r�   r�   rS   r!  rS   rS   rT   r*     s   c                C  sJ   t  t|ƒt j¡std|› d�ƒ‚tj | ¡rt| ||d�S t	| ||d�S )ae  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.]])
    zfactor=z must be integer-valuedr  )
rH   r\   r©   rg   r   rÕ   rÌ   Z
isspmatrixr  r  r!  rS   rS   rT   r*     s
   +ÚarraysúList[np.ndarray]c                C  s˜   dd„ | D ƒ}t |ƒdkrtdƒ‚t |ƒdk rtdƒ‚| ¡ }|dkr*tj| |d�S tt | ƒgt|ƒ ƒ}tj| Ž }tj||dd	�}tj| ||d
� |S )a+  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
    c                 S  s   h | ]}|j ’qS rS   )rG   )rå   ÚarrrS   rS   rT   Ú	<setcomp>   s    zstack.<locals>.<setcomp>r   z)all input arrays must have the same shapez3at least one input array must be provided for stackr   rk   rï   )r]   rñ   )r:   r  )	rz   r   ÚpoprH   r+   rJ   rK   Úresult_typerò   )r#  r:   ÚshapesZshape_inrG   r]   ÚresultrS   rS   rT   r+   T  s   L
r+   )ÚdefaultrE   r+  úOptional[type]c                C  ó\   t  t j¡t jt  t j¡t jt  t¡t  t¡ji}t  | ¡}|j	dkr%|S t  | 
||¡¡S )aä  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')
    Úc)rH   r]   rù   Ú	complex64Úfloat64Ú
complex128rc   Úcomplexr©   ÚkindÚget©rE   r+  ÚmappingÚdtrS   rS   rT   r3   º  s   )ý

r3   c                C  r-  )a(  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')
    Úf)rH   r]   r/  rù   r1  r0  r2  rc   r©   r3  r4  r5  rS   rS   rT   r4   ò  s   ,ý

r4   c                 C  s   t  | ¡}|jd S )z‹Count the number of unique values in an array.

    This function is a helper for `count_unique` and is not
    to be called directly.
    r   )rH   rˆ   rG   ©r=   ZuniquesrS   rS   rT   Ú__count_unique-	  s   

r:  c                C  ó   t  t|| ¡S )a‹  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])
    )rH   Úapply_along_axisr:  ©rl   r:   rS   rS   rT   r5   8	  s   %r5   c                 C  s   t  | ¡}|jd | jkS )z�Determine if the input array has all unique values.

    This function is a helper for `is_unique` and is not
    to be called directly.
    r   )rH   rˆ   rG   rm   r9  rS   rS   rT   Ú__is_unique`	  s   
r>  c                C  r;  )a¸  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])
    )rH   r<  r>  r=  rS   rS   rT   r6   k	  s   &r6   zfloat32(complex64)zfloat64(complex128))r´   r   Úidentityr   c                 C  s   | j d | jd  S )z*Efficiently compute abs2 on complex inputsr   )ÚrealÚimagrh   rS   rS   rT   Ú_cabs2”	  s   rB  znp.number[Any]Ú_NumberOrArrayc                 C  s8   t  | ¡rt| ƒ}|du r|S | |¡S t j| d|d�S )a  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])
    Nr   rº   )rH   ÚiscomplexobjrB  r‰   rõ   )r=   r]   rX   rS   rS   rT   r7    	  s   

r7   zcomplex64(float32)zcomplex128(float64)únp.complex_c                 C  s   t  | ¡dt  | ¡  S )Ny              ð?)rH   ÚcosÚsinrh   rS   rS   rT   Ú_phasor_anglesÈ	  s   rH  znp.integer[Any]znp.floating[Any])r¯   Úanglesr¯   úOptional[np.ndarray]c                C  r�   r�   rS   ©rI  r¯   rS   rS   rT   r8   Ò	  r"  r8   Ú_RealúOptional[_Number]c                C  r�   r�   rS   rK  rS   rS   rT   r8   ×	  r"  úUnion[np.ndarray, _Real]ú$Optional[Union[np.ndarray, _Number]]úUnion[np.ndarray, np.complex_]c                C  s   t | ƒ}|dur||9 }|S )aà  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])
    N)rH  )rI  r¯   ÚzrS   rS   rT   r8   Ü	  s   :)r=   r>   r?   r@   rA   r@   r:   r@   r;   rB   r<   rB   rC   r>   )rX   r>   rW   rY   rC   rB   )r=   rc   rb   rd   rC   r@   )r=   rc   rC   rB   )ri   r>   rC   rB   )
rl   r>   rm   r@   r:   r@   rn   r   rC   r>   )r=   r>   rN   r@   rw   rx   rC   r>   )
r�   r‚   r   rƒ   r€   rƒ   rt   rB   rC   r>   )
rŒ   r>   r:   r@   rŠ   r�   r‹   rŽ   rC   r>   )
rŒ   r>   r:   r@   rŠ   r“   r‹   rŽ   rC   r”   )
rŒ   r>   r:   r@   rŠ   rB   r‹   rŽ   rC   r•   )rŒ   r>   r›   rž   r:   rƒ   rœ   rŸ   r�   r    rC   r>   )r=   r>   r:   r@   rC   r>   )r=   r>   rÃ   r@   rÄ   r@   rÅ   r@   rÆ   r@   rÇ   rc   rÈ   r@   rÌ   rB   r:   r@   rC   r>   )r=   r>   rÐ   rc   r]   rÑ   rC   rÒ   )r=   r>   rÜ   r@   r]   r
   rC   r>   )r™   r‚   rá   rƒ   râ   rƒ   rã   rƒ   rt   rB   rC   rä   )rl   r>   r™   rì   rë   rŽ   rt   rB   r:   r@   rC   r>   )
r÷   r>   rø   r>   rõ   rc   rö   rB   rC   r>   )r=   rþ   rC   r   )r=   r>   r   rc   r‹   rc   rC   r  )rl   r>   r
  r  r:   r@   rC   r>   )r÷   r>   r  r@   r:   r@   rC   r>   )r÷   r  r  r@   r:   r@   rC   r  )r÷   r  r  r@   r:   r@   rC   r  )r#  r$  r:   r@   rC   r>   )rE   r
   r+  r,  rC   r
   )rl   r>   r:   r@   rC   r>   )r=   r   rC   r   r�   )r=   rC  r]   rÑ   rC   rC  )rC   rE  )rI  r>   r¯   rJ  rC   r>   )rI  rL  r¯   rM  rC   rE  )rI  rN  r¯   rO  rC   rP  )aÚ__doc__Ú
__future__r   Zscipy.ndimagerÕ   Zscipy.sparseÚnumpyrH   ÚnumbaÚnumpy.lib.stride_tricksr   Ú_cacher   Ú
exceptionsr   Údeprecationr   Znumpy.typingr	   r
   Útypingr   r   r   r   r   r   r   r   r   r   r   Útyping_extensionsr   Ú_typingr   r   r   r   Ú__all__r   r   r    r!   r"   r   r   r   r#   r$   r¥   r'   Zstencilr±   r³   Zguvectorizer·   r¹   r%   r&   rË   r(   r)   rù   r0   r-   r.   r/   r1   r,   r2   Újitr  r  r[   rÌ   Zspmatrixr  r*   r+   r/  r3   r4   r:  r5   r>  r6   Ú	vectorizerB  r2  Z_NumberrC  r7   rH  rc   rL  r8   rS   rS   rS   rT   Ú<module>   s&  4(ù 'P
 
ÿ
JHÿ>ûYû
ûûdú h

ö
ö
=?ø
	)ö~ÿcÿ"ú:ú ÿvCEÿBÿÿÿÿ6f8;

(

)ÿ(ÿý