ambisonic.lib

//############################################################ ambisonic.lib ###
//
// A library for general ambisonic documentation
//
// * ENCODERS
// * DECODERS
// *
// *
// *
//
//##############################################################################

/*******************************************************************************
Except where noted otherwise, Copyright (C) 2019-2020 by SEAM

GRAME LICENSE

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the Free
Software Foundation; either version 2.1 of the License, or (at your option) any
later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along
with the GNU C Library; if not, write to the Free Software Foundation, Inc., 59
Temple Place, Suite 330, Boston, MA 02111-1307 USA.

EXCEPTION TO THE LGPL LICENSE : As a special exception, you may create a larger
FAUST program which directly or indirectly imports this library file and still
distribute the compiled code generated by the FAUST compiler, or a modified
version of this compiled code, under your own copyright and license. This
EXCEPTION TO THE LGPL LICENSE explicitly grants you the right to freely choose
the license for the resulting compiled code. In particular the resulting compiled
code has no obligation to be LGPL or GPL. For example you are free to choose a
commercial or closed source license or any other license if you decide so.
*******************************************************************************/

declare name "Ambisonic Elements Faust Library";
declare version "0.1";
declare author "Giuseppe Silvi";
declare license "CC4";

//================================================================= ENCODERS ===
//==============================================================================
//------------------------------------------------------------------------------
// MS STEREO TO FIRST ORDER B-FORMAT ENCODER
//------------------------------------------------------------------------------
// Converts a Mid-Side Stereo stream into Firts Order B-Format
//
// #### Reference
//
// #### Usage
//
// ```
// _,_ : ms2bfmt : _,_,_,_
// ```
//
// Where the two inputs are respectively:
// Mid and Side
//
// Where the four outpust are respectively:
// W,X,Y,Z
//
//------------------------------------------------------------------------------
ms2bfmt = (_ <: _,_), _;

//------------------------------------------------------------------------------
// LR STEREO TO FIRST ORDER B-FORMAT ENCODER
//------------------------------------------------------------------------------
// Converts a Left-Right Stereo stream into Mid-Side and then into
// Firts Order B-Format
//
// #### Reference
//
// #### Usage
//
// ```
// _,_ : lr2bfmt : _,_,_,_
// ```
//
// Where the two inputs are respectively:
// L,R
//
// Where the four outpust are respectively:
// W,X,Y,Z
//
//------------------------------------------------------------------------------
lr2ms2bfmt = sdmx : ms2bfmt;

//================================================================= DECODERS ===
//==============================================================================
//------------------------------------------------------------------------------
// FIRST ORDER PLANAR B-FORMAT TO MONO DECODER
//------------------------------------------------------------------------------
// Converts a First Order Planar B-Format into mono first order signal
//
// #### Reference
// https://en.wikipedia.org/wiki/Ambisonics
//
// The B-format components can be combined to derive virtual microphones with
// any first-order polar pattern (omnidirectional, cardioid, hypercardioid,
// figure-of-eight or anything in between) pointing in any direction. Several
// such microphones with different parameters can be derived at the same time,
// to create coincident stereo pairs (such as a Blumlein) or surround arrays.
// A horizontal virtual microphone at horizontal angle Θ \Theta with pattern
// 0 ≤ p ≤ 1 0 \leq p \leq 1 is given by
// 
// This virtual mic is free-field normalised, which means it has a constant
// gain of one for on-axis sounds. The illustration on the left shows some
// examples created with this formula. Virtual microphones can be manipulated
// in post-production: desired sounds can be picked out, unwanted ones
// suppressed, and the balance between direct and reverberant sound can be
// fine-tuned during mixing.
//
// #### Usage
//
// ```
// encoder(x) = hgroup("BFMT MONO-DECODER", x);
// azi = encoder(vslider("[01] Azimuth [style:knob]", 0, 0, 360, 0.1) : deg2rad : si.smoo);
// p = encoder(vslider("[02] Polar [style:knob]", 0.5, 0, 1, 0.01) : si.smoo);
// deg2rad = *(ma.PI/180);
// process = _,_,_ : pbf2hm(azi,p) : _;
// ```
//
// Where the four inputs are respectively:
// W,X,Y
//
// Where the output is a mono signal with modulable polar pattern:
// out: m
// polar pattern: p
//
//------------------------------------------------------------------------------
pbf2hm(azi,p) = p*(sqrt(2)*(_))+((1-p)*((_*cos(azi))+(_*sin(azi))));

//------------------------------------------------------------------------------
// FIRST ORDER B-FORMAT TO REGULAR POLYGON
//------------------------------------------------------------------------------
// Converts a First Order B-Format n mono first order signal on the edge of a
// polygon
//
// #### Reference
// https://en.wikipedia.org/wiki/Ambisonics
//
// #### Usage
//
// ```
// _,_,_ : bfmt2m : _
// ```
//
// Where the two inputs are respectively:
// W,X,Y,Z
//
// Where the output is a mono signal with modulable polar pattern:
// m
//
//------------------------------------------------------------------------------
pbf2poly(n,p) = polygon
  with{
      azi(n) = 360/(n) : deg2rad;
      polygon(n) = par(i, n, pbf2m);
};