%% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[a4paper,10pt,english]{sphinxmanual}
\ifdefined\pdfpxdimen
   \let\sphinxpxdimen\pdfpxdimen\else\newdimen\sphinxpxdimen
\fi \sphinxpxdimen=.75bp\relax

\usepackage[utf8]{inputenc}
\ifdefined\DeclareUnicodeCharacter
 \ifdefined\DeclareUnicodeCharacterAsOptional
  \DeclareUnicodeCharacter{"00A0}{\nobreakspace}
  \DeclareUnicodeCharacter{"2500}{\sphinxunichar{2500}}
  \DeclareUnicodeCharacter{"2502}{\sphinxunichar{2502}}
  \DeclareUnicodeCharacter{"2514}{\sphinxunichar{2514}}
  \DeclareUnicodeCharacter{"251C}{\sphinxunichar{251C}}
  \DeclareUnicodeCharacter{"2572}{\textbackslash}
 \else
  \DeclareUnicodeCharacter{00A0}{\nobreakspace}
  \DeclareUnicodeCharacter{2500}{\sphinxunichar{2500}}
  \DeclareUnicodeCharacter{2502}{\sphinxunichar{2502}}
  \DeclareUnicodeCharacter{2514}{\sphinxunichar{2514}}
  \DeclareUnicodeCharacter{251C}{\sphinxunichar{251C}}
  \DeclareUnicodeCharacter{2572}{\textbackslash}
 \fi
\fi
\usepackage{cmap}
\usepackage[T1]{fontenc}
\usepackage{amsmath,amssymb,amstext}
\usepackage{babel}
\usepackage{times}
\usepackage[Bjarne]{fncychap}
\usepackage[dontkeepoldnames]{sphinx}

\usepackage{geometry}

% Include hyperref last.
\usepackage{hyperref}
% Fix anchor placement for figures with captions.
\usepackage{hypcap}% it must be loaded after hyperref.
% Set up styles of URL: it should be placed after hyperref.
\urlstyle{same}
\addto\captionsenglish{\renewcommand{\contentsname}{Contents}}

\addto\captionsenglish{\renewcommand{\figurename}{Fig.}}
\addto\captionsenglish{\renewcommand{\tablename}{Table}}
\addto\captionsenglish{\renewcommand{\literalblockname}{Listing}}

\addto\captionsenglish{\renewcommand{\literalblockcontinuedname}{continued from previous page}}
\addto\captionsenglish{\renewcommand{\literalblockcontinuesname}{continues on next page}}

\addto\extrasenglish{\def\pageautorefname{page}}

\setcounter{tocdepth}{2}



\title{VISR User documentation}
\date{Oct 19, 2018}
\release{}
\author{The S3A project team}
\newcommand{\sphinxlogo}{\vbox{}}
\renewcommand{\releasename}{Release}
\makeindex

\begin{document}

\maketitle
\sphinxtableofcontents
\phantomsection\label{\detokenize{index::doc}}



\chapter{About}
\label{\detokenize{about:about}}\label{\detokenize{about::doc}}\label{\detokenize{about:visr-user-manual}}
The VISR framework is a collection of software for audio processing that forms the backbone for most of the technology created in S3A. In this extensible software framework, complex audio algorithms can be formed by interconnecting existing building blocks, termed components.

It can be used either interactively in the Python language, in custom applications (for instance in written C++, or integrated into other applications, for instance as DAW plugins or Max/MSP externals. While the VISR provides several renderers and building blocks for spatial and object-based audio, it is nonetheless a generic audio processing framework that can be used in other applications, for example array processing or hearing aid prototypes. The Python integration makes the system accessible, and enables easy algorithm development and prototyping.


\chapter{Getting started with the VISR framework: Overview}
\label{\detokenize{getting-started:getting-started-with-the-visr-framework-overview}}\label{\detokenize{getting-started::doc}}

\section{Python integration}
\label{\detokenize{getting-started:python-integration}}\label{\detokenize{getting-started:overview-python-integration}}

\chapter{Basic tutorial}
\label{\detokenize{basic_tutorial::doc}}\label{\detokenize{basic_tutorial:basic-tutorial}}\label{\detokenize{basic_tutorial:id1}}
This tutorial explains the first steps for using the VISR framework by creating and running an audio renderer.
It is based on the conference paper {[}{]}.


\chapter{People}
\label{\detokenize{people:people}}\label{\detokenize{people::doc}}

\chapter{Getting VISR}
\label{\detokenize{index:getting-visr}}

\section{Download}
\label{\detokenize{download::doc}}\label{\detokenize{download:download}}
The VISR framework can be obtained in diffeent forms.
FOr most persons, however, downloading and installing an installer package is the most convenient way to use this framework.

Installation packages can be downloaded from the \sphinxhref{http://s3a-spatialaudio.org}{S3A software download page} .

Installation packages are available for the following platforms:
\begin{quote}
\begin{description}
\item[{Windows (x86\_64)}] \leavevmode
Recent versions (Windows 8 and Windows 10) 64 Bit only

\item[{Mac OS X}] \leavevmode
Version 10.11 and above, 64 Bit only

\item[{Linux}] \leavevmode
Ubuntu 16.04 LTS and Ubuntu 18.04 LTS, 64 bit

\item[{Rasspberry Pi (ARM)}] \leavevmode
Raspbian Stretch, 32 Bit

\end{description}
\end{quote}


\section{Installing VISR}
\label{\detokenize{installation::doc}}\label{\detokenize{installation:installing-visr}}
Binary installation packages are the suggested way to uses the VISR framework.
A binary installers enables all uses of the framework, including
\begin{itemize}
\item {} 
Running standalone applications

\item {} 
Using DAW plugins based on the VISR

\item {} 
Using the Python interfaces and creating new functionality in Python

\item {} 
Creating standalone applications and extension libraries in C++

\end{itemize}

\begin{sphinxadmonition}{hint}{Hint:}
Building the VISR from source is necessary only in these cases:
\begin{itemize}
\item {} 
Porting it to a platform where no binary installer exists

\item {} 
Fixing or changing the internal workings of the framework.

\end{itemize}
\end{sphinxadmonition}

Installation packages are available on the \sphinxhref{http://s3a-audio.space}{S3A Software download page}.

\begin{sphinxadmonition}{note}{Note:}
If you plan to use the Python integration of the VISR framework (see {\hyperref[\detokenize{getting-started:overview-python-integration}]{\sphinxcrossref{\DUrole{std,std-ref}{Python integration}}}}), you need to select an installation package matching the Python version you are using, for example \sphinxstylestrong{VISR-X.X.X-python36-Windows.exe}.
\end{sphinxadmonition}


\subsection{Windows}
\label{\detokenize{installation:windows}}\label{\detokenize{installation:installation-windows}}
The graphical installer is provides as an \sphinxstylestrong{.exe} file and provides a dialog-based, component-enables installation.
Figure {\hyperref[\detokenize{installation:figure-windows-installer}]{\sphinxcrossref{figure\_windows\_installer}}} shows the component selection dialog of the installer. The choices are detailed below in section {\hyperref[\detokenize{installation:installation-component-description}]{\sphinxcrossref{\DUrole{std,std-ref}{Installation components}}}}.

\begin{figure}[htbp]
\centering
\capstart

\noindent\sphinxincludegraphics[scale=1.0]{{windows_installer}.png}
\caption{Graphical Windows installer.}\label{\detokenize{installation:figure-windows-installer}}\label{\detokenize{installation:id2}}\end{figure}

An executable installer (.exe) with a graphical user interface and corresponding uninstall functionality. Supported are 64-bit versions of Windows.
If required, install the “Microsoft Visual C++ Redistributable for Visual Studio 2017”, package,
for example from the \sphinxhref{https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads}{Visual C++ downloads page}.

On Windows, it is necessary to add the directory containing the VISR libraries (DLLs) as well as the directory containing third-party libraries shipped with the VISR installer to the \sphinxstylestrong{PATH} variable.
To this end, open the environment variable editor (Settings -\textgreater{} System -\textgreater{} Advanced system settings -\textgreater{} Environment variables).
The environment variable on Windows 10 is depicted in figure windows\_environment\_variables\_editor .

\begin{figure}[htbp]
\centering
\capstart

\noindent\sphinxincludegraphics[scale=0.5]{{windows_environment_variables_editor}.png}
\caption{Environment variable editor on Windows 10.}\label{\detokenize{installation:windows-environment-variables-editor}}\label{\detokenize{installation:id3}}\end{figure}

Append the value “C:Program FilesVISR-X.X.Xlib;C:Program FilesVISR-X.X.X3rd” if the standard installation location was used. (Note: Replace \sphinxstylestrong{X.X.X} with the actual version number of VISR.
Depending on your system permissions and whether you VISR shall be used by all users of the computer, you can either set the \sphinxstylestrong{PATH} user variable or the \sphinxstylestrong{PATH} system variable.

\begin{sphinxadmonition}{note}{Note:}
Any applications used to access VISR (for example command line terminals, Python development environments, or DAWs) must be closed and reopened before the changed paths take effect.
\end{sphinxadmonition}

Append the path ‘’\textless{}install-directory\textgreater{}/lib’’ to the path variable, where ‘’install\_diectory’’ is the directory specified during the installation.
For the default path, the setting would be ‘’c:Program FilesVISR-N.N.Nlib’‘, where ‘’N.N.N is replaced by the actual version number.
If the \sphinxstylestrong{PATH} variable is edited as a string, subsequent paths are separated by semicolons.

\begin{sphinxadmonition}{note}{Note:}
Future versions of the installer might adjust the paths automatically.
However, as pointed out in
\sphinxhref{http://nsis.sourceforge.net/Path\_Manipulation}{NSIS Path manipulation},
this needs an extremely cautious implementation to avoid potential damage to users’ systems.
\end{sphinxadmonition}

To use standalone applications (see section {\hyperref[\detokenize{using-standalone-renderers:using-visr-using-standalone-renderers}]{\sphinxcrossref{\DUrole{std,std-ref}{Using standalone applications}}}}), it may be useful to add the \sphinxstylestrong{bin/} directory to the user or system path.
For the default installation location, add ‘’c:Program FilesVISR-N.N.Nbin’’ to the \sphinxstylestrong{\%PATH\%} environment variable.


\subsection{Mac OS X}
\label{\detokenize{installation:mac-os-x}}
An installer with a graphical user interface guides through the installation process and allows the selection of optional components.
Figure {\hyperref[\detokenize{installation:figure-visr-macos-installer}]{\sphinxcrossref{\DUrole{std,std-ref}{Component-based installer for Mac OS X.}}}} shows a screenshot of this installer.
By default, it installs the VISR into the directory \sphinxstylestrong{/Applications/VISR-X.X.X/} where \sphinxstylestrong{X.X.X} denotes the version number.

\begin{figure}[htbp]
\centering
\capstart

\noindent\sphinxincludegraphics[scale=0.5]{{visr_macos_installer}.png}
\caption{Component-based installer for Mac OS X.}\label{\detokenize{installation:figure-visr-macos-installer}}\label{\detokenize{installation:id4}}\end{figure}

To access the component selection dialog, use the button “Customize” on the “Installation Type” screen (see figure {\hyperref[\detokenize{installation:figure-visr-macos-installer-customize}]{\sphinxcrossref{\DUrole{std,std-ref}{“Installation type” screen of Mac OS X installer. Use “Customize” to get to the component selection.}}}})

\begin{figure}[htbp]
\centering
\capstart

\noindent\sphinxincludegraphics[scale=0.5]{{visr_macos_installer_customize}.png}
\caption{“Installation type” screen of Mac OS X installer. Use “Customize” to get to the component selection.}\label{\detokenize{installation:figure-visr-macos-installer-customize}}\label{\detokenize{installation:id5}}\end{figure}

To use the standalone applications from the command line, the \sphinxstylestrong{bin/} subfolder of the installation directory, e.g., \sphinxstylestrong{/Applications/VISR-X.X.X/bin}.
This can be done, for example, by adding

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n+nb}{export} \PYG{n+nv}{PATH}\PYG{o}{=}\PYG{n+nv}{\PYGZdl{}PATH}:/Applications/VISR\PYGZhy{}X.X.X/bin
\end{sphinxVerbatim}

to the file \sphinxstylestrong{\$HOME/.bash\_profile}.
However, this works only for running standalone applications from a shell (i.e., a terminal window).
If you need this path also from applications that are not started from a shell, we recommend the solution used in section {\hyperref[\detokenize{installation:installation-python-setup-configuration}]{\sphinxcrossref{\DUrole{std,std-ref}{Configuration}}}}.


\subsection{Linux}
\label{\detokenize{installation:linux}}
For Linux, installation packages are provided as \sphinxstyleemphasis{.deb} (Debian) packages.
At the moment, this package is monolithic, i.e., it contains all components.
They are installed via the command

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
sudo apt install VISR\PYGZhy{}\PYGZlt{}version\PYGZgt{}.deb
\end{sphinxVerbatim}

If this command reports missing dependencies, these can be installed subsequently with the command

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
sudo apt install \PYGZhy{}\PYGZhy{}fix\PYGZhy{}broken
\end{sphinxVerbatim}

After that the framework is ready to use.


\section{Installation components}
\label{\detokenize{installation:installation-component-description}}\label{\detokenize{installation:installation-components}}
With the dialog-based, component-enabled installers, parts of the framework can be chosen depending on the intended use of the framework.
\begin{description}
\item[{Shared Libraries}] \leavevmode
The core VISR libraries. This component is mandatory and cannot be unselected.

\item[{Standalone applications.}] \leavevmode
Renderers and small tools to be run as command-line applications.

\item[{Python externals}] \leavevmode
Python modules that give access to the functionality of the framework from Python.
Also needed to run applications that use Python internally (e.g., the binaural synthesis toolkit or metadapter-enabled rendering).

\item[{Python Packages}] \leavevmode
VISR extensions implemented in Python. This group of components requires the component “Python externals”.

\item[{Development files}] \leavevmode
Header files and CMake build support - Needed to extend the VISR with components using C++ or use the framework in external C++ applications.

\item[{Loudspeaker configurations}] \leavevmode
A set of standard loudspeaker configuration files and additional example files from actual locations.

\item[{Python templates}] \leavevmode
A set of commented template files for different types of VISR components.

\item[{Documentation}] \leavevmode
User and code reference documentation as PDF documents.
The Doxygen code documentation covering the complete source code can be optionally selected. However, the latter documentation is deprecated and will be contained in the code reference documentation in the future.

\end{description}


\section{Setting up Python}
\label{\detokenize{installation:setting-up-python}}
As explained in section {\hyperref[\detokenize{getting-started:overview-python-integration}]{\sphinxcrossref{\DUrole{std,std-ref}{Python integration}}}}, the Python integration is an optional, albeit central, part of the VISR framework that enables a number of its functionalities, for example:
\begin{itemize}
\item {} 
Using the framework interactively from a Python interpreter.

\item {} 
Using application that use Python internally, for instance the Binaural Synthesis Toolkit or metadata adaptation processes using the metadapter.

\item {} 
Creating new signal flows or algorithms in Python.

\end{itemize}

To use these functionalities, a Python 3 distribution must be installed on the computer, and some configuration steps are required.


\subsection{Python distribution}
\label{\detokenize{installation:python-distribution}}
Depending on the system, we suggest different Python distributions:


\subsubsection{Linux}
\label{\detokenize{installation:id1}}
Use the system-provided Python3 installation.

To install, use the package manager of your distribution, e.g.,

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
sudo apt install python3
\end{sphinxVerbatim}


\subsubsection{Windows and Mac OS X}
\label{\detokenize{installation:windows-and-mac-os-x}}
We recommend \sphinxhref{https://www.anaconda.com/download/}{Anaconda}. Please make sure you install the  Python3 / 64-Bit variant.

\begin{sphinxadmonition}{note}{Note:}
Some Mac OS variants (for example 10.12) come with a pre-installed Python 3 variant in \sphinxstylestrong{/Library/Frameworks/Python.framework}.
In this case, care must be taken that it does not interferes with the chosen Python distribution. In particular, the \sphinxstylestrong{PYTHONHOME} environment variable must be set correctly.
\end{sphinxadmonition}


\subsection{Configuration}
\label{\detokenize{installation:configuration}}\label{\detokenize{installation:installation-python-setup-configuration}}
Two environment variables must be set to ensure the working of the VISR Python subsystem.
\begin{itemize}
\item {} 
\sphinxstylestrong{PYTHONPATH} This variable is used to add the directory containing the VISR python modules to the system path.
To this end, the \sphinxstylestrong{python/} subdirectory of the installation folder must be added to \sphinxstylestrong{PYTHONPATH}.

Note that other ways exist to add to the system path, for example

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{sys}
\PYG{n}{sys}\PYG{o}{.}\PYG{n}{path}\PYG{o}{.}\PYG{n}{append}\PYG{p}{(} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{\PYGZlt{}visr\PYGZus{}installation\PYGZus{}dir\PYGZgt{}/python}\PYG{l+s+s1}{\PYGZsq{}} \PYG{p}{)}
\end{sphinxVerbatim}

However, we recommend setting \sphinxstylestrong{PYTHONPATH} and assume this in the examples throughout this document.

\end{itemize}
\begin{description}
\item[{PYTHOMHOME}] \leavevmode
This variable is needed to locate the files and libraries of the Python distribution.
This is especially important if there are more than one distributions on the system, most often on Mac OS X.
Strictly speaking, this variable is required only if VISR Python code is executed from a C++ application, for instance some DAW plugins, \sphinxstylestrong{python\_runner} standalone application (section ??), or the \sphinxstylestrong{visr\_renderer} with metadata processing enabled. (see section {\hyperref[\detokenize{using-standalone-renderers:using-visr-using-standalone-renderers-visr-renderer}]{\sphinxcrossref{\DUrole{std,std-ref}{VISR object-based loudspeaker renderer}}}}).

This variable has to be set to the root directory of the Python distribution, i.e.,
one level of hierarchy above the \sphinxstylestrong{bin/} folder conatining the Python interpreter.
Depending on the platform and the distribution, the correct value might be:
\begin{description}
\item[{Windows with Anaconda}] \leavevmode
\sphinxstylestrong{C:ProgramDataAnaconda3}

\item[{Mac OS X with Anaconda}] \leavevmode
\sphinxstylestrong{\$HOME/anaconda3/}

\item[{Linux}] \leavevmode
\sphinxstylestrong{/usr}

\end{description}

It is necessary to check whether these settings match with your directory layout.

If the Python distribution provides a \sphinxstylestrong{python-config} or \sphinxstylestrong{python3-config} binary, the command

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
python\PYGZhy{}config \PYGZhy{}\PYGZhy{}prefix
\end{sphinxVerbatim}

or

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
python3\PYGZhy{}config \PYGZhy{}\PYGZhy{}prefix
\end{sphinxVerbatim}

can be used to retrieve the required value for \sphinxstylestrong{PYTHONHOME}
On Linux, setting \sphinxstylestrong{PYTHONHOME} is not necessary in most cases, because there is only the system-provided Python installation available.

\end{description}

Depending on the operating system, these variables can be set as follows:
\begin{description}
\item[{OPENBLAS\_NUM\_THREADS}] \leavevmode
It is advisable, in many cases, to set the value of this environment variable to 1. It controls how \sphinxstylestrong{numpy} numerical algebra functions are distributed to multiple CPU cores.
\sphinxstylestrong{numpy} is used by the VISR Python integration as well as in many Python-based VISR components performing mathematical or DSP operations.
For the matrix/vector sizes typically encountered in our code, the overhead for distributing the work over multiple cores typically exceeds the potential gains.
Multithreading is disabled by setting the maximum number of cores (or threads) to 1:

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n+nv}{OPENBLAS\PYGZus{}NUM\PYGZus{}THREADS} \PYG{o}{=} \PYG{l+m}{1}
\end{sphinxVerbatim}

This setting is optional. However, if you encounter excessive loads, for example a constant 100\% load in the real-time thread, this setting can help to resolve the problem.

\item[{Linux}] \leavevmode
Append the lines
.. code-block:: bash
\begin{quote}

export PYTHONPATH=\$PYTHONPATH:/usr/share/visr/python
export OPENBLAS\_NUM\_THREADS=1
\end{quote}

to \sphinxstylestrong{\$HOME/.profile}.

\item[{Windows}] \leavevmode
Add \sphinxstylestrong{PYTHONPATH} entries either as a user or system variable as described in {\hyperref[\detokenize{installation:installation-windows}]{\sphinxcrossref{\DUrole{std,std-ref}{Windows}}}} section.
The corrects setting are (assuming the default installation directory and the Anaconda distribution):
\begin{quote}

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]

\end{sphinxVerbatim}

PYTHONPATH=c:Program FilesVISR-X.X.Xpython
PYTHONHOME=c:ProgramDataAnaconda3
OPENBLAS\_NUM\_THREADS=1
\end{quote}

Note that if there is already a \sphinxstylestrong{PYTHONPATH} variable, the recommended value should be appended, using a semicolon as a separator.

\item[{Mac OS X}] \leavevmode
In order to set the environment variables system-wide, without requiring that the applications in question is started from a shell, (e.g., a command-line terminal), we recommend a custom \sphinxstylestrong{launchd} property list file, as detailed, e.g., in this \sphinxhref{https://apple.stackexchange.com/questions/106355/setting-the-system-wide-path-environment-variable-in-mavericks}{StackExchange thread}.

To this end, create a \sphinxstylestrong{VISR-X.X.X.plist} file with this contents

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZlt{}?xml version=\PYGZdq{}1.0\PYGZdq{} encoding=\PYGZdq{}UTF\PYGZhy{}8\PYGZdq{}?\PYGZgt{}}
\PYG{c+cp}{\PYGZlt{}!DOCTYPE plist PUBLIC \PYGZdq{}\PYGZhy{}//Apple//DTD PLIST 1.0//EN\PYGZdq{} \PYGZdq{}http://www.apple.com/DTDs/PropertyList\PYGZhy{}1.0.dtd\PYGZdq{}\PYGZgt{}}
\PYG{n+nt}{\PYGZlt{}plist} \PYG{n+na}{version=}\PYG{l+s}{\PYGZdq{}1.0\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
\PYG{n+nt}{\PYGZlt{}dict}\PYG{n+nt}{\PYGZgt{}}
 \PYG{n+nt}{\PYGZlt{}key}\PYG{n+nt}{\PYGZgt{}}Label\PYG{n+nt}{\PYGZlt{}/key\PYGZgt{}}
 \PYG{n+nt}{\PYGZlt{}string}\PYG{n+nt}{\PYGZgt{}}my.startup\PYG{n+nt}{\PYGZlt{}/string\PYGZgt{}}
 \PYG{n+nt}{\PYGZlt{}key}\PYG{n+nt}{\PYGZgt{}}ProgramArguments\PYG{n+nt}{\PYGZlt{}/key\PYGZgt{}}
 \PYG{n+nt}{\PYGZlt{}array}\PYG{n+nt}{\PYGZgt{}}
   \PYG{n+nt}{\PYGZlt{}string}\PYG{n+nt}{\PYGZgt{}}sh\PYG{n+nt}{\PYGZlt{}/string\PYGZgt{}}
   \PYG{n+nt}{\PYGZlt{}string}\PYG{n+nt}{\PYGZgt{}}\PYGZhy{}c\PYG{n+nt}{\PYGZlt{}/string\PYGZgt{}}
   \PYG{n+nt}{\PYGZlt{}string}\PYG{n+nt}{\PYGZgt{}}
   launchctl setenv PYTHONPATH /Applications/VISR\PYGZhy{}X.X.X/python
   launchctl setenv OPENBLAS\PYGZus{}NUM\PYGZus{}THREADS 1
   launchctl setenv PYTHONHOME \PYGZdl{}\PYGZob{}HOME\PYGZcb{}/anaconda3
   \PYG{n+nt}{\PYGZlt{}/string\PYGZgt{}}
 \PYG{n+nt}{\PYGZlt{}/array\PYGZgt{}}
 \PYG{n+nt}{\PYGZlt{}key}\PYG{n+nt}{\PYGZgt{}}RunAtLoad\PYG{n+nt}{\PYGZlt{}/key\PYGZgt{}}
 \PYG{n+nt}{\PYGZlt{}true}\PYG{n+nt}{/\PYGZgt{}}
\PYG{n+nt}{\PYGZlt{}/dict\PYGZgt{}}
\PYG{n+nt}{\PYGZlt{}/plist\PYGZgt{}}
\end{sphinxVerbatim}

By convention, these files are stored in \sphinxstylestrong{/Users/\textless{}loginname\textgreater{}/Library/LaunchAgents/}.
To activate the settings, call

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
launchctl load \PYGZlt{}path\PYGZhy{}to\PYGZhy{}file\PYGZgt{}/VISR\PYGZhy{}X.X.X.plist
\end{sphinxVerbatim}

To take effect, all applications using these settings (e.g., terminals, Python interpreters, DAWs) must be quit and reopened.

These settings are preserved if the machine is restarted.
To deactivate them, the property list file must be unloaded:
\begin{quote}

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
launchctl unload \PYGZlt{}path\PYGZhy{}to\PYGZhy{}file\PYGZgt{}/VISR\PYGZhy{}X.X.X.plist
\end{sphinxVerbatim}
\end{quote}

If you made changes to the settings, you have to perform the \sphinxstylestrong{unload} command followed by a \sphinxstylestrong{load}.

For convenience, the installers create a pre-configured \sphinxstylestrong{VISR-X.X.X.plist} file in the \sphinxstylestrong{etc} subdirectory of the installation directory (e.g., \sphinxstylestrong{/Applications/VISR-X.X.X/etc/VISR-X.X.X.plist} ).
This file can be either loaded directly or copied to the \sphinxstylestrong{LaunchAgents/} directory first. Please check the values in this file first and adjust them accordingly.

\end{description}


\section{Verifying the installation}
\label{\detokenize{installation:verifying-the-installation}}
We suggest some basic tests to verify that the VISR framework has been correctly installed and configured.


\subsection{Testing a standalone application}
\label{\detokenize{installation:testing-a-standalone-application}}
This test is to ensure that that the installation is successful, and that the VISR shared libraries can be located and are compatible with the system.
When using the component-enabled installers, the component \sphinxcode{Standalone applications} must have been selected in order to perform this check.

In a terminal (Linux shell, Mac OS Terminal application, Windows command line \sphinxstylestrong{cmd}),
execute this command:

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYGZlt{}visr\PYGZhy{}installation\PYGZhy{}dir\PYGZgt{}/bin/matrix\PYGZus{}convolver \PYGZhy{}\PYGZhy{}version
\end{sphinxVerbatim}

For the different platforms, the full commands are (assuming the default installation directory)
Windows
\begin{quote}

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
  \PYG{l+s+s2}{\PYGZdq{}c:\PYGZbs{}Program Files\PYGZbs{}VISR\PYGZhy{}X.X.X\PYGZbs{}bin\PYGZbs{}matrix\PYGZus{}convolver.exe\PYGZdq{}} \PYGZhy{}\PYGZhy{}version

Note that the quotes are necessary to cope with the space in the path.
\end{sphinxVerbatim}
\end{quote}

Mac OS X
\begin{quote}

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
/Applications/VISR\PYGZhy{}X.X.X/bin/matrix\PYGZus{}convolver \PYGZhy{}\PYGZhy{}version
\end{sphinxVerbatim}
\end{quote}

Linux
\begin{quote}

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
/usr/bin/matrix\PYGZus{}convolver \PYGZhy{}\PYGZhy{}version
\end{sphinxVerbatim}
\end{quote}

If you added the \sphinxstylestrong{bin/} directory as described above, calling
\begin{quote}

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
matrix\PYGZus{}convolver \PYGZhy{}\PYGZhy{}version
\end{sphinxVerbatim}
\end{quote}

is sufficient.

In any case, the call should generate a statement like
\begin{quote}

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
VISR Matrix convolver utility  \PYG{l+m}{0}.10.0
\end{sphinxVerbatim}
\end{quote}

If there is an error message about a missing shared library (or DLL), you should consult the respective section about installation.
In particular this applies Windows, where the \sphinxstylestrong{PATH} variable needs to be set accordingly.


\subsubsection{Testing the interactive Python integration}
\label{\detokenize{installation:testing-the-interactive-python-integration}}
This test ensures that the VISR framework can be used interactively from Python interpreters.

First start a Python 3 interpreter (for example \sphinxstylestrong{python} or \sphinxstylestrong{ipython}).
Depending on the system, the binaries might be called \sphinxstylestrong{python3} or \sphinxstylestrong{ipython3}, respectively
It must be the interpreter of the Python distribution you intend to use (e.g., Anaconda).

In the interpreter, try to import the \sphinxstylestrong{visr} modules
\begin{quote}

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{visr}
\end{sphinxVerbatim}
\end{quote}

This command should return without an error message.
In this case, you can check whether the module is loaded from the correct location:
\begin{quote}

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n+nb}{getattr}\PYG{p}{(} \PYG{n}{visr}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{\PYGZus{}\PYGZus{}file\PYGZus{}\PYGZus{}}\PYG{l+s+s1}{\PYGZsq{}} \PYG{p}{)}
\end{sphinxVerbatim}
\end{quote}

The directory of the resulting file path should be \sphinxstylestrong{\textless{}visr-installation-dir\textgreater{}/python}.
For example, on Windows this returns \sphinxstylestrong{C:Program FilesVISR 0.10.0\textbackslash{}python\textbackslash{}visr.pyd}.


\section{Source Code}
\label{\detokenize{sourcecode::doc}}\label{\detokenize{sourcecode:index-0}}\label{\detokenize{sourcecode:source-code}}
Alternatively, the VISR framework can be installed and build from source code.
It is hosted at the GitLab repository \sphinxurl{https://gitlab.eps.surrey.ac.uk:s3a/VISR.git}

To retrieve the source code, clone the repository with

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
git clone https://gitlab.eps.surrey.ac.uk:s3a/VISR.git
\end{sphinxVerbatim}

Setting up a build environment, including the required software tools, and compiling the source code is detailed in the \sphinxhref{http://s3a-spatialaudio.org}{VISR API documentation}.


\section{Support and help}
\label{\detokenize{support::doc}}\label{\detokenize{support:index-0}}\label{\detokenize{support:support-and-help}}\label{\detokenize{support:support}}
Sopport for installing and using the VISR is available through several ways.

First, you should check the FAQ section of the website (TODO: Insert link here)

Second, the mailing list (insert link to the registration page of the 3a-software list here).

Third, problems and supected bugs can be reported on (insert link to issues page of GitLab repository / later GitHub repo).


\chapter{VISR principles}
\label{\detokenize{index:visr-principles}}

\section{Component-Based Audio processing}
\label{\detokenize{index:component-based-audio-processing}}

\section{VISR as a Rendering Framework}
\label{\detokenize{index:visr-as-a-rendering-framework}}

\section{Realtime and Offline Processing}
\label{\detokenize{index:realtime-and-offline-processing}}

\section{Prototyping versus mature signal processing code}
\label{\detokenize{index:prototyping-versus-mature-signal-processing-code}}

\chapter{Using VISR}
\label{\detokenize{index:using-visr}}

\section{Using VISR standalone renderers}
\label{\detokenize{index:using-visr-standalone-renderers}}

\subsection{Using standalone applications}
\label{\detokenize{using-standalone-renderers::doc}}\label{\detokenize{using-standalone-renderers:using-visr-using-standalone-renderers}}\label{\detokenize{using-standalone-renderers:using-standalone-applications}}
The VISR framework provides a number of standalone real-time rendering applications for some of its audio processing functionality.

If a component-aware installer is used (see Section {\hyperref[\detokenize{installation:installation-component-description}]{\sphinxcrossref{\DUrole{std,std-ref}{Installation components}}}}), then the component “Standalone applications” has to be selected during installation.

The standalone applications are started as command line applications, and configured through a number of command line options or a configuration file.


\subsubsection{Common options}
\label{\detokenize{using-standalone-renderers:common-options}}\label{\detokenize{using-standalone-renderers:using-standalone-renderers-common-options}}
All standalone applications provided with the VISR provide a common set of command line options:
\begin{description}
\item[{\sphinxstylestrong{\textendash{}version} or \sphinxstylestrong{-v}}] \leavevmode
Returns a short description of the tool and its version information.

\item[{\sphinxstylestrong{\textendash{}help} or \sphinxstylestrong{-h}}] \leavevmode
Returns a list of supported command line options with brief descriptions.

\item[{\sphinxstylestrong{\textendash{}option-file \textless{}filename\textgreater{}} or \sphinxstylestrong{@\textless{}filename\textgreater{}}}] \leavevmode
Pass a configuration file containing a set of command line options to the applications.
This options allows to store and share complex sets of command line options, and to overcome potential command line length limitations.

A typical option file has the format

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYGZhy{}i \PYG{l+m}{2}
\PYGZhy{}o \PYG{l+m}{2}
\PYGZhy{}f \PYG{l+m}{48000}
\PYGZhy{}c \PYG{l+s+s2}{\PYGZdq{}/usr/share/visr/config/generic/stereo.xml\PYGZdq{}}
\end{sphinxVerbatim}

where,by convention, one option is stored per line.

\item[{\sphinxstylestrong{\textendash{}sampling-frequency} or \sphinxstylestrong{-f}}] \leavevmode
The sampling frequency to be used for rendering, as an integer value in Hz.
Typically optional. If not given, a default value (e.g., 48000 Hz) will be used.

\item[{\sphinxstylestrong{\textendash{}period} or \sphinxstylestrong{-p}}] \leavevmode
The period, or blocksize, or buffersize to be used by the audio interface.

In most cases, the period should be a power of 2, e.g., 64, 128, 256, 512, …, 4096.
Lower values mean lower audio latency, but typically higher system load and higher susceptibility to audio underruns.

Typically an optional argument. If not given, a default value (e.g., 1024) is used.

\item[{\sphinxstylestrong{\textendash{}audio-backend} or \sphinxstylestrong{-D}}] \leavevmode
Specify the audio interface library to be used.

This option is mandatory.

The audio interfaces depend on the operating system and the configuration of the user’s system. The most common options are \sphinxstylestrong{“PortAudio”} (all platforms) and \sphinxstylestrong{“Jack”} (Linux and Mac OS X). Note that additional libraries (or backends) can be available for a specific platform, and new backends might be added in the future.

\item[{\sphinxstylestrong{-audio-ifc-options}}] \leavevmode
A string to provide additional options to the audio interface.

This is an optional argument, and its content is interface-specific.

By convention, the existing audio interfaces expect JSON (\sphinxhref{https://www.json.org/}{JavaScript Object Notation}) strings for the backend-configuration.

To pass JSON strings, the whole string should be enclosed in single or double quotes, and the quotes required by JSON must be escaped with a backslash. For example, the option might be used in this way:

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
visr\PYGZus{}renderer ... \PYGZhy{}audio\PYGZhy{}ifc\PYGZhy{}options\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}\PYGZob{} \PYGZbs{}\PYGZdq{}hostapi\PYGZbs{}\PYGZdq{}: \PYGZbs{}\PYGZdq{}WASAPI\PYGZbs{}\PYGZdq{} \PYGZcb{}\PYGZsq{}}
\end{sphinxVerbatim}

Section {\hyperref[\detokenize{using-standalone-renderers:using-visr-using-standalone-renderers-specific-audio-options}]{\sphinxcrossref{\DUrole{std,std-ref}{Interface-specific audio options}}}} below explains the options for the currently supported audio interfaces.

\item[{\sphinxstylestrong{-audio-ifc-option-file}}] \leavevmode
Provide a interface-specific option string within a file.

This can be used to avoid re-specifying complex options strings, to author them in a structured way, and to store and share them.

In addition, it avoids the quoting and escaping tricks needed on the command line.
For example, the option shown above could be specified in a file \sphinxstylestrong{portaudio\_options.cfg} as

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{p}{\PYGZob{}}
  \PYG{n+nt}{\PYGZdq{}hostapi\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}WASAPI\PYGZdq{}}
\PYG{p}{\PYGZcb{}}
\end{sphinxVerbatim}

and passed as

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
visr\PYGZus{}renderer ... \PYGZhy{}audio\PYGZhy{}ifc\PYGZhy{}option\PYGZhy{}file\PYG{o}{=}portaudio\PYGZus{}options.cfg
\end{sphinxVerbatim}

\end{description}

\begin{sphinxadmonition}{note}{Note:}
The options \sphinxstylestrong{\textendash{}audio-ifc-options} and \sphinxstylestrong{\textendash{}audio-ifc-option-file} are mutually
exclusive, that means other none or one of them can be provided.
\end{sphinxadmonition}


\subsubsection{VISR object-based loudspeaker renderer}
\label{\detokenize{using-standalone-renderers:visr-object-based-loudspeaker-renderer}}\label{\detokenize{using-standalone-renderers:using-visr-using-standalone-renderers-visr-renderer}}
These renderers facilitate object-based rendering to arbitrary loudspeaker setups.
They use the VISR audio object model and the corresponding JSON format described in Section {\hyperref[\detokenize{index:id1}]{\sphinxcrossref{\DUrole{std,std-ref}{Predefined object-based rendering primitives and renderers}}}}.

Note that there are two binaries for loudspeaker rendering: \sphinxstylestrong{visr\_renderer} and \sphinxstylestrong{baseline\_renderer}.
The provision of these separate binaries has technical reasons - mainly their dependency on a compatible and configured Python installation, as explained below.

The two binaries provided are:
\begin{description}
\item[{\sphinxstyleemphasis{visr\_renderer}}] \leavevmode
This is the full object-based renderer, including a powerful metadata adaptation engine for intelligent object-based rendering - the Metadapter - implemented in Python.
This metadapter is integrated into the rendering binary as an optional part, and is used if the option \sphinxstylestrong{\textendash{}metadapter-config} is specified.
The binary itself, however, needs a Python istallation to start at all, irrespective whether this option is set.

\item[{\sphinxstyleemphasis{baseline\_renderer}}] \leavevmode
This is the legacy object-based loudspeaker renderer. At the time being, it provides the same functionality as the \sphinxstylestrong{visr\_renderer},
but without the optional integrated metadapter component.
In this way, the binary is independent of a Python distribution on the user’s computer.

\end{description}

In general, we recommend to use \sphinxstylestrong{visr\_renderer} if possible, and to use \sphinxstylestrong{baseline\_renderer} on systems where the Python features
of the VISR framework are not available.

The command line arguments supported by the \sphinxstylestrong{visr\_renderer} application are:

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYGZdl{}\PYGZgt{} visr\PYGZus{}renderer.exe \PYGZhy{}\PYGZhy{}help
\PYGZhy{}h \PYG{o}{[} \PYGZhy{}\PYGZhy{}help \PYG{o}{]}                   Show \PYG{n+nb}{help} and usage information.
\PYGZhy{}v \PYG{o}{[} \PYGZhy{}\PYGZhy{}version \PYG{o}{]}                Display version information.
\PYGZhy{}\PYGZhy{}option\PYGZhy{}file arg               Load options from a file. Can also be used
                                with syntax \PYG{l+s+s2}{\PYGZdq{}@\PYGZlt{}filename\PYGZgt{}\PYGZdq{}}.
\PYGZhy{}D \PYG{o}{[} \PYGZhy{}\PYGZhy{}audio\PYGZhy{}backend \PYG{o}{]} arg      The audio backend.
\PYGZhy{}f \PYG{o}{[} \PYGZhy{}\PYGZhy{}sampling\PYGZhy{}frequency \PYG{o}{]} arg Sampling frequency \PYG{o}{[}Hz\PYG{o}{]}
\PYGZhy{}p \PYG{o}{[} \PYGZhy{}\PYGZhy{}period \PYG{o}{]} arg             Period \PYG{o}{(}blocklength\PYG{o}{)} \PYG{o}{[}Number of samples per
                                audio block\PYG{o}{]}
\PYGZhy{}c \PYG{o}{[} \PYGZhy{}\PYGZhy{}array\PYGZhy{}config \PYG{o}{]} arg       Loudspeaker array configuration file
\PYGZhy{}i \PYG{o}{[} \PYGZhy{}\PYGZhy{}input\PYGZhy{}channels \PYG{o}{]} arg     Number of input channels \PYG{k}{for} audio object
                                signal
\PYGZhy{}o \PYG{o}{[} \PYGZhy{}\PYGZhy{}output\PYGZhy{}channels \PYG{o}{]} arg    Number of audio output channels
\PYGZhy{}e \PYG{o}{[} \PYGZhy{}\PYGZhy{}object\PYGZhy{}eq\PYGZhy{}sections \PYG{o}{]} arg Number of eq \PYG{o}{(}biquad\PYG{o}{)} section processed \PYG{k}{for}
                                each object signal.
\PYGZhy{}\PYGZhy{}reverb\PYGZhy{}config arg             JSON string to configure the object\PYGZhy{}based
                                reverberation part, empty string \PYG{o}{(}default\PYG{o}{)} to
                                disable reverb.
\PYGZhy{}\PYGZhy{}tracking arg                  Enable adaptation of the panning using visual
                                tracking. Accepts the position of the tracker
                                in JSON format\PYG{l+s+s2}{\PYGZdq{}\PYGZob{} \PYGZdq{}}port\PYG{l+s+s2}{\PYGZdq{}: \PYGZlt{}UDP port number\PYGZgt{},}
\PYG{l+s+s2}{                                \PYGZdq{}}position\PYG{l+s+s2}{\PYGZdq{}: \PYGZob{}\PYGZdq{}}x\PYG{l+s+s2}{\PYGZdq{}: \PYGZlt{}x in m\PYGZgt{}, \PYGZdq{}}y\PYG{l+s+s2}{\PYGZdq{}: \PYGZlt{}y im m\PYGZgt{},}
\PYG{l+s+s2}{                                \PYGZdq{}}z\PYG{l+s+s2}{\PYGZdq{}: \PYGZlt{}z in m\PYGZgt{} \PYGZcb{}, \PYGZdq{}}rotation\PYG{l+s+s2}{\PYGZdq{}: \PYGZob{} \PYGZdq{}}rotX\PYG{l+s+s2}{\PYGZdq{}: rX,}
\PYG{l+s+s2}{                                \PYGZdq{}}rotY\PYG{l+s+s2}{\PYGZdq{}: rY, \PYGZdq{}}rotZ\PYG{l+s+s2}{\PYGZdq{}: rZ \PYGZcb{} \PYGZcb{}\PYGZdq{}} .
\PYGZhy{}r \PYG{o}{[} \PYGZhy{}\PYGZhy{}scene\PYGZhy{}port \PYG{o}{]} arg         UDP port \PYG{k}{for} receiving object metadata
\PYGZhy{}m \PYG{o}{[} \PYGZhy{}\PYGZhy{}metadapter\PYGZhy{}config \PYG{o}{]} arg  Metadapter configuration file. Requires a
                                build with Python support. If empty, no
                                metadata adaptation is performed.
\PYGZhy{}\PYGZhy{}low\PYGZhy{}frequency\PYGZhy{}panning         Activates frequency\PYGZhy{}dependent panning gains
                                and normalisation
\PYGZhy{}\PYGZhy{}audio\PYGZhy{}ifc\PYGZhy{}options arg         Audio interface optional configuration
\PYGZhy{}\PYGZhy{}audio\PYGZhy{}ifc\PYGZhy{}option\PYGZhy{}file arg     Audio interface optional configuration file
\end{sphinxVerbatim}

The arguments for the \sphinxstylestrong{baseline\_renderer} application are identical, except that the \sphinxcode{-{-}metadapter-config} option is not supported as explained above.
\begin{description}
\item[{\sphinxcode{-{-}audio-backend} or \sphinxcode{-D}}] \leavevmode
The audio interface library to be used. See section :ref:using\_standalone\_renderers\_common\_options.

\item[{\sphinxcode{-{-}audio-ifc-options}:}] \leavevmode
Audio-interface specific options, section :ref:using\_standalone\_renderers\_common\_options.

\item[{\sphinxcode{-{-}audio-ifc-option-file}:}] \leavevmode
Audio-interface specific options, section :ref:using\_standalone\_renderers\_common\_options.

\item[{\sphinxcode{-{-}sampling-frequency} or \sphinxcode{-f}:}] \leavevmode
Sampling frequency in Hz. Default: 48000 Hz. See section :ref:using\_standalone\_renderers\_common\_options.

\item[{\sphinxcode{-{-}period} or \sphinxcode{-p}:}] \leavevmode
The number of samples processed in one iteration of the renderer. Should be a power of 2 (64,128,…,4096,…) . Default: 1024 samples. See section :ref:using\_standalone\_renderers\_common\_options.

\item[{\sphinxcode{-{-}array-config} or \sphinxcode{-c}:}] \leavevmode
File path to the loudspeaker configuration file. Path might be relative to the current working directory. Mandatory argument.
The XML file format is described below in Section {\hyperref[\detokenize{using-standalone-renderers:loudspeaker-configuration-file-format}]{\sphinxcrossref{\DUrole{std,std-ref}{Loudspeaker configuration file format}}}}.

\item[{\sphinxcode{-{-}input-channels} or \sphinxcode{-i}:}] \leavevmode
The number of audio input channels. This corresponds to the number of single-waveform objects the renderer will process. Mandatory argument. A (case-insensitive) file extension of c .xml triggers the use of the XML format for parsing.

\item[{\sphinxcode{-{-}output-channels} or \sphinxcode{-o}:}] \leavevmode
The number of output channels the renderer will put write to. If not given, the number of output channels is determined from the largest logical channel number in the array configuration.

\item[{\sphinxcode{-{-}object-eq-sections}:}] \leavevmode
The number of EQs (biquad sections) that can be specified for each object audio signal.

Default value: o, which deactivate EQ filtering for objects.

\item[{\sphinxcode{-{-}low-frequency-panning}:}] \leavevmode
Switches the loudspeaker panning between standard VBAP and a dual-frequency approach with separate low- and high-frequency panning rules.

Admissible values are \sphinxcode{true} and \sphinxcode{false}. The default value is \sphinxcode{false}, corresponding
to the standard VBAP algorithm.

\item[{\sphinxcode{-{-}reverb-config}:}] \leavevmode
A set of options for the integrated reverberation engine for the RSAO (\sphinxcode{PointsourceWithReverb}) object (see section {\hyperref[\detokenize{index:visr-object-based-audio-reverberation}]{\sphinxcrossref{\DUrole{std,std-ref}{Object-Based Reverberation}}}}).
To be passed as a JSON string. The supported options are:
\begin{description}
\item[{\sphinxcode{numReverbObjects}:}] \leavevmode
The number of RSAO objects that can be rendered simultaneously.
These objects may have arbitrary object ids, and they are automatically allocated to the computational resources avalable.

To be provided as a nonnegative integer number The default value is 0, which means that the reverberation rendering is effectively disabled.

\item[{\sphinxcode{lateReverbFilterLength}:}] \leavevmode
Specify the length of the late reverberation filters, in seconds.

Provided as a floating-point value, in seconds. Default value is zero, which results in the shortest reverb filter length that can be processed by the renderer, typically one sample.

\item[{\sphinxcode{lateReverbDecorrelationFilters}:}] \leavevmode
Specifies a multichannel WAV file containing a set of decorrelation filters, one per loudspeaker output. The number of channels must be equal or greater than the number of loudspeakers, channels that exceed the number of loudspeakers are not used.

To be provided as a full file path. The default value is empty, which means that zero-valued filters are used, which effectively disables the late reverb.

\item[{\sphinxcode{discreteReflectionsPerObject}:}] \leavevmode
The maximum number of discrete reflections that can be rendered for a single RSAO object.

Given as a nonnegative integer number. The default value is 0, which means that no discrete reflections are supported.

\item[{\sphinxcode{maxDiscreteReflectionDelay}:}] \leavevmode
The maximum discrete reflection delay supported. This allows a for tradeoff between the computational resources, i.e., memory required by the renderer and a realistic upper limit for discrete reflection delays.

To be provided as a floating-point number in seconds. Default value is 1.0, i.e., one second.

\item[{\sphinxcode{lateReverbFilterUpdatesPerPeriod}}] \leavevmode
Optional argument for limiting the number of filter updates in realtime rendering.
This is to avoid processing load peaks, which might lead to audio underruns, if multiple RSAO objects are changed simultaneously.
The argument specifies the maximum number of objects for whom the late reverb filter is calculated withon one period (audio buffer). If there are more pending changes than thix number, the updates are spread over multiple periods.
This is a tradeoff between peak load and the timing accuracy and synchronity of late reverb updates.

Optional value, default value is 1, meaning at most one update per period

\end{description}

An example configuration is:

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZhy{}}\PYG{n}{reverb}\PYG{o}{\PYGZhy{}}\PYG{n}{config}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{\PYGZob{}}\PYG{l+s+s1}{ }\PYG{l+s+se}{\PYGZbs{}\PYGZdq{}}\PYG{l+s+s1}{numReverbObjects}\PYG{l+s+se}{\PYGZbs{}\PYGZdq{}}\PYG{l+s+s1}{: 5, }\PYG{l+s+se}{\PYGZbs{}\PYGZdq{}}\PYG{l+s+s1}{lateReverbFilterLength}\PYG{l+s+se}{\PYGZbs{}\PYGZdq{}}\PYG{l+s+s1}{: 4.0,}
           \PYGZbs{}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{lateReverbDecorrelationFilters}\PYG{l+s+se}{\PYGZbs{}\PYGZdq{}}\PYG{l+s+s2}{: }\PYG{l+s+s2}{\PYGZdq{}}\PYG{o}{/}\PYG{n}{home}\PYG{o}{/}\PYG{n}{af5u13}\PYG{o}{/}\PYG{n}{tmp}\PYG{o}{/}\PYG{n}{decorr}\PYG{o}{.}\PYG{n}{wav}\PYGZbs{}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{,}
           \PYGZbs{}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{discreteReflectionsPerObject}\PYG{l+s+se}{\PYGZbs{}\PYGZdq{}}\PYG{l+s+s2}{: 10 \PYGZcb{}}\PYG{l+s+s2}{\PYGZsq{}}
\end{sphinxVerbatim}

\item[{\sphinxcode{-{-}tracking}}] \leavevmode
Activates the listener-tracked VBAP reproduction, which adjust both the VBAP gains as well as the final loudspeaker gains and delays according to the listener position. It takes a non-empty string argument containing a JSON message of the format: \sphinxcode{\{ "port": \&lt;UDP port number\&gt;, "position": \{"x": \&lt;x in m\&gt;, "y": \&lt;y im m\&gt;, "z": \&lt;z in m\&gt; \}, "rotation": \{ "rotX": rX, "rotY": rY, "rotZ": rZ \} \}"}. The values are defined as follows:


\begin{savenotes}\sphinxattablestart
\centering
\begin{tabulary}{\linewidth}[t]{|T|T|T|T|}
\hline
\sphinxstylethead{\sphinxstyletheadfamily 
ID
\unskip}\relax &\sphinxstylethead{\sphinxstyletheadfamily 
Description
\unskip}\relax &\sphinxstylethead{\sphinxstyletheadfamily 
Unit
\unskip}\relax &\sphinxstylethead{\sphinxstyletheadfamily 
Default
\unskip}\relax \\
\hline
port
&
UDP port number
&
unsigned int
&
8888
\\
\hline
position.x
&
x position of the tracker
&
m
&
2.08
\\
\hline
position.y
&
y position of the tracker
&
m
&
0.0
\\
\hline
position.z
&
z position of the tracker
&
m
&
0.0
\\
\hline
rotation.rotX
&
rotation the tracker about the x axis, i.e., y-z plane
&
degree
&
0.0
\\
\hline
rotation.rotY
&
rotation the tracker about the y axis, i.e., z-x plane
&
degree
&
0.0
\\
\hline
rotation.rotZ
&
rotation the tracker about the z axis, i.e., x-y plane
&
degree
&
180
\\
\hline
\end{tabulary}
\par
\sphinxattableend\end{savenotes}

\end{description}

\begin{sphinxadmonition}{note}{Note:}
The option parsing for \sphinxcode{-{-}tracking} not supported yet, default values are used invariably. To activate tracking, you need to specify the  \sphinxcode{-{-}tracking} option with an arbitrary parameter (even  \sphinxcode{-{-}tracking=false} would activate the tracking.
\end{sphinxadmonition}
\begin{description}
\item[{\sphinxcode{-{-}scene-port}}] \leavevmode
The UDP network port which receives the scene data in the VISR JSON object format.

\item[{\sphinxcode{-{-}metadapter-config}}] \leavevmode
An optional Metadapter configuration file in XML format, provided as a full path to the file. If specified, the received metadata are passed through a sequence of metadata adaptation steps that are specified in the configuration file. If not given., metadata adaptation is not performed, and objects are directly passed to the audio renderer.

This option is not supported by the \sphinxstylestrong{baseline\_renderer} application.

\end{description}


\paragraph{Loudspeaker configuration file format}
\label{\detokenize{using-standalone-renderers:loudspeaker-configuration-file-format}}\label{\detokenize{using-standalone-renderers:id1}}
The loudspeaker configuration has to be specified in an XML file.
It is used primarily for the loudspeaker renderers.

An example is given below.

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\PYGZlt{}panningConfiguration}\PYG{n+nt}{\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}loudspeaker} \PYG{n+na}{id=}\PYG{l+s}{\PYGZdq{}M+000\PYGZdq{}} \PYG{n+na}{channel=}\PYG{l+s}{\PYGZdq{}1\PYGZdq{}} \PYG{n+na}{eq=}\PYG{l+s}{\PYGZdq{}highpass\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
    \PYG{n+nt}{\PYGZlt{}cart} \PYG{n+na}{x=}\PYG{l+s}{\PYGZdq{}1.0\PYGZdq{}} \PYG{n+na}{y=}\PYG{l+s}{\PYGZdq{}0.0\PYGZdq{}} \PYG{n+na}{z=}\PYG{l+s}{\PYGZdq{}0\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}/loudspeaker\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}loudspeaker} \PYG{n+na}{id=}\PYG{l+s}{\PYGZdq{}M\PYGZhy{}030\PYGZdq{}} \PYG{n+na}{channel=}\PYG{l+s}{\PYGZdq{}2\PYGZdq{}} \PYG{n+na}{eq=}\PYG{l+s}{\PYGZdq{}highpass\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
    \PYG{n+nt}{\PYGZlt{}polar} \PYG{n+na}{az=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}30.0\PYGZdq{}} \PYG{n+na}{el=}\PYG{l+s}{\PYGZdq{}0.0\PYGZdq{}} \PYG{n+na}{r=}\PYG{l+s}{\PYGZdq{}1.0\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}/loudspeaker\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}loudspeaker} \PYG{n+na}{id=}\PYG{l+s}{\PYGZdq{}M+030\PYGZdq{}} \PYG{n+na}{channel=}\PYG{l+s}{\PYGZdq{}3\PYGZdq{}} \PYG{n+na}{eq=}\PYG{l+s}{\PYGZdq{}highpass\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
    \PYG{n+nt}{\PYGZlt{}polar} \PYG{n+na}{az=}\PYG{l+s}{\PYGZdq{}30.0\PYGZdq{}} \PYG{n+na}{el=}\PYG{l+s}{\PYGZdq{}0.0\PYGZdq{}} \PYG{n+na}{r=}\PYG{l+s}{\PYGZdq{}1.0\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}/loudspeaker\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}loudspeaker} \PYG{n+na}{id=}\PYG{l+s}{\PYGZdq{}M\PYGZhy{}110\PYGZdq{}} \PYG{n+na}{channel=}\PYG{l+s}{\PYGZdq{}4\PYGZdq{}} \PYG{n+na}{eq=}\PYG{l+s}{\PYGZdq{}highpass\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
    \PYG{n+nt}{\PYGZlt{}polar} \PYG{n+na}{az=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}110.0\PYGZdq{}} \PYG{n+na}{el=}\PYG{l+s}{\PYGZdq{}0.0\PYGZdq{}} \PYG{n+na}{r=}\PYG{l+s}{\PYGZdq{}1.0\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}/loudspeaker\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}loudspeaker} \PYG{n+na}{id=}\PYG{l+s}{\PYGZdq{}M+110\PYGZdq{}} \PYG{n+na}{channel=}\PYG{l+s}{\PYGZdq{}5\PYGZdq{}} \PYG{n+na}{eq=}\PYG{l+s}{\PYGZdq{}highpass\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
    \PYG{n+nt}{\PYGZlt{}polar} \PYG{n+na}{az=}\PYG{l+s}{\PYGZdq{}110.0\PYGZdq{}} \PYG{n+na}{el=}\PYG{l+s}{\PYGZdq{}0.0\PYGZdq{}} \PYG{n+na}{r=}\PYG{l+s}{\PYGZdq{}1.0\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}/loudspeaker\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}loudspeaker} \PYG{n+na}{id=}\PYG{l+s}{\PYGZdq{}U\PYGZhy{}030\PYGZdq{}} \PYG{n+na}{channel=}\PYG{l+s}{\PYGZdq{}6\PYGZdq{}} \PYG{n+na}{eq=}\PYG{l+s}{\PYGZdq{}highpass\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
    \PYG{n+nt}{\PYGZlt{}polar} \PYG{n+na}{az=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}30.0\PYGZdq{}} \PYG{n+na}{el=}\PYG{l+s}{\PYGZdq{}30.0\PYGZdq{}} \PYG{n+na}{r=}\PYG{l+s}{\PYGZdq{}1.0\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}/loudspeaker\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}loudspeaker} \PYG{n+na}{id=}\PYG{l+s}{\PYGZdq{}U+030\PYGZdq{}} \PYG{n+na}{channel=}\PYG{l+s}{\PYGZdq{}7\PYGZdq{}} \PYG{n+na}{eq=}\PYG{l+s}{\PYGZdq{}highpass\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
    \PYG{n+nt}{\PYGZlt{}polar} \PYG{n+na}{az=}\PYG{l+s}{\PYGZdq{}30.0\PYGZdq{}} \PYG{n+na}{el=}\PYG{l+s}{\PYGZdq{}30.0\PYGZdq{}} \PYG{n+na}{r=}\PYG{l+s}{\PYGZdq{}1.0\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}/loudspeaker\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}loudspeaker} \PYG{n+na}{id=}\PYG{l+s}{\PYGZdq{}U\PYGZhy{}110\PYGZdq{}} \PYG{n+na}{channel=}\PYG{l+s}{\PYGZdq{}8\PYGZdq{}} \PYG{n+na}{eq=}\PYG{l+s}{\PYGZdq{}highpass\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
    \PYG{n+nt}{\PYGZlt{}polar} \PYG{n+na}{az=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}110.0\PYGZdq{}} \PYG{n+na}{el=}\PYG{l+s}{\PYGZdq{}30.0\PYGZdq{}} \PYG{n+na}{r=}\PYG{l+s}{\PYGZdq{}1.0\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}/loudspeaker\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}loudspeaker} \PYG{n+na}{id=}\PYG{l+s}{\PYGZdq{}U+110\PYGZdq{}} \PYG{n+na}{channel=}\PYG{l+s}{\PYGZdq{}9\PYGZdq{}} \PYG{n+na}{eq=}\PYG{l+s}{\PYGZdq{}highpass\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
    \PYG{n+nt}{\PYGZlt{}polar} \PYG{n+na}{az=}\PYG{l+s}{\PYGZdq{}110.0\PYGZdq{}} \PYG{n+na}{el=}\PYG{l+s}{\PYGZdq{}30.0\PYGZdq{}} \PYG{n+na}{r=}\PYG{l+s}{\PYGZdq{}1.0\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}/loudspeaker\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}virtualspeaker} \PYG{n+na}{id=}\PYG{l+s}{\PYGZdq{}VoS\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
    \PYG{n+nt}{\PYGZlt{}polar} \PYG{n+na}{az=}\PYG{l+s}{\PYGZdq{}0.0\PYGZdq{}} \PYG{n+na}{el=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}90.0\PYGZdq{}} \PYG{n+na}{r=}\PYG{l+s}{\PYGZdq{}1.0\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
    \PYG{n+nt}{\PYGZlt{}route} \PYG{n+na}{lspId=}\PYG{l+s}{\PYGZdq{}M+000\PYGZdq{}} \PYG{n+na}{gainDB=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}13.9794\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
    \PYG{n+nt}{\PYGZlt{}route} \PYG{n+na}{lspId=}\PYG{l+s}{\PYGZdq{}M+030\PYGZdq{}} \PYG{n+na}{gainDB=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}13.9794\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
    \PYG{n+nt}{\PYGZlt{}route} \PYG{n+na}{lspId=}\PYG{l+s}{\PYGZdq{}M\PYGZhy{}030\PYGZdq{}} \PYG{n+na}{gainDB=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}13.9794\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
    \PYG{n+nt}{\PYGZlt{}route} \PYG{n+na}{lspId=}\PYG{l+s}{\PYGZdq{}M+110\PYGZdq{}} \PYG{n+na}{gainDB=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}13.9794\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
    \PYG{n+nt}{\PYGZlt{}route} \PYG{n+na}{lspId=}\PYG{l+s}{\PYGZdq{}M\PYGZhy{}110\PYGZdq{}} \PYG{n+na}{gainDB=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}13.9794\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}/virtualspeaker\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}triplet} \PYG{n+na}{l1=}\PYG{l+s}{\PYGZdq{}VoS\PYGZdq{}} \PYG{n+na}{l2=}\PYG{l+s}{\PYGZdq{}M+110\PYGZdq{}} \PYG{n+na}{l3=}\PYG{l+s}{\PYGZdq{}M\PYGZhy{}110\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}triplet} \PYG{n+na}{l1=}\PYG{l+s}{\PYGZdq{}M\PYGZhy{}030\PYGZdq{}} \PYG{n+na}{l2=}\PYG{l+s}{\PYGZdq{}VoS\PYGZdq{}} \PYG{n+na}{l3=}\PYG{l+s}{\PYGZdq{}M\PYGZhy{}110\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}triplet} \PYG{n+na}{l1=}\PYG{l+s}{\PYGZdq{}M\PYGZhy{}030\PYGZdq{}} \PYG{n+na}{l2=}\PYG{l+s}{\PYGZdq{}VoS\PYGZdq{}} \PYG{n+na}{l3=}\PYG{l+s}{\PYGZdq{}M+000\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}triplet} \PYG{n+na}{l1=}\PYG{l+s}{\PYGZdq{}M\PYGZhy{}030\PYGZdq{}} \PYG{n+na}{l2=}\PYG{l+s}{\PYGZdq{}U\PYGZhy{}030\PYGZdq{}} \PYG{n+na}{l3=}\PYG{l+s}{\PYGZdq{}M+000\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}triplet} \PYG{n+na}{l1=}\PYG{l+s}{\PYGZdq{}M+030\PYGZdq{}} \PYG{n+na}{l2=}\PYG{l+s}{\PYGZdq{}VoS\PYGZdq{}} \PYG{n+na}{l3=}\PYG{l+s}{\PYGZdq{}M+000\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}triplet} \PYG{n+na}{l1=}\PYG{l+s}{\PYGZdq{}M+030\PYGZdq{}} \PYG{n+na}{l2=}\PYG{l+s}{\PYGZdq{}VoS\PYGZdq{}} \PYG{n+na}{l3=}\PYG{l+s}{\PYGZdq{}M+110\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}triplet} \PYG{n+na}{l1=}\PYG{l+s}{\PYGZdq{}U+030\PYGZdq{}} \PYG{n+na}{l2=}\PYG{l+s}{\PYGZdq{}U\PYGZhy{}030\PYGZdq{}} \PYG{n+na}{l3=}\PYG{l+s}{\PYGZdq{}M+000\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}triplet} \PYG{n+na}{l1=}\PYG{l+s}{\PYGZdq{}U+030\PYGZdq{}} \PYG{n+na}{l2=}\PYG{l+s}{\PYGZdq{}M+030\PYGZdq{}} \PYG{n+na}{l3=}\PYG{l+s}{\PYGZdq{}M+000\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}triplet} \PYG{n+na}{l1=}\PYG{l+s}{\PYGZdq{}U\PYGZhy{}110\PYGZdq{}} \PYG{n+na}{l2=}\PYG{l+s}{\PYGZdq{}M\PYGZhy{}030\PYGZdq{}} \PYG{n+na}{l3=}\PYG{l+s}{\PYGZdq{}U\PYGZhy{}030\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}triplet} \PYG{n+na}{l1=}\PYG{l+s}{\PYGZdq{}U\PYGZhy{}110\PYGZdq{}} \PYG{n+na}{l2=}\PYG{l+s}{\PYGZdq{}M\PYGZhy{}030\PYGZdq{}} \PYG{n+na}{l3=}\PYG{l+s}{\PYGZdq{}M\PYGZhy{}110\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}triplet} \PYG{n+na}{l1=}\PYG{l+s}{\PYGZdq{}U+110\PYGZdq{}} \PYG{n+na}{l2=}\PYG{l+s}{\PYGZdq{}U\PYGZhy{}110\PYGZdq{}} \PYG{n+na}{l3=}\PYG{l+s}{\PYGZdq{}M\PYGZhy{}110\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}triplet} \PYG{n+na}{l1=}\PYG{l+s}{\PYGZdq{}U+110\PYGZdq{}} \PYG{n+na}{l2=}\PYG{l+s}{\PYGZdq{}M+110\PYGZdq{}} \PYG{n+na}{l3=}\PYG{l+s}{\PYGZdq{}M\PYGZhy{}110\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}triplet} \PYG{n+na}{l1=}\PYG{l+s}{\PYGZdq{}U+030\PYGZdq{}} \PYG{n+na}{l2=}\PYG{l+s}{\PYGZdq{}U\PYGZhy{}110\PYGZdq{}} \PYG{n+na}{l3=}\PYG{l+s}{\PYGZdq{}U\PYGZhy{}030\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}triplet} \PYG{n+na}{l1=}\PYG{l+s}{\PYGZdq{}U+030\PYGZdq{}} \PYG{n+na}{l2=}\PYG{l+s}{\PYGZdq{}U+110\PYGZdq{}} \PYG{n+na}{l3=}\PYG{l+s}{\PYGZdq{}U\PYGZhy{}110\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}triplet} \PYG{n+na}{l1=}\PYG{l+s}{\PYGZdq{}U+030\PYGZdq{}} \PYG{n+na}{l2=}\PYG{l+s}{\PYGZdq{}U+110\PYGZdq{}} \PYG{n+na}{l3=}\PYG{l+s}{\PYGZdq{}M+110\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}triplet} \PYG{n+na}{l1=}\PYG{l+s}{\PYGZdq{}U+030\PYGZdq{}} \PYG{n+na}{l2=}\PYG{l+s}{\PYGZdq{}M+030\PYGZdq{}} \PYG{n+na}{l3=}\PYG{l+s}{\PYGZdq{}M+110\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}subwoofer} \PYG{n+na}{assignedLoudspeakers=}\PYG{l+s}{\PYGZdq{}M+000, M\PYGZhy{}030, M+030, M\PYGZhy{}110, M+110, U\PYGZhy{}030, U+030, U\PYGZhy{}110, U+110\PYGZdq{}}
          \PYG{n+na}{channel=}\PYG{l+s}{\PYGZdq{}10\PYGZdq{}} \PYG{n+na}{delay=}\PYG{l+s}{\PYGZdq{}0\PYGZdq{}} \PYG{n+na}{eq=}\PYG{l+s}{\PYGZdq{}lowpass\PYGZdq{}} \PYG{n+na}{gainDB=}\PYG{l+s}{\PYGZdq{}0\PYGZdq{}}
          \PYG{n+na}{weights=}\PYG{l+s}{\PYGZdq{}1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0\PYGZdq{}}
          \PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}outputEqConfiguration} \PYG{n+na}{numberOfBiquads=}\PYG{l+s}{\PYGZdq{}1\PYGZdq{}} \PYG{n+na}{type=}\PYG{l+s}{\PYGZdq{}iir\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
      \PYG{n+nt}{\PYGZlt{}filterSpec} \PYG{n+na}{name=}\PYG{l+s}{\PYGZdq{}lowpass\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
         \PYG{n+nt}{\PYGZlt{}biquad} \PYG{n+na}{a1=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}1.9688283\PYGZdq{}} \PYG{n+na}{a2=}\PYG{l+s}{\PYGZdq{}0.96907117\PYGZdq{}} \PYG{n+na}{b0=}\PYG{l+s}{\PYGZdq{}6.0729856e\PYGZhy{}05\PYGZdq{}} \PYG{n+na}{b1=}\PYG{l+s}{\PYGZdq{}0.00012145971\PYGZdq{}} \PYG{n+na}{b2=}\PYG{l+s}{\PYGZdq{}6.0729856e\PYGZhy{}05\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
      \PYG{n+nt}{\PYGZlt{}/filterSpec\PYGZgt{}}
      \PYG{n+nt}{\PYGZlt{}filterSpec} \PYG{n+na}{name=}\PYG{l+s}{\PYGZdq{}highpass\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
         \PYG{n+nt}{\PYGZlt{}biquad} \PYG{n+na}{a1=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}1.9688283\PYGZdq{}} \PYG{n+na}{a2=}\PYG{l+s}{\PYGZdq{}0.96907117\PYGZdq{}} \PYG{n+na}{b0=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}0.98447486\PYGZdq{}} \PYG{n+na}{b1=}\PYG{l+s}{\PYGZdq{}1.9689497\PYGZdq{}} \PYG{n+na}{b2=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}0.98447486\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
      \PYG{n+nt}{\PYGZlt{}/filterSpec\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}/outputEqConfiguration\PYGZgt{}}
