U
    %d:                    @   s  d dl Z d dlZd dlZd dlmZ d dlmZmZmZm	Z	 d dl
Z
d dlZd dl
mZ d dlmZ dddd	d
dddddddd
dddddddddddddddd d!d"gZdeeeeeeee eeeeee ed%d&dZdeee eeeeeeeeeed'd(dZe
jd)d*d+Zeeeeeeeeee eed,d-dZdeeeeee ed.d/d	Zeeeed0d1d
Zdeeed3d4d5Zdeeed6d7d8Zeeed9d:d;Zdeeeeeee eed<d=dZeeeeeed>d?dZ eeee ed@dAdZ!eeedBdCdZ"eeedDdEdZ#eeeedFdGdZ$eeeedHdIdJZ%deeeeeedLdMdZ&deeeeeedNdOdZ'deeeedRdSdZ(eeeeedTdUdVZ)deeef eeef eeeef dXdYdZZ*eeeed[d\d]Z+eeed^d_d`Z,deeeeeeededfdZ-deeeeeedjdkdZ.eeeeeeeedldmdZ/e0 deeeeee ee ee edndodZ1e2 de
jeeeeeeeeeeeeeeeeeee
jd{d|dZ3d}dWd~de
4ddfeeeeeeee e
j4ee
j d	ddZ5eeeeeedddZ6deeeeeeee edddZ7e
j8j9eeedddZ:deeeeeee ee ee ed	ddZ;deeeeee ee ee edddZ<ee	e edddZ=deeeeeeedddZ>deee eeedddZ?de
jeee
jdddZ@de
jeee
jdddZAe
je
jddddZBdeeeeef eeeedddZCdeeeeeef  eeeedddZDeeddd ZEdeeeeef eeeeddd!ZFeeeddd"ZGdS )    N)Sequence)OptionalTupleUnionList)Tensor)module_utilsspectrograminverse_spectrogram
griffinlimamplitude_to_DBDB_to_amplitudecompute_deltascompute_kaldi_pitchmelscale_fbankslinear_fbanks
create_dctdetect_pitch_frequencymu_law_encodingmu_law_decodingphase_vocodermask_along_axismask_along_axis_iidsliding_window_cmnspectral_centroidapply_codecresampleedit_distancepitch_shift	rnnt_losspsdmvdr_weights_soudenmvdr_weights_rtfrtf_evd	rtf_powerapply_beamformingTreflect)waveformpadwindown_fft
hop_length
win_lengthpower
normalizedcenterpad_modeonesidedreturn_complexreturnc                 C   s   |dk	rt d |dkr0tjj| ||fd} |  }| d|d } tj| ||||||	d|
dd
}||dd |j	d	d  }|r||
d
   }|dk	r|dkr| S | 
|S |S )a-  Create a spectrogram or a batch of spectrograms from a raw audio signal.
    The spectrogram can be either magnitude-only or complex.

    .. devices:: CPU CUDA

    .. properties:: Autograd TorchScript

    Args:
        waveform (Tensor): Tensor of audio of dimension `(..., time)`
        pad (int): Two sided padding of signal
        window (Tensor): Window tensor that is applied/multiplied to each frame/window
        n_fft (int): Size of FFT
        hop_length (int): Length of hop between STFT windows
        win_length (int): Window size
        power (float or None): Exponent for the magnitude spectrogram,
            (must be > 0) e.g., 1 for energy, 2 for power, etc.
            If None, then the complex spectrum is returned instead.
        normalized (bool): Whether to normalize by magnitude after stft
        center (bool, optional): whether to pad :attr:`waveform` on both sides so
            that the :math:`t`-th frame is centered at time :math:`t \times \text{hop\_length}`.
            Default: ``True``
        pad_mode (string, optional): controls the padding method used when
            :attr:`center` is ``True``. Default: ``"reflect"``
        onesided (bool, optional): controls whether to return half of results to
            avoid redundancy. Default: ``True``
        return_complex (bool, optional):
            Deprecated and not used.

    Returns:
        Tensor: Dimension `(..., freq, time)`, freq is
        ``n_fft // 2 + 1`` and ``n_fft`` is the number of
        Fourier bins, and time is the number of window hops (n_frame).
    Nz`return_complex` argument is now deprecated and is not effective.`torchaudio.functional.spectrogram(power=None)` always returns a tensor with complex dtype. Please remove the argument in the function call.r   constantFT
inputr*   r+   r,   r)   r/   r0   r.   r1   r2          @      ?)warningswarntorchnn
functionalr(   sizereshapestftshapepowsumsqrtabs)r'   r(   r)   r*   r+   r,   r-   r.   r/   r0   r1   r2   rC   spec_f rI   D/tmp/pip-unpacked-wheel-lbdmvq91/torchaudio/functional/functional.pyr	   1   s8    / )r	   lengthr(   r)   r*   r+   r,   r.   r/   r0   r1   r3   c                 C   s   |   std|r*| |d   } |  }| d|d |d } tj| |||||d|
|dk	rp|d|  nddd
}|dk	r|d	kr|dd|| f }||dd |j	dd  }|S )
a  Create an inverse spectrogram or a batch of inverse spectrograms from the provided
    complex-valued spectrogram.

    .. devices:: CPU CUDA

    .. properties:: Autograd TorchScript

    Args:
        spectrogram (Tensor): Complex tensor of audio of dimension (..., freq, time).
        length (int or None): The output length of the waveform.
        pad (int): Two sided padding of signal. It is only effective when ``length`` is provided.
        window (Tensor): Window tensor that is applied/multiplied to each frame/window
        n_fft (int): Size of FFT
        hop_length (int): Length of hop between STFT windows
        win_length (int): Window size
        normalized (bool): Whether the stft output was normalized by magnitude
        center (bool, optional): whether the waveform was padded on both sides so
            that the :math:`t`-th frame is centered at time :math:`t \times \text{hop\_length}`.
            Default: ``True``
        pad_mode (string, optional): controls the padding method used when
            :attr:`center` is ``True``. This parameter is provided for compatibility with the
            spectrogram function and is not used. Default: ``"reflect"``
        onesided (bool, optional): controls whether spectrogram was done in onesided mode.
            Default: ``True``

    Returns:
        Tensor: Dimension `(..., time)`. Least squares estimation of the original signal.
    z+Expected `spectrogram` to be complex dtype.r9   r5   r8   FN   )
r7   r*   r+   r,   r)   r/   r.   r1   rK   r2   r   )

is_complex
ValueErrorrD   rE   rF   r@   rA   r=   istftrC   )r	   rK   r(   r)   r*   r+   r,   r.   r/   r0   r1   rC   r'   rI   rI   rJ   r
      s,    * 
real_dtypec                 C   sB   | t jkrt jS | t jkr t jS | t jkr0t jS td|  d S )NzUnexpected dtype )r=   doubleZcdoublefloatZcfloathalfZ	complex32rN   rP   rI   rI   rJ   _get_complex_dtype   s    


rU   )specgramr)   r*   r+   r,   r-   n_itermomentumrK   	rand_initr3   c
                 C   sn  |dk st d||dks,t d||  }
