alsaucm/alsaucm.rst

   1 =========
   2  alsaucm
   3 =========
   4
   5 ---------------------
   6 ALSA Use Case Manager
   7 ---------------------
   8
   9 :Author: Antonio Ospite <ao2@ao2.it>
  10 :Date:   2016-09-22
  11 :Copyright: GPLv2+
  12 :Manual section: 1
  13 :Manual group: General Commands Manual
  14
  15 SYNOPSIS
  16 ========
  17
  18 *alsaucm* <options> [command]
  19
  20 DESCRIPTION
  21 ===========
  22
  23 alsaucm (ALSA Use Case Manager) is a program to use the ALSA `Use Case
  24 Interface`_ from the command line.
  25
  26 On complex sound cards, setting up audio routes is not trivial and mixer
  27 settings can conflict one another preventing the audio card to work at all.
  28
  29 The ALSA Use Case Manager is a mechanism for controlling complex audio
  30 hardware establishing a relationship between hardware configurations and
  31 meaningful use cases that the end-user can relate with.
  32
  33 The use case manager can also be used to switch between use cases when
  34 necessary, in a consistent way.
  35
  36 At a lower level, the use case manager works by configuring the sound card
  37 ALSA kcontrols to change the hardware digital and analog audio routing to
  38 match the requested device use case.
  39
  40 The use case manager kcontrol configurations are stored in easy to modify text
  41 files. An audio use case can be defined by a **verb** and **device** parameter.
  42
  43 The verb describes the use case action i.e. a phone call, listening to music,
  44 recording a conversation etc. The device describes the physical audio capture
  45 and playback hardware i.e. headphones, phone handset, bluetooth headset, etc.
  46
  47
  48 OPTIONS
  49 =======
  50
  51 Available options:
  52
  53   **-h**, **--help**
  54     this help
  55
  56   **-c**, **--card** `NAME`
  57     open card NAME
  58
  59   **-i**, **--interactive**
  60     interactive mode
  61
  62   **-b**, **--batch** `FILE`
  63     batch mode (use ``'-'`` for the stdin input)
  64
  65   **-n**, **--no-open**
  66     do not open first card found
  67
  68
  69 Available commands:
  70
  71   ``open`` `NAME`
  72     open card NAME.
  73
  74     valid names are sound card names as listed in ``/usr/share/alsa/ucm``.
  75
  76   ``reset``
  77     reset sound card to default state.
  78
  79   ``reload``
  80     reload configuration.
  81
  82   ``listcards``
  83     list available cards.
  84
  85   ``list`` `IDENTIFIER`
  86     list command, for items returning two entries (value+comment).
  87
  88     the value of the `IDENTIFIER` argument can can be:
  89
  90     - ``_verbs`` - get verb list (in pair verb+comment)
  91     - ``_devices[/{verb}]`` - get list of supported devices (in pair device+comment)
  92     - ``_modifiers[/{verb}]`` - get list of supported modifiers (in pair modifier+comment)
  93
  94     The forms without the trailing ``/{verb}`` are valid only after a specific
  95     verb has been set.
  96
  97   ``list1`` `IDENTIFIER`
  98     list command, for lists returning one item per entry.
  99
 100     the value of the `IDENTIFIER` argument can vary depending on the context,
 101     it can be:
 102
 103     - ``TQ[/{verb}]`` - get list of Tone Quality identifiers
 104     - ``_enadevs`` - get list of enabled devices
 105     - ``_enamods`` - get list of enabled modifiers
 106     - ``_supporteddevs/{modifier}|{device}[/{verb}]`` - list of supported devices
 107     - ``_conflictingdevs/{modifier}|{device}[/{verb}]`` - list of conflicting devices
 108
 109   ``get`` `IDENTIFIER`
 110     get string value.
 111
 112     the value of the `IDENTIFIER` argument can can be:
 113
 114     - ``_verb`` - return current verb
 115     - ``[=]{NAME}[/[{modifier}|{/device}][/{verb}]]`` (For valid NAMEs look at the
 116       ALSA `Use Case Interface`_)
 117
 118
 119   ``geti`` `IDENTIFIER`
 120     get integer value.
 121
 122     the value of the `IDENTIFIER` argument can can be:
 123
 124     - ``_devstatus/{device}``
 125     - ``_modtstaus/{device}``
 126
 127   ``set`` `IDENTIFIER` `VALUE`
 128     set string value
 129
 130     The value of the `IDENTIFIER` argument can can be:
 131
 132     - ``_verb`` - set the verb to `VALUE`
 133     - ``_enadev`` - enable the device specified by `VALUE`
 134     - ``_disdev`` - disable the device specified by `VALUE`
 135     - ``_swdev/{old_device}`` - switche device:
 136
 137       - disable `old_device` and then enable the device specified by
 138         `VALUE`
 139       - if no device was enabled just return
 140
 141     - ``_enamod`` - enable the modifier specified by `VALUE`
 142     - ``_dismod`` - disable the modifier specified by `VALUE`
 143     - ``_swmod/{old_modifier}`` - switch modifier:
 144
 145       - disable `old_modifier` and then enable the modifier specified by
 146         `VALUE`
 147       - if no modifier was enabled just return
 148
 149     Note that the identifiers referring to devices and modifiers are valid
 150     only after setting a verb.
 151
 152   ``h``, ``help``
 153     help
 154
 155   ``q``, ``quit``
 156     quit
 157
 158
 159 FILES
 160 =====
 161
 162 The master use case files for each supported sound card are in ``/usr/share/alsa/ucm``.
 163
 164 For example, the master use case file for the `Pandaboard` card is in
 165 ``/usr/share/alsa/ucm/PandaBoard/PandaBoard.conf``, this file lists all the
 166 supported use cases, e.g.
 167
 168 ::
 169
 170   SectionUseCase."HiFi" {
 171                   File "hifi"
 172                   Comment "Play HiFi quality Music."
 173   }
 174   ...
 175
 176
 177 Each use case defines a _verb, which is described in the file specified in
 178 the ``File`` directive, like above.
 179
 180 The ``HiFi`` verb above is described in
 181 ``/usr/share/alsa/ucm/PandaBoard/hifi``.
 182
 183 For more details on the syntax of UCM files, see the alsa-lib source code:
 184 http://git.alsa-project.org/?p=alsa-lib.git;a=blob;f=src/ucm/parser.c
 185
 186
 187 EXAMPLES OF USE
 188 ===============
 189
 190 Some commands, like for instance ``list _devices``,
 191 can only work after setting a ``_verb`` in the **same execution**, for
 192 instance this sequence doesn't work:
 193
 194 ::
 195
 196   # alsaucm -c bytcr-rt5640 set _verb HiFi
 197   # alsaucm -c bytcr-rt5640 list _devices
 198
 199
 200 However this command does:
 201
 202 ::
 203
 204   # alsaucm -n -b - <<EOM
 205   open bytcr-rt5640
 206   set _verb HiFi
 207   list _devices
 208   EOM
 209
 210
 211 An example of setting the `Speaker` device for the `HiFi` verb of the
 212 `bytcr-rt5640` card:
 213
 214 ::
 215
 216   # alsaucm -n -b - <<EOM
 217   open bytcr-rt5640
 218   reset
 219   set _verb HiFi
 220   set _enadev Speaker
 221   EOM
 222
 223
 224
 225 SEE ALSO
 226 ========
 227
 228 * Use Case Interface: http://www.alsa-project.org/alsa-doc/alsa-lib/group__ucm.html
 229
 230 .. _Use Case Interface: http://www.alsa-project.org/alsa-doc/alsa-lib/group__ucm.html
 231
 232 BUGS
 233 ====
 234
 235 None known.