\PYG{n+nt}{\PYGZlt{}/panningConfiguration\PYGZgt{}}
\end{sphinxVerbatim}


\subparagraph{Format description}
\label{\detokenize{using-standalone-renderers:format-description}}
The root node of the XML file is \sphinxcode{\textless{}panningConfiguration\textgreater{}}.
This root element supports the folloring optional attributes:
* \sphinxcode{isInfinite} Whether the loudspeakers are regardes as point sources located on the unit sphere (\sphinxcode{false}) or as plane waves, corresponding to an infinite distance (\sphinxcode{true}). The default value is \sphinxcode{false}.
* \sphinxcode{dimension} Whether the setup is considered as a 2-dimensional configuration (value \sphinxcode{2}) or as three-dimensional (\sphinxcode{3}, thedefault). In the 2D case, the array is considered in the x-y plane , and the \sphinxcode{z} or \sphinxcode{el} attributes of the loudspeaker positions are not evaluated. In this case, the triplet specifications consist of two indices only (technically they are pairs, not triplets).

Within the \sphinxcode{\textless{}panningConfiguration\textgreater{}} root element, the following elements are supported:
\begin{description}
\item[{\sphinxcode{\textless{}loudspeaker\textgreater{}}}] \leavevmode
Represents a reproduction loudspeaker.
The position  is encoded either in a \sphinxcode{\textless{}cart\textgreater{}} node representing the cartesian coordinates in the \sphinxcode{x}, \sphinxcode{y} and \sphinxcode{z} attributes (floating point values in meter), or a \sphinxcode{\textless{}polar\textgreater{}} node with the attributes \sphinxcode{az} and \sphinxcode{el} (azimuth and elevation, both in degree) and \sphinxcode{r} (radius, in meter).

