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