PYTHON-SAMPLERATE(1)

NAME
python-samplerate - python-samplerate Documentation [image]
 <https://pypi.python.org/pypi/samplerate>[image]
 <https://pypi.python.org/pypi/samplerate>[image]
 <https://pypi.python.org/pypi/samplerate>[image]
 <https://pypi.python.org/pypi/samplerate>[image: Documentation Status] [image]
 <http://python-samplerate.readthedocs.io/en/latest/?badge=latest>

This is a wrapper around Erik de Castro Lopo's libsamplerate <http://www.mega-nerd.com/libsamplerate/> (aka Secret Rabbit Code) for high-quality sample rate conversion.

It implements all three APIs <http://www.mega-nerd.com/libsamplerate/api.html> available in libsamplerate <http://www.mega-nerd.com/libsamplerate/>:

    •   Simple API: for resampling a large chunk of data with a single library call

    •   Full API: for obtaining the resampled signal from successive chunks of data

    •   Callback API: like Full API, but input samples are provided by a callback function

The libsamplerate <http://www.mega-nerd.com/libsamplerate/> library is statically built together with the python bindings using pybind11 <https://github.com/pybind/pybind11/>.

INSTALLATION
        $ pip install samplerate

Binary wheels of libsamplerate <http://www.mega-nerd.com/libsamplerate/> are available for macOS (x86_64, arm64), Linux (x86_64, aarch64), and Windows (x86_64). Building from source on other platforms requires a C++14 or later compiler.

USAGE

            import numpy as np
            import samplerate

            # Synthesize data
            fs = 1000.
            t = np.arange(fs * 2) / fs
            input_data = np.sin(2 * np.pi * 5 * t)

            # Simple API
            ratio = 1.5
            converter = 'sinc_best'  # or 'sinc_fastest', ...
            output_data_simple = samplerate.resample(input_data, ratio, converter)

            # Full API
            resampler = samplerate.Resampler(converter, channels=1)
            output_data_full = resampler.process(input_data, ratio, end_of_input=True)

            # The result is the same for both APIs.
            assert np.allclose(output_data_simple, output_data_full)

            # See `samplerate.CallbackResampler` for the Callback API, or
            # `examples/play_modulation.py` for an example.

See samplerate.resample, samplerate.Resampler, and samplerate.CallbackResampler in the API documentation for details.

SEE ALSO

    •   scikits.samplerate <https://pypi.python.org/pypi/scikits.samplerate> implements only the Simple API and uses Cython <http://cython.org/> for extern calls. The resample function of scikits.samplerate and this package share the same function signature for compatiblity.

    •   resampy <https://github.com/bmcfee/resampy>: sample rate conversion in Python + Cython.

LICENSE

This project is licensed under the MIT license <https://opensource.org/licenses/MIT>.

As of version 0.1.9, libsamplerate <http://www.mega-nerd.com/libsamplerate/> is licensed under the 2-clause BSD license <https://opensource.org/licenses/BSD-2-Clause>.

