# Core functionality

Core resampling interface

resampy.core.resample(x, sr_orig, sr_new, axis=-1, filter='kaiser_best', parallel=False, **kwargs)

  Resample a signal x from sr_orig to sr_new along a given axis.

  Parameters:
    x np.ndarray, dtype=np.float*

      The input signal(s) to resample.

    sr_orig int > 0

      The sampling rate of x

    sr_new int > 0

      The target sampling rate of the output signal(s)

      If sr_new == sr_orig, then a copy of x is returned with no interpolation performed.

    axis int

      The target axis along which to resample x

    filter optional, str or callable

      The resampling filter to use.

      By default, uses the kaiser_best (pre-computed filter).

    parallel optional, bool

      Enable/disable parallel computation exploiting multi-threading.

      Default: False.

    **kwargs

      additional keyword arguments provided to the specified filter

  Returns:
    y np.ndarray

      x resampled to sr_new

  Raises:
    ValueError

      if sr_orig or sr_new is not positive

    TypeError

      if the input signal x has an unsupported data type.

  Examples

      >>> import resampy
      >>> np.set_printoptions(precision=3, suppress=True)
      >>> # Generate a sine wave at 440 Hz for 5 seconds
      >>> sr_orig = 44100.0
      >>> x = np.sin(2 * np.pi * 440.0 / sr_orig * np.arange(5 * sr_orig))
      >>> x
      array([ 0.   ,  0.063, ..., -0.125, -0.063])
      >>> # Resample to 22050 with default parameters
      >>> resampy.resample(x, sr_orig, 22050)
      array([ 0.011,  0.122,  0.25 , ..., -0.366, -0.25 , -0.122])
      >>> # Resample using the fast (low-quality) filter
      >>> resampy.resample(x, sr_orig, 22050, filter='kaiser_fast')
      array([ 0.012,  0.121,  0.251, ..., -0.365, -0.251, -0.121])
      >>> # Resample using a high-quality filter
      >>> resampy.resample(x, sr_orig, 22050, filter='kaiser_best')
      array([ 0.011,  0.122,  0.25 , ..., -0.366, -0.25 , -0.122])
      >>> # Resample using a Hann-windowed sinc filter
      >>> import scipy.signal
      >>> resampy.resample(x, sr_orig, 22050, filter='sinc_window',
      ...                  window=scipy.signal.windows.hann)
      array([ 0.011,  0.123,  0.25 , ..., -0.366, -0.25 , -0.123])

      >>> # Generate stereo data
      >>> x_right = np.sin(2 * np.pi * 880.0 / sr_orig * np.arange(len(x)))
      >>> x_stereo = np.stack([x, x_right])
      >>> x_stereo.shape
      (2, 220500)
      >>> # Resample along the time axis (1)
      >>> y_stereo = resampy.resample(x_stereo, sr_orig, 22050, axis=1)
      >>> y_stereo.shape
      (2, 110250)

resampy.core.resample_nu(x, sr_orig, t_out, axis=-1, filter='kaiser_best', parallel=False, **kwargs)

  Interpolate a signal x at specified positions (t_out) along a given axis.

  Parameters:
    x np.ndarray, dtype=np.float*

      The input signal(s) to resample.

    sr_orig float

      Sampling rate of the input signal (x).

    t_out np.ndarray, dtype=np.float*

      Position of the output samples.

    axis int

      The target axis along which to resample x

    filter optional, str or callable

      The resampling filter to use.

      By default, uses the kaiser_best (pre-computed filter).

    parallel optional, bool

      Enable/disable parallel computation exploiting multi-threading.

      Default: True.

    **kwargs

      additional keyword arguments provided to the specified filter

  Returns:
    y np.ndarray

      x resampled to t_out

  Raises:
    TypeError

      if the input signal x has an unsupported data type.

  Notes

  Differently form the resample function the filter rolloff is not automatically adapted in case of subsampling. For this reason results obtained with the resample_nu could be slightly different form the ones obtained with resample if the filter parameters are not carefully set by the user.

  Examples

      >>> import resampy
      >>> np.set_printoptions(precision=3, suppress=True)
      >>> # Generate a sine wave at 100 Hz for 5 seconds
      >>> sr_orig = 100.0
      >>> f0 = 1
      >>> t = np.arange(5 * sr_orig) / sr_orig
      >>> x = np.sin(2 * np.pi * f0 * t)
      >>> x
      array([ 0.   ,  0.063,  0.125, ..., -0.187, -0.125, -0.063])
      >>> # Resample to non-uniform sampling
      >>> t_new = np.log2(1 + t)[::5] - t[0]
      >>> resampy.resample_nu(x, sr_orig, t_new)
      array([ 0.001,  0.427,  0.76 , ..., -0.3  , -0.372, -0.442])