| dgt|
dd  } | d| } |	rtj|  t| j	| j
d}ntj|  dt| j	| j
d}tjd	| j	| j
d}t|D ]t}tj| | |||||d
}tj|||||dddddd
}|}|r|||d|   }|| d}|}qtj| | |||||d
}||
dd |jdd  }|S )a  Compute waveform from a linear scale magnitude spectrogram using the Griffin-Lim transformation.

    .. devices:: CPU CUDA

    .. properties:: Autograd TorchScript

    Implementation ported from
    *librosa* [:footcite:`brian_mcfee-proc-scipy-2015`], *A fast Griffin-Lim algorithm* [:footcite:`6701851`]
    and *Signal estimation from modified short-time Fourier transform* [:footcite:`1172092`].

    Args:
        specgram (Tensor): A magnitude-only STFT spectrogram of dimension `(..., freq, frames)`
            where freq is ``n_fft // 2 + 1``.
        window (Tensor): Window tensor that is applied/multiplied to each frame/window
        n_fft (int): Size of FFT, creates ``n_fft // 2 + 1`` bins
        hop_length (int): Length of hop between STFT windows. (
            Default: ``win_length // 2``)
        win_length (int): Window size. (Default: ``n_fft``)
        power (float): Exponent for the magnitude spectrogram,
            (must be > 0) e.g., 1 for energy, 2 for power, etc.
        n_iter (int): Number of iteration for phase recovery process.
        momentum (float): The momentum parameter for fast Griffin-Lim.
            Setting this to 0 recovers the original Griffin-Lim method.
            Values near 1 can lead to faster convergence, but above 1 may not converge.
        length (int or None): Array length of the expected output.
        rand_init (bool): Initializes phase randomly if True, to zero otherwise.

    Returns:
        Tensor: waveform of `(..., time)`, where time equals the ``length`` parameter if given.
       zmomentum={} > 1 can be unstabler   zmomentum={} < 0r5   r8   Ndtypedevice        r*   r+   r,   r)   rK   Tr&   Fr6   gؗҜ<)AssertionErrorformatr@   rA   listrD   r=   randrU   r\   r]   fulltensorrangerO   rB   mul_divrG   addrC   )rV   r)   r*   r+   r,   r-   rW   rX   rK   rY   rC   ZanglesZtprev_ZinverseZrebuiltr'   rI   rI   rJ   r      sZ    *           )x
multiplieramindb_multipliertop_dbr3   c              	   C   s   |t t j| |d }||| 8 }|dk	r| }| dkrH|d nd}|d||d |d }t ||jdd	| dddd}||}|S )
a  Turn a spectrogram from the power/amplitude scale to the decibel scale.

    .. devices:: CPU CUDA

    .. properties:: Autograd TorchScript

    The output of each tensor in a batch depends on the maximum value of that tensor,
    and so may return different values for an audio clip split into snippets vs. a full clip.

    Args:

        x (Tensor): Input spectrogram(s) before being converted to decibel scale. Input should take
          the form `(..., freq, time)`. Batched inputs should include a channel dimension and
          have the form `(batch, channel, freq, time)`.
        multiplier (float): Use 10. for power and 20. for amplitude
        amin (float): Number to clamp ``x``
        db_multiplier (float): Log10(max(reference value and amin))
        top_db (float or None, optional): Minimum negative cut-off in decibels. A reasonable number
            is 80. (Default: ``None``)

    Returns:
        Tensor: Output tensor in decibel scale
    )minNrL   rZ   r5   r8   )rq   r8   r5   dim)	r=   log10clampr@   rs   rA   maxZamaxview)rk   rl   rm   rn   ro   Zx_dbrC   Zpacked_channelsrI   rI   rJ   r   B  s    $
)rk   refr-   r3   c                 C   s   |t t dd|  | S )a  Turn a tensor from the decibel scale to the power/amplitude scale.

    .. devices:: CPU CUDA

    .. properties:: TorchScript

    Args:
        x (Tensor): Input tensor before being converted to power/amplitude scale.
        ref (float): Reference which the output will be scaled by.
        power (float): If power equals 1, will compute DB to power. If 0.5, will compute DB to amplitude.

    Returns:
        Tensor: Output tensor in power/amplitude scale.
          $@皙?)r=   rD   )rk   rx   r-   rI   rI   rJ   r   m  s    htk)freq	mel_scaler3   c                 C   s   |dkrt d|dkr.dtd| d   S d}d}| | | }d	}|| | }td
d }| |kr~|t| | |  }|S )zConvert Hz to Mels.

    Args:
        freqs (float): Frequencies in Hz
        mel_scale (str, optional): Scale to use: ``htk`` or ``slaney``. (Default: ``htk``)

    Returns:
        mels (float): Frequency in Mels
    slaneyr{   -mel_scale should be one of "htk" or "slaney".r{        F@r:        @r^   竪P@     @@皙@      ;@)rN   mathrt   log)r|   r}   f_minf_spmels
min_log_hzmin_log_mellogsteprI   rI   rJ   
_hz_to_mel  s    r   )r   r}   r3   c           	      C   s   |dkrt d|dkr,dd| d  d  S d}d	}|||   }d
}|| | }tdd }| |k}|t|| | |   ||< |S )zConvert mel bin numbers to frequencies.

    Args:
        mels (Tensor): Mel frequencies
        mel_scale (str, optional): Scale to use: ``htk`` or ``slaney``. (Default: ``htk``)

    Returns:
        freqs (Tensor): Mels converted in Hz
    r~   r   r{   r   ry   r   r:   r^   r   r   r   r   )rN   r   r   r=   exp)	r   r}   r   r   freqsr   r   r   Zlog_trI   rI   rJ   
_mel_to_hz  s    r   )	all_freqsf_ptsr3   c                 C   s   |dd |dd  }| d|  d }td}d|ddddf  |dd  }|ddddf |dd  }t|t||}|S )a  Create a triangular filter bank.

    Args:
        all_freqs (Tensor): STFT freq points of size (`n_freqs`).
        f_pts (Tensor): Filter mid points of size (`n_filter`).

    Returns:
        fb (Tensor): The filter bank of size (`n_freqs`, `n_filter`).
    rZ   Nr5   r   g      r8   rL   )	unsqueezer=   zerosrv   rp   )r   r   Zf_diffZslopesZzeroZdown_slopesZ	up_slopesfbrI   rI   rJ   _create_triangular_filterbank  s    
