Console and Configuration Guide

Note - the functions described below, if improperly used, may cause the Solocontutti app to behave incorrectly, crash or crash your computer. If you are not sure what these parameters mean, please to not use them. In particular, incorrect modification of the "Limiter" parameter can lead to equipment damage or worse.

Introduction to the console

(Note: the console is not available on portable devices)

The Solocontutti app console is a command line interface which allows users to view and modify internal parameters of the program, either to debug or to tune it. The console is accessed by adding the line:

set console on

somewhere at the beginning of the file Solocontutti.cfg which is in the same directory as the program itself. [In some versions of the program there is a function which allows the console to be turned on and off. This has the same effect].

Commands can be entered at the console and have the syntax:

{command} {parameter} {parameter} ...

Commands will only be executed when the Enter key is struck. For the purposes of tuning and monitoring, the only command of interest is "set" which has the following syntax:

set {variable} {value}

This commands sets internal variables to the given value. Entering the command with no parameters will produce a list of all available variables and their values. In addition, the command "script" (abbreviated to @) will cause the commands in the given file to be executed as if they were entered from the console.

Script {filename} or @{filename}

Config file

On startup a special script file "Solocontutti.cfg", which is located in the same directory as the application, will be executed. This allows a number of configuration parameters and logging options to be specified. The script is executed after the registry is read, so it will override any values in the registry.

Variables

The following lists all the variables accessible from the console and their meanings and usage. In addition, there are 10 special variables, %0, %1 ... %8, %9 which are used as substitution variables. These variables can be entered anywhere in a command or in a script file, and their value will be substituted into the command. For example:

set %0 JitterSize
set %1 1200
set %0 %1

is equivalent to:

set JitterSize 1200

The following is the list of variables (note that names are case sensitive).

Console

Type : on/off
Usage : enable the console

Console turns the debugging console on and causes the console to be displayed in a separate window. This is equivalent to creating the DWORD registry value HKEY_CURRENT_USER\Software\Solocontutti\UserData\Console with the value 1.

filtering

Type : on/off
Usage : enable or disable filtering

When set "off" all logging messages will be sent to the console and the logfile (if enabled). When set "on" only those messages containing one of the text strings defined in f0 - f5 will be logged. If f0 - f5 are all blank, then no messages will be logged. Note that not all messages are filterable and will be displayed irrespective of this setting (e.g. statistics output)

f0, f1, f2, f3, f4, f5

Type : text
Usage : set filtering parameters

These variables define the strings that are searched for in logging messages in order to decide to print them. For example, if you only want to print messages containing the text "error" or "sound" then use the commands:

set f0 error
set f1 sound
set filtering on

You can also specify a filter for a string not to be included by prefixing the string with a "!". So the filter "!sound" means that only messages NOT containing the word "sound" will be printed. The following rules apply for combinations of filters:

• Filters for included strings are ORed, i.e. the string is printed if any of the filter strings are in the text. If there are no inclusion filters then all strings are considered TRUE for this test
• Filters for excluded strings ("!" sign) are ANDed, i.e. the string is printed only if none of the excluded strings are in the text
• The result of ORing included strings is ANDed with the result of excluded strings, i.e. the text is printed if none of the excluded strings is present and at least one of the include strings is present, OR there are no include strings defined.

JitterSize

Type : number (integer)
Usage: maximum size of jitter buffer

The jitter buffer is an area for gathering samples that cannot yet be played. This may arise because there was a delay in transmission, after which all the missed packets arrived very quickly. When the next gap happens the jitter buffer can then be emptied. This does, however, introduce an additional latency equal to the size of the gap which can sometimes by > 100ms. In order to avoid this the jitter buffer has a threshold value, JitterSize (in ms), which will cause a jitter buffer overflow to be signalled. Once the jitter buffer has been in a state of overflow for more than JitterTime ms, then the excess packets are discarded. JitterSize is in units of driver frames and should be as low as possible. Default is 2ms, which for a 120 byte frame will introduce an average 1.5ms extra latency. For WiFi networks a value of 15 - 20 is sometimes needed. The software may modify this to a larger value to prevent excessive buffer underruns.

