Settings Available From carb.audio

• /audio/allowThreadTermination: The underlying audio library (Forge) used by carb.audio will optionally terminate its own threads when it detects them to be hanging via watchdog timers expiring. Hangs can be caused by internal bugs, system audio library issues or bugs within callbacks. Terminating threads is not safe, so the process may crash or hang later on. Setting this to false will cause Forge to abort instead of terminating its threads when the watchdogs expire. It’s recommended to set this to false in tests to avoid a deferred crash. This defaults to true.

• /audio/debugChannels: This will enable/disable log channels specific to carb.audio; these are intended to be used for developers of carb.audio and code dependent on carb.audio.

  • The syntax of this setting is a list of debug channels to enable. Each debug channel in the list is separated by a comma. No spaces are allowed in the string. Each debug channel specifier has the following format: [<dbgClass>]"+|-"<channelName> where:

    • <dbgClass> is the name of the class of messages to enable. This may be exactly one of: “fatal”, “error”, “warn”, “info” or “verbose”.

    • <channelName> is the name of the channel to enable/disable. See below for a list of available channel names. Omitting this parameter results in the verbose log level being used for ‘+’ and disabled log level being used for ‘-‘.

    • “+|-” indicates whether the named debug channel is to be enabled (‘+’) or disabled (‘-‘).

    • Channels are parsed left to right, so you can override the effects of a previous entry in the debug channel string.

  • Some example channel strings are:

    • warn+all,-bus: To enable warnings + errors from all channels, then silence the bus channel entirely (this can be useful if a spurious error message is spamming the logs).

    • +bus,+stream_decoder: Enable the bus and stream_decoder channels.

  • The available debug channels are:

    • all: Enable all log channels. Extremely verbose.

    • audio: Plugin startup and miscellaneous messages.

    • balance: Pan and fade calculations (dumps out calculated matrices in debug mode).

    • bus: Information related to voices playing into the audio mixer. Can be extremely verbose.

    • capture: Audio capture information. Extremely verbose when capturing.

    • codec: Codec management information.

    • context: Logging from carb::audio::IAudioPlayback Context related functions.

    • convert: carb::audio::IAudioUtils::convert related info.

    • data: Logging related to SoundData accessor as well as uncategorized messages from carb::audio::IAudioData functions.

    • device: Device enumeration information. Not much is logged on this channel currently.

    • eventpoint: Logging related to event point management (event point use during playback is logged on the bus channel).

    • flac: Logging related to FLAC encoding/decoding. Extremely verbose.

    • group: Logging from the IAudioGroup interface.

    • heap: Logging related to the heap structure used for voice priority tracking. This is not particularly useful except for debugging heap issues. Extremely verbose.

    • load: Logging related to carb::audio::IAudioData::createData.

    • metadata: IAudioData metadata accessor function information.

    • mp3: MP3 and Id3 tag parsing logging.

    • notify: Information related to device change notifications.

    • ogg: Ogg file parsing infromation. Extremely verbose.

    • ogg_seek: Logging related to seeking within Ogg files. Extremely verbose.

    • opus: Opus encoding/decoding information.

    • output: Information related to the output from the audio mixer. This includes information about: device connection, audio streamers, playback device enumeration and speaker configuration.

    • outputstream: Logging related to the carb::audio::OutputStreamer object used by carb::audio::IAudioUtils.

    • pcm: PCM transcoding logging.

    • playback: Uncategorized IAudioPlayback logging.

    • riff: Information related to encoding/decoding of RIFF (WAVE) media containers.

    • stream_decoder: Logging from the asynchronous audio decoding during playback. Extremely verbose.

    • voice: Logging related to the individual voice objects. This includes, modification to the voice state, simulation, spatial audio parameter calculation, etc. Extremely verbose.

    • vorbis: Information related to encoding/decoding of Vorbis.

• /audio/forgeChannels: This passes the string of log channels to Forge’s logging system. Forge logging is only enabled in debug builds. The syntax of this string and the list of logging channels can be found in debugchannels.md within the Forge documentation; these logs are only particularly useful to Forge developers. The Forge channel string is similar in syntax to the debug channel string, except the log levels are: trace, warn, fixme and err. Some settings that may be useful are:

  • +tid,+timestamp: Add a thread ID and timestamp to all logs. It is recommended that you always add this to the Forge channel string.

  • "+tid,+timestamp,err+all": Forge will log error messages.

  • "+tid,+timestamp,err+all,warn+all,fixme+all": Forge will log error messages as well as warnings and unimplemented features used. Warn tends to spam in some cases. Fixme is not particularly useful for Carbonite development.

  • "+tid,+timestamp,+forgeaudio_backend": (Linux only) This will log information related to audio device enumeration. This can be particularly useful when ALSA is doing something weird. This is fairly verbose.

  • "+tid,+timestamp,+forgeaudio_data": (Linux only) Log when reading/writing to an audio device. This can be useful when audio timing is behaving unexpectedly. Extremely verbose.

  • "+tid,+timestamp,+forgeaudio_latency": (Linux only) Dump latency information from forgeaudio. Does not work if the null audio backend is used. This is fairly verbose.

  • "+tid,+timestamp,+forgeaudio_stats": (Linux only) Occasionally log stats such as latency and underruns from forgeaudio. Does not work if the null audio backend is used.

  • "+tid,+timestamp,+forgeaudio_stats(2)": Identical to the above example, except that trace messages from forgeaudio_stats are colored in terminal color 2 (green); values up to 256 should work if supported by your terminal. You can add the +color channel to try to force color on if Forge isn’t detecting color support.