The \sphinxcode{\textless{}loudspeaker\textgreater{}} nodes allows for  number of attributes:
\begin{itemize}
\item {} 
\sphinxcode{id} A mandatory, non-empty string identification for the loudspeaker, which must be unique across all \sphinxcode{\textless{}loudspeaker\textgreater{}} and \sphinxcode{\textless{}virtualspeaker\textgreater{}} (see below) elements.
Permitted are alpha-numeric characters, numbers, and the characters “@\&()+/:\_-“.
ID strings are case-sensitive.

\item {} 
\sphinxcode{channel} The output channel number (sound card channel) for this loudspeaker. Logical channel indices start from 1. Each channel must be assigned at most once over the set of all loudspeaker and subwoofers of the setup..

\item {} 
\sphinxcode{gainDB} or \sphinxcode{gain} Additional gain adjustment for this loudspeaker, either in linear scale or in dB (floating-point values. The  default value is 1.0 or 0 dB.  \sphinxcode{gainDB} or \sphinxcode{gain} are mutually exclusive.

\item {} 
\sphinxcode{delay} Delay adjustment to be applied to this loudspeaker as a floating-point value in seconds. The default value is  0.0).

\item {} 
\sphinxcode{eq} An optional output equalisation filter to be applied for this loudspeaker.
Specified as a non-empty string that needs to match an \sphinxcode{filterSpec} element in the \sphinxcode{outputEqConfiguration}
element (see below). If not given, no EQ is applied to for this loudspeaker.

