DOCSEARCHbyAlgolia
Submit Docs

libsamplerate (Secret Rabbit Code)

repository·master·Indexed 20 days ago

https://github.com/libsndfile/libsamplerate

A specialized library for high-quality sample rate conversion of audio data. Version 0.2.2 provides multiple conversion algorithms ranging from high-quality sinc-based interpolators to high-speed linear converters. It features a full API for streaming data via the SRC_DATA struct, a callback-based API for custom data retrieval, and tools for generating filter coefficients using GNU Octave.

Tokens
7.4K
Snippets
26
Records
42
Agent score
72%

What's inside libsamplerate

  2. Use the SRC_DATA struct to pass audio data

    master

    The SRC_DATA struct is the primary mechanism for passing audio buffers and control parameters to the sample rate converter in both simple and full-featured API modes.

    Field Definitions

    FieldTypeDescription
    data_inconst float *Pointer to the input audio data array.
    data_outfloat *Pointer to the array where the converter will write output data.
    input_frameslongNumber of input frames provided in data_in.
    output_frameslongMaximum number of output frames the data_out array can hold.
    input_frames_usedlong[Output] Set by the converter; number of frames actually consumed from data_in.
    output_frames_genlong[Output] Set by the converter; number of frames actually generated in data_out.
    end_of_inputintSet to 1 if this is the last buffer; otherwise 0. Used with src_process.
    src_ratiodoubleThe conversion ratio (output_rate / input_rate). Supports time-varying conversion via linear interpolation between calls.

    Important Notes

    • Multichannel Data: For multichannel audio, data_in and data_out must point to a single array of interleaved data. The input_frames and output_frames values should be the number of frames (total samples divided by the number of channels), not the total number of samples.
    • Buffer Management: Always check input_frames_used and output_frames_gen after a call to src_process to know how much data was actually processed.
    typedef struct
{
    const float  *data_in;
    float *data_out ;

    long   input_frames, output_frames ;
    long   input_frames_used, output_frames_gen ;

    int    end_of_input ;

    double src_ratio ;
} SRC_DATA ;

  3. Handle transport delay in SRC_SINC_* converters

    master

    Converters like SRC_SINC_* introduce a transport delay. For example, if you input 1000 samples with a 2x upsampling ratio, the first call to src_process() might return fewer than 2000 samples (e.g., 1900) due to this delay. Subsequent calls will typically return the expected ratio.

    Best Practice: To ensure you always receive the required number of output samples, always supply more input samples than are strictly necessary. Always track the number of input frames used via the return values of src_process() to manage your buffers correctly.

  4. Handle potential audio clipping in libsamplerate output

    master

    The output of libsamplerate may contain peak values that exceed the input range, even if the input is strictly within (-1.0, 1.0). This occurs because interpolation (e.g., upsampling) can create values larger than the original samples.

    Action: Always normalize the output of libsamplerate before saving it to fixed-point formats like 16-bit WAV files to prevent clipping.

  5. Implement a src_callback_t callback function

    master

    When implementing the src_callback_t function for the callback API, follow these rules:

    1. Signature: The function must match long (*src_callback_t) (void *cb_data, float **data).
    2. Data Access: The data parameter is a pointer to a pointer to floats. You should populate the memory pointed to by *data with your input samples.
    3. Multi-channel Data: If the converter is configured for multiple channels, your callback must provide interleaved data.
    4. Return Value: The function must return the number of frames supplied to the converter.
      • For multi-channel data, the number of frames is the total number of floats divided by the number of channels.
      • Returning 0 signals to the converter that no more input data is available.
    typedef long (*src_callback_t) (void *cb_data, float **data) ;

  6. Common components across libsamplerate interfaces

    master

    Regardless of which interface you choose (Simple, Full, or Callback), the following components are shared across the library:

    • Error reporting mechanism: Standardized way to handle issues.
    • Converter types: The various algorithms available for sample rate conversion.
    • SRC_DATA struct: The primary data structure used for processing.
    • Auxiliary functions: Tools for converting arrays of float data to and from short data (since the core API operates on floats).

  7. Choose an API access method

    master

    libsamplerate provides three distinct interfaces depending on your application's requirements. All three methods support multi-channel interleaved data and operate on buffers of ISO C Standard float data.

    1. Simple Interface: Best for converting a single block of samples (one or more channels) in one operation. It is less capable than the other interfaces.
    2. Full Interface: Designed for streaming data, allowing for time-varying sample rate conversion.
    3. Callback Interface: Provides the same functionality as the Full Interface but separates input and output details. The library calls a user-supplied callback function to obtain input when a read function is called. This is ideal for applications where the output sample rate varies over time.

  8. Understanding Sample Rate Converter (SRC) quality metrics

    master

    When evaluating the performance of a Sample Rate Converter (SRC), three primary metrics are used to determine quality:

    1. Signal-to-Noise Ratio (SNR): Measures the amount of noise added during the conversion process, expressed in decibels (dB). A higher SNR is better. Note that SNR varies based on the input signal and the conversion ratio; for valid comparisons between different converters, compare their worst-case scenarios.
    2. Bandwidth: Measures high-frequency attenuation. It is typically calculated as the frequency where attenuation reaches -3dB, expressed as a percentage of the full bandwidth available at that sampling rate.
    3. Speed: The computational efficiency of the conversion process; faster is better.

  9. Precision of src_ratio for long-running conversions

    master

    The src_ratio field uses double-precision floating point numbers. For long-running conversions, the precision of this ratio is sufficient to prevent cumulative errors.

    Even for extremely long durations (e.g., over 1,400 years at 96kHz), the error introduced by the floating-point ratio is significantly smaller than the inaccuracies found in standard hardware crystal oscillators used for sampling.

  10. Avoid using src_simple() for streaming or small chunks

    master

    The src_simple() function is designed for processing a whole audio file at once.

    Do not use src_simple() for:

    • Processing successive blocks of a continuous stream.
    • Processing small chunks (e.g., 160 frames) if high quality is required.

    Instead, use:

    • The src_process() API.
    • The callback-based API.

  11. Subscribe to the Secret Rabbit Code mailing lists

    master

    You can join the Secret Rabbit Code (libsamplerate) mailing lists to receive announcements or participate in general discussions.

    • Announcements: To receive read-only project announcements, subscribe to src-announce@mega-nerd.com.
    • General Discussion: To participate in general discussions (which also include announcements), subscribe to src@mega-nerd.com. Note that posting to this list is restricted to subscribers.
    To subscribe, send an email to:
- src-announce-request@mega-nerd.com (Announcements)
- src-request@mega-nerd.com (General list)

With the subject: subscribe

  12. Install dependencies for libsamplerate examples and tests on Win32

    master

    If you intend to build the examples and tests provided with libsamplerate, you must install the following dependencies:

    • libsndfile
    • fftw3

    The recommended method for installation on Windows is using the Vcpkg package manager.

    # Example using vcpkg (commands vary by installation)
vcpkg install libsndfile fftw3