# hoa.lib

Faust library for high order ambisonic. Its official prefix is `ho`

.

#### References

## Encoding/decoding Functions

`(ho.)encoder`

Ambisonic encoder. Encodes a signal in the circular harmonics domain depending on an order of decomposition and an angle.

#### Usage

```
encoder(N, x, a) : _
```

Where:

`N`

: the ambisonic order (constant numerical expression)`x`

: the signal`a`

: the angle

`(ho.)rEncoder`

Ambisonic encoder in 2D including source rotation. A mono signal is encoded at a certain ambisonic order with two possible modes: either rotation with an angular speed, or static with a fixed angle (when speed is zero).

#### Usage

```
_ : rEncoder(N, sp, a, it) : _,_, ...
```

Where:

`N`

: the ambisonic order (constant numerical expression)`sp`

: the azimuth speed expressed as angular speed (2PI/sec), positive or negative`a`

: the fixed azimuth when the rotation stops (sp = 0) in radians`it`

: interpolation time (in milliseconds) between the rotation and the fixed modes

`(ho.)stereoEncoder`

Encoding of a stereo pair of channels with symetric angles (a/2, -a/2).

#### Usage

```
_,_ : stereoEncoder(N, a) : _,_, ...
```

Where:

`N`

: the ambisonic order (constant numerical expression)`a`

: opening angle in radians, left channel at a/2 angle, right channel at -a/2 angle

`(ho.)multiEncoder`

Encoding of a set of P signals distributed on the unit circle according to a list of P speeds and P angles.

#### Usage

```
_,_, ... : multiEncoder(N, lspeed, langle, it) : _,_, ...
```

Where:

`N`

: the ambisonic order (constant numerical expression)`lspeed`

: a list of P speeds in turns by second (one speed per input signal, positive or negative)`langle`

: a list of P angles in radians on the unit circle to localize the sources (one angle per input signal)`it`

: interpolation time (in milliseconds) between the rotation and the fixed modes.

`(ho.)decoder`

Decodes an ambisonics sound field for a circular array of loudspeakers.

#### Usage

```
_ : decoder(N, P) : _
```

Where:

`N`

: the ambisonic order (constant numerical expression)`P`

: the number of speakers (constant numerical expression)

#### Note

The number of loudspeakers must be greater or equal to 2n+1. It's preferable to use 2n+2 loudspeakers.

`(ho.)decoderStereo`

Decodes an ambisonic sound field for stereophonic configuration.
An "home made" ambisonic decoder for stereophonic restitution
(30° - 330°): Sound field lose energy around 180°. You should
use `inPhase`

optimization with ponctual sources.

#### Usage

```
_ : decoderStereo(N) : _
```

Where:

`N`

: the ambisonic order (constant numerical expression)

`(ho.)iBasicDecoder`

The irregular basic decoder is a simple decoder that projects the incoming ambisonic situation to the loudspeaker situation (P loudspeakers) whatever it is, without compensation. When there is a strong irregularity, there can be some discontinuity in the sound field.

#### Usage

```
_,_, ... : iBasicDecoder(N,la, direct, shift) : _,_, ...
```

Where:

`N`

: the ambisonic order (there are 2*N+1 inputs to this function)`la`

: the list of P angles in degrees, for instance (0, 85, 182, 263) for four loudspeakers`direct`

: 1 for direct mode, -1 for the indirect mode (changes the rotation direction)`shift`

: angular shift in degrees to easily adjust angles

`(ho.)circularScaledVBAP`

The function provides a circular scaled VBAP with all loudspeakers and the virtual source on the unit-circle.

#### Usage

```
_ : circularScaledVBAP(l, t) : _,_, ...
```

Where:

`l`

: the list of angles of the loudspeakers in degrees, for instance (0, 85, 182, 263) for four loudspeakers`t`

: the current angle of the virtual source in degrees

`(ho.)imlsDecoder`