\end{itemize}

\item[{\sphinxcode{\textless{}virtualspeaker\textgreater{}}}] \leavevmode
An additional vertex added to the triangulation that does not correspond to a physical loudspeaker. Consist of a numerical \sphinxcode{id} attribute and a position specified either as a \sphinxcode{\textless{}cart\textgreater{}} or a \sphinxcode{\textless{}polar\textgreater{}} node (see \sphinxcode{\textless{}loudspeaker\textgreater{}} specification).

The \sphinxcode{\textless{}virtualspeaker\textgreater{}} node provides the following configuration options:
\begin{itemize}
\item {} 
A mandatory, nonempty and unique attribute \sphinxcode{id} that follows the same rules as for the \sphinxcode{\textless{}loudspeaker\textgreater{}} elements.

\item {} 
A number of \sphinxcode{route} sub-elements that specify how the energy from this virtual loudspeaker is routed to real loudspeakers.
The \sphinxcode{route} element has the following attributes:
* \sphinxcode{lspId}: The ID of an existing real loudspeaker.
* \sphinxcode{gainDB}: A scaling factor with which the gain of the virtual loudspeaker is distributed to the real loudspeaker.

In the above example, the routing specification is given by

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
 \PYG{n+nt}{\PYGZlt{}virtualspeaker} \PYG{n+na}{id=}\PYG{l+s}{\PYGZdq{}VoS\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}polar} \PYG{n+na}{az=}\PYG{l+s}{\PYGZdq{}0.0\PYGZdq{}} \PYG{n+na}{el=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}90.0\PYGZdq{}} \PYG{n+na}{r=}\PYG{l+s}{\PYGZdq{}1.0\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}route} \PYG{n+na}{lspId=}\PYG{l+s}{\PYGZdq{}M+000\PYGZdq{}} \PYG{n+na}{gainDB=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}13.9794\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}route} \PYG{n+na}{lspId=}\PYG{l+s}{\PYGZdq{}M+030\PYGZdq{}} \PYG{n+na}{gainDB=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}13.9794\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}route} \PYG{n+na}{lspId=}\PYG{l+s}{\PYGZdq{}M\PYGZhy{}030\PYGZdq{}} \PYG{n+na}{gainDB=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}13.9794\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}route} \PYG{n+na}{lspId=}\PYG{l+s}{\PYGZdq{}M+110\PYGZdq{}} \PYG{n+na}{gainDB=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}13.9794\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}route} \PYG{n+na}{lspId=}\PYG{l+s}{\PYGZdq{}M\PYGZhy{}110\PYGZdq{}} \PYG{n+na}{gainDB=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}13.9794\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
