ambi_bin.h

A binaural Ambisonic decoder for reproducing Ambisonic sound scenes over headphones.

A binaural Ambisonic decoder for reproducing Ambisonic sound scenes over headphones

Files

ambi_bin.h (include), ambi_bin_internal.h, ambi_bin.c, ambi_bin_internal.c

Example Usage

int main(void) {
    void* hAmbi;
    int frameSize;
 
    // Create an instance of ambi_bin
    ambi_bin_create(&hAmbi);
 
    // Call any set functions, e.g.:
    ambi_bin_setNormType(hAmbi, NORM_N3D);
    ambi_bin_setInputOrderPreset(hAmbi, SH_ORDER_FIRST);
    ambi_bin_setEnableRotation(hAmbi, SAF_TRUE);
    ambi_bin_setYaw(hAmbi, 180.0f); // turn the listener around
 
    // Note that many set functions, for example ambi_bin_setYaw(), will
    // update their value immediately. Whereas, others, for example
    // ambi_bin_setInputOrderPreset(), which could cause clicks/hangs with
    // the main processing loop, will only trigger a flag that indicates that
    // a re-initisation is required. Therefore, ambi_bin_initCodec() should
    // be called after calling these particular set functions in order to
    // update the run-time settings accordingly.
    //
    // This function is fully thread-safe, and actually calling this on a
    // separate thread is actively encouraged, in order to avoid the
    // aforementioned run-time clicks/hangs. ambi_bin_process() is muted
    // if the initialisations are still on-going, and initialisations are
    // paused until the current ambi_bin_process() call has completed.
    ambi_bin_initCodec(hAmbi);
 
    // ambi_bin_init() should be called once before calling
    // ambi_bin_process() in order to inform the example of the host sample
    // rate and flush run-time buffers with zeros. It is not safe to call
    // this during ambi_bin_process()!
    ambi_bin_init(hAmbi, hostSamplingRate);
 
    // The framesize of this example is fixed, and can be found with
    frameSize = ambi_bin_getFrameSize();
 
    // Processing frame-by-frame
    ...
    // Load signals into inputSignalBuffer (numberOfInputs x frameSize)
    ambi_bin_process(hAmbi, inputSignalBuffer, outputSignalBuffer,
                     numberOfInputs, numberOfOutputs, frameSize);
    // Copy signals from outputSignalBuffer (numberOfOutputs x frameSize)
    ...
 
    // Destroy this instance of ambi_bin
    ambi_bin_destroy(&hAmbi);
}

Include Header

/*
 * Copyright 2018 Leo McCormack
 *
 * Permission to use, copy, modify, and/or distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
 * OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THIS SOFTWARE.
 */
 
#ifndef __AMBI_BIN_H_INCLUDED__
#define __AMBI_BIN_H_INCLUDED__
 
#include "_common.h"
 
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
 
/* ========================================================================== */
/*                             Presets + Constants                            */
/* ========================================================================== */
    
typedef enum {
    DECODING_METHOD_LS = 1,   
    DECODING_METHOD_LSDIFFEQ, 
    DECODING_METHOD_SPR,      
    DECODING_METHOD_TA,       
    DECODING_METHOD_MAGLS,    
}AMBI_BIN_DECODING_METHODS;
    
#define AMBI_BIN_NUM_DECODING_METHODS ( 5 )
 
typedef enum {
    HRIR_PREPROC_OFF = 1,     
    HRIR_PREPROC_EQ,          
    HRIR_PREPROC_PHASE,       
    HRIR_PREPROC_ALL,         
}AMBI_BIN_PREPROC;
 
#define AMBI_BIN_NUM_HRIR_PREPROC_OPTIONS ( 4 )
 
 
/* ========================================================================== */
/*                               Main Functions                               */
/* ========================================================================== */
 
void ambi_bin_create(void** const phAmbi);
 
void ambi_bin_destroy(void** const phAmbi);
 
void ambi_bin_init(void* const hAmbi,
                   int samplerate);
 
void ambi_bin_initCodec(void* const hAmbi);
 
void ambi_bin_process(void* const hAmbi,
                      const float *const * inputs,
                      float* const* const outputs,
                      int nInputs,
                      int nOutputs,
                      int nSamples);
 
 