Irregular decoder in 2D for an irregular configuration of P loudspeakers using 2D VBAP for compensation.

#### Usage

```
_,_, ... : imlsDecoder(N,la, direct, shift) : _,_, ...
```

Where:

`N`

: the ambisonic order (constant numerical expression)`la`

: the list of P angles in degrees, for instance (0, 85, 182, 263) for four loudspeakers`direct`

: 1 for direct mode, -1 for the indirect mode (changes the rotation direction)`shift`

: angular shift in degrees to easily adjust angles

`(ho.)iDecoder`

General decoder in 2D enabling an irregular multi-loudspeaker configuration and to switch between multi-channel and stereo.

#### Usage

```
_,_, ... : iDecoder(N, la, direct, st, g) : _,_, ...
```

Where:

`N`

: the ambisonic order (constant numerical expression)`la`

: the list of angles in degrees`direct`

: 1 for direct mode, -1 for the indirect mode (changes the rotation direction)`shift`

: angular shift in degrees to easily adjust angles`st`

: 1 for stereo, 0 for multi-loudspeaker configuration. When 1, stereo sounds goes through the first two channels`g`

: gain between 0 and 1

## Optimization Functions

Functions to weight the circular harmonics signals depending to the
ambisonics optimization.
It can be `basic`

for no optimization, `maxRe`

or `inPhase`

.

`(ho.)optimBasic`

The basic optimization has no effect and should be used for a perfect circle of loudspeakers with one listener at the perfect center loudspeakers array.

#### Usage

```
_ : optimBasic(N) : _
```

Where:

`N`

: the ambisonic order (constant numerical expression)

`(ho.)optimMaxRe`

The maxRe optimization optimizes energy vector. It should be used for an auditory confined in the center of the loudspeakers array.

#### Usage

```
_ : optimMaxRe(N) : _
```

Where:

`N`

: the ambisonic order (constant numerical expression)

`(ho.)optimInPhase`

The inPhase optimization optimizes energy vector and put all loudspeakers signals in phase. It should be used for an auditory.

#### Usage

```
_ : optimInPhase(N) : _
```

Where:

`N`

: the ambisonic order (constant numerical expression)

`(ho.)optim`

Ambisonic optimizer including the three elementary optimizers:
`(ho).optimBasic`

, `(ho).optimMaxRe`

and `(ho.)optimInPhase`

.

#### Usage

```
_,_, ... : optim(N, ot) : _,_, ...
```

Where:

`N`

: the ambisonic order (constant numerical expression)`ot`

: optimization type (0 for`optimBasic`

, 1 for`optimMaxRe`

, 2 for`optimInPhase`

)

`(ho.)wider`

Can be used to wide the diffusion of a localized sound. The order depending signals are weighted and appear in a logarithmic way to have linear changes.

#### Usage

```
_ : wider(N,w) : _
```

Where:

`N`

: the ambisonic order (constant numerical expression)`w`

: the width value between 0 - 1

`(ho.)mirror`

Mirroring effect on the sound field.

#### Usage

```
_,_, ... : mirror(N, fa) : _,_, ...
```

Where:

`N`

: the ambisonic order (constant numerical expression)`fa`

: mirroring type (1 = original sound field, 0 = original+mirrored sound field, -1 = mirrored sound field)

`(ho.)map`

It simulates the distance of the source by applying a gain on the signal and a wider processing on the soundfield.

#### Usage

```
map(N, x, r, a)
```

Where:

`N`

: the ambisonic order (constant numerical expression)`x`

: the signal`r`

: the radius`a`

: the angle in radian

`(ho.)rotate`

Rotates the sound field.

#### Usage

```
_ : rotate(N, a) : _
```

Where:

`N`

: the ambisonic order (constant numerical expression)`a`

: the angle in radian

`(ho.)scope`

Produces an XY pair of signals representing the ambisonic sound field.

#### Usage

```
_,_, ... : scope(N, rt) : _,_
```

