Dynamic binaural synthesis rendering component. Optional parts are dashed.

“Installation type” screen of Mac OS X installer. Use “Customize” to get to the component selection.

Offline simulation plots of the proposed panning algorithm: Audio signal.

Offline simulation plots of the proposed panning algorithm: Panning gains.

Offline simulation plots of the proposed panning algorithm: Energy vector direction difference.

Interactive loudspeaker rendering binauralization implemented in Max/MSP using VISR components as externals.

headphones;mobile communication;head motion;headphone-based rendering;headphone-based spatial sound;immersive communication;mobile communications systems;motion-tracked sound;Acoustics;Ear;Headphones;Mathematical model;Mobile communication;Reflection;Spatial coherence;Time frequency analysis

AES69:2015 {AES} standard for file exchange -- {Spatial} acoustic data file format

Binaural room scanning --- A new tool for acoustic and psychoacoustic research

Digital Signal Processing Issues in the Context of Binaural and Transaural Stereophony

Sound Software: Towards Software Reuse in Audio and Music Research

music;software reusability;audio research;music research;software development;software reuse;sound software;Collaboration;Communities;Educational institutions;Multiple signal classification;Software reusability;Training;Programming;Reproducible research;Scientific computing;Software reuse;Software tools

Rotation Matrices for Real Spherical Harmonics. Direct Determination by Recursion

Binaural Simulation of Complex Acoustic Scenes for Interactive Audio

Selection and Interpolation of Head-Related Transfer Functions for Rendering Moving Virtual Sound Sources

Individualization of Dynamic Binaural Synthesis by Real Time Manipulation of {ITD}

audio coding;headphones;DirAC;binaural reproduction;directional audio coding;head related transfer functions;head tracking;headphone reproduction;plausible spatial impression;spatial sound reproduction;Acoustic applications;Acoustic signal processing;Audio coding;Conferences;Frequency;Headphones;Loudspeakers;Microphones;Signal analysis;Signal synthesis;HRTF;Spatial audio;binaural reproduction

Assessing the Plausibility of Non-Individualised Dynamic Binaural Synthesis in a Small Room

Efficient Algorithms and Structures for Fractional Delay Filtering based on {Lagrange} Interpolation

Efficient Frequency-Domain Filter Crossfading for Fast Convolution with Application to Binaural Synthesis

An Audio-Visual System for Object-Based Audio: {From} Recording to Listening

On the Development of a {Matlab}-Based Tool for Real-Time Spatial Audio Rendering

An Impulse Response Dataset for Dynamic Data-Based Auralization of Advanced Sound Systems

{VISR} -- A versatile open software framework for audio signal processing

Ambisonics Encoding of Other Audio Formats for Multiple Listening Conditions

The {NumPy} Array: A Structure for Efficient Numerical Computation

data structures;high level languages;mathematics computing;numerical analysis;Python programming language;high level language;numerical computation;numerical data;numpy array;Arrays;Computational efficiency;Finite element methods;Numerical analysis;Performance evaluation;Resource management;Vector quantization;NumPy;Python;numerical computations;programming libraries;scientific programming

high level languages;Python;high-level language;scientific codes;scientific computing;steering language;Application software;Embedded software;High level languages;Internet;Libraries;Prototypes;Scientific computing;Software standards;Standards development;Writing;Python;computer languages;scientific computing;scientific programming

A framework for efficient and rapid development of cross-platform audio applications

In this article, we present CLAM, a C++ software framework, that offers a complete development and research platform for the audio and music domain. It offers an abstract model for audio systems and includes a repository of processing algorithms and data types as well as all the necessary tools for audio and control input/output. The framework offers tools that enable the exploitation of all these features to easily build cross-platform applications or rapid prototypes for media processing algorithms and systems. Furthermore, included ready-to-use applications can be used for tasks such as audio analysis/synthesis, plug-in development, feature extraction or metadata annotation. CLAM represents a step forward over other similar existing environments in the multimedia domain. Nevertheless, it also shares models and constructs with many of those. These commonalities are expressed in the form of a metamodel for multimedia processing systems and a design pattern language.

{CVXPY}: A {P}ython-Embedded Modeling Language for Convex Optimization

Sparse, {$\ell_{1}$}-Optimal Multi-Loudspeaker Panning and its Relation to Vector Base Amplitude Panning

An Open-Source {C++} Framework for Multithreaded Realtime Multichannel Audio Applications

Dual frequency band amplitude panning for multichannel audio systems

ITU-R BS.1534-3, Method for the subjective assessment of intermediate quality levels of coding systems

This paper presents some syntactical and semantical aspects of FAUST (Functional AUdio STreams), a programming language for real-time sound processing and synthesis. The programming model of FAUST combines two approaches: functional programming and block-diagrams composition. It is based on a block-diagram algebra. It as a well defined formal semantic and can be compiled into efficient C/C++ code.

Virtual Sound Source Positioning Using Vector Base Amplitude Panning

Installation packages can be downloaded from the `S3A software download page <http://s3a-spatialaudio.org>`_ .

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 are available for the following platforms:

Windows (x86_64)
Recent versions (Windows 8 and Windows 10) 64 Bit only

Add a test with the :code:`python_runner` application to check whether the
linked Python library is found and the setting of :code:`PYTHONHOME` is sensible.

 application to check whether the
linked Python library is found and the setting of 

Binary installation packages are the suggested way to uses the VISR framework.
A binary installers enables all uses of the framework, including

Using the Python interfaces and creating new functionality in Python

Creating standalone applications and extension libraries in C++

Building the VISR from source is necessary only in these cases:

- Porting it to a platform where no binary installer exists
- Fixing or changing the internal workings of the framework.

Installation packages are available on the `S3A Software download page <http://s3a-audio.space>`_.

If you plan to use the Python integration of the VISR framework (see :ref:`overview_python_integration`), you need to select an installation package matching the Python version you are using, for example :code:`VISR-X.X.X-python36-Windows.exe`.

If you plan to use the Python integration of the VISR framework (see 

), you need to select an installation package matching the Python version you are using, for example 

The graphical installer is provides as an :code:`.exe` file and provides a dialog-based, component-enables installation.
Figure figure_windows_installer_ shows the component selection dialog of the installer. The choices are detailed below in section :ref:`installation_component_description`.

 file and provides a dialog-based, component-enables installation.
Figure 

 shows the component selection dialog of the installer. The choices are detailed below in section 

.. figure:: ../images/windows_installer.png
   :width: 60 %
   :align: center

   Graphical Windows installer.

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 `Visual C++ downloads page <https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads>`_.

If required, install the “Microsoft Visual C++ Redistributable for Visual Studio 2017”, package,
for example from the 

`Visual C++ downloads page <https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads>`_

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 :code:`PATH` variable.
To this end, open the environment variable editor (Settings -> System -> Advanced system settings -> Environment variables).
The environment variable on Windows 10 is depicted in figure windows_environment_variables_editor .

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 

 variable.

.. figure:: ../images/windows_environment_variables_editor.png

   Environment variable editor on Windows 10.