$ r   )n_freqsr   f_maxn_melssample_ratenormr}   r3   c                 C   s   |dk	r|dkrt dtd|d | }t||d}t||d}	t||	|d }
t|
|d}t||}|dk	r|dkrd|d|d  |d|   }||d9 }|jddjd	k	 rt
d
| d|  d |S )a"  Create a frequency bin conversion matrix.

    .. devices:: CPU

    .. properties:: TorchScript

    Note:
        For the sake of the numerical compatibility with librosa, not all the coefficients
        in the resulting filter bank has magnitude of 1.

        .. image:: https://download.pytorch.org/torchaudio/doc-assets/mel_fbanks.png
           :alt: Visualization of generated filter bank

    Args:
        n_freqs (int): Number of frequencies to highlight/apply
        f_min (float): Minimum frequency (Hz)
        f_max (float): Maximum frequency (Hz)
        n_mels (int): Number of mel filterbanks
        sample_rate (int): Sample rate of the audio waveform
        norm (str or None, optional): If 'slaney', divide the triangular mel weights by the width of the mel band
            (area normalization). (Default: ``None``)
        mel_scale (str, optional): Scale to use: ``htk`` or ``slaney``. (Default: ``htk``)

    Returns:
        Tensor: Triangular filter banks (fb matrix) of size (``n_freqs``, ``n_mels``)
        meaning number of frequencies to highlight/apply to x the number of filterbanks.
        Each column is a filterbank so that assuming there is a matrix A of
        size (..., ``n_freqs``), the applied result would be
        ``A * melscale_fbanks(A.size(-1), ...)``.

    Nr   z$norm must be one of None or 'slaney'r   rL   )r}   r9   rr   r^   zIAt least one mel filterbank has all zero values. The value for `n_mels` (z4) may be set too high. Or, the value for `n_freqs` (z) may be set too low.)rN   r=   linspacer   r   r   r   rv   valuesanyr;   r<   )r   r   r   r   r   r   r}   r   Zm_minZm_maxZm_ptsr   r   ZenormrI   rI   rJ   r     s     )
 )r   r   r   n_filterr   r3   c                 C   s2   t d|d | }t |||d }t||}|S )a)  Creates a linear triangular filterbank.

    .. devices:: CPU

    .. properties:: TorchScript

    Note:
        For the sake of the numerical compatibility with librosa, not all the coefficients
        in the resulting filter bank has magnitude of 1.

        .. image:: https://download.pytorch.org/torchaudio/doc-assets/lin_fbanks.png
           :alt: Visualization of generated filter bank

    Args:
        n_freqs (int): Number of frequencies to highlight/apply
        f_min (float): Minimum frequency (Hz)
        f_max (float): Maximum frequency (Hz)
        n_filter (int): Number of (linear) triangular filter
        sample_rate (int): Sample rate of the audio waveform

    Returns:
        Tensor: Triangular filter banks (fb matrix) of size (``n_freqs``, ``n_filter``)
        meaning number of frequencies to highlight/apply to x the number of filterbanks.
        Each column is a filterbank so that assuming there is a matrix A of
        size (..., ``n_freqs``), the applied result would be
        ``A * linear_fbanks(A.size(-1), ...)``.
    r   rL   )r=   r   r   )r   r   r   r   r   r   r   r   rI   rI   rJ   r   $  s    #
)n_mfccr   r   r3   c                 C   s   t t|}t t| d}t tjt| |d  | }|dkrT|d9 }n<|dks`t|d  dtd 9  < |tdt| 9 }|	 S )a  Create a DCT transformation matrix with shape (``n_mels``, ``n_mfcc``),
    normalized depending on norm.

    .. devices:: CPU

    .. properties:: TorchScript

    Args:
        n_mfcc (int): Number of mfc coefficients to retain
        n_mels (int): Number of mel filterbanks
        norm (str or None): Norm to use (either 'ortho' or None)

    Returns:
        Tensor: The transformation matrix, to be right-multiplied to
        row-wise data of size (``n_mels``, ``n_mfcc``).
    rZ         ?Nr9   Zorthor   r:   )
r=   arangerS   r   cosr   pir`   rF   t)r   r   r   nkdctrI   rI   rJ   r   R  s     
)rk   quantization_channelsr3   c                 C   s~   |d }|   s&td | tj} tj|| jd}t| t	|t
|   t	| }|d d | d tj}|S )a  Encode signal based on mu-law companding.

    .. devices:: CPU CUDA

    .. properties:: TorchScript

    For more info see the
    `Wikipedia Entry <https://en.wikipedia.org/wiki/%CE%9C-law_algorithm>`_

    This algorithm expects the signal has been scaled to between -1 and 1 and
    returns a signal encoded with values from 0 to quantization_channels - 1.

    Args:
        x (Tensor): Input tensor
        quantization_channels (int): Number of channels

    Returns:
        Tensor: Input after mu-law encoding
    r:   zbThe input Tensor must be of floating type.             This will be an error in the v0.12 release.r\   rZ   rL   r   )is_floating_pointr;   r<   tor=   rS   re   r\   signlog1prG   Zint64)rk   r   mux_murI   rI   rJ   r   p  s    ()r   r   r3   c                 C   sl   |d }|   s| tj} tj|| jd}| | d d }t|tt|t	| d  | }|S )a  Decode mu-law encoded signal.

    .. devices:: CPU CUDA

    .. properties:: TorchScript

    For more info see the
    `Wikipedia Entry <https://en.wikipedia.org/wiki/%CE%9C-law_algorithm>`_

    This expects an input with values between 0 and quantization_channels - 1
    and returns a signal scaled between -1 and 1.

    Args:
        x_mu (Tensor): Input tensor
        quantization_channels (int): Number of channels

    Returns:
        Tensor: Input after mu-law decoding
    r:   r   rL   )
r   r   r=   rS   re   r\   r   r   rG   r   )r   r   r   rk   rI   rI   rJ   r     s    ,)complex_specgramsratephase_advancer3   c                 C   sp  |dkr| S |   }| dgt|dd  } t| j}tjd|  d|| j|d}|d }| dddf  }tj	j
| dd	g} | d| }| d|d  }	| }
|	 }| }|	 }||
 | }|d	tj t|d	tj    }|| }tj||dddf gdd
}t|d}|| d| |  }t||}||dd |jdd  }|S )aF  Given a STFT tensor, speed up in time without modifying pitch by a factor of ``rate``.

    .. devices:: CPU CUDA

    .. properties:: Autograd TorchScript

    Args:
        complex_specgrams (Tensor):
            A tensor of dimension `(..., freq, num_frame)` with complex dtype.
        rate (float): Speed-up factor
        phase_advance (Tensor): Expected phase advance in each bin. Dimension of `(freq, 1)`

    Returns:
        Tensor:
            Stretched spectrogram. The resulting tensor is of the same dtype as the input
            spectrogram, but the number of frames is changed to ``ceil(num_frame / rate)``.

    Example
        >>> freq, hop_length = 1025, 512
        >>> # (channel, freq, time)
        >>> complex_specgrams = torch.randn(2, freq, 300, dtype=torch.cfloat)
        >>> rate = 1.3 # Speed up by 30%
        >>> phase_advance = torch.linspace(
        >>>    0, math.pi * hop_length, freq)[..., None]
        >>> x = phase_vocoder(complex_specgrams, rate, phase_advance)
        >>> x.shape # with 231 == ceil(300 / 1.3)
        torch.Size([2, 1025, 231])
    r:   r5   r8   Nr   r]   r\   .rZ   rL   rr   )r@   rA   rb   r=   realr\   r   r]   Zangler>   r?   r(   Zindex_selectlongrG   r   r   roundcatcumsumZpolarrC   )r   r   r   rC   rQ   Z
time_stepsalphasZphase_0Zcomplex_specgrams_0Zcomplex_specgrams_1Zangle_0Zangle_1Znorm_0Znorm_1phaseZ	phase_accZmagZcomplex_specgrams_stretchrI   rI   rJ   r     s0    " )
mask_parampaxis_lengthr3   c                 C   s"   |dkr| S t | t|| S d S )Nr:   )rp   int)r   r   r   rI   rI   rJ   _get_mask_param  s    r   r:   )	specgramsr   
mask_valueaxisr   r3   c                 C   s  |dkrt dd|  kr$dks6n t d| dt||| j| }|dk rT| S | j}| j}tj| jdd	 ||d
| }tj| jdd	 ||d
| ||  }| d }	| |  d }
tj	d| |||d
}| 
|d} | ||	k||
k @ |} | 
|d} | S )a  Apply a mask along ``axis``.

    .. devices:: CPU CUDA

    .. properties:: Autograd TorchScript

    Mask will be applied from indices ``[v_0, v_0 + v)``,
    where ``v`` is sampled from ``uniform(0, max_v)`` and
    ``v_0`` from ``uniform(0, specgrams.size(axis) - v)``,
    with ``max_v = mask_param`` when ``p = 1.0`` and
    ``max_v = min(mask_param, floor(specgrams.size(axis) * p))`` otherwise.

    Args:
        specgrams (Tensor): Real spectrograms `(batch, channel, freq, time)`
        mask_param (int): Number of columns to be masked will be uniformly sampled from [0, mask_param]
        mask_value (float): Value to assign to the masked columns
        axis (int): Axis to apply masking on (2 -> frequency, 3 -> time)
        p (float, optional): maximum proportion of columns that can be masked. (Default: 1.0)

    Returns:
        Tensor: Masked spectrograms of dimensions `(batch, channel, freq, time)`
    )rL      -Only Frequency and Time masking are supportedr^   r:   ,The value of p must be between 0.0 and 1.0 ( given).rZ   NrL   r   .NNr   r5   )rN   r   rC   r]   r\   r=   rc   r@   r   r   	transposemasked_fill)r   r   r   r   r   r]   r\   value	min_value
mask_startmask_endmaskrI   rI   rJ   r     s$    ()rV   r   r   r   r   r3   c                 C   s>  |dkrt dd|  kr$dks6n t d| dt||| j| }|dk rT| S |  }| dgt|d	d
  } td| }td| ||  }| 	 }| |  	 }	tj