Where:

`N`

: the ambisonic order (constant numerical expression)`rt`

: refreshment time in milliseconds

## Spatial Sound Processes

We propose implementations of processes intricated to the ambisonic model. The process is implemented using as many instances as the number of harmonics at at certain order. The key control parameters of these instances are computed thanks to distribution functions (th functions below) and to a global driving factor.

`(ho.).fxDecorrelation`

Spatial ambisonic decorrelation in fx mode.

`fxDecorrelation`

applies decorrelations to spatial components already created.
The decorrelation is defined for each #i spatial component among P=2*N+1 at the ambisonic order `N`

as a delay of 0 if factor `fa`

is under a certain value 1-(i+1)/P and d*F((i+1)/p) in the contrary case,
where `d`

is the maximum delay applied (in samples) and F is a distribution function for durations.
The user can choose this delay time distribution among 22 different ones.
The delay increases according to the index of ambisonic components.
But it increases at each step and it is modulated by a threshold.
Therefore, delays are progressively revealed when the factor increases:

- when the factor is close to 0, only upper components are delayed;
- when the factor increases, more and more components are delayed.

#### Usage

```
_,_, ... : fxDecorrelation(N, d, wf, fa, fd, tf) : _,_, ...
```

Where:

`N`

: the ambisonic order (constant numerical expression)`d`

: the maximum delay applied (in samples)`wf`

: window frequency (in Hz) for the overlapped delay`fa`

: decorrelation factor (between 0 and 1)`fd`

: feedback / level of reinjection (between 0 and 1)`tf`

: type of function of delay distribution (integer, between 0 and 21)

`(ho.).synDecorrelation`

Spatial ambisonic decorrelation in syn mode.

`synDecorrelation`

generates spatial decorrelated components in ambisonics from one mono signal.
The decorrelation is defined for each #i spatial component among P=2*N+1 at the ambisonic order `N`

as a delay of 0 if factor `fa`

is under a certain value 1-(i+1)/P and d*F((i+1)/p) in the contrary case,
where `d`

is the maximum delay applied (in samples) and F is a distribution function for durations.
The user can choose this delay time distribution among 22 different ones.
The delay increases according to the index of ambisonic components.
But it increases at each step and it is modulated by a threshold.
Therefore, delays are progressively revealed when the factor increases:

- when the factor is close to 0, only upper components are delayed;
- when the factor increases, more and more components are delayed.

When the factor is between [0; 1/P], upper harmonics are progressively faded and the level of the H0 component is compensated to avoid source localization and to produce a large mono.

#### Usage

```
_,_, ... : synDecorrelation(N, d, wf, fa, fd, tf) : _,_, ...
```

Where:

`N`

: the ambisonic order (constant numerical expression)`d`

: the maximum delay applied (in samples)`wf`

: window frequency (in Hz) for the overlapped delay`fa`

: decorrelation factor (between 0 and 1)`fd`

: feedback / level of reinjection (between 0 and 1)`tf`

: type of function of delay distribution (integer, between 0 and 21)

`(ho.).fxRingMod`

Spatial ring modulation in syn mode.

`fxRingMod`

applies ring modulation to spatial components already created.
The ring modulation is defined for each spatial component among P=2*n+1 at the ambisonic order `N`

.
For each spatial component #i, the result is either the original signal or a ring modulated signal
according to a threshold that is i/P.

The general process is drive by a factor `fa`

between 0 and 1 and a modulation frequency `f0`

.
If `fa`

is greater than theshold (P-i-1)/P, the ith ring modulator is on with carrier frequency of f0*(i+1)/P.
On the contrary, it provides the original signal.

Therefore ring modulators are progressively revealed when `fa`

increases.

#### Usage

```
_,_, ... : fxRingMod(N, f0, fa, tf) : _,_, ...
```

Where:

`N`

: the ambisonic order (constant numerical expression)`f0`

: the maximum delay applied (in samples)`fa`

