Codebase list alsa-lib / e288ca7
doc: ucm - more volume notes Signed-off-by: Jaroslav Kysela <perex@perex.cz> Jaroslav Kysela 1 year, 7 months ago
3 changed file(s) with 72 addition(s) and 13 deletion(s). Raw diff Collapse all Expand all
+19
-0
doc/pictures/ucm-volume.puml less more
0 @startuml
1 title "UCM volume"
2
3 start
4 if (Card state (/var/lib/alsa/asound.state)) then (not present)
5 :UCM: BootSequence;
6 else (present)
7 :alsactl: Restore state (from asound.state);
8 endif
9 :UCM application:set device volume;
10 note right
11 The application uses (Playback|Capture)MixerElem or
12 (Playback/Capture)(Volume/Switch) values to get
13 the controls.
14 end note
15 :alsactl: Store state (to asound.state);
16 stop
17
18 @enduml
+29
-0
doc/pictures/ucm-volume.svg less more
0 <?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" height="357px" preserveAspectRatio="none" style="width:724px;height:357px;background:#FFFFFF;" version="1.1" viewBox="0 0 724 357" width="724px" zoomAndPan="magnify"><defs/><g><rect height="26.2969" style="stroke:#00000000;stroke-width:1.0;fill:none;" width="107" x="307.25" y="15"/><text fill="#000000" font-family="sans-serif" font-size="14" font-weight="bold" lengthAdjust="spacing" textLength="97" x="312.25" y="32.9951">UCM volume</text><ellipse cx="215.5" cy="57.2969" fill="#222222" rx="10" ry="10" style="stroke:#222222;stroke-width:1.0;"/><polygon fill="#F1F1F1" points="106.5,87.2969,324.5,87.2969,336.5,99.2969,324.5,111.2969,106.5,111.2969,94.5,99.2969,106.5,87.2969" style="stroke:#181818;stroke-width:0.5;"/><text fill="#000000" font-family="sans-serif" font-size="11" lengthAdjust="spacing" textLength="218" x="106.5" y="103.105">Card state (/var/lib/alsa/asound.state)</text><text fill="#000000" font-family="sans-serif" font-size="11" lengthAdjust="spacing" textLength="66" x="28.5" y="96.7026">not present</text><text fill="#000000" font-family="sans-serif" font-size="11" lengthAdjust="spacing" textLength="44" x="336.5" y="96.7026">present</text><rect fill="#F1F1F1" height="33.9688" rx="12.5" ry="12.5" style="stroke:#181818;stroke-width:0.5;" width="147" x="11" y="121.2969"/><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacing" textLength="127" x="21" y="142.4355">UCM: BootSequence</text><rect fill="#F1F1F1" height="33.9688" rx="12.5" ry="12.5" style="stroke:#181818;stroke-width:0.5;" width="285" x="204" y="121.2969"/><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacing" textLength="265" x="214" y="142.4355">alsactl: Restore state (from asound.state)</text><polygon fill="#F1F1F1" points="215.5,161.2656,227.5,173.2656,215.5,185.2656,203.5,173.2656,215.5,161.2656" style="stroke:#181818;stroke-width:0.5;"/><path d="M353.5,195.2656 L353.5,218.9648 L333.5,222.9648 L353.5,226.9648 L353.5,250.6641 A0,0 0 0 0 353.5,250.6641 L712.5,250.6641 A0,0 0 0 0 712.5,250.6641 L712.5,205.2656 L702.5,195.2656 L353.5,195.2656 A0,0 0 0 0 353.5,195.2656 " fill="#FEFFDD" style="stroke:#181818;stroke-width:0.5;"/><path d="M702.5,195.2656 L702.5,205.2656 L712.5,205.2656 L702.5,195.2656 " fill="#FEFFDD" style="stroke:#181818;stroke-width:0.5;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="338" x="359.5" y="212.3325">The application uses (Playback|Capture)MixerElem or</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="312" x="359.5" y="227.4653">(Playback/Capture)(Volume/Switch) values to get</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="80" x="359.5" y="242.5981">the controls.</text><rect fill="#F1F1F1" height="33.9688" rx="12.5" ry="12.5" style="stroke:#181818;stroke-width:0.5;" width="236" x="97.5" y="205.9805"/><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacing" textLength="216" x="107.5" y="227.1191">UCM application:set device volume</text><rect fill="#F1F1F1" height="33.9688" rx="12.5" ry="12.5" style="stroke:#181818;stroke-width:0.5;" width="255" x="88" y="270.6641"/><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacing" textLength="235" x="98" y="291.8027">alsactl: Store state (to asound.state)</text><ellipse cx="215.5" cy="335.6328" rx="11" ry="11" style="stroke:#222222;stroke-width:1.0;fill:none;"/><ellipse cx="215.5" cy="335.6328" fill="#222222" rx="6" ry="6" style="stroke:#111111;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="94.5" x2="84.5" y1="99.2969" y2="99.2969"/><line style="stroke:#181818;stroke-width:1.0;" x1="84.5" x2="84.5" y1="99.2969" y2="121.2969"/><polygon fill="#181818" points="80.5,111.2969,84.5,121.2969,88.5,111.2969,84.5,115.2969" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="336.5" x2="346.5" y1="99.2969" y2="99.2969"/><line style="stroke:#181818;stroke-width:1.0;" x1="346.5" x2="346.5" y1="99.2969" y2="121.2969"/><polygon fill="#181818" points="342.5,111.2969,346.5,121.2969,350.5,111.2969,346.5,115.2969" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="84.5" x2="84.5" y1="155.2656" y2="173.2656"/><line style="stroke:#181818;stroke-width:1.0;" x1="84.5" x2="203.5" y1="173.2656" y2="173.2656"/><polygon fill="#181818" points="193.5,169.2656,203.5,173.2656,193.5,177.2656,197.5,173.2656" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="346.5" x2="346.5" y1="155.2656" y2="173.2656"/><line style="stroke:#181818;stroke-width:1.0;" x1="346.5" x2="227.5" y1="173.2656" y2="173.2656"/><polygon fill="#181818" points="237.5,169.2656,227.5,173.2656,237.5,177.2656,233.5,173.2656" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="215.5" x2="215.5" y1="67.2969" y2="87.2969"/><polygon fill="#181818" points="211.5,77.2969,215.5,87.2969,219.5,77.2969,215.5,81.2969" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="215.5" x2="215.5" y1="185.2656" y2="205.9805"/><polygon fill="#181818" points="211.5,195.9805,215.5,205.9805,219.5,195.9805,215.5,199.9805" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="215.5" x2="215.5" y1="239.9492" y2="270.6641"/><polygon fill="#181818" points="211.5,260.6641,215.5,270.6641,219.5,260.6641,215.5,264.6641" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="215.5" x2="215.5" y1="304.6328" y2="324.6328"/><polygon fill="#181818" points="211.5,314.6328,215.5,324.6328,219.5,314.6328,215.5,318.6328" style="stroke:#181818;stroke-width:1.0;"/><!--MD5=[3a7c61dd4ff8304ea95eeb2e154d1932]
1 @startuml
2 title "UCM volume"
3
4 start
5 if (Card state (/var/lib/alsa/asound.state)) then (not present)
6 :UCM: BootSequence;
7 else (present)
8 :alsactl: Restore state (from asound.state);
9 endif
10 :UCM application:set device volume;
11 note right
12 The application uses (Playback|Capture)MixerElem or
13 (Playback/Capture)(Volume/Switch) values to get
14 the controls.
15 end note
16 :alsactl: Store state (to asound.state);
17 stop
18
19 @enduml
20
21 PlantUML version 1.2022.5(Sat Apr 30 12:55:52 CEST 2022)
22 (LGPL source distribution)
23 Java Runtime: OpenJDK Runtime Environment
24 JVM: OpenJDK 64-Bit Server VM
25 Default Encoding: UTF-8
26 Language: cs
27 Country: CZ
28 --></g></svg>⏎
+24
-13
src/ucm/ucm_confdoc.h less more
6262 # Example master file for blah sound card
6363 # By Joe Blogs <joe@bloggs.org>
6464
65 Syntax 6
66
6567 # Use Case name for user interface
6668 Comment "Nice Abstracted Soundcard"
6769
9092 # ALSA card controls which may be modified by user after initial settings.
9193
9294 BootSequence [
93 cset "name='My control' on"
95 cset "name='Master Playback Switch',index=2 0,0"
96 cset "name='Master Playback Volume',index=2 25,25"
97 msleep 50
98 cset "name='Master Playback Switch',index=2 1,1"
99 cset "name='Master Playback Volume',index=2 50,50"
94100 ]
95101
96102 # Define fixed boot sequence
116122
117123 # enable and disable sequences are compulsory
118124 EnableSequence [
119 cset "name='Master Playback Switch',index=2 0,0"
120 cset "name='Master Playback Volume',index=2 25,25"
121 msleep 50
122 cset "name='Master Playback Switch',index=2 1,1"
123 cset "name='Master Playback Volume',index=2 50,50"
125 disdevall "" # run DisableSequence for all devices
124126 ]
125127
126128 DisableSequence [
127 cset "name='Master Playback Switch',index=2 0,0"
128 cset "name='Master Playback Volume',index=2 25,25"
129 msleep 50
130 cset "name='Master Playback Switch',index=2 1,1"
131 cset "name='Master Playback Volume',index=2 50,50"
129 cset "name='Power Save' on"
132130 ]
133131
134132 # Optional transition verb
135133 TransitionSequence."ToCaseName" [
134 disdevall "" # run DisableSequence for all devices
136135 msleep 1
137136 ]
138137
211210 Value {
212211 TQ Voice
213212 CapturePCM "hw:${CardId},11"
213 PlaybackMixerElem "Master"
214214 PlaybackVolume "name='Master Playback Volume',index=2"
215215 PlaybackSwitch "name='Master Playback Switch',index=2"
216216 }
287287 ### Device volume
288288
289289 It is expected that the applications handle the volume settings. It is not recommended
290 to set the fixed values for the volume settings to the Enable / Disable sequences for
290 to set the fixed values for the volume settings in the Enable / Disable sequences for
291291 verbs or devices, if the device exports the hardware volume (MixerElem or Volume/Switch
292 values). The default volume settings should be set in the *BootSequence*.
292 values). The default volume settings should be set in the *BootSequence*. The purpose
293 for this scheme is to allow users to override defaults using the alsactl sound card
294 state management.
295
296 Checklist:
297
298 1. Set default volume in BootSequence
299 2. Verb's EnableSequence should ensure that all devices are turned off (mixer paths)
300 to avoid simultaneous device use - the previous state is unknown (see *disdevall*
301 and *disdev2* commands or create a new custom command sequence)
302
303 \image html ucm-volume.svg
293304
294305 ### Dynamic configuration tree
295306