Repository files navigation

Open source (under the MIT license) high-quality professional audio samplerate converter (SRC) / resampler C++ library. Features routines for SRC,both up- and downsampling, to/from any sample rate, including non-integersample rates: it can be also used for conversion to/from SACD/DSD samplerates, and even go beyond that. SRC routines were implemented in a portable,multi-platform C++ code, and have a high level of optimality. Also suitablefor fast general-purpose 1D time-series resampling / interpolation (withrelaxed filter parameters).

The structure of this library's objects is such that they can be frequentlycreated and destroyed in large applications with a minimal performance impactdue to a high level of reusability of its most "initialization-expensive"objects: the fast Fourier transform and FIR filter objects.

The SRC algorithm at first produces 2X oversampled (relative to the sourcesample rate, or the destination sample rate if the downsampling is performed)signal, then performs interpolation using a bank of short (8 to 30 taps,depending on the required precision) polynomial-interpolated sincfunction-based fractional delay filters. This puts the algorithm into theleague of the fastest among the most precise SRC algorithms. The more precisealternative being only the whole number-factored SRC, which can be slower.

P.S. Please credit the creator of this library in your documentation in thefollowing way: "Sample rate converter designed by Aleksey Vaneev of Voxengo".

C++ compiler and system with the "double" floating-point type (53-bitmantissa) support. No explicit code for the "float" type is present in thislibrary, because as practice has shown, the "float"-based code performsconsiderably slower on a modern processor, at least in this library. Thislibrary does not have dependencies beside the standard C library, the"windows.h" on Windows and the "pthread.h" on macOS and Linux.

The sample rate converter (resampler) is represented by ther8b::CDSPResampler class, which is a single front-end class for thewhole library. You do not basically need to use nor understand any otherclasses beside this class. Several derived classes that have varying levelsof precision are also available (for full-resolution 16-bit and 24-bitresampling).

• Documentation

The code of the library resides in the "r8b" C++ namespace, effectivelyisolating it from all other code. The code is thread-safe. A separateresampler object should be created for each audio channel or stream beingprocessed concurrently.

Note that you will need to compile the "r8bbase.cpp" source file and includethe resulting object file into your application build. This source fileincludes definitions of several global static objects used by the library.You may also need to include to your project: the "Kernel32" library (onWindows) and the "pthread" library on macOS and Linux.

The library is able to process signal of any scale and loudness: it is notlimited to just a "usual" -1.0 to 1.0 range.

By defining theR8B_IPP configuration macro it is possible to enable IntelIPP back-end for FFT functions, instead of the default Ooura FFT. IPP FFTmakes sample rate conversion faster by 23% on average.

#define R8B_IPP 1

If a larger initial processing delay and a very minor sample-timing error arenot an issue, for the most efficiency you can define these macros atthe beginning of ther8bconf.h file, or during compilation:

#define R8B_IPP 1#define R8B_FASTTIMING 1#define R8B_EXTFFT 1

If you do not have access to the Intel IPP then you may consider enabling thePFFFT which is only slightly slower than Intel IPP FFT in performance. Thereare two macros available:R8B_PFFFT andR8B_PFFFT_DOUBLE. The first macroenables PFFFT that works in single-precision resolution, thus limiting theoverall resampler's precision to 24-bit sample rate conversions (formission-critical professional audio applications, using theR8B_PFFFT macrois not recommended as its peak error is quite large). The second macroenables PFFFT implementation that works in double-precision resolution, makinguse of SSE2, AVX, and NEON intrinsics, yielding precision that is equal toboth Intel IPP and Ooura FFT implementations.

To use the PFFFT, define theR8B_PFFFT orR8B_PFFFT_DOUBLE macro, compileand include the suppliedpffft.cpp orpffft_double/pffft_double.c file toyour project build.

#define R8B_PFFFT 1or#define R8B_PFFFT_DOUBLE 1

The code of this library was commented in theDoxygenstyle. To generate the documentation locally you may run thedoxygen ./other/r8bdoxy.txt command from the library's folder.