API DOCUMENTATION

  samplerate module documentation

  samplerate -- Python bindings for libsamplerate based on CFFI and NumPy

  Simple API

    samplerate.resample()
        See samplerate.converters.resample() <#samplerate.converters.resample>.

  Full API

    class samplerate.Resampler
        See samplerate.converters.Resampler() <#samplerate.converters.Resampler>.

  Callback API

    class samplerate.CallbackResampler
        See samplerate.converters.CallbackResampler() <#samplerate.converters.CallbackResampler>.

  Exceptions

    class samplerate.ResamplingError
        See samplerate.converters.CallbackResampler() <#samplerate.converters.CallbackResampler>.

  samplerate.converters -- Sample rate converters

  Converter types

    class samplerate.converters.ConverterType
            Enum of samplerate converter types.

            Pass any of the members, or their string or value representation, as converter_type in the resamplers.

    Members:
            sinc_best

            sinc_medium

            sinc_fastest

            zero_order_hold

            linear

        linear = <ConverterType.linear: 4>

        ConverterType.name -> str

        sinc_best = <ConverterType.sinc_best: 0>

        sinc_fastest = <ConverterType.sinc_fastest: 2>

        sinc_medium = <ConverterType.sinc_medium: 1>

        property value

        zero_order_hold = <ConverterType.zero_order_hold: 3>

  Sample rate converters

  Simple

    samplerate.converters.resample(input: Annotated[numpy.typing.ArrayLike, numpy.float32], ratio: SupportsFloat, converter_type: object = 'sinc_best', verbose: bool = False) -> numpy.typing.NDArray[numpy.float32]
        Resample the signal in input_data at once.

        Parameters

            •   input_data (ndarray) -- Input data. Input data with one or more channels is represented as a 2D array of shape (num_frames, num_channels). A single channel can be provided as a 1D array of num_frames length. For use with libsamplerate, input_data is converted to 32-bit float and C (row-major) memory order.

            •   ratio (float) -- Conversion ratio = output sample rate / input sample rate.

            •   converter_type (ConverterType <#samplerate.converters.ConverterType>, str, or int) -- Sample rate converter (default: sinc_best).

            •   verbose (bool) -- If True, print additional information about the conversion.

        Returns
            output_data -- Resampled input data.

        Return type
            ndarray

    Note:
            If samples are to be processed in chunks, Resampler and CallbackResampler will provide better results and allow for variable conversion ratios.

  Full API

    class samplerate.converters.Resampler
        Resampler.

        Parameters

            •   converter_type (ConverterType <#samplerate.converters.ConverterType>, str, or int) -- Sample rate converter (default: sinc_best).

            •   num_channels (int) -- Number of channels.

        property channels
            Number of channels.

        clone(self: samplerate.converters.Resampler <#samplerate.converters.Resampler>) -> samplerate.converters.Resampler <#samplerate.converters.Resampler>
            Creates a copy of the resampler object with the same internal state.

        property converter_type
            Converter type.

        process(self: samplerate.converters.Resampler <#samplerate.converters.Resampler>, input: Annotated[numpy.typing.ArrayLike, numpy.float32], ratio: SupportsFloat, end_of_input: bool = False) -> numpy.typing.NDArray[numpy.float32]
            Resample the signal in input_data.

            Parameters

                •   input_data (ndarray) -- Input data. Input data with one or more channels is represented as a 2D array of shape (num_frames, num_channels). A single channel can be provided as a 1D array of num_frames length. For use with libsamplerate, input_data is converted to 32-bit float and C (row-major) memory order.

                •   ratio (float) -- Conversion ratio = output sample rate / input sample rate.

                •   end_of_input (int) -- Set to True if no more data is available, or to False otherwise.

                •   verbose (bool) -- If True, print additional information about the conversion.

            Returns
                output_data -- Resampled input data.

            Return type
                ndarray

        reset(self: samplerate.converters.Resampler <#samplerate.converters.Resampler>) -> None
            Reset internal state.

        set_ratio(self: samplerate.converters.Resampler <#samplerate.converters.Resampler>, arg0: SupportsFloat) -> None
            Set a new conversion ratio immediately.

  Callback API

    class samplerate.converters.CallbackResampler
        CallbackResampler.

        Parameters

            •   callback (function) -- Function that returns new frames on each call, or None otherwise. Input data with one or more channels is represented as a 2D array of shape (num_frames, num_channels). A single channel can be provided as a 1D array of num_frames length. For use with libsamplerate, input_data is converted to 32-bit float and C (row-major) memory order.

            •   ratio (float) -- Conversion ratio = output sample rate / input sample rate.

            •   converter_type (ConverterType <#samplerate.converters.ConverterType>, str, or int) -- Sample rate converter.

            •   channels (int) -- Number of channels.

        property channels
            Number of channels.

        clone(self: samplerate.converters.CallbackResampler <#samplerate.converters.CallbackResampler>) -> samplerate.converters.CallbackResampler <#samplerate.converters.CallbackResampler>
            Create a copy of the resampler object.

        property converter_type
            Converter type.

        property ratio
            Conversion ratio = output sample rate / input sample rate.

        read(self: samplerate.converters.CallbackResampler <#samplerate.converters.CallbackResampler>, num_frames: SupportsInt) -> numpy.typing.NDArray[numpy.float32]
            Read a number of frames from the resampler.

            Parameters
                num_frames (int) -- Number of frames to read.

            Returns
                output_data -- Resampled frames as a (num_output_frames, num_channels) or (num_output_frames,) array. Note that this may return fewer frames than requested, for example when no more input is available.

            Return type
                ndarray

        reset(self: samplerate.converters.CallbackResampler <#samplerate.converters.CallbackResampler>) -> None
            Reset state.

        set_starting_ratio(self: samplerate.converters.CallbackResampler <#samplerate.converters.CallbackResampler>, arg0: SupportsFloat) -> None
            Set the starting conversion ratio for the next read call.

  samplerate.exceptions -- Sample rate exceptions

    class samplerate.exceptions.ResamplingError

CHANGE LOG

  Change Log

  0.1.0

    •   Initial release.

INDICES AND TABLES

    •   Index <>

    •   Module Index <>

    •   Search Page <>

Author
Tino Wagner

Copyright
2017, Tino Wagner