I Parent topic: I

io-audio

Updated: October 28, 2024

Start one or more audio drivers

Syntax:

io-audio [-c config_file] [-v[v]...]
         [-l level]
         [-m opt[,opt...]]
         [-o opt[,opt...]] 
         [-U string]
         [-d driver[opt[,opt...]]]

Runs on:

QNX Neutrino

Options:

-c config_file
Load the specified audio configuration file. For more information, see “Audio configuration file”, below.
-d driver [opt[,opt...]]
Load the specified driver and pass it the given driver options. The driver name is the name of the shared object without the deva-ctrl- prefix and the .so extension. For example, to load the deva-ctrl-audiopci.so shared object, specify audiopci as the driver name. You can start more than one driver by using multiple -d command-line options. For information on the drivers and any specific options, see the entries for the deva-ctrl-* shared objects.
Note:

If you want to start the driver from a configuration file, all the following driver options can be specified using the options key-value pair in the [CTRL] section, with the exception of the unit option.

All audio drivers support the following card options:

cap_name=name
The symbolic name to assign to the PCM capture device.
conf=path_to_file

This option allows you specify driver settings in a separate, driver-specific configuration file.

dindex=number
The device number that additional following options apply to.
output_classes=number[:number]...
The output class used for DRM purposes. To specify more than one class, separate the values with a colon.
  • 0 (SND_OUTPUT_CLASS_UNKNOWN) — The output channel is for an unknown type.
  • 1 (SND_OUTPUT_CLASS_SPEAKER) — Indicates that the output channel is for speakers connected to the system.
  • 2 (SND_OUTPUT_CLASS_HEADPHONE) — Indicates that the output channel is for headphones connected to the system.
  • 3 (SND_OUTPUT_CLASS_LINEOUT) — Indicates that the output channel is for the line-out for the system.
  • 4 (SND_OUTPUT_CLASS_BLUETOOTH) — Indicates that the output channel is for Bluetooth.
  • 5 (SND_OUTPUT_CLASS_HDMI) — Indicates that the output channel is for speakers connected to the system.
  • 6 (SND_OUTPUT_CLASS_TOSLINK) — Indicates the output channel is for an S-Link connector.
  • 7 (SND_OUTPUT_CLASS_MIRACAST) — Indicates that the output channel is for Miracast.
play_name=name
The symbolic name to assign to the PCM playback device.
restrict_interface=capture | playback | both
Enable restricted access to the capture, playback, or both PCM device interfaces. These restrictions are provided with these io-audio manager-specific process abilities:
  • io-audio/capturerestricted (IOAUDIO_ABILITY_RESTRICTED_CAPTURE) — Restrict applications from capturing audio data. To apply this restriction, set the driver option to capture.
  • io-audio/playbackrestricted (IOAUDIO_ABILITY_RESTRICTED_PLAYBACK) — Restrict applications from playing audio data. To apply this restriction, set the driver option to playback.
