build: Use .ONESHELL.
[paraslash.git] / m4 / lls / mixer.suite.m4
1 m4_define(PROGRAM, para_mixer)
2 m4_define(DEFAULT_CONFIG_FILE, ~/.paraslash/mixer.conf)
3 [suite mixer]
4 version-string = GIT_VERSION()
5 caption = List of subcommands
6 [supercommand para_mixer]
7 purpose = alarm clock and volume-fader for OSS and ALSA
8 synopsis = [<options>] -- [<subcommand>] [<subcommand_options>]
9 [description]
10 para_mixer adjusts the settings of an audio mixing device. It can
11 set the level of a mixer channel, or fade the level from one value
12 to another in a given time period. The sleep and snooze subcommands
13 contact para_server to start or stop streaming.
14 [/description]
15 m4_include(common-option-section.m4)
16 m4_include(help.m4)
17 m4_include(detailed-help.m4)
18 m4_include(version.m4)
19 m4_include(config-file.m4)
20 m4_include(loglevel.m4)
21 m4_include(per-command-options-section.m4)
22 [help]
23 These options apply to several subcommands.
24 [/help]
25 [option mixer-api]
26 short_opt = a
27 summary = select alternative mixer API
28 arg_info = required_arg
29 arg_type = string
30 typestr = api
31 [help]
32 ALSA is preferred over OSS if both APIs are supported and this option
33 is not given. To see the supported mixer APIs, use this option with
34 an invalid string as the mixer API, e.g. --mixer-api help.
35 [/help]
36 [option mixer-device]
37 short_opt = m
38 summary = set mixer device
39 arg_info = required_arg
40 arg_type = string
41 typestr = device
42 [help]
43 The default device (used if this option is not given) depends
44 on the selected mixer API. For ALSA, the default is 'hw:0' which
45 corresponds to the first sound device. For OSS, '/dev/mixer' is used
46 as the default.
47 [/help]
48 [option mixer-channel]
49 short_opt = C
50 summary = select a mixer channel
51 arg_info = required_arg
52 arg_type = string
53 typestr = channel
54 [help]
55 For the ALSA mixer API, the possible values are determined at runtime
56 depending on the hardware and can be printed by specifying an invalid
57 mixer channel, for example --mixer-channel help. The default channel is
58 'Master'.
59
60 For OSS the possible values are invariably 'volume', 'bass', 'treble',
61 'synth', 'pcm', 'speaker', 'line', 'mic', 'cd', 'imix', 'altpcm',
62 'reclev', 'igain', 'ogain'. However, not all listed channels might be
63 supported on any particular hardware. The default channel is 'volume'.
64 [/help]
65 [option fade-exponent]
66 summary = set non-linear time scale for fading
67 arg_info = required_arg
68 arg_type = uint32
69 typestr = value
70 default_val = 0
71 [help]
72 This option affects the fade, snooze and sleep subcommands. It is
73 ignored in set mode.
74
75 The argument must be a number between 0 and 100. The default value
76 0 corresponds to linear scaling. That is, the value of the mixer
77 channel is increased or decreased in fixed time intervals until the
78 destination value is reached. Exponents between 1 and 99 cause low
79 channel values to be increased more quickly than high channel values.
80 Large exponents cause greater differences. The special value 100 sets
81 the destination value immediately. The command then sleeps for the
82 configured fade time.
83 [/help]
84 [subcommand help]
85 purpose = print subcommand help
86 non-opts-name = [<subcommand>]
87 [option long]
88 summary = print the long help text
89 short_opt = l
90
91 [subcommand set]
92 purpose = set a channel to the given value and exit
93 [option val]
94 summary = mixer channel value to set
95 arg_info = required_arg
96 arg_type = uint32
97 typestr = value
98 default_val = 10
99 [subcommand fade]
100 purpose = fade a channel to the given value in the given time
101 [option fade-vol]
102 short_opt = f
103 summary = destination volume for fading
104 arg_info = required_arg
105 arg_type = uint32
106 typestr = volume
107 default_val = 50
108 [option fade-time]
109 short_opt = t
110 summary = duration of fade period
111 arg_info = required_arg
112 arg_type = uint32
113 typestr = seconds
114 default_val = 5
115 [subcommand snooze]
116 purpose = fade out, pause, sleep, play, fade in
117 [option so-time]
118 summary = duration of fade-out period
119 arg_info = required_arg
120 arg_type = uint32
121 typestr = seconds
122 default_val = 30
123 [option so-vol]
124 summary = destination volume for fade-out
125 arg_info = required_arg
126 arg_type = uint32
127 typestr = volume
128 default_val = 20
129 [option snooze-time]
130 summary = delay between end of fade-out and begin of fade-in
131 arg_info = required_arg
132 arg_type = uint32
133 typestr = seconds
134 default_val = 600
135 [option si-time]
136 summary = duration of fade-in period
137 arg_info = required_arg
138 arg_type = uint32
139 typestr = seconds
140 default_val = 180
141 [option si-vol]
142 summary = destination volume for fade-in
143 arg_info = required_arg
144 arg_type = uint32
145 typestr = volume
146 default_val = 80
147 [subcommand sleep]
148 purpose = stream, fade out, sleep, fade in
149 [description]
150 Change to the initial volume and select the initial mood/playlist.
151 Fade out to the given fade-out volume in the specified time. Switch
152 to the sleep mood/playlist and wait until wake time minus fade-in
153 time. Finally, switch to the wake mood/playlist and fade in to the
154 fade-in volume.
155 [/description]
156 [option ivol]
157 summary = set initial volume
158 arg_info = required_arg
159 arg_type = string
160 default_val = 60
161 flag multiple
162 typestr = [channel:]volume
163 [help]
164 Used as the start volume, before fading out to the fade-out volume. The
165 channel part may be omitted, in which case the default channel is
166 used. This option may be given multiple times.
167 [/help]
168 [option fo-mood]
169 summary = mood or playlist for fade-out
170 arg_info = required_arg
171 arg_type = string
172 typestr = mood_spec
173 [help]
174 This mood (or playlist) is selected right after setting the initial
175 volume.
176 [/help]
177 [option fo-time]
178 summary = duration of fade-out period
179 arg_info = required_arg
180 arg_type = uint32
181 typestr = seconds
182 default_val = 1800
183 [help]
184 No fading if this is set to 0.
185 [/help]
186 [option fo-vol]
187 summary = destination volume for fade-out
188 arg_info = required_arg
189 arg_type = uint32
190 typestr = volume
191 default_val = 20
192 [option sleep-mood]
193 summary = mood/playlist between fade-out and fade-in
194 arg_info = required_arg
195 arg_type = string
196 typestr = mood_spec
197 [help]
198 Select the given mood or playlist after the fade-out. If unset,
199 playback is stopped until fade-in starts.
200 [/help]
201 [option wake-time]
202 short_opt = w
203 summary = when to start fade in
204 arg_info = required_arg
205 arg_type = string
206 typestr = [+][HH][:MM]
207 default_val = +9:00
208 [help]
209 If the optional plus character is given, the wake time is computed as
210 now + HH hours + MM minutes. Otherwise the HH:MM argument is considered
211 an absolute time (referring to either the current or the next day).
212 [/help]
213 [option fi-mood]
214 summary = mood or playlist for fade-in
215 arg_info = required_arg
216 arg_type = string
217 typestr = mood_spec
218 [help]
219 This mood or playlist is selected right before fade-in begins.
220 [/help]
221 [option fi-time]
222 summary = duration of fade-in period
223 arg_info = required_arg
224 arg_type = uint32
225 typestr = seconds
226 default_val = 1200
227 [help]
228 No fading if this is set to 0.
229 [/help]
230 [option fi-vol]
231 summary = destination volume for fade-in
232 arg_info = required_arg
233 arg_type = uint32
234 typestr = volume
235 default_val = 80