d| j| | j| jd}
|
|k|
|	k @ }
|dkr|
d}
|	| |k st| |
|} | |d
d	 | jd	d
  } | S )a  Apply a mask along ``axis``.

    .. devices:: CPU CUDA

    .. properties:: Autograd TorchScript

    Mask will be applied from indices ``[v_0, v_0 + v)``,
    where ``v`` is sampled from ``uniform(0, max_v)`` and
    ``v_0`` from ``uniform(0, specgrams.size(axis) - v)``, with
    ``max_v = mask_param`` when ``p = 1.0`` and
    ``max_v = min(mask_param, floor(specgrams.size(axis) * p))``
    otherwise.
    All examples will have the same mask interval.

    Args:
        specgram (Tensor): Real spectrogram `(channel, freq, time)`
        mask_param (int): Number of columns to be masked will be uniformly sampled from [0, mask_param]
        mask_value (float): Value to assign to the masked columns
        axis (int): Axis to apply masking on (1 -> frequency, 2 -> time)
        p (float, optional): maximum proportion of columns that can be masked. (Default: 1.0)

    Returns:
        Tensor: Masked spectrogram of dimensions `(channel, freq, time)`
    )rZ   rL   r   r^   r:   r   r   rZ   r5   r8   Nr   r   )rN   r   rC   r@   rA   rb   r=   rc   r   squeezer   r]   r\   r   r`   r   )rV   r   r   r   r   rC   r   r   r   r   r   rI   rI   rJ   r   :  s*    
    	replicate)rV   r,   moder3   c           
      C   s   | j }| j}|  }| dd|d } |dks2t|d d }||d  d| d  d }tjjj| ||f|d} tj	| |d d||d
| jd dd}tjjj| || jd d| }	|	|}	|	S )a  Compute delta coefficients of a tensor, usually a spectrogram:

    .. devices:: CPU CUDA

    .. properties:: TorchScript

    .. math::
       d_t = \frac{\sum_{n=1}^{\text{N}} n (c_{t+n} - c_{t-n})}{2 \sum_{n=1}^{\text{N}} n^2}

    where :math:`d_t` is the deltas at time :math:`t`,
    :math:`c_t` is the spectrogram coeffcients at time :math:`t`,
    :math:`N` is ``(win_length-1)//2``.

    Args:
        specgram (Tensor): Tensor of audio of dimension `(..., freq, time)`
        win_length (int, optional): The window length used for computing delta (Default: ``5``)
        mode (str, optional): Mode parameter passed to padding (Default: ``"replicate"``)

    Returns:
        Tensor: Tensor of deltas of dimension `(..., freq, time)`

    Example
        >>> specgram = torch.randn(1, 40, 1000)
        >>> delta = compute_deltas(specgram)
        >>> delta2 = compute_deltas(delta)
    rZ   r5   r   rL   )r   r   )groups)r]   r\   r@   rA   r`   r=   r>   r?   r(   r   repeatrC   conv1d)
rV   r,   r   r]   r\   rC   r   ZdenomkerneloutputrI   rI   rJ   r   z  s    *
)r'   r   
frame_timefreq_lowr3   c                 C   s>  d}t t|| }t t|| }|  d }t t|| }|||  | }	tjj| d|	f} g }
td|d D ]}| dd| f 	d||dd|ddf }| d|df 	d||dd|ddf }|| 
d|tj|ddd d |tj|ddd d }|
|d q|t|
d}|S )	a  
    Compute Normalized Cross-Correlation Function (NCCF).

    .. math::
        \phi_i(m) = \frac{\sum_{n=b_i}^{b_i + N-1} w(n) w(m+n)}{\sqrt{E(b_i) E(m+b_i)}},

    where
    :math:`\phi_i(m)` is the NCCF at frame :math:`i` with lag :math:`m`,
    :math:`w` is the waveform,
    :math:`N` is the length of a frame,
    :math:`b_i` is the beginning of frame :math:`i`,
    :math:`E(j)` is the energy :math:`\sum_{n=j}^{j+N-1} w^2(n)`.
    &.>r5   r   rZ   .NrL   )r   rs   )r   r   ceilr@   r=   r>   r?   r(   rf   unfoldrE   r   rD   appendr   r   )r'   r   r   r   EPSILONZlags
frame_sizeZwaveform_lengthZnum_of_framesr   Z
output_lagZlags1s2Zoutput_framesnccfrI   rI   rJ   _compute_nccf  s(    .,r   Gz?)abthreshr3   c                 C   sP   | d ||d  k}|| d  | |d   }|| d  | |d   }||fS )zb
    Take value from first if bigger than a multiplicative factor of the second, elementwise.
    r   rZ   rI   )r   r   r   r   r   indicesrI   rI   rJ   _combine_max  s    r   )r   r   	freq_highr3   c                 C   sv   t t|| }t| d|df d}| jd d }t| d||f d}t||}|d }||7 }|d7 }|S )z
    For each frame, take the highest value of NCCF,
    apply centered median smoothing, and convert to frequency.

    Note: If the max among all the lags is very close
    to the first half of lags, then the latter is taken.
    .Nr5   rL   rZ   )r   r   r   r=   rv   rC   r   )r   r   r   Zlag_minbestZ	half_sizerT   r   rI   rI   rJ   _find_max_per_frame  s    	
r   )r   r,   r3   c                 C   sv   |d d }t jjj| |dfddd} t j|| d|f dg dd	| dd
|f< | d|d}t |d\}}|S )zH
    Apply median smoothing to the 1D tensor over the given window.
    rZ   rL   r   r4   r^   )r   r   .r5   rr   N)r=   r>   r?   r(   r   r   r   Zmedian)r   r,   Z
pad_lengthZrollr   rj   rI   rI   rJ   _median_smoothing  s    .r   {Gz?   U   H  )r'   r   r   r,   r   r   r3   c                 C   s   t |  }| dg|dd  } t| |||}t|||}t||}d}	||	|tj  }
|
|dd t |
j	dd  }
|
S )a  Detect pitch frequency.

    .. devices:: CPU CUDA

    .. properties:: TorchScript

    It is implemented using normalized cross-correlation function and median smoothing.

    Args:
        waveform (Tensor): Tensor of audio of dimension `(..., freq, time)`
        sample_rate (int): The sample rate of the waveform (Hz)
        frame_time (float, optional): Duration of a frame (Default: ``10 ** (-2)``).
        win_length (int, optional): The window length for median smoothing (in number of frames) (Default: ``30``).
        freq_low (int, optional): Lowest frequency that can be detected (Hz) (Default: ``85``).
        freq_high (int, optional): Highest frequency that can be detected (Hz) (Default: ``3400``).

    Returns:
        Tensor: Tensor of freq of dimension `(..., frame)`
    r5   Nr   )
rb   r@   rA   r   r   r   r   r=   rS   rC   )r'   r   r   r,   r   r   rC   r   r   r   r|   rI   rI   rJ   r     s    
$X  d   F)rV   
cmn_windowmin_cmn_windowr/   	norm_varsr3   c                 C   s  | j }|dd \}}| d||} | j d }| j}	| j}
d }}tj|||	|
d}tj|||	|
d}tj||||	|
d}t|D ]$}d}d}|r||d  }|| }n|| }|d }|dk r||8 }d}|s||krt|d |}||kr||| 8 }|}|dk rd}|dkrv| dd||| ddf }|t|d7 }|r|t	|d ddddddf 7 }nt||kr| dd|ddf }||8 }|r||d 8 }||kr| dd|ddf }||7 }|r||d 7 }|| }|}|}| dd|ddf ||  |dd|ddf< |r|dkr^tj|||	|
d|dd|ddf< q|}|| }||d |d  8 }t
|d}|dd|ddf  |9  < q||dd ||f }t|dkr|d}|S )	a  
    Apply sliding-window cepstral mean (and optionally variance) normalization per utterance.

    .. devices:: CPU CUDA

    .. properties:: TorchScript

    Args:
        specgram (Tensor): Tensor of spectrogram of dimension `(..., time, freq)`
        cmn_window (int, optional): Window in frames for running average CMN computation (int, default = 600)
        min_cmn_window (int, optional):  Minimum CMN window used at start of decoding (adds latency only at start).
            Only applicable if center == false, ignored if center==true (int, default = 100)
        center (bool, optional): If true, use a window centered on the current frame
            (to the extent possible, modulo end effects). If false, window is to the left. (bool, default = false)
        norm_vars (bool, optional): If true, normalize variance to one. (bool, default = false)

    Returns:
        Tensor: Tensor matching input shape `(..., freq, time)`
    r8   Nr5   r   r[   rL   rZ   g      )rC   rw   r\   r]   r=   r   rf   rv   rE   r   rD   lenr   )rV   r   r   r/   r   Zinput_shapeZ