\PYG{n+nt}{\PYGZlt{}/virtualspeaker\PYGZgt{}}
\end{sphinxVerbatim}

That means that the energy of the virtual speaker \sphinxcode{"vos"} is routed to five surrounding speakers, with a scaling factor of 13.97 dB each.

\end{itemize}

\end{description}

\sphinxcode{\textless{}subwoofer\textgreater{}} Specify a subwoofer channel. In the current implementation, the loudspeaker are weighted and mixed into an arbitray number of subwoofer channels. The attributes are:
\begin{itemize}
\item {} 
\sphinxcode{assignedLoudspeakers} The loudspeaker signals (given as a sequence of logical loudspeaker IDs) that contribute to the subwoofer signals. Given as comma-separated list of loudspeaker index or loudspeaker ranges. Index sequences are similar to Matlab array definitions, except that thes commas separating the parts of the sequence are compulsory.

Complex example:

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
assignedLoudspeakers = \PYGZdq{}1, 3,4,5:7, 2, 8:\PYGZhy{}3:1\PYGZdq{}
\end{sphinxVerbatim}

\item {} 
\sphinxcode{weights} Optional weights (linear scale) that scale the contributions of the assigned speakers to the subwoofer signal.
Given as a sequence of comma-separated linear-scale gain values, Matlab ranges are also allowed. The number of elements must match the \sphinxcode{assignedLoudspeakers} index list. Optional value, the default option assigns 1.0 for all assigned loudspeakers.
Example: “0:0.2:1.0, 1, 1, 1:-0.2:0”.