If you wanted to restrict applications from both capturing and playing audio data, set the driver option to both.
After you apply your restrictions, you may want to grant permissions to capture or play audio data only to specific applications on your system. For example, let's say you restricted all applications on your system from capturing audio data, use this command to start io-audio manager: 
io-audio -d audiopci -dindex=0,
restrict_interface=capture
You could then grant access to a specific application by using another process to grant permission. For example, here we show a way how you can use the on command (which has been granted root privileges on the system) to grant the wave application (which doesn't have root or the io-audio/capturerestricted ability): 
on -u100:100 -A able=io-audio/capturerestricted,
allow,nonroot waverec /temp/test.wav
unit=number
The configuration of the card number to use for the driver.

When you use the mount command to dynamically load a driver, you can use the unit number to specify which [CTRL] section in the configuration file to use. For more information on the different scenarios, see the “Description” section. .

-l level
Explicitly set the level of output verbosity. You can also use the -v[v...] option to specify verbosity.
-m opt[,opt...]
Memory options. The opt variable can be any of the following:
pool_size=kbytes
The size of the DMA memory pool to create, in KB. The default is 0 KB.
pool_name=string
The name of a shared memory object or typed memory object to map and use as DMA memory pool. This object must be physically contiguous memory.
Note: If the pool name is a reference to a typed memory object, then you must also provide the pool_size. If the pool name is a reference to a shared memory object, then the pool is automatically sized to be the size of the object.
smmu=[0 | 1 | off | on]
Use the QNX System Memory Management Unit Manager (SMMUMAN).

If the smmuman service is running, specify 1 or on to configure io-audio to interface with smmuman to manage ("cage") access for non-CPU initiated reads and writes (i.e., DMA devices).

-o opt[,opt...]
Global options to apply to all drivers (specified with the -d option) that follow on the command line. The opt variable can be any of the following:
config_write_delay=time
The time in seconds after the last change before sound card settings are written to disk. The default value is -1, which prevents the settings from ever being written. The settings are written to a file at /etc/system/config/audio, which must be located on a writable filesystem.
data_thread_prio=priority
The minimum priority of the software mixer thread. The default is 25; values that are outside the priority range for the round-robin scheduler are discarded.
disable_sw_mixer
On cards that have only a single channel in hardware, don't use software techniques to increase the maximum number of playing channels. By default, the software mixer is enabled.
intr_thread_prio=priority
Set the priority of the interrupt service threads. The default is 50; values that are outside the priority range for the round-robin scheduler are discarded.
max_dma_buf_size=size
The maximum size, in kilobytes, for the DMA buffer. The default is 256 KB; io-audio uses a minimum size of 16 KB.
sw_mixer_rate=[FAHQ | FA | Lvalue]
Set the method of selecting the sampling frequency used by the PCM software mixing device if the underlying hardware device supports multiple rates. The selection process may make use of two possible rate "families" — a set of rates that are multiples of 4 kHz and a set that are multiples of 11.025 kHz:
  • FA (First Active) — Select the sample rate using the following process:
    1. Use the requested rate, if supported.
    2. Search the sample rate range for the next higher supported rate in the same rate family.
    3. Search the sample rate range for the next higher supported rate in the other rate family.
    4. Search the sample rate range for the next higher supported rate that is not part of either sample rate family (i.e., not a multiple of 4 kHz or 11.025 kHz).
    5. Search the sample rate range for the next lower supported rate, regardless of the rate family.
    6. Select the maximum available sample rate.
  • FAHQ (First active high quality) — If the requested rate is equal to or less than 48 kHz or 44.1 kHz:
    • If the requested rate is a multiple of 4 kHz, select 48 kHz.
    • If the requested rate is a multiple of 11.025 kHz, select 44.1 kHz.
    If the requested rate is greater than 48 kHz or 44.1 kHz, or if the requested rate of 48 kHz or 44.1 kHz is not supported, then search the sample rate range with the same method that is used for FA.
  • Lvalue — Lock the sample rate to the rate specified by value, regardless of the client's requested rate.
The default is FAHQ.
sw_mixer_sample_size=[16 | 32]
Specify the sample size for the PCM software mixer to use:
  • 16 — 16-bit signed, native endian.
  • 32 — 32-bit signed, native endian.

If you do not use this key, the sample size is determined by the sample size the underlying hardware uses:

  • If the hardware is 8- or 16-bit, the mixer uses 16-bit signed, native endian.
  • For 24- or 32-bit hardware, the mixer uses 32-bit signed, native endian.
sw_mixer_samples=num
Adjust the fragment size in samples per voice. Here's an example of how to calculate the value to pass in with this option:

sw_mixer_samples = sample_rate (in samples per second) * fragment_length (in seconds)

-v[v...]
Increase the level of output verbosity. Additional v characters increase the verbosity. You can also use the -l option to specify verbosity.
-U string
(QNX Neutrino 7.0 or later) This option is recognized only if you run as root. Once the utility is running, it will run as the specified user with the proper process abilities so that the program doesn't need to run as root.
The string can be in one of these forms:
  • uid[:gid[,sup_gid]*]
  • user_name[,sup_gid]*

In the second form, the primary group is the one specified for user_name in /etc/passwd.

-v[v...]
Increase the level of output verbosity. Additional v characters increase the verbosity. You can also use the -l option to specify verbosity.

Description:

The io-audio service allows you to dynamically load audio drivers when you start io-audio. You use the -d options to specify the drivers to load.

You can run this command as root or a non-root user. When you run this command as a non-root user, it must be granted the proper process abilities. The io-audio manager includes custom permissions to restrict capture and playback. For more information, see the restrict_interface driver option for the driver (-d) option.

Note: The PCM software mixer and PCM software splitter threads run at a priority of either +1 from the highest audio client application priority or data_thread_prio, whichever is higher. To make sure that the threads closest to the hardware have the highest priority, the client application priorities should never be more than -2 from intr_thread_prio. For example, if the priority of the client thread is 48, the PCM software mixer thread is 49 (48+1), which is one less than the default intr_thread_prio value of 50.

Once io-audio has started, you can dynamically load and unload drivers using the mount and umount commands.

Mounting a driver

Here's how you can use the mount command to dynamically load drivers. For example, this command: 

io-audio -dusb -daudiopci

gives the same result as this sequence: 

io-audio
mount -T io-audio usb
mount -T io-audio audiopci
Note: When searching for shared objects, the io-audio uses the LD_LIBRARY_PATH environment variable.

Unit (card) numbers are reserved for drivers defined in the [CTRL] sections of the audio configuration file. The numbers are reserved based on the order that the [CTRL] sections appear in the file. Additionally, the unit key in the [CTRL] section can be used to define a specific card number unrelated to the section's position in the file. This ensures that card numbers that are assigned at io-audio startup via the configuration file are deterministic regardless of further runtime loading/unloading of driver DLLs.

If a device is defined in the audio configuration file, its card number is assigned for the lifetime that io-audio runs. If you unload a card (e.g., umount /dev/snd/controlCx) and its number is reserved for a driver in the configuration file, the card number is not released back to the system. However, if a driver is dynamically loaded at runtime (and does not match a number reserved in the configuration file), unloading the card releases its number.

When you dynamically load a driver DLL at runtime using the mount command, providing the unit option causes io-audio to first search the audio configuration file for a [CTRL] section that matches the provided unit and driver name. If a [CTRL] section with a matching unit number isn't found, then the driver (DLL) is loaded based solely on the options provided to the mount command. If a [CTRL] section with a matching unit number is found, the driver name is used to validate the use of the [CTRL] section to load the DLL; if the driver name doesn't match, the mount operation fails. Here's an example of using the unit option to dynamically load a driver DLL: 
# mount -Tio-audio -ounit=2 deva-ctrl-mcasp.so
Note: Card numbers must be unique. Any attempt to mount a driver DLL with a unit number that's in use will fail.
A driver DLL can also be dynamically mounted using a driver-specific configuration file by using the conf=path_to_file option. If no unit number is provided, then the first [CTRL] section with the matching driver name is used to load the driver. If the unit option is provided, then a [CTRL] section that matches both the unit number and driver name is used. If no match is found, then the attempted mount operation fails. 
#mount -Tio-audio -oconf=mydriver.conf deva-ctrl-mcasp.so
#mount -Tio-audio -oconf=mydriver.conf,unit=2 deva-ctrl-mcasp.so
The following driver-specific configuration file (mydriver.conf) has two entries that match the previous mount commands. The first [CTRL] section is used when you don't provide the unit option. If you do provide the option (as in the second example [CTRL] section), then the second [CTRL] section is used: 
[CTRL]
name=mcasp
options=clk_mode=master

[CTRL]
name=mcasp
unit=2
options=clk_mode=master
Note:
  • Unlike the audio configuration file, driver-specific configuration files must explicitly specify the unit key to be used in conjunction with a mount command that includes the unit option.
  • Don’t set unit as an option for the options key in the audio configuration file or driver-specific configuration file. Instead, use the explicit unit key. For example, the following example section is invalid: 
    [CTRL]
name=mcasp
options=unit=2,clk_mode=master
    The following section with the explicit unit key is correct: 
    [CTRL]
name=mcasp
unit=2
options=clk_mode=master
  • When you mount a driver, don't use the configuration file that was used to start io-audio as a driver-specific configuration file. If you need to re-mount a driver defined in the io-audio configuration file, specify the appropriate unit number and driver name with mount. The io-audio service automatically checks the io-audio conference file for a matching [CTRL] driver name and unit number.
Two special options can be used in conjunction with the audio configuration when you use the mount command:
all
Mounts all currently unmounted (e.g., deferred or previously unmounted) cards that are specified in the audio configuration file. Any other options provided to the mount command are ignored. For example: 
# mount -T io-audio all
acoustics
If the QNX Acoustics Management Platform 3.0 is available, mount all currently unmounted Acoustic Control Server (ACS) and Acoustic Management Platform Functional Modules (AFM) cards specified in the audio configuration file. Any other options provided to the mount command are ignored. 
# mount -T io-audio acoustics

Unmounting a module

To unload a module, reference its published device name in the unmount command. For example: 

umount /dev/snd/controlC0

Audio configuration file

The audio configuration file is optional, but is easier to use and more flexible than using the corresponding command-line options. In order to load an audio configuration file, specify the -c configuration_file_path option when you start io-audio. Global and memory options provided on the command line override the corresponding audio configuration file settings. If you specify deva-* shared objects both on the command line (via the -d option) and in the audio configuration file (via [CTRL] sections), each is treated as an individual and independent request to load or mount a driver.

Options from the [CTRL] section take precedence over options defined (and supported) in both the [GLOBAL] and [CTRL] sections. Global options provided via the command line (-o) are also overridden by options defined in the [CTRL] section in the audio configuration file. In general, we recommend that you limit the use of [GLOBAL] options and use the options under the [CTRL] section.

The standard location for this file is /etc/system/config/audio/io-audio_platformVariant.conf. If an error occurs while parsing the audio configuration file, io-audio won't start.

When you're using indexed PCM mixer or input splitter keys, the index is that of the parent PCM device that the mixer/splitter is being created for, not the index of the mixer/splitter PCM device that's being created.

The general syntax is as follows:

#
Anything after a number sign on a line is considered a comment.
[ name ]
A string enclosed in square brackets indicates the start of a section.
  • The name is case-insensitive.
  • Leading and trailing spaces are removed, but white space is allowed within the name.
  • Extra characters other than comments after the closing bracket cause the section to be discarded.
  • Duplicated section names are allowed. However unless the section specifically specifies multiples (see below), in most cases only the keys in the first section of that name in the file are used. The Acoustic Control Server section is an exception to this; multiple ACS sections will cause an error.
key = value
A key-value pair.
  • The key is case-insensitive.
  • The value is case-sensitive.
  • Leading and trailing spaces are removed from the key and value.
  • A key must have a value; a value must have a key.
  • White space within a key or value causes the key-value pair to be discarded.
  • All valid key-value pairs are associated with the section preceding them in the file.
  • If there are multiple keys of the same name within a section, the value of the last key in the section is used.
  • An indexed key is a key with the “_index” suffix appended to the key name (e.g., key_1).
  • Nonindexed key values apply globally for the section that they're defined in. You can override this value on a device-by-device basis with indexed keys.
  • Key/value pairs at the start of the file (before a section has been specified), or after an invalid section are discarded.
  • If you specify an ampersand (&) before the key name, the value is appended to the key's current value. For example, the following: 
    options=clkmgmt=0
&options=,dindex=1,play_name=defaultp
&options=,dindex=2,cap_name=defaultc
    Is the same as: 
    options=clkmgmt=0,dindex=1,play_name=defaultp,dindex=2,cap_name=defaultc

[GLOBAL] section

The keys in the [GLOBAL] section include the following:
Key Default Description
config_write_delay -1 The time in seconds after last change before soundcard settings are written to disk. The default value of -1 prevents the settings from ever being written.
max_dma_buf_size 256 The maximum DMA buffer size, in KB. The minimum value for this parameter is 16 KB.
status_accuracy 25 Status accuracy in milliseconds
disable_sw_mixer 0 Disable the PCM Software mixer (0 / 1). If 0, a PCM Software mixer is instantiated.

If 1, don't use software techniques to increase the maximum number of playing channels on cards that have only a single channel in hardware.

You should specify this in the [CTRL] section for each card rather than at this point, to simplify enabling/disabling of the PCM software mixer on a card-by-card basis.

sw_mixer_ms See description

Set the PCM mixer fragment size, in milliseconds, for any card that doesn't specify the fragment size in the [CTRL] section or at the command line. This key overrides sw_mixer_samples.

If you don't specify this key, sw_mixer_samples sets the PCM mixer fragment size.

Note:
  • If any acoustic AFMs play back through a PCM software mixer, the following configuration is required:
    • sw_mixer_ms must be specified at the command line or in the [GLOBAL] or [CTRL] section
    • the sw_mixer_ms should be a factor of the acoustic library fragment size. If the hardware requires a sw_mixer_ms value that is larger than the acoustic library fragment size, you can set sw_mixer_ms to a multiple of the acoustic library fragment size. However, using a fragment size that is larger than the acoustic library fragment size will have an impact on the AFMs performance.
  • You can only specify an integer for this option. However, if the configured sample rate is not a multiple of 4 kHz, a valid fragment size in milliseconds can't be expressed as an integer. To compensate, io-audio rounds down the value that you specify, taking into account various alignment restrictions (audio frame size, cache line size, etc.).
sw_mixer_samples 1024 The mixer fragment size, in samples per voice. It is overridden by sw_mixer_ms, if specified. The minimum and maximum values you can use are determined by other parameters (sw_mixer_sample_size, voices, max_dma_buf_size). The default value for max_dma_buf_size configuration is 256 KB.
sw_mixer_sample_size None Specifies one of the following sample sizes for the PCM software mixer to use:
  • 16 — 16-bit signed, native endian
  • 32 — 32-bit signed, native endian

If you do not use this key, the sample size is determined by the sample size the underlying hardware uses:

  • If the hardware is 8- or 16-bit, the mixer uses 16-bit signed, native endian.
  • For 24- or 32-bit hardware, the mixer uses 32-bit signed, native endian.
To specify the sample size for a specific PCM software mixer, append an underscore and the device name to the key. For example, sw_mixer_sample_size_0.
sw_mixer_rate FAHQ The method for setting the PCM software mixer sample rate. If the underlying hardware supports multiple sample rates, the specified method determines which rate the mixer uses. The selection process may make use of two possible rate "families" — a set of rates that are multiples of 4 kHz and a set that are multiples of 11.025 kHz:
  • FA — First active; select the sample rate using the following process:
    1. Use the requested rate, if supported.
    2. Search the sample rate range for the next higher supported rate in the same rate family.
    3. Search the sample rate range for the next higher supported rate in the other rate family.
    4. Search the sample rate range for the next higher supported rate that is not part of either sample rate family (i.e., not a multiple of 4 kHz or 11.025 kHz).
    5. Search the sample rate range for the next lower supported rate, regardless of the rate family.
    6. Select the maximum available sample rate.
  • FAHQ (First active high quality) — If the requested rate is equal to or less than 48 kHz or 44.1 kH z:
    • If the requested rate is a multiple of 4 kHz, select 48 kHz.
    • If the requested rate is a multiple of 11.025 kHz, select 44.1 kHz.
    If the requested rate is greater than 48 kHz or 44.1 kHz, or if the requested rate of 48 kHz or 44.1 kHz is not supported, then search the sample rate range with the same method that is used for FA.
  • Lvalue — Lock to the specified rate, where value is in the range 100–200000.
intr_thread_prio 50 The interrupt service thread's priority. The value is discarded if it isn't within the valid range of round-robin priorities.
data_thread_prio 25 The minimum thread priority. The value is discarded if it isn't within the valid range of round-robin priorities.
verbosity 0 The logging verbosity level. using a Bit-masked log level:
  • Bit 0 DRIVER — Debug information from drivers. (e.g., you can also use INTERRUPT or CODEC for driver-level debug information).
  • Bit 1 CONTROL — Debug information from the control path, state machine, etc.
  • Bit 2 PCM — Logs control type information.
  • Bit 3 MIXER — Mixer related debug debug information, such as volume and mute controls. Debug information from mixer DLL and codec level deva-* DLLs.
  • Bit 4 IO_ADO — High-level Audio library debug information.
  • Bit 5 RESMGR — Debug information from the resource manager (resmgr_*) callbacks.
  • Bit 6 POWER — Debug information related to power management.
  • Bit 7 MISC — Miscellaneous debug information.
  • Bit 8 CODEC — Codec-level debug information from the PCM software mixer and deva-* DLLs.
  • Bit 30 INTERRUPT — Interrupt handler debug information. (dma_interrupt, deva interrupt callbacks, etc.)
  • Bit 31 MEMORY — Memory allocation debug information.
pool_name None The name of a shared memory or typed memory object to map and use as a DMA memory pool. The object must be physically contiguous memory.

If the pool_name refers to typed memory, then you must also provide the pool_size option. If the pool_name refers to a shared memory object, then the pool is automatically sized to the size of the object (pool_size is ignored if provided). The io-audio service first tries to open the name as typed memory; if this fails, it tries to open the name as a shared memory object.

pool_size   The size of the DMA memory pool to create, in KB. If no pool_name is provided, then an anonymous object is created to the pool_size specified. If the pool_name refers to typed memory, then you must also provide the pool_size.
pcmPreferredp None The name of the preferred playback device; that is, the device snd_pcm_open_preferred() opens when SND_PCM_OPEN_PLAYBACK is specified.

For more information on how io-audio sets the preferred device, see “Preferred device selection”.

pcmPreferredc None The name of preferred capture device; that is, the device opened with snd_pcm_open_preferred() when SND_PCM_OPEN_CAPTURE is specified.

For more information on how io-audio sets the preferred device, see “Preferred device selection”.

smmu 0 Use the QNX System Memory Management Unit Manager (SMMUMAN).

If the smmuman service is running, specify 1 or on to configure io-audio to interface with smmuman to manage ("cage") access for non-CPU initiated reads and writes (i.e., DMA devices). Otherwise, specify 0 or off.

[AUDIOMGMT] section(s)

[AUDIOMGMT]sections include the following keys:

Key Default Description
audiomgmt_id None (Required) Name of the audio concurrency management context or output. PCM devices can attach to the audio concurrency management context or output using this identifier.
policy_conf None (Required) Path to the audio policy configuration file. The audio policy file contains audio concurrency management policies such as volume ramping and audio ducking for the system. For more information, see the “Audio Concurrency Management” chapter in the QNX Neutrino Audio Developer's Guide.
unit 0 Card number used in the filesystem mount. The card number (unit) must be unique.
Note: This key is used by the first [AUDIOMGT] section. Subsequent unit keys in other [AUDIOMGMT] sections are ignored.

[CTRL] section(s)

The keys in the [CTRL] section include the following:
Key Default Description
name None The name of the sound card HW interface DLL. Required; omit the deva-ctrl- prefix and the .so suffix when you're specifying the driver name.
options None Driver-specific options as documented for the sound card DLL.
As part of the card options, the following options can be specified for each PCM device:
  • dindex — the device number to which the following options apply
  • cap_name — the PCM capture device alias
  • play_name — the PCM playback device alias
  • output_classes — the output class used for DRM purposes. For valid values and their description, see the -d command line option.
  • restrict_interface — enable restricted access to the capture, playback, or both PCM device interfaces
For example, the following creates an alias for the capture and playback PCM device interfaces for device number 2 to devC and devP, respectively. 
options=dindex=2,cap_name=devC,play_name=devP
unit -1 Card or unit numbers must be unique, non-negative number. This value is used as the card number to mount the card on the filesystem.

If this key isn't provided or if the number is a negative, a unique value is generated with the first available number starting at zero. After io-audio starts, the unit (card) number corresponds to the DLL mounted as specified in the audio configuration file. These numbers are reserved for the life of io-audio and can be reused only if the corresponding DLL has previously been unmounted. For more information, see “ Driver-specific configuration file”.

input_splitter_enable 0 Enable or disable the input splitter on PCM devices that have a capture device (0 / 1). Append an optional _index suffix to the key to apply the option to a specific PCM device.

If you specify this parameter without an index suffix, the value applies to every capture-capable PCM device under the card created by this section.

If you specify this parameter with an index suffix, then the applied value (0/1) takes effect only for the PCM device specified by the index, overriding the value specified by an instance of the key without an index suffix.

To ensure that the input splitter can route data to a PCM software mixer device, both devices (input_splitter and PCM software mixer) must operate at the same data fragment size, which you set via the sw_mixer_ms option, and thus the sw_mixer_ms option is required when you're using the input splitter (even if the PCM software mixer device isn't being used).