• /audio/deviceBackend: This can be used to select a specific audio backend, rather than using Forge’s preferred option. Some of these are for platforms that are not supported by Carbonite. This is not case sensitive. Backends available in forge are:

  • ALSA: Use the Advanced Linux Sound Architecture (Linux only)

  • PulseAudio - Output to the Pulse Audio sound server (Linux only)

  • CoreAudio - Use the Core Audio sound system (OSX only)

  • DroidAudio - Use the OpenSL sound system (Android only)

  • magic - An alternative OpenSL sound backend (Android only)

  • WASAPI - Use the Windows Audio Services API (Windows only)

  • null - fake audio playback/recording.

  For carb::audio::IAudioPlayback on Windows, WASAPI is used by default; WASAPI initialization is never expected to fail but if it does, null is used. For carb::audio::IAudioCapture on Windows, the device backend is DirectSound, and this cannot be changed; in the future, this will be changed to use the same device backend as carb::audio::IAudioPlayback (OM-35108).

  On Linux, PulseAudio is used by default; if the Pulse Audio server is not running or the Pulse Audio library (libpulse.so.0) is missing, ALSA is used; if the ALSA library (libasound.so.2) is missing, null is used.

• /audio/context/forceDecodeLargeSound: This can be set to 1 to disable the memory limit for carb::audio::IAudioData::createData when carb::audio::fDataFlagDecode is used. This memory limit will result in the decoding flag being removed when the sound is beyond the limit of what would be reasonable to decode (the maximum of 2GiB or half the system’s physical memory). This limit mainly exists because corrupted audio files can report their size incorrectly, which can result in the audio plugin trying to create an overly large buffer when this is disabled.

• /audio/nullBackend: This is a settings tree for options related to the null audio backend. These settings only take effect when set on launch. Although the null backend exists primarily to handle cases where a host-system’s audio subsystem is non-functional, it can be useful for automated testing. The options available within this setting tree are all intended to improve automated testing capabilities. When testing with these features, /audio/deviceBackend should be set to "null" to force the null backend to be used.

  • /audio/nullBackend/DeviceCount: This is an unsigned integer setting that specifies how many audio devices the null backend will report. Every device will be identical, aside from the name and GUID. This is intended to allow you to test how an application will behave when there are no either no audio devices in the system or a very large number of audio devices. This is set to 1 by default.

  • /audio/nullBackend/IsFunctional: This is a boolean setting; when false, this will cause audio devices to behave identically to a broken ALSA device. This is intended to allow you to test how an application will behave when the system’s audio device is broken. This is set to true by default.

  • /audio/nullBackend/ReportsOverruns: This is a boolean setting; when true, this will cause devices to report an overrun/underrun when the simulated 4096 byte buffer fills up/runs out. This is intended for testing carb::audio::IAudioCapture’s overrun detection. This is set to false by default.

  • /audio/nullBackend/CaptureTestMode: This is a boolean setting; when true, this will cause carb::audio::IAudioCapture to produce a specific sample pattern, rather than silence. The pattern produced depends on the sample type being recorded:

    • Integer sample formats will begin at their silence value (0 in all formats aside from carb::audio::SampleFormat::ePcm8; 128 in carb::audio::SampleFormat::ePcm8), then increment by 1 for every sample recorded. After they reach the maximum sample value, they will wrap around in the standard two’s complement manner, then subsequent samples will increase. Note that the value increments per-sample, not per-frame, so each subsequent channel in an audio frame will be 1 greater than the previous.

    • Floating point sample formats (carb::audio::SampleFormat::ePcmFloat) will begin at 0, then increase by 1.0f / (1 << 24) every frame until it reaches 1.0 at which point the next sample will be -1.0 and then subsequent samples will increase from there.

    This is intended to allow automated testing to verify that the data captured is able to make it through a system unaltered. This defaults to false.

• /audio/pulseAudio: This is a settings tree for options related to the Pulse Audio audio device backend. These settings only take effect when set on launch.

  • /audio/pulseAudio/enumerateMonitors: This is a boolean setting which specifies whether carb.audio-forge will enumerate loopback devices, which PulseAudio refers to as ‘monitors’. carb.audio-forge will not recognize GUIDs of ‘monitors’ when it is launched with this setting set to false. This is set to false by default.

• /audio/WASAPI: This is a settings tree for options related to the Windows Audio Services audio device backend.

  • /audio/WASAPI/legacyBackend: This is a boolean setting which will switch back to an older version of the Windows Audio Services backend for carb::audio::IAudioPlayback. This is offered in case device issues occur as a result of the newer version of this device backend; this setting may be removed eventually. This is set to false by default.