: decorrelation factor (between 0 and 1)`tf`

: type of function of delay distribution (integer, between 0 and 21)

`(ho.).synRingMod`

Spatial ring modulation in syn mode.

`synRingMod`

generates spatial components in ambisonics from one mono signal thanks to ring modulation.
The ring modulation is defined for each spatial component among P=2*n+1 at the ambisonic order `N`

.
For each spatial component #i, the result is either the original signal or a ring modulated signal
according to a threshold that is i/P.

The general process is drive by a factor `fa`

between 0 and 1 and a modulation frequency `f0`

.
If `fa`

is greater than theshold (P-i-1)/P, the ith ring modulator is on with carrier frequency of f0*(i+1)/P.
On the contrary, it provides the original signal.

Therefore ring modulators are progressively revealed when `fa`

increases.
When the factor is between [0; 1/P], upper harmonics are progressively faded and the level of the H0 component is compensated
to avoid source localization and to produce a large mono.

#### Usage

```
_,_, ... : synRingMod(N, f0, fa, tf) : _,_, ...
```

Where:

`N`

: the ambisonic order (constant numerical expression)`f0`

: the maximum delay applied (in samples)`fa`

: decorrelation factor (between 0 and 1)`tf`

: type of function of delay distribution (integer, between 0 and 21)

## 3D Functions

`(ho.)encoder3D`

Ambisonic encoder. Encodes a signal in the circular harmonics domain depending on an order of decomposition, an angle and an elevation.

#### Usage

```
encoder3D(N, x, a, e) : _
```

Where:

`N`

: the ambisonic order (constant numerical expression)`x`

: the signal`a`

: the angle`e`

: the elevation

`(ho.)rEncoder3D`

Ambisonic encoder in 3D including source rotation. A mono signal is encoded at at certain ambisonic order with two possible modes: either rotation with 2 angular speeds (azimuth and elevation), or static with a fixed pair of angles.

`rEncoder3D`

is a standard Faust function.

#### Usage

```
_ : rEncoder3D(N, azsp, elsp, az, el, it) : _,_, ...
```

Where:

`N`

: the ambisonic order (constant numerical expression)`azsp`

: the azimuth speed expressed as angular speed (2PI/sec), positive or negative`elsp`

: the elevation speed expressed as angular speed (2PI/sec), positive or negative`az`

: the fixed azimuth when the azimuth rotation stops (azsp = 0) in radians`el`

: the fixed elevation when the elevation rotation stops (elsp = 0) in radians`it`

: interpolation time (in milliseconds) between the rotation and the fixed modes

`(ho.)optimBasic3D`

The basic optimization has no effect and should be used for a perfect sphere of loudspeakers with one listener at the perfect center loudspeakers array.

#### Usage

```
_ : optimBasic3D(N) : _
```

Where:

`N`

: the ambisonic order (constant numerical expression)

`(ho.)optimMaxRe3D`

The maxRe optimization optimize energy vector. It should be used for an auditory confined in the center of the loudspeakers array.

#### Usage

```
_ : optimMaxRe3D(N) : _
```

Where:

`N`

: the ambisonic order (constant numerical expression)

`(ho.)optimInPhase3D`

The inPhase Optimization optimizes energy vector and put all loudspeakers signals in phase. It should be used for an auditory.

#### Usage

```
_ : optimInPhase3D(N) : _
```

Where:

`N`

: the ambisonic order (constant numerical expression)

`(ho.)optim3D`

Ambisonic optimizer including the three elementary optimizers:
`(ho).optimBasic3D`

, `(ho).optimMaxRe3D`

and `(ho.)optimInPhase3D`

.

#### Usage

```
_,_, ... : optim3D(N, ot) : _,_, ...
```

Where:

`N`

: the ambisonic order (constant numerical expression)`ot`

: optimization type (0 for optimBasic, 1 for optimMaxRe, 2 for optimInPhase)