alsa_ctl (alsa v0.3.0)

Access to the controls of an ALSA sound card.

The controls of a sound card, such as the volume or the switch of an output, are exposed by its CTL as control elements. Open a CTL with open/1, list its elements with elem_list/1, get information about an element with elem_info/2, read and write the value of an element with elem_read/2 and elem_write/3, and close the CTL with close/1.

The CTL handle is closed automatically if the process that opened it terminates.

Summary

Types

ctl()

A handle to a CTL.

elem_id()

Identifies a control element.

elem_id_matcher()

Selects a control element, either by its numeric identifier or by its name.

elem_info()

Describes a control element. count is the number of values of the element, and type is the type of those values

elem_value()

The value of a control element. The value of an element of type bytes is a binary of count bytes. The value of any other element is a tuple with count entries, which are booleans, integers, or item names (strings) depending on the type of the element.

Functions

close(CTL)

Closes a previously opened CTL handle.

elem_info(CTL, Id)

Gets information about a control element.

elem_list(CTL)

Lists the control elements of a CTL.

elem_read(CTL, Id)

Gets the value of a control element.

elem_write(CTL, Id, Value)

Sets the value of a control element. Integer values are limited to the range of the element.

open(Name)

Opens a CTL. The returned CTL handle will be closed automatically if the opening process terminates.

Types

ctl()

-opaque ctl()

A handle to a CTL.

elem_id()

-type elem_id() ::
          #{numid := integer(),
            interface := card | mixer | pcm | rawmidi | timer | sequencer,
            name := string(),
            index := non_neg_integer(),
            device := non_neg_integer(),
            subdevice := non_neg_integer()}.

Identifies a control element.

numid - the numeric identifier of the element
interface - the interface the element belongs to
name - the name of the element
index - the index of the element
device - the device number of the element
subdevice - the subdevice number of the element

elem_id_matcher()

-type elem_id_matcher() :: #{numid := integer()} | #{name := string()}.

Selects a control element, either by its numeric identifier or by its name.

elem_info()

-type elem_info() ::
          #{type := boolean, count := non_neg_integer()} |
          #{type := integer, count := non_neg_integer(), min := integer(), max := integer()} |
          #{type := enumerated, count := non_neg_integer(), items := [string()]} |
          #{type := bytes, count := non_neg_integer()}.

Describes a control element. count is the number of values of the element, and type is the type of those values:

boolean - each value is true or false
integer - each value is an integer between min and max
enumerated - each value is one of the names in items
bytes - the value is a binary of count bytes

elem_value()

-type elem_value() :: binary() | tuple().

Functions

close(CTL)

-spec close(ctl()) -> ok | {error, Error} when Error :: closed | pos_integer().

Closes a previously opened CTL handle.

CTL - the CTL handle to close

Returns ok on success otherwise an error.

elem_info(CTL, Id)

-spec elem_info(ctl(), elem_id_matcher()) -> {ok, elem_info()} | {error, Error}
                   when Error :: pos_integer() | enotsup.

Gets information about a control element.

CTL - the CTL handle
Id - selects the element

Returns the information about the element on success otherwise an error. The error is enotsup when the type of the element is not supported.

elem_list(CTL)

-spec elem_list(ctl()) -> {ok, [elem_id()]} | {error, Error} when Error :: pos_integer().

Lists the control elements of a CTL.

CTL - the CTL handle

Returns the identifiers of the elements on success otherwise an error.

elem_read(CTL, Id)

-spec elem_read(ctl(), elem_id_matcher()) -> {ok, elem_value()} | {error, Error}
                   when Error :: pos_integer() | enotsup.

Gets the value of a control element.

CTL - the CTL handle
Id - selects the element

Returns the value of the element on success otherwise an error. The error is enotsup when the type of the element is not supported.

elem_write(CTL, Id, Value)

-spec elem_write(ctl(), elem_id_matcher(), elem_value()) -> ok | {error, Error}
                    when Error :: pos_integer() | enotsup.

Sets the value of a control element. Integer values are limited to the range of the element.

CTL - the CTL handle
Id - selects the element
Value - the new value of the element

Returns ok on success otherwise an error. The error is enotsup when the type of the element is not supported.

open(Name)

-spec open(string() | binary()) -> {ok, ctl()} | {error, Error} when Error :: enomem | pos_integer().

Opens a CTL. The returned CTL handle will be closed automatically if the opening process terminates.

Name - ASCII identifier of the CTL handle

Returns a handle to the CTL device on success otherwise an error.