num_framesZ	num_featsZnum_channelsr\   r]   Zlast_window_startZlast_window_endZcur_sumZ	cur_sumsqZcmn_specgramr   Zwindow_startZ
window_endZ
input_partZframe_to_removeZframe_to_addZwindow_framesZvariancerI   rI   rJ   r   D  sx    




(

0
& 
)r'   r   r(   r)   r*   r+   r,   r3   c           
   
   C   s^   t | |||||ddd}tjd|d d|d  |jdd}d	}	|| j|	d
|j|	d
 S )a  Compute the spectral centroid for each channel along the time axis.

    .. devices:: CPU CUDA

    .. properties:: Autograd TorchScript

    The spectral centroid is defined as the weighted average of the
    frequency values, weighted by their magnitude.

    Args:
        waveform (Tensor): Tensor of audio of dimension `(..., time)`
        sample_rate (int): Sample rate of the audio waveform
        pad (int): Two sided padding of signal
        window (Tensor): Window tensor that is applied/multiplied to each frame/window
        n_fft (int): Size of FFT
        hop_length (int): Length of hop between STFT windows
        win_length (int): Window size

    Returns:
        Tensor: Dimension `(..., time)`
    r:   F)r(   r)   r*   r+   r,   r-   r.   r   rL   rZ   )Zstepsr]   )r5   rZ   r8   rr   )r	   r=   r   r]   rA   rE   )
r'   r   r(   r)   r*   r+   r,   rV   r   Zfreq_dimrI   rI   rJ   r     s    
&)r'   r   ra   channels_firstcompressionencodingbits_per_sampler3   c           
   
   C   s^   t  }tjj|| |||||| |d tjjj|||d\}}	|	|krZt||	|}|S )a^  
    Apply codecs as a form of augmentation.

    .. devices:: CPU

    Args:
        waveform (Tensor): Audio data. Must be 2 dimensional. See also ```channels_first```.
        sample_rate (int): Sample rate of the audio waveform.
        format (str): File format.
        channels_first (bool, optional):
            When True, both the input and output Tensor have dimension `(channel, time)`.
            Otherwise, they have dimension `(time, channel)`.
        compression (float or None, optional): Used for formats other than WAV.
            For more details see :py:func:`torchaudio.backend.sox_io_backend.save`.
        encoding (str or None, optional): Changes the encoding for the supported formats.
            For more details see :py:func:`torchaudio.backend.sox_io_backend.save`.
        bits_per_sample (int or None, optional): Changes the bit depth for the supported formats.
            For more details see :py:func:`torchaudio.backend.sox_io_backend.save`.

    Returns:
        Tensor: Resulting Tensor.
        If ``channels_first=True``, it has `(channel, time)` else `(time, channel)`.
    r   )r   ra   )	ioBytesIO
torchaudiobackendZsox_io_backendsaveseekloadr   )
r'   r   ra   r   r   r   r   bytesZ	augmentedsrrI   rI   rJ   r     s     !       
      9@ry   2     rz       {Gzt?X  rZ     )r'   r   frame_lengthframe_shiftmin_f0max_f0soft_min_f0penalty_factorlowpass_cutoffresample_frequencydelta_pitchnccf_ballastlowpass_filter_widthupsample_filter_widthmax_frames_latencyframes_per_chunksimulate_first_pass_onlinerecompute_frame
snip_edgesr3   c                 C   sl   | j }| d|d } tjj| |||||||||	|
||||||||}||dd |j dd  }|S )ad  Extract pitch based on method described in *A pitch extraction algorithm tuned
    for automatic speech recognition* [:footcite:`6854049`].

    .. devices:: CPU

    .. properties:: TorchScript

    This function computes the equivalent of `compute-kaldi-pitch-feats` from Kaldi.

    Args:
        waveform (Tensor):
            The input waveform of shape `(..., time)`.
        sample_rate (float):
            Sample rate of `waveform`.
        frame_length (float, optional):
            Frame length in milliseconds. (default: 25.0)
        frame_shift (float, optional):
            Frame shift in milliseconds. (default: 10.0)
        min_f0 (float, optional):
            Minimum F0 to search for (Hz)  (default: 50.0)
        max_f0 (float, optional):
            Maximum F0 to search for (Hz)  (default: 400.0)
        soft_min_f0 (float, optional):
            Minimum f0, applied in soft way, must not exceed min-f0  (default: 10.0)
        penalty_factor (float, optional):
            Cost factor for FO change.  (default: 0.1)
        lowpass_cutoff (float, optional):
            Cutoff frequency for LowPass filter (Hz) (default: 1000)
        resample_frequency (float, optional):
            Frequency that we down-sample the signal to. Must be more than twice lowpass-cutoff.
            (default: 4000)
        delta_pitch( float, optional):
            Smallest relative change in pitch that our algorithm measures. (default: 0.005)
        nccf_ballast (float, optional):
            Increasing this factor reduces NCCF for quiet frames (default: 7000)
        lowpass_filter_width (int, optional):
            Integer that determines filter width of lowpass filter, more gives sharper filter.
            (default: 1)
        upsample_filter_width (int, optional):
            Integer that determines filter width when upsampling NCCF. (default: 5)
        max_frames_latency (int, optional):
            Maximum number of frames of latency that we allow pitch tracking to introduce into
            the feature processing (affects output only if ``frames_per_chunk > 0`` and
            ``simulate_first_pass_online=True``) (default: 0)
        frames_per_chunk (int, optional):
            The number of frames used for energy normalization. (default: 0)
        simulate_first_pass_online (bool, optional):
            If true, the function will output features that correspond to what an online decoder
            would see in the first pass of decoding -- not the final version of the features,
            which is the default. (default: False)
            Relevant if ``frames_per_chunk > 0``.
        recompute_frame (int, optional):
            Only relevant for compatibility with online pitch extraction.
            A non-critical parameter; the frame at which we recompute some of the forward pointers,
            after revising our estimate of the signal energy.
            Relevant if ``frames_per_chunk > 0``. (default: 500)
        snip_edges (bool, optional):
            If this is set to false, the incomplete frames near the ending edge won't be snipped,
            so that the number of frames is the file size divided by the frame-shift.
            This makes different types of features give the same number of frames. (default: True)

    Returns:
       Tensor: Pitch feature. Shape: `(batch, frames 2)` where the last dimension
       corresponds to pitch and NCCF.
    r5   Nr8   )rC   rA   r=   opsr  Zkaldi_ComputeKaldiPitch)r'   r   r  r  r  r  r  r  r  r  r  r  r  r  r  r  r  r  r   rC   resultrI   rI   rJ   r     s2    W    sinc_interpolationcpu)		orig_freqnew_freqgcdr  rolloffresampling_methodbetar]   r\   c	              	   C   s  t | | krt ||ks td|dkr6td|t | | } t || }|dksZtg }	t| |}
|
|9 }
t||  |
 }|d k	r|ntj	}tj
| ||  ||d}t|D ]}| | ||   |
 }|| |}|dkrt|tj | d d }nF|d krd}tt|}t|td	|| d   t| }|tj9 }t|dktd
|t|| }|| |	| q|
|  }t|	|d	d|}	|d kr|	jtjd}	|	|fS )Na  Frequencies must be of integer type to ensure quality resampling computation. To work around this, manually convert both frequencies to integer values that maintain their resampling rate ratio before passing them into the function. Example: To downsample a 44100 hz waveform by a factor of 8, use `orig_freq=8` and `new_freq=1` instead of `orig_freq=44100` and `new_freq=5512.5`. For more information, please refer to https://github.com/pytorch/audio/issues/1487.)r$  Zkaiser_windowzInvalid resampling method: {}r   r   r$  rL   gQaTi-@rZ   r:   r5   r   )r   	ExceptionrN   ra   r`   rp   r   r   r=   Zfloat64r   rf   Zclamp_r   r   re   rS   Zi0rF   wherer   sinrg   r   stackrw   Zfloat32)r&  r'  r(  r  r)  r*  r+  r]   r\   ZkernelsZ	base_freqwidthZ	idx_dtypeidxir   r)   Zbeta_tensorr   scalerI   rI   rJ   _get_sinc_resample_kernell  sB    	