Append the value :code:`C:\Program Files\VISR-X.X.X\lib;C:\Program Files\VISR-X.X.X\3rd` if the standard installation location was used (Note: Replace :code:`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 :code:`PATH` user variable or the :code:`PATH` system variable.

:code:`C:\Program Files\VISR-X.X.X\lib;C:\Program Files\VISR-X.X.X\3rd`

 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 

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.

Append the path ''<install-directory>/lib'' to the path variable, where ''install_diectory'' is the directory specified during the installation.
For the default path, the setting would be :code:`c:\Program Files\VISR-N.N.N\lib`, where :code:`N.N.N` is replaced by the actual version number.
If the :code:`PATH` variable is edited as a string, subsequent paths are separated by semicolons.

Append the path ‘’<install-directory>/lib’’ to the path variable, where ‘’install_diectory’’ is the directory specified during the installation.
For the default path, the setting would be 

 variable is edited as a string, subsequent paths are separated by semicolons.

Future versions of the installer might adjust the paths automatically.
However, as pointed out in
`NSIS Path manipulation <http://nsis.sourceforge.net/Path_Manipulation>`_,
this needs an extremely cautious implementation to avoid potential damage to users' systems.

`NSIS Path manipulation <http://nsis.sourceforge.net/Path_Manipulation>`_

,
this needs an extremely cautious implementation to avoid potential damage to users’ systems.

,

To use standalone applications (see section :ref:`using_visr_using_standalone_renderers`), it may be useful to add the :code:`bin/` directory to the user or system path.
For the default installation location, add :code:`c:\Program Files\VISR-N.N.N\bin` to the :code:`%PATH%` environment variable.

 directory to the user or system path.
For the default installation location, add 

An installer with a graphical user interface guides through the installation process and allows the selection of optional components.
Figure :ref:`figure_visr_macos_installer` shows a screenshot of this installer.
By default, it installs the VISR into the directory :code:`/Applications/VISR-X.X.X/` where :code:`X.X.X` denotes the version number.

Figure 

 shows a screenshot of this installer.
By default, it installs the VISR into the directory 

.. figure:: ../images/visr_macos_installer.png
   :width: 75 %

   Component-based installer for Mac OS X.

To access the component selection dialog, use the button "Customize" on the "Installation Type" screen (see figure :ref:`figure_visr_macos_installer_customize`)

To access the component selection dialog, use the button “Customize” on the “Installation Type” screen (see figure 

To access the component selection dialog, use the button "Customize" on the "Installation Type" screen (see figure 

.. figure:: ../images/visr_macos_installer_customize.png

   "Installation type" screen of Mac OS X installer. Use "Customize" to get to the component selection.

"Installation type" screen of Mac OS X installer. Use "Customize" to get to the component selection.

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

to the file :code:`$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 :ref:`installation_python_setup_configuration`.

.
If you need this path also from applications that are not started from a shell, we recommend the solution used in section 

For Linux, installation packages are provided as *.deb* (Debian) packages.
At the moment, this package is monolithic, i.e., it contains all components.
They are installed via the command

 (Debian) packages.

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

With the dialog-based, component-enabled installers, parts of the framework can be chosen depending on the intended use of the framework.

Shared Libraries
The core VISR libraries. This component is mandatory and cannot be unselected.

Standalone applications.
Renderers and small tools to be run as command-line applications.

Python externals
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).

Python Packages
VISR extensions implemented in Python. This group of components requires the component "Python externals".

VISR extensions implemented in Python. This group of components requires the component “Python externals”.

Development files
Header files and CMake build support - Needed to extend the VISR with components using C++ or use the framework in external C++ applications.

Loudspeaker configurations
A set of standard loudspeaker configuration files and additional example files from actual locations.

Python templates
A set of commented template files for different types of VISR components.

Documentation
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.

As explained in section :ref:`overview_python_integration`, the Python integration is an optional, albeit central, part of the VISR framework that enables a number of its functionalities, for example:

, the Python integration is an optional, albeit central, part of the VISR framework that enables a number of its functionalities, for example:

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

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

Depending on the system, we suggest different Python distributions:

We recommend `Anaconda <https://www.anaconda.com/download/>`_. Please make sure you install the  Python3 / 64-Bit variant.

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

Some Mac OS variants (for example 10.12) come with a pre-installed Python 3 variant in 

.
In this case, care must be taken that it does not interferes with the chosen Python distribution. In particular, the 

Two environment variables must be set to ensure the working of the VISR Python subsystem.

:code:`PYTHONPATH` This variable is used to add the directory containing the VISR python modules to the system path.
To this end, the :code:`python/` subdirectory of the installation folder must be added to :code:`PYTHONPATH`.

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

.. code-block:: Python

   import sys
   sys.path.append( '<visr_installation_dir>/python' )

However, we recommend setting :code:`PYTHONPATH` and assume this in the examples throughout this document.

 This variable is used to add the directory containing the VISR python modules to the system path.
To this end, the 

PYTHONHOME
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, :code:`python_runner` standalone application (section ??), or the :code:`visr_renderer` with metadata processing enabled. (see section :ref:`using_visr_using_standalone_renderers_visr_renderer`).

This variable has to be set to the root directory of the Python distribution, i.e.,
one level of hierarchy above the :code:`bin/` folder conatining the Python interpreter.
Depending on the platform and the distribution, the correct value might be:

Windows with Anaconda
  :code:`C:\ProgramData\Anaconda3`
Mac OS X with Anaconda
  `$HOME/anaconda3/`
Linux
  :code:`/usr`

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

If the Python distribution provides a :code:`python-config` or :code:`python3-config` binary, the command

.. code-block:: bash

  python-config --prefix

or

  python3-config --prefix

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

Strictly speaking, this variable is required only if VISR Python code is executed from a C++ application, for instance some DAW plugins, 

one level of hierarchy above the 

 folder conatining the Python interpreter.

 is not necessary in most cases, because there is only the system-provided Python installation available.

OPENBLAS_NUM_THREADS
It is advisable, in many cases, to set the value of this environment variable to 1. It controls how :code:`numpy` numerical algebra functions are distributed to multiple CPU cores.
:code:`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:

  OPENBLAS_NUM_THREADS = 1

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

It is advisable, in many cases, to set the value of this environment variable to 1. It controls how 

 numerical algebra functions are distributed to multiple CPU cores.

 is used by the VISR Python integration as well as in many Python-based VISR components performing mathematical or DSP operations.

Depending on the operating system, these variables can be set as follows:

Linux
Append the lines

  export PYTHONPATH=$PYTHONPATH:/usr/share/visr/python
  export OPENBLAS_NUM_THREADS=1

to :code:`$HOME/.profile`.

export PYTHONPATH=$PYTHONPATH:/usr/share/visr/python
export OPENBLAS_NUM_THREADS=1

Windows
Add :code:`PYTHONPATH` entries either as a user or system variable as described in :ref:`installation_windows` section.
The corrects setting are (assuming the default installation directory and the Anaconda distribution):

  PYTHONPATH=c:\Program Files\VISR-X.X.X\python
  PYTHONHOME=c:\ProgramData\Anaconda3
  OPENBLAS_NUM_THREADS=1

Note that if there is already a :code:`PYTHONPATH` variable, the recommended value should be appended, using a semicolon as a separator.

 section.

PYTHONPATH=c:\Program Files\VISR-X.X.X\python
PYTHONHOME=c:\ProgramData\Anaconda3
OPENBLAS_NUM_THREADS=1

 variable, the recommended value should be appended, using a semicolon as a separator.

Mac OS X
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 :code:`launchd` property list file, as detailed, e.g., in this `StackExchange thread <https://apple.stackexchange.com/questions/106355/setting-the-system-wide-path-environment-variable-in-mavericks>`_.

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 

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

The :code:`VISR-X.X.X.plist` will have this contents:

.. code-block:: xml

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
    <key>Label</key>
    <string>my.startup</string>
    <key>ProgramArguments</key>
    <array>
      <string>sh</string>
      <string>-c</string>
      <string>
      launchctl setenv PYTHONPATH /Applications/VISR-X.X.X/python
      launchctl setenv OPENBLAS_NUM_THREADS 1
      launchctl setenv PYTHONHOME <BASE_DIRECTORY_OF_PYTHON_INSTALLATION>
      </string>
    </array>
    <key>RunAtLoad</key>
    <true/>
   </dict>
   </plist>

By convention, these files are stored in :code:`/Users/<loginname>/Library/LaunchAgents/`.
To activate the settings, call

  launchctl load <path-to-file>/VISR-X.X.X.plist

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:

  .. code-block:: bash

    launchctl unload <path-to-file>/VISR-X.X.X.plist

If you made changes to the settings, you have to perform the :code:`unload` command followed by a :code:`load`.

 directory first. Please check the values in this file first and adjust them accordingly.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
 <key>Label</key>
 <string>my.startup</string>
 <key>ProgramArguments</key>
 <array>
   <string>sh</string>
   <string>-c</string>
   <string>
   launchctl setenv PYTHONPATH /Applications/VISR-X.X.X/python
   launchctl setenv OPENBLAS_NUM_THREADS 1
   launchctl setenv PYTHONHOME <BASE_DIRECTORY_OF_PYTHON_INSTALLATION>
   </string>
 </array>
 <key>RunAtLoad</key>
 <true/>
</dict>
</plist>

We suggest some basic tests to verify that the VISR framework has been correctly installed and configured.

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 ``Standalone applications`` must have been selected in order to perform this check.

When using the component-enabled installers, the component 

In a terminal (Linux shell, Mac OS Terminal application, Windows command line :code:`cmd`),
execute this command:

In a terminal (Linux shell, Mac OS Terminal application, Windows command line 

For the different platforms, the full commands are (assuming the default installation directory)
Windows

  "c:\Program Files\VISR-X.X.X\bin\matrix_convolver.exe" --version

Note that the quotes are necessary to cope with the space in the path.

If you added the :code:`bin/` directory as described above, calling

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 :code:`PATH` variable needs to be set accordingly.

In particular this applies Windows, where the 

Hyperlink target "windows-environment-variables-editor" is not referenced.

Hyperlink target "figure-visr-macos-installer" is not referenced.

Hyperlink target "figure-visr-macos-installer-customize" is not referenced.

Hyperlink target "installation-component-description" is not referenced.

Hyperlink target "visr-installation-setting-up-python" is not referenced.

Hyperlink target "installation-python-setup-configuration" is not referenced.

This test ensures that the VISR framework can be used interactively from Python interpreters.

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

, respectively

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

The directory of the resulting file path should be :code:`<visr-installation-dir>/python`.
For example, on Windows this returns :code:`C:\Program Files\VISR 0.10.0\\python\\visr.pyd`.

Although the VISR framework is deliberately application-agnostic, it is well-suited for working with spatial and object-based audio.
This is due to a number of reasons:

The focus on multichannel audio makes it suitable for object-based audio, which often features complex sound scenes consisting of many signals, as well as multichannel reproduction systems.

The ability to handle complex, also structure parameter data allows for the generation and transmission of object metadata within the system.

The modular, reusable component structure fosters the creation of complex signal flows that are often used in object-bases audio.

Last but not least, the VISR framework was conceived in the `S3A project <http://www.s3a-spatialaudio.org>`_ a research project on spatial and object-based audio.

Consequently the VISR framework contains different types of functionality to support processing of object-based audio.
These are typically implemened as libraries, for example component libraries.

.. figure:: ../images/visr_object_based_object_model_hierarchy.png
   :width: 70%

   Object types and hierarchy.

The VISR object model supports a hierarchical and extensible set of object types.
These types and their relations are shown above.

where :code:`<object k>` stands for the encoding of a single object. The objects can be arranged in arbitary order as long as the object ids are unique. Moreover, the object vector can be split into arbitrary subsets and be transmitted as individual :code:`"objects"` messages.

 stands for the encoding of a single object. The objects can be arranged in arbitary order as long as the object ids are unique. Moreover, the object vector can be split into arbitrary subsets and be transmitted as individual 

:code:`Object` is the base type of all objects. Therefore, the attributes are common to all objects.
The following attributes are supported:

 is the base type of all objects. Therefore, the attributes are common to all objects.

:code:`"id"`
The object id, a nonnegative integer that must be unique withing the object vector (mandatory attribute).

:code:`"group"`
The group id, a nonnegative integer (mandatory attribute). Not used in the core renderer, but potentially in the metadata adaptation process.

:code:`"channels"`
A list of audio channel indices referencing the audio signals associated with this object. The list is formed as a string consisting of comma-separated unsigned integers enclosed in quotation marks, e.g., "0,3, 5, 7 " with arbitrary amounts of whitespace in between. The format also allows Matlab-style ranges for any part of the list. For instance, "0, 2 : 2 : 8, 10" is equivalent to "0,2,4,6,8,10". This is a mandatory argument. The reuired number of channels is typically determined by the object type and its parameters. For instance, point source objects are invariably single-channel, while the number of required channels of a HOA object depends on the Ambisonics order specified by the "order" of this object.

A list of audio channel indices referencing the audio signals associated with this object. The list is formed as a string consisting of comma-separated unsigned integers enclosed in quotation marks, e.g., “0,3, 5, 7 ” with arbitrary amounts of whitespace in between. The format also allows Matlab-style ranges for any part of the list. For instance, “0, 2 : 2 : 8, 10” is equivalent to “0,2,4,6,8,10”. This is a mandatory argument. The reuired number of channels is typically determined by the object type and its parameters. For instance, point source objects are invariably single-channel, while the number of required channels of a HOA object depends on the Ambisonics order specified by the “order” of this object.

:code:`"level"`
The level of the audio object in linear scale as a floating-point number. Note that this value does not necessarily denote the loudness of the reproduced object, since the latter also depends on the level of the audio signal(s). (Mandatory argument).

:code:`"priority"`
The priority of the object given as an unsigned integer (mandatory argument). Lower numbers represent higher priority, with "0" being the highest prority. Not currently used in the core renderer, but potentially (and moe appropriately) in the metadata processing.

The priority of the object given as an unsigned integer (mandatory argument). Lower numbers represent higher priority, with “0” being the highest prority. Not currently used in the core renderer, but potentially (and moe appropriately) in the metadata processing.

:code:`"eq"`
An array of parametric EQ parameters to be applied to all audio signals for this object. This is an optional attribute, if not present, a 'flat', i.e., unity-gain equalisation curve is applied. The attribute has the format

An array of parametric EQ parameters to be applied to all audio signals for this object. This is an optional attribute, if not present, a ‘flat’, i.e., unity-gain equalisation curve is applied. The attribute has the format

: The number of admissible EQ sections is renderer-dependent. Providing more EQ parameters for a single object than supported by the renderer might result in an error message and termination of the renderer. If less EQ parameters are sent than supported by the renderer, the remaining EQ sections are padded with 'flat' characteristics. The individual EQ section have the form

: The number of admissible EQ sections is renderer-dependent. Providing more EQ parameters for a single object than supported by the renderer might result in an error message and termination of the renderer. If less EQ parameters are sent than supported by the renderer, the remaining EQ sections are padded with ‘flat’ characteristics. The individual EQ section have the form

{ "type": "<type>", "f": (center/cutoff frequency), "q": (quality) [, "gain": (dB) }

:code:`"type"`
A type string chosen from the following values: :code:`"lowpass"`, :code:`"highpass"`, :code:`"bandpass"`, :code:`"bandstop"`, :code:`"peak"`, :code:`"lowshelf"`, :code:`"highshelf"`, :code:`"allpass"`.

:code:`"f"`
Centre/cutoff frequency in Hz (depending on the filter type).

:code:`"gain"`
Optional gain parameter (in dB). If not provided, the default value of 0 dB is used. Only used by the filter types :code:`"peak"`, :code:`"lowshelf"`, and :code:`"highshelf"`. The filter characteristics follow the `Audio EQ Cookbook formulas <http://www.musicdsp.org/files/Audio-EQ-Cookbook.txt>`_.

Optional gain parameter (in dB). If not provided, the default value of 0 dB is used. Only used by the filter types 

`Audio EQ Cookbook formulas <http://www.musicdsp.org/files/Audio-EQ-Cookbook.txt>`_

Point sources are invariable single-channel objects, that is the :code:`"channels"` attribute of the base type :code:`Object` must contain a single channel index.
The type string is :code:`"point"`.

Point sources are invariable single-channel objects, that is the 

The point source coordinates sre specified in the :code:`"position"`, which is an object holding either Cartesian coordinates :code:`"x"`, :code:`"y"`, and :code:`"z"` or spherical coordinates :code:`"az"`, :code:`"el"`, :code:`"radius"`

{ "id": "5", "channels": "2", "type": "point", "group": "2", "priority": "0", "level": "0.350",
  "position": {"x": "3.0", "y": "-0.5", "z": "0.25" } }

  "position": {"az": "30", "el": "15.0", "radius": "1.25" } }

Plane waves differ from point sources that they do not exhibit distance-dependent attenuation and do not provide parallalax effects for moving listener positions. Because the main reproduction method in the VISR renderer at the moment is VBAP, plane waves are handled identically to point sources. This might change for alternative reproduction methods, including listener position adaptive VBAP.

Plane waves use the type :code:`"plane"` and are single-channel objects.

The plane wave representation uses an object :code:`"direction"` containing the attributes :code:`"az"` and :code:`"el"` to describe azimuth and elevation of the direction of the impinging source. The third parameter :code:`"refDist"` (reference distance) encodes the relative timing of the object's audio signal: A value of 0 means that a sound event at signal time 0 is perceived at the central listener at time 0.

 to describe azimuth and elevation of the direction of the impinging source. The third parameter 

 (reference distance) encodes the relative timing of the object’s audio signal: A value of 0 means that a sound event at signal time 0 is perceived at the central listener at time 0.

 (reference distance) encodes the relative timing of the object's audio signal: A value of 0 means that a sound event at signal time 0 is perceived at the central listener at time 0.

{"id": 5, "channels": 5, "type": "plane", "group": 0, "priority": 0, "level": 1.000000, "direction": {"az": 30.0, "el": 45.0, "refdist": 12.00 } }

Point source with diffuseness are derived from PointSource and therefore support all attributes of the latter.
In addition they define the attribute :code:`"diffuseness"` that is a floating-point supposed to be in the range between 0.0 and 1.0 and describes the amount of diffuse energy relative to the point source radiation.

In addition they define the attribute 

 that is a floating-point supposed to be in the range between 0.0 and 1.0 and describes the amount of diffuse energy relative to the point source radiation.

They are single-channel and use the type string :code:`"pointdiffuse"`.

{"id": "5", "channels": "5", "type": "pointdiffuse", "group": "0", "priority": "0",
 "level": "1.0", "diffuseness": "0.35", "position": {"x": "3.0", "y": "-0.5", "z": "0.25" } }

This source type describes a surrounding objects reproducing decorrelated signals obtained from the single object audio signal.

This object does not introduce any other attributes apart from those inherited from the base class Object. The type string is :code:`"diffuse"`.

This object does not introduce any other attributes apart from those inherited from the base class Object. The type string is 

{"id": 3, "channels": 3, "type": "diffuse", "group": 0, "priority": 0, "level": 1.000000}

This source type represents a Ambisonics sound field of arbitrary order. It is a multichannel object where the number of channels depends on the Ambisonics order :math:`N`: :math:`ch=(N+1)^{2}`. The audio signals (as indexed by the :code:`"channels"` attribute, are expected to be in ACN channel order http://ambisonics.ch/standards/channels/.

This source type represents a Ambisonics sound field of arbitrary order. It is a multichannel object where the number of channels depends on the Ambisonics order 

{"type": "hoa", "channels": "0:8", "group": 0, "id": 0, "level": 1, "order": 2, "priority": 0},

Channel objects are audio signals that are routed directly to a loudspeaker (or group of loudspeakers) specified by an id.

This type is derived from :code:`Object` and adds the :code:`"outputChannels"` attribute. This attribute is a string contains a list of loudspeaker ids (i.e., labels).
Channel objects can contain an arbitrary number of channels. The :code:`outputChannels` must contain an entry for each channel. This can be either a single label or a list of labels enclosed in square brackets.
In the latter case, the respective channel is routed to the list of loudspeakers.

 attribute. This attribute is a string contains a list of loudspeaker ids (i.e., labels).
Channel objects can contain an arbitrary number of channels. The 

 must contain an entry for each channel. This can be either a single label or a list of labels enclosed in square brackets.

An :code:`diffuseness` attribute controls the level of decorrelation applied, from 0.0 (no decorrelation) to 1.0 (fully replayed to the decorrelation filters). OPtional attribute, default is 0.0.

 attribute controls the level of decorrelation applied, from 0.0 (no decorrelation) to 1.0 (fully replayed to the decorrelation filters). OPtional attribute, default is 0.0.

If a channel is routed to more than one loudspeaker, the levels of these loudspeakers are normalised using the same norm as the respective panner (VBAP, VBIP in case of separate high-frequency panning, or diffuse panning).

{"id": 2, "channels": "3", "type": "channel", "group": 0, "priority": 0, "level": 0.50000, "diffuseness": 0.5,
  "outputChannels": "M+030"} ]

 "outputChannels": "[M+030]"} ]

 "outputChannels": "[M+030, M-030]"} ]

