Fast audio resampling library for C and C++.

This library focuses on speed at the expense of audio quality, for scenarios where correct audio processing is not needed. For that it takes many shortcuts to reduce processing and latency.

If you are looking for a high quality resampling library for offline audio processing, or where audio quality is more important than performance, this project is not suited. Look at a resampler like the Opus Silk resampler instead.

C

#include "libfar.h"

// Upsample float stereo audio from 22050 Hz to 44100 Hz.
byte32* upsample(const byte32* buffer, size_t size)
{
  const size_t size_out = size * 2;
  const size_t aligned_size_out = (size_out + 31) & ~(size_t)31;
  char32* buf_out = far_malloc_align32(aligned_size_out);
  const int num_channels = 2; // stereo
  far_upsample2f32(buffer, size, 22050, num_channels, buf_out, size_out);
  return buf_out;
}

C++

#include "libfar.h"

// Convert int16 48kHz audio from mono to stereo.
short512* mono_to_stereo(const short512* buffer, size_t size)
{
  const size_t size_out = size * 2;
  const size_t aligned_size_out = (size_out + 63) & ~(size_t)63;
  short512* buf_out = libfar::malloc_align(aligned_size_out, 64);
  libfar::adapt_ch1x2s16(buffer, size, 48000, buf_out, size_out);
  return buf_out;
}

Internally functions names are wrapped into the FAR_FN macro to allow inserting an optional prefix for C usage (defined by FAR_FN_PREFIX).

C

Functions are prefixed with FAR_FN_PREFIX, which defaults to far_ but can be redefined by the user:

far_upsample2f32(...);

C++

Functions are enclosed inside the libfar namespace:

libfar::upsample2f32(...);

The FAR_FN_PREFIX preprocessor definition is ignored.

libfar supports 3 different audio sample types:

C

In C, there is no built-in boolean type. As a fallback, libfar defines a far_bool type backed by an int32_t type and equal to 0 for false and -1 (bit pattern 0xFFFFFFFF) for true.

typedef int32_t far_bool;
#define far_true ((far_bool)-1)
#define far_false ((far_bool)0)

C++

In C++ for convenience far_bool is an alias of the built-in boolean type bool. Developers are encouraged to use bool directly.

using far_bool = bool;
constexpr bool far_true = true;
constexpr bool far_false = false;

Buffers are over-aligned compared to standard C/C++ rules to improve performance with SIMD. Special types aliases are defined for those buffers to make the alignment requirement explicit via the type name. There is currently no compile-time check, and it is still possible to pass the wrong type, so developers should be careful.

*Unspecified sample types indicate only an alignment, without specifying an actual type. This is useful for functions which can operate on any sample type, but still require an aligned buffer.

Typically the following SIMD implementations requires some specific alignment:

• SSE, SSE2, ..., SSE4.2 : 16 bytes (128 bits)
• AVX, AVX2 : 32 bytes (256 bits)
• AVX512 : 64 bytes (512 bits)

Types of a given alignment can safely be cast to a lower alignment. Therefore most generic dispatching functions take some 64-byte aligned buffers to not lose any generality.

C++

// Generic dispatcher function func1().
byte16* ptr16 = ...
libfar::func1((const byte4*)ptr16, ...); // OK; cast to lower alignment.

// Specific SSE implementation of func1()
byte16* ptr16 = ...
libfar::func1_sse(ptr16, ...); // OK; SSE explicitly requires 16-byte alignment.

Default allocators are based on the standard library's aligned_alloc(). Custom allocators can be defined by defining the FAR_CUSTOM_ALLOCATORS preprocessor symbol to avoid defining the built-in allocators, and defining them manually instead.

Note: If defining the allocators generically for both C and C++, remember to use the FAR_FN() macro. Otherwise you can use directly the prefix (default: far_) for C or the namespace (libfar) for C++.

char* FAR_FN(malloc_align)(size_t size, size_t align) {
  // ...
}

void FAR_FN(free_align)(void* ptr) {
  // ...
}

byte32* FAR_FN(malloc_align32)(size_t size) {
  // ...
}

void FAR_FN(free_align32)(byte32* ptr) {
  // ...
}

C++

On C++ only, some templated versions are provided for convenience, which deduct the alignment from the sample type alias.

short512* buffer = libfar::malloc_align<short512>(size); // 64-byte aligned
float128* buffer = libfar::malloc_align<float128>(size); // 16-byte aligned

Change the sample rate by an integral factor.

C

size_t size_out = 3 * size_in;
float512* buf_out =(float512*)far_malloc_align64(size_out);
far_upsample3f32(buf_in, size_in, 48000, 2, buf_out, size_out);

C++

size_t size_out = size_in / 2;
float512* buf_out = libfar::malloc_align<float512>(size_out);
libfar::downsample2f32(buf_in, size_in, 44100, 1, buf_out, size_out);

Change the number of audio channels.

Utilities for allocating and deallocating aligned memory buffers.

C++

In C++, an extra templated helper is available which deduces the alignment from the type alias, which redirects to the corresponding malloc_alignN() variant, where N is the deduced alignment.

template <typename T>
T* malloc_align(size_t size);

The template is only instantiated for the intX and floatX type aliases.

Utilities to detect CPU features at runtime and dynamically select the fastest implementation of each library function available on the current host CPU. This is generally used internally only.