Harpex

Technology Examples Test online Licensing Documentation Download Contact

HARPEX library API version 1.5

HARPEX library API version 1.5

Table of Contents

1 Introduction

The Harpex API is written in C, and can be called from any programming environment which supports C libraries. The functions and data types are declared in a few header files:

#include “harpex.h”

#include “options.h”

#include “bformat.h”

#include “costereo.h”

#include “vmic.h”

#include “hrtf.h”

#include “horizspk.h”

#include “vbap.h”

#include “hoa.h”

There are always three objects involved in a harpex process:

A harpex object

A direction estimator

A panning function

The direction estimator depends on the format of the input signal, i.e. B-format, double M/S, Blumlein pair etc. The panning function determines the format of the output signal, i.e. binaural HRTF, loudspeaker array or higher-order ambisonics. Any combination of direction estimator and panning function is permissible. The harpex object receives the input signal and uses the direction estimator and panning function to create an output signal.

There are many options that can be set, and to help standardize the naming and meaning of options across different platforms where options can be specified as a text string, an option class is provided for parsing textual options.

Throughout this document, positive X-axis points forwards, positive Y-axis points leftwards, positive Z-axis points upwards, zero azimuth is forwards, positive azimuth is leftwards, zero elevation is horizontal and positive elevation is upwards.

2 Harpex class

This class is used for the signal processing.

2.1 harpex_new

Create new harpex object.

#include “harpex.h”

harpex *harpex_new(harpex_filter *panfunc,

harpex_direst *direst, int nthread,

float freqconstant, float phaseconstant,

float timeconstant, float envelop);

Arguments

panfunc: Panning function object
direst: Direction estimation object
nthread: Number of threads to use for parallel processing. Use 0 to auto-detect number of CPUs. Use 1 to process signal in calling thread. This option is currently only implemented with posix threads (Linux, OS X). In Windows, this option is ignored and nthread=1 is used.
envelop: Degree of envelopment. A guideline is to use 0 for large loudspeaker arrays, 1 for typical home listening, 2 for binaural decoding (see Option class for default values)
phaseconstant: Phase smoothing constant (see Option class for default values)
freqconstant: Frequency smoothing constant (see Option class for default values)
timeconstant: Time smoothing constant (see Option class for default values)

Return value

Pointer to new object or NULL if creation failed

Discussion

Create a new harpex object. The panning function and direction estimation objects must both use the same window length.

2.2 harpex_latency

Query an object for its latency.

#include “harpex.h”

int harpex_latency(harpex *me);

Arguments

me: Object to query

Return value

Latency of signal processing, in samples

Discussion

Queries an object for its latency, i.e. the number of sample frames that the output signal must be advanced in order to be in sync with the input signal. The latency is independent of the number of sample frames which is passed in each call to harpex_calc, but depends on the window length used internally, which is determined by the panning function and direction estimation objects.

2.3 harpex_calc

Process a signal.

#include “harpex.h”

