e2bd162d19b5161a38c9b404607842a0115c4a48
[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 addatt]
56 purpose = add new attribute(s)
57 non-opts-name = attribute...
58 aux_info = AFS_READ | AFS_WRITE
59 [description]
60 This adds new attributes to the attribute table. At most 64 attributes
61 may be defined.
62 [/description]
63
64 [subcommand check]
65 purpose = run integrity checks on database tables
66 aux_info = AFS_READ
67 [description]
68 If no options are given, all checks are run.
69 [/description]
70 [option aft]
71 short_opt = a
72 summary = run audio file table checks
73 [help]
74 Report stale paths and invalid image and lyrics ids of the audio
75 file table.
76 [/help]
77 [option attribute]
78 short_opt = A
79 summary = check for invalid attributes
80 [help]
81 Report audio files whose attribute bitmask is invalid, i.e., has a bit
82 set which does not correspond to any attribute of the attribute table.
83 [/help]
84 [option mood]
85 short_opt = m
86 summary = check for invalid mood definitions
87 [help]
88 Run syntax checks on all moods of the mood table.
89 [/help]
90 [option playlist]
91 short_opt = p
92 summary = find invalid paths in playlists
93 [help]
94 Check all playlists for paths not contained in the audio file table.
95 [/help]
96
97 [subcommand cpsi]
98 purpose = copy selected parts of the audio file selector info
99 non-opts-name = source pattern...
100 aux_info = AFS_READ | AFS_WRITE
101 [description]
102 If no option, or only --verbose is given, all fields of the audio
103 file selector info structure are copied to each row of the audio file
104 table whose path matches at least one of the given patterns. Otherwise,
105 only those fields which correspond to the given options are copied.
106 [/description]
107 [option attribute-bitmap]
108 short_opt = a
109 summary = copy the attribute bitmap
110 [option image-id]
111 short_opt = i
112 summary = copy the image id
113 [option lyrics-id]
114 short_opt = y
115 summary = copy the lyrics id
116 [option lastplayed]
117 short_opt = l
118 summary = copy the lastplayed timestamp
119 [option numplayed]
120 short_opt = n
121 summary = copy the numplayed counter
122 [option verbose]
123 short_opt = v
124 summary = enable verbose mode
125
126 [subcommand ff]
127 purpose = jump N seconds forward or backward
128 synopsis = n[-]
129 aux_info = VSS_READ | VSS_WRITE
130 [description]
131 This sets the 'R' (reposition request) bit of the vss status flags
132 which enqueues a request to jump n seconds forwards or backwards.
133
134 Example:
135
136 para_client ff 30-
137
138 jumps 30 seconds backwards.
139
140 [/description]
141
142 [subcommand help]
143 purpose = list available commands or print command-specific help
144 non-opts-name = [command]
145 aux_info = NO_PERMISSION_REQUIRED
146 [description]
147 Without any arguments, help prints a list of available commands. When
148 called with a command name as first argument, it prints the description
149 of this command.
150 [/description]
151
152 [subcommand hup]
153 purpose = reload config file, log file and user list
154 aux_info = VSS_WRITE
155 [description]
156 Reread the config file and the user list file, close and reopen the log
157 file, and ask the afs process to do the same. Sending the HUP signal
158 to the server process has the same effect as running this command.
159 [/description]
160
161 [subcommand init]
162 purpose = initialize the database tables for the audio file selector
163 synopsis = [table_name...]
164 aux_info = AFS_READ | AFS_WRITE
165 [description]
166 When invoked without arguments, this command creates all
167 tables: audio_files, attributes, scores, moods, lyrics, images,
168 playlists. Otherwise only the given tables are created.
169 [/description]
170
171 [subcommand jmp]
172 purpose = reposition the current stream
173 non-opts-name = n
174 aux_info = VSS_READ | VSS_WRITE
175 [description]
176 Set the 'R' (reposition request) bit of the vss status flags and
177 enqueue a request to jump to n% of the current audio file, where 0 <=
178 n <= 100.
179 [/description]
180
181 [subcommand ls]
182 purpose = list audio files which match a pattern
183 non-opts-name = [pattern...]
184 aux_info = AFS_READ
185 [description]
186 If no pattern is given, all files are listed. Otherwise, the command
187 lists all files of the audio file table whose path matches at least
188 one of the given patterns.
189 [/description]
190 [option listing-mode]
191 short_opt = l
192 summary = use alternative output format
193 arg_type = string
194 arg_info = optional_arg
195 typestr = mode
196 default_val = long
197 [help]
198 The optional mode argument is either a single character or a word
199 according to the following list.
200
201 short (s). List only the path or basename (last component of the path),
202 depending on whether -p is also given. This listing mode acts as if
203 --listing-mode had not been given.
204
205 long (l). Show detailed information. This is the default if no argument
206 to --listing-mode is supplied.
207
208 verbose (v). Multi-line output, one row per data field stored in the
209 audio file table.
210
211 parser-friendly (p). Like verbose listing mode, but use numerical
212 values for the names of the output fields and prefix each line with
213 a length field.
214
215 mbox (m). Generate output suitable to be viewed with a mail
216 program. One "mail" per matching audio file.
217
218 chunk-table (c). Print path (or basename, depending on whether -p is
219 also given), chunk time and chunk offsets.
220
221 [/help]
222 [option full-path]
223 short_opt = F
224 summary = list full paths, match full paths against patterns
225 [help]
226 This option is the default, so it does nothing. Deprecated as of
227 v0.6.0, scheduled for removal in v0.6.1.
228 [/help]
229 [option basename]
230 short_opt = b
231 summary = list and match basenames only
232 [help]
233 Print only the basename of each matching file and match only the
234 basenames of the paths stored in the audio file table against the
235 given patterns. The default is to print and match the full path.
236 [/help]
237 [option admissible]
238 short_opt = a
239 summary = list only admissible files
240 [help]
241 List only files which are admissible with respect to the current mood
242 or playlist.
243 [/help]
244 [option reverse]
245 short_opt = r
246 summary = reverse sort order
247 [option unix-date]
248 short_opt = d
249 summary = print dates as seconds after the epoch
250 [option sort]
251 short_opt = s
252 summary = change sort order
253 arg_type = string
254 arg_info = required_arg
255 typestr = order
256 default_val = path
257 [help]
258 The sort order must be given as an required argument. Like for
259 --listing-mode, this argument may either be a single character or a
260 word, according to the following list.
261
262 path (p). Sort alphabetically by path or basename, depending on
263 whether -b is given. This is the default if --sort is not given.
264
265 score (s). Iterate over the entries of the score table, rather than
266 the audio file table. This sort order implies --admissible, since
267 the score table contains only admissible files.
268
269 lastplayed (l)
270
271 numplayed (n)
272
273 frequency (f)
274
275 channels (c)
276
277 image-id (i)
278
279 lyrics-id (y)
280
281 bitrate (b)
282
283 duration (d)
284
285 audio-format (a)
286
287 If --sort is not given, path sort is implied.
288 [/help]
289
290 [subcommand lsatt]
291 purpose = list attributes
292 aux_info = AFS_READ
293 [description]
294 Print the list of all defined attributes which match the given
295 pattern. If no pattern is given, the full list is printed.
296 [/description]
297
298 [option id-sort]
299 short_opt = i
300 summary = sort attributes by id
301 [help]
302 The default is to sort alphabetically by name.
303
304 Attributes are internally represented as an 64 bit array. The attribute
305 id is the bit number in this array.
306 [/help]
307 [option long]
308 short_opt = l
309 summary = print long listing
310 [help]
311 The long listing prints the attribute id in addition to the name of
312 the attribute. The id is printed as a decimal number and is separated
313 from the name by a tab character.
314 [/help]
315 [option reverse]
316 short_opt = r
317 summary = reverse sort order
318
319 [subcommand mvatt]
320 purpose = rename an attribute
321 synopsis = source dest
322 aux_info = AFS_READ | AFS_WRITE
323 [description]
324 Rename the attribute given by the first argument to the destination
325 given by the second argument. It is an error if the destination
326 attribute exists.
327 [/description]
328
329 [subcommand next]
330 purpose = close the stream and start to stream the next audio file
331 aux_info = VSS_READ | VSS_WRITE
332 [description]
333 Set the 'N' (next audio file) bit of the vss status flags. This
334 instructs the server to close the current stream, if any. The 'P'
335 (playing) bit is not modified by this command. If it is on, playing
336 continues with the next audio file.
337
338 This command is equivalent to stop if paused, and has no effect
339 if stopped.
340 [/description]
341
342 [subcommand nomore]
343 purpose = stop playing after current audio file
344 aux_info = VSS_READ | VSS_WRITE
345 [description]
346 Set the 'O' (no more) bit of the vss status flags which asks
347 para_server to clear the 'P' (playing) bit after the 'N' (next audio
348 file) bit transitions from off to on (because the end of the current
349 audio file is reached). Use this command instead of stop if you don't
350 like sudden endings.
351 [/description]
352
353 [subcommand pause]
354 purpose = suspend the current stream
355 aux_info = VSS_READ | VSS_WRITE
356 [description]
357 Clear the 'P' (playing) bit of the vss status flags.
358 [/description]
359
360 [subcommand play]
361 purpose = start or resume playback
362 aux_info = VSS_READ | VSS_WRITE
363 [description]
364 Set the 'P' (playing) bit of the vss status flags.
365 [/description]
366
367 [subcommand rm]
368 purpose = remove rows from the audio file table
369 non-opts-name = pattern...
370 aux_info = AFS_READ | AFS_WRITE
371 [description]
372 Remove all rows of the audio file table which match any of the given
373 patterns. Note that this affects only the database table; the command
374 won't touch your audio files on disk.
375 [/description]
376 [option verbose]
377 short_opt = v
378 summary = print paths of deleted rows
379 [option force]
380 short_opt = f
381 summary = don't complain if nothing was removed
382 [option pathname-match]
383 short_opt = p
384 summary = modify matching behaviour
385 [help]
386 Match a slash in the path only with a slash in pattern and not by an
387 asterisk (*) or a question mark (?) metacharacter, nor by a bracket
388 expression ([]) containing a slash (see fnmatch(3)).
389 [/help]
390
391 [subcommand rmatt]
392 purpose = remove attribute(s)
393 non-opts-name = pattern...
394 aux_info = AFS_READ | AFS_WRITE
395 [description]
396 Remove all attributes which match any given pattern. All information
397 about the removed attributes in the audio file table is lost.
398 [/description]
399
400 [subcommand select]
401 purpose = activate a mood or a playlist
402 non-opts-name = specifier/name
403 aux_info = AFS_READ | AFS_WRITE
404 [description]
405 The specifier is either 'm' or 'p' to indicate whether a playlist or
406 a mood should be activated. Example:
407
408 select m/foo
409
410 activates the mood named 'foo'.
411 [/description]
412
413 [subcommand sender]
414 purpose = control paraslash senders
415 synopsis = [sender cmd [arguments]]
416 aux_info = VSS_READ | VSS_WRITE
417 [description]
418 Send a command to a specific sender. The following commands are
419 available, but not all senders support every command.
420
421 help, on, off, add, delete, allow, deny, status.
422
423 The help command prints the help text of the given sender. If no
424 command is given the list of available senders is shown.
425
426 Example:
427
428 para_client sender http help
429
430 [/description]
431
432 [subcommand setatt]
433 purpose = set or unset attributes
434 synopsis = attribute{+|-}... pattern...
435 aux_info = AFS_READ | AFS_WRITE
436 [description]
437 Set ('+') or unset ('-') the given attributes for all audio files
438 matching the given pattern. Example:
439
440 setatt rock+ punk+ pop- '*foo.mp3'
441
442 sets the 'rock' and the 'punk' attribute and unsets the 'pop' attribute
443 of all files ending with 'foo.mp3'.
444 [/description]
445
446 [subcommand si]
447 purpose = print server info
448 aux_info = NO_PERMISSION_REQUIRED
449 [description]
450 Show server and afs PID, number of connections, uptime and more.
451 [/description]
452
453 [subcommand stat]
454 purpose = print information about the current audio file
455 aux_info = VSS_READ
456 [option num]
457 short_opt = n
458 summary = number of times to show the status info
459 arg_info = required_arg
460 arg_type = uint32
461 typestr = num
462 [help]
463 Exit after the status information has been shown num times. If this
464 option is not given, the command runs in an endless loop.
465 [/help]
466 [option parser-friendly]
467 short_opt = p
468 summary = enable parser-friendly output
469 [help]
470 Show status item identifiers as numerical values and prefix each
471 status item with its size in bytes.
472 [/help]
473
474 [subcommand stop]
475 purpose = stop playback
476 aux_info = VSS_READ | VSS_WRITE
477 [description]
478 Clear the 'P' (playing) bit and set the 'N' (next audio file) bit of
479 the vss status flags, effectively stopping playback.
480 [/description]
481
482 [subcommand tasks]
483 purpose = list active server tasks
484 aux_info = NO_PERMISSION_REQUIRED
485 [description]
486 For each task, print ID, status and name. This is mostly useful
487 for debugging.
488 [/description]
489
490 [subcommand term]
491 purpose = ask the server to terminate
492 aux_info = VSS_READ | VSS_WRITE
493 [description]
494 Shut down the server. Instead of this command, you can also send
495 SIGINT or SIGTERM to the para_server process. It should never be
496 necessary to send SIGKILL.
497 [/description]
498
499 [subcommand touch]
500 purpose = manipulate the afs information of audio files
501 non-opts-name = pattern...
502 aux_info = AFS_READ | AFS_WRITE
503 [description]
504 This command modifies the afs info structure of all rows of the audio
505 file table whose path matches at least one of the given patters.
506
507 If at least one option is given which takes a number as its argument,
508 only those fields of the afs info structure are updated which
509 correspond to the given options while all other fields stay unmodified.
510
511 If no such option is given, the lastplayed field is set to the current
512 time and the value of the numplayed field is increased by one while
513 all other fields are left unchanged. This mimics what happens when
514 the virtual streaming system selects the file for streaming.
515
516 If the file is admissible for the current mood (or contained in the
517 current playlist), its score is recomputed according to the changed
518 values.
519 [/description]
520 [option numplayed]
521 short_opt = n
522 summary = set the numplayed count manually
523 arg_type = uint32
524 arg_info = required_arg
525 typestr = num
526 [help]
527 The numplayed count of an audio file is the number of times the file
528 was selected for streaming. It is one of the inputs to the scoring
529 function which determines the order in which admissible files are
530 streamed.
531
532 The virtual streaming system increases this number automatically each
533 time it opens the file for streaming.
534 [/help]
535 [option lastplayed]
536 short_opt = l
537 summary = set the lastplayed time manually
538 arg_type = uint64
539 arg_info = required_arg
540 typestr = num
541 [help]
542 The lastplayed time of an audio file is the time when the file was
543 last opened for streaming.
544
545 Like the numplayed count, it is an input for the scoring function
546 and is updated automatically by the virtual streaming system.
547
548 The argument must be a number of seconds since the epoch. Example:
549
550 touch -l=$(date +%s) file
551
552 sets the lastplayed time of 'file' to the current time.
553 [/help]
554 [option image-id]
555 short_opt = i
556 summary = set the image id
557 arg_type = uint32
558 arg_info = required_arg
559 typestr = num
560 [help]
561 The afs info structure of each row of the audio file table contains
562 a slot for the image id of the audio file that corresponds to the
563 row. The image id stored in this slot refers to the key in the image
564 table that identifies the blob.
565
566 When a new audio file is added to the audio file table, its image
567 id starts out as zero, indicating that there is no image associated
568 with the file. Setting the image id to a non-zero number associates
569 the file with a particular blob of the image table, for example the
570 cover art of the album in jpg format.
571 [/help]
572 [option lyrics-id]
573 short_opt = y
574 summary = set the lyrics id
575 arg_type = uint32
576 arg_info = required_arg
577 typestr = num
578 [help]
579 This option works just like --image-id, but sets the lyrics ID rather
580 than the image id.
581 [/help]
582 [option amp]
583 short_opt = a
584 summary = set the amplification value (0-255)
585 arg_type = uint32
586 arg_info = required_arg
587 typestr = num
588 [help]
589 The amplification value of an audio file is a number which is stored
590 in the afs info structure.
591
592 The value determines the scaling factor by which the amplitude of
593 the decoded samples should be multiplied in order to normalize the
594 volume. A value of zero means no amplification, 64 means the amplitude
595 should be multiplied by a factor of two, 128 by three and so on.
596
597 The amp filter of para_audiod amplifies the volume according to
598 this value.
599 [/help]
600 [option verbose]
601 short_opt = v
602 summary = explain what is being done
603 [option pathname-match]
604 short_opt = p
605 summary = modify matching behaviour
606 [help]
607 Match a slash in the path only with a slash in pattern and not by an
608 asterisk (*) or a question mark (?) metacharacter, nor by a bracket
609 expression ([]) containing a slash (see fnmatch(3)).
610 [/help]
611
612 [subcommand version]
613 purpose = print the git version string of para_server
614 aux_info = NO_PERMISSION_REQUIRED
615 [option verbose]
616 short_opt = v
617 summary = print detailed (multi-line) version text
618
619 m4_define(`BLOB_COMMANDS', `
620 [subcommand rm`$2']
621 purpose = remove `$1' blob(s)
622 non-opts-name = pattern...
623 aux_info = AFS_READ | AFS_WRITE
624 [description]
625 Remove all `$1' blobs which match any of the given patterns.
626 [/description]
627
628 [subcommand mv`$2']
629 purpose = rename `$1' blob(s)
630 non-opts-name = source dest
631 aux_info = AFS_READ | AFS_WRITE
632 [description]
633 Rename `$1' source to dest. The command fails if the source `$1'
634 does not exist or if the destination `$1' already exists.
635 [/description]
636
637 [subcommand add`$2']
638 purpose = add a blob to the `$1' table
639 non-opts-name = `$1'_name
640 aux_info = AFS_READ | AFS_WRITE
641 [description]
642 Read from stdin and ask the audio file selector to create a blob in
643 the `$1' table. If the named blob already exists, it gets replaced
644 with the new data.
645 [/description]
646
647 [subcommand cat`$2']
648 purpose = dump a `$1' blob to stdout
649 non-opts-name = `$1'_name
650 aux_info = AFS_READ
651
652 [subcommand ls`$2']
653 purpose = list blobs of type `$1' which match a pattern
654 non-opts-name = [pattern...]
655 aux_info = AFS_READ
656 [description]
657 Print the list of all blobs which match the given pattern. If no
658 pattern is given, the full list is printed.
659 [/description]
660 [option id-sort]
661 short_opt = i
662 summary = sort by identifier
663 [help]
664 The default is to sort alphabetically by name.
665 [/help]
666 [option long]
667 short_opt = l
668 summary = long listing
669 [help]
670 Print identifier and name. The default is to print only the name.
671 [/help]
672 [option reverse]
673 short_opt = r
674 summary = reverse sort order
675 ')
676
677 BLOB_COMMANDS(`moods', `mood')
678 BLOB_COMMANDS(`playlist', `pl')
679 BLOB_COMMANDS(`image', `img')
680 BLOB_COMMANDS(`lyrics', `lyr')