/* ========================================================================== */
/*                                Set Functions                               */
/* ========================================================================== */
 
void ambi_bin_refreshParams(void* const hAmbi);
 
void ambi_bin_setUseDefaultHRIRsflag(void* const hAmbi, int newState);
 
void ambi_bin_setSofaFilePath(void* const hAmbi, const char* path);
 
void ambi_bin_setInputOrderPreset(void* const hAmbi,
                                  SH_ORDERS newPreset);
 
void ambi_bin_setDecodingMethod(void* const hAmbi,
                                AMBI_BIN_DECODING_METHODS newMethod);
 
void ambi_bin_setChOrder(void* const hAmbi, int newOrder);
 
void ambi_bin_setNormType(void* const hAmbi, int newType);
 
void ambi_bin_setEnableMaxRE(void* const hAmbi, int newState);
 
void ambi_bin_setEnableDiffuseMatching(void* const hAmbi, int newState);
 
void ambi_bin_setEnableTruncationEQ(void* const hAmbi, int newState);
 
void ambi_bin_setHRIRsPreProc(void* const hAmbi, AMBI_BIN_PREPROC newType);
 
void ambi_bin_setEnableRotation(void* const hAmbi, int newState);
 
void ambi_bin_setYaw(void* const hAmbi, float newYaw_deg);
 
void ambi_bin_setPitch(void* const hAmbi, float newPitch);
 
void ambi_bin_setRoll(void* const hAmbi, float newRoll);
 
void ambi_bin_setFlipYaw(void* const hAmbi, int newState);
 
void ambi_bin_setFlipPitch(void* const hAmbi, int newState);
 
void ambi_bin_setFlipRoll(void* const hAmbi, int newState);
 
void ambi_bin_setRPYflag(void* const hAmbi, int newState);
 
 
/* ========================================================================== */
/*                                Get Functions                               */
/* ========================================================================== */
 
int ambi_bin_getFrameSize(void);
 
CODEC_STATUS ambi_bin_getCodecStatus(void* const hAmbi);
    
float ambi_bin_getProgressBar0_1(void* const hAmbi);
    
void ambi_bin_getProgressBarText(void* const hAmbi, char* text);
    
int ambi_bin_getUseDefaultHRIRsflag(void* const hAmbi);
 
int ambi_bin_getInputOrderPreset(void* const hAmbi);
 
AMBI_BIN_DECODING_METHODS ambi_bin_getDecodingMethod(void* const hAmbi);
 
char* ambi_bin_getSofaFilePath(void* const hAmbi);
 
int ambi_bin_getChOrder(void* const hAmbi);
 
int ambi_bin_getNormType(void* const hAmbi); 
 
int ambi_bin_getNumEars(void);
 
int ambi_bin_getNSHrequired(void* const hAmbi);
 
int ambi_bin_getEnableMaxRE(void* const hAmbi);
 
int ambi_bin_getEnableDiffuseMatching(void* const hAmbi);
 
int ambi_bin_getEnableTruncationEQ(void* const hAmbi);
 
AMBI_BIN_PREPROC ambi_bin_getHRIRsPreProc(void* const hAmbi);
 
int ambi_bin_getEnableRotation(void* const hAmbi);
 
float ambi_bin_getYaw(void* const hAmbi);
 
float ambi_bin_getPitch(void* const hAmbi);
 
float ambi_bin_getRoll(void* const hAmbi);
 
int ambi_bin_getFlipYaw(void* const hAmbi);
 
int ambi_bin_getFlipPitch(void* const hAmbi);
 
int ambi_bin_getFlipRoll(void* const hAmbi);
 
int ambi_bin_getRPYflag(void* const hAmbi);
 
int ambi_bin_getNDirs(void* const hAmbi);
 
int ambi_bin_getHRIRlength(void* const hAmbi);
 
int ambi_bin_getHRIRsamplerate(void* const hAmbi);
 
int ambi_bin_getDAWsamplerate(void* const hAmbi);
 
int ambi_bin_getProcessingDelay(void);
 
    
#ifdef __cplusplus
} /* extern "C" { */
#endif /* __cplusplus */
 
#endif /* __AMBI_BIN_H_INCLUDED__ */