User configuration

AudioMath can obtain default device, minLatencyMsec, bufferLengthMsec and apiPreferences values from either of these files:

~/.audiomath
~/.config/audiomath/config

The files use INI syntax. They are read in the order shown when the first stream needs a configured default, so the second file overrides the first at the same level of specificity. If XDG_CONFIG_HOME is set, it replaces ~/.config. Missing files are ignored.

Settings may be global or limited by back-end, host API and device. For example:

[default]
minLatencyMsec = auto
bufferLengthMsec = auto
apiPreferences = Core Audio, ALSA, *
device = USB Audio

[backend PortAudioInterface]
minLatencyMsec = 10
apiPreferences = WDM-KS, WASAPI, DirectSound, *

[backend PortAudioInterface // hostapi Core Audio]
minLatencyMsec = 12
device = MacBook Pro Speakers

[backend PortAudioInterface // hostapi Core Audio // device MacBook Pro]
minLatencyMsec = 18
bufferLengthMsec = [256]

The selector keywords backend, hostapi and device are case-insensitive and may be combined in any order. Back-end and host-API values are matched exactly, ignoring case. Device values are matched as case-insensitive partial names in the same way as the device argument to Player, Recorder and Stream: punctuation is treated as spacing, and the specified word or phrase must appear in the device name. The applicable back-end names are currently PortAudioInterface and PsychToolboxInterface.

Since apiPreferences controls which device and host API are selected, it is valid only in [default] or in a section containing just a backend selector. Specifying it in a section with a hostapi or device selector is an error: those selectors cannot be evaluated until after apiPreferences has already done its work.

The device setting is valid in [default], backend-only, host-API-only and combined backend/host-API sections. Its value is a partial device name with the same matching rules described above. A host-API-specific value is applied while candidates from that host API are considered. Specifying a device setting inside a section that already has a device selector is an error. The value device = * removes any broader configured device restriction within that scope.

Sections with more matching selectors override sections with fewer. For equally specific sections, device sections override host-API sections, which override back-end sections. A longer matching device phrase overrides a shorter one. Otherwise, later sections and files override earlier ones.

An explicit constructor argument has highest priority. A setting assigned for the current process, such as PORTAUDIO.DEFAULT_MIN_LATENCY_MSEC = 4, has priority over the files. Devices selected with SetInputDevice or SetOutputDevice likewise have priority over configured device defaults. The configuration cascade then precedes AudioMath’s factory defaults and PortAudio’s own device defaults. The values auto and pa-default retain their usual meanings.

Configuration affects only streams constructed after the files are read. In particular, an existing stream shared by multiple Player instances is not reconfigured.