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 >

6.1 Using the hrtf and bformat classes >

6.2 Using the option class >

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:

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

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

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

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

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.

Arguments

set

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

Interpolation methods

HRTF_NEAREST

3.2 hrtf_free

Free an hrtf object.

#include “hrtf.h”

void hrtf_free(hrtf *me);

Arguments

me

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

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

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

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

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

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

3.8 horizspk_free

Free a horizspk object.

#include “horizspk.h”

void horizspk_free(horizspk *me);

Arguments

me

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

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

The normalization is one of the following:

HOA_NORM_N3D

3.10 hoa_free

Free an hoa object.

#include “hoa.h”

void hoa_free(hoa *me);

Arguments

me

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

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

4.2 bformat_set_nfc

Set near-field compensation.

#include “bformat.h”

void bformat_set_nfc(bformat *me, float nfc);

Arguments

me

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

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

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 rotate, float tilt, float tumble,

float zoom, int mirror);

Arguments

me

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

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

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

4.8 costereo_free

Free a costereo object.

#include “costereo.h”

void costereo_free(costereo *me);

Arguments

me

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

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.

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:

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

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

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

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

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

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

Return value

Discussion

Free the objects created by harpex_opt_makeobjs

6 Examples

6.1 Using the hrtf and bformat classes

6.2 Using the option class

Â© 2011 Harpex Ltd