Preliminary tests show that the r8b::CDSPResampler24 resampler class achieves38*n_cores Mrops (56*n_cores for Intel IPP FFT) when converting 1 channelof 24-bit audio from 44100 to 96000 sample rate (2% transition band), on aRyzen 3700X processor-based 64-bit system. This approximately translates to areal-time resampling of860*n_cores (1270*n_cores) audio streams, at 100%CPU load. Performance when converting to other sample rates may vary greatly.When comparing performance of this resampler library to another library makesure that the competing library is also tuned to produce a fully linear-phaseresponse, has similar stop-band characteristics and similar sample-timingprecision.

The functions of this SRC library are also accessible in simplified form viathe DLL file on Windows, requiring a processor with SSE2 support (Win64version includes AVX2 auto-dispatch code). Delphi Pascal interface unit filefor the DLL file is available. DLL and C LIB files are distributed in the DLLfolder on the project's homepage. On non-Windows systems it is preferrableto use the C++ library directly. Note that the DLL was compiled with theIntel IPP enabled.

The resampler class of this library was designed as an asynchronous processor:it may produce any number of output samples, depending on the input sampledata length and the resampling parameters. The resampler must be fed with theinput sample data until enough output sample data were produced, with anyexcess output samples used before feeding the resampler with more input data.A "relief" factor here is that the resampler removes the initial processinglatency automatically, and that after initial moments of processing the outputbecomes steady, with only minor output sample data length fluctuations.

So, while for an off-line resampling a "push" method can be used,demonstrated in theexample.cpp file, for a real-time resampling a "pull"method should be used which calls the resampling process until the outputbuffer is filled.

When using ther8b::CDSPResampler class directly, you may select thetransition band/steepness of the low-pass (reconstruction) filter, expressedas a percentage of the full spectral bandwidth of the input signal (or theoutput signal if the downsampling is performed), and the desired stop-bandattenuation in decibel.

The transition band is specified as the normalized spectral space of the inputsignal (or the output signal if the downsampling is performed) between thelow-pass filter's -3 dB point and the Nyquist frequency, and ranges from 0.5%to 45%. Stop-band attenuation can be specified in the range from 49 to 218decibel. Both the transition band and stop-band attenuation affectresampler's overall performance and initial output delay. For yourinformation, transition frequency range spans 175% of the specified transitionband, which means that for 2% transition band, frequency response below0.965*Nyquist is linear.

This SRC library also implements a much faster "power of 2" resampling (e.g.2X, 4X, 8X, 16X, 3X, 3*2X, 3*4X, 3*8X, etc. upsampling and downsampling),which is engaged automatically if the resampling parameters permit.

This library was tested for compatibility withGNU C++,Microsoft Visual C++,Clang andIntel C++compilers, on 32- and 64-bit Windows, macOS, and CentOS Linux.

Most code is "inline", without the need to compile many source files. Thememory footprint is quite modest.

For high-quality dithering you may consider usingPRVHASH PRNG which features an excellentpsycho-acoustic performance.

r8brain-free-src is bundled with the following code:

• FFT routines Copyright (c) 1996-2001 Takuya OOURA.Homepage
• PFFFT Copyright (c) 2013 Julien Pommier.Homepage
• PFFFT DOUBLE Copyright (c) 2020 Hayati Ayguen, Dario Mambro.Homepage

This library is used by:

• REAPER
• AUDIRVANA
• Red Dead Redemption 2
• Mini Piano Lite
• OpenMPT
• Boogex Guitar Amp audio plugin
• Voice Aloud Reader
• Zynewave Podium
• Phonometrica
• Ripcord
• TensorVox
• Curvessor
• Hang Loose Convolver
• Wave Breaker

Version 6.5:

• Made a fix to the getWholeStepping() function to permit GCD search forfractional sample rates lower than 1.0.
• Changed floating-point0x1pN constants not supported by some compilers,toe notation.

Version 6.4:

• Improved SSE detection macros.

Version 6.3:

• Improved the findGCD() function, to cover a wider range of sample rateratios.
• Added the R8B_DSPBASECLASS macro, to redefine the base class of non-cachedobjects.

Version 6.2:

• Fixed miscalculation in the recently introduced getInLenBeforeOutPos()function for minimum-phase filters.
• Fixed a mistake in the getInputRequiredForOutput() function.
• Fixed a long-standing mistake in LatencyFrac value of whole-steppinginterpolation. However, this mistake gave no practical issues before (absentfor linear-phase filters, and minor for minimum-phase filters).

Version 6.1:

• Made a micro-optimization of the "whole stepping" interpolation yielding 18%performance increase in some conversions (e.g., 44100 to 96000).
• Implemented the getInLenBeforeOutPos() function which is an ultra-fast andflexible replacement for the getInLenBeforeOutStart() function (that became alegacy function now). Also added the getInputRequiredForOutput() helperfunction.
• Updated comment sections across the codebase, to match the latest Doxygenversion.
• Reintroduced the r8b_inlen() function in the DLL.

Version 6.0:

• Added SSE and NEON implementations toCDSPHBDownsampler yielding 5-16%performance improvement of power-of-2 downsampling.
• Further optimization of filter calculation making it 15% faster.
• Upped "SpinCount" in Windows mutex to 2000, to be on a safer side when thefilter cache is fully filled.
• Made the latest used "static" filter bank pop to the top of the list, forcases when multiple "ReqAtten" values are in use in an application.

Version 5.9:

• Optimized filter calculation (Kaiser window function) with negligible changein filtering results.
• Optimized min-phase filter's group delay calculation.
• Reduced "SpinCount" in Windows mutex to 1000.
• Made non-essential changes across the codebase and comments.

Version 5.8:

• Rearranged FFT macros, addedR8B_PFFFT andR8B_PFFFT_DOUBLE collisioncheck.

Version 5.7:

• Removed thedefined( __ARM_NEON ) macro detection so that the codecompiles on non-ARM64 platforms.

Version 5.6:

• Added SSE and NEON implementations toCDSPHBUpsampler yielding 15%performance improvement of power-of-2 upsampling.
• Added SSE and NEON implementations to theCDSPRealFFT::multiplyBlocksZPfunction, for 2-3% performance improvement.
• Added intermediate interpolator's transition band limitation, for logicalhardness (not practically needed).
• Added theaDoConsumeLatency parameter toCDSPHBUpsampler constructor,for "inline" DSP uses of the class.
• Made various minor changes across the codebase.

Version 5.5:

• Hardened positional logic of fractional filter calculation, removedredundant multiplications.
• Removed unnecessary function templating from theCDSPSincFilterGen class.
• Added the__ARM_NEON macro to NEON availability detection.

Version 5.4:

• Added compiler specializations to previously optimized inner loops."Shuffled" SIMD interpolation code is not efficient on Apple M1. Intel C++Compiler vectorizes "whole stepping" interpolation as good as amanually-written SSE.
• Reorganized SIMD instructions for a slightly better performance.
• Changed internal buffer sizes of half-band resamplers (1-2% performanceboost).
• Fixed compiler warnings in PFFFT code.
• Added several asserts to the code.

Version 5.3:

• Optimized inner loops of the fractional interpolator, added SSE2 and NEONintrinsics, resulting in a measurable (8-25%) performance gain.
• Optimized filter calculation functions: changed some divisions by a constantto multiplications.
• Renamed M_PI macros to R8B_PI, to avoid macro collisions.
• Removed redundant code and macros.

Version 5.2:

• ModifiedPFFFT andPFFFT DOUBLE conditional pre-processor directives toalways enable NEON onaarch64/arm64 (this includes code built forApple M1).

Version 5.1:

• Changed alignment in theCFixedBuffer class to 64 bytes. This improves AVXperformance of thePFFFT DOUBLE implementation by a few percent.
• Removed redundant files from thepffft_double folder, integrated thepffft_common.c file into thepffft_double.c file.

Version 5.0:

• Removed a long-outdated macros from ther8bconf.h file.
• Changed a conditional pre-processor directive in thepf_sse2_double.h fileas per PFFFT DOUBLE author's suggestion, to allow SSE2 intrinsics in mostcompilers.
• Fixed "License.txt" misnaming in the source files to "LICENSE".

Version 4.10:

• Added thePFFFT DOUBLE implementation support. Now available via theR8B_PFFFT_DOUBLE definition macro.

Version 4.9:

• Reoptimized half-band and fractional interpolation filters with a stricterfrequency response linearity constraints. This did not impact the averagespeed performance.

Version 4.8:

• Added a limit to the intermediate filter's transition band, to keep thelatency under control at any resampling ratio.

Version 4.7:

• Added#ifndef _USE_MATH_DEFINES topffft.cpp.
• Moved#include "pffft.h" toCDSPRealFFT.h.

Version 4.6:

• Removed theMaxInLen parameter from theoneshot() function.
• Decreased intermediate low-pass filter's transition band slightly, for morestable quality.

Version 4.5:

• Fixed VS2017 compiler warnings.

Version 4.4:

• Fixed the "Declaration hides a member" Intel C++ compiler warnings.

Version 4.3:

• Added //$ markers for internal debugging purposes.

Version 4.2:

• Backed-off max transition band to 45 and MinAtten to 49.
• Implemented Wave64 and AIFF file input in ther8bfreesrc bench tool. Thetool is now compiled with theR8B_IPP 1 andR8B_EXTFFT 1 macros todemonstrate the maximal achievable performance.

Version 4.1:

• Updated allowed ReqAtten range to 52-218, ReqTransBand 0.5-56. It ispossible to specify filter parameters slightly beyond these values, but theresulting filter will be slightly out of specification as well.
• Optimized static filter banks allocation.

Version 4.0:

• A major overhaul of interpolation classes: now templated parameters are notused, all required parameters are calculated at runtime. Static filter bankobject is not used, it is created when necessary, and then cached.
• Implemented one-third interpolation filters, however, this did notmeasurably increase resampler's speed.

Version 3.7:

• Used ippsMul_64f_I() in the CDSPRealFFT::multiplyBlockZ() function for aminor conversion speed increase in Intel IPP mode.

Version 3.6:

• Added memory alignment to allocated buffers which boosts performance by 1.5%when Intel IPP FFT is in use.
• Implemented PFFFT support.

Version 3.5:

• Improved resampling speed very slightly.
• Updated ther8bfreesrc benchmark tool to support RF64 WAV files.

Version 3.4:

• Added a more efficient half-band filters for >= 256 resampling ratios.

Version 3.3:

• Made minor fix to downsampling for some use cases of CDSPBlockConvolver,did not affect resampler.
• Converted CDSPHBUpsampler and CDSPHBDownsampler's inner functions tostatic functions, which boosted high-ratio resampling performance measurably.

Version 3.2:

• Minor fix to the latency consumption mechanism.

Version 3.1:

• Reoptimized fractional delay filter's windowing function.

Version 3.0:

• Implemented a new variant of the getInLenBeforeOutStart() function.
• Reimplemented oneshot() function to supportfloat buffer types.
• Considerably improved downsampling performance at high resampling ratios.
• Implemented intermediate interpolation technique which boosted upsamplingperformance for most resampling ratios considerably.
• Removed the ConvCount constant - now resampler supports virtually anyresampling ratios.
• Removed the UsePower2 parameter from the resampler constructor.
• Now resampler's process() function always returns pointer to the internalbuffer, input buffer is returned only if no resampling happens.
• Resampler's getMaxOutLen() function can now be used to obtain the maximaloutput length that can be produced by the resampler in a single call.
• Added a more efficient "one-third" filters to half-band upsampler anddownsampler.

Version 2.1:

• Optimized 2X half-band downsampler.

Version 2.0:

• Optimized power-of-2 upsampling.

Version 1.9:

• Optimized half-band downsampling filter.
• Implemented whole-number stepping resampling.
• AddedR8B_EXTFFT configuration option.
• Fixed initial sub-sample offseting on downsampling.

Version 1.8:

• AddedR8B_FASTTIMING configuration option.

Version 1.7:

• Improved sample timing precision.
• Increased CDSPResampler :: ConvCountMax to 28 to support a lot widerresampling ratios.
• Addedbench tools.
• Removed getInLenBeforeOutStart() due to incorrect calculation.