# Filters

## Filter construction and loading.

resampy provides two pre-computed resampling filters which are tuned for either high-quality or fast calculation. These filters are constructed by the create_filters.py script.

> - kaiser_best :

>     > Parameters for kaiser_best: > —————————————- > beta = 12.9846 > roll = 0.917347 > # zeros = 50 > precision = 13 > attenuation = -120.0 > —————————————-

> - kaiser_fast :

>     > Parameters for kaiser_fast: > —————————————- > beta = 9.90322 > roll = 0.868212 > # zeros = 24 > precision = 9 > attenuation = -93.0 > —————————————-

These filters can be used by calling resample as follows:

    >>> # High-quality
    >>> resampy.resample(x, sr_orig, sr_new, filter='kaiser_best')
    >>> # Fast calculation
    >>> resampy.resample(x, sr_orig, sr_new, filter='kaiser_fast')

It is also possible to construct custom filters as follows:

    >>> resampy.resample(x, sr_orig, sr_new, filter='sinc_window',
    ...                  **kwargs)

where `**kwargs` are additional parameters to sinc_window.

resampy.filters.clear_cache()

  Clear the filter cache.

  Calling this function will ensure that packaged filters are reloaded upon the next usage.

resampy.filters.get_filter(name_or_function, **kwargs)

  Retrieve a window given its name or function handle.

  Parameters:
    name_or_function str or callable

      If a function, returns name_or_function(**kwargs).

      If a string, and it matches the name of one of the defined filter functions, the corresponding function is called with **kwargs.

      If a string, and it matches the name of a pre-computed filter, the corresponding filter is retrieved, and kwargs is ignored.

      Valid pre-computed filter names are:

        - ‘kaiser_fast’

        - ‘kaiser_best’

    **kwargs

      Additional keyword arguments passed to name_or_function (if callable)

  Returns:
    half_window np.ndarray

      The right wing of the interpolation filter

    precision int > 0

      The number of samples between zero-crossings of the filter

    rolloff float > 0

      The roll-off frequency of the filter as a fraction of Nyquist

  Raises:
    NotImplementedError

      If name_or_function cannot be found as a filter.

resampy.filters.sinc_window(num_zeros=64, precision=9, window=None, rolloff=0.945)

  Construct a windowed sinc interpolation filter

  Parameters:
    num_zeros int > 0

      The number of zero-crossings to retain in the sinc filter

    precision int > 0

      The number of filter coefficients to retain for each zero-crossing

    window callable

      The window function. By default, uses a Hann window.

    rolloff float > 0

      The roll-off frequency (as a fraction of nyquist)

  Returns:
    interp_window: np.ndarray [shape=(num_zeros * num_table + 1)]

      The interpolation window (right-hand side)

    num_bits: int

      The number of bits of precision to use in the filter table

    rolloff float > 0

      The roll-off frequency of the filter, as a fraction of Nyquist

  Raises:
    TypeError

      if window is not callable or None

    ValueError

      if num_zeros < 1, precision < 1, or rolloff is outside the range (0, 1].

  Examples

      >>> import scipy, scipy.signal
      >>> import resampy
      >>> np.set_printoptions(threshold=5, suppress=False)
      >>> # A filter with 10 zero-crossings, 32 samples per crossing, and a
      >>> # Hann window for tapering.
      >>> halfwin, prec, rolloff = resampy.filters.sinc_window(num_zeros=10, precision=5,
      ...                                                      window=scipy.signal.windows.hann)
      >>> halfwin
      array([  9.450e-01,   9.436e-01, ...,  -7.455e-07,  -0.000e+00])
      >>> prec
      32
      >>> rolloff
      0.945

      >>> # Or using sinc-window filter construction directly in resample
      >>> y = resampy.resample(x, sr_orig, sr_new, filter='sinc_window',
      ...                      num_zeros=10, precision=5,
      ...                      window=scipy.signal.windows.hann)