2 caption = list of server commands
3 aux_info_prefix = Permissions:
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
17 purpose = add or update audio files
18 non-opts-name = path...
19 aux_info = AFS_READ | AFS_WRITE
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.
28 summary = add all files
30 The default is to add only files ending in a known suffix for a
31 supported audio format.
35 summary = add files lazily
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.
43 summary = force adding/updating
45 Recompute the audio format handler data even if a file with the same
46 path and the same hash value exists.
50 summary = enable verbose mode
52 Print what is being done.
56 purpose = add new attribute(s)
57 non-opts-name = attribute...
58 aux_info = AFS_READ | AFS_WRITE
60 This adds new attributes to the attribute table. At most 64 attributes
65 purpose = run integrity checks on database tables
68 If no options are given, all checks are run.
72 summary = run audio file table checks
74 Report stale paths and invalid image and lyrics ids of the audio
79 summary = check for invalid attributes
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.
86 summary = check for invalid mood definitions
88 Run syntax checks on all moods of the mood table.
92 summary = find invalid paths in playlists
94 Check all playlists for paths not contained in the audio file table.
98 purpose = copy selected parts of the audio file selector info
99 non-opts-name = source pattern...
100 aux_info = AFS_READ | AFS_WRITE
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.
107 [option attribute-bitmap]
109 summary = copy the attribute bitmap
112 summary = copy the image id
115 summary = copy the lyrics id
118 summary = copy the lastplayed timestamp
121 summary = copy the numplayed counter
124 summary = enable verbose mode
127 purpose = jump forward or backward in the current audio file
129 aux_info = VSS_READ | VSS_WRITE
131 This enqueues a request to reposition the audio stream according to
132 the argument, which may be a signed or an unsigned integer. Negative
133 values correspond to backward jumps.
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.
143 purpose = list available commands or print command-specific help
144 non-opts-name = [command]
145 aux_info = NO_PERMISSION_REQUIRED
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.
151 m4_include(`long-help.m4')
154 purpose = reload config file, log file and user list
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.
163 purpose = initialize the database tables for the audio file selector
164 synopsis = [table_name...]
165 aux_info = AFS_READ | AFS_WRITE
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.
172 m4_include(`com_ll.m4')
175 purpose = reposition the current stream
177 aux_info = VSS_READ | VSS_WRITE
179 Set the 'R' (reposition request) bit of the vss status flags and
180 enqueue a request to jump to n% of the current audio file, where 0 <=
185 purpose = list audio files which match a pattern
186 non-opts-name = [pattern...]
189 If no pattern is given, all files are listed. Otherwise, the command
190 lists all files of the audio file table whose path matches at least
191 one of the given patterns.
193 [option listing-mode]
195 summary = use alternative output format
197 arg_info = optional_arg
201 The optional mode argument is either a single character or a word
202 according to the following list.
204 short (s). List only the path or basename (last component of the path),
205 depending on whether -p is also given. This listing mode acts as if
206 --listing-mode had not been given.
208 long (l). Show detailed information. This is the default if no argument
209 to --listing-mode is supplied.
211 verbose (v). Multi-line output, one row per data field stored in the
214 parser-friendly (p). Like verbose listing mode, but use numerical
215 values for the names of the output fields and prefix each line with
218 mbox (m). Generate output suitable to be viewed with a mail
219 program. One "mail" per matching audio file.
221 chunk-table (c). Print path (or basename, depending on whether -p is
222 also given), chunk time and chunk offsets.
227 summary = list and match basenames only
229 Print only the basename of each matching file and match only the
230 basenames of the paths stored in the audio file table against the
231 given patterns. The default is to print and match the full path.
235 summary = list only admissible files
237 List only files which are admissible with respect to the current mood
242 summary = reverse sort order
245 summary = print dates as seconds after the epoch
248 summary = change sort order
250 arg_info = required_arg
254 The sort order must be given as an required argument. Like for
255 --listing-mode, this argument may either be a single character or a
256 word, according to the following list.
258 path (p). Sort alphabetically by path or basename, depending on
259 whether -b is given. This is the default if --sort is not given.
261 score (s). Iterate over the entries of the score table, rather than
262 the audio file table. This sort order implies --admissible, since
263 the score table contains only admissible files.
285 If --sort is not given, path sort is implied.
289 purpose = list attributes
292 Print the list of all defined attributes which match the given
293 pattern. If no pattern is given, the full list is printed.
298 summary = sort attributes by id
300 The default is to sort alphabetically by name.
302 Attributes are internally represented as an 64 bit array. The attribute
303 id is the bit number in this array.
307 summary = print long listing
309 The long listing prints the attribute id in addition to the name of
310 the attribute. The id is printed as a decimal number and is separated
311 from the name by a tab character.
315 summary = reverse sort order
318 purpose = rename an attribute
319 synopsis = source dest
320 aux_info = AFS_READ | AFS_WRITE
322 Rename the attribute given by the first argument to the destination
323 given by the second argument. It is an error if the destination
328 purpose = close the stream and start to stream the next audio file
329 aux_info = VSS_READ | VSS_WRITE
331 Set the 'N' (next audio file) bit of the vss status flags. This
332 instructs the server to close the current stream, if any. The 'P'
333 (playing) bit is not modified by this command. If it is on, playing
334 continues with the next audio file.
336 This command is equivalent to stop if paused, and has no effect
341 purpose = stop playing after current audio file
342 aux_info = VSS_READ | VSS_WRITE
344 Set the 'O' (no more) bit of the vss status flags which asks
345 para_server to clear the 'P' (playing) bit after the 'N' (next audio
346 file) bit transitions from off to on (because the end of the current
347 audio file is reached). Use this command instead of stop if you don't
352 purpose = suspend the current stream
353 aux_info = VSS_READ | VSS_WRITE
355 Clear the 'P' (playing) bit of the vss status flags.
359 purpose = start or resume playback
360 aux_info = VSS_READ | VSS_WRITE
362 Set the 'P' (playing) bit of the vss status flags.
366 purpose = remove rows from the audio file table
367 non-opts-name = pattern...
368 aux_info = AFS_READ | AFS_WRITE
370 Remove all rows of the audio file table which match any of the given
371 patterns. Note that this affects only the database table; the command
372 won't touch your audio files on disk.
376 summary = print paths of deleted rows
379 summary = don't complain if nothing was removed
380 [option pathname-match]
382 summary = modify matching behaviour
384 Match a slash in the path only with a slash in pattern and not by an
385 asterisk (*) or a question mark (?) metacharacter, nor by a bracket
386 expression ([]) containing a slash (see fnmatch(3)).
390 purpose = remove attribute(s)
391 non-opts-name = pattern...
392 aux_info = AFS_READ | AFS_WRITE
394 Remove all attributes which match any given pattern. All information
395 about the removed attributes in the audio file table is lost.
399 purpose = activate a mood or a playlist
400 non-opts-name = specifier/name
401 aux_info = AFS_READ | AFS_WRITE
403 The specifier is either 'm' or 'p' to indicate whether a playlist or
404 a mood should be activated. Example:
408 activates the mood named 'foo'.
412 purpose = control paraslash senders
413 synopsis = [sender subcmd [arguments]]
414 aux_info = VSS_READ | VSS_WRITE
416 This command executes a subcommand for the given sender, which is
417 one of "http", "dccp" or "udp". Various subcommands exist to print
418 information about the sender, to activate and deactivate the sender,
419 and to change the access permissions and targets. The following
420 subcommands are available:
422 help, status, on, off, allow, deny, add, delete.
424 All senders support the first four commands. The "allow" and "deny"
425 commands are supported by the http and the dccp senders while "add"
426 and "delete" are only supported by the udp sender. If no sender is
427 given, the list of available senders is shown.
431 Get help for the udp sender (contains further examples):
435 Show the access control list and the number of connected clients of
440 Senders may be activated and deactivated independently of each
441 other. The following command switches off the dccp sender:
445 Add an UDP unicast for a client to the target list of the UDP sender:
447 sender udp add client.foo.org
449 Start UDP multicast, using the default multicast address:
451 sender udp add 224.0.1.38
456 purpose = set or unset attributes
457 synopsis = attribute{+|-}... pattern...
458 aux_info = AFS_READ | AFS_WRITE
460 Set ('+') or unset ('-') the given attributes for all audio files
461 matching the given pattern. Example:
463 setatt rock+ punk+ pop- '*foo.mp3'
465 sets the 'rock' and the 'punk' attribute and unsets the 'pop' attribute
466 of all files ending with 'foo.mp3'.
470 purpose = print server info
471 aux_info = NO_PERMISSION_REQUIRED
473 Show server and afs PID, number of connections, uptime and more.
477 purpose = print information about the current audio file
481 summary = number of times to show the status info
482 arg_info = required_arg
486 Exit after the status information has been shown num times. If this
487 option is not given, the command runs in an endless loop.
489 [option parser-friendly]
491 summary = enable parser-friendly output
493 Show status item identifiers as numerical values and prefix each
494 status item with its size in bytes.
498 purpose = stop playback
499 aux_info = VSS_READ | VSS_WRITE
501 Clear the 'P' (playing) bit and set the 'N' (next audio file) bit of
502 the vss status flags, effectively stopping playback.
506 purpose = ask the server to terminate
507 aux_info = VSS_READ | VSS_WRITE
509 Shut down the server. Instead of this command, you can also send
510 SIGINT or SIGTERM to the para_server process. It should never be
511 necessary to send SIGKILL.
515 purpose = manipulate the afs information of audio files
516 non-opts-name = pattern...
517 aux_info = AFS_READ | AFS_WRITE
519 This command modifies the afs info structure of all rows of the audio
520 file table whose path matches at least one of the given patters.
522 If at least one option is given which takes a number as its argument,
523 only those fields of the afs info structure are updated which
524 correspond to the given options while all other fields stay unmodified.
526 If no such option is given, the lastplayed field is set to the current
527 time and the value of the numplayed field is increased by one while
528 all other fields are left unchanged. This mimics what happens when
529 the virtual streaming system selects the file for streaming.
531 If the file is admissible for the current mood (or contained in the
532 current playlist), its score is recomputed according to the changed
537 summary = set the numplayed count manually
539 arg_info = required_arg
542 The numplayed count of an audio file is the number of times the file
543 was selected for streaming. It is one of the inputs to the scoring
544 function which determines the order in which admissible files are
547 The virtual streaming system increases this number automatically each
548 time it opens the file for streaming.
552 summary = set the lastplayed time manually
554 arg_info = required_arg
557 The lastplayed time of an audio file is the time when the file was
558 last opened for streaming.
560 Like the numplayed count, it is an input for the scoring function
561 and is updated automatically by the virtual streaming system.
563 The argument must be a number of seconds since the epoch. Example:
565 touch -l=$(date +%s) file
567 sets the lastplayed time of 'file' to the current time.
571 summary = set the image id
573 arg_info = required_arg
576 The afs info structure of each row of the audio file table contains
577 a slot for the image id of the audio file that corresponds to the
578 row. The image id stored in this slot refers to the key in the image
579 table that identifies the blob.
581 When a new audio file is added to the audio file table, its image
582 id starts out as zero, indicating that there is no image associated
583 with the file. Setting the image id to a non-zero number associates
584 the file with a particular blob of the image table, for example the
585 cover art of the album in jpg format.
589 summary = set the lyrics id
591 arg_info = required_arg
594 This option works just like --image-id, but sets the lyrics ID rather
599 summary = set the amplification value (0-255)
601 arg_info = required_arg
604 The amplification value of an audio file is a number which is stored
605 in the afs info structure.
607 The value determines the scaling factor by which the amplitude of
608 the decoded samples should be multiplied in order to normalize the
609 volume. A value of zero means no amplification, 64 means the amplitude
610 should be multiplied by a factor of two, 128 by three and so on.
612 The amp filter of para_audiod amplifies the volume according to
617 summary = explain what is being done
618 [option pathname-match]
620 summary = modify matching behaviour
622 Match a slash in the path only with a slash in pattern and not by an
623 asterisk (*) or a question mark (?) metacharacter, nor by a bracket
624 expression ([]) containing a slash (see fnmatch(3)).
628 purpose = print the git version string of para_server
629 aux_info = NO_PERMISSION_REQUIRED
632 summary = print detailed (multi-line) version text
634 m4_define(`BLOB_COMMANDS', `
636 purpose = remove `$1' blob(s)
637 non-opts-name = pattern...
638 aux_info = AFS_READ | AFS_WRITE
640 Remove all `$1' blobs which match any of the given patterns.
644 purpose = rename `$1' blob(s)
645 non-opts-name = source dest
646 aux_info = AFS_READ | AFS_WRITE
648 Rename `$1' source to dest. The command fails if the source `$1'
649 does not exist or if the destination `$1' already exists.
653 purpose = add a blob to the `$1' table
654 non-opts-name = `$1'_name
655 aux_info = AFS_READ | AFS_WRITE
657 Read from stdin and ask the audio file selector to create a blob in
658 the `$1' table. If the named blob already exists, it gets replaced
663 purpose = dump a `$1' blob to stdout
664 non-opts-name = `$1'_name
668 purpose = list blobs of type `$1' which match a pattern
669 non-opts-name = [pattern...]
672 Print the list of all blobs which match the given pattern. If no
673 pattern is given, the full list is printed.
677 summary = sort by identifier
679 The default is to sort alphabetically by name.
683 summary = long listing
685 Print identifier and name. The default is to print only the name.
689 summary = reverse sort order
692 BLOB_COMMANDS(`moods', `mood')
693 BLOB_COMMANDS(`playlist', `pl')
694 BLOB_COMMANDS(`image', `img')
695 BLOB_COMMANDS(`lyrics', `lyr')