Add vocoder node and duplex example.

research/_examples/duplex_effect.c

+/*
+Demonstrates how to apply an effect to a duplex stream using the node graph system.
+
+This example applies a vocoder effect to the input stream before outputting it. A custom node
+called `ma_vocoder_node` is used to achieve the effect which can be found in the extras folder in
+the miniaudio repository. The vocoder node uses https://github.com/blastbay/voclib to achieve the
+effect.
+*/
+#define MINIAUDIO_IMPLEMENTATION
+#include "../../miniaudio.h"
+#include "../miniaudio_engine.h"
+#include "../_extras/nodes/ma_vocoder_node/ma_vocoder_node.c"
+
+#include <stdio.h>
+
+#define DEVICE_FORMAT      ma_format_f32;   /* Must always be f32 for this example because the node graph system only works with this. */
+#define DEVICE_CHANNELS    2                /* The vocoder only supports 1 or 2 channels. */
+
+static ma_audio_buffer_ref g_sourceData;    /* The underlying data source of the source node. */
+static ma_waveform         g_exciteData;    /* The underlying data source of the excite node. */
+static ma_data_source_node g_sourceNode;    /* A data source node containing the source data we'll be sending through to the vocoder. This will be routed into the first bus of the vocoder node. */
+static ma_data_source_node g_exciteNode;    /* A data source node containing the excite data we'll be sending through to the vocoder. This will be routed into the second bus of the vocoder node. */
+static ma_vocoder_node     g_vocoderNode;   /* The vocoder node. */
+static ma_node_graph       g_nodeGraph;
+
+void data_callback(ma_device* pDevice, void* pOutput, const void* pInput, ma_uint32 frameCount)
+{
+    MA_ASSERT(pDevice->capture.format == pDevice->playback.format);
+    MA_ASSERT(pDevice->capture.channels == pDevice->playback.channels);
+
+    /* Make sure the audio buffer has it's data buffer updated. */
+    ma_audio_buffer_ref_set_data(&g_sourceData, pInput, frameCount);
+
+    /* With the source buffer configured we can now read directly from the node graph. */
+    ma_node_graph_read_pcm_frames(&g_nodeGraph, pOutput, frameCount, NULL);
+}
+
+int main(int argc, char** argv)
+{
+    ma_result result;
+    ma_device_config deviceConfig;
+    ma_device device;
+    ma_node_graph_config nodeGraphConfig;
+    ma_vocoder_node_config vocoderNodeConfig;
+    ma_data_source_node_config sourceNodeConfig;
+    ma_data_source_node_config exciteNodeConfig;
+    ma_waveform_config waveformConfig;
+
+    deviceConfig = ma_device_config_init(ma_device_type_duplex);
+    deviceConfig.capture.pDeviceID  = NULL;
+    deviceConfig.capture.format     = DEVICE_FORMAT;
+    deviceConfig.capture.channels   = DEVICE_CHANNELS;
+    deviceConfig.capture.shareMode  = ma_share_mode_shared;
+    deviceConfig.playback.pDeviceID = NULL;
+    deviceConfig.playback.format    = DEVICE_FORMAT;
+    deviceConfig.playback.channels  = DEVICE_CHANNELS;
+    deviceConfig.dataCallback       = data_callback;
+    result = ma_device_init(NULL, &deviceConfig, &device);
+    if (result != MA_SUCCESS) {
+        return result;
+    }
+
+
+    /* Now we can setup our node graph. */
+    nodeGraphConfig = ma_node_graph_config_init(device.capture.channels);
+
+    result = ma_node_graph_init(&nodeGraphConfig, NULL, &g_nodeGraph);
+    if (result != MA_SUCCESS) {
+        printf("Failed to initialize node graph.");
+        goto done0;
+    }
+
+
+    /* Vocoder. Attached straight to the endpoint. */
+    vocoderNodeConfig = ma_vocoder_node_config_init(device.capture.channels, device.sampleRate);
+
+    result = ma_vocoder_node_init(&g_nodeGraph, &vocoderNodeConfig, NULL, &g_vocoderNode);
+    if (result != MA_SUCCESS) {
+        printf("Failed to initialize vocoder node.");
+        goto done1;
+    }
+
+    ma_node_attach_output_bus(&g_vocoderNode, 0, ma_node_graph_get_endpoint(&g_nodeGraph), 0);
+
+    /* Amplify the volume of the vocoder output because in my testing it is a bit quiet. */
+    ma_node_set_output_bus_volume(&g_vocoderNode, 0, 2);
+
+
+    /* Source/carrier. Attached to input bus 0 of the vocoder node. */
+    result = ma_audio_buffer_ref_init(device.capture.format, device.capture.channels, &g_sourceData);
+    if (result != MA_SUCCESS) {
+        printf("Failed to initialize audio buffer for source.");
+        goto done2;
+    }
+
+    sourceNodeConfig = ma_data_source_node_config_init(&g_sourceData, MA_FALSE);
+
+    result = ma_data_source_node_init(&g_nodeGraph, &sourceNodeConfig, NULL, &g_sourceNode);
+    if (result != MA_SUCCESS) {
+        printf("Failed to initialize source node.");
+        goto done2;
+    }
+
+    ma_node_attach_output_bus(&g_sourceNode, 0, &g_vocoderNode, 0);
+
+
+    /* Excite/modulator. Attached to input bus 1 of the vocoder node. */
+    waveformConfig = ma_waveform_config_init(device.capture.format, 1, device.sampleRate, ma_waveform_type_sawtooth, 1.0, 500); /* Must be one channel. */
+
+    result = ma_waveform_init(&waveformConfig, &g_exciteData);
+    if (result != MA_SUCCESS) {
+        printf("Failed to initialize waveform for excite node.");
+        goto done3;
+    }
+
+    exciteNodeConfig = ma_data_source_node_config_init(&g_exciteData, MA_FALSE);
+
+    result = ma_data_source_node_init(&g_nodeGraph, &exciteNodeConfig, NULL, &g_exciteNode);
+    if (result != MA_SUCCESS) {
+        printf("Failed to initialize excite node.");
+        goto done3;
+    }
+
+    ma_node_attach_output_bus(&g_exciteNode, 0, &g_vocoderNode, 1);
+
+
+    ma_device_start(&device);
+
+    printf("Press Enter to quit...\n");
+    getchar();
+
+    /* It's important that we stop the device first or else we'll uninitialize the graph from under the device. */
+    ma_device_stop(&device);
+
+/*done4:*/ ma_data_source_node_uninit(&g_exciteNode, NULL);
+done3: ma_data_source_node_uninit(&g_sourceNode, NULL);
+done2: ma_vocoder_node_uninit(&g_vocoderNode, NULL);
+done1: ma_node_graph_uninit(&g_nodeGraph, NULL);
+done0: ma_device_uninit(&device);
+
+    (void)argc;
+    (void)argv;
+    return 0;
+}

