![]() |
VISR
0.11.7
Versatile Interactive Scene Renderer
|
The baseline renderer is controlled by a combination of command line options and configuration file(s), which are itself specified as command line options.
At the time being, the VBAP rendering supports two different configuration file formats: plain text and XML-based. The XML configuration is currently supported only in the git branch subwoooferSupport
, but will be merged into the main branch (master
) soon. The selection of the file format is based on the file extension. Extension .xml (case-insensitive) activates XML parsing, all other extensions are treated as the text config format.
Compared to the the text configuration format, the XML format supports a number of additional features:
For these reasons, we suggest to favour the use of the XML-based format, and to phase out the text-based format at some time in the future. Matlab functions are provided (in src/libpanning/test/matlab
) to read read and write both formats to provide automatic conversion and the generation of configuration files from position data.
The XML-based format also removes the necessity for a separate loudspeaker configuration file to adjsut the gains and delays. To avoid unneccessary complexity regarding channel numbering and the support for additional features as subwoofers, the separate configuration option –output-gain
, short option -g
will be removed. For the same, the ability to adjust the output channel ordering (option -output-routing
is no longer supported.
The commandline options are displayed by invoking
The current output is
–audio-backend
The audio backend used by the Portaudio driver. Currently supported backends are "ALSA" and "JACK" on Linux, "DirectSound", "ASIO", "WDMKS" and "WASAPI" on Windows (depending on the installed SDKs/Drivers), and "CoreAudio" on MacOS. The value "default" triggers the default backend for this platform (ALSA on Linux).–sampling-frequency
Sampling frequency in Hz. Default: 48000 Hz.–period
The number of samples processed in one iteration of the renderer. Should be a power of 2 (64,128,...,4096,...) Very low values increase the load and the likelihood of audio dropouts, larger value decrease reactiveness and increase audio latency. Default: 1024 samples.–array-config
File path to the loudspeaker configuration file. Path might be relative to the current working directory. Mandatory argument. –input-channels 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
.xml triggers the use of the XML format for parsing.–output-channels
The number of output channels the renderer will put write to. It can be used to overwrite the channel configuration in the array configuration file. If not given, the number of output channels is determined from the largest logical channel number in the array configuration. If given, it must be in the form "o1=c1, o2=c2, o3=c3,..." or "o1=c1 o2=c2 o3=c3", where "ix" and "ox" denote physical output indices and logical channel indices, respectively. Both indices start at one.–output-gains
Optional gain and delay adjustment for the physical output channels. Takes a string argument to a XML configuration file. The format is described below. The channel indices in this file must refer to the physical outputs of the renderer, i.e., the number of entries must equal the number of renderer outputs (either given implicitly or by the -o option), and must cover all consecutive numbers from 1 to the number of outputs.–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: { "port": <UDP port number>, "position": {"x": <x in m>, "y": <y im m>, "z": <z in m> }, "rotation": { "rotX": rX, "rotY": rY, "rotZ": rZ } }". The values are 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 |
–tracking
not implemented yet, default values are used invariably. TO activate tracking, you need to specify the –tracking
option with an arbitrary parameter (even false
activates the tracker).–scene-port
The UDP network port which receives the scene data in the S3A JSON object format.The root node of the XML file is <panningConfiguration>
. This element supports the folloring optional attributes:
isInfinite
Whether the loudspeakers are regardes as point sources located on the unit sphere (false) or as plane waves, corresponding to an infinite distance (true). Default: false.dimension
Whether the setup is considered as a 2-dimensional configuration (value 2) or as three-dimensional (value 3, default). In the 2D case, the array is considered in the x-y plane , and the z
and el
attributes of the loudspeaker positions are not evaluated. In this case, the triplet specifications consist of two indices only (technically being pairs).Four types of elements are contained within the <panningConfiguration>
root element:
<loudspeaker>
Represents a reproduction loudspeaker. The position is encoded either in a <cart> node representing the cartesian coordinates in the x
, y
and z
attributes (floating point values in meter), or a <polar>
node with the attributes az
and el
(azimuth and elevation, both in degree) and r
(radius, in meter). Further attributes are:id
Numerical id id the loudspeaker, equal or larger than zero. Loudspeaker ids must be unique across the <loudspeaker> and <virtualspeaker> nodes and must form a consecutive range of integers. The requirement of using consecutive integers might be removed, as well as the restriction to integers. As the IDs are used only to reference loudspeakers in the <triplet> specification, any unique identifier (e.g., a name or a speaker label similar to ITU-R BS.775 labels) would be possible.channel
The logical output channel (sound card channel) for this loudspeaker. Logical channel indices start from 1. They must be unique over the set of loudspeaker and subwoofer channel indices.gainDB
or gain
Additional gain adjustment for this loudspeaker, either in linear scale or in dB (floating-point valus, default 1.0 / 0 dB ). Only one of them must be used for a single node.delay
Delay adjustment to be applied to this loudspeaker (floating-point value in seconds, default 0.0).<virtualspeaker>
An additional vertex added to the triangulation that does not correspond to a physical loudspeaker. Consist of a numerical id
attribute and a position specified either as a <cart> or a <polar> node (see <loudspeaker> specification).<subwoofer>
Specify a subwoofer channel. In the current implementation, the loudspeaker are weighted and mixed into an arbitraty number of subwoofer channels. The atributes are: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: "1, 3,4,5:7, 2, 8:-3:1".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 assignedLoudspeakers
index list. Optional value, the default value uses 1.0 for all assigned loudspeakers. Example: "0:0.2:1.0, 1, 1, 1:-0.2:0".gainDB
or 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 weight
attributes to the summed subwoofer signal. See <loudspeaker> specification.delay
Delay adjustment for this (floating-point value in seconds, default 0.0). See <loudspeaker> specification.<triplet>
Loudspeaker triplet specified by the attributes l1
, l2
, and l3
. In case of a 2D setup, only l1
and l2
are evaluated. all loudspeaker numbers must denote logical loudspeaker indices. NOTE: This representation does not assign an ID to the triplet, because this is noot required by the VBAP algorithm If an ordering of the triplets is required for whatever reason (the algorithm should not require this), then this should be imposed by the ordering of the triplet nodes.