void harpex_calc(harpex *me, float **in, float **out, int nchan,

Arguments

me: Object
in: Input signal
out: Output signal
nchan: Number of input channels
n: Number of sample frames

Return value

Discussion

Process the input signal in in and store an output signal in out. The input and output signals are arranged as non-interleaved sample vectors, i.e. in[channel][time] and out[channel][time].

Any number of sample frames may be passed in each call to harpex_calc, independently of the block size used internally in harpex. If a small number of sample frames is passed, harpex attempts to divide its processing into stages so that the amount of CPU time consumed by harpex_calc is approximately proportional to the number of sample frames. If a large number of sample frames is passed, harpex_calc will divide it into blocks and process each block before returning.

If the input signal is silent, harpex_calc will make shortcuts in the processing, so that very little CPU time is consumed.

2.4 harpex_free

Free a harpex object.

#include “harpex.h”

void harpex_free(harpex *me);

Arguments

me: Object

Return value

Discussion

Free a harpex object. Note: The panning function and direction estimation objects are not freed by harpex_free, and should be freed separately.

3 Panning functions

3.1 hrtf_new

Create a new hrtf panning function.

#include “hrtf.h”

hrtf *hrtf_new(hrtf_hrir_pack set[],

enum hrtf_eq eq,

enum hrtf_interpol interpol);

Arguments

set: HRIR set. See discussion
fs: Sampling frequency in Hz
winlen: Length of FFT window to use internally
pns: Phase noise suppression constant, used with hrtf_interpol=HRTF_SIGMOID (see Option class for default values)
hrtf_eq: Equalization method. See discussion. (see Option class for default values)
hrtf_interpol: Interpolation method. See discussion. (see Option class for default values)

Return value

A new hrtf object or NULL if an error occurred.

Discussion

Create a new hrtf panning function. The object should be freed with hrtf_free. The process of initializing an hrtf object can be somewhat time consuming, since it may involve the resampling of a large set of impulse responses. The hrtf object can be passed as panning function object to harpex_new.

A number of HRIR sets are declared in hrtf.h:

extern hrtf_hrir_pack hrtf_kemar_normal[];

extern hrtf_hrir_pack hrtf_kemar_large_red[];

extern hrtf_hrir_pack hrtf_listen_1002[];

extern hrtf_hrir_pack hrtf_listen_1003[];

extern hrtf_hrir_pack hrtf_listen_1004[];

extern hrtf_hrir_pack hrtf_listen_1005[];

extern hrtf_hrir_pack hrtf_listen_1006[];

extern hrtf_hrir_pack hrtf_listen_1007[];

extern hrtf_hrir_pack hrtf_listen_1008[];

extern hrtf_hrir_pack hrtf_listen_1009[];

extern hrtf_hrir_pack hrtf_listen_1012[];

extern hrtf_hrir_pack hrtf_listen_1013[];

extern hrtf_hrir_pack hrtf_listen_1014[];

extern hrtf_hrir_pack hrtf_listen_1015[];

extern hrtf_hrir_pack hrtf_listen_1016[];

extern hrtf_hrir_pack hrtf_listen_1017[];

extern hrtf_hrir_pack hrtf_listen_1018[];

extern hrtf_hrir_pack hrtf_listen_1020[];

extern hrtf_hrir_pack hrtf_listen_1021[];

extern hrtf_hrir_pack hrtf_listen_1022[];

extern hrtf_hrir_pack hrtf_listen_1023[];

extern hrtf_hrir_pack hrtf_listen_1025[];

extern hrtf_hrir_pack hrtf_listen_1026[];

extern hrtf_hrir_pack hrtf_listen_1028[];

extern hrtf_hrir_pack hrtf_listen_1029[];

extern hrtf_hrir_pack hrtf_listen_1030[];

extern hrtf_hrir_pack hrtf_listen_1031[];

extern hrtf_hrir_pack hrtf_listen_1032[];

extern hrtf_hrir_pack hrtf_listen_1033[];

extern hrtf_hrir_pack hrtf_listen_1034[];

extern hrtf_hrir_pack hrtf_listen_1037[];

extern hrtf_hrir_pack hrtf_listen_1038[];

extern hrtf_hrir_pack hrtf_listen_1039[];

extern hrtf_hrir_pack hrtf_listen_1040[];

extern hrtf_hrir_pack hrtf_listen_1041[];

extern hrtf_hrir_pack hrtf_listen_1042[];

extern hrtf_hrir_pack hrtf_listen_1043[];

extern hrtf_hrir_pack hrtf_listen_1044[];

extern hrtf_hrir_pack hrtf_listen_1045[];

extern hrtf_hrir_pack hrtf_listen_1046[];

extern hrtf_hrir_pack hrtf_listen_1047[];

extern hrtf_hrir_pack hrtf_listen_1048[];

extern hrtf_hrir_pack hrtf_listen_1049[];

extern hrtf_hrir_pack hrtf_listen_1050[];

extern hrtf_hrir_pack hrtf_listen_1051[];

extern hrtf_hrir_pack hrtf_listen_1052[];

extern hrtf_hrir_pack hrtf_listen_1053[];

extern hrtf_hrir_pack hrtf_listen_1054[];

extern hrtf_hrir_pack hrtf_listen_1055[];

extern hrtf_hrir_pack hrtf_listen_1056[];

extern hrtf_hrir_pack hrtf_listen_1057[];

extern hrtf_hrir_pack hrtf_listen_1058[];

extern hrtf_hrir_pack hrtf_listen_1059[];

Equalization methods

HRTF_HORIZ: Equalize HRTF set to the average response in the horizontal plane
HRTF_DIFFUSE: Equqlize HRTF set to the average response overall
HRTF_NONE: Do not equalize HRTF set
HRTF_FRONT: Equalize HRTF set to the response from the front

Interpolation methods

HRTF_NEAREST: Choose the nearest HRTF in each case
HRTF_DIFFPHASE: Interpolate using linear interpolation between group delay
HRTF_ABSPHASE: Interpolate using linear interpolation between phase delay
HRTF_SIGMOID: Use nearest HRTF, suppressing phase noise at high frequencies

3.2 hrtf_free

Free an hrtf object.

#include “hrtf.h”

void hrtf_free(hrtf *me);

Arguments

me: Object

Return value

Discussion

Free an hrtf object.

3.3 vmic_new

Create a new panning function that emulates a virtual microphone array.

#include “vmic.h”

vmic *vmic_new(int winlen,

const struct vmic_mike *mike, int nmike,

Arguments

winlen: Length of FFT window to use internally
fs: Sampling frequency in Hz
mike: Defines location, orientation and characteristic of each virtual microphone. See discussion.
nmike: Number of virtual microphones
pns: Phase noise suppression constant (see Option class for default values)

Return value

A new ortf object or NULL if an error occurred.

Discussion

Create a new vmic panning function. This function simulates the response of an array of first- og higher-order microphones, where each microphone can have any location and orientation. The class of microphone layouts that can be simulated includes XY, ORTF, AB, MS, Double MS, Hamasaki square, etc. The location, orientation and characteristic of each virtual microphone is defined using an array of struct vmic_mike. This struct is defined as

struct vmic_mike {

float azim, elev; // pointing direction, degrees

float polar; // 0=omni, 0.5=cardioid, 1=figure-of-8

float order; // 0=omni, 1=1st order 2=2nd order etc

float pos[3]; // location of microphone, meters (affects phase, not amplitude)

The order parameter is used as an exponent that is applied to the polar pattern.

3.4 vmic_free

Free a vmic object.

#include “vmic.h”

void vmic_free(vmic *me);

Arguments

me: Object

Return value

Discussion

Free an ortf object.

3.5 vbap_new

Create a new vbap panning function object for 3-D loudspeaker arrays.

#include “vbap.h”

vbap *vbap_new(int winlen, int fs, int nspk,

float *azim, float *elev,

float panlaw, char *vrml, int bighole);

Arguments

winlen: Length of FFT window to use with this panning function
fs: Sampling frequency in Hz
nspk: Number of loudspeakers in array
azim: Vector of azimuth of each loudspeaker, in degrees. Front is 0Â°, positive angles to the left
elev: Vector of elevation of each loudspeaker. Horizontal is 0Â°, positive angles upwards
panlaw: Panning law. Defines the amplitude loss in dB when a sound source is located half-way between a pair of loudspeakers.
vrml: Pointer to filename to visualize tesselation as a vrml file. Use NULL to skip visualization.
bighole: Flag to indicate whether “big holes”, typically sound coming from below in half-dome rigs, should be discarded (1) or distributed over the lower ring of speakers (0).

Return value

New vbap object or NULL if an error occurred.

Discussion

Create a new vbap panning function. Use modified Delaunay tesselation to determine loudspeaker triangles. To inspect the chosen tesselation pattern, specify a filename and view the resulting file in a VRML viewer. The vbap object can be passed as panning function object to harpex_new.

3.6 vbap_free

Free a vbap object.

#include “vbap.h”

void vbap_free(vbap *me);

Arguments

me: object

Return value

Discussion

Free a vbap object.

3.7 horizspk_new

Create a new panning function for horizontal loudspeaker arrays.

#include “horizspk.h”

horizspk *horizspk_new(int winlen, int fs, int nband, int nchan, float *freq,

float *azim, int **use, enum horizspk_panlaw *panlaw, float dist, float pns);

Arguments

winlen: Length of FFT window to use with this panning function
fs: Sampling frequency in Hz
nband: Number of frequency bands
nchan: Number of loudspeakers in the array
freq: Crossover frequencies, marking borders between the different frequency ranges. In Hz. See discussion.
azim: Array of azimuths in degrees
use: 2D array of flags indicating which loudspeakers to use in each frequency range. See discussion
panlaw: Array of panning laws, one per frequency range, see discussion (see Option class for default values)
dist: Direction-dependent time-delay is added according to this virtual microphone distance parameter. Meters. (see Option class for default values)
pns: Phase noise suppression constant (see Option class for default values)

Return value

New horizspk object or NULL if an error occurred.

Discussion

Create a new horizspk panning function. The horizspk object can be passed as panning function object to harpex_new. Since different panning functions may be optimal in different frequency ranges and because different loudspeaker arrays may be used in different frequency ranges (sub-woofers, separate tweeters etc), the frequency spectrum can be divided into any number of frequency bands. Each frequency band can use a different pan law and a different subset of the full speaker array. The first frequency band spans from 0 Hz to freq[0] and uses the loudspeakers with index n whose flag use[0][n] is nonzero. The last frequency band spans from freq[nband-1] to fs/2 and uses the loudspeakers with index n whose flag use [nband-1][n] is nonzero. Between these, transfer functions are constructed to be piecewise linear in the linear-frequency domain.

Example

To create an LFE channel with flat response up to 80 Hz, which crosses over with 5 full-bandwith channels up to 120 Hz, use these values:

use={{0,0,0,0,0,1},{1,1,1,1,1,0}}

Panlaw options

HORIZSPK_STEP: Use only nearest loudspeaker
HORIZSPK_3DB: Use 3 dB panning law
HORIZSPK_6DB: Use 6 dB panning law
HORIZSPK_MAXRV: Panning law optimized for high rE with rV=1. Requires more than 2 speakers, covering more than 180Â°
HORIZSPK_MIXED: Use max-rV panning law at low frequencies and 3 dB law at high frequencies

3.8 horizspk_free

Free a horizspk object.

#include “horizspk.h”

void horizspk_free(horizspk *me);

Arguments

me: Object

Return value

Discussion

Free a horizspk object.

3.9 hoa_new

Create a new panning function for higher-order ambisonics output.

#include “hoa.h”

hoa *hoa_new(int winlen, int fs, int order, int withheight

enum hoa_sorting sorting,

enum hoa_norm norm);

Arguments

winlen: Length of FFT window to use with this panning function
fs: Sampling frequency in Hz
order: Ambisonics order of output
withheight: Flag to specify whether to include channels other than purely horizontal ones
sorting: Order of output channels, see discussion (see Option class for default values)
norm: Normalization of output channels, see discussion (see Option class for default values)

Return value

New hoa object or NULL if an error occurred.

Discussion

Create a new hoa panning function. The hoa object can be passed as panning function object to harpex_new. The sorting is one of the following:

HOA_SORT_ACN: Use channel ordering l*(l+1)+m. Note that by this definition, the first four channels are W, Y, Z, X.
HOA_SORT_FUMA: Use FuMa channel order. Only defined up to 3rd order. Note that by this definitions, the first four channels are W, X, Y, Z.

The normalization is one of the following:

HOA_NORM_N3D: Use N3D normalization, defined to give the same amplitude in all channels when encoding an isotropic noise field. Note that W by this definition is scaled by sqrt(1/3) relative to Y, Z and X.
HOA_NORM_SN3D: Use SN3D normalization, equal to N3D multiplied by a factor 1/sqrt(2*l+1). Note that W by this definition is scaled by 1 relative to Y, Z and X.
HOA_NORM_FUMA: Use FuMa normalization, defined to give the same maximum amplitude in all channels when encoding a planewave, except for W, which is scaled by 1/sqrt(2) relative to the other channels. Only defined up to 3rd order.

3.10 hoa_free

Free an hoa object.

#include “hoa.h”

void hoa_free(hoa *me);

Arguments

me: Object

Return value

Discussion

Free an hoa object.

4 Direction estimators

4.1 bformat_new

Create a new direction estimator for first-order B-format input.

#include “bformat.h”

bformat *bformat_new(int winlen, int fs,

float minangle, enum bformat_format matrix);

Arguments

winlen: Length of FFT window to use with this panning function
fs: Sampling frequency in Hz
minangle: Minimum angle between planewaves, degrees (see Option class for default values)
matrix: Which input matrix to use

Return value

New direction estimator object or NULL if an error occurred.

Discussion

Create a new bformat object which handles 2-D or 3-D B-format input. In cases where the decomposition does not exist or where the angle between planewaves is less than minangle, an alternative method is used. The bformat object can be passed as direction estimator object to harpex_new. The following matrices are supported:

HARPEX_BFORMAT2D: 2-D B-format input. The channel order is W, X, Y. The W channel should be scaled such that a planewave along the X axis has an amplitude 3 dB less in W than in X.
HARPEX_BFORMAT3D: 3-D B-format input. The channel order is W, X, Y, Z. The W channel should be scaled such that a planewave along the X axis has an amplitude 3 dB less in W than in X.
HARPEX_AFORMAT: 3-D A-format input. The channel order is ULF, DRF, DLB, URB. Assumes coincident capsules and orthogonal characteristics. Can be modified with bformat_set_pvbalance and bformat_set_capsuledist.
HARPEX_3C: Create a new bformat object which handles cardioid triangle input. The channel order is front, left back, right back.
HARPEX_H2: Create a new bformat object which handles four-channel Zoom H2 input. The channel order is FR, FL, BR, BL. Note that left and right are swapped in the H2, so this is the channel order coming from the H2.
HARPEX_MSM: Create a new bformat object which handles double M/S input. The channel order is front, mid, back. The front and back channels should have equal sensitivity. The side channel should be scaled such that a planewave from the front has the same amplitude in the front channel as the same planewave from the side has in the side channel.
HARPEX_50: ITU 5.0 channel input, transformed into horizontal B-format.

4.2 bformat_set_nfc

Set near-field compensation.

#include “bformat.h”

void bformat_set_nfc(bformat *me, float nfc);

Arguments

me: bformat object
nfc: Distance to loudspeakers, in meters

Discussion

NB! Although the option is applied to the direction estimator, the nfc is meant to compensate for proximity to the loudspeakers.

4.3 bformat_set_capsuledist

Set compensation for capsule spacing.

#include “bformat.h”

void bformat_set_capsuledist(bformat *me, float r);

Arguments

me: bformat object
r: Distance from centre of microphone to membrane, in meters

Discussion

Compensates for phase shift related to finite capsule distance.

4.4 bformat_set_pvbalance

Set pressure/velocity balance.

#include “bformat.h”

void bformat_set_pvbalance(bformat *me, float df, const float *pv, int n);

Arguments

me: bformat object
df: Spacing between measurements, in Hz
pv: Measurements
n: Number of measurements

Discussion

When *pv=1, it is assumed that a planewave will have a total energy in the X, Y and Z channels which is sqrt(3/2) the energy in the W channel. A number different from one means that the total energy in the X, Y and Z channels is greater or smaller by that factor compared to the W channel.

4.5 bformat_set_rtz

Set rotation, zoom and mirror.

#include “bformat.h”

void bformat_set_rtz(bformat *me, float yaw, float pitch, float roll,

const float zoom[3], int mirror);

Arguments

me: bformat object
yaw: Rotation about z axis, degrees
pitch: Rotation about y axis, degrees
roll: Rotation about x axis, degrees
zoom: Vector pointing in the direction to zoom in on (after rotation). The vector should have a length between 0 and 1. The value {0.f, 0.f, 0.f} gives no zoom.
mirror: Mirror about x/z plane (before rotation)

Discussion

Performs a rotation, zoom and (optionally) mirror operation on the input.

4.6 bformat_free

Free a bformat object.

#include “bformat.h”

void bformat_free(bformat *me);

Arguments

me: Object

Return value

Discussion

Free a bformat object.

4.7 costereo_new

Create a new direction estimator for coincident stereo input.

#include “costereo.h”

costereo *costereo_new(int winlen, int fs,

enum costereo_format format,

float minangle);

Arguments

winlen: Length of FFT window to use with this panning function
fs: Sampling frequency in Hz
format: Microphone setup, see discussion
minangle: Minimum angle between planewaves, degrees (see Option class for default values)

Return value

New direction estimator object or NULL if an error occurred.

Discussion

Create a new costereo object which handles coincident microphone input. In cases where the decomposition does not exist or where the angle between planewaves is less than minangle, an alternative method is used. The costereo object can be passed as direction estimator object to harpex_new.

Format options

COSTEREO_BLUMLEINX: Blumlein pair, figure-of-eight microphones oriented at 45Â° and â45Â°
COSTEREO_BLUMLEINT: Blumlein pair, figure-of-eight microphones oriented at 0Â° and 90Â°
COSTEREO_MSO: Mid-side pair, where mid-microphone is omnidirectional. A planewave coming from the side should have the same amplitude in both channels. Channel order: M, S
COSTEREO_MSS: Mid-side pair, where mid-microphone has a subcardioid pattern. A planewave coming from the front should have the same amplitude in the mid channel as the same planewave from the side has in the side channels. Channel order: M, S
COSTEREO_MSC: Mid-side pair, where mid-microphone has a cardioid pattern. A planewave coming from the front should have the same amplitude in the mid channel as the same planewave from the side has in the side channels. Channel order: M, S
COSTEREO_MSH: Mid-side pair, where mid-microphone has a hypercardioid pattern. A planewave coming from the front should have the same amplitude in the mid channel as the same planewave from the side has in the side channels. Channel order: M, S
COSTEREO_OC: Back-to-back cardioids. Channel order: L, R
COSTEREO_XY: Cardioids separated by 90Â° in the horizontal plane. Channel order: L, R

4.8 costereo_free

Free a costereo object.

#include “costereo.h”

void costereo_free(costereo *me);

Arguments

me: Object

Return value

Discussion

Free a costereo object.

5 Option class

This class is used for parsing textual options. It can also create and destroy the other objects as necessary. The available options are the same as in the command-line version of harpex:

-F, –format=<name> Indicates recording format of input file, which is one of

'B-format', 'Blumlein+', 'BlumleinX', 'MS', 'MSM'. Default is

-h, –hrtf=<set> Decode to hrtf, using the specified hrtf set (see list below)

-s, –spk=<...> Decode to loudspeakers layout. For each speaker, specify azimuth

in degrees, optionally followed by colon and elevation in degrees.

Separate speakers with comma. Positive azimuth is to the left,

positive elevation is up. See examples.

-V, –vrml=<filename> Make a VRML file showing loudspeaker positions and tesselation.

-H, –hoa=<order> Decode and reencode to higher-order ambisonics, at the specified

-a, –minangle=<deg> Minimum angle between same-frequency components. Default: 15

-w, –winlen=<samples> Length of analysis frame. Must be power of 2. Default=2048

-f, –freqconstant=<f> Filter constant for frequency smoothing, in octaves. Default=0.1

-t, –timeconstant=<t> Filter constant for time smoothing, in seconds. Default=0.15

-E, –envelop=<e> Degree of envelopment, from 0.0 to 2.0. Default=1.0

-T, –nthread=<n> Number of parallel threads. Default=1. –nthread=0 will detect the

number of processors and create one thread per processor.

Options that only apply to hrtf output:

-i, –interpol=<method> Use the specified hrtf interpolation method, which is one of:

'hybridphase', 'diffphase', 'absphase', 'nearest' or

'hybridnear'. Default is 'hybridnear'.

-e, –eq=<method> Use the specified hrtf equalization method, which is one of:

'none', 'front', 'horiz' or 'diffuse'. Default is 'horiz'

Option that only applies to loudspeaker output:

-l, –panlaw=<dB> Set panning law for loudspeaker decoding, in dB. Default is 4.5.

If no output filename is given, the output file is sent to stdout. If no input filename is

given, the input soundfile is read from stdin. The output file will have the same format,

sampling rate and resolution as the input file. Supported formats are: wav, aiff, aifc, amb.

Available hrtf sets:

kemar_normal, kemar_large_red, listen_1002, listen_1003, listen_1004,

listen_1005, listen_1006, listen_1007, listen_1008, listen_1009,

listen_1012, listen_1013, listen_1014, listen_1015, listen_1016,

listen_1017, listen_1018, listen_1020, listen_1021, listen_1022,

listen_1023, listen_1025, listen_1026, listen_1028, listen_1029,

listen_1030, listen_1031, listen_1032, listen_1033, listen_1034,

listen_1037, listen_1038, listen_1039, listen_1040, listen_1041,

listen_1042, listen_1043, listen_1044, listen_1045, listen_1046,

listen_1047, listen_1048, listen_1049, listen_1050, listen_1051,

listen_1052, listen_1053, listen_1054, listen_1055, listen_1056,

listen_1057, listen_1058, listen_1059

Note that the option object does not split the command line into separate options, and can only be invoked after the option name and value have been determined by other means, which are usually platform-specific.

5.1 harpex_opt

A struct which stores a set of options.

#include “options.h”

struct harpex_opt {

hrtf_hrir_pack *hrtf;

float spkazim[HARPEX_MAXSPK];

float spkelev[HARPEX_MAXSPK];

float spkmicdist;

struct vmic_mike vmic[HARPEX_MAXSPK];

float minangle;

float freqconstant;

float phaseconstant;

float timeconstant;

enum aformat_format mike;

enum hrtf_eq eq;

enum hrtf_interpol interpol;

enum horizspk_panlaw horizpanlaw[HARPEX_MAXBAND];

int spkuse[HARPEX_MAXBAND][HARPEX_MAXSPK];

float freqband[HARPEX_MAXBAND];

int hoawithheight;

enum hoa_sorting hoasort;

enum hoa_norm hoanorm;

enum harpex_format format;

float yaw, pitch, roll, zoom[3];

int pvbalance_n;

float pvbalance_df;

float pvbalance_data[HARPEX_PVDATAMAX];

typedef struct harpex_opt harpex_opt;

Members

hrtf: Pointer to HRTF set. Use NULL for other panning functions. Default: hrtf_kemar_normal
nspk: Number of loudspeakers. Used for horizontal and vbap arrays. Use 0 for ORTF. Default: 0
ortf_angle: Angle between virtual microphones in ortf mode. Degrees. Default: 110
ortf_dist: Distance between virtual microphones in ortf mode. Meters. Default: 0.17
minangle: Minimum angle between planewaves. Degrees. Default: 15
winlen: Length of FFT frames. Samples. Default: 4096
freqconstant: Frequency smoothing constant. Octaves. Default: 0.1
phaseconstant: Phase smoothing constant. Hz. Default: 0
timeconstant: Time smoothing constant. Seconds. Default: 0.05
eq: Equalization method used with HRTF panning functions. Default: HRTF_HORIZ
interpol: Interpolation method used with HRTF panning functions. Default: HRTF_SIGMOID
panlaw: Panning law used with vbap arrays. dB. Use 0 for horizontal loudspeaker arrays. Default: 4.5
horizpanlaw: Panning law used with horizontal loudspeaker arrays. Default: HORIZSPK_MIXED
hoa: Ambisonic order used with HOA panning functions. Default: 0
vrml: Filename of VRML output file used to visualize tesselation. Used with vbap. Default: NULL
hoasort: Channel order used with HOA panning functions. Default: HOA_SORT_ACN
hoanorm: Channel normalization used with HOA panning functions. Default: HOA_NORM_N3D
format: Format of input signal. Default: HARPEX_BFORMAT
nthread: Number of threads for parallel processing. Use 0 to auto-detect number of CPUs. Default: 1
dist: Distance between microphone capsules. Used with A-format input. Meters. Default: 0.01
nfc: Near-field compensation in meters. Used with B-format direction estimators. Default: 0 (off)
pns: Phase noise suppression constant. Hz. Used with HRTF and ORTF. Default: 10000
envelop: Degree of envelopment, from 0 to 2. Default: 1

Discussion

You may set the members of the harpex_opt object directly.

5.2 harpex_options

A struct which associates long option names with one-character names.

#include “options.h”

struct harpex_option {

char character;

struct harpex_option harpex_options[]={

{"distance", 'd'},

{"interpol", 'i'},

{"minangle", 'a'},

{"winlen", 'w'},

{"freqconstant", 'f'},

{"timeconstant", 't'},

{"envelop", 'E'},

{"panlaw", 'l'},

{"hoasort", 'S'},

{"hoanorm", 'N'},

{"nthread",'T'},

{"format",'F'},

Discussion

Defines the names of the options and the character which identifies each option.

5.3 harpex_format

Defines the format of the input signal.

#include “options.h”

enum harpex_format {

HARPEX_BFORMAT,

HARPEX_BFORMAT2D,

HARPEX_BFORMAT3D,

HARPEX_AFORMAT,

HARPEX_COSTEREO

Members

HARPEX_BFORMAT:: Input signal is in B-format (2-D or 3-D)
HARPEX_BFORMAT2D:: Input signal is in B-format (2-D)
HARPEX_BFORMAT3D:: Input signal is in B-format (3-D)
HARPEX_AFORMAT:: Input signal is in A-format (ULF, DRF, DLB, URB)
HARPEX_3C:: Input signal originates from 3 cardioid microphones (0Â°, 120Â°, 240Â°)
HARPEX_H2:: Input signal originates from a Zoom H2 (â90Â°, 90Â°, â120Â°, 120Â°)
HARPEX_MSM:: Input signal is double MS (front, mid, back)
HARPEX_COSTEREO:: Input signal is coincident stereo

5.4 harpex_opt_new

Create new harpex_opt object.

#include “options.h”

harpex_opt *harpex_opt_new (void);

Arguments

Return value

A new option object with default values.

Discussion

Objects created with this function should be freed with harpex_opt_free.

5.5 harpex_opt_free

Free a harpex_obj object.

#include “options.h”

void harpex_opt_free (harpex_opt *opt);

Arguments

opt: Object to free

Return value

Discussion

Free an object created with harpex_opt_new.

5.6 harpex_opt_parse

Parse an option.

#include “options.h”

char *harpex_opt_parse(harpex_opt *opt, char c,

Arguments

opt: Object to modify
c: ID of option to set
optarg: String containing new value of option. May be NULL.

Return value

Pointer to error message or NULL if successful. Do not free the pointer.

Discussion

Parses part of an option string and sets the corresponding option in a harpex_opt object.

5.7 harpex_opt_parselong

Parse an option.

#include “options.h”

char *harpex_opt_parselong(harpex_opt *opt, char *name,

Arguments

opt: Object to modify
name: Name of option to set
optarg: String containing new value of option. May be NULL.

Return value

Pointer to error message or NULL if successful. Do not free the pointer.

Discussion

Parses part of an option string and sets the corresponding option in a harpex_opt object.

5.8 harpex_opt_ichan

Query an option object for the number of channels in the input signal.

#include “options.h”

int harpex_opt_ichan(harpex_opt *opt);

Arguments

opt: Object to query

Return value

Minimum number of input channels.

Discussion

Query an option object for the minimum number of channels in the input signal.

5.9 harpex_opt_makeobjs

Create objects described by a harpex_opt object.

#include “options.h”

char *harpex_opt_makeobjs(harpex_opt *opt, int samplerate,

Arguments

opt: Options defining the objects to create
samplerate: Samplerate in Hz
h: A pointer to the created harpex object will be stored here

Return value

Pointer to error message or NULL if successful. Do not free the pointer.

Discussion

Create a harpex object, an direction estimator and a panning function as defined by the options. The created objects should be freed by passing the pointer stored in h to harpex_opt_freeobjs.

5.10 harpex_opt_freeobjs

Free the objects created by harpex_opt_makeobjs

#include “options.h”

void harpex_opt_freeobjs(harpex *h);

Arguments

h: A harpex object created by harpex_opt_makeobjs

Return value

Discussion

Free the objects created by harpex_opt_makeobjs

6 Examples

6.1 Using the hrtf and bformat classes

#include “harpex.h”

#include “bformat.h”

#include “hrtf.h”

bformat *direst=bformat_new(4096, 44100, 0, 15);

hrtf *panfunc=hrtf_new(hrtf_listen_1033, 44100, 4096,

10000, HRTF_NONE, HRTF_SIGMOID);

if (!panfunc) {

harpex *h=harpex_new((harpex_filter *)panfunc,

(harpex_direst *)direst,

1, 0.1, 0.15, 2);

harpex_calc(h, in, out, 100000);

harpex_free(h);

hrtf_free(panfunc);

bformat_free(direst);

6.2 Using the option class

#include “options.h”

harpex_opt *opt=harpex_opt_new();

harpex_opt_parselong(opt, “eq”, “none”);

harpex_opt_parselong(opt, “hrtf”, “listen_1033”);

char *err=harpex_opt_makeobjs(opt, 44100, &h);

harpex_calc(h, in, out, 100000);

harpex_opt_freeobjs(h);

harpex_opt_free(opt);

Â© 2011â2013 Harpex Audio GmbH