research/_extras/nodes/ma_vocoder_node/ma_vocoder_node.c

+
+#define VOCLIB_IMPLEMENTATION
+#include "ma_vocoder_node.h"
+
+static void ma_vocoder_node_process_pcm_frames(ma_node* pNode, const float** ppFramesIn, ma_uint32* pFrameCountIn, float** ppFramesOut, ma_uint32* pFrameCountOut)
+{
+    ma_vocoder_node* pVocoderNode = (ma_vocoder_node*)pNode;
+
+    (void)pFrameCountIn;
+
+    voclib_process(&pVocoderNode->voclib, ppFramesIn[0], ppFramesIn[1], ppFramesOut[0], *pFrameCountOut);
+}
+
+static ma_node_vtable g_ma_vocoder_node_vtable =
+{
+    ma_vocoder_node_process_pcm_frames,
+    NULL,
+    2,  /* 2 input channels. */
+    1,  /* 1 output channel. */
+    0
+};
+
+MA_API ma_vocoder_node_config ma_vocoder_node_config_init(ma_uint32 channels, ma_uint32 sampleRate)
+{
+    ma_vocoder_node_config config;
+
+    MA_ZERO_OBJECT(&config);
+    config.nodeConfig     = ma_node_config_init();   /* Input and output channels will be set in ma_vocoder_node_init(). */
+    config.channels       = channels;
+    config.sampleRate     = sampleRate;
+    config.bands          = 16;
+    config.filtersPerBand = 6;
+
+    return config;
+}
+
+
+
+MA_API ma_result ma_vocoder_node_init(ma_node_graph* pNodeGraph, const ma_vocoder_node_config* pConfig, const ma_allocation_callbacks* pAllocationCallbacks, ma_vocoder_node* pVocoderNode)
+{
+    ma_result result;
+    ma_node_config baseConfig;
+
+    if (pVocoderNode == NULL) {
+        return MA_INVALID_ARGS;
+    }
+
+    MA_ZERO_OBJECT(pVocoderNode);
+
+    if (pConfig == NULL) {
+        return MA_INVALID_ARGS;
+    }
+
+    if (voclib_initialize(&pVocoderNode->voclib, (unsigned char)pConfig->bands, (unsigned char)pConfig->filtersPerBand, (unsigned int)pConfig->sampleRate, (unsigned char)pConfig->channels) == 0) {
+        return MA_INVALID_ARGS;
+    }
+
+    baseConfig = pConfig->nodeConfig;
+    baseConfig.vtable = &g_ma_vocoder_node_vtable;
+    baseConfig.inputChannels[0] = pConfig->channels;    /* Source/carrier. */
+    baseConfig.inputChannels[1] = 1;                    /* Excite/modulator. Must always be single channel. */
+    baseConfig.outputChannels[0] = pConfig->channels;   /* Output channels is always the same as the source/carrier. */
+    baseConfig.outputChannels[1] = 0;                   /* Unused. */
+
+    result = ma_node_init(pNodeGraph, &baseConfig, pAllocationCallbacks, &pVocoderNode->baseNode);
+    if (result != MA_SUCCESS) {
+        return result;
+    }
+
+    return MA_SUCCESS;
+}
+
+MA_API void ma_vocoder_node_uninit(ma_vocoder_node* pVocoderNode, const ma_allocation_callbacks* pAllocationCallbacks)
+{
+    /* The base node must always be initialized first. */
+    ma_node_uninit(pVocoderNode, pAllocationCallbacks);
+}

