alsaucm

ALSAUCM(1)                  General Commands Manual                 ALSAUCM(1)

NAME
       alsaucm - ALSA Use Case Manager

SYNOPSIS
       alsaucm <options> [command]

DESCRIPTION
       alsaucm  (ALSA  Use Case Manager) is a program to use the ALSA Use Case
       Interface from the command line.

       On complex sound cards, setting up audio  routes  is  not  trivial  and
       mixer  settings  can  conflict one another preventing the audio card to
       work at all.

       The ALSA Use Case Manager is a mechanism for controlling complex  audio
       hardware  establishing  a  relationship between hardware configurations
       and meaningful use cases that the end-user can relate with.

       The use case manager can also be used to switch between use cases  when
       necessary, in a consistent way.

       At  a  lower level, the use case manager works by configuring the sound
       card ALSA kcontrols to change the hardware  digital  and  analog  audio
       routing to match the requested device use case.

       The use case manager kcontrol configurations are stored in easy to mod-
       ify text files. An audio use case can be defined by a verb  and  device
       parameter.

       The  verb describes the use case action i.e. a phone call, listening to
       music, recording a conversation etc. The device describes the  physical
       audio  capture  and  playback  hardware i.e. headphones, phone handset,
       bluetooth headset, etc.

OPTIONS
       Available options:

          -h, --help
                 this help

          -c, --card NAME
                 open card NAME

          -i, --interactive
                 interactive mode

          -b, --batch FILE
                 batch mode (use '-' for the stdin input)

          -n, --no-open
                 do not open first card found

       Available commands:

          open NAME
                 open card NAME.

                 valid   names   are   sound   card   names   as   listed   in
                 /usr/share/alsa/ucm.

          reset  reset sound card to default state.

          reload reload configuration.

          listcards
                 list available cards.

          list IDENTIFIER
                 list  command,  for  items  returning two entries (value+com-
                 ment).

                 the value of the IDENTIFIER argument can can be:

                 o _verbs - get verb list (in pair verb+comment)

                 o _devices[/{verb}] - get list of supported devices (in  pair
                   device+comment)

                 o _modifiers[/{verb}]  -  get list of supported modifiers (in
                   pair modifier+comment)

                 The forms without the trailing /{verb} are valid only after a
                 specific verb has been set.

          list1 IDENTIFIER
                 list command, for lists returning one item per entry.

                 the  value  of  the IDENTIFIER argument can vary depending on
                 the context, it can be:

                 o TQ[/{verb}] - get list of Tone Quality identifiers

                 o _enadevs - get list of enabled devices

                 o _enamods - get list of enabled modifiers

                 o _supporteddevs/{modifier}|{device}[/{verb}] - list of  sup-
                   ported devices

                 o _conflictingdevs/{modifier}|{device}[/{verb}]   -  list  of
                   conflicting devices

          get IDENTIFIER
                 get string value.

                 the value of the IDENTIFIER argument can can be:

                 o _verb - return current verb

                 o [=]{NAME}[/[{modifier}|{/device}][/{verb}]]   (For    valid
                   NAMEs look at the ALSA Use Case Interface)

          geti IDENTIFIER
                 get integer value.

                 the value of the IDENTIFIER argument can can be:

                 o _devstatus/{device}

                 o _modtstaus/{device}

          set IDENTIFIER VALUE
                 set string value

                 The value of the IDENTIFIER argument can can be:

                 o _verb - set the verb to VALUE

                 o _enadev - enable the device specified by VALUE

                 o _disdev - disable the device specified by VALUE

                 o _swdev/{old_device} - switche device:

                   o disable  old_device  and then enable the device specified
                     by VALUE

                   o if no device was enabled just return

                 o _enamod - enable the modifier specified by VALUE

                 o _dismod - disable the modifier specified by VALUE

                 o _swmod/{old_modifier} - switch modifier:

                   o disable old_modifier and then enable the modifier  speci-
                     fied by VALUE

                   o if no modifier was enabled just return

                 Note  that the identifiers referring to devices and modifiers
                 are valid only after setting a verb.

          h, help
                 help

          q, quit
                 quit

FILES
       The master use  case  files  for  each  supported  sound  card  are  in
       /usr/share/alsa/ucm.

       For  example,  the  master  use case file for the Pandaboard card is in
       /usr/share/alsa/ucm/PandaBoard/PandaBoard.conf, this file lists all the
       supported use cases, e.g.

          SectionUseCase."HiFi" {
                          File "hifi"
                          Comment "Play HiFi quality Music."
          }
          ...

       Each use case defines a _verb, which is described in the file specified
       in the File directive, like above.

       The  HiFi  verb  above  is   described   in   /usr/share/alsa/ucm/Pand-
       aBoard/hifi.

       For  more  details  on the syntax of UCM files, see the alsa-lib source
       code:
       http://git.alsa-project.org/?p=alsa-lib.git;a=blob;f=src/ucm/parser.c

EXAMPLES OF USE
       Some  commands,  like  for  instance list _devices, can only work after
       setting a _verb in the  same  execution,  for  instance  this  sequence
       doesn't work:

          # alsaucm -c bytcr-rt5640 set _verb HiFi
          # alsaucm -c bytcr-rt5640 list _devices

       However this command does:

          # alsaucm -n -b - <<EOM
          open bytcr-rt5640
          set _verb HiFi
          list _devices
          EOM

       An  example  of  setting  the  Speaker  device for the HiFi verb of the
       bytcr-rt5640 card:

          # alsaucm -n -b - <<EOM
          open bytcr-rt5640
          reset
          set _verb HiFi
          set _enadev Speaker
          EOM

SEE ALSO
       o Use                          Case                          Interface:
         http://www.alsa-project.org/alsa-doc/alsa-lib/group__ucm.html

BUGS
       None known.

AUTHOR
       Antonio Ospite <ao2@ao2.it>

COPYRIGHT
       GPLv2+

                                  2016-09-22                        ALSAUCM(1)