Note: If you use the QNX Acoustic Management Platform 3.0, you must specify this parameter if multiple AFMs are capturing simultaneously from the same capture device on this sound card.
input_splitter_ms None

The input splitter fragment size, in milliseconds. No default.

To specify the fragment size for a specific PCM device, add an underscore and the device name to the key. For example, input_splitter_ms_0.

When this key is specified, it sets the PCM input splitter fragment size and overrides input_splitter_samples.

If neither input_splitter_ms nor input_splitter_samples are specified, the sw_mixer_ms value from the [CTRL] or [GLOBAL] section determines the size.

Note: You can only specify an integer for this option. However, if the configured sample rate is not a multiple of 4 kHz, a valid fragment size in milliseconds can't be expressed as an integer. To compensate, io-audio rounds down the value that you specify, taking into account various alignment restrictions (audio frame size, cache line size, etc.).

You must specify either this parameter (in the [CTRL] section) or sw_mixer_ms (in the [GLOBAL] or [CTRL] section) if any AFMs are configured to capture through the PCM input splitter on this card.

To route data between the PCM input splitter and the PCM software mixer via an AFM, both the splitter and mixer must use a data fragment size that can be divided exactly into the AFM’s fragment period. (You can use ms_frag_period to set the AFM's fragment period.)

For example, to configure a Bridge AFM to operate with 8 millisecond fragments, specify ms_frag_period=8. To configure a QNX Acoustics for Voice AFM to use smaller but compatible mixer and splitter fragment sizes, specify sw_mixer_ms=1 and input_splitter_ms=2.

For more information, see ms_frag_period in the [AFM] section.
input_splitter_samples None

The input splitter fragment size, in samples per voice. The minimum and maximum values you can use are determined by other parameters (sample size, voices, max_dma_buf_size). The default value for the max_dma_buf_size configuration is 256 KB.

Do not use if any AFMs are configured to capture through the PCM input splitter on this card.

If you set input_splitter_ms, it has priority over this key.

If you are streaming data from the input splitter to the software mixer, the fragment sizes need to be the same.

This key is set in the [CTRL] section only.

To specify the fragment size for a specific PCM input splitter, append an underscore and the device name to the key.
input_splitter_hw_sample_size None If the underlying capture hardware supports multiple data sizes (formats), this configuration key allows you to lock the input splitter format to a specific sample size (e.g., 8 (8-bit), 16 (16-bit), and so on).

If you do not use this key, the highest-quality format supported by the underlying hardware is selected by default.

To specify the sample size for a specific PCM Input splitter, append an underscore and the device name to the key.
input_splitter_rate FAHQ

The method for setting the PCM input splitter sample rate.

If the underlying hardware supports multiple sample rates, the specified method determines which sample rate applies to the splitter. The selection process may make use of two possible rate "families" — a set of rates that are multiples of 4 kHz and a set that are multiples of 11.025 kHz:

  • FA — First active; select the sample rate using the following process:
    1. Use the requested rate, if supported.
      1. Search the sample rate range for the next higher supported rate in the same rate family.
      2. Search the sample rate range for the next higher supported rate in the other rate family.
      1. Search the sample rate range for the next lower support rate in the same rate family.
      2. Search the sample rate range for the next lower support rate in the other rate family.
    4. Search the rates that are not part of either sample rate family (i.e., neither 4 kHz nor 11.025 kHz multiples).
    5. As a last resort, pick the highest available sample rate.
  • FAHQ (First active high quality) — If the requested rate is equal to or less than 48 kHz or 44.1 kHz:
    • If the requested rate is a multiple of 4 kHz, select 48 kHz.
    • If the requested rate is a multiple of 11.025 kHz, select 44.1 kHz.
    If the requested rate is greater than 48 kHz or 44.1 kHz, or if the requested rate of 48 kHz or 44.1 kHz is not supported, then search the sample rate range with the same method that is used for FA.
  • Lvalue — A specified, locked rate, where value is in the range 100–200000.

To specify the method for a specific PCM device, add an underscore and the device name to the key. For example, input_splitter_rate_0.
disable_sw_mixer 0 Disable the sw mixer (0 / 1). Append an optional _index suffix to the key to apply the option to a specific PCM device.

If the value of this parameter is 0, a PCM Software mixer is instantiated.

If it's 1, io-audio doesn't use software techniques to increase the maximum number of playing channels on cards that have only a single channel in hardware.

For a Bluetooth device, this should be 1 (disable the PCM software mixer).

This parameter overrides the corresponding option from the [GLOBAL] section or the command line for this card.

Note: If you use the QNX Acoustic Management Platform 3.0, this parameter must be 0 if AFMs are playing simultaneously to the same playback device on this sound card.
sw_mixer_ms See description

Set the PCM mixer fragment size, in milliseconds, for this card. This key overrides sw_mixer_samples and any fragment size specified in the [GLOBAL] section or at the command line.

If you don't specify this key, the fragment size specified in the [GLOBAL] section or at the command line is used; if no fragment size is specified in [GLOBAL] or at the command line, sw_mixer_samples sets the PCM mixer fragment size.

Note:
If any acoustic AFMs play back through a PCM software mixer, the following configuration is required:
  • sw_mixer_ms must be specified at the command line or in the [GLOBAL] or [CTRL] section
  • the sw_mixer_ms should be a factor of the acoustic library fragment size. If the hardware requires a sw_mixer_ms value that is larger than the acoustic library fragment size, you can set sw_mixer_ms to a multiple of the acoustic library fragment size. However, using a fragment size that is larger than the acoustic library fragment size will have an impact on the AFMs performance.

To specify the fragment size for a specific PCM device, add an underscore and the device name to the key. For example, sw_mixer_ms_0.

sw_mixer_samples 1024 The mixer fragment size, in samples per voice. It is overridden by sw_mixer_ms, if specified.

The minimum and maximum values you can use are determined by other parameters (sw_mixer_sample_size, voices, max_dma_buf_size).The default value for the max_dma_buf_size configuration is 256 KB.

Append an optional _index suffix to the key to apply the option to a specific PCM device.

Do not use if any AFMs are configured to capture through the PCM input splitter on this card.

This parameter overrides the corresponding option from the [GLOBAL] section or the command line for this card.

sw_mixer_rate FAHQ The method for setting the PCM software mixer sample rate. If the underlying hardware supports multiple sample rates, the specified method determines which rate the mixer uses. The selection process may make use of two possible rate "families" — a set of rates that are multiples of 4 kHz and a set that are multiples of 11.025 kHz:
  • FA — First active; select the sample rate using the following process:
    1. Use the requested rate, if supported.
    2. Search the sample rate range for the next higher supported rate in the same rate family.
    3. Search the sample rate range for the next higher supported rate in the other rate family.
    4. Search the sample rate range for the next higher supported rate that is not part of either sample rate family (i.e., not a multiple of 4 kHz or 11.025 kHz).
    5. Search the sample rate range for the next lower supported rate, regardless of the rate family.
    6. Select the maximum available sample rate.
  • FAHQ (First active high quality) — If the requested rate is equal to or less than 48 kHz or 44.1 kHz:
    • If the requested rate is a multiple of 4 kHz, select 48 kHz.
    • If the requested rate is a multiple of 11.025 kHz, select 44.1 kHz.
    If the requested rate is greater than 48 kHz or 44.1 kHz, or if the requested rate of 48 kHz or 44.1 kHz is not supported, search the sample rate range with the same method that is used for FA.
  • Lvalue — Lock to the specified rate, where value is in the range 100–200000.

This parameter overrides the corresponding option from the [GLOBAL] section or the command line for this card.

Append an optional _index suffix to the key to apply the option to a specific PCM device.

sw_mixer_sample_size None Specifies one of the following sample sizes for the PCM software mixer to use:
  • 16 — 16-bit signed, native endian
  • 32 — 32-bit signed, native endian

If you do not use this key, the sample size is determined by the sample size the underlying hardware uses.

  • If the hardware is 8- or 16-bit, the mixer uses signed, native endian
  • For 24- or 32-bit hardware, the mixer uses 32-bit signed, native endian

To specify the sample size for a specific PCM software mixer, append an underscore and the device name to the key. For example, sw_mixer_sample_size_0.

This parameter overrides the corresponding key from the [GLOBAL] section or the command line for this card.
sw_mixer_cap_name pcmCxDyp_ref The symbolic name for PCM software mixer's reference devices, where x is the numeric index of the card and y is the numeric index of the device. Append an optional _index suffix to the key to apply the option to a specific PCM device. If you create multiple PCM mixers, and you provide this key without an index suffix, then a name collision occurs, and the PCM mixer creation fails.
Note: If you have QNX Acoustics Management Platform 3.0, you can use the symbolic name instead of the PCM device name in the audio configuration file to simplify AFM device assignments.
sw_mixer_limiter 0 Enable the PCM software mixer limiter. Append an optional _index suffix to the key to apply the option to a specific PCM device.

If 1, enable a 1 ms soft look-ahead limiter on the main media mixing path through the PCM software mixer.

If 0, audio streams are strictly added and hard-clamped.

sw_mixer_max_references 0 The maximum number of media references available for capture from the PCM software mixer (maximum is 10).

This value should be equal to or greater than the total number of media references required by all configured AFMs. A reference is required for each pcm_media_capture device (used with ICC and QAV AFMs) that points to the PCM mixer reference capture device (typically specified by sw_mixer_cap_name).

Append an optional _index suffix to the key to apply the option to a specific PCM device.
audiomgmt_id None Name of the audio concurrency management context to be used. Append an optional _index suffix to the key to apply the option to a specific PCM device.
defer_mount 0 Set to 1 to defer mounting the card until the mount command is issued.

When set to 0, the card is mounted at startup.

Note: You use the following keys only if you have QNX Acoustic Management Platform 3.0.
input_splitter_tap 0

Enable an Acoustic Control Server (ACS) tap point in the input splitter.

Specify 1 to create a tap point that LiveAMP can stream or inject audio to using the ACS protocol, or 0 for no tap point.

Append an optional _index suffix to the key to apply the option to a specific PCM device.
sw_mixer_tap 0

Enable an Acoustic Control Server (ACS) audio tap point in the PCM software mixer.

Specify 1 to create a tap point that LiveAMP can stream or inject audio to using the ACS protocol, or 0 for no tap point.

Append an optional _index suffix to the key to apply the option to a specific PCM device.
Note: This option is intended for systems where Sound Field Optimization (SFO) or Speaker Management Module (SPM) are not being used and you still want access to the PCM mixer audio in LiveAMP. SPM and SFO have internal audio tap points that provide access to the PCM mixer audio; if they are enabled, you don't need to specify sw_mixer_tap.
sw_mixer_spm 0 Enable the SPM in the PCM software mixer.

Specify 1 to create a module, or 0 for no module.

Append an optional _index suffix to the key to apply the option to a specific PCM device.
sw_mixer_sfo 0 Enable the SFO module in the PCM software mixer.

Specify 1 to create a module, or 0 for no module.

Append an optional _index suffix to the key to apply the option to a specific PCM device.

spm_qcf None Specify the path to the SPM tuning file. The recommended directory is /etc/acoustic. For example:
spm_qcf=/etc/acoustic/spm.qcf

Append an optional _index suffix to the key to apply the option to a specific PCM device.

sfo_qcf None Specify the path to the SFO tuning file.

The recommended directory is /etc/acoustic. For example:

sfo_qcf=/etc/acoustic/sfo.qcf

Append an optional _index suffix to the key to apply the option to a specific PCM device.

spm_dataset_qcf_name None Specify the path to the SPM acoustic tuning file (.qcf).

The recommended directory is /etc/acoustic. For example:

The path to the dataset acoustic tuning file (.qcf) to apply when the dataset name is set with snd_pcm_load_apx_dataset().
sfo_dataset_qcf_name None Specify the path to the SFO acoustic tuning file (.qcf).

The recommended directory is /etc/acoustic. For example:

The path to the dataset acoustic tuning file (.qcf) to apply when the dataset name is set with snd_pcm_load_apx_dataset().
spm_libpath libqwa_spm.so Path to the SPM library. Append an optional _index suffix to the key to apply the option to a specific PCM device.
sfo_libpath libqwa_sfo.so Path to the SFO library. Append an optional _index suffix to the key to apply the option to a specific PCM device.
sw_mixer_spm_chmap The hardware channel mapping Specify channel mapping names within the mixer before SPM is applied.

Separate the channel name strings with colons (similar to how drivers overwrite their channel map; for example, fl:fr).

This mapping allows you to associate the correct channel names with channels within the mixer but does not change the mapping set in the SPM tuning file. It is only used when SPM is enabled.

The following channel name strings are valid: fl (front left), fr (front right), rl (rear left), rr (rear right), fc (front center), lfe (low-frequency effects (LFE)), sl (side left), sr (side right), rc (rear center), flc (front left center), frc (front right center), rlc (rear left center), rrc (rear right center), flw (front left wide), frw (front right wide), flh (front left high), fch (front center high), frh (front right high), tc (top center), tfl (top front left), tfr (top front right), tfc (top front center), trl (top rear left), trr (top rear right), trc (top rear center), tflc (top front left center), tfrc (top front right center), tsl (top side left), tsr (top side right), llfe (left LFE), rlfe (right LFE), bc (bottom center), blc (bottom left center), brc (bottom right center).

Append an optional _index suffix to the key to apply the option to a specific PCM device.
sfo_audio_type None Specify the name of the audio type used to calculate an internal user volume.

SFO calculates the internal user volume using the software mixer volume, the audio type volume, the codec volume, and the external volume. You can use snd_pcm_set_apx_user_volume() to override the calculated value.

Append an optional _index suffix to the key to apply the option to a specific PCM device.

csa_audio_type None Specify the name of the audio type used to create the CSA reference.

If the PCM mixer reference capture device (typically specified by sw_mixer_cap_name) is used as the pcm_ref_capture device for the CSA AFM, the CSA reference is a mix of all the subchannels whose audio type matches this key.

If this key is not specified (and the pcm_ref_capture device for the CSA AFM points at the PCM mixer reference capture device), the CSA reference is not created and the CSA AFM will not start.

Append an optional _index suffix to the key to apply the option to a specific PCM device.

csa_limiter 1 Enable the PCM software mixer limiter in the CSA mix audio path.

Specify 1 to enable a 1 ms soft look-ahead limiter on the CSA mixing path through the PCM software mixer.

Specify 0 to add the CSA mix strictly and make it hard-clamped.

Append an optional _index suffix to the key to apply the option to a specific PCM device.

afm_mixer_enable 0 Enable mixing of the AFM outputs separately from the media streams in the PCM software mixer.

Specify 1 to enable the AFM mixer or 0 to disable it. This value is discarded if there are no configured AFMs.

Append an optional _index suffix to the key to apply the option to a specific PCM device.
afm_mixer_max_references 0 The maximum number of AFM references available for capture from the AFM mixer (maximum is 10).

Append an optional _index suffix to the key to apply the option to a specific PCM device.

This value is discarded unless afm_mixer_enable is 1 and there are configured AFMs.

This value should be equal to or greater than the total number of AFM references (non-media) required by all configured AFMs. A reference is required for each pcm_ref_capture device that points to the PCM mixer reference capture device (typically specified by sw_mixer_cap_name). A minimum of one AFM reference is required for the ICC AFM if not using loopback as the reference. Using a reference with the QAV AFM is optional and depends on whether pcm_ref_capture is specified.

afm_mixer_atten_disable 0 Disable AFM mixer attenuation.

This value is discarded unless afm_mixer_enable is set to 1 and there are configured AFMs.

Normally, when the AFM mixer is enabled there is an implicit 6 dB attenuation of both the main (audio stream) and the AFM mixing paths in the PCM mixer, so that the combined output of these two paths with never need to be clamped, avoiding the audio artifacts which could arise when performing acoustic echo cancellation.

This implicit attenuation can be disabled for target systems where it is known that the AFM audio and media playback will never run concurrently. This can be true in systems where only the QAV AFM is integrated. However if integrating ASD or ICC, which do typically run concurrently with media playback, this key shouldn't be used.

If set to 1, the AFM mixer attenuation is disabled for all devices on a card; otherwise if set to 0, the AFM mixer attenuation is enabled for all devices.

Append an optional _index suffix to the key to apply the option to a specific PCM device.

max_concurrent_afms 0 The maximum number of AFMs that are expected to be concurrently active. This value is discarded unless afm_mixer_enable is set to 1 and there are AFMs that are configured.

Normally the AFM mixer gain is 1/afm_cnt to avoid clipping (non-linearity) when mixing, where afm_cnt is the number of AFMs, which have a pcm_local_playback device and an afm (default) sw_mixer_route. If you know that AFMs aren't going to be concurrently used, or if the AFMs are tuned correctly, this restriction can be overridden to a value less than afm_cnt.

If this value is set to 0, the key/value pair is ignored for all devices.

Append an optional _index suffix to the key to apply the option to a specific PCM device.

clock_domain 0 Identify a PCM device that is in a separate clock domain.

When an AFM is used to bridge hardware devices in separate clock domains, an asynchronous sample rate converter (ASRC) is created to translate between the domains.

Append an optional _index suffix to the key to apply the option to a specific PCM device.

[AFM] section(s)

Note: The [AFM] section is only available if you have installed QNX Acoustic Management Platform 3.0.
Note: The keys in this section that are prefixed with ap_ only apply to acoustic AFMs. Acoustic AFMs are associated with an acoustic processing library. Currently, the following acoustic AFMs are available:
  • ASD (QNX Active Sound Design)
  • CSA (QNX Chimes and Saftey Alerts)
  • ICC (QNX In-Car Communication)
  • QAV (QNX Acoustics for Voice)
The keys in the [AFM] section include the following:
Key Default Description
name None The name of the DLL, which is usually an AMP (Acoustic Management Platform) functional module (AFM); this parameter is required and must be one of the following modular libraries:
  • asd — QNX Active Sound Design (ASD) to use active-noise cancellation to reduce engine tones, as well as synthesize sound to support a manufacturer's vision of what their vehicle should sound like.
  • bridge — bridges audio inputs to audio outputs and assumes the clocking for the inputs and outputs is synchronized.
  • csa — QNX Chimes and Safety Alerts (CSA) to provide chime monitoring.
  • icc — QNX In-Car Communications (ICC) that provides algorithms to improve the ease of communication between passengers within a vehicle.
  • voice — QNX Acoustics for Voice (QAV) that provides algorithms to detect and extract voice from conditions that have lots of noise (wind, road, etc.).
Omit the deva-afm- prefix and the .so suffix when specifying the module name (e.g., icc corresponds to deva-afm-icc.so).
unit -1 Card number used in the filesystem mount. Card numbers must be unique. If this key isn't provided or if the value is a negative number, the first available, unique number after zero is generated for the AFM.
audio_type None Audio type that's used by the system to handle audio ducking. Not used with the CSA AFM.
pcm_local_capture None The name of the local capture device. Required for ICC, Voice, CSA, Bridge, and Recorder AFMs. Optional for ASD AFM.
pcm_local_playback None The name of the local playback device. Required for all AFMs except CSA and Recorder AFMs.
pcm_remote_capture None The name of the remote capture device. Required for the QAV AFM.
pcm_remote_playback None The name of the remote playback device. Required for the QAV AFM.
pcm_ref_capture None The name of the acoustic reference capture device. For ICC, if the value is loopback rather than a PCM device name, the ICC output is routed internally to the ICC reference input. Required for the ICC and CSA AFMs; optional for the QAV AFM.
pcm_media_capture None The name of the media reference capture device. Optional key for ICC and QAV AFMs.
map_mic_X A 1:1 mapping of the capture voice to library input (e.g., map_mic_0=0, map_mic_1=1, etc.)

Map the capture voice to the acoustic processing microphone input X.

  • Library inputs and capture voices are 0-based.
  • Maps of multiple captured voices are allowed per library input.
  • You must map all library inputs or none.
  • Maps for unused library inputs are ignored.
Note:

These keys are parsed when the AFM is initiated. If there are errors, the AFM does not start.

The Bridge AFM is a special case since this is a mapping from capture voice to playback voice rather than library input. And so, there are exceptions to Bridge AFMs:
  • Maps to multiple playback voices are allowed per capture voice.
  • Maps to multiple capture voices are allowed per playback voice.
  • Not all capture voices need to be mapped.
map_spk_X A 1:1 mapping of library output to playback voice (e.g., map_spk_0=0, map_spk_1=1, etc.).

Map acoustic processing speaker output X to playback voice(s); you can specify multiple voices, delimited by commas. Not applicable for Recorder and CSA AFMs.

  • Library outputs and playback voices are 0-based.
  • Maps to multiple voices are allowed per library output.
  • Maps of multiple library output are allowed per playback voice.
  • You must map all library outputs or none.
  • Maps for unused library outputs are ignored.
  • Maps for non-existent playback voices are ignored.
Note: When acoustic library volume and mute control is enabled (enable_vol_ctl) for an AFM, these keys are used to instantiate the corresponding mixer controls, so they are parsed when the AFM is loaded when io-audio starts. If there are errors, io-audio doesn't start.

If there is no acoustic volume control, these keys are parsed when the AFM is started. If there are errors, the AFM does not start.
threshold 0

The ASD sample asset priority threshold. Valid values are from 0 to 100. This is optional for ASD AFM.

You should include ASD playback in the audio management policy when sw_mixer_route= main, ASD is actively playing a sample asset, and the ASD MaxPriority parameter is >= audio management threshold. This configuration selectively ducks other io-audio streams (with same or lower priority audio_type) only when high-priority ASD sample assets are playing.

If the audio management threshold is not set, the sample asset priority is not considered when determining inclusion in the audio management policy.

Note: The threshold setting only works as expected when ASD is ducking other io-audio subchannels. If other subchannels duck ASD then the behavior is opposite of what you would expect. The high priority ASD audio gets ducked but the lower priority ASD audio does not. This is because the lower priority ASD audio does not meet the threshold and hence, it does not enable audio ducking.
map_ref_X A 1:1 mapping of acoustic reference voice to library reference input (e.g., map_ref_0=0, map_ref_1=1, etc.) Map the acoustic reference voice to acoustic processing reference input X. You can specify multiple voices, delimited by commas.

ICC, CSA and QAV AFMs only.

  • Library inputs and capture voices are 0-based.
  • Maps of multiple capture voices are allowed per library input.
  • You must map all library inputs or none.
  • Maps for unused library inputs are ignored.

These keys are parsed when the AFM is started; if there are errors, the AFM doesn't start.
map_ref_media_X A 1:1 mapping of media reference voice to library external reference input (e.g., map_ref_media_0=0, map_ref_media_1=1, etc.) Map a media reference capture voice to acoustic processing external reference input X. You can specify multiple voices, delimited by commas.

ICC and QAV AFMs only.

  • Library inputs and capture voices are 0-based.
  • Maps for unused library inputs are ignored.
  • Maps of multiple capture voices are allowed per library input.

These keys are parsed when the AFM is started; if there are errors, the AFM doesn't start.
map_rem_uplink_X A 1:1 mapping of acoustic reference voice to library reference input (e.g., map_ref_0=0, map_ref_1=1, etc.) Map the acoustic reference voice to acoustic processing reference input X. You can specify multiple voices, delimited by commas.

QAV AFM only.

  • Library inputs and capture voices are 0-based.
  • Maps of multiple capture voices are allowed per library input.
  • Maps for unused library inputs are ignored.

These keys are parsed when the AFM is started; if there are errors, the AFM doesn't start.
map_rem_dnlink_X A 1:1 mapping of acoustic reference voice to library reference input (e.g., map_ref_0=0, map_ref_1=1, etc.) Map the acoustic reference voice to acoustic processing reference input X. You can specify multiple voices, delimited by commas.

QAV AFM only

  • Library inputs and capture voices are 0-based.
  • Maps of multiple capture voices are allowed per library input.
  • Maps for unused library inputs are ignored.

These keys are parsed when the AFM is started; if there are errors, the AFM doesn't start.
ap_dlname The acoustic processing DLL name corresponding to the AFM type:
  • asd: libqwa_asd.so
  • csa: libqwa_csa.so
  • icc: libqwa_icc.so
  • voice: libqwa_qvp.so
 Acoustic processing library .so name
ap_qcf_default None The path to the acoustic tuning file when in the default audio mode. QNX recommends that you store tuning files in the directory /etc/acoustic (for example, ap_qcf_default=/etc/acoustic/handsfree.qcf).

The default audio mode is used when a mode is not set using the libasound library snd_afm_set_audio_mode() function.

See “AFM” section below for operation with or without a qcf specified.
ap_qcf_mode None The path to the acoustic tuning file to use when in the specified mode.

mode is a string set using the libasound library snd_afm_set_audio_mode() function. It specifies an audio mode that corresponds to a particular audio environment.

  • ap_qcf_nb
  • ap_qcf_wb
 None These keys are paths to QCF files that contain acoustic configurations unique to the sample rate modes specified below.
  • ap_qcf_nb - 8000 Hz
  • ap_qcf_wb - 16000 Hz
ap_samp_play_dir_default None The path to the acoustic sample player directory.

ASD AFM only.

Binaries targeted for deferred load must be placed into a subdirectory (e.g.,path/deferred) of the specified path.
ap_samp_play_dir_mode None

The path to the acoustic sample player directory when the mode string is set by snd_afm_set_audio_mode(). ASD AFM only.

Binaries targeted for deferred load must be placed into a subdirectory (e.g.,path/deferred) of the specified path.
ap_gran_syn_dir_default None The path to the acoustic granular synthesis files to use when in the default mode. ASD AFM only.

The default audio mode is used when a mode is not set using the libasound library snd_afm_set_audio_mode() function.

Binaries targeted for deferred load must be placed into a subdirectory (e.g.,path/deferred) of the specified path.
ap_gran_syn_dir_mode None The path to the acoustic granular synthesis files to use when in the specified mode. ASD AFM only.

mode is a string set using the libasound library snd_afm_set_audio_mode() function. It specifies an audio mode that corresponds to a particular audio environment.

Binaries targeted for deferred load must be placed into a subdirectory (e.g.,path/deferred) of the specified path.
ap_calib_default None The path to the acoustic calibration file (ASD and CSA AFMs only) or beamformer calibration directory (QAV AFM only) to use when in the default mode.

The default audio mode is used when a mode is not set using the libasound library snd_afm_set_audio_mode() function.
ap_calib_mode None The path to the acoustic calibration file (ASD and CSA AFMs only) or beamformer calibration directory (QAV AFM only) to use when in the specified mode.

mode is a string set using the libasound library snd_afm_set_audio_mode() function. It specifies an audio mode that corresponds to a particular audio environment.

ap_dataset_qcf_name None The path to the dataset QCF to apply when the dataset name string is set with snd_afm_load_ap_dataset().
ap_enable_diagnostics 0 Enable acoustic library diagnostics; ICC and QAV AFMs only.

If 0, the baseline settings don't turn on diagnostics in the acoustic library. If 1, the baseline settings enable the diagnostics module in the acoustic library. Note that the baseline settings can be overridden by the QCF file.

enable_pass_through 0

Enable pass through. If 0, the acoustic processing library is used. If 1, the acoustic enable_pass_through 0 processing library is neither loaded nor used and the audio data is copied from the input to the output of the AFMs.

Note: This option can result in extreme feedback in the case of the ICC and Bridge AFMs.
pcm_play_name voicep The symbolic name for the PCM interface published for playback. QAV AFM only.
pcm_cap_name voicec The symbolic name for the PCM interface published for capture. QAV AFM only.
pcm_disable 0 Disable PCM interface. QAV AFM only. If 0, the voice PCM interface is enabled; if 1, it's disabled.
pcm_play_low_latency 0 Enable low latency PCM playback. QAV AFM only.

If 0, low latency PCM playback is not enabled.

If 1, low latency PCM playback is enabled. When enabled, applications calling snd_pcm_plugin_params() configure playback for the voice PCM device that specifies a frags_max of 0. This eliminates one 16 ms fragment in the processing path in the PCM mode.

If 2, low latency PCM playback is forced. Playback for all applications using the voice PCM device will have frags_max overridden to 0.
sw_mixer_route afm The route to use when mixing playback audio (main or afm) in the PCM software mixer.
  • When the value is afm, playback audio is routed through the AFM mixer path in the PCM software mixer.
  • When the value is main, playback audio is routed through the main (media) path in the PCM software mixer.
Normally, you do not specify this value and it defaults to afm. You typically use main with the Bridge or Player AFMs, where acoustic processing is not performed and the output is expected to be included in the main (media) reference. The main value is also used with the ASD AFM when it is operating as a chime generator. When playing through the main mixing path, the ASD AFM is subject to the rules of the configured audio policy. You need to specify a suitable audio_type for the ASD AFM to allow it to duck or be ducked as needed.
ms_frag_period sw_mixer_ms (when the local playback device is a PCM Software Mixer device) The fragment size, in milliseconds, to use for audio hardware interfacing.
When the local playback device is a PCM software mixer, the value of this key:
  • defaults to sw_mixer_ms
  • if set, must be a multiple of sw_mixer_ms
This key must be explicitly specified:
  • if the local playback device is not a PCM software mixer
  • for Bridge AFMs

For acoustic AFMs, the value of ms_frag_period should be a factor of the acoustic library fragment period.

If the hardware requires a sw_mixer_ms value (and, implicity, ms_frag_period) that is larger than the acoustic library fragment size, you can set ms_frag_period to a multiple of the acoustic library fragment size. However, using a fragment size that is larger than the acoustic library fragment size will have an impact on the AFMs performance.

slip_guard_frags 1 Specify how many additional fragments to add in the playback path to ensure consistent startup timing.

If set to 0 (zero), audio is buffered on the playback path by either the maximum of the acoustic library fragment period or ms_frag_period, whichever is larger. Each additional slip guard fragment you specify adds an additional period of latency as specified by ms_frag_period.
enable_vol_ctl 0 Enable acoustic library volume and mute control; ICC and QAV AFMs only.

If 0, volume control, that uses the acoustic library gain and mute controls is disabled. If 1, a mixer group that uses the acoustic library gain and mute controls (ICC gain or QAV Gain) to adjust the volume is published.

Note: If both enable_vol_ctrl and enable_mute_ctrl_only are set to 1, enable_vol_ctl takes precedence.
enable_mute_ctl_only 0 Only enable acoustic library mute control; ICC and QAV AFMs only.

If 0, mute control using the acoustic library and gain control is disabled. If 1, a mixer interface that uses the acoustic library mute controls to perform muting is published. This key is used if mute control is required, but the library QCF (.qcf) configuration file is used to set a fixed library gain value.

Note: If both enable_vol_ctrl and enable_mute_ctrl_only are set to 1, enable_vol_ctl takes precedence.
max_vol_db_X
  • ICC: 20 dB
  • QAV: 20 dB
 The maximum output fixed gain setting for speaker output X corresponding to 100% volume set with mix_ctl. This key is ignored if enable_vol_ctl is set to 0. ICC and QAV AFMs only.

This parameter must be >= min_vol_db. If this value is set beyond the ICC/QAV library maximum of 40 dB, a warning is logged, but the value is accepted.

min_vol_db_X
  • ICC: -20 dB
  • QAV: -20 dB
 The minimum output fixed gain setting for speaker output X corresponding to 0% volume set with mix_ctl. This key is ignored if enable_vol_ctl is set to 0. ICC and QAV AFMs only;

This parameter must be <= max_vol_db. If this value is set beyond the ICC/QAV library minimum of -30 dB, a warning is logged, but the value is accepted.

init_vol_X
  • ICC: 50
  • QAV: 50

The initial AFM volume setting at boot (0-num_vol_steps) for speaker output X. This key is ignored if enable_vol_ctl is set to 0. Applicable for ICC and QAV AFMs only. If the key value is out of range, it is rounded to be between 0 to num_vol_steps inclusive.
num_vol_steps 100 The number of volume steps for the mixer volume control. It maps the range of steps to the specified number of steps between 0 to 100 percent of the range defined by min_vol_db and max_vol_db. For example, if the number of steps is 5, step 5 is equal to 50 percent of the max_vol_db value.

This is adjustable in QAV AFM only. Currently, the value is parsed by ICC but you should either leave it out or set it to 100.

It must be set to a value between 1 to 100 inclusive or not set. Not setting it will default it to 100. Doing neither will cause the AFM operation to fail.
start_on_boot 0 If 1, start the AFM when io-audio starts, after all cards and AFMs have been successfully loaded; if 0, the AFM is idle after io-audio starts.
master capture Master channel for bridge audio transfer; Bridge AFM only.

The Bridge is an AFM that connects audio between two devices. For example, it captures audio from a microphone input and plays it out to a speaker output. It times itself on the hardware capture and playback interrupts.

The Bridge can use only capture interrupts, playback interrupts, or both for timing. When capture or playback is specified as a value for this key, input is captured and played out when an interrupt occurs on the specified channel. When both is specified, both capture and playback interrupts are used. Audio is input when a capture interrupt occurs and played out when a playback interrupt occurs.

resync_on_xrun 0 Force audio resynchronization when an overrun or an underrun occurs; Bridge AFM only.

When set to 1, audio is restarted when overrun or underrun is detected. When set to 0, no correction will be performed if an overrun or underrun is detected.

artifact_protection 0 Clear the capture buffer before advancing internal references (pointers) to it. Bridge AFM only.

When set to 1, once capture audio is written to the playback buffer, clear and silence the capture buffer. This prevents stale data from being left behind. When set to 0, the capture buffer isn't overwritten with silence.

sym_name Same as the AFM name specified by name Symbolic name for the AFM that you can use with snd_afm_open_name() and utilities such as afm_ctl to access the AFM.

This key can be used to differentiate between AFMs if your configuration has multiple AFMs of the same type. For example, if there are multiple bridges, set the symbolic names to bridge1, bridge2, and so on, and access them with afm_ctl -a bridge1 or afm_ctl -a bridge2.
pcm_mode_remote_frags 1 Number of remote fragments used for QAV PCM mode, which are used to compensate for variable-interrupt timing.

This key/value fair can be used to compensate for variable interrupt timing. For example, if local card interrupts occurs in a cycle of 12ms/18ms/18ms, instead of 16 ms, data may be dropped. Increasing the number of remote fragments to be 2 (or higher) compensates for this inconsistency at a the cost of a higher round trip latency.

defer_mount 0 Defer mounting of the DLL until a later time.

When set to 0, the card is mounted at startup. When set to 1, mounting of the card is deferred until the mount command is issued. The acoustics option can be used with the mount command to mount all AFM cards that were deferred.

local_rate_default 0 Sample rate to use when you open pcm_local_capture and pcm_local_playback when in the default audio mode. If you do not specify this key, the highest sample rate that the underlying hardware supports is used.

The default audio mode is used when a mode is not set using the libasound library snd_afm_set_audio_mode() function.

Applies to acoustic AFMs only.

  • 0 — Open the devices at the highest supported sample rate.
  • Non-zero — Open the devices at the specified rate.
local_rate_mode 0 Sample rate to use when you open pcm_local_capture and pcm_local_playback devices when in the specified audio mode. If you do not specify this key, the highest sample rate that the underlying hardware supports is used.

mode is a string set using the libasound library snd_afm_set_audio_mode() function. It specifies an audio mode that corresponds to a particular audio environment. For example, for Bluetooth hands-free phone calls that operate at 8 kHZ (narrowband) and 16 kHz (wideband), you can create the corresponding modes "nb" and "wb". To apply sample rates other than the default to these modes, create keys local_rate_wb and local_rate_nb.

Applies to acoustic AFMs only.
  • 0 — Open the devices at the highest supported sample rate.
  • Non-zero — Open the devices at the specified rate.
remote_rate_default 0 Sample rate to use when you open pcm_remote_capture and pcm_remote_playback when in the default audio mode. If you do not specify this key, the highest sample rate that the underlying hardware supports is used.

The default audio mode is used when a mode is not set using the libasound library snd_afm_set_audio_mode() function.

Applies to the QAV AFM only.

  • 0 — Open the devices at the highest supported sample rate.
  • Non-zero — Open the devices at the specified rate.
remote_rate_mode 0 Sample rate to use when you open pcm_remote_capture and pcm_remote_playback devices when in the specified audio mode.

For information on mode, see local_rate_mode.

Applies to the QAV AFM only.

  • 0 — Open the devices at the highest supported sample rate.
  • Non-zero — Open the devices at the specified rate.
ref_rate_default 0 Sample rate to use when you open any reference device (e.g., pcm_ref_capture) when in the default audio mode.

The default audio mode is used when a mode is not set using the libasound library snd_afm_set_audio_mode() function.

Applies to acoustic AFMs only.

  • 0 — Open the reference devices at the highest supported sample rate.
  • Non-zero — Open the devices at the specified rate.
ref_rate_mode 0 Sample rate to use when you open any reference device (e.g., pcm_ref_capture) when in the specified audio mode.

For information on mode, see local_rate_mode.

Applies to acoustic AFMs only.

  • 0 — Open the reference devices at the highest supported sample rate.
  • Non-zero — Open the devices at the specified rate.
ep_notify_default 0 Enable endpoint notifications when the audio is considered "voiced" or "non-voiced" in the default audio mode. Clients can read notifications using snd_ctrl_read().

The default audio mode is used when a mode is not set using the libasound library snd_afm_set_audio_mode() function.

  • 0 — Disable voiced endpoint notifications when in the default audio mode.
  • 1 — Enable voiced endpoint notifications when in the default audio mode.

Applies to the QAV AFM only. For more information, see the QNX Acoustics for Voice Developer’s Guide.

ep_notify_mode 0

Enable endpoint notifications when the audio is considered "voiced" or "non-voiced" in the specified audio mode.

  • 0 — Disable voiced endpoint notifications when in the specified audio mode.
  • 1 — Enable voiced endpoint notifications when in the specified audio mode.

For information on mode, see local_rate_mode.

Applies to the QAV AFM only. For more information, see the QNX Acoustics for Voice Developer’s Guide.

ep_min_voiced 300

Specify the minimum duration of a voiced event that produces an endpoint notification, in milliseconds. A voiced event that is shorter than this value does not produce a notification.

Applies to the QAV AFM only. For more information, see the QNX Acoustics for Voice Developer’s Guide.
ep_min_non_voiced 200

Specify the minimum duration of a non-voiced event that produces an end-of-speech notification, in milliseconds. If the time between two voiced events is shorter than this value, they are handled as one event.

Applies to the QAV AFM only. For more information, see the QNX Acoustics for Voice Developer’s Guide.
buffer_ms 5000

Specify the maximum time to buffer audio, in milliseconds.

Applies to the TAADIS AFM only.

[ACS] section(s)

Note: The [ACS] section is only available if you have installed QNX Acoustic Management Platform 3.0.
The keys in the [ACS] section include the following:
Key Default Description
name None The name of the link. This is a required key.

The deva-acs- prefix and the .so suffix are omitted when specifying the module name. For example, link corrsponds to deva-acs-link.so. The link module is a special type of AFM that integrates the Acoustic Control Server (ACS) for tuning purposes; it performs no acoustic processing.
unit -1 Card number used in the filesystem mount. Card numbers must be unique. If this key isn't provided or if the value is a negative number, the first available, unique number after zero is generated.
enable_acs None (Required) Enable the ACS link.

When set to 1, the Link AFM is available to be started. When set to 0, the link AFM isn't available and can't be started.
server_port 4000 The ACS TCP/IP server port.
ms_frag_period None Not used.
tap_split_cap None Not used.
tap_media_ref None Not used.
defer_mount 0 Defer mounting of the DLL until a later time.

When set to 0, the card is mounted at startup. When set to 1, mounting of the card is deferred until the mount command is issued. The acoustics option can be used with the mount command to mount all AFM cards that were deferred.

After the DLL is mounted, it cannot be unmounted.

Here's an example of an audio configuration file: 
[global]
verbosity=3
sw_mixer_ms=2

########################################
# Audio Concurrency Management Output Context
########################################
[audiomgmt]
audiomgmt_id=Zone1
policy_conf=/etc/system/config/audio/audio_policy_zone1.conf

########################################
# On-board audio
########################################
# This card's PCM software mixer and input splitter will be the preferred devices
[ctrl]
name= your_driver_name
options= your_driver_specific_options
input_splitter_enable=1
sw_mixer_ms=16
audiomgmt_id=Zone1

Preferred device selection

When you use snd_pcm_open_preferred() to open an audio interface, the function attempts to open the device configured as the preferred device.

The io-audio service searches for the preferred device to use in the following system resources and order:

  1. The /etc/system/config/audio/preferences file. This file uses the following format, with a tab character between the fields: 
    pcmPreferredp    card_name    device_number
pcmPreferredc    card_name    device_number

    The io-audio service compares available card names to the preferred card name in the following order and selects the first card name that matches:

    1. the card long name, as an exact match
    2. the card short name, as an exact match
    3. a substring that matches the start of the card name

    (The card name is set by the driver code and can be queried via card_get_longname(), card_get_name(), and so on.)

  2. In the [GLOBAL] section of the audio configuration file, the device specified by pcmPreferredp, pcmPreferredc, or both.
  3. The first valid playback or capture device. (The order of devices is based on the deva-* load order.)

Whenever a new device is mounted or unmounted, io-audio repeats the search and updates the preferred device if it finds a better match.

Driver-specific configuration file

The driver-specific configuration uses [CTRL] sections as defined in the “Audio configuration file” section. For more information, see the “Description” section above. For example, if you wanted to use the configuration for a mcasp driver (deva-ctrl-mcasp.so), you could dynamically mount driver with the following mount command: 
mount -T io-audio -o conf=mydriver.conf deva-ctrl-mcasp.so
Here's the example mydriver.conf file that corresponds to the above command: 
[CTRL]
name=mcasp
options=clk_mode=master

Examples:

Start io-audio and load the audio configuration from a file: 

io-audio -c /etc/system/config/audio/io-audio.conf

Load the AudioPCI driver, specifying the size of the DMA memory pool as 512 KB: 

io-audio -vv -m pool_size=512 -d audiopci

Lock the sample rate to 8 kHz (if the hardware supports 8 kHz natively): 

io-audio -o sw_mixer_rate=L8000 -d my_audio_driver

Start an audio driver, specifying the card options: 

io-audio -d my_audio_driver cap_name=capture,play_name=playback

The /dev/snd directory will look something like this: 

# ls -l /dev/snd
total 0
lrw-rw-rw- 1 root root 0 May 31 11:11 capture -> pcmC0D0c
-rw-rw-rw- 1 root root 0 May 31 11:11 controlC0
-rw-rw-rw- 1 root root 0 May 31 11:11 mixerC0D0
-rw-rw-rw- 1 root root 0 May 31 11:11 pcmC0D0c
-rw-rw-rw- 1 root root 0 May 31 11:11 pcmC0D0p
lrw-rw-rw- 1 root root 0 May 31 11:11 pcmPreferredc -> pcmC0D0c
lrw-rw-rw- 1 root root 0 May 31 11:11 pcmPreferredp -> pcmC0D0p
lrw-rw-rw- 1 root root 0 May 31 11:11 playback -> pcmC0D0p

Files:

In addition to the deva-ctrl-*, deva-afm-*, and dev-acs-link drivers, the io-audio command can load the following shared objects:

deva-mixer-ac97.so
Mixer DLL for the AC97 codec.
deva-mixer-ak4531.so
Mixer DLL for the AK4531 codec.
deva-mixer-hda.so
Mixer DLL for High Definition Audio codecs.
deva-util-restore.so
Shared object used to restore an audio driver's state.
Related reference
deva-ctrl-audiopci.so
deva-ctrl-intel_hda.so
deva-ctrl-usb.so
deva-mixer-ac97.so
deva-mixer-ak4531.so
deva-mixer-hda.so
deva-util-restore.so
mix_ctl
Parent topic: I