research/_extras/nodes/ma_vocoder_node/ma_vocoder_node.h

+/* Include ma_vocoder_node.h after miniaudio.h */
+#ifndef ma_vocoder_node_h
+#define ma_vocoder_node_h
+
+#include "voclib.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct
+{
+    ma_node_config nodeConfig;
+    ma_uint32 channels;         /* The number of channels of the source, which will be the same as the output. Must be 1 or 2. The excite bus must always have one channel. */
+    ma_uint32 sampleRate;
+    ma_uint32 bands;            /* Defaults to 16. */
+    ma_uint32 filtersPerBand;   /* Defaults to 6. */
+} ma_vocoder_node_config;
+
+MA_API ma_vocoder_node_config ma_vocoder_node_config_init(ma_uint32 channels, ma_uint32 sampleRate);
+
+
+typedef struct
+{
+    ma_node_base baseNode;
+    voclib_instance voclib;
+} ma_vocoder_node;
+
+MA_API ma_result ma_vocoder_node_init(ma_node_graph* pNodeGraph, const ma_vocoder_node_config* pConfig, const ma_allocation_callbacks* pAllocationCallbacks, ma_vocoder_node* pVocoderNode);
+MA_API void ma_vocoder_node_uninit(ma_vocoder_node* pVocoderNode, const ma_allocation_callbacks* pAllocationCallbacks);
+
+#ifdef __cplusplus
+}
+#endif
+#endif  /* ma_vocoder_node_h */

research/_extras/nodes/ma_vocoder_node/voclib.h