*
(

r4  )r'   r&  r'  r(  r   r0  c                 C   s   |   std| j dt|| }t|| }|  }| d|d } | j\}}tjj	
| ||| f} tjj	j| d d d f ||d}	|	dd|d}	tt|| | }
|	dd |
f }	|	|d d |	jdd   }	|	S )Nz?Expected floating point type for waveform tensor, but received .r5   )ZstriderZ   rL   .)r   	TypeErrorr\   r   r@   rw   rC   r=   r>   r?   r(   r   r   rA   r   r   )r'   r&  r'  r(  r   r0  rC   Znum_wavsrK   	resampledZtarget_lengthrI   rI   rJ   _apply_sinc_resample_kernel  s    
  r8  )r'   r&  r'  r  r)  r*  r+  r3   c              
   C   sj   |dkr|dkst ||kr | S tt|t|}t|||||||| j| j	\}}	t| |||||	}
|
S )a  Resamples the waveform at the new frequency using bandlimited interpolation. [:footcite:`RESAMPLE`].

    .. devices:: CPU CUDA

    .. properties:: Autograd TorchScript

    Note:
        ``transforms.Resample`` precomputes and reuses the resampling kernel, so using it will result in
        more efficient computation if resampling multiple waveforms with the same resampling parameters.

    Args:
        waveform (Tensor): The input signal of dimension `(..., time)`
        orig_freq (int): The original frequency of the signal
        new_freq (int): The desired frequency
        lowpass_filter_width (int, optional): Controls the sharpness of the filter, more == sharper
            but less efficient. (Default: ``6``)
        rolloff (float, optional): The roll-off frequency of the filter, as a fraction of the Nyquist.
            Lower values reduce anti-aliasing, but also reduce some of the highest frequencies. (Default: ``0.99``)
        resampling_method (str, optional): The resampling method to use.
            Options: [``sinc_interpolation``, ``kaiser_window``] (Default: ``'sinc_interpolation'``)
        beta (float or None, optional): The shape parameter used for kaiser window.

    Returns:
        Tensor: The waveform at the new frequency of dimension `(..., time).`
    r^   )r`   r   r(  r   r4  r]   r\   r8  )r'   r&  r'  r  r)  r*  r+  r(  r   r0  r7  rI   rI   rJ   r     s"    #)seq1seq2r3   c           
      C   s   t |}tt|d }dd t|d D }tdt | d D ]}||d< td|d D ]j}| |d  ||d  kr||d  ||< qZ||d  d }||d  d }|| d }	t|||	||< qZ|| }}q@t|d S )a4  
    Calculate the word level edit (Levenshtein) distance between two sequences.

    .. devices:: CPU

    The function computes an edit distance allowing deletion, insertion and
    substitution. The result is an integer.

    For most applications, the two input sequences should be the same type. If
    two strings are given, the output is the edit distance between the two
    strings (character edit distance). If two lists of strings are given, the
    output is the edit distance between sentences (word edit distance). Users
    may want to normalize the output by the length of the reference sequence.

    Args:
        seq1 (Sequence): the first sequence to compare.
        seq2 (Sequence): the second sequence to compare.
    Returns:
        int: The distance between the first and second sequences.
    rZ   c                 S   s   g | ]}d qS )r   rI   ).0rj   rI   rI   rJ   
<listcomp>3  s     z!edit_distance.<locals>.<listcomp>r   r5   )r   rb   rf   rp   r   )
r9  r:  Z	len_sent2ZdoldZdnewr2  jZsubstitutionZ	insertionZdeletionrI   rI   rJ   r     s          )	r'   r   n_stepsbins_per_octaver*   r,   r+   r)   r3   c                 C   sH   t | ||||||}dt| |  }	t|t||	 |}
t|
|  S )a#  
    Shift the pitch of a waveform by ``n_steps`` steps.

    .. devices:: CPU CUDA

    .. properties:: TorchScript

    Args:
        waveform (Tensor): The input waveform of shape `(..., time)`.
        sample_rate (int): Sample rate of `waveform`.
        n_steps (int): The (fractional) steps to shift `waveform`.
        bins_per_octave (int, optional): The number of steps per octave (Default: ``12``).
        n_fft (int, optional): Size of FFT, creates ``n_fft // 2 + 1`` bins (Default: ``512``).
        win_length (int or None, optional): Window size. If None, then ``n_fft`` is used. (Default: ``None``).
        hop_length (int or None, optional): Length of hop between STFT windows. If None, then
            ``win_length // 4`` is used (Default: ``None``).
        window (Tensor or None, optional): Window tensor that is applied/multiplied to each frame/window.
            If None, then ``torch.hann_window(win_length)`` is used (Default: ``None``).


    Returns:
        Tensor: The pitch-shifted audio waveform of shape `(..., time)`.
    r9   )_stretch_waveformrS   r   r   _fix_waveform_shaper@   )r'   r   r@  rA  r*   r,   r+   r)   waveform_stretchr   waveform_shiftrI   rI   rJ   r   E  s    !	)r'   r@  rA  r*   r,   r+   r)   r3   c                 C   s   |dkr|d }|dkr|}|dkr4t j|| jd}|  }| d|d } |d }dt| |  }	t j| ||||dddddd	
}
t jd
tj	| |
j
d |
jdd }t|
|	|}tt||	 }t j||||||d}|S )z
    Pitch shift helper function to preprocess and stretch waveform before resampling step.

    Args:
        See pitch_shift arg descriptions.

    Returns:
        Tensor: The preprocessed waveform stretched prior to resampling.
    N   )Zwindow_lengthr]   r5   r9   Tr&   Fr6   r   r8   )r]   .Nr_   )r=   Zhann_windowr]   r@   rA   rS   rB   r   r   r   rC   r   r   r   rO   )r'   r@  rA  r*   r,   r+   r)   rC   ori_lenr   rH   r   Zspec_stretchZlen_stretchrD  rI   rI   rJ   rB  u  sD    $     rB  )rE  rC   r3   c                 C   sj   |d }|   d }||kr.| dd|f } ntjj| d|| g} | |dd | jdd  } | S )a?  
    PitchShift helper function to process after resampling step to fix the shape back.

    Args:
        waveform_shift(Tensor): The waveform after stretch and resample
        shape (List[int]): The shape of initial waveform

    Returns:
        Tensor: The pitch-shifted audio waveform of shape `(..., time)`.
    r5   .Nr   )r@   r=   r>   r?   r(   rw   rC   )rE  rC   rH  Z	shift_lenrI   rI   rJ   rC    s     rC  r5   mean)logitstargetslogit_lengthstarget_lengthsblankru   	reductionc           	      C   sh   |dkrt d|dk r&| jd | }tjjj| |||||d\}}|dkrT| S |dkrd| S |S )a.  Compute the RNN Transducer loss from *Sequence Transduction with Recurrent Neural Networks*
    [:footcite:`graves2012sequence`].

    .. devices:: CPU CUDA

    .. properties:: Autograd TorchScript

    The RNN Transducer loss extends the CTC loss by defining a distribution over output
    sequences of all lengths, and by jointly modelling both input-output and output-output
    dependencies.

    Args:
        logits (Tensor): Tensor of dimension `(batch, max seq length, max target length + 1, class)`
            containing output from joiner
        targets (Tensor): Tensor of dimension `(batch, max target length)` containing targets with zero padded
        logit_lengths (Tensor): Tensor of dimension `(batch)` containing lengths of each sequence from encoder
        target_lengths (Tensor): Tensor of dimension `(batch)` containing lengths of targets for each sequence
        blank (int, optional): blank label (Default: ``-1``)
        clamp (float, optional): clamp for gradients (Default: ``-1``)
        reduction (string, optional): Specifies the reduction to apply to the output:
            ``'none'`` | ``'mean'`` | ``'sum'``. (Default: ``'mean'``)
    Returns:
        Tensor: Loss with the reduction option applied. If ``reduction`` is  ``'none'``, then size `(batch)`,
        otherwise scalar.
    )nonerI  rE   z3reduction should be one of 'none', 'mean', or 'sum'r   r5   )rJ  rK  rL  rM  rN  ru   rI  rE   )rN   rC   r=   r!  r  r   rI  rE   )	rJ  rK  rL  rM  rN  ru   rO  Zcostsrj   rI   rI   rJ   r     s"    "
	绽|=)rV   r   	normalizeepsr3   c                 C   s   |  dd} td| |  g}|dk	r|jdd | jdd krX|jd | jd ks`tdd|j d| j d	 |r||jdd
