ALSA project - the C library reference
Control interface

Control interface is designed to access primitive controls. There is also an interface for notifying about control and structure changes.

General overview

In ALSA control feature, each sound card can have control elements. The elements are managed according to below model.

Identifying Elements

Each element has the following identifying properties:

An element can be identified either by its short numid or by the full set of fields (interface type, device, subdevice, name, index). This set of fields is always the same (driver updates can change it, but in practice this is rare). The numid can change on each boot. In case of an USB sound card, the numid can also change when it is reconnected. The short numid is used to reduce the lookup time.

Element Lists

An element list can be used to obtain a list of all elements of the sound card. The list contains generic information (e.g. how many elements the card has), and the identifying properties of the elements (numid, card, name, ...). See snd_ctl_elem_list_t to learn more about element lists.

Working with Elements

It is possible to obtain information about an element using the snd_ctl_elem_info_*() functions. For enums, the allowed values can be obtained, for integers, the min/max values can be obtained, and so on. In addition, these functions can report the identifying properties. E.g. when the element is addressed using its numid, the functions complements the name, index, etc.

To access the members (i.e. values) of a control, use the snd_ctl_elem_value*() functions. These allow to get and set the actual values or settings. It is also possible to get and set the ID values (such as the numid or the name).

Element Sets

The type of element set is one of integer, integer64, boolean, enumerators, bytes and IEC958 structure. This indicates the type of value for each member in elements included in the element set.

Events

When the value of a member is changed, corresponding events are transferred to userspace applications. The applications should subscribe any events in advance.

Supplemental data for elements in an element set

TLV feature is designed to transfer data in a shape of Type/Length/Value, between a driver and any userspace applications. The main purpose is to attach supplement information for elements to an element set; e.g. dB range.

At first, this feature was implemented to add pre-defined data readable to userspace applications. Soon, it was extended to handle several operations; read, write and command. The original implementation remains as the read operation. The command operation allows drivers to have own implementations against requests from userspace applications.

This feature was introduced to ALSA control feature in 2006, at commit c7a0708a2362, corresponding to a series of work for Linux kernel (42750b04c5ba and 8aa9b586e420).

There's no limitation about maximum size of the data, therefore it can be used to deliver quite large arbitrary data from userspace to in-kernel drivers via ALSA control character device. Focusing on this nature, as of 2016, some in-kernel implementations utilize this feature for I/O operations. This is against the original design.