\item {} 
\sphinxcode{gainDB} or \sphinxcode{gain} Additional gain adjustment for this subwoofer, either in linear scale or in dB (floating-point valus, default 1.0 / 0 dB ). Applied on top of the \sphinxcode{weight} attributes to the summed subwoofer signal. See the \sphinxcode{\textless{}loudspeaker\textgreater{}} specification.

\item {} 
\sphinxcode{delay} Delay adjustment for this (floating-point value in seconds, default 0.0). See the \sphinxcode{\textless{}loudspeaker\textgreater{}} specification.

\end{itemize}
\begin{description}
\item[{\sphinxcode{\textless{}triplet\textgreater{}}}] \leavevmode
Loudspeaker triplet specified by the attributes \sphinxcode{l1}, \sphinxcode{l2}, and \sphinxcode{l3}.
The values of \sphinxcode{l1}, \sphinxcode{l2}, and \sphinxcode{l3} must correspond to IDs of existing real or virtual loudspeakers.
In case of a 2D setup, only \sphinxcode{l1} and \sphinxcode{l2} are evaluated.

\begin{sphinxadmonition}{note}{Note:}
At the time being, triplet specifications must be generated externally and placed in the configuration file.
This is typically done by creating a Delaunay triangulation on the sphere, which can be done in Matlab or Python.

Future versions of the loudspeaker renderer might perform the triangulation internally, or might not require a
conventional triangulation at all. In these cases, is it possible that the renderer ignores or internally
adapts the specified triplets.
\end{sphinxadmonition}

\item[{\sphinxcode{outputEqConfiguration}}] \leavevmode
This optional element must occur at most once.
It provides a global specification for equalisation filters for loudspeakers and subwoofers.

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\PYGZlt{}outputEqConfiguration}  \PYG{n+na}{type=}\PYG{l+s}{\PYGZdq{}iir\PYGZdq{}} \PYG{n+na}{numberOfBiquads=}\PYG{l+s}{\PYGZdq{}1\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}filterSpec} \PYG{n+na}{name=}\PYG{l+s}{\PYGZdq{}lowpass\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
    \PYG{n+nt}{\PYGZlt{}biquad} \PYG{n+na}{a1=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}1.9688283\PYGZdq{}} \PYG{n+na}{a2=}\PYG{l+s}{\PYGZdq{}0.96907117\PYGZdq{}} \PYG{n+na}{b0=}\PYG{l+s}{\PYGZdq{}6.0729856e\PYGZhy{}05\PYGZdq{}} \PYG{n+na}{b1=}\PYG{l+s}{\PYGZdq{}0.00012145971\PYGZdq{}} \PYG{n+na}{b2=}\PYG{l+s}{\PYGZdq{}6.0729856e\PYGZhy{}05\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}/filterSpec\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}filterSpec} \PYG{n+na}{name=}\PYG{l+s}{\PYGZdq{}highpass\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
    \PYG{n+nt}{\PYGZlt{}biquad} \PYG{n+na}{a1=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}1.9688283\PYGZdq{}} \PYG{n+na}{a2=}\PYG{l+s}{\PYGZdq{}0.96907117\PYGZdq{}} \PYG{n+na}{b0=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}0.98447486\PYGZdq{}} \PYG{n+na}{b1=}\PYG{l+s}{\PYGZdq{}1.9689497\PYGZdq{}} \PYG{n+na}{b2=}\PYG{l+s}{\PYGZdq{}\PYGZhy{}0.98447486\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}/filterSpec\PYGZgt{}}
\PYG{n+nt}{\PYGZlt{}/outputEqConfiguration\PYGZgt{}}
\end{sphinxVerbatim}

The  attributes are:
\begin{itemize}
\item {} 
\sphinxcode{type}: The type of the output filters. At the moment, only IIR filters provide as second-order sections (biquads) are supported. Thus, the value \sphinxcode{"iir"} must be set.

\item {} 
\sphinxcode{numberOfBiquads}: This value is specific to the \sphinxcode{"iir"} filter type.

\end{itemize}

The filters are described in \sphinxcode{filterSpec} elements.
These are identifed by a \sphinxcode{name} attribute, which must be an non-empty string unique across all \sphinxcode{filterSpec} elements.
For the type \sphinxcode{iir}, a \sphinxcode{filterSpec} element consists of at most \sphinxcode{numberOfBiquad} nodes of type \sphinxcode{biquad}, which represent the coefficients of one second-order IIR (biquad) section.
This is done through the attributes \sphinxcode{a1},  \sphinxcode{a2}, \sphinxcode{b0}, \sphinxcode{b1}, \sphinxcode{b2} that represent the coefficients of the normalised transfer function
\begin{equation*}
\begin{split}H(z) = \frac{ b_0 + b_1 z^{-1} + b_{2}z^{-2} }{1 + a_1 z^{-1} + a_{2}z^{-2}}\end{split}
\end{equation*}
\end{description}


\subsubsection{The matrix convolver renderer}
\label{\detokenize{using-standalone-renderers:using-visr-using-standalone-renderers-matrix-convolver}}\label{\detokenize{using-standalone-renderers:the-matrix-convolver-renderer}}
The matrix convolver renderer is a multiple-input multiple-output convolution engine to be run as a command line application.

It implements uniformly partitioned fast convolution for arbitrary routing points between input and output files.


\paragraph{Basic usage}
\label{\detokenize{using-standalone-renderers:basic-usage}}
\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYGZdl{}\PYGZgt{} matrix\PYGZus{}convolver \PYGZhy{}\PYGZhy{}help
\PYGZhy{}h \PYG{o}{[} \PYGZhy{}\PYGZhy{}help \PYG{o}{]}                   Show \PYG{n+nb}{help} and usage information.
\PYGZhy{}v \PYG{o}{[} \PYGZhy{}\PYGZhy{}version \PYG{o}{]}                Display version information.
\PYGZhy{}\PYGZhy{}option\PYGZhy{}file arg               Load options from a file. Can also be used
                                with syntax \PYG{l+s+s2}{\PYGZdq{}@\PYGZlt{}filename\PYGZgt{}\PYGZdq{}}.
\PYGZhy{}D \PYG{o}{[} \PYGZhy{}\PYGZhy{}audio\PYGZhy{}backend \PYG{o}{]} arg      The audio backend. JACK\PYGZus{}NATIVE activates the
                                native Jack driver insteat of the PortAudio
                                implementation.
\PYGZhy{}\PYGZhy{}audio\PYGZhy{}ifc\PYGZhy{}options arg         Audio interface optional configuration
\PYGZhy{}\PYGZhy{}audio\PYGZhy{}ifc\PYGZhy{}option\PYGZhy{}file arg     Audio interface optional configuration file
\PYGZhy{}\PYGZhy{}list\PYGZhy{}audio\PYGZhy{}backends           List the supported audio backends that can be
                                passed to the the \PYG{l+s+s2}{\PYGZdq{}\PYGZhy{}\PYGZhy{}audio\PYGZhy{}backend\PYGZdq{}} \PYG{o}{(}\PYG{l+s+s2}{\PYGZdq{}\PYGZhy{}D\PYGZdq{}}\PYG{o}{)}
                                option.
\PYGZhy{}\PYGZhy{}list\PYGZhy{}fft\PYGZhy{}libraries            List the supported FFT implementations that
                                can be selected using the \PYG{l+s+s2}{\PYGZdq{}\PYGZhy{}\PYGZhy{}fftLibrary\PYGZdq{}}
                                option.
\PYGZhy{}f \PYG{o}{[} \PYGZhy{}\PYGZhy{}sampling\PYGZhy{}frequency \PYG{o}{]} arg Sampling frequency \PYG{o}{[}Hz\PYG{o}{]}
\PYGZhy{}p \PYG{o}{[} \PYGZhy{}\PYGZhy{}period \PYG{o}{]} arg             Period \PYG{o}{(}block length\PYG{o}{)}: The number of samples
                                per audio block, also the block size of the
                                partitioned convolution.
\PYGZhy{}i \PYG{o}{[} \PYGZhy{}\PYGZhy{}input\PYGZhy{}channels \PYG{o}{]} arg     Number of input channels \PYG{k}{for} audio object
                                signal.
\PYGZhy{}o \PYG{o}{[} \PYGZhy{}\PYGZhy{}output\PYGZhy{}channels \PYG{o}{]} arg    Number of audio output channels.
\PYGZhy{}\PYGZhy{}filters arg                   Initial impulse responses, specified as
                                comma\PYGZhy{}separated list of one or multiple WAV
                                files.
\PYGZhy{}\PYGZhy{}filter\PYGZhy{}file\PYGZhy{}index\PYGZhy{}offsets arg Index offsets to address the impulses in the
                                provided multichannel filter files. If
                                specified, the number of values must match
                                the number of filter files.
\PYGZhy{}r \PYG{o}{[} \PYGZhy{}\PYGZhy{}routings \PYG{o}{]} arg           Initial routing entries, expects a JSON array
                                consisting of objects \PYG{l+s+s2}{\PYGZdq{}\PYGZob{}\PYGZdq{}}inputs\PYG{l+s+s2}{\PYGZdq{}: nn,}
\PYG{l+s+s2}{                                \PYGZdq{}}outputs\PYG{l+s+s2}{\PYGZdq{}:nn, \PYGZdq{}}filters\PYG{l+s+s2}{\PYGZdq{}:nn (\PYGZdq{}}gain\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{:XX)}
\PYG{l+s+s2}{\PYGZhy{}l [ \PYGZhy{}\PYGZhy{}max\PYGZhy{}filter\PYGZhy{}length ] arg  Maximum length of the impulse responses, in}
\PYG{l+s+s2}{                                samples. If not given, it defaults to the}
\PYG{l+s+s2}{                                longest provided filter,}
\PYG{l+s+s2}{\PYGZhy{}\PYGZhy{}max\PYGZhy{}routings arg              Maximum number of filter routings.}
\PYG{l+s+s2}{\PYGZhy{}\PYGZhy{}max\PYGZhy{}filters arg               Maximum number of impulse responses that can}
\PYG{l+s+s2}{                                be stored.}
\PYG{l+s+s2}{\PYGZhy{}\PYGZhy{}fft\PYGZhy{}library arg               Specify the FFT implementation to be used.}
\PYG{l+s+s2}{                                Defaults to the default implementation for}
\PYG{l+s+s2}{                                the platform.}
\end{sphinxVerbatim}


\paragraph{Operation}
\label{\detokenize{using-standalone-renderers:operation}}
The matrix convolver consists of the following elements:
\begin{itemize}
\item {} 
A number of \sphinxstylestrong{input channels}.

\item {} 
A set of \sphinxstylestrong{FIR filter}, which can be reused multiple times.

\item {} 
A set of \sphinxstylestrong{output channels}.

\item {} 
A set of \sphinxstylestrong{routings}, which defines that a given input is filtered through a specific filter (with an optional gain), and the result is routed to a given output channels. All filtering results that are routed to a given output are summed together.

\end{itemize}

This interface allows for several different operation modes, for example:
\begin{itemize}
\item {} 
Multi-channel filtering where each input is filtered with one filter to give produce the same number of output channels.

\item {} 
Filtering to produce multiple, different copies of the same input signal.

\item {} 
Filtering multiple signals and adding them together, as, for example, in filter-and-sum beamforming.

\item {} 
MIMO filtering with complete matrices, where a filter is defined for each input-output combination.

\item {} 
MIMO filtering with sparse matrices, corresponding to sophisticated routings between inputs and outputs.

\end{itemize}


\paragraph{Detailed option description}
\label{\detokenize{using-standalone-renderers:detailed-option-description}}
\sphinxcode{-{-}help} or \sphinxcode{-h}:
\begin{description}
\item[{\sphinxcode{-{-}version} or \sphinxcode{-v}  :}] \leavevmode
Standard options, described in {\hyperref[\detokenize{using-standalone-renderers:using-standalone-renderers-common-options}]{\sphinxcrossref{\DUrole{std,std-ref}{Common options}}}}

\item[{\sphinxcode{-{-}option-file}:}] \leavevmode
Standard options, described in {\hyperref[\detokenize{using-standalone-renderers:using-standalone-renderers-common-options}]{\sphinxcrossref{\DUrole{std,std-ref}{Common options}}}}

\item[{\sphinxcode{-{-}audio-backend} or \sphinxcode{-D}:}] \leavevmode
Standard options, described in {\hyperref[\detokenize{using-standalone-renderers:using-standalone-renderers-common-options}]{\sphinxcrossref{\DUrole{std,std-ref}{Common options}}}}

\item[{\sphinxcode{-{-}audio-ifc-options}:}] \leavevmode
Standard options, described in {\hyperref[\detokenize{using-standalone-renderers:using-standalone-renderers-common-options}]{\sphinxcrossref{\DUrole{std,std-ref}{Common options}}}}

\item[{\sphinxcode{-{-}audio-ifc-option-file}:}] \leavevmode
Standard options, described in {\hyperref[\detokenize{using-standalone-renderers:using-standalone-renderers-common-options}]{\sphinxcrossref{\DUrole{std,std-ref}{Common options}}}}

\item[{\sphinxcode{-{-}sampling-frequency} or \sphinxcode{-f}}] \leavevmode
Standard options, described in {\hyperref[\detokenize{using-standalone-renderers:using-standalone-renderers-common-options}]{\sphinxcrossref{\DUrole{std,std-ref}{Common options}}}}

\item[{\sphinxcode{-{-}period} or \sphinxcode{-p}:}] \leavevmode
Standard options, described in {\hyperref[\detokenize{using-standalone-renderers:using-standalone-renderers-common-options}]{\sphinxcrossref{\DUrole{std,std-ref}{Common options}}}}

\item[{\sphinxcode{-{-}input-channels} or \sphinxcode{-i}:}] \leavevmode
The number of input channels. Must not exceed the number of capture channels of the sound card.

\item[{\sphinxcode{-o} or \sphinxcode{-{-}output-channels}:}] \leavevmode
The number of output channels. Must be less or equal than the number of sound card output channels.

\item[{\sphinxcode{-{-}filters}}] \leavevmode
The filters, specified as a comma-separated list of WAV files. WAV files can be multichannel, in this case, every channel is handled as a separate filter.

All filters are combined into a single array, where each filter is associated to a unique index (starting from zero if not specified otherwise.)

This argument is optional. If not provided, all filters are zero-initialised. Note that if the \sphinxcode{filters} argument is not provided, then the option \sphinxcode{max-routings} must be provided.

\item[{\sphinxcode{-{-}filter-file-index-offsets}}] \leavevmode
Specify the start filter index for each WAV file specified by the \sphinxcode{-{-}filters} argument.
To be provided as a comma-separated list of nonnegative filter entries, one for each file in the \sphinxcode{filters} argument.
This argument is optional. If not provided, the start index of the first file is 0, and the start offset af all subsequent filter files follows the end index of the previous filter file.
This facility can be used to decouple the number of filters in the WAV files from the indexing scheme used to define the routings.

Example:

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYGZhy{}\PYGZhy{}filters \PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}filters\PYGZus{}2ch.wav, filters\PYGZus{}6ch.wav, filters\PYGZus{}4ch.wav\PYGZdq{}}
\PYGZhy{}\PYGZhy{}filter\PYGZhy{}file\PYGZhy{}index\PYGZhy{}offsets\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}2, 8, 16\PYGZdq{}}
\end{sphinxVerbatim}

