2ddc53dcba134073fab6081c9365d608c3dc2856
[paraslash.git] / m4 / lls / server_cmd.suite.m4
1 [suite server_cmd]
2 caption = list of server commands
3 aux_info_prefix = Permissions:
4
5 [introduction]
6 The server process listens on a network socket and accepts connections
7 from para_client or para_audiod. For the connection to succeed the
8 connecting peer must authenticate as one of the users stored in the
9 user table of para_server. Each entry of the user table contains the
10 set of permission bits that are granted to the user. Authenticated
11 users may execute one of the commands below if the set of permission
12 bits of the command is a subset of the permission bits that are
13 granted to the user.
14 [/introduction]
15
16 [subcommand add]
17 purpose = add or update audio files
18 non-opts-name = path...
19 aux_info = AFS_READ | AFS_WRITE
20 [description]
21 Each path must be absolute and refer to either an audio file or a
22 directory. In case of a directory, all audio files in that directory
23 are added recursively. Note that the given paths refer to files or
24 directories on the host on which para_server is running.
25 [/description]
26 [option all]
27 short_opt = a
28 summary = add all files
29 [help]
30 The default is to add only files ending in a known suffix for a
31 supported audio format.
32 [/help]
33 [option lazy]
34 short_opt = l
35 summary = add files lazily
36 [help]
37 If the path already exists in the database, skip this file. This
38 operation is really cheap. Useful to update large directories after
39 some files have been added.
40 [/help]
41 [option force]
42 short_opt = f
43 summary = force adding/updating
44 [help]
45 Recompute the audio format handler data even if a file with the same
46 path and the same hash value exists.
47 [/help]
48 [option verbose]
49 short_opt = v
50 summary = enable verbose mode
51 [help]
52 Print what is being done.
53 [/help]
54
55 [subcommand check]
56 purpose = run integrity checks on database tables
57 aux_info = AFS_READ
58 [description]
59 If no options are given, all checks are run.
60 [/description]
61 [option aft]
62 short_opt = a
63 summary = run audio file table checks
64 [help]
65 Report stale paths and invalid image and lyrics ids of the audio
66 file table.
67 [/help]
68 [option attribute]
69 short_opt = A
70 summary = check for invalid attributes
71 [help]
72 Report audio files whose attribute bitmask is invalid, i.e., has a bit
73 set which does not correspond to any attribute of the attribute table.
74 [/help]
75 [option mood]
76 short_opt = m
77 summary = check for invalid mood definitions
78 [help]
79 Run syntax checks on all moods of the mood table.
80 [/help]
81 [option playlist]
82 short_opt = p
83 summary = find invalid paths in playlists
84 [help]
85 Check all playlists for paths not contained in the audio file table.
86 [/help]
87
88 [subcommand cpsi]
89 purpose = copy selected parts of the audio file selector info
90 non-opts-name = source pattern...
91 aux_info = AFS_READ | AFS_WRITE
92 [description]
93 If no option, or only --verbose is given, all fields of the audio
94 file selector info structure are copied to each row of the audio file
95 table whose path matches at least one of the given patterns. Otherwise,
96 only those fields which correspond to the given options are copied.
97 [/description]
98 [option attribute-bitmap]
99 short_opt = a
100 summary = copy the attribute bitmap
101 [option image-id]
102 short_opt = i
103 summary = copy the image id
104 [option lyrics-id]
105 short_opt = y
106 summary = copy the lyrics id
107 [option lastplayed]
108 short_opt = l
109 summary = copy the lastplayed timestamp
110 [option numplayed]
111 short_opt = n
112 summary = copy the numplayed counter
113 [option verbose]
114 short_opt = v
115 summary = enable verbose mode
116
117 [subcommand ff]
118 purpose = jump N seconds forward or backward
119 synopsis = n[-]
120 aux_info = VSS_READ | VSS_WRITE
121 [description]
122 This sets the 'R' (reposition request) bit of the vss status flags
123 which enqueues a request to jump n seconds forwards or backwards.
124
125 Example:
126
127 para_client ff 30-
128
129 jumps 30 seconds backwards.
130
131 [/description]
132
133 [subcommand help]
134 purpose = list available commands or print command-specific help
135 non-opts-name = [command]
136 aux_info = NO_PERMISSION_REQUIRED
137 [description]
138 Without any arguments, help prints a list of available commands. When
139 called with a command name as first argument, it prints the description
140 of this command.
141 [/description]
142
143 [subcommand hup]
144 purpose = reload config file, log file and user list
145 aux_info = VSS_WRITE
146 [description]
147 Reread the config file and the user list file, close and reopen the log
148 file, and ask the afs process to do the same. Sending the HUP signal
149 to the server process has the same effect as running this command.
150 [/description]
151
152 [subcommand init]
153 purpose = initialize the database tables for the audio file selector
154 synopsis = [table_name...]
155 aux_info = AFS_READ | AFS_WRITE
156 [description]
157 When invoked without arguments, this command creates all
158 tables: audio_files, attributes, scores, moods, lyrics, images,
159 playlists. Otherwise only the given tables are created.
160 [/description]
161
162 [subcommand jmp]
163 purpose = reposition the current stream
164 non-opts-name = n
165 aux_info = VSS_READ | VSS_WRITE
166 [description]
167 Set the 'R' (reposition request) bit of the vss status flags and
168 enqueue a request to jump to n% of the current audio file, where 0 <=
169 n <= 100.
170 [/description]
171
172 [subcommand lsatt]
173 purpose = list attributes
174 aux_info = AFS_READ
175 [description]
176 Print the list of all defined attributes which match the given
177 pattern. If no pattern is given, the full list is printed.
178 [/description]
179
180 [option id-sort]
181 short_opt = i
182 summary = sort attributes by id
183 [help]
184 The default is to sort alphabetically by name.
185
186 Attributes are internally represented as an 64 bit array. The attribute
187 id is the bit number in this array.
188 [/help]
189 [option long]
190 short_opt = l
191 summary = print long listing
192 [help]
193 The long listing prints the attribute id in addition to the name of
194 the attribute. The id is printed as a decimal number and is separated
195 from the name by a tab character.
196 [/help]
197 [option reverse]
198 short_opt = r
199 summary = reverse sort order
200
201 [subcommand mvatt]
202 purpose = rename an attribute
203 synopsis = source dest
204 aux_info = AFS_READ | AFS_WRITE
205 [description]
206 Rename the attribute given by the first argument to the destination
207 given by the second argument. It is an error if the destination
208 attribute exists.
209 [/description]
210
211 [subcommand next]
212 purpose = close the stream and start to stream the next audio file
213 aux_info = VSS_READ | VSS_WRITE
214 [description]
215 Set the 'N' (next audio file) bit of the vss status flags. This
216 instructs the server to close the current stream, if any. The 'P'
217 (playing) bit is not modified by this command. If it is on, playing
218 continues with the next audio file.
219
220 This command is equivalent to stop if paused, and has no effect
221 if stopped.
222 [/description]
223
224 [subcommand nomore]
225 purpose = stop playing after current audio file
226 aux_info = VSS_READ | VSS_WRITE
227 [description]
228 Set the 'O' (no more) bit of the vss status flags which asks
229 para_server to clear the 'P' (playing) bit after the 'N' (next audio
230 file) bit transitions from off to on (because the end of the current
231 audio file is reached). Use this command instead of stop if you don't
232 like sudden endings.
233 [/description]
234
235 [subcommand pause]
236 purpose = suspend the current stream
237 aux_info = VSS_READ | VSS_WRITE
238 [description]
239 Clear the 'P' (playing) bit of the vss status flags.
240 [/description]
241
242 [subcommand play]
243 purpose = start or resume playback
244 aux_info = VSS_READ | VSS_WRITE
245 [description]
246 Set the 'P' (playing) bit of the vss status flags.
247 [/description]
248
249 [subcommand rm]
250 purpose = remove rows from the audio file table
251 non-opts-name = pattern...
252 aux_info = AFS_READ | AFS_WRITE
253 [description]
254 Remove all rows of the audio file table which match any of the given
255 patterns. Note that this affects only the database table; the command
256 won't touch your audio files on disk.
257 [/description]
258 [option verbose]
259 short_opt = v
260 summary = print paths of deleted rows
261 [option force]
262 short_opt = f
263 summary = don't complain if nothing was removed
264 [option pathname-match]
265 short_opt = p
266 summary = modify matching behaviour
267 [help]
268 Match a slash in the path only with a slash in pattern and not by an
269 asterisk (*) or a question mark (?) metacharacter, nor by a bracket
270 expression ([]) containing a slash (see fnmatch(3)).
271 [/help]
272
273 [subcommand rmatt]
274 purpose = remove attribute(s)
275 non-opts-name = pattern...
276 aux_info = AFS_READ | AFS_WRITE
277 [description]
278 Remove all attributes which match any given pattern. All information
279 about the removed attributes in the audio file table is lost.
280 [/description]
281
282 [subcommand select]
283 purpose = activate a mood or a playlist
284 non-opts-name = specifier/name
285 aux_info = AFS_READ | AFS_WRITE
286 [description]
287 The specifier is either 'm' or 'p' to indicate whether a playlist or
288 a mood should be activated. Example:
289
290 select m/foo
291
292 activates the mood named 'foo'.
293 [/description]
294
295 [subcommand sender]
296 purpose = control paraslash senders
297 synopsis = [sender cmd [arguments]]
298 aux_info = VSS_READ | VSS_WRITE
299 [description]
300 Send a command to a specific sender. The following commands are
301 available, but not all senders support every command.
302
303 help, on, off, add, delete, allow, deny, status.
304
305 The help command prints the help text of the given sender. If no
306 command is given the list of available senders is shown.
307
308 Example:
309
310 para_client sender http help
311
312 [/description]
313
314 [subcommand setatt]
315 purpose = set or unset attributes
316 synopsis = attribute{+|-}... pattern...
317 aux_info = AFS_READ | AFS_WRITE
318 [description]
319 Set ('+') or unset ('-') the given attributes for all audio files
320 matching the given pattern. Example:
321
322 setatt rock+ punk+ pop- '*foo.mp3'
323
324 sets the 'rock' and the 'punk' attribute and unsets the 'pop' attribute
325 of all files ending with 'foo.mp3'.
326 [/description]
327
328 [subcommand si]
329 purpose = print server info
330 aux_info = NO_PERMISSION_REQUIRED
331 [description]
332 Show server and afs PID, number of connections, uptime and more.
333 [/description]
334
335 [subcommand stat]
336 purpose = print information about the current audio file
337 aux_info = VSS_READ
338 [option num]
339 short_opt = n
340 summary = number of times to show the status info
341 arg_info = required_arg
342 arg_type = uint32
343 typestr = num
344 [help]
345 Exit after the status information has been shown num times. If this
346 option is not given, the command runs in an endless loop.
347 [/help]
348 [option parser-friendly]
349 short_opt = p
350 summary = enable parser-friendly output
351 [help]
352 Show status item identifiers as numerical values and prefix each
353 status item with its size in bytes.
354 [/help]
355
356 [subcommand stop]
357 purpose = stop playback
358 aux_info = VSS_READ | VSS_WRITE
359 [description]
360 Clear the 'P' (playing) bit and set the 'N' (next audio file) bit of
361 the vss status flags, effectively stopping playback.
362 [/description]
363
364 [subcommand tasks]
365 purpose = list active server tasks
366 aux_info = NO_PERMISSION_REQUIRED
367 [description]
368 For each task, print ID, status and name. This is mostly useful
369 for debugging.
370 [/description]
371
372 [subcommand term]
373 purpose = ask the server to terminate
374 aux_info = VSS_READ | VSS_WRITE
375 [description]
376 Shut down the server. Instead of this command, you can also send
377 SIGINT or SIGTERM to the para_server process. It should never be
378 necessary to send SIGKILL.
379 [/description]
380
381 [subcommand touch]
382 purpose = manipulate the afs information of audio files
383 non-opts-name = pattern...
384 aux_info = AFS_READ | AFS_WRITE
385 [description]
386 This command modifies the afs info structure of all rows of the audio
387 file table whose path matches at least one of the given patters.
388
389 If at least one option is given which takes a number as its argument,
390 only those fields of the afs info structure are updated which
391 correspond to the given options while all other fields stay unmodified.
392
393 If no such option is given, the lastplayed field is set to the current
394 time and the value of the numplayed field is increased by one while
395 all other fields are left unchanged. This mimics what happens when
396 the virtual streaming system selects the file for streaming.
397
398 If the file is admissible for the current mood (or contained in the
399 current playlist), its score is recomputed according to the changed
400 values.
401 [/description]
402 [option numplayed]
403 short_opt = n
404 summary = set the numplayed count manually
405 arg_type = uint32
406 arg_info = required_arg
407 typestr = num
408 [help]
409 The numplayed count of an audio file is the number of times the file
410 was selected for streaming. It is one of the inputs to the scoring
411 function which determines the order in which admissible files are
412 streamed.
413
414 The virtual streaming system increases this number automatically each
415 time it opens the file for streaming.
416 [/help]
417 [option lastplayed]
418 short_opt = l
419 summary = set the lastplayed time manually
420 arg_type = uint64
421 arg_info = required_arg
422 typestr = num
423 [help]
424 The lastplayed time of an audio file is the time when the file was
425 last opened for streaming.
426
427 Like the numplayed count, it is an input for the scoring function
428 and is updated automatically by the virtual streaming system.
429
430 The argument must be a number of seconds since the epoch. Example:
431
432 touch -l=$(date +%s) file
433
434 sets the lastplayed time of 'file' to the current time.
435 [/help]
436 [option image-id]
437 short_opt = i
438 summary = set the image id
439 arg_type = uint32
440 arg_info = required_arg
441 typestr = num
442 [help]
443 The afs info structure of each row of the audio file table contains
444 a slot for the image id of the audio file that corresponds to the
445 row. The image id stored in this slot refers to the key in the image
446 table that identifies the blob.
447
448 When a new audio file is added to the audio file table, its image
449 id starts out as zero, indicating that there is no image associated
450 with the file. Setting the image id to a non-zero number associates
451 the file with a particular blob of the image table, for example the
452 cover art of the album in jpg format.
453 [/help]
454 [option lyrics-id]
455 short_opt = y
456 summary = set the lyrics id
457 arg_type = uint32
458 arg_info = required_arg
459 typestr = num
460 [help]
461 This option works just like --image-id, but sets the lyrics ID rather
462 than the image id.
463 [/help]
464 [option amp]
465 short_opt = a
466 summary = set the amplification value (0-255)
467 arg_type = uint32
468 arg_info = required_arg
469 typestr = num
470 [help]
471 The amplification value of an audio file is a number which is stored
472 in the afs info structure.
473
474 The value determines the scaling factor by which the amplitude of
475 the decoded samples should be multiplied in order to normalize the
476 volume. A value of zero means no amplification, 64 means the amplitude
477 should be multiplied by a factor of two, 128 by three and so on.
478
479 The amp filter of para_audiod amplifies the volume according to
480 this value.
481 [/help]
482 [option verbose]
483 short_opt = v
484 summary = explain what is being done
485 [option pathname-match]
486 short_opt = p
487 summary = modify matching behaviour
488 [help]
489 Match a slash in the path only with a slash in pattern and not by an
490 asterisk (*) or a question mark (?) metacharacter, nor by a bracket
491 expression ([]) containing a slash (see fnmatch(3)).
492 [/help]
493
494 [subcommand version]
495 purpose = print the git version string of para_server
496 aux_info = NO_PERMISSION_REQUIRED
497 [option verbose]
498 short_opt = v
499 summary = print detailed (multi-line) version text
500