{ "id": 2, "channels": "4:8", "type": "channel", "group": 0, "priority": 0,
  "level": 0.350000, "diffuseness": 0.25,
  "outputChannels": "M+000, [M+030], [M-030, U+030], U+110"}]

PointSourceWithReverb is a single-channel object that adds reverb to a PointSource. It uses the type string :code:`"pointreverb"`.
In addition to the Object and PointSource properties it defines an attribute "room" containing the objects :code:`"ereflect"` (early reflections) and :code:`"lreverb"` (late reverberation). :code:`"ereflect"` is an array of early reflection objects, consisting of IIR coefficients (:code:`"biquadsos"`, a point source position :code:`"position"` using the same format as in :code:`PointSource`, and additional level and delay information.

PointSourceWithReverb is a single-channel object that adds reverb to a PointSource. It uses the type string 

.
In addition to the Object and PointSource properties it defines an attribute “room” containing the objects 

.
In addition to the Object and PointSource properties it defines an attribute "room" containing the objects 

 is an array of early reflection objects, consisting of IIR coefficients (

The maximum number of discrete reflections per reverb object is a configuration parameter of the renderer.

The :code:`"lreverb"` object contains parameter data in fixed frequency bands that are used to synthesize reverb tails.

 object contains parameter data in fixed frequency bands that are used to synthesize reverb tails.

{ "type": "pointreverb", "channels": "4", "group": 0, "id": 1,"level": 1,
  "position": {"x": 1.5, "y": 0.0, "z": 0.0}, "priority": 0,
  "room": {
  "ereflect": [{"biquadsos": [{"a0": "1.00000e+00", "a1": "-1.05734e+00", "a2": "5.69314e-01",
                               "b0": "3.87648e-01", "b1": "0.00000e+00", "b2": "0.00000e+00"},
                              ( more biquad coefficients)
                              {"a0": "1.00000e+00", "a1": "-7.20132e-02", "a2": "6.48827e-01",
                               "b0": "1.00000e+00", "b1": "0.00000e+00", "b2": "0.00000e+00"}],
                "delay": "0.00931", "level": "0.0603584806", "position": {"az": 337.0, "el": "-1.00000", "refdist": "1.00000"} },
              ( more early reflections )
            ],
"lreverb": {"attacktime": "0.01321, 0.01321, 0.01321, 0.01321, 0.01321, 0.01321, 0.01321, 0.01321, 0.01321",
            "decayconst": "-4.50698, -5.02028, -5.75817, -5.36509, -5.42654, -5.62316, -5.75298, -6.41075, -11.13465",
            "level": "0.02522, 0.01052, 0.01657, 0.02744, 0.02058, 0.01679, 0.01698, 0.01433, 0.00041", "delay": "0.00931" } }

The default component library contains numerous atomic components for object-based audio as well as ready-made rendering signal flows.

The loudspeaker renderers are described in Section :ref:`using_visr_using_standalone_renderers_visr_renderer`.

This section will describe the support for object-based reverberation in the VISR renderers.
This is based on the reverb object :cite:`coleman2017reverb` using the object representation described in Section :ref:`visr_object_model_reverb_object`.
The functionality is contained in the library :code:`reverbobject` and the corresponding Python module :py:mod:`reverbobject`.

This is based on the reverb object 

Loudspeaker configurations are used to tell a renderer about the loudspeaker positions
and other properties of the setup.
It is used primarily in the loudspeaker renderers, including binaural renderering that use a virtual loudspeaker setup internally.

This section describes the format of a loudspeaker configuration and explains the helper functions provided with a VISR installation to create configuration files.

<panningConfiguration>
  <loudspeaker id="M+000" channel="1" eq="highpass">
    <cart x="1.0" y="0.0" z="0"/>
  </loudspeaker>
  <loudspeaker id="M-030" channel="2" eq="highpass">
    <polar az="-30.0" el="0.0" r="1.0"/>
  <loudspeaker id="M+030" channel="3" eq="highpass">
    <polar az="30.0" el="0.0" r="1.0"/>
  <loudspeaker id="M-110" channel="4" eq="highpass">
    <polar az="-110.0" el="0.0" r="1.0"/>
  <loudspeaker id="M+110" channel="5" eq="highpass">
    <polar az="110.0" el="0.0" r="1.0"/>
  <loudspeaker id="U-030" channel="6" eq="highpass">
    <polar az="-30.0" el="30.0" r="1.0"/>
  <loudspeaker id="U+030" channel="7" eq="highpass">
    <polar az="30.0" el="30.0" r="1.0"/>
  <loudspeaker id="U-110" channel="8" eq="highpass">
    <polar az="-110.0" el="30.0" r="1.0"/>
  <loudspeaker id="U+110" channel="9" eq="highpass">
    <polar az="110.0" el="30.0" r="1.0"/>
  <virtualspeaker id="VoS">
    <polar az="0.0" el="-90.0" r="1.0"/>
    <route lspId="M+000" gainDB="-13.9794"/>
    <route lspId="M+030" gainDB="-13.9794"/>
    <route lspId="M-030" gainDB="-13.9794"/>
    <route lspId="M+110" gainDB="-13.9794"/>
    <route lspId="M-110" gainDB="-13.9794"/>
  </virtualspeaker>
  <triplet l1="VoS" l2="M+110" l3="M-110"/>
  <triplet l1="M-030" l2="VoS" l3="M-110"/>
  <triplet l1="M-030" l2="VoS" l3="M+000"/>
  <triplet l1="M-030" l2="U-030" l3="M+000"/>
  <triplet l1="M+030" l2="VoS" l3="M+000"/>
  <triplet l1="M+030" l2="VoS" l3="M+110"/>
  <triplet l1="U+030" l2="U-030" l3="M+000"/>
  <triplet l1="U+030" l2="M+030" l3="M+000"/>
  <triplet l1="U-110" l2="M-030" l3="U-030"/>
  <triplet l1="U-110" l2="M-030" l3="M-110"/>
  <triplet l1="U+110" l2="U-110" l3="M-110"/>
  <triplet l1="U+110" l2="M+110" l3="M-110"/>
  <triplet l1="U+030" l2="U-110" l3="U-030"/>
  <triplet l1="U+030" l2="U+110" l3="U-110"/>
  <triplet l1="U+030" l2="U+110" l3="M+110"/>
  <triplet l1="U+030" l2="M+030" l3="M+110"/>
  <subwoofer assignedLoudspeakers="M+000, M-030, M+030, M-110, M+110, U-030, U+030, U-110, U+110"
          channel="10" delay="0" eq="lowpass" gainDB="0"
          weights="1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0"
          />
  <outputEqConfiguration numberOfBiquads="1" type="iir">
      <filterSpec name="lowpass">
         <biquad a1="-1.9688283" a2="0.96907117" b0="6.0729856e-05" b1="0.00012145971" b2="6.0729856e-05"/>
      </filterSpec>
      <filterSpec name="highpass">
         <biquad a1="-1.9688283" a2="0.96907117" b0="-0.98447486" b1="1.9689497" b2="-0.98447486"/>
  </outputEqConfiguration>
</panningConfiguration>

The VISR package comes with a number of preconfigured loudspeaker configurations.
They are contained in the directory :code:`$VISR_ROOT/config/`.

They are contained in the directory 

The subdirectory :code:`config/generic` contains standard configurations, mainly from the `ITU-R BS2051 standard <https://www.itu.int/rec/R-REC-BS.2051/en>`_.

`ITU-R BS2051 standard <https://www.itu.int/rec/R-REC-BS.2051/en>`_

For all configurations, versions with and without subwoofer channels are provided. The version with subwoofer has
no suffix, the version without has :code:`-no-subwoofer` appended to the file name.
In general, the version with subwoofer should be preferred and the generated loudspeaker outputs are identical.
The output channel mapping is identical for both cases. In some cases the subwoofer channels are embedded
into the block of loudspeaker output channels. In the corresponding configurations without subwoofer, these
channels are not used.

no suffix, the version without has 

 appended to the file name.

For the stereo configuration, an additional configuration :code:`bs2051-0+2+0-rear-fading.xml` is provided in
which sound sources are faded out as they approach :math:`180^{\circ}`. In all other cases, the energy from virtual loudspeakers (as denoted in the table above) is distributed to neighboring real loudspeakers.

 is provided in
which sound sources are faded out as they approach 

. In all other cases, the energy from virtual loudspeakers (as denoted in the table above) is distributed to neighboring real loudspeakers.

The subdirectories :code:`config/isvr`, :code:`config/surrey`, and :code:`config/bbc` contain examples of actual listening rooms.
The functions to generated these configurations are contained in the subdirectories :code:`scripts/` within these folders.

 contain examples of actual listening rooms.
The functions to generated these configurations are contained in the subdirectories 

To ease the creation of generation functions, the VISR framework provides several Python functions
to create the XML configuration files from a number of loudspeaker coordinates and additional optional parameters.
These functions are contained in the Python module :code:`loudspeakerconfig`.
If the VISR framework was installed through a binary installer and Python was configured as described in :ref:`installation_python_setup_configuration`, then the package can be directly imported, e.g.,

These functions are contained in the Python module 

.
If the VISR framework was installed through a binary installer and Python was configured as described in 

import loudspeakerconfig
loudspeakerconfig.createArrayConfigFile( ... )

The main function in this module is :code:`createArrayConfigFile()`.
It takes a set of loudspeaker coordinates, an output file name, and a large set of additional options:

.

createArrayConfigFile(outputFileName, lspPositions, twoDconfig=False, sphericalPositions=False, channelIndices=None, loudspeakerLabels=None, triplets=None, distanceDelay=False, distanceAttenuation=False, lspDelays=None, lspGainDB=None, eqConfiguration=None, virtualLoudspeakers=[], subwooferConfig=[], comment=None, speedOfSound=340.0)

outputFileName, lspPositions, twoDconfig=False, sphericalPositions=False, channelIndices=None, loudspeakerLabels=None, triplets=None, distanceDelay=False, distanceAttenuation=False, lspDelays=None, lspGainDB=None, eqConfiguration=None, virtualLoudspeakers=[], subwooferConfig=[], comment=None, speedOfSound=340.0

outputFileName (string) -- The file name of the XML file to be written. This can be a file name or path.
The file extension (typically .xml) must be provided by the user.

The file name of the XML file to be written. This can be a file name or path.

lspPositions (array-like, 3xL or 2xL, where L is the number of loudspeakers.) -- Provide the loudspeaker in Cartesian coordinates, relative to the centre of the array.

Provide the loudspeaker in Cartesian coordinates, relative to the centre of the array.

twoDconfig (bool, optional) -- Whether the loudspeaker configuration is 2D or 3D (default). In the former case, the lspPositions
parameter does not need to have a third row, and it is ignored if present. If twoDconfig if True,
then the loudspeaker coordinates in the do not have an "z" or "el" coordinate. Likewise,
the triangulation "triplets" consist only of two loudspeakers.

Whether the loudspeaker configuration is 2D or 3D (default). In the former case, the lspPositions
then the loudspeaker coordinates in the do not have an “z” or “el” coordinate. Likewise,
the triangulation “triplets” consist only of two loudspeakers.

sphericalPositions (bool, optional) -- Specify whether the loudspeaker and virtual loudspeaker positions are written in spherical (True)
or Cartesian coordinates (False). Default is Cartesian.

Specify whether the loudspeaker and virtual loudspeaker positions are written in spherical (True)

channelIndices (array-like, optional) -- A list of output integer channel indices, one for each real loudspeaker. Optional argument, if not provided, consecutive indices starting from 1 are assigned. If provided, the length of the array must match the number of real loudspeakers, and indices must be unique.

A list of output integer channel indices, one for each real loudspeaker. Optional argument, if not provided, consecutive indices starting from 1 are assigned. If provided, the length of the array must match the number of real loudspeakers, and indices must be unique.

loudspeakerLabels (array-like, optional) -- A list of strings containing alphanumerical labels for the real loudspeakers.
Labels must be unique, consist of the characters 'a-zA-Z0-9&()+:_-', one for
each real loudspeaker. The labels are used to reference loudspeakers in triplets,
virtual loudspeaker routings, and subwoofer configs.
Optional parameter. If not provided, labels of the form 'lsp_i' with i=1,2,...
are generated.

A list of strings containing alphanumerical labels for the real loudspeakers.
Labels must be unique, consist of the characters ‘a-zA-Z0-9&()+:_-‘, one for
Optional parameter. If not provided, labels of the form ‘lsp_i’ with i=1,2,…

Labels must be unique, consist of the characters 'a-zA-Z0-9&()\+:_-', one for

triplets (array-like, optional.) -- A loudspeaker triangulation. To be provided as a list of arrays consisting of three
(or two in case of a 2D configuration) loudspeaker labels. Labels must match
existing values of the loudspeakerLabels  parameter.
Optional parameter, to be provided only in special cases. By default, the
triangulation is computed internally.

A loudspeaker triangulation. To be provided as a list of arrays consisting of three

distanceDelay (bool, optional) -- Whether the loudspeaker signals are delayed such that they arrive simultaneously in the array centre.
This can be used if the loudspeaker distances to the centre ar not equal. In this case
the farthest loudspeaker gets a delay of 0 s, and closer loudpeakers a positive delay.
The distance compensation delay is added to the lspDelays parameter (if present).
Optional attribute. The default (False) means no distance attenuation is used.

Whether the loudspeaker signals are delayed such that they arrive simultaneously in the array centre.
The distance compensation delay is added to the 

 parameter (if present).

distanceAttenuation (bool, optional) -- Whether the loudspeaker gains shall be scaled if the loudspeaker distances are not 1.0.
In this case, a 1/r distance law is applied such that the farthest loudspeaker
gets a scaling factor of 0 dB, and lower factors are assigned to loudspeakers closer to the centre.
The gain factors are applied on top of the optional parameter lspGainDB, if present.
Optional attribute. Default is False (no distance attenutation applied)

Whether the loudspeaker gains shall be scaled if the loudspeaker distances are not 1.0.
The gain factors are applied on top of the optional parameter 

, if present.

lspDelays (array-like, optional) -- An array of delay values to be applied tothe loudspeakers. Values are to be provided in seconds.
If not provided, no delays are applied. If specified, the length of the array must match the
number of real loudspeakers.

An array of delay values to be applied tothe loudspeakers. Values are to be provided in seconds.

lspGainDB (array-like, optional.) -- An array of gain values (in dB) to adjust the output gains of the real loudpeakers.
If provided, the length must match the number of real loudspeakers.
By default, no additional gains are applied.

An array of gain values (in dB) to adjust the output gains of the real loudpeakers.

virtualLoudspeakers (array of dicts, optional) -- Provide a set of additional virtual/phantom/dead/imaginary loudspeaker nodes to adjust the triangulation of the array. Each entry is a dict consisting of the following key-value pairs."id": A alphanumeric id, following the same rules as the loudspeaker indices. Must be unique across all real and imaginary loudspeakers.

"pos": A 3- or vector containing the position in Cartesian coordinates. 2 elements are allowed for 2D setups.

"routing": Specification how the panning gains calculated for this loudspeaker are distributed to neighbouring real loudspeakers. Provided as a list of tuples (label, gain), where label is the id of a real loudspeaker and gain is a linear gain value. Optional element, if not given, the energy of the virtual loudspeaker is discarded.Optional argument. No virtual loudspeakers are created if not specified.

Provide a set of additional virtual/phantom/dead/imaginary loudspeaker nodes to adjust the triangulation of the array. Each entry is a dict consisting of the following key-value pairs.

"id": A alphanumeric id, following the same rules as the loudspeaker indices. Must be unique across all real and imaginary loudspeakers.

”id”: A alphanumeric id, following the same rules as the loudspeaker indices. Must be unique across all real and imaginary loudspeakers.

”pos”: A 3- or vector containing the position in Cartesian coordinates. 2 elements are allowed for 2D setups.

"routing": Specification how the panning gains calculated for this loudspeaker are distributed to neighbouring real loudspeakers. Provided as a list of tuples (label, gain), where label is the id of a real loudspeaker and gain is a linear gain value. Optional element, if not given, the energy of the virtual loudspeaker is discarded.

”routing”: Specification how the panning gains calculated for this loudspeaker are distributed to neighbouring real loudspeakers. Provided as a list of tuples (label, gain), where label is the id of a real loudspeaker and gain is a linear gain value. Optional element, if not given, the energy of the virtual loudspeaker is discarded.

Optional argument. No virtual loudspeakers are created if not specified.

eqConfiguration (array of structures (dicts), optional) -- Define a set of EQ filters to be applied to loudspeaker and subwoofer output channels. Each entry of the list is a dict containing the following key-value pairs."name": A unique, nonempty id that is referenced in loudspeaker and subwoofer specifications.

"filter": A list of biquad definitions, where each element is a dictionary containing the keys 'b' and 'a' that represent the numerator and denominator of the transfer function. 'b' must be a 3-element numeric vector, and 'a' a three- or two-element numeric vector. In the latter case, the leading coefficient is assumed to be 1, i.e., a normalised transfer function.

"loudspeakers": A list of loudspeaker labels (real loudspeakers) to whom the eq is applied.

Define a set of EQ filters to be applied to loudspeaker and subwoofer output channels. Each entry of the list is a dict containing the following key-value pairs.

"name": A unique, nonempty id that is referenced in loudspeaker and subwoofer specifications.

”name”: A unique, nonempty id that is referenced in loudspeaker and subwoofer specifications.

”filter”: A list of biquad definitions, where each element is a dictionary containing the keys ‘b’ and ‘a’ that represent the numerator and denominator of the transfer function. ‘b’ must be a 3-element numeric vector, and ‘a’ a three- or two-element numeric vector. In the latter case, the leading coefficient is assumed to be 1, i.e., a normalised transfer function.

”loudspeakers”: A list of loudspeaker labels (real loudspeakers) to whom the eq is applied.

subwooferConfig (array of dicts, optional) -- A list of subwoofer specifications, where each entry is a dictionary with the following key-value pairs:"name": A string to name the subwoofer. If not provided, a default name will be generated.

"channel": An output channel number for the subwoofer signal. Must be unique across all loudspeakers and subwoofers.

"assignedSpeakers": A list of ids of (real) loudspeakers. The signals of these loudspeakers are used in the computation of the subwoofer signal.

"weights": An optional weighting applied to the loudspeaker signals of the the assigned loudspeakers. If provided, it must be an array-like sequence with the same length as assignedSpeakers. If not given, all assigned speakers are weighted equally with factor "1.0".

A list of subwoofer specifications, where each entry is a dictionary with the following key-value pairs:

"name": A string to name the subwoofer. If not provided, a default name will be generated.

”name”: A string to name the subwoofer. If not provided, a default name will be generated.

”channel”: An output channel number for the subwoofer signal. Must be unique across all loudspeakers and subwoofers.

”assignedSpeakers”: A list of ids of (real) loudspeakers. The signals of these loudspeakers are used in the computation of the subwoofer signal.

”weights”: An optional weighting applied to the loudspeaker signals of the the assigned loudspeakers. If provided, it must be an array-like sequence with the same length as assignedSpeakers. If not given, all assigned speakers are weighted equally with factor “1.0”.

comment (string, optional) -- Optional string to be written as an XML comment at the head of the file.

Optional string to be written as an XML comment at the head of the file.

createArrayConfigFile( 'bs2051-4+5+0.xml',
                       lspPositions = lspPos,
                       twoDconfig = False,
                       sphericalPositions=True,
                       channelIndices = [1, 2, 3, 5, 6, 7, 8, 9, 10],
                       loudspeakerLabels =  ["M+030", "M-030", "M+000", "M+110", "M-110",
                          "U+030", "U-030", "U+110", "U-110"  ],
                       virtualLoudspeakers = [ { "id": "VotD", "pos": [0.0, 0.0,-1.0],
                                            "routing": [ ("M+030", 0.2), ("M-030", 0.2),
                                             ("M+000", 0.2), ("M+110", 0.2), ("M-110", 0.2) ] }]

The function `createArrayConfigFromSofa()` can be used to create configuration files from a SOFA file to be used, for example in a virtual loudspeaker renderer (:py:class:`visr_bst.VirtualLoudspeakerRenderer`):

 can be used to create configuration files from a SOFA file to be used, for example in a virtual loudspeaker renderer (

createArrayConfigFromSofa(sofaFile, xmlFile=None, lspLabels=None, twoDSetup=False, virtualLoudspeakers=[])

sofaFile, xmlFile=None, lspLabels=None, twoDSetup=False, virtualLoudspeakers=[]

Create a loudspeaker configuraton file from a SOFA file containing a number of emitters representing loudspeakers.

xmlFile (string, optional) -- Path of the XML output file to be written.
Optional argument, if not provided, the SOFA file path is used with the extension replaced by ".xml"

Path of the XML output file to be written.
Optional argument, if not provided, the SOFA file path is used with the extension replaced by “.xml”

lspLabels (list of strings, optional) -- List of loudspeaker labels, must match the number of emitters in the SOFA files.
If not provided, numbered labels are automatically generated.

List of loudspeaker labels, must match the number of emitters in the SOFA files.

twoDSetup (bool, optional) -- Flag specifying whether the aray is to be considered plane (True) or 3D (False).
Optional value, dafault is False (3D).

Flag specifying whether the aray is to be considered plane (True) or 3D (False).

virtualLoudspeakers (list, optional) -- A list of virtual loudspeakers to be added to the setup. Each entry must be a Python dict as decribed
in the function loudspeakerconfig.createArrayConfigFile().

A list of virtual loudspeakers to be added to the setup. Each entry must be a Python dict as decribed
in the function 

The root node of the XML file is :code:`<panningConfiguration>`.
This root element supports the following optional attributes:

:code:`isInfinite`
Whether the loudspeakers are regarded as point sources located on the unit sphere (:code:`false`) or as plane waves, corresponding to an infinite distance (:code:`true`). The default value is :code:`false`.

Whether the loudspeakers are regarded as point sources located on the unit sphere (

:code:`dimension`
Whether the setup is considered as a 2-dimensional configuration (value :code:`2`) or as three-dimensional (:code:`3`, thedefault). In the 2D case, the array is considered in the x-y plane , and the :code:`z` or :code:`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).

Whether the setup is considered as a 2-dimensional configuration (value 

, thedefault). In the 2D case, the array is considered in the x-y plane , and the 

 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 :code:`<panningConfiguration>` root element, the following elements are supported:

:code:`<loudspeaker>`
Represents a reproduction loudspeaker.
The position  is encoded either in a :code:`<cart>` node representing the cartesian coordinates in the :code:`x`, :code:`y` and :code:`z` attributes (floating point values in meter), or a :code:`<polar>` node with the attributes :code:`az` and :code:`el` (azimuth and elevation, both in degree) and :code:`r` (radius, in meter).

The :code:`<loudspeaker>` nodes supports for a number of attributes:

* :code:`id` A mandatory, non-empty string identification for the loudspeaker, which must be unique across all :code:`<loudspeaker>` and :code:`<virtualspeaker>` (see below) elements.
  Permitted are alpha-numeric characters, numbers, and the characters "@&()+/:_-".
  ID strings are case-sensitive.
* :code:`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..
* :code:`gainDB` or :code:`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.  :code:`gainDB` or :code:`gain` are mutually exclusive.
* :code:`delay` Delay adjustment to be applied to this loudspeaker as a floating-point value in seconds. The default value is  0.0).
* :code:`eq` An optional output equalisation filter to be applied for this loudspeaker.
  Specified as a non-empty string that needs to match an :code:`filterSpec` element in the :code:`outputEqConfiguration`
  element (see below). If not given, no EQ is applied to for this loudspeaker.

The position  is encoded either in a 

:code:`id` A mandatory, non-empty string identification for the loudspeaker, which must be unique across all :code:`<loudspeaker>` and :code:`<virtualspeaker>` (see below) elements.
Permitted are alpha-numeric characters, numbers, and the characters "@&()+/:_-".
ID strings are case-sensitive.

 A mandatory, non-empty string identification for the loudspeaker, which must be unique across all 

 (see below) elements.
Permitted are alpha-numeric characters, numbers, and the characters “@&()+/:_-“.

:code:`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..

 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..

:code:`gainDB` or :code:`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.  :code:`gainDB` or :code:`gain` are mutually exclusive.

 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.  

:code:`delay` Delay adjustment to be applied to this loudspeaker as a floating-point value in seconds. The default value is  0.0).

 Delay adjustment to be applied to this loudspeaker as a floating-point value in seconds. The default value is  0.0).

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

 An optional output equalisation filter to be applied for this loudspeaker.
Specified as a non-empty string that needs to match an 

:code:`<virtualspeaker>`
An additional vertex added to the triangulation that does not correspond to a physical loudspeaker. Consist of a numerical :code:`id` attribute and a position specified either as a :code:`<cart>` or a :code:`<polar>` node (see :code:`<loudspeaker>` specification).

The :code:`<virtualspeaker>` node provides the following configuration options:

* A mandatory, nonempty and unique attribute :code:`id` that follows the same rules as for the :code:`<loudspeaker>` elements.
* A number of :code:`route` sub-elements that specify how the energy from this virtual loudspeaker is routed to real loudspeakers.
  The :code:`route` element has the following attributes:
  * :code:`lspId`: The ID of an existing real loudspeaker.
  * :code:`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

  .. code-block:: xml

     <virtualspeaker id="VoS">
      <polar az="0.0" el="-90.0" r="1.0"/>
      <route lspId="M+000" gainDB="-13.9794"/>
      <route lspId="M+030" gainDB="-13.9794"/>
      <route lspId="M-030" gainDB="-13.9794"/>
      <route lspId="M+110" gainDB="-13.9794"/>
      <route lspId="M-110" gainDB="-13.9794"/>
    </virtualspeaker>

  That means that the energy of the virtual speaker :code:`"vos"` is routed to five surrounding speakers, with a scaling factor of 13.97 dB each.

An additional vertex added to the triangulation that does not correspond to a physical loudspeaker. Consist of a numerical 

A mandatory, nonempty and unique attribute :code:`id` that follows the same rules as for the :code:`<loudspeaker>` elements.

A number of :code:`route` sub-elements that specify how the energy from this virtual loudspeaker is routed to real loudspeakers.
The :code:`route` element has the following attributes:
* :code:`lspId`: The ID of an existing real loudspeaker.
* :code:`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

   <virtualspeaker id="VoS">

That means that the energy of the virtual speaker :code:`"vos"` is routed to five surrounding speakers, with a scaling factor of 13.97 dB each.

 sub-elements that specify how the energy from this virtual loudspeaker is routed to real loudspeakers.
The 

: A scaling factor with which the gain of the virtual loudspeaker is distributed to the real loudspeaker.

 <virtualspeaker id="VoS">
  <polar az="0.0" el="-90.0" r="1.0"/>
  <route lspId="M+000" gainDB="-13.9794"/>
  <route lspId="M+030" gainDB="-13.9794"/>
  <route lspId="M-030" gainDB="-13.9794"/>
  <route lspId="M+110" gainDB="-13.9794"/>
  <route lspId="M-110" gainDB="-13.9794"/>
</virtualspeaker>

 is routed to five surrounding speakers, with a scaling factor of 13.97 dB each.

:code:`<subwoofer>` Specify a subwoofer channel. In the current implementation, the loudspeaker are weighted and mixed into an arbitray number of subwoofer channels. The attributes are:

 Specify a subwoofer channel. In the current implementation, the loudspeaker are weighted and mixed into an arbitray number of subwoofer channels. The attributes are:

:code:`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:

   assignedLoudspeakers = "1, 3,4,5:7, 2, 8:-3:1"

 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.

:code:`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 :code:`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".

 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 

 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”.

:code:`gainDB` or :code:`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 :code:`weight` attributes to the summed subwoofer signal. See the :code:`<loudspeaker>` specification.

 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 

:code:`delay` Delay adjustment for this (floating-point value in seconds, default 0.0). See the :code:`<loudspeaker>` specification.

 Delay adjustment for this (floating-point value in seconds, default 0.0). See the 

:code:`<triplet>`
Loudspeaker triplet specified by the attributes :code:`l1`, :code:`l2`, and :code:`l3`.
The values of :code:`l1`, :code:`l2`, and :code:`l3` must correspond to IDs of existing real or virtual loudspeakers.
In case of a 2D setup, only :code:`l1` and :code:`l2` are evaluated.

.. 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.

 must correspond to IDs of existing real or virtual loudspeakers.
In case of a 2D setup, only 

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.

:code:`outputEqConfiguration`
This optional element must occur at most once.
It provides a global specification for equalisation filters for loudspeakers and subwoofers.

   <outputEqConfiguration  type="iir" numberOfBiquads="1">
     <filterSpec name="lowpass">
       <biquad a1="-1.9688283" a2="0.96907117" b0="6.0729856e-05" b1="0.00012145971" b2="6.0729856e-05"/>
     </filterSpec>
     <filterSpec name="highpass">
       <biquad a1="-1.9688283" a2="0.96907117" b0="-0.98447486" b1="1.9689497" b2="-0.98447486"/>
   </outputEqConfiguration>

The  attributes are:

* :code:`type`: The type of the output filters. At the moment, only IIR filters provide as second-order sections (biquads) are supported. Thus, the value :code:`"iir"` must be set.
* :code:`numberOfBiquads`: This value is specific to the :code:`"iir"` filter type.

The filters are described in :code:`filterSpec` elements.
These are identifed by a :code:`name` attribute, which must be an non-empty string unique across all :code:`filterSpec` elements.
For the type :code:`iir`, a :code:`filterSpec` element consists of at most :code:`numberOfBiquad` nodes of type :code:`biquad`, which represent the coefficients of one second-order IIR (biquad) section.
This is done through the attributes :code:`a1`,  :code:`a2`, :code:`b0`, :code:`b1`, :code:`b2` that represent the coefficients of the normalised transfer function

.. math::

   H(z) = \frac{ b_0 + b_1 z^{-1} + b_{2}z^{-2} }{1 + a_1 z^{-1} + a_{2}z^{-2}}

<outputEqConfiguration  type="iir" numberOfBiquads="1">
  <filterSpec name="lowpass">
    <biquad a1="-1.9688283" a2="0.96907117" b0="6.0729856e-05" b1="0.00012145971" b2="6.0729856e-05"/>
  </filterSpec>
  <filterSpec name="highpass">
    <biquad a1="-1.9688283" a2="0.96907117" b0="-0.98447486" b1="1.9689497" b2="-0.98447486"/>
</outputEqConfiguration>

:code:`type`: The type of the output filters. At the moment, only IIR filters provide as second-order sections (biquads) are supported. Thus, the value :code:`"iir"` must be set.

: The type of the output filters. At the moment, only IIR filters provide as second-order sections (biquads) are supported. Thus, the value 

:code:`numberOfBiquads`: This value is specific to the :code:`"iir"` filter type.

 attribute, which must be an non-empty string unique across all 

, which represent the coefficients of one second-order IIR (biquad) section.
This is done through the attributes 

 that represent the coefficients of the normalised transfer function

H(z) = \frac{ b_0 + b_1 z^{-1} + b_{2}z^{-2} }{1 + a_1 z^{-1} + a_{2}z^{-2}}

Unexpected possible title overline or transition.
Treating it as ordinary text because it's so short.

Treating it as ordinary text because it’s so short.

Hyperlink target "visr-object-model-reverb-object" is not referenced.

Hyperlink target "visr-object-based-audio-reverberation" is not referenced.

Hyperlink target "loudspeaker-configuration-file-format" is not referenced.

Depending on the object type, either Cartesian and spherical coordinates are use. The coordinate axes follow, e.g., the ITU-R BS.2051 conventions.

The azimuth angle is measured counterclockwise from the x axis (front).

The elevation angle is measure up (positive values) or down (negative values) from the horizontal plane.

Coordinates are represented in the JSON format in degree (this does not necessarily hold for the internal representation in the renderer).

Setting up a build environment, including the required software tools, and compiling the source code is detailed in the `VISR API documentation <http://s3a-spatialaudio.org>`_.

Setting up a build environment, including the required software tools, and compiling the source code is detailed in the 

Alternatively, the VISR framework can be installed and build from source code.
It is hosted at the GitLab repository https://gitlab.eps.surrey.ac.uk:s3a/VISR.git

It is hosted at the GitLab repository 

Decide whether the additional paths shall be appended or prepended to the system path.
In the latter case, this could avoid loading another module of the same name by prioritizing the explicitly added paths.

These search paths can be used to locate the module containing the component to be run, unless
a directory path is passed to the :code:`--module-name` option.
In addition, the search paths are evaluated to locate transitive dependencies of the module to be loaded.
For example, the path to VISR Python externals can be specidied in this way, thus avoiding the use of
the :code:`PYTHONPATH` environment variable, as described in section
:ref:`installation_python_setup_configuration`.
The additional search paths are added to the Python search path :code:`sys.path` before the main
module specified by the :code:`-m` option is loaded.

a directory path is passed to the 

 option.
the 

.
The additional search paths are added to the Python search path 

This argument is optional, no additional search paths are added if the option is not provided.

:code:`--module-search-path` or :code:`-d`:
Specifies additional search paths for Python modules.

To be specified as a comma-separeted list of directory path.

.. todo:: Decide whether the additional paths shall be appended or prepended to the system path.
          In the latter case, this could avoid loading another module of the same name by prioritizing the explicitly added paths.

:code:`--module-name` or :code:`-m`:
Specify the name of a Python module that contains the VISR component to be executed.
That is, use the module name that would need to be imported in an interactive Python session.
The module name must be provided without the file extension.
It can be specified either with a full file path, or as a pure module name.
In the latter case, the directory containing the module must be on the Python module search
path or included in the :code:`--module-search-path` option.

The module can be in one of several forms:

* A Python file (normally with extension :code:`.py`) that contains the component class.
  The module name must be specified without the extension.
* A directory containing a multi-file package.
* Compiled extension modules implemented in C++. Typical file extesnions are :code:`.so`
  (Linux and Mac OS X) or :code:`.pyc` (Windows). The module name must be specified without the extension.

This is a mandatory argument.

path or included in the 

A Python file (normally with extension :code:`.py`) that contains the component class.
The module name must be specified without the extension.

) that contains the component class.

Compiled extension modules implemented in C++. Typical file extesnions are :code:`.so`
(Linux and Mac OS X) or :code:`.pyc` (Windows). The module name must be specified without the extension.

Compiled extension modules implemented in C++. Typical file extesnions are 

 (Windows). The module name must be specified without the extension.

:code:`--python-class-name` or :code:`-c`:
The name of the Python class to be instantiated, without the leading namespace name.
This class must be derived from :code:`visr.Component`
and must be defined in the module :code:`module-name`.

.. note:: At the moment, only classes in the top-level namespace are supported.
          That is, classes of the form :code:`moduleName.submodule.className` cannot be used.

This argument is mandatory.

This class must be derived from 

At the moment, only classes in the top-level namespace are supported.
That is, classes of the form :code:`moduleName.submodule.className` cannot be used.

That is, classes of the form 

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 :ref:`installation_component_description`), then the component "Standalone applications" has to be selected during installation.

), then the component “Standalone applications” has to be selected during installation.

), 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.

All standalone applications provided with the VISR provide a common set of command line options:

**--version** or **-v**
Returns a short description of the tool and its version information.

**--help** or **-h**
Returns a list of supported command line options with brief descriptions.

**--option-file <filename>** or **@<filename>**
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

   -i 2
   -o 2
   -f 48000
   -c "/usr/share/visr/config/generic/stereo.xml"

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

-i 2
-o 2
-f 48000
-c "/usr/share/visr/config/generic/stereo.xml"

**--sampling-frequency** or **-f**
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.

**--period** or **-p**
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.

In most cases, the period should be a power of 2, e.g., 64, 128, 256, 512, …, 4096.

**--audio-backend** or **-D**
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 **"PortAudio"** (all platforms) and **"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.

The audio interfaces depend on the operating system and the configuration of the user’s system. The most common options are 

The audio interfaces depend on the operating system and the configuration of the user's system. The most common options are 

 (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.

**-audio-ifc-options**
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 (`JavaScript Object Notation <https://www.json.org/>`_) 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:

   visr_renderer ... -audio-ifc-options='{ \"hostapi\": \"WASAPI\" }'

Section :ref:`using_visr_using_standalone_renderers_specific_audio_options` below explains the options for the currently supported audio interfaces.

visr_renderer ... -audio-ifc-options='{ \"hostapi\": \"WASAPI\" }'

 below explains the options for the currently supported audio interfaces.

**-audio-ifc-option-file**
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 **portaudio_options.cfg** as

.. code-block:: json

   {
     "hostapi": "WASAPI"
   }

and passed as

   visr_renderer ... -audio-ifc-option-file=portaudio_options.cfg

For example, the option shown above could be specified in a file 

The options **--audio-ifc-options** and **--audio-ifc-option-file** are mutually
exclusive, that means other none or one of them can be provided.

 are mutually

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 :ref:`the_visr_object_model`.

They use the VISR audio object model and the corresponding JSON format described in Section 

Object-based rendering requires audio scenes consisting of audio objects, that is, audio and corresponding
object metadata.
The audio signals have to be provided to the input of the audio interface used by the renderer.
The object metadata has to be sent as a stream of UDP messages.

The VISR framework does not provide a graphical user interface to generate object metadata.
We recommend using thehttps://www.reaper.fm>`_.
Section "TODO: Insert name here" of the `VISR production suite User Manual <http://cvssp.org/data/s3a/public/VISRPluginSuite/html/index.html>`_
describes how to configure these plugins with an external renderer.

Section “TODO: Insert name here” of the 

Section "TODO: Insert name here" of the 

`VISR production suite User Manual <http://cvssp.org/data/s3a/public/VISRPluginSuite/html/index.html>`_

There are two binaries for loudspeaker rendering: **visr_renderer** and **baseline_renderer**.
The provision of these separate binaries has technical reasons - mainly their dependency on a compatible and configured Python installation, as explained below.

.

*visr_renderer*
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 **--metadapter-config** is specified.
The binary itself, however, needs a Python istallation to start at all, irrespective whether this option is set.

This metadapter is integrated into the rendering binary as an optional part, and is used if the option 

 is specified.

*baseline_renderer*
This is the legacy object-based loudspeaker renderer. At the time being, it provides the same functionality as the **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.

This is the legacy object-based loudspeaker renderer. At the time being, it provides the same functionality as the 

,
In this way, the binary is independent of a Python distribution on the user’s computer.

,

In general, we recommend to use **visr_renderer** if possible, and to use **baseline_renderer** on systems where the Python features
of the VISR framework are not available.

 on systems where the Python features

The command line arguments supported by the **visr_renderer** application are:

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

The arguments for the **baseline_renderer** application are identical, except that the :code:`--metadapter-config` option is not supported as explained above.

:code:`--audio-backend` or :code:`-D`
The audio interface library to be used. See section :ref:`using_standalone_renderers_common_options`.

:code:`--audio-ifc-options`:
Audio-interface specific options, section :ref:`using_standalone_renderers_common_options`.

:code:`--audio-ifc-option-file`:

:code:`--sampling-frequency` or :code:`-f`:
Sampling frequency in Hz. Default: 48000 Hz. See section :ref:`using_standalone_renderers_common_options`.

:code:`--period` or :code:`-p`:
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`.

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 

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 

:code:`--array-config` or :code:`-c`:
File path to the loudspeaker configuration file. Path might be relative to the current working directory. Mandatory argument.
The XML file format is described in Section :ref:`loudspeaker_configuration_file_format`.

The XML file format is described in Section 

:code:`--input-channels` or :code:`-i`:
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 :code:`.xml` triggers the use of the XML format for parsing.

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 

:code:`--output-channels` or :code:`-o`:
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.

:code:`--object-eq-sections`:
The number of EQs (biquad sections) that can be specified for each object audio signal.

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

:code:`--low-frequency-panning`:
Switches the loudspeaker panning between standard VBAP and a dual-frequency approach with separate low- and high-frequency panning rules.

Admissible values are :code:`true` and :code:`false`. The default value is :code:`false`, corresponding
to the standard VBAP algorithm.

:code:`--reverb-config`:
A set of options for the integrated reverberation engine for the RSAO (:code:`PointsourceWithReverb`) object (see section :ref:`visr_object_based_audio_reverberation`).
To be passed as a JSON string. The supported options are:

:code:`numReverbObjects`:
  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.

:code:`lateReverbFilterLength`:
  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.

:code:`lateReverbDecorrelationFilters`:
  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.

:code:`discreteReflectionsPerObject`:
  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.

:code:`maxDiscreteReflectionDelay`:
  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.

:code:`lateReverbFilterUpdatesPerPeriod`
  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

  .. todo: Decide wehether the default value should mean that all changes should be applied instantaneously.

An example configuration is:

.. code:: bash

   --reverb-config='{ \"numReverbObjects\": 5, \"lateReverbFilterLength\": 4.0,
              \"lateReverbDecorrelationFilters\": "/home/af5u13/tmp/decorr.wav\",
              \"discreteReflectionsPerObject\": 10 }'

A set of options for the integrated reverberation engine for the RSAO (

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.

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.

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.

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.

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.

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

.. todo: Decide wehether the default value should mean that all changes should be applied instantaneously.

todo: Decide wehether the default value should mean that all changes should be applied instantaneously.

--reverb-config='{ \"numReverbObjects\": 5, \"lateReverbFilterLength\": 4.0,
           \"lateReverbDecorrelationFilters\": "/home/af5u13/tmp/decorr.wav\",
           \"discreteReflectionsPerObject\": 10 }'

'{ \"numReverbObjects\": 5, \"lateReverbFilterLength\": 4.0,

:code:`--tracking`
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: :code:`{ "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:

=============  ======================================================  ============  =======
ID             Description                                             Unit          Default
port           UDP port number                                         unsigned int  8888
position.x     x position of the tracker                               m             2.08
position.y     y position of the tracker                               m             0.0
position.z     z position of the tracker                               m             0.0
rotation.rotX  rotation the tracker about the x axis, i.e., y-z plane  degree        0.0
rotation.rotY  rotation the tracker about the y axis, i.e., z-x plane  degree        0.0
rotation.rotZ  rotation the tracker about the z axis, i.e., x-y plane  degree        180

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: 

:code:`{ "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 } }"`

{ "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 option parsing for :code:`--tracking` not supported yet, default values are used invariably. To activate tracking, you need to specify the  :code:`--tracking` option with an arbitrary parameter (even  :code:`--tracking=false` would activate the tracking.

 not supported yet, default values are used invariably. To activate tracking, you need to specify the  

:code:`--scene-port`
The UDP network port which receives the scene data in the VISR JSON object format.

:code:`--metadapter-config`
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 **baseline_renderer** application.

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.

$> matrix_convolver --help
-D [ --audio-backend ] arg      The audio backend. JACK_NATIVE activates the
                                native Jack driver insteat of the PortAudio
                                implementation.
--list-audio-backends           List the supported audio backends that can be
                                passed to the the "--audio-backend" ("-D")
                                option.
--list-fft-libraries            List the supported FFT implementations that
                                can be selected using the "--fftLibrary"
                                option.
-p [ --period ] arg             Period (block length): The number of samples
                                per audio block, also the block size of the
                                partitioned convolution.
                                signal.
-o [ --output-channels ] arg    Number of audio output channels.
--filters arg                   Initial impulse responses, specified as
                                comma-separated list of one or multiple WAV
                                files.
--filter-file-index-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.
-r [ --routings ] arg           Initial routing entries, expects a JSON array
                                consisting of objects "{"inputs": nn,
                                "outputs":nn, "filters":nn ("gain":XX)
-l [ --max-filter-length ] arg  Maximum length of the impulse responses, in
                                samples. If not given, it defaults to the
                                longest provided filter,
--max-routings arg              Maximum number of filter routings.
--max-filters arg               Maximum number of impulse responses that can
                                be stored.
--fft-library arg               Specify the FFT implementation to be used.
                                Defaults to the default implementation for
                                the platform.

A set of **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.

, 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.

This interface allows for several different operation modes, for example:

Multi-channel filtering where each input is filtered with one filter to give produce the same number of output channels.

Filtering to produce multiple, different copies of the same input signal.

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

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

MIMO filtering with sparse matrices, corresponding to sophisticated routings between inputs and outputs.

:code:`--version` or :code:`-v`  :
Standard options, described in :ref:`using_standalone_renderers_common_options`

:code:`--option-file`:

:code:`--audio-backend` or :code:`-D`:

:code:`--sampling-frequency` or :code:`-f`

The number of input channels. Must not exceed the number of capture channels of the sound card.

:code:`-o` or :code:`--output-channels`:
The number of output channels. Must be less or equal than the number of sound card output channels.

:code:`--filters`
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 :code:`filters` argument is not provided, then the option :code:`max-routings` must be provided.

This argument is optional. If not provided, all filters are zero-initialised. Note that if the 

:code:`--filter-file-index-offsets`
Specify the start filter index for each WAV file specified by the :code:`--filters` argument.
To be provided as a comma-separated list of nonnegative filter entries, one for each file in the :code:`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:

   --filters ="filters_2ch.wav, filters_6ch.wav, filters_4ch.wav"
   --filter-file-index-offsets="2, 8, 16"

Here, three WAV files are provided: :code:`filters_2ch.wav`, :code:`filters_6ch.wav`, and :code:`filters_4ch.wav`, with 2, 6, and 4 channels respectively.
The filter offsets "2, 8, 16" mean that the filters of :code:`filters_2ch.wav` will be associated to the indices 2 and 3, that of :code:`filters_6ch.wav` by indices 8-13, and that of :code:`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 >=20) will be zero-initialised.

If the :code:`--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.

Specify the start filter index for each WAV file specified by the 

 argument.
To be provided as a comma-separated list of nonnegative filter entries, one for each file in the 

 argument.

--filters ="filters_2ch.wav, filters_6ch.wav, filters_4ch.wav"
--filter-file-index-offsets="2, 8, 16"

, with 2, 6, and 4 channels respectively.
The filter offsets “2, 8, 16” mean that the filters of 

The filter offsets "2, 8, 16" mean that the filters of 

 hadn’t been provided in this example, the start offsets for the filter sets from the three files would have been 0,2,8.

 hadn't been provided in this example, the start offsets for the filter sets from the three files would have been 0,2,8.

:code:`--routings` or :code:`-r`
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

   { "input": "<i>", "output": "<o>", "filter": "<f>", "gain": "<g>" }

Here, :code:`<i>` is the index of the input channel, :code:`<o>` is the channel index of the output, and :code:`<f>` is the index of the filter (see above).
All indices are zero-offset.
The gain specification :code:`,"gain": <g>` is optional, with :code:`<g>` representing a linear-scale gain value.

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

   [{"input":"0", "output":"0", "filter":"2" },
    {"input":"0", "output":"1", "filter":"1" },
    {"input":"0", "output":"2", "filter":"0" }]

A routing entry can define multiple multiple routings using a Matlab-like stride syntax for :code:`<i>`, :code:`<o>`, :code:`<f>`, 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

   {"input":"3", "output":"0:3:9", "filter":"1" }

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

   {"input":"0", "output":"0:2", "filter":"2:-1:0" }

is equivalent to the routing list shown above.

{ "input": "<i>", "output": "<o>", "filter": "<f>", "gain": "<g>" }

 is the index of the filter (see above).
The gain specification 

[{"input":"0", "output":"0", "filter":"2" },
 {"input":"0", "output":"1", "filter":"1" },
 {"input":"0", "output":"2", "filter":"0" }]

A routing entry can define multiple multiple routings using a Matlab-like stride syntax for 

, or several of them.

:code:`--max-filter-length` or :code:`-l`:
Define the maximum length of the FIR filters.
If the :code:`--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 :code:`--filters` and :code:`--max-filter-length` are both provided, then an error is generated if the length of any specified filter exceeds the value of :code:`--max-filter-length`.

 option is provided, this argument is optional. In this case, admissible filter length is set to the largest length of all specified filter.
If 

 are both provided, then an error is generated if the length of any specified filter exceeds the value of 

:code:`--max-routings` :
Define the maximum number of routings.
If the :code:`--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 :code:`--routing` argument.
If :code:`routings` and :code:`--max-routings` are both specified, the number of entries in :code:`--routings` must not exceed the value of :code:`--max-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 

:code:`--max-filters`:
Define the maximum number of filter entries.
This parameter is optional if the argument :code:`--filters` is provided. In this case, the maximum filter number is set to the number of filters generated by the  :code:`--filters` argument.

.. note:: If combined with :code:`--filter-file-index-offsets`, this automatically computed number of filters includes any gaps in the generated filter set.

If :code:`--filters` and :code:`max-filters` are both provided, then the number of filter entries created by :code:`--filters` must not exceed
the value of :code:`--max-filters`.

This parameter is optional if the argument 

 is provided. In this case, the maximum filter number is set to the number of filters generated by the  

If combined with :code:`--filter-file-index-offsets`, this automatically computed number of filters includes any gaps in the generated filter set.

, this automatically computed number of filters includes any gaps in the generated filter set.

 are both provided, then the number of filter entries created by 

:code:`--fft-library`:
Select a FFT implementation from the set of available FFT libraries.
The admissible values (strings) can be obtained through the :code:`--list-fft-libraries` option.

The admissible values (strings) can be obtained through the 

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 :code:`--max-routings` or :code:`--max-filters` that are larger than the currently set values.

Examples include the ability to provide empty routings, zero-valued filters, or to specify values for 

$> matrix_convolver -i 2 -o 2 -p 512 -D PortAudio -f 48000 --filters="filters.wav"
  -r '[ {\"input\": \"0:1\", \"output\":\"0:1\", \"filter\":\"0:1\"}]'

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.

$> matrix_convolver -i 9 -o 2 --max-filters=18 --max-routings=18
   -r "[{\"input\":\"0:8\", \"output\":\"0\", \"filter\":\"0:2:16\"},
        {\"input\":\"0:8\", \"output\":\"1\", \"filter\":\"1:2:17\"}]"
   --filters="bbcrdlr9ch_brirs.wav"
   -D Jack -f 48000 -p 512

Here, the file :code:`bbcrdlr9ch_brirs.wav` contains the 18 BRIRs, with the first nine channels for the left and the remaining channels for the right ear filters.

 contains the 18 BRIRs, with the first nine channels for the left and the remaining channels for the right ear filters.

This standalone application is an alternative way to run arbitrary VISR components in real-time.

Compared to instantiating the processing from a Python interpreter, this can be easier to control, for example within  a script or when running a device in 'headless mode'.

Compared to instantiating the processing from a Python interpreter, this can be easier to control, for example within  a script or when running a device in ‘headless mode’.

For obvious reasons, this application requires an installed and correctly configured Python distribution, as described in Section :ref:`installation_python_setup_configuration`.

For obvious reasons, this application requires an installed and correctly configured Python distribution, as described in Section 

The supported options are displayed when started with the :code:`--help` or :code:`-h` option:

$> python_runner --help
  -h [ --help ]                     Show help and usage information.
  -v [ --version ]                  Display version information.
  --option-file arg                 Load options from a file. Can also be used
                                    with syntax "@<filename>".
  -D [ --audio-backend ] arg        The audio backend.
  -f [ --sampling-frequency ] arg   Sampling frequency [Hz]
  -p [ --period ] arg               Period (blocklength) [Number of samples per
                                    audio block]
  -m [ --module-name ] arg          Name of the Python module to be loaded
                                    (without path or extension).
  -c [ --python-class-name ] arg    Name of the Python class (must be a
                                    subclass of visr.Component).
  -n [ --object-name ] arg          Name of the Python class (must be a
  -a [ --positional-arguments ] arg Comma-separated list of positional options
                                    passed to the class constructor.
  -k [ --keyword-arguments ] arg    Comma-separated list of named (keyword)
                                    options passed to the class constructor.
  -d [ --module-search-path ] arg   Optional path to search for the Python
                                    module (in addition to the default search
                                    path (sys.path incl. $PYTHONPATH). Provided as a
                                    comma-separated list of directories.
  --audio-ifc-options arg           Audio interface optional configuration.
  --audio-ifc-option-file arg       Audio interface optional configuration file.

If the processing is correctly started, a message is displayed on the command line:

To terminate the :code:`python_runner`, press the "q" key followed by <Return>.

On Linux and Mac OS X, the standard program termination via <Ctrl-C> does not work at the moment.
Instead, this key combination is ignored, and Python exception message is shown if the program is
later terminated via "q<Return>".
See issue https://gitlab.eps.surrey.ac.uk/s3a/VISR/issues/23 .

later terminated via “q<Return>”.
See issue 

See issue 

The standard options :code:`--help`, :code:`--version`, :code:`--audio-backend`, :code:`sampling-frequency`, `:code:`--period`, `:code:`--audio-ifc-options`, and `:code:`--audio-ifc-option-file` are described in Section :ref:`using_standalone_renderers_common_options`.

In this example we use a simple Python-based VISR component :code:`PythonAdder`.

class PythonAdder( visr.AtomicComponent ):
  """ General-purpose add block for an arbitrary number of inputs"""
  def __init__( self, context, name, parent, numInputs, width ):
  ...

that implements generic addition with :code:`numInputs` signals to be added with
:code:`width` signals each.
Here, the component class :code:`PythonAdder` is contained in a source file :code:`pythonAtoms.py`.

The :code:`python_runner` can be invoked using positional arguments through

$> python_runner -D PortAudio -f 48000 -p 512
    -m $HOME/VISR/src/python/scripts/pythonAtoms -c PythonAdder -a "3,2"

which creates a :code:`PythonAdder` component with three inputs and a width of two.

The same component is constructed with the keyword argument option as

    -m $HOME/VISR/src/python/scripts/pythonAtoms -c PythonAdder -k "{'width':2, 'numInputs':3}"

Positional and keyword arguments can also be mixed, as long as the corresponding Python rules are observed:

    -m $HOME/VISR/src/python/scripts/pythonAtoms -c PythonAdder -a "3," -k "{'width':2}"

So far, the examples specified the path to the module explicitly.
If this path (:code:`$HOME/VISR/src/python/scripts` in the example) is contained in the default Python search path, i.e., :code:`sys.path`, then the pure module name suffices

If this path (

 in the example) is contained in the default Python search path, i.e., 

    -m pythonAtoms -c PythonAdder -a "3," -k "{'width':2}"

Another way to locate the module is to provide the path through the :code:`module-search-path` option.

Another way to locate the module is to provide the path through the 

    --module-search-path $HOME/VISR/src/python/scripts

Finally, the option :code:`--module-search-path` can also be used to locate modules needed by the
main module. For example, the path to the core VISR modules can be specified in this way, thus
eradicating the need to add them to the default Python search path, for example by adding them to
the :code:`PYTHONPATH` variable.

 can also be used to locate modules needed by the
the 

    --module-search-path
    $HOME/VISR/src/python/scripts,/usr/share/visr/python

This section described the audio-interface-specific options that can be passed through the
:code:`--audio-ifc-options` or :code:`--audio-ifc-option-file` arguments.

The interface-specific options for the PortAudio interface are to be provided as a JSON file,
for example:

{
 "sampleformat": "...",
 "interleaved": "...",
 "hostapi" : "..."
}

When used on the command line using the :code:`--audio-ifc-options` argument, apply the quotation and escaping as described in Section :ref:`using_standalone_renderers_common_options`.

 argument, apply the quotation and escaping as described in Section 

The following options are supported for the PortAudio interface:

**sampleformat**
Specifies the PortAudio sample format. Possible values are:

 * :code:`signedInt8Bit`
 * :code:`unsignedInt8Bit`
 * :code:`signedInt16Bit`
 * :code:`unsignedInt16Bit`
 * :code:`signedInt24Bit`
 * :code:`unsignedInt24Bit`
 * :code:`signedInt32Bit`
 * :code:`unsignedInt32Bit`
 * :code:`float32Bit` .

**interleaved**:
Enable/disable interleaved mode, possible values are :code:`true, false`.

**hostapi**:
Used to specify PortAudio backend audio interface. Possible values are:

 - :code:`default`: This activates the default backend
 - :code:`WASAPI` : Supported OS: Windows.
 - :code:`ASIO` : Supported OS: Windows.
 - :code:`WDMKS`: Supported OS: Windows.
 - :code:`DirectSound` : Supported OS: Windows.
 - :code:`CoreAudio` : Supported OS: MacOs.
 - :code:`ALSA` : Supported OS: Linux.
 - :code:`JACK` : Supported OSs: MacOs, Linux.

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

- 

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

{
  "sampleformat": "float32Bit",
  "interleaved": "false",
  "hostapi" : "JACK"
}

The following options can be provided when using Jack as our top level component’s Audio Interface:

:code:`clientname`:
Jack Client name for our top level component.

:code:`servername`:
Jack Server name. If not provided, the default Jack server is used.

:code:`autoconnect`:
Globally enable/disable the automatic connection of ports.
Admissible values are :code:`true` and :code:`false`.
This setting can be overridden specifically for capture and playback ports in the port configuration section described below.

Admissible values are 

.

:code:`portconfig`: Subset of options regarding the configuration and connection of Jack Ports, see following section.

: Subset of options regarding the configuration and connection of Jack Ports, see following section.

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.

:code:`capture`: Specifies that the following options regard the top level component’s capture ports only

: Specifies that the following options regard the top level component’s capture ports only

:code:`autoconnect` : Enable/disable auto connection to an external jack client’s input ports, possible values are :code:`true, false`

 : Enable/disable auto connection to an external jack client’s input ports, possible values are 

:code:`port`: Jack ports specification

  - :code:`basename`: Common name for all top level component’s capture ports
  - :code:`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)
  - :code:`externalport`: Specification of an external jack client to connect to if :code:`autoconnect` is enabled.
        - :code:`client`: Name of an external jack client to use as input for our top level component (es. “system")
        - :code:`portname`: Common name for all external jack client input ports
        - :code:`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.

:code:`basename`: Common name for all top level component’s capture ports

:code:`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)

:  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)

:  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)

:code:`externalport`: Specification of an external jack client to connect to if :code:`autoconnect` is enabled.
    - :code:`client`: Name of an external jack client to use as input for our top level component (es. “system")
    - :code:`portname`: Common name for all external jack client input ports
    - :code:`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.

- :code:`client`: Name of an external jack client to use as input for our top level component (es. “system")
- :code:`portname`: Common name for all external jack client input ports
- :code:`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.

:code:`client`: Name of an external jack client to use as input for our top level component (es. “system")

: Name of an external jack client to use as input for our top level component (es. “system”)

: Name of an external jack client to use as input for our top level component (es. “system")

:code:`portname`: Common name for all external jack client input ports

:code:`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.

: 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.

:code:`playback`: Specifies that the following options regard the top level component’s playback ports only.

: Specifies that the following options regard the top level component’s playback ports only.

:code:`autoconnect` : Enable/disable auto connection to an external jack client’s output ports, possible values are :code:`true, false`

 : Enable/disable auto connection to an external jack client’s output ports, possible values are 

  - :code:`basename`: Common name for all top level component’s playback ports
  - :code:`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)
        - :code:`client`: Name of an external jack client to use as output for our top level component (es. “system")
        - :code:`portname`: Common name for all external jack client output ports
        - :code:`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.

- :code:`basename`: Common name for all top level component’s playback ports
- :code:`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)
- :code:`externalport`: Specification of an external jack client to connect to if :code:`autoconnect` is enabled.
      - :code:`client`: Name of an external jack client to use as output for our top level component (es. “system")
      - :code:`portname`: Common name for all external jack client output ports
      - :code:`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.

:code:`basename`: Common name for all top level component’s playback ports

:code:`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)

:  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)

:  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)

    - :code:`client`: Name of an external jack client to use as output for our top level component (es. “system")
    - :code:`portname`: Common name for all external jack client output ports
    - :code:`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.

- :code:`client`: Name of an external jack client to use as output for our top level component (es. “system")
- :code:`portname`: Common name for all external jack client output ports
- :code:`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.

:code:`client`: Name of an external jack client to use as output for our top level component (es. “system")

: Name of an external jack client to use as output for our top level component (es. “system”)

: Name of an external jack client to use as output for our top level component (es. “system")

:code:`portname`: Common name for all external jack client output ports

:code:`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.

: 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.

This configuration example shows how to auto-connect the Jack input and output ports of an application to the default jack client (:code:`system`), specifying which range of ports to connect.

This configuration example shows how to auto-connect the Jack input and output ports of an application to the default jack client (

{
  "clientname": "BaseRenderer",
  "autoconnect" : "true",
  "portconfig":
  {
    "capture":
    {
      "port":
      [{ "externalport" : {"indices": "1:4"} }]
    },
    "playback":
    {
      "port":
      [{ "externalport" : {"indices": "5:8"} }]
    }
  }
}

.. figure:: ../images/jacksimpleexample.jpeg
   :scale: 100 %

   Jack audio complex configuration 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.

{
  "clientname": "VisrRenderer",
  "servername": "",
  {
    {
      "autoconnect" : "true",
      "port":
      [
        {
         "basename" : "Baseinput_" ,
         "indices": "0:1",
         "externalport" :
          {
            "client" : "REAPER",
            "portname": "out",
            "indices": "1:2"
          }
        },
        {
         "indices": "2:3",
          {
            "indices": "4:5"
          }
         }
      ]
    },
    {
      "port":
      [{
        "basename" : "Baseoutput_" ,
        "indices": "0:1",
        "externalport" :
         {
          "client" : "system",
          "portname": "playback_",
          "indices": "4:5"
         }
       }]
    }
  }
}

.. figure:: ../images/jackexample.jpeg

The parameters are passed as a Python tuple.
See, e.g., the `Python documentation on tuples <https://docs.python.org/3.7/library/stdtypes.html#typesseq-tuple>`_.
Following these conventions, the arguments can be specified as follows:

`Python documentation on tuples <https://docs.python.org/3.7/library/stdtypes.html#typesseq-tuple>`_

.

Provide a sequence of parameters to the component's constructor as positional arguments.

Provide a sequence of parameters to the component’s constructor as positional arguments.

The fixed first three arguments to a component constructor, i.e., :code:`context`,
:code:`name` and :code:`parent`, do not need top be specified.
That means the first value of the sequence is passed to the fourth argument, the second value
to the fifth argument, and so on.

The fixed first three arguments to a component constructor, i.e., 

, do not need top be specified.

A comma-separated list of values, for example

   -a "3, 2.7,'foobar'"

Note that the enclosing double quotes are required to separate the argument to :code:`-a`
from other options on the command line.
They are strictly necessary only if the parameter sequence contains spaces, but we
recommend to use double quotes for consistency.

If the parameter sequence consists of a single value, a training comma is required.
That is, a single positional argument is specified as

   -a "3,"

If two or more arguments are provided, the trailing comma is optional.

Note that the enclosing double quotes are required to separate the argument to 

A comma-separated list of values, enclosed in parentheses.
Apart from the additional parentheses, the syntax is identical to the
comma-separated lists above.
That is, the argument list above would be specified as

   -a "(3, 2.7,'foobar' )"

As above, single arguments require a trailing comma.

   -a "(3,)"

A tuple constructed using the :code:`tuple()` keyword, that is

   -a "tuple(3, 2.7,'foobar' )"

and in the single-parameter case

   -a "tuple(3)"

That is, no trailing comma is required in this case.

The :code:`--positional-arguments` option is optional.
If it is not provided, no positional arguments are passed to the component's constructor.

 option is optional.
If it is not provided, no positional arguments are passed to the component’s constructor.

:code:`-a` :code:`--positional-arguments`:

* A comma-separated list of values, for example

     -a "3, 2.7,'foobar'"

  Note that the enclosing double quotes are required to separate the argument to :code:`-a`
  from other options on the command line.
  They are strictly necessary only if the parameter sequence contains spaces, but we
  recommend to use double quotes for consistency.

  If the parameter sequence consists of a single value, a training comma is required.
  That is, a single positional argument is specified as

     -a "3,"

  If two or more arguments are provided, the trailing comma is optional.

* A comma-separated list of values, enclosed in parentheses.
  Apart from the additional parentheses, the syntax is identical to the
  comma-separated lists above.
  That is, the argument list above would be specified as

     -a "(3, 2.7,'foobar' )"

  As above, single arguments require a trailing comma.

     -a "(3,)"

* A tuple constructed using the :code:`tuple()` keyword, that is

     -a "tuple(3, 2.7,'foobar' )"

  and in the single-parameter case

     -a "tuple(3)"

  That is, no trailing comma is required in this case.

Hyperlink target "using-visr-using-standalone-renderers" is not referenced.

Hyperlink target "using-standalone-renderers-common-options" is not referenced.

Hyperlink target "using-visr-using-standalone-renderers-visr-renderer" is not referenced.

Hyperlink target "using-visr-using-standalone-renderers-matrix-convolver" is not referenced.

Hyperlink target "using-visr-using-standalone-renderers-python-runner" is not referenced.

Hyperlink target "using-visr-using-standalone-renderers-specific-audio-options" is not referenced.

Hyperlink target "figure-jack-config-simple-example" is not referenced.

Hyperlink target "figure-jack-config-complex-example" is not referenced.

:code:`--object-name` or :code:`-n`:
Set a name for the top-level component. This name is used, for example, in error messages
and warnings emitted from the component.

This argument is optional.
If not provided, a default name is used.

:code:`--keyword-arguments` or :code:`-k`:
A set of keyword arguments to be passed to the component's constructor.
To be provided as a Python dictionary, for example:

   -k "{ 'argument1': value1, 'argument2': value2, ..., 'argumentN': valueN }"

.. hint:: As in case of positional arguments, we suggest to enclose the complete argument
          in double quotes.
          When following this convention, single quotes can be used for the keywords as
          :code:`'argument1'` and string parameters without the need for escaping quotes.

Following Python conventions, keyword arguments must not be provided for arguments already
handled by the :code:`--positional-arguments` option.
Likewise, keyword arguments must not be provided for the fixed first three constructor
arguments of a component: :code:`context`, :code:`name` and :code:`parent`.

This argument is optional; no keyword arguments are passed to the component if it is not given.

A set of keyword arguments to be passed to the component’s constructor.

-k "{ 'argument1': value1, 'argument2': value2, ..., 'argumentN': valueN }"

As in case of positional arguments, we suggest to enclose the complete argument
in double quotes.
When following this convention, single quotes can be used for the keywords as
:code:`'argument1'` and string parameters without the need for escaping quotes.

handled by the 

 option.
arguments of a component: 