1=========
2 alsaucm
3=========
4
5---------------------
6ALSA 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
15SYNOPSIS
16========
17
18*alsaucm* <options> [command]
19
20DESCRIPTION
21===========
22
23alsaucm (ALSA Use Case Manager) is a program to use the ALSA `Use Case
24Interface`_ from the command line.
25
26On complex sound cards, setting up audio routes is not trivial and mixer
27settings can conflict one another preventing the audio card to work at all.
28
29The ALSA Use Case Manager is a mechanism for controlling complex audio
30hardware establishing a relationship between hardware configurations and
31meaningful use cases that the end-user can relate with.
32
33The use case manager can also be used to switch between use cases when
34necessary, in a consistent way.
35
36At a lower level, the use case manager works by configuring the sound card
37ALSA kcontrols to change the hardware digital and analog audio routing to
38match the requested device use case.
39
40The use case manager kcontrol configurations are stored in easy to modify text
41files. An audio use case can be defined by a **verb** and **device** parameter.
42
43The verb describes the use case action i.e. a phone call, listening to music,
44recording a conversation etc. The device describes the physical audio capture
45and playback hardware i.e. headphones, phone handset, bluetooth headset, etc.
46
47
48OPTIONS
49=======
50
51Available 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
69Available 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
159FILES
160=====
161
162The master use case files for each supported sound card are in ``/usr/share/alsa/ucm``.
163
164For 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
166supported use cases, e.g.
167
168::
169
170  SectionUseCase."HiFi" {
171                  File "hifi"
172                  Comment "Play HiFi quality Music."
173  }
174  ...
175
176
177Each use case defines a _verb, which is described in the file specified in
178the ``File`` directive, like above.
179
180The ``HiFi`` verb above is described in
181``/usr/share/alsa/ucm/PandaBoard/hifi``.
182
183For more details on the syntax of UCM files, see the alsa-lib source code:
184http://git.alsa-project.org/?p=alsa-lib.git;a=blob;f=src/ucm/parser.c
185
186
187EXAMPLES OF USE
188===============
189
190Some commands, like for instance ``list _devices``,
191can only work after setting a ``_verb`` in the **same execution**, for
192instance 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
200However 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
211An 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
225SEE 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
232BUGS
233====
234
235None known.
236