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