Here, three WAV files are provided: \sphinxcode{filters\_2ch.wav}, \sphinxcode{filters\_6ch.wav}, and \sphinxcode{filters\_4ch.wav}, with 2, 6, and 4 channels respectively.
The filter offsets “2, 8, 16” mean that the filters of \sphinxcode{filters\_2ch.wav} will be associated to the indices 2 and 3, that of \sphinxcode{filters\_6ch.wav} by indices 8-13, and that of \sphinxcode{filters\_4ch.wav} by the indices 16-19.

Any filters below, between, or above the initialized filter channels (here, indices 0-1, 4-7, 14-15, and \textgreater{}=20) will be zero-initialised.

If the \sphinxcode{-{-}filter-file-index-offsets} hadn’t been provided in this example, the start offsets for the filter sets from the three files would have been 0,2,8.

\item[{\sphinxcode{-{-}routings} or \sphinxcode{-r}}] \leavevmode
Provide a list of routings points. This is to be specified as a JSON string.
A routing defines a filter being applied between a specific input channel and a specific output channels.
The JSON representation for a single entry is

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{p}{\PYGZob{}} \PYG{n+nt}{\PYGZdq{}input\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}\PYGZlt{}i\PYGZgt{}\PYGZdq{}}\PYG{p}{,} \PYG{n+nt}{\PYGZdq{}output\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}\PYGZlt{}o\PYGZgt{}\PYGZdq{}}\PYG{p}{,} \PYG{n+nt}{\PYGZdq{}filter\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}\PYGZlt{}f\PYGZgt{}\PYGZdq{}}\PYG{p}{,} \PYG{n+nt}{\PYGZdq{}gain\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}\PYGZlt{}g\PYGZgt{}\PYGZdq{}} \PYG{p}{\PYGZcb{}}
\end{sphinxVerbatim}

Here, \sphinxcode{\textless{}i\textgreater{}} is the index of the input channel, \sphinxcode{\textless{}o\textgreater{}} is the channel index of the output, and \sphinxcode{\textless{}f\textgreater{}} is the index of the filter (see above).
All indices are zero-offset.
The gain specification \sphinxcode{,"gain": \textless{}g\textgreater{}} is optional, with \sphinxcode{\textless{}g\textgreater{}} representing a linear-scale gain value.

A routing list is a JSON array of routing entries, for example

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{p}{[}\PYG{p}{\PYGZob{}}\PYG{n+nt}{\PYGZdq{}input\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}0\PYGZdq{}}\PYG{p}{,} \PYG{n+nt}{\PYGZdq{}output\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}0\PYGZdq{}}\PYG{p}{,} \PYG{n+nt}{\PYGZdq{}filter\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}2\PYGZdq{}} \PYG{p}{\PYGZcb{}}\PYG{p}{,}
 \PYG{p}{\PYGZob{}}\PYG{n+nt}{\PYGZdq{}input\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}0\PYGZdq{}}\PYG{p}{,} \PYG{n+nt}{\PYGZdq{}output\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}1\PYGZdq{}}\PYG{p}{,} \PYG{n+nt}{\PYGZdq{}filter\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}1\PYGZdq{}} \PYG{p}{\PYGZcb{}}\PYG{p}{,}
 \PYG{p}{\PYGZob{}}\PYG{n+nt}{\PYGZdq{}input\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}0\PYGZdq{}}\PYG{p}{,} \PYG{n+nt}{\PYGZdq{}output\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}2\PYGZdq{}}\PYG{p}{,} \PYG{n+nt}{\PYGZdq{}filter\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}0\PYGZdq{}} \PYG{p}{\PYGZcb{}}\PYG{p}{]}
\end{sphinxVerbatim}

A routing entry can define multiple multiple routings using a Matlab-like stride syntax for \sphinxcode{\textless{}i\textgreater{}}, \sphinxcode{\textless{}o\textgreater{}}, \sphinxcode{\textless{}f\textgreater{}}, or several of them.
If an index is a stride sequence, then the routing entry is duplicated over all values of the stride sequence. If more than one index in the routing entry are strides, then all of them must have the same length, and each of the duplicated routing entries contains the respective value of the respective stride sequence.
For example, the strided routing entry

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{p}{\PYGZob{}}\PYG{n+nt}{\PYGZdq{}input\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}3\PYGZdq{}}\PYG{p}{,} \PYG{n+nt}{\PYGZdq{}output\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}0:3:9\PYGZdq{}}\PYG{p}{,} \PYG{n+nt}{\PYGZdq{}filter\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}1\PYGZdq{}} \PYG{p}{\PYGZcb{}}
\end{sphinxVerbatim}

routes input 3 to the outputs 0, 3, 6, and 9, using the filter indexed by 1 for each routing.
In contrast.

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{p}{\PYGZob{}}\PYG{n+nt}{\PYGZdq{}input\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}0\PYGZdq{}}\PYG{p}{,} \PYG{n+nt}{\PYGZdq{}output\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}0:2\PYGZdq{}}\PYG{p}{,} \PYG{n+nt}{\PYGZdq{}filter\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}2:\PYGZhy{}1:0\PYGZdq{}} \PYG{p}{\PYGZcb{}}
\end{sphinxVerbatim}

is equivalent to the routing list shown above.

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{p}{[}\PYG{p}{\PYGZob{}}\PYG{n+nt}{\PYGZdq{}input\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}0\PYGZdq{}}\PYG{p}{,} \PYG{n+nt}{\PYGZdq{}output\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}0\PYGZdq{}}\PYG{p}{,} \PYG{n+nt}{\PYGZdq{}filter\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}2\PYGZdq{}} \PYG{p}{\PYGZcb{}}\PYG{p}{,}
 \PYG{p}{\PYGZob{}}\PYG{n+nt}{\PYGZdq{}input\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}0\PYGZdq{}}\PYG{p}{,} \PYG{n+nt}{\PYGZdq{}output\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}1\PYGZdq{}}\PYG{p}{,} \PYG{n+nt}{\PYGZdq{}filter\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}1\PYGZdq{}} \PYG{p}{\PYGZcb{}}\PYG{p}{,}
 \PYG{p}{\PYGZob{}}\PYG{n+nt}{\PYGZdq{}input\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}0\PYGZdq{}}\PYG{p}{,} \PYG{n+nt}{\PYGZdq{}output\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}2\PYGZdq{}}\PYG{p}{,} \PYG{n+nt}{\PYGZdq{}filter\PYGZdq{}}\PYG{p}{:}\PYG{l+s+s2}{\PYGZdq{}0\PYGZdq{}} \PYG{p}{\PYGZcb{}}\PYG{p}{]}
\end{sphinxVerbatim}

\item[{\sphinxcode{-{-}max-filter-length} or \sphinxcode{-l}:}] \leavevmode
Define the maximum length of the FIR filters.
If the \sphinxcode{-{-}filters} option is provided, this argument is optional. In this case, admissible filter length is set to the largest length of all specified filter.
an error is reported if any specified filter exceeds the admissible length.
If \sphinxcode{-{-}filters} and \sphinxcode{-{-}max-filter-length} are both provided, then an error is generated if the length of any specified filter exceeds the value of \sphinxcode{-{-}max-filter-length}.

\item[{\sphinxcode{-{-}max-routings} :}] \leavevmode
Define the maximum number of routings.
If the \sphinxcode{-{-}routings} options is present, this argument is optional, and the maximum number of permissible routings is set to the number
of routing entries in the \sphinxcode{-{-}routing} argument.
If \sphinxcode{routings} and \sphinxcode{-{-}max-routings} are both specified, the number of entries in \sphinxcode{-{-}routings} must not exceed the value of \sphinxcode{-{-}max-routings}.

\item[{\sphinxcode{-{-}max-filters}:}] \leavevmode
Define the maximum number of filter entries.
This parameter is optional if the argument \sphinxcode{-{-}filters} is provided. In this case, the maximum filter number is set to the number of filters generated by the  \sphinxcode{-{-}filters} argument.

\begin{sphinxadmonition}{note}{Note:}
If combined with \sphinxcode{-{-}filter-file-index-offsets}, this automatically computed number of filters includes any gaps in the generated filter set.
\end{sphinxadmonition}

If \sphinxcode{-{-}filters} and \sphinxcode{max-filters} are both provided, then the number of filter entries created by \sphinxcode{-{-}filters} must not exceed
the value of \sphinxcode{-{-}max-filters}.

\item[{\sphinxcode{-{-}fft-library}:}] \leavevmode
Select a FFT implementation from the set of available FFT libraries.
The admissible values (strings) can be obtained through the \sphinxcode{-{-}list-fft-libraries} option.

\end{description}

\begin{sphinxadmonition}{note}{Note:}
The current implementation accepts only a static configuration.

Future versions, however, will provide runtime control through a network command interface.

Some arguments or argument combinations do not make sense at the moment, but will do when combined with runtime control.
Examples include the ability to provide empty routings, zero-valued filters, or to specify values for \sphinxcode{-{-}max-routings} or \sphinxcode{-{-}max-filters} that are larger than the currently set values.
\end{sphinxadmonition}


\paragraph{Examples}
\label{\detokenize{using-standalone-renderers:examples}}
A channel-wise multichannel convolution can be performed as

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYGZdl{}\PYGZgt{} matrix\PYGZus{}convolver \PYGZhy{}i \PYG{l+m}{2} \PYGZhy{}o \PYG{l+m}{2} \PYGZhy{}p \PYG{l+m}{512} \PYGZhy{}D PortAudio \PYGZhy{}f \PYG{l+m}{48000} \PYGZhy{}\PYGZhy{}filters\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}filters.wav\PYGZdq{}}
  \PYGZhy{}r \PYG{l+s+s1}{\PYGZsq{}[ \PYGZob{}\PYGZbs{}\PYGZdq{}input\PYGZbs{}\PYGZdq{}: \PYGZbs{}\PYGZdq{}0:1\PYGZbs{}\PYGZdq{}, \PYGZbs{}\PYGZdq{}output\PYGZbs{}\PYGZdq{}:\PYGZbs{}\PYGZdq{}0:1\PYGZbs{}\PYGZdq{}, \PYGZbs{}\PYGZdq{}filter\PYGZbs{}\PYGZdq{}:\PYGZbs{}\PYGZdq{}0:1\PYGZbs{}\PYGZdq{}\PYGZcb{}]\PYGZsq{}}
\end{sphinxVerbatim}

\begin{sphinxadmonition}{note}{Note:}
The quoting is necessary when started from the command line.
\end{sphinxadmonition}

The following example shows a convolution with binaural room impulse responses, where a 9-loudspeaker multichannel signal is routed to 9x2 BRIRs
that are summed to form two ear signals.

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYGZdl{}\PYGZgt{} matrix\PYGZus{}convolver \PYGZhy{}i \PYG{l+m}{9} \PYGZhy{}o \PYG{l+m}{2} \PYGZhy{}\PYGZhy{}max\PYGZhy{}filters\PYG{o}{=}\PYG{l+m}{18} \PYGZhy{}\PYGZhy{}max\PYGZhy{}routings\PYG{o}{=}\PYG{l+m}{18}
   \PYGZhy{}r \PYG{l+s+s2}{\PYGZdq{}[\PYGZob{}\PYGZbs{}\PYGZdq{}input\PYGZbs{}\PYGZdq{}:\PYGZbs{}\PYGZdq{}0:8\PYGZbs{}\PYGZdq{}, \PYGZbs{}\PYGZdq{}output\PYGZbs{}\PYGZdq{}:\PYGZbs{}\PYGZdq{}0\PYGZbs{}\PYGZdq{}, \PYGZbs{}\PYGZdq{}filter\PYGZbs{}\PYGZdq{}:\PYGZbs{}\PYGZdq{}0:2:16\PYGZbs{}\PYGZdq{}\PYGZcb{},}
\PYG{l+s+s2}{        \PYGZob{}\PYGZbs{}\PYGZdq{}input\PYGZbs{}\PYGZdq{}:\PYGZbs{}\PYGZdq{}0:8\PYGZbs{}\PYGZdq{}, \PYGZbs{}\PYGZdq{}output\PYGZbs{}\PYGZdq{}:\PYGZbs{}\PYGZdq{}1\PYGZbs{}\PYGZdq{}, \PYGZbs{}\PYGZdq{}filter\PYGZbs{}\PYGZdq{}:\PYGZbs{}\PYGZdq{}1:2:17\PYGZbs{}\PYGZdq{}\PYGZcb{}]\PYGZdq{}}
   \PYGZhy{}\PYGZhy{}filters\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}bbcrdlr9ch\PYGZus{}brirs.wav\PYGZdq{}}
   \PYGZhy{}D Jack \PYGZhy{}f \PYG{l+m}{48000} \PYGZhy{}p \PYG{l+m}{512}
\end{sphinxVerbatim}

Here, the file \sphinxcode{bbcrdlr9ch\_brirs.wav} contains the 18 BRIRs, with the first nine channels for the left and the remaining channels for the right ear filters.


\subsubsection{Interface-specific audio options}
\label{\detokenize{using-standalone-renderers:interface-specific-audio-options}}\label{\detokenize{using-standalone-renderers:using-visr-using-standalone-renderers-specific-audio-options}}
This section described the audio-interface-specific options that can be passed through the
\sphinxcode{-{-}audio-ifc-options} or \sphinxcode{-{-}audio-ifc-option-file} arguments.


\paragraph{PortAudio interface}
\label{\detokenize{using-standalone-renderers:portaudio-interface}}
The interface-specific options for the PortAudio interface are to be provided as a JSON file,
for example:

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{p}{\PYGZob{}}
 \PYG{n+nt}{\PYGZdq{}sampleformat\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}...\PYGZdq{}}\PYG{p}{,}
 \PYG{n+nt}{\PYGZdq{}interleaved\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}...\PYGZdq{}}\PYG{p}{,}
 \PYG{n+nt}{\PYGZdq{}hostapi\PYGZdq{}} \PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}...\PYGZdq{}}
\PYG{p}{\PYGZcb{}}
\end{sphinxVerbatim}

\begin{sphinxadmonition}{note}{Note:}
When used on the command line using the \sphinxcode{-{-}audio-ifc-options} argument, apply the quotation and escaping as described in Section {\hyperref[\detokenize{using-standalone-renderers:using-standalone-renderers-common-options}]{\sphinxcrossref{\DUrole{std,std-ref}{Common options}}}}.
\end{sphinxadmonition}

The following options are supported for the PortAudio interface:
\begin{description}
\item[{\sphinxstylestrong{sampleformat}}] \leavevmode
Specifies the PortAudio sample format. Possible values are:
\begin{itemize}
\item {} 
\sphinxcode{signedInt8Bit}

\item {} 
\sphinxcode{unsignedInt8Bit}

\item {} 
\sphinxcode{signedInt16Bit}

\item {} 
\sphinxcode{unsignedInt16Bit}

\item {} 
\sphinxcode{signedInt24Bit}

\item {} 
\sphinxcode{unsignedInt24Bit}

\item {} 
\sphinxcode{signedInt32Bit}

\item {} 
\sphinxcode{unsignedInt32Bit}

\item {} 
\sphinxcode{float32Bit} .

\end{itemize}

\item[{\sphinxstylestrong{interleaved}:}] \leavevmode
Enable/disable interleaved mode, possible values are \sphinxcode{true, false}.