d|  }||d  }|jdd}|S )a/  Compute cross-channel power spectral density (PSD) matrix.

    .. devices:: CPU CUDA

    .. properties:: Autograd TorchScript

    Args:
        specgram (torch.Tensor): Multi-channel complex-valued spectrum.
            Tensor with dimensions `(..., channel, freq, time)`.
        mask (torch.Tensor or None, optional): Time-Frequency mask for normalization.
            Tensor with dimensions `(..., freq, time)`. (Default: ``None``)
        normalize (bool, optional): If ``True``, normalize the mask along the time dimension. (Default: ``True``)
        eps (float, optional): Value to add to the denominator in mask normalization. (Default: ``1e-15``)

    Returns:
        torch.Tensor: The complex-valued PSD matrix of the input spectrum.
        Tensor with dimensions `(..., freq, channel, channel)`
    rq   r8   z...ct,...et->...tceNr5   zSThe dimensions of mask except the channel dimension should be the same as specgram.Found z for mask and  for specgram.T)rs   Zkeepdimr   rr   )r   r=   einsumconjrC   r`   rE   )rV   r   rR  rS  r    rI   rI   rJ   r      s    r8   )r7   dim1dim2r3   c                 C   sL   | j dkstd| j| | j| ks.tdtj| d||d} | jddS )a  Compute the trace of a Tensor along ``dim1`` and ``dim2`` dimensions.

    Args:
        input (torch.Tensor): Tensor with dimensions `(..., channel, channel)`.
        dim1 (int, optional): The first dimension of the diagonal matrix.
            (Default: ``-1``)
        dim2 (int, optional): The second dimension of the diagonal matrix.
            (Default: ``-2``)

    Returns:
        Tensor: The trace of the input Tensor.
    rL   z/The dimension of the tensor must be at least 2.z3The size of ``dim1`` and ``dim2`` must be the same.r   )rX  rY  r5   rr   )ndimr`   rC   r=   ZdiagonalrE   )r7   rX  rY  rI   rI   rJ   _compute_mat_trace(  s    r[  Hz>:0yE>)matregrS  r3   c                 C   sZ   |  d}tj|| j| jd}t| jd | }|| }| ||dddddf   } | S )a  Perform Tikhonov regularization (only modifying real part).

    Args:
        mat (torch.Tensor): Input matrix with dimensions `(..., channel, channel)`.
        reg (float, optional): Regularization factor. (Default: 1e-8)
        eps (float, optional): Value to avoid the correlation matrix is all-zero. (Default: ``1e-8``)

    Returns:
        Tensor: Regularized matrix with dimensions `(..., channel, channel)`.
    r5   r[   r   .N)r@   r=   eyer\   r]   r[  r   )r^  r_  rS  Cr`  epsilonrI   rI   rJ   _tik_reg;  s    
rc  )psd_spsd_nr3   c                 C   s   | j dkr|j dkstd|  r,| s4tdd| j d|j d | j|jksptd| j d|j d	| jd
 | jd kstd| j d	dS )a  Assertion checks of the PSD matrices of target speech and noise.

    Args:
        psd_s (torch.Tensor): The complex-valued power spectral density (PSD) matrix of target speech.
            Tensor with dimensions `(..., freq, channel, channel)`.
        psd_n (torch.Tensor): The complex-valued power spectral density (PSD) matrix of noise.
            Tensor with dimensions `(..., freq, channel, channel)`.
    r   zNExpected at least 3D Tensor (..., freq, channel, channel) for psd_s and psd_n.zJThe type of psd_s and psd_n must be ``torch.cfloat`` or ``torch.cdouble``.rT  z for psd_s and  for psd_n.z<The dimensions of psd_s and psd_n should be the same. Found z and r5  r5   r8   ;The last two dimensions of psd_s should be the same. Found N)rZ  r`   rM   r\   rC   )rd  re  rI   rI   rJ   _assert_psd_matricesP  s*    

rh  )rd  re  reference_channeldiagonal_loadingdiag_epsrS  r3   c           	   
   C   s   t | | |rt||d}tj|| }|t|d |  }tj|tr^|ddd|f }nPtj|t	r|
|j}td||dddddf g}ntdt| d|S )a+  Compute the Minimum Variance Distortionless Response (*MVDR* [:footcite:`capon1969high`]) beamforming weights
    by the method proposed by *Souden et, al.* [:footcite:`souden2009optimal`].

    .. devices:: CPU CUDA

    .. properties:: Autograd TorchScript

    Given the power spectral density (PSD) matrix of target speech :math:`\bf{\Phi}_{\textbf{SS}}`,
    the PSD matrix of noise :math:`\bf{\Phi}_{\textbf{NN}}`, and a one-hot vector that represents the
    reference channel :math:`\bf{u}`, the method computes the MVDR beamforming weight martrix
    :math:`\textbf{w}_{\text{MVDR}}`. The formula is defined as:

    .. math::
        \textbf{w}_{\text{MVDR}}(f) =
        \frac{{{\bf{\Phi}_{\textbf{NN}}^{-1}}(f){\bf{\Phi}_{\textbf{SS}}}}(f)}
        {\text{Trace}({{{\bf{\Phi}_{\textbf{NN}}^{-1}}(f) \bf{\Phi}_{\textbf{SS}}}(f))}}\bm{u}

    Args:
        psd_s (torch.Tensor): The complex-valued power spectral density (PSD) matrix of target speech.
            Tensor with dimensions `(..., freq, channel, channel)`.
        psd_n (torch.Tensor): The complex-valued power spectral density (PSD) matrix of noise.
            Tensor with dimensions `(..., freq, channel, channel)`.
        reference_channel (int or torch.Tensor): Specifies the reference channel.
            If the dtype is ``int``, it represents the reference channel index.
            If the dtype is ``torch.Tensor``, its shape is `(..., channel)`, where the ``channel`` dimension
            is one-hot.
        diagonal_loading (bool, optional): If ``True``, enables applying diagonal loading to ``psd_n``.
            (Default: ``True``)
        diag_eps (float, optional): The coefficient multiplied to the identity matrix for diagonal loading.
            It is only effective when ``diagonal_loading`` is set to ``True``. (Default: ``1e-7``)
        eps (float, optional): Value to add to the denominator in the beamforming weight formula.
            (Default: ``1e-8``)

    Returns:
        torch.Tensor: The complex-valued MVDR beamforming weight matrix with dimensions `(..., freq, channel)`.
    r_  r   .N...c,...c->...9Expected 'int' or 'Tensor' for reference_channel. Found: r5  )rh  rc  r=   linalgsolver[  jit
isinstancer   r   r   r\   rV  r6  type)	rd  re  ri  rj  rk  rS  	numeratorwsbeamform_weightsrI   rI   rJ   r!   i  s    ,
")rtfre  ri  rj  rk  rS  r3   c           
   	   C   s  | j dkstd| j d|j dks8td|j d|  rH| sPtdd| j d|j d	 | j|jd