+/* Vocoder Library
+* Voclib version 1.1 - 2019-02-16
+*
+* Philip Bennefall - philip@blastbay.com
+*
+* See the end of this file for licensing terms.
+* The filter implementation was derived from public domain code found on musicdsp.org (see the section called "Filters" for more details).
+*
+* USAGE
+*
+* This is a single-file library. To use it, do something like the following in one .c file.
+* #define VOCLIB_IMPLEMENTATION
+* #include "voclib.h"
+*
+* You can then #include this file in other parts of the program as you would with any other header file.
+*/
+
+#ifndef VOCLIB_H
+#define VOCLIB_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+    /* COMPILE-TIME OPTIONS */
+
+    /* The maximum number of bands that the vocoder can be initialized with (lower this number to save memory). */
+#define VOCLIB_MAX_BANDS 96
+
+    /* The maximum number of filters per vocoder band (lower this number to save memory). */
+#define VOCLIB_MAX_FILTERS_PER_BAND 8
+
+    /* PUBLIC API */
+
+    typedef struct voclib_instance voclib_instance;
+
+    /* Initialize a voclib_instance structure.
+    *
+    * Call this function to initialize the voclib_instance structure.
+    * bands is the number of bands that the vocoder should use; recommended values are between 12 and 64.
+    * bands must be between 4 and VOCLIB_MAX_BANDS (inclusive).
+    * filters_per_band determines the steapness with which the filterbank divides the signal; a value of 6 is recommended.
+    * filters_per_band must be between 1 and VOCLIB_MAX_FILTERS_PER_BAND (inclusive).
+    * sample_rate is the number of samples per second in hertz, and should be between 8000 and 192000 (inclusive).
+    * carrier_channels is the number of channels that the carrier has, and should be between 1 and 2 (inclusive).
+    * Note: The modulator must always have only one channel.
+    * Returns nonzero (true) on success or 0 (false) on failure.
+    * The function will only fail if one or more of the parameters are invalid.
+    */
+    int voclib_initialize ( voclib_instance* instance, unsigned char bands, unsigned char filters_per_band, unsigned int sample_rate, unsigned char carrier_channels );
+
+    /* Run the vocoder.
+    *
+    * Call this function continuously to generate your output.
+    * carrier_buffer and modulator_buffer should contain the carrier and modulator signals respectively.
+    * The modulator must always have one channel.
+    * If the carrier has two channels, the samples in carrier_buffer must be interleaved.
+    * output_buffer will be filled with the result, and must be able to hold as many channels as the carrier.
+    * If the carrier has two channels, the output buffer will be filled with interleaved samples.
+    * output_buffer may be the same pointer as either carrier_buffer or modulator_buffer as long as it can hold the same number of channels as the carrier.
+    * The processing is performed in place.
+    * frames specifies the number of sample frames that should be processed.
+    * Returns nonzero (true) on success or 0 (false) on failure.
+    * The function will only fail if one or more of the parameters are invalid.
+    */
+    int voclib_process ( voclib_instance* instance, const float* carrier_buffer, const float* modulator_buffer, float* output_buffer, unsigned int frames );
+
+    /* Reset the vocoder sample history.
+    *
+    * In order to run smoothly, the vocoder needs to store a few recent samples internally.
+    * This function resets that internal history. This should only be done if you are processing a new stream.
+    * Resetting the history in the middle of a stream will cause clicks.
+    */
+    void voclib_reset_history ( voclib_instance* instance );
+
+    /* Set the reaction time of the vocoder in seconds.
+    *
+    * The reaction time is the time it takes for the vocoder to respond to a volume change in the modulator.
+    * A value of 0.03 (AKA 30 milliseconds) is recommended for intelligible speech.
+    * Values lower than about 0.02 will make the output sound raspy and unpleasant.
+    * Values above 0.2 or so will make the speech hard to understand, but can be used for special effects.
+    * The value must be between 0.002 and 2.0 (inclusive).
+    * Returns nonzero (true) on success or 0 (false) on failure.
+    * The function will only fail if the parameter is invalid.
+    */
+    int voclib_set_reaction_time ( voclib_instance* instance, float reaction_time );
+
+    /* Get the current reaction time of the vocoder in seconds. */
+    float voclib_get_reaction_time ( const voclib_instance* instance );
+
+    /* Set the formant shift of the vocoder in octaves.
+    *
+    * Formant shifting changes the size of the speaker's head.
+    * A value of 1.0 leaves the head size unmodified.
+    * Values lower than 1.0 make the head larger, and values above 1.0 make it smaller.
+    * The value must be between 0.25 and 4.0 (inclusive).
+    * Returns nonzero (true) on success or 0 (false) on failure.
+    * The function will only fail if the parameter is invalid.
+    */
+    int voclib_set_formant_shift ( voclib_instance* instance, float formant_shift );
+
+    /* Get the current formant shift of the vocoder in octaves. */
+    float voclib_get_formant_shift ( const voclib_instance* instance );
+
+    /* INTERNAL STRUCTURES */
+
+    /* this holds the data required to update samples thru a filter. */
+    typedef struct
+    {
+        float a0, a1, a2, a3, a4;
+        float x1, x2, y1, y2;
+    } voclib_biquad;
+
+    /* Stores the state required for our envelope follower. */
+    typedef struct
+    {
+        float coef;
+        float history[4];
+    } voclib_envelope;
+
+    /* Holds a set of filters required for one vocoder band. */
+    typedef struct
+    {
+        voclib_biquad filters[VOCLIB_MAX_FILTERS_PER_BAND];
+    } voclib_band;
+
+    /* The main instance structure. This is the structure that you will create an instance of when using the vocoder. */
+    struct voclib_instance
+    {
+        voclib_band analysis_bands[VOCLIB_MAX_BANDS]; /* The filterbank used for analysis (these are applied to the modulator). */
+        voclib_envelope analysis_envelopes[VOCLIB_MAX_BANDS]; /* The envelopes used to smooth the analysis bands. */
+        voclib_band synthesis_bands[VOCLIB_MAX_BANDS * 2]; /* The filterbank used for synthesis (these are applied to the carrier). The second half of the array is only used for stereo carriers. */
+        float reaction_time; /* In seconds. Higher values make the vocoder respond more slowly to changes in the modulator. */
+        float formant_shift; /* In octaves. 1.0 is unchanged. */
+        unsigned int sample_rate; /* In hertz. */
+        unsigned char bands;
+        unsigned char filters_per_band;
+        unsigned char carrier_channels;
+    };
+
+#ifdef __cplusplus
+}
+#endif
+#endif  /* VOCLIB_H */
+
+/* IMPLEMENTATION */
+
+#ifdef VOCLIB_IMPLEMENTATION
+
+#include <math.h>
+#include <assert.h>
+
+#ifdef _MSC_VER
+#define VOCLIB_INLINE __forceinline
+#else
+#ifdef __GNUC__
+#define VOCLIB_INLINE inline __attribute__((always_inline))
+#else
+#define VOCLIB_INLINE inline
+#endif
+#endif
+
+/* Filters
+*
+* The filter code below was derived from http://www.musicdsp.org/files/biquad.c. The comment at the top of biquad.c file reads:
+*
+* Simple implementation of Biquad filters -- Tom St Denis
+ *
+ * Based on the work
+
+Cookbook formulae for audio EQ biquad filter coefficients
+---------------------------------------------------------
+by Robert Bristow-Johnson, pbjrbj@viconet.com  a.k.a. robert@audioheads.com
+
+ * Available on the web at
+
+http://www.smartelectronix.com/musicdsp/text/filters005.txt
+
+ * Enjoy.
+ *
+ * This work is hereby placed in the public domain for all purposes, whether
+ * commercial, free [as in speech] or educational, etc.  Use the code and please
+ * give me credit if you wish.
+ *
+ * Tom St Denis -- http://tomstdenis.home.dhs.org
+*/
+
+#ifndef VOCLIB_M_LN2
+#define VOCLIB_M_LN2	   0.69314718055994530942
+#endif
+
+#ifndef VOCLIB_M_PI
+#define VOCLIB_M_PI		3.14159265358979323846
+#endif
+
+/* Computes a BiQuad filter on a sample. */
+static VOCLIB_INLINE float voclib_BiQuad ( float sample, voclib_biquad* b )
+{
+    float result;
+
+    /* compute the result. */
+    result = b->a0 * sample + b->a1 * b->x1 + b->a2 * b->x2 -
+             b->a3 * b->y1 - b->a4 * b->y2;
+
+    /* shift x1 to x2, sample to x1. */
+    b->x2 = b->x1;
+    b->x1 = sample;
+
+    /* shift y1 to y2, result to y1. */
+    b->y2 = b->y1;
+    b->y1 = result;
+
+    return result;
+}
+
+/* filter types. */
+enum
+{
+    VOCLIB_LPF, /* low pass filter */
+    VOCLIB_HPF, /* High pass filter */
+    VOCLIB_BPF, /* band pass filter */
+    VOCLIB_NOTCH, /* Notch Filter */
+    VOCLIB_PEQ, /* Peaking band EQ filter */
+    VOCLIB_LSH, /* Low shelf filter */
+    VOCLIB_HSH /* High shelf filter */
+};
+
+/* sets up a BiQuad Filter. */
+static void voclib_BiQuad_new ( voclib_biquad* b, int type, float dbGain, /* gain of filter */
+                                float freq, /* center frequency */
+                                float srate, /* sampling rate */
+                                float bandwidth ) /* bandwidth in octaves */
+{
+    float A, omega, sn, cs, alpha, beta;
+    float a0, a1, a2, b0, b1, b2;
+
+    /* setup variables. */
+    A = ( float ) pow ( 10, dbGain / 40.0f );
+    omega = ( float ) ( 2.0 * VOCLIB_M_PI * freq / srate );
+    sn = ( float ) sin ( omega );
+    cs = ( float ) cos ( omega );
+    alpha = sn * ( float ) sinh ( VOCLIB_M_LN2 / 2 * bandwidth * omega / sn );
+    beta = ( float ) sqrt ( A + A );
+
+    switch ( type )
+    {
+        case VOCLIB_LPF:
+            b0 = ( 1 - cs ) / 2;
+            b1 = 1 - cs;
+            b2 = ( 1 - cs ) / 2;
+            a0 = 1 + alpha;
+            a1 = -2 * cs;
+            a2 = 1 - alpha;
+            break;
+        case VOCLIB_HPF:
+            b0 = ( 1 + cs ) / 2;
+            b1 = - ( 1 + cs );
+            b2 = ( 1 + cs ) / 2;
+            a0 = 1 + alpha;
+            a1 = -2 * cs;
+            a2 = 1 - alpha;
+            break;
+        case VOCLIB_BPF:
+            b0 = alpha;
+            b1 = 0;
+            b2 = -alpha;
+            a0 = 1 + alpha;
+            a1 = -2 * cs;
+            a2 = 1 - alpha;
+            break;
+        case VOCLIB_NOTCH:
+            b0 = 1;
+            b1 = -2 * cs;
+            b2 = 1;
+            a0 = 1 + alpha;
+            a1 = -2 * cs;
+            a2 = 1 - alpha;
+            break;
+        case VOCLIB_PEQ:
+            b0 = 1 + ( alpha * A );
+            b1 = -2 * cs;
+            b2 = 1 - ( alpha * A );
+            a0 = 1 + ( alpha / A );
+            a1 = -2 * cs;
+            a2 = 1 - ( alpha / A );
+            break;
+        case VOCLIB_LSH:
+            b0 = A * ( ( A + 1 ) - ( A - 1 ) * cs + beta * sn );
+            b1 = 2 * A * ( ( A - 1 ) - ( A + 1 ) * cs );
+            b2 = A * ( ( A + 1 ) - ( A - 1 ) * cs - beta * sn );
+            a0 = ( A + 1 ) + ( A - 1 ) * cs + beta * sn;
+            a1 = -2 * ( ( A - 1 ) + ( A + 1 ) * cs );
+            a2 = ( A + 1 ) + ( A - 1 ) * cs - beta * sn;
+            break;
+        case VOCLIB_HSH:
+            b0 = A * ( ( A + 1 ) + ( A - 1 ) * cs + beta * sn );
+            b1 = -2 * A * ( ( A - 1 ) + ( A + 1 ) * cs );
+            b2 = A * ( ( A + 1 ) + ( A - 1 ) * cs - beta * sn );
+            a0 = ( A + 1 ) - ( A - 1 ) * cs + beta * sn;
+            a1 = 2 * ( ( A - 1 ) - ( A + 1 ) * cs );
+            a2 = ( A + 1 ) - ( A - 1 ) * cs - beta * sn;
+            break;
+        default:
+            assert ( 0 ); /* Misuse. */
+            return;
+    }
+
+    /* precompute the coefficients. */
+    b->a0 = b0 / a0;
+    b->a1 = b1 / a0;
+    b->a2 = b2 / a0;
+    b->a3 = a1 / a0;
+    b->a4 = a2 / a0;
+}
+
+/* Reset the filter history. */
+static void voclib_BiQuad_reset ( voclib_biquad* b )
+{
+    b->x1 = b->x2 = 0.0f;
+    b->y1 = b->y2 = 0.0f;
+}
+
+/* Envelope follower. */
+
+static void voclib_envelope_configure ( voclib_envelope* envelope, double time_in_seconds, double sample_rate )
+{
+    envelope->coef = ( float ) ( pow ( 0.01, 1.0 / ( time_in_seconds * sample_rate ) ) );
+}
+
+/* Reset the envelope history. */
+static void voclib_envelope_reset ( voclib_envelope* envelope )
+{
+    envelope->history[0] = 0.0f;
+    envelope->history[1] = 0.0f;
+    envelope->history[2] = 0.0f;
+    envelope->history[3] = 0.0f;
+}
+
+static VOCLIB_INLINE float voclib_envelope_tick ( voclib_envelope* envelope, float sample )
+{
+    const float coef = envelope->coef;
+    envelope->history[0] = ( float ) ( ( 1.0f - coef ) * fabs ( sample ) ) + ( coef * envelope->history[0] );
+    envelope->history[1] = ( ( 1.0f - coef ) * envelope->history[0] ) + ( coef * envelope->history[1] );
+    envelope->history[2] = ( ( 1.0f - coef ) * envelope->history[1] ) + ( coef * envelope->history[2] );
+    envelope->history[3] = ( ( 1.0f - coef ) * envelope->history[2] ) + ( coef * envelope->history[3] );
+    return envelope->history[3];
+}
+
+/* Initialize the vocoder filterbank. */
+static void voclib_initialize_filterbank ( voclib_instance* instance, int carrier_only )
+{
+    unsigned char i;
+    double step;
+    double lastfreq = 0.0;
+    double minfreq = 80.0;
+    double maxfreq = instance->sample_rate;
+    if ( maxfreq > 12000.0 )
+    {
+        maxfreq = 12000.0;
+    }
+    step = pow ( ( maxfreq / minfreq ), ( 1.0 / instance->bands ) );
+
+    for ( i = 0; i < instance->bands; ++i )
+    {
+        unsigned char i2;
+        double bandwidth, nextfreq;
+        double priorfreq = lastfreq;
+        if ( lastfreq > 0.0 )
+        {
+            lastfreq *= step;
+        }
+        else
+        {
+            lastfreq = minfreq;
+        }
+        nextfreq = lastfreq * step;
+        bandwidth = ( nextfreq - priorfreq ) / lastfreq;
+
+        if ( !carrier_only )
+        {
+            voclib_BiQuad_new ( &instance->analysis_bands[i].filters[0], VOCLIB_BPF, 0.0f, ( float ) lastfreq, ( float ) instance->sample_rate, ( float ) bandwidth );
+            for ( i2 = 1; i2 < instance->filters_per_band; ++i2 )
+            {
+                instance->analysis_bands[i].filters[i2].a0 = instance->analysis_bands[i].filters[0].a0;
+                instance->analysis_bands[i].filters[i2].a1 = instance->analysis_bands[i].filters[0].a1;
+                instance->analysis_bands[i].filters[i2].a2 = instance->analysis_bands[i].filters[0].a2;
+                instance->analysis_bands[i].filters[i2].a3 = instance->analysis_bands[i].filters[0].a3;
+                instance->analysis_bands[i].filters[i2].a4 = instance->analysis_bands[i].filters[0].a4;
+            }
+        }
+
+        if ( instance->formant_shift != 1.0f )
+        {
+            voclib_BiQuad_new ( &instance->synthesis_bands[i].filters[0], VOCLIB_BPF, 0.0f, ( float ) ( lastfreq * instance->formant_shift ), ( float ) instance->sample_rate, ( float ) bandwidth );
+        }
+        else
+        {
+            instance->synthesis_bands[i].filters[0].a0 = instance->analysis_bands[i].filters[0].a0;
+            instance->synthesis_bands[i].filters[0].a1 = instance->analysis_bands[i].filters[0].a1;
+            instance->synthesis_bands[i].filters[0].a2 = instance->analysis_bands[i].filters[0].a2;
+            instance->synthesis_bands[i].filters[0].a3 = instance->analysis_bands[i].filters[0].a3;
+            instance->synthesis_bands[i].filters[0].a4 = instance->analysis_bands[i].filters[0].a4;
+        }
+
+        instance->synthesis_bands[i + VOCLIB_MAX_BANDS].filters[0].a0 = instance->synthesis_bands[i].filters[0].a0;
+        instance->synthesis_bands[i + VOCLIB_MAX_BANDS].filters[0].a1 = instance->synthesis_bands[i].filters[0].a1;
+        instance->synthesis_bands[i + VOCLIB_MAX_BANDS].filters[0].a2 = instance->synthesis_bands[i].filters[0].a2;
+        instance->synthesis_bands[i + VOCLIB_MAX_BANDS].filters[0].a3 = instance->synthesis_bands[i].filters[0].a3;
+        instance->synthesis_bands[i + VOCLIB_MAX_BANDS].filters[0].a4 = instance->synthesis_bands[i].filters[0].a4;
+
+        for ( i2 = 1; i2 < instance->filters_per_band; ++i2 )
+        {
+            instance->synthesis_bands[i].filters[i2].a0 = instance->synthesis_bands[i].filters[0].a0;
+            instance->synthesis_bands[i].filters[i2].a1 = instance->synthesis_bands[i].filters[0].a1;
+            instance->synthesis_bands[i].filters[i2].a2 = instance->synthesis_bands[i].filters[0].a2;
+            instance->synthesis_bands[i].filters[i2].a3 = instance->synthesis_bands[i].filters[0].a3;
+            instance->synthesis_bands[i].filters[i2].a4 = instance->synthesis_bands[i].filters[0].a4;
+
+            instance->synthesis_bands[i + VOCLIB_MAX_BANDS].filters[i2].a0 = instance->synthesis_bands[i].filters[0].a0;
+            instance->synthesis_bands[i + VOCLIB_MAX_BANDS].filters[i2].a1 = instance->synthesis_bands[i].filters[0].a1;
+            instance->synthesis_bands[i + VOCLIB_MAX_BANDS].filters[i2].a2 = instance->synthesis_bands[i].filters[0].a2;
+            instance->synthesis_bands[i + VOCLIB_MAX_BANDS].filters[i2].a3 = instance->synthesis_bands[i].filters[0].a3;
+            instance->synthesis_bands[i + VOCLIB_MAX_BANDS].filters[i2].a4 = instance->synthesis_bands[i].filters[0].a4;
+        }
+    }
+
+}
+
+/* Initialize the vocoder envelopes. */
+static void voclib_initialize_envelopes ( voclib_instance* instance )
+{
+    unsigned char i;
+
+    voclib_envelope_configure ( &instance->analysis_envelopes[0], instance->reaction_time, ( double ) instance->sample_rate );
+    for ( i = 1; i < instance->bands; ++i )
+    {
+        instance->analysis_envelopes[i].coef = instance->analysis_envelopes[0].coef;
+    }
+}
+
+int voclib_initialize ( voclib_instance* instance, unsigned char bands, unsigned char filters_per_band, unsigned int sample_rate, unsigned char carrier_channels )
+{
+    if ( !instance )
+    {
+        return 0;
+    }
+    if ( bands < 4 || bands > VOCLIB_MAX_BANDS )
+    {
+        return 0;
+    }
+    if ( filters_per_band < 1 || filters_per_band > VOCLIB_MAX_FILTERS_PER_BAND )
+    {
+        return 0;
+    }
+    if ( sample_rate < 8000 || sample_rate > 192000 )
+    {
+        return 0;
+    }
+    if ( carrier_channels < 1 || carrier_channels > 2 )
+    {
+        return 0;
+    }
+
+    instance->reaction_time = 0.03f;
+    instance->formant_shift = 1.0f;
+    instance->sample_rate = sample_rate;
+    instance->bands = bands;
+    instance->filters_per_band = filters_per_band;
+    instance->carrier_channels = carrier_channels;
+
+    voclib_reset_history ( instance );
+    voclib_initialize_filterbank ( instance, 0 );
+    voclib_initialize_envelopes ( instance );
+
+    return 1;
+}
+
+void voclib_reset_history ( voclib_instance* instance )
+{
+    unsigned char i;
+
+    for ( i = 0; i < instance->bands; ++i )
+    {
+        unsigned char i2;
+
+        for ( i2 = 0; i2 < instance->filters_per_band; ++i2 )
+        {
+            voclib_BiQuad_reset ( &instance->analysis_bands[i].filters[i2] );
+            voclib_BiQuad_reset ( &instance->synthesis_bands[i].filters[i2] );
+            voclib_BiQuad_reset ( &instance->synthesis_bands[i + VOCLIB_MAX_BANDS].filters[i2] );
+        }
+        voclib_envelope_reset ( &instance->analysis_envelopes[i] );
+    }
+}
+
+int voclib_process ( voclib_instance* instance, const float* carrier_buffer, const float* modulator_buffer, float* output_buffer, unsigned int frames )
+{
+    unsigned int i;
+    const unsigned char bands = instance->bands;
+    const unsigned char filters_per_band = instance->filters_per_band;
+
+    if ( !carrier_buffer )
+    {
+        return 0;
+    }
+    if ( !modulator_buffer )
+    {
+        return 0;
+    }
+    if ( !output_buffer )
+    {
+        return 0;
+    }
+    if ( frames == 0 )
+    {
+        return 0;
+    }
+
+    if ( instance->carrier_channels == 2 )
+    {
+
+        /* The carrier has two channels and the modulator has 1. */
+        for ( i = 0; i < frames * 2; i += 2, ++modulator_buffer )
+        {
+            unsigned char i2;
+            float out_left = 0.0f;
+            float out_right = 0.0f;
+
+            /* Run the bands in parallel and accumulate the output. */
+            for ( i2 = 0; i2 < bands; ++i2 )
+            {
+                unsigned char i3;
+                float analysis_band = voclib_BiQuad ( *modulator_buffer, &instance->analysis_bands[i2].filters[0] );
+                float synthesis_band_left = voclib_BiQuad ( carrier_buffer[i], &instance->synthesis_bands[i2].filters[0] );
+                float synthesis_band_right = voclib_BiQuad ( carrier_buffer[i + 1], &instance->synthesis_bands[i2 + VOCLIB_MAX_BANDS].filters[0] );
+
+                for ( i3 = 1; i3 < filters_per_band; ++i3 )
+                {
+                    analysis_band = voclib_BiQuad ( analysis_band, &instance->analysis_bands[i2].filters[i3] );
+                    synthesis_band_left = voclib_BiQuad ( synthesis_band_left, &instance->synthesis_bands[i2].filters[i3] );
+                    synthesis_band_right = voclib_BiQuad ( synthesis_band_right, &instance->synthesis_bands[i2 + VOCLIB_MAX_BANDS].filters[i3] );
+                }
+                analysis_band = voclib_envelope_tick ( &instance->analysis_envelopes[i2], analysis_band );
+                out_left += synthesis_band_left * analysis_band;
+                out_right += synthesis_band_right * analysis_band;
+            }
+            output_buffer[i] = out_left;
+            output_buffer[i + 1] = out_right;
+        }
+
+    }
+    else
+    {
+
+        /* Both the carrier and the modulator have a single channel. */
+        for ( i = 0; i < frames; ++i )
+        {
+            unsigned char i2;
+            float out = 0.0f;
+
+            /* Run the bands in parallel and accumulate the output. */
+            for ( i2 = 0; i2 < bands; ++i2 )
+            {
+                unsigned char i3;
+                float analysis_band = voclib_BiQuad ( modulator_buffer[i], &instance->analysis_bands[i2].filters[0] );
+                float synthesis_band = voclib_BiQuad ( carrier_buffer[i], &instance->synthesis_bands[i2].filters[0] );
+
+                for ( i3 = 1; i3 < filters_per_band; ++i3 )
+                {
+                    analysis_band = voclib_BiQuad ( analysis_band, &instance->analysis_bands[i2].filters[i3] );
+                    synthesis_band = voclib_BiQuad ( synthesis_band, &instance->synthesis_bands[i2].filters[i3] );
+                }
+                analysis_band = voclib_envelope_tick ( &instance->analysis_envelopes[i2], analysis_band );
+                out += synthesis_band * analysis_band;
+            }
+            output_buffer[i] = out;
+        }
+    }
+
+    return 1;
+}
+
+int voclib_set_reaction_time ( voclib_instance* instance, float reaction_time )
+{
+    if ( reaction_time < 0.002f || reaction_time > 2.0f )
+    {
+        return 0;
+    }
+
+    instance->reaction_time = reaction_time;
+    voclib_initialize_envelopes ( instance );
+    return 1;
+}
+
+float voclib_get_reaction_time ( const voclib_instance* instance )
+{
+    return instance->reaction_time;
+}
+
+int voclib_set_formant_shift ( voclib_instance* instance, float formant_shift )
+{
+    if ( formant_shift < 0.25f || formant_shift > 4.0f )
+    {
+        return 0;
+    }
+
+    instance->formant_shift = formant_shift;
+    voclib_initialize_filterbank ( instance, 1 );
+    return 1;
+}
+
+float voclib_get_formant_shift ( const voclib_instance* instance )
+{
+    return instance->formant_shift;
+}
+
+#endif /* VOCLIB_IMPLEMENTATION */
+
+/* REVISION HISTORY
+*
+* Version 1.1 - 2019-02-16
+* Breaking change: Introduced a new argument to voclib_initialize called carrier_channels. This allows the vocoder to output stereo natively.
+* Better assignment of band frequencies when using lower sample rates.
+* The shell now automatically normalizes the output file to match the peak amplitude in the carrier.
+* Fixed a memory corruption bug in the shell which would occur in response to an error condition.
+*
+* Version 1.0 - 2019-01-27
+* Initial release.
+*/
+
+/* LICENSE
+
+This software is available under 2 licenses -- choose whichever you prefer.
+------------------------------------------------------------------------------
+ALTERNATIVE A - MIT No Attribution License
+Copyright (c) 2019 Philip Bennefall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+------------------------------------------------------------------------------
+ALTERNATIVE B - Public Domain (www.unlicense.org)
+This is free and unencumbered software released into the public domain.
+Anyone is free to copy, modify, publish, use, compile, sell, or distribute this
+software, either in source code form or as a compiled binary, for any purpose,
+commercial or non-commercial, and by any means.
+
+In jurisdictions that recognize copyright laws, the author or authors of this
+software dedicate any and all copyright interest in the software to the public
+domain. We make this dedication for the benefit of the public at large and to
+the detriment of our heirs and successors. We intend this dedication to be an
+overt act of relinquishment in perpetuity of all present and future rights to
+this software under copyright law.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+------------------------------------------------------------------------------
+*/