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