d kstdd| j d|j d	 |jd |jd kstd|j d|rt||d}tj|| 	d
d}td|  |g}||j	d|  }|d
k	rtj|tr<| d|f  }	nTtj|tr|||j}td|  |dd
d
d
f g}	ntdt| d||	d  }|S )aS  Compute the Minimum Variance Distortionless Response (*MVDR* [:footcite:`capon1969high`]) beamforming weights
    based on the relative transfer function (RTF) and power spectral density (PSD) matrix of noise.

    .. devices:: CPU CUDA

    .. properties:: Autograd TorchScript

    Given the relative transfer function (RTF) matrix or the steering vector of target speech :math:`\bm{v}`,
    the PSD matrix of noise :math:`\bf{\Phi}_{\textbf{NN}}`, and a one-hot vector that represents the
    reference channel :math:`\bf{u}`, the method computes the MVDR beamforming weight martrix
    :math:`\textbf{w}_{\text{MVDR}}`. The formula is defined as:

    .. math::
        \textbf{w}_{\text{MVDR}}(f) =
        \frac{{{\bf{\Phi}_{\textbf{NN}}^{-1}}(f){\bm{v}}(f)}}
        {{\bm{v}^{\mathsf{H}}}(f){\bf{\Phi}_{\textbf{NN}}^{-1}}(f){\bm{v}}(f)}

    where :math:`(.)^{\mathsf{H}}` denotes the Hermitian Conjugate operation.

    Args:
        rtf (torch.Tensor): The complex-valued RTF vector of target speech.
            Tensor with dimensions `(..., freq, channel)`.
        psd_n (torch.Tensor): The complex-valued power spectral density (PSD) matrix of noise.
            Tensor with dimensions `(..., freq, channel, channel)`.
        reference_channel (int or torch.Tensor): Specifies the reference channel.
            If the dtype is ``int``, it represents the reference channel index.
            If the dtype is ``torch.Tensor``, its shape is `(..., channel)`, where the ``channel`` dimension
            is one-hot.
        diagonal_loading (bool, optional): If ``True``, enables applying diagonal loading to ``psd_n``.
            (Default: ``True``)
        diag_eps (float, optional): The coefficient multiplied to the identity matrix for diagonal loading.
            It is only effective when ``diagonal_loading`` is set to ``True``. (Default: ``1e-7``)
        eps (float, optional): Value to add to the denominator in the beamforming weight formula.
            (Default: ``1e-8``)

    Returns:
        torch.Tensor: The complex-valued MVDR beamforming weight matrix with dimensions `(..., freq, channel)`.
    rL   z@Expected at least 2D Tensor (..., freq, channel) for rtf. Found r5  r   zKExpected at least 3D Tensor (..., freq, channel, channel) for psd_n. Found zHThe type of rtf and psd_n must be ``torch.cfloat`` or ``torch.cdouble``.rT  z for rtf and rf  Nr5   z_The dimensions of rtf and the dimensions withou the last dimension of psd_n should be the same.r8   z;The last two dimensions of psd_n should be the same. Found rl  z...d,...d->....rm  rn  rG  )rZ  r`   rC   rM   r\   rc  r=   ro  rp  r   r   rV  rW  r   rq  rr  r   r   r   r6  rs  )
rw  re  ri  rj  rk  rS  rt  denominatorrv  r3  rI   rI   rJ   r"     s@    .
$)rd  r3   c                 C   s\   |   std| j d| jd | jd ks@td| j dtj| \}}|d }|S )a  Estimate the relative transfer function (RTF) or the steering vector by eigenvalue decomposition.

    .. devices:: CPU CUDA

    .. properties:: TorchScript

    Args:
        psd_s (Tensor): The complex-valued power spectral density (PSD) matrix of target speech.
            Tensor of dimension `(..., freq, channel, channel)`

    Returns:
        Tensor: The estimated complex-valued RTF of target speech.
        Tensor of dimension `(..., freq, channel)`
    zGThe type of psd_s must be ``torch.cfloat`` or ``torch.cdouble``. Found r5  r5   r8   rg  ).r5   )rM   r`   r\   rC   r=   ro  Zeigh)rd  rj   vrw  rI   rI   rJ   r#     s    r   )rd  re  ri  rW   rj  rk  r3   c           	   
   C   s   t | | |dkstd|r*t||d}tj|| }tj|trT|d|f }nPtj|t	r|
|j}td||dddddf g}ntdt| d|d	}|d
krt|d
 D ]}t||}qt| |}nt||}|d	S )a  Estimate the relative transfer function (RTF) or the steering vector by the power method.

    .. devices:: CPU CUDA

    .. properties:: Autograd TorchScript

    Args:
        psd_s (torch.Tensor): The complex-valued power spectral density (PSD) matrix of target speech.
            Tensor with dimensions `(..., freq, channel, channel)`.
        psd_n (torch.Tensor): The complex-valued power spectral density (PSD) matrix of noise.
            Tensor with dimensions `(..., freq, channel, channel)`.
        reference_channel (int or torch.Tensor): Specifies the reference channel.
            If the dtype is ``int``, it represents the reference channel index.
            If the dtype is ``torch.Tensor``, its shape is `(..., channel)`, where the ``channel`` dimension
            is one-hot.
        diagonal_loading (bool, optional): If ``True``, enables applying diagonal loading to ``psd_n``.
            (Default: ``True``)
        diag_eps (float, optional): The coefficient multiplied to the identity matrix for diagonal loading.
            It is only effective when ``diagonal_loading`` is set to ``True``. (Default: ``1e-7``)

    Returns:
        torch.Tensor: The estimated complex-valued RTF of target speech.
        Tensor of dimension `(..., freq, channel)`.
    r   z/The number of iteration must be greater than 0.rl  .rm  Nrn  r5  r5   rL   )rh  r`   rc  r=   ro  rp  rq  rr  r   r   r   r\   rV  r6  rs  r   rf   matmulr   )	rd  re  ri  rW   rj  rk  phirw  rj   rI   rI   rJ   r$     s$     
"
)rv  rV   r3   c                 C   s   | j dd |j dd ks$tdd| j  d|j  d |  rJ| sRtdd| j d|j d td	|  |g}|S )
a  Apply the beamforming weight to the multi-channel noisy spectrum to obtain the single-channel enhanced spectrum.

    .. devices:: CPU CUDA

    .. properties:: Autograd TorchScript

    .. math::
        \hat{\textbf{S}}(f) = \textbf{w}_{\text{bf}}(f)^{\mathsf{H}} \textbf{Y}(f)
    where :math:`\textbf{w}_{\text{bf}}(f)` is the beamforming weight for the :math:`f`-th frequency bin,
    :math:`\textbf{Y}` is the multi-channel spectrum for the :math:`f`-th frequency bin.

    Args:
        beamform_weights (Tensor): The complex-valued beamforming weight matrix.
            Tensor of dimension `(..., freq, channel)`
        specgram (Tensor): The multi-channel complex-valued noisy spectrum.
            Tensor of dimension `(..., channel, freq, time)`

    Returns:
        Tensor: The single-channel complex-valued enhanced spectrum.
            Tensor of dimension `(..., freq, time)`
    Nr8   rq   zUThe dimensions except the last two dimensions of beamform_weights should be the same rT  z for beamform_weights and rU  zXThe type of beamform_weights and specgram must be ``torch.cfloat`` or ``torch.cdouble``.z...fc,...cft->...ft)rC   r`   rM   r\   r=   rV  rW  )rv  rV   Zspecgram_enhancedrI   rI   rJ   r%   P  s    )Tr&   TN)Tr&   T)N)r{   )r{   )Nr{   )r:   )r:   )r   r   )r   )r   r   r   r   )r   r   FF)TNNN)r  ry   r	  r
  ry   rz   r  r  r  r  rZ   r   r   r   Fr  T)r#  r   r$  N)r>  r?  NNN)r>  r?  NNN)r5   r5   rI  )NTrQ  )r5   r8   )r\  r]  )Tr\  r]  )NTr\  r]  )r   Tr\  )Hr   r   r;   collections.abcr   typingr   r   r   r   r=   r  r   Ztorchaudio._internalr   Z
_mod_utils__all__r   rS   boolstrr	   r
   r\   rU   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   Zrequires_soxr   Zrequires_kaldir   r]   r4  r8  r   rq  Zunusedr   r   rB  rC  r   r    r[  rc  rh  r!   r"   r#   r$   r%   rI   rI   rI   rJ   <module>   s  ,    a   Ld     +""   I.!J @ @5/.
    /    ^-    +                 uY"    9-     3     5   ;   ,   
B    R   
>