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 N seconds forward or backward
129 aux_info = VSS_READ | VSS_WRITE
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.
138 jumps 30 seconds backwards.
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.
173 purpose = reposition the current stream
175 aux_info = VSS_READ | VSS_WRITE
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 <=
183 purpose = list audio files which match a pattern
184 non-opts-name = [pattern...]
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.
191 [option listing-mode]
193 summary = use alternative output format
195 arg_info = optional_arg
199 The optional mode argument is either a single character or a word
200 according to the following list.
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.
206 long (l). Show detailed information. This is the default if no argument
207 to --listing-mode is supplied.
209 verbose (v). Multi-line output, one row per data field stored in the
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
216 mbox (m). Generate output suitable to be viewed with a mail
217 program. One "mail" per matching audio file.
219 chunk-table (c). Print path (or basename, depending on whether -p is
220 also given), chunk time and chunk offsets.
225 summary = list and match basenames only
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.
233 summary = list only admissible files
235 List only files which are admissible with respect to the current mood
240 summary = reverse sort order
243 summary = print dates as seconds after the epoch
246 summary = change sort order
248 arg_info = required_arg
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.
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.
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.
283 If --sort is not given, path sort is implied.
287 purpose = list attributes
290 Print the list of all defined attributes which match the given
291 pattern. If no pattern is given, the full list is printed.
296 summary = sort attributes by id
298 The default is to sort alphabetically by name.
300 Attributes are internally represented as an 64 bit array. The attribute
301 id is the bit number in this array.
305 summary = print long listing
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.
313 summary = reverse sort order
316 purpose = rename an attribute
317 synopsis = source dest
318 aux_info = AFS_READ | AFS_WRITE
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
326 purpose = close the stream and start to stream the next audio file
327 aux_info = VSS_READ | VSS_WRITE
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.
334 This command is equivalent to stop if paused, and has no effect
339 purpose = stop playing after current audio file
340 aux_info = VSS_READ | VSS_WRITE
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
350 purpose = suspend the current stream
351 aux_info = VSS_READ | VSS_WRITE
353 Clear the 'P' (playing) bit of the vss status flags.
357 purpose = start or resume playback
358 aux_info = VSS_READ | VSS_WRITE
360 Set the 'P' (playing) bit of the vss status flags.
364 purpose = remove rows from the audio file table
365 non-opts-name = pattern...
366 aux_info = AFS_READ | AFS_WRITE
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.
374 summary = print paths of deleted rows
377 summary = don't complain if nothing was removed
378 [option pathname-match]
380 summary = modify matching behaviour
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)).
388 purpose = remove attribute(s)
389 non-opts-name = pattern...
390 aux_info = AFS_READ | AFS_WRITE
392 Remove all attributes which match any given pattern. All information
393 about the removed attributes in the audio file table is lost.
397 purpose = activate a mood or a playlist
398 non-opts-name = specifier/name
399 aux_info = AFS_READ | AFS_WRITE
401 The specifier is either 'm' or 'p' to indicate whether a playlist or
402 a mood should be activated. Example:
406 activates the mood named 'foo'.
410 purpose = control paraslash senders
411 synopsis = [sender cmd [arguments]]
412 aux_info = VSS_READ | VSS_WRITE
414 Send a command to a specific sender. The following commands are
415 available, but not all senders support every command.
417 help, on, off, add, delete, allow, deny, status.
419 The help command prints the help text of the given sender. If no
420 command is given the list of available senders is shown.
424 para_client sender http help
429 purpose = set or unset attributes
430 synopsis = attribute{+|-}... pattern...
431 aux_info = AFS_READ | AFS_WRITE
433 Set ('+') or unset ('-') the given attributes for all audio files
434 matching the given pattern. Example:
436 setatt rock+ punk+ pop- '*foo.mp3'
438 sets the 'rock' and the 'punk' attribute and unsets the 'pop' attribute
439 of all files ending with 'foo.mp3'.
443 purpose = print server info
444 aux_info = NO_PERMISSION_REQUIRED
446 Show server and afs PID, number of connections, uptime and more.
450 purpose = print information about the current audio file
454 summary = number of times to show the status info
455 arg_info = required_arg
459 Exit after the status information has been shown num times. If this
460 option is not given, the command runs in an endless loop.
462 [option parser-friendly]
464 summary = enable parser-friendly output
466 Show status item identifiers as numerical values and prefix each
467 status item with its size in bytes.
471 purpose = stop playback
472 aux_info = VSS_READ | VSS_WRITE
474 Clear the 'P' (playing) bit and set the 'N' (next audio file) bit of
475 the vss status flags, effectively stopping playback.
479 purpose = list active server tasks (deprecated)
480 aux_info = NO_PERMISSION_REQUIRED
482 This used to print the ID, the status and the name of each task,
483 mainly for debugging purposes. As of version 0.6.2, the subcommand
484 prints nothing. It will be removed in 0.7.0. Don't use.
488 purpose = ask the server to terminate
489 aux_info = VSS_READ | VSS_WRITE
491 Shut down the server. Instead of this command, you can also send
492 SIGINT or SIGTERM to the para_server process. It should never be
493 necessary to send SIGKILL.
497 purpose = manipulate the afs information of audio files
498 non-opts-name = pattern...
499 aux_info = AFS_READ | AFS_WRITE
501 This command modifies the afs info structure of all rows of the audio
502 file table whose path matches at least one of the given patters.
504 If at least one option is given which takes a number as its argument,
505 only those fields of the afs info structure are updated which
506 correspond to the given options while all other fields stay unmodified.
508 If no such option is given, the lastplayed field is set to the current
509 time and the value of the numplayed field is increased by one while
510 all other fields are left unchanged. This mimics what happens when
511 the virtual streaming system selects the file for streaming.
513 If the file is admissible for the current mood (or contained in the
514 current playlist), its score is recomputed according to the changed
519 summary = set the numplayed count manually
521 arg_info = required_arg
524 The numplayed count of an audio file is the number of times the file
525 was selected for streaming. It is one of the inputs to the scoring
526 function which determines the order in which admissible files are
529 The virtual streaming system increases this number automatically each
530 time it opens the file for streaming.
534 summary = set the lastplayed time manually
536 arg_info = required_arg
539 The lastplayed time of an audio file is the time when the file was
540 last opened for streaming.
542 Like the numplayed count, it is an input for the scoring function
543 and is updated automatically by the virtual streaming system.
545 The argument must be a number of seconds since the epoch. Example:
547 touch -l=$(date +%s) file
549 sets the lastplayed time of 'file' to the current time.
553 summary = set the image id
555 arg_info = required_arg
558 The afs info structure of each row of the audio file table contains
559 a slot for the image id of the audio file that corresponds to the
560 row. The image id stored in this slot refers to the key in the image
561 table that identifies the blob.
563 When a new audio file is added to the audio file table, its image
564 id starts out as zero, indicating that there is no image associated
565 with the file. Setting the image id to a non-zero number associates
566 the file with a particular blob of the image table, for example the
567 cover art of the album in jpg format.
571 summary = set the lyrics id
573 arg_info = required_arg
576 This option works just like --image-id, but sets the lyrics ID rather
581 summary = set the amplification value (0-255)
583 arg_info = required_arg
586 The amplification value of an audio file is a number which is stored
587 in the afs info structure.
589 The value determines the scaling factor by which the amplitude of
590 the decoded samples should be multiplied in order to normalize the
591 volume. A value of zero means no amplification, 64 means the amplitude
592 should be multiplied by a factor of two, 128 by three and so on.
594 The amp filter of para_audiod amplifies the volume according to
599 summary = explain what is being done
600 [option pathname-match]
602 summary = modify matching behaviour
604 Match a slash in the path only with a slash in pattern and not by an
605 asterisk (*) or a question mark (?) metacharacter, nor by a bracket
606 expression ([]) containing a slash (see fnmatch(3)).
610 purpose = print the git version string of para_server
611 aux_info = NO_PERMISSION_REQUIRED
614 summary = print detailed (multi-line) version text
616 m4_define(`BLOB_COMMANDS', `
618 purpose = remove `$1' blob(s)
619 non-opts-name = pattern...
620 aux_info = AFS_READ | AFS_WRITE
622 Remove all `$1' blobs which match any of the given patterns.
626 purpose = rename `$1' blob(s)
627 non-opts-name = source dest
628 aux_info = AFS_READ | AFS_WRITE
630 Rename `$1' source to dest. The command fails if the source `$1'
631 does not exist or if the destination `$1' already exists.
635 purpose = add a blob to the `$1' table
636 non-opts-name = `$1'_name
637 aux_info = AFS_READ | AFS_WRITE
639 Read from stdin and ask the audio file selector to create a blob in
640 the `$1' table. If the named blob already exists, it gets replaced
645 purpose = dump a `$1' blob to stdout
646 non-opts-name = `$1'_name
650 purpose = list blobs of type `$1' which match a pattern
651 non-opts-name = [pattern...]
654 Print the list of all blobs which match the given pattern. If no
655 pattern is given, the full list is printed.
659 summary = sort by identifier
661 The default is to sort alphabetically by name.
665 summary = long listing
667 Print identifier and name. The default is to print only the name.
671 summary = reverse sort order
674 BLOB_COMMANDS(`moods', `mood')
675 BLOB_COMMANDS(`playlist', `pl')
676 BLOB_COMMANDS(`image', `img')
677 BLOB_COMMANDS(`lyrics', `lyr')