JitterCap

Type : number (integer)
Usage: absolute maximum size of jitter buffer

This value is similar to JitterSize, except the jitter buffer will be truncated immediately if this size (in ms) is exceeded. This effectively sets an upper bound on the extra latency that can be created by the Jitter Buffer. The software may modify this to a larger value to prevent excessive buffer underruns.

JitterTime

Type : number (integer)
Usage: discard time for jitter buffer

When a jitter buffer overflow has persisted for more than JitterTime cycles, then the excess packets will be discarded.

PingTimeout

Type : number (integer)
Usage: rejection time for ping reply

The program continually checks if it is in communication with other computers by sending out a message and waiting for a reply. PingTimeout is the time in ms that the program waits before concluding that the other program is unable to reply. After a number of retries Solocontutti will close the link. The standard timeout is 300ms, but this may be too small in some extreme circumstances, and can be altered with this parameter.

PortRange

Type : number (integer)
Usage: number of ports to scan for NAT tunnelling

PortRange determines the number of ports that the application uses to try and create a connection with the other users. Because most users will be behind a NAT enabled gateway, the application needs to try to make connections on several ports. The variable may be between 1 and 9, any other values will most likely cause communication to fail. Reducing this value reduces the time that it takes to establish a connection, but on various types of gateways may reduce the chance of connections being established. This variable is mainly relevant for system administrators of corporate networks who want to reduce the number of ports that they need to keep available.

SendPrivateIP

Type : on/off
Usage: send local IP address to server

When enabled (default) this instructs the program to send the local IP address of your computer to the server, which will in turn broadcast this to other users in the session. This is used to allow connections preferentially in a local area network. In combination with 'set PortRange 0' you can set Comble to only work in a local network. This can be disabled if required.

FillWindow

Type : integer
Usage: number of frames to use for filling gaps

Gaps in received data are partially filled by repeating a portion of the previous samples, mediated by an estimation of the current pitch of the music. The size of this repeated section is the FillWindow, which is measured in frames. Larger fill windows tend to produce a smoother sounding fill, at the expense of a more abrupt transition when the data is available. NOTE: this only affects non-codec filling.

Limiter

Type : integer
Usage: limiter for overloaded output

The Solocontutti app includes a limiter to ensure that outputs are not overloaded. The limiter works by cutting off output if the total energy if output exceeds a given level. The level is given by "Limiter" decibels w.r.t the theoretical maximum sound level, and so must always be negative to be effective. Setting the limiter to 0 or a positive value is equivalent to turning off the limiter. The limiter operates on the output of the Solocontutti app program to the ASIO drivers, and so does not take account of gain modifications in the mixer of the ASIO driver, or of physical gain controls. The limiter is a simple precaution mainly designed to ensure that hearing or equipment damage is not accidentally caused by overloaded outputs. The limiter may in some cases be undesirable and can by turned off with this value. Exercise caution when doing this and be sure that that there are no feedback loops in the system when doing so.

NoiseShaper

Type : on/off
Usage: Use noise shaping algorithm

When on this applies a simple noise shaping algorithm to the output, reducing noise and enhancing perceived quality of the feed. This may be useful if a lot of background noise is being received, but will eventually be replaced by a filterbank.

Other Commands

Other commands are useful for helping diagnose problems:

• chan - show information about the connection to the channels
• dev - show the currently active sound devices
• help - show help text

ASIO is a trademark of Steinberg media technologies GmbH. Not all sound cards will support the required frame sizes and there are some limitations imposed by combinations of framesizes that the encoding software supports and framesizes that the driver supports. In these cases you may use ASIO4ALL. If this does not work, the device may be incompatible with the Solocontutti app.