1# Sample Rate Converter 2 3This folder contains a sample rate converter, or "resampler". 4 5The converter is based on a sinc function that has been windowed by a hyperbolic cosine. 6We found this had fewer artifacts than the more traditional Kaiser window. 7 8## Building the Resampler 9 10It is part of [Oboe](https://github.com/google/oboe) but has no dependencies on Oboe. 11So the contents of this folder can be used outside of Oboe. 12 13To build it for use outside of Oboe: 14 151. Copy the "resampler" folder to a folder in your project that is in the include path. 162. Add all of the \*.cpp files in the resampler folder to your project IDE or Makefile. 173. In ResamplerDefinitions.h, define RESAMPLER_OUTER_NAMESPACE with your own project name. Alternatively, use -DRESAMPLER_OUTER_NAMESPACE=mynamespace when compiling to avoid modifying the resampler code. 18 19## Creating a Resampler 20 21Include the [main header](MultiChannelResampler.h) for the resampler. 22 23 #include "resampler/MultiChannelResampler.h" 24 25Here is an example of creating a stereo resampler that will convert from 44100 to 48000 Hz. 26Only do this once, when you open your stream. Then use the sample resampler to process multiple buffers. 27 28 MultiChannelResampler *resampler = MultiChannelResampler::make( 29 2, // channel count 30 44100, // input sampleRate 31 48000, // output sampleRate 32 MultiChannelResampler::Quality::Medium); // conversion quality 33 34Possible values for quality include { Fastest, Low, Medium, High, Best }. 35Higher quality levels will sound better but consume more CPU because they have more taps in the filter. 36 37## Fractional Frame Counts 38 39Note that the number of output frames generated for a given number of input frames can vary. 40 41For example, suppose you are converting from 44100 Hz to 48000 Hz and using an input buffer with 960 frames. If you calculate the number of output frames you get: 42 43 960.0 * 48000 / 44100 = 1044.897959... 44 45You cannot generate a fractional number of frames. So the resampler will sometimes generate 1044 frames and sometimes 1045 frames. On average it will generate 1044.897959 frames. The resampler stores the fraction internally and keeps track of when to consume or generate a frame. 46 47You can either use a fixed number of input frames or a fixed number of output frames. The other frame count will vary. 48 49## Calling the Resampler with a fixed number of OUTPUT frames 50 51In this example, suppose we have a fixed number of output frames and a variable number of input frames. 52 53Assume you start with these variables and a method that returns the next input frame: 54 55 float *outputBuffer; // multi-channel buffer to be filled 56 int numOutputFrames; // number of frames of output 57 58The resampler has a method isWriteNeeded() that tells you whether to write to or read from the resampler. 59 60 int outputFramesLeft = numOutputFrames; 61 while (outputFramesLeft > 0) { 62 if(resampler->isWriteNeeded()) { 63 const float *frame = getNextInputFrame(); // you provide this 64 resampler->writeNextFrame(frame); 65 } else { 66 resampler->readNextFrame(outputBuffer); 67 outputBuffer += channelCount; 68 outputFramesLeft--; 69 } 70 } 71 72## Calling the Resampler with a fixed number of INPUT frames 73 74In this example, suppose we have a fixed number of input frames and a variable number of output frames. 75 76Assume you start with these variables: 77 78 float *inputBuffer; // multi-channel buffer to be consumed 79 float *outputBuffer; // multi-channel buffer to be filled 80 int numInputFrames; // number of frames of input 81 int numOutputFrames = 0; 82 int channelCount; // 1 for mono, 2 for stereo 83 84 int inputFramesLeft = numInputFrames; 85 while (inputFramesLeft > 0) { 86 if(resampler->isWriteNeeded()) { 87 resampler->writeNextFrame(inputBuffer); 88 inputBuffer += channelCount; 89 inputFramesLeft--; 90 } else { 91 resampler->readNextFrame(outputBuffer); 92 outputBuffer += channelCount; 93 numOutputFrames++; 94 } 95 } 96 97## Deleting the Resampler 98 99When you are done, you should delete the Resampler to avoid a memory leak. 100 101 delete resampler; 102