\item[{\sphinxstylestrong{hostapi}:}] \leavevmode
Used to specify PortAudio backend audio interface. Possible values are:
\begin{itemize}
\item {} 
\sphinxcode{default}: This activates the default backend

\item {} 
\sphinxcode{WASAPI} : Supported OS: Windows.

\item {} 
\sphinxcode{ASIO} : Supported OS: Windows.

\item {} 
\sphinxcode{WDMKS}: Supported OS: Windows.

\item {} 
\sphinxcode{DirectSound} : Supported OS: Windows.

\item {} 
\sphinxcode{CoreAudio} : Supported OS: MacOs.

\item {} 
\sphinxcode{ALSA} : Supported OS: Linux.

\item {} 
\sphinxcode{JACK} : Supported OSs: MacOs, Linux.

\end{itemize}

PortAudio aupports a number of other APIs. However, they are outdated or refer to obsolete platforms and therefore should not be used:
- \sphinxcode{SoundManager} (MacOs)
- \sphinxcode{OSS} (Linux)
- \sphinxcode{AL}
- \sphinxcode{BeOS}
- \sphinxcode{AudioScienceHPI} (Linux)

\end{description}

This configuration is an example of usage of PortAudio, with Jack audio interface as backend.

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{p}{\PYGZob{}}
  \PYG{n+nt}{\PYGZdq{}sampleformat\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}float32Bit\PYGZdq{}}\PYG{p}{,}
  \PYG{n+nt}{\PYGZdq{}interleaved\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}false\PYGZdq{}}\PYG{p}{,}
  \PYG{n+nt}{\PYGZdq{}hostapi\PYGZdq{}} \PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}JACK\PYGZdq{}}
\PYG{p}{\PYGZcb{}}
\end{sphinxVerbatim}


\paragraph{Jack audio interface}
\label{\detokenize{using-standalone-renderers:jack-audio-interface}}
The following options can be provided when using Jack as our top level component’s Audio Interface:
\begin{description}
\item[{\sphinxcode{clientname}:}] \leavevmode
Jack Client name for our top level component.

\item[{\sphinxcode{servername}:}] \leavevmode
Jack Server name. If not provided, the default Jack server is used.

\item[{\sphinxcode{autoconnect}:}] \leavevmode
Globally enable/disable the automatic connection of ports.
Admissible values are \sphinxcode{true} and \sphinxcode{false}.
This setting can be overridden specifically for capture and playback ports in the port configuration section described below.

\end{description}

\sphinxcode{portconfig}: Subset of options regarding the configuration and connection of Jack Ports, see following section.


\subparagraph{Port Configuration}
\label{\detokenize{using-standalone-renderers:port-configuration}}
The port configuration section allows to individually set properties for the capture, i.e., input, and the playback, i.e., output, ports of an application.

\sphinxcode{capture}: Specifies that the following options regard the top level component’s capture ports only
\begin{itemize}
\item {} 
\sphinxcode{autoconnect} : Enable/disable auto connection to an external jack client’s input ports, possible values are \sphinxcode{true, false}

\item {} 
\sphinxcode{port}: Jack ports specification
\begin{itemize}
\item {} 
\sphinxcode{basename}: Common name for all top level component’s capture ports

\item {} 
\sphinxcode{indices}:  list of port numbers to append to top level component’s capture port name. It is possible to use Matlab’s colon operator to express a list of numbers in a compact fashion (es.”0:4” means appending numbers 0 to 3 to port names)

\item {} \begin{description}
\item[{\sphinxcode{externalport}: Specification of an external jack client to connect to if \sphinxcode{autoconnect} is enabled.}] \leavevmode\begin{itemize}
\item {} 
\sphinxcode{client}: Name of an external jack client to use as input for our top level component (es. “system”)

\item {} 
\sphinxcode{portname}: Common name for all external jack client input ports

\item {} 
\sphinxcode{indices}: List of port numbers that together with :code:{}` portname{}` describe existing external jack client input ports. It is possible to use Matlab’s colon operator to express a list of numbers.

\end{itemize}

\end{description}

\end{itemize}

\end{itemize}

\sphinxcode{playback}: Specifies that the following options regard the top level component’s playback ports only.
\begin{itemize}
\item {} 
\sphinxcode{autoconnect} : Enable/disable auto connection to an external jack client’s output ports, possible values are \sphinxcode{true, false}

\item {} \begin{description}
\item[{\sphinxcode{port}: Jack ports specification}] \leavevmode\begin{itemize}
\item {} 
\sphinxcode{basename}: Common name for all top level component’s playback ports

\item {} 
\sphinxcode{indices}:  list of port numbers to append to top level component’s playback port name. It is possible to use Matlab’s colon operator to express a list of numbers in a compact fashion (es.”0:4” means appending numbers 0 to 4 to port names)

\item {} \begin{description}
\item[{\sphinxcode{externalport}: Specification of an external jack client to connect to if \sphinxcode{autoconnect} is enabled.}] \leavevmode\begin{itemize}
\item {} 
\sphinxcode{client}: Name of an external jack client to use as output for our top level component (es. “system”)

\item {} 
\sphinxcode{portname}: Common name for all external jack client output ports

\item {} 
\sphinxcode{indices}: List of port numbers that together with :code:{}` portname{}` describe existing external jack client output ports. It is possible to use Matlab’s colon operator to express a list of numbers.

\end{itemize}

\end{description}

\end{itemize}

\end{description}

\end{itemize}


\subparagraph{Simple Example}
\label{\detokenize{using-standalone-renderers:simple-example}}
This configuration example shows how to auto-connect the Jack input and output ports of an application to the default jack client (\sphinxcode{system}), specifying which range of ports to connect.

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{p}{\PYGZob{}}
  \PYG{n+nt}{\PYGZdq{}clientname\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}BaseRenderer\PYGZdq{}}\PYG{p}{,}
  \PYG{n+nt}{\PYGZdq{}autoconnect\PYGZdq{}} \PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}true\PYGZdq{}}\PYG{p}{,}
  \PYG{n+nt}{\PYGZdq{}portconfig\PYGZdq{}}\PYG{p}{:}
  \PYG{p}{\PYGZob{}}
    \PYG{n+nt}{\PYGZdq{}capture\PYGZdq{}}\PYG{p}{:}
    \PYG{p}{\PYGZob{}}
      \PYG{n+nt}{\PYGZdq{}port\PYGZdq{}}\PYG{p}{:}
      \PYG{p}{[}\PYG{p}{\PYGZob{}} \PYG{n+nt}{\PYGZdq{}externalport\PYGZdq{}} \PYG{p}{:} \PYG{p}{\PYGZob{}}\PYG{n+nt}{\PYGZdq{}indices\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}1:4\PYGZdq{}}\PYG{p}{\PYGZcb{}} \PYG{p}{\PYGZcb{}}\PYG{p}{]}
    \PYG{p}{\PYGZcb{}}\PYG{p}{,}
    \PYG{n+nt}{\PYGZdq{}playback\PYGZdq{}}\PYG{p}{:}
    \PYG{p}{\PYGZob{}}
      \PYG{n+nt}{\PYGZdq{}port\PYGZdq{}}\PYG{p}{:}
      \PYG{p}{[}\PYG{p}{\PYGZob{}} \PYG{n+nt}{\PYGZdq{}externalport\PYGZdq{}} \PYG{p}{:} \PYG{p}{\PYGZob{}}\PYG{n+nt}{\PYGZdq{}indices\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}5:8\PYGZdq{}}\PYG{p}{\PYGZcb{}} \PYG{p}{\PYGZcb{}}\PYG{p}{]}
    \PYG{p}{\PYGZcb{}}
  \PYG{p}{\PYGZcb{}}
\PYG{p}{\PYGZcb{}}
\end{sphinxVerbatim}

\begin{figure}[htbp]
\centering
\capstart

\noindent\sphinxincludegraphics[scale=1.0]{{jacksimpleexample}.jpeg}
\caption{Jack audio complex configuration example.}\label{\detokenize{using-standalone-renderers:figure-jack-config-simple-example}}\label{\detokenize{using-standalone-renderers:id2}}\end{figure}


\subparagraph{Complex Example}
\label{\detokenize{using-standalone-renderers:complex-example}}
Follow a more complex example where auto-connection of ports is performed specifying different jack clients and the ranges of ports to be connected are described both for the top level component and for external clients.

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{p}{\PYGZob{}}
  \PYG{n+nt}{\PYGZdq{}clientname\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}VisrRenderer\PYGZdq{}}\PYG{p}{,}
  \PYG{n+nt}{\PYGZdq{}servername\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}\PYGZdq{}}\PYG{p}{,}
  \PYG{n+nt}{\PYGZdq{}autoconnect\PYGZdq{}} \PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}true\PYGZdq{}}\PYG{p}{,}
  \PYG{n+nt}{\PYGZdq{}portconfig\PYGZdq{}}\PYG{p}{:}
  \PYG{p}{\PYGZob{}}
    \PYG{n+nt}{\PYGZdq{}capture\PYGZdq{}}\PYG{p}{:}
    \PYG{p}{\PYGZob{}}
      \PYG{n+nt}{\PYGZdq{}autoconnect\PYGZdq{}} \PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}true\PYGZdq{}}\PYG{p}{,}
      \PYG{n+nt}{\PYGZdq{}port\PYGZdq{}}\PYG{p}{:}
      \PYG{p}{[}
        \PYG{p}{\PYGZob{}}
         \PYG{n+nt}{\PYGZdq{}basename\PYGZdq{}} \PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}Baseinput\PYGZus{}\PYGZdq{}} \PYG{p}{,}
         \PYG{n+nt}{\PYGZdq{}indices\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}0:1\PYGZdq{}}\PYG{p}{,}
         \PYG{n+nt}{\PYGZdq{}externalport\PYGZdq{}} \PYG{p}{:}
          \PYG{p}{\PYGZob{}}
            \PYG{n+nt}{\PYGZdq{}client\PYGZdq{}} \PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}REAPER\PYGZdq{}}\PYG{p}{,}
            \PYG{n+nt}{\PYGZdq{}portname\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}out\PYGZdq{}}\PYG{p}{,}
            \PYG{n+nt}{\PYGZdq{}indices\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}1:2\PYGZdq{}}
          \PYG{p}{\PYGZcb{}}
        \PYG{p}{\PYGZcb{}}\PYG{p}{,}
        \PYG{p}{\PYGZob{}}
         \PYG{n+nt}{\PYGZdq{}basename\PYGZdq{}} \PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}Baseinput\PYGZus{}\PYGZdq{}} \PYG{p}{,}
         \PYG{n+nt}{\PYGZdq{}indices\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}2:3\PYGZdq{}}\PYG{p}{,}
         \PYG{n+nt}{\PYGZdq{}externalport\PYGZdq{}} \PYG{p}{:}
          \PYG{p}{\PYGZob{}}
            \PYG{n+nt}{\PYGZdq{}indices\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}4:5\PYGZdq{}}
          \PYG{p}{\PYGZcb{}}
         \PYG{p}{\PYGZcb{}}
      \PYG{p}{]}
    \PYG{p}{\PYGZcb{}}\PYG{p}{,}
    \PYG{n+nt}{\PYGZdq{}playback\PYGZdq{}}\PYG{p}{:}
    \PYG{p}{\PYGZob{}}
      \PYG{n+nt}{\PYGZdq{}autoconnect\PYGZdq{}} \PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}true\PYGZdq{}}\PYG{p}{,}
      \PYG{n+nt}{\PYGZdq{}port\PYGZdq{}}\PYG{p}{:}
      \PYG{p}{[}\PYG{p}{\PYGZob{}}
        \PYG{n+nt}{\PYGZdq{}basename\PYGZdq{}} \PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}Baseoutput\PYGZus{}\PYGZdq{}} \PYG{p}{,}
        \PYG{n+nt}{\PYGZdq{}indices\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}0:1\PYGZdq{}}\PYG{p}{,}
        \PYG{n+nt}{\PYGZdq{}externalport\PYGZdq{}} \PYG{p}{:}
         \PYG{p}{\PYGZob{}}
          \PYG{n+nt}{\PYGZdq{}client\PYGZdq{}} \PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}system\PYGZdq{}}\PYG{p}{,}
          \PYG{n+nt}{\PYGZdq{}portname\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}playback\PYGZus{}\PYGZdq{}}\PYG{p}{,}
          \PYG{n+nt}{\PYGZdq{}indices\PYGZdq{}}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}4:5\PYGZdq{}}
         \PYG{p}{\PYGZcb{}}
       \PYG{p}{\PYGZcb{}}\PYG{p}{]}
    \PYG{p}{\PYGZcb{}}
  \PYG{p}{\PYGZcb{}}
\PYG{p}{\PYGZcb{}}
\end{sphinxVerbatim}

\begin{figure}[htbp]
\centering
\capstart

\noindent\sphinxincludegraphics[scale=1.0]{{jackexample}.jpeg}
\caption{Jack audio complex configuration example.}\label{\detokenize{using-standalone-renderers:figure-jack-config-complex-example}}\label{\detokenize{using-standalone-renderers:id3}}\end{figure}


\section{Using VISR with Python}
\label{\detokenize{index:using-visr-with-python}}

\section{Using VISR audio workstation plugins}
\label{\detokenize{index:using-visr-audio-workstation-plugins}}

\section{Using Max/MSP externals}
\label{\detokenize{index:using-max-msp-externals}}

\chapter{Extending VISR}
\label{\detokenize{index:extending-visr}}
In this part we describe how to use the VISR framework to implement new functionality, i.e., functionality that is not contained in the existing components or standalone renderers.
This part is basically an extended version of the tutorial presented in


\section{Creating signal flows from existing components in Python}
\label{\detokenize{index:creating-signal-flows-from-existing-components-in-python}}

\section{Writing atomic functionality in Python}
\label{\detokenize{index:writing-atomic-functionality-in-python}}

\section{Implementing atomic components in C++}
\label{\detokenize{index:implementing-atomic-components-in-c}}

\section{Creating composite components in C++}
\label{\detokenize{index:creating-composite-components-in-c}}

\chapter{Object-Based Audio with VISR}
\label{\detokenize{index:object-based-audio-with-visr}}

\section{Overview}
\label{\detokenize{index:overview}}
Although the VISR framework is deliberately application-agnostic, it is well-suited for working with spatial and object-based audio.


\section{The VISR object model}
\label{\detokenize{index:the-visr-object-model}}

\section{Predefined object-based rendering primitives and renderers}
\label{\detokenize{index:id1}}\label{\detokenize{index:predefined-object-based-rendering-primitives-and-renderers}}

\section{Object-Based Reverberation}
\label{\detokenize{index:object-based-reverberation}}\label{\detokenize{index:visr-object-based-audio-reverberation}}

\chapter{VISR component reference}
\label{\detokenize{index:visr-component-reference}}

\section{Standard rendering component library}
\label{\detokenize{index:standard-rendering-component-library}}

\section{Binaural synthesis toolkit}
\label{\detokenize{index:binaural-synthesis-toolkit}}

\section{Dynamic range control library}
\label{\detokenize{index:dynamic-range-control-library}}

\chapter{Old contents}
\label{\detokenize{index:old-contents}}

\section{Examples}
\label{\detokenize{examples:examples}}\label{\detokenize{examples::doc}}

\section{Tutorials}
\label{\detokenize{tutorials::doc}}\label{\detokenize{tutorials:tutorials}}
The contents of these files will be removed or moded to other parts of the documentation.



\renewcommand{\indexname}{Index}
\printindex
\end{document}