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 ff]
  56         purpose = jump N seconds forward or backward
  57         synopsis = n[-]
  58         aux_info = VSS_READ | VSS_WRITE
  59         [description]
  60                 This sets the 'R' (reposition request) bit of the vss status flags
  61                 which enqueues a request to jump n seconds forwards or backwards.
  62
  63                 Example:
  64
  65                      para_client ff 30-
  66
  67                 jumps 30 seconds backwards.
  68
  69         [/description]
  70
  71 [subcommand help]
  72         purpose = list available commands or print command-specific help
  73         non-opts-name = [command]
  74         aux_info = NO_PERMISSION_REQUIRED
  75         [description]
  76                 Without any arguments, help prints a list of available commands. When
  77                 called with a command name as first argument, it prints the description
  78                 of this command.
  79         [/description]
  80
  81 [subcommand hup]
  82         purpose = reload config file, log file and user list
  83         aux_info = VSS_WRITE
  84         [description]
  85                 Reread the config file and the user list file, close and reopen the log
  86                 file, and ask the afs process to do the same. Sending the HUP signal
  87                 to the server process has the same effect as running this command.
  88         [/description]
  89
  90 [subcommand init]
  91         purpose = initialize the database tables for the audio file selector
  92         synopsis = [table_name...]
  93         aux_info = AFS_READ | AFS_WRITE
  94         [description]
  95                 When invoked without arguments, this command creates all
  96                 tables: audio_files, attributes, scores, moods, lyrics, images,
  97                 playlists. Otherwise only the given tables are created.
  98         [/description]
  99
 100 [subcommand jmp]
 101         purpose = reposition the current stream
 102         non-opts-name = n
 103         aux_info = VSS_READ | VSS_WRITE
 104         [description]
 105                 Set the 'R' (reposition request) bit of the vss status flags and
 106                 enqueue a request to jump to n% of the current audio file, where 0 <=
 107                 n <= 100.
 108         [/description]
 109
 110 [subcommand lsatt]
 111         purpose = list attributes
 112         aux_info = AFS_READ
 113         [description]
 114                 Print the list of all defined attributes which match the given
 115                 pattern. If no pattern is given, the full list is printed.
 116         [/description]
 117
 118         [option id-sort]
 119                 short_opt = i
 120                 summary = sort attributes by id
 121                 [help]
 122                         The default is to sort alphabetically by name.
 123
 124                         Attributes are internally represented as an 64 bit array. The attribute
 125                         id is the bit number in this array.
 126                 [/help]
 127         [option long]
 128                 short_opt = l
 129                 summary = print long listing
 130                 [help]
 131                         The long listing prints the attribute id in addition to the name of
 132                         the attribute. The id is printed as a decimal number and is separated
 133                         from the name by a tab character.
 134                 [/help]
 135         [option reverse]
 136                 short_opt = r
 137                 summary = reverse sort order
 138
 139 [subcommand mvatt]
 140         purpose = rename an attribute
 141         synopsis = source dest
 142         aux_info = AFS_READ | AFS_WRITE
 143         [description]
 144                 Rename the attribute given by the first argument to the destination
 145                 given by the second argument. It is an error if the destination
 146                 attribute exists.
 147         [/description]
 148
 149 [subcommand next]
 150         purpose = close the stream and start to stream the next audio file
 151         aux_info = VSS_READ | VSS_WRITE
 152         [description]
 153                 Set the 'N' (next audio file) bit of the vss status flags. This
 154                 instructs the server to close the current stream, if any. The 'P'
 155                 (playing) bit is not modified by this command. If it is on, playing
 156                 continues with the next audio file.
 157
 158                 This command is equivalent to stop if paused, and has no effect
 159                 if stopped.
 160         [/description]
 161
 162 [subcommand nomore]
 163         purpose = stop playing after current audio file
 164         aux_info = VSS_READ | VSS_WRITE
 165         [description]
 166                 Set the 'O' (no more) bit of the vss status flags which asks
 167                 para_server to clear the 'P' (playing) bit after the 'N' (next audio
 168                 file) bit transitions from off to on (because the end of the current
 169                 audio file is reached). Use this command instead of stop if you don't
 170                 like sudden endings.
 171         [/description]
 172
 173 [subcommand pause]
 174         purpose = suspend the current stream
 175         aux_info = VSS_READ | VSS_WRITE
 176         [description]
 177                 Clear the 'P' (playing) bit of the vss status flags.
 178         [/description]
 179
 180 [subcommand play]
 181         purpose = start or resume playback
 182         aux_info = VSS_READ | VSS_WRITE
 183         [description]
 184                 Set the 'P' (playing) bit of the vss status flags.
 185         [/description]
 186
 187 [subcommand sender]
 188         purpose = control paraslash senders
 189         synopsis = [sender cmd [arguments]]
 190         aux_info = VSS_READ | VSS_WRITE
 191         [description]
 192                 Send a command to a specific sender. The following commands are
 193                 available, but not all senders support every command.
 194
 195                        help, on, off, add, delete, allow, deny, status.
 196
 197                 The help command prints the help text of the given sender. If no
 198                 command is given the list of available senders is shown.
 199
 200                 Example:
 201
 202                         para_client sender http help
 203
 204         [/description]
 205
 206 [subcommand setatt]
 207         purpose = set or unset attributes
 208         synopsis = attribute{+|-}... pattern...
 209         aux_info = AFS_READ | AFS_WRITE
 210         [description]
 211                 Set ('+') or unset ('-') the given attributes for all audio files
 212                 matching the given pattern. Example:
 213
 214                         setatt rock+ punk+ pop- '*foo.mp3'
 215
 216                 sets the 'rock' and the 'punk' attribute and unsets the 'pop' attribute
 217                 of all files ending with 'foo.mp3'.
 218         [/description]
 219
 220 [subcommand si]
 221         purpose = print server info
 222         aux_info = NO_PERMISSION_REQUIRED
 223         [description]
 224                 Show server and afs PID, number of connections, uptime and more.
 225         [/description]
 226
 227 [subcommand stat]
 228         purpose = print information about the current audio file
 229         aux_info = VSS_READ
 230         [option num]
 231                 short_opt = n
 232                 summary = number of times to show the status info
 233                 arg_info = required_arg
 234                 arg_type = uint32
 235                 typestr = num
 236                 [help]
 237                         Exit after the status information has been shown num times. If this
 238                         option is not given, the command runs in an endless loop.
 239                 [/help]
 240         [option parser-friendly]
 241                 short_opt = p
 242                 summary = enable parser-friendly output
 243                 [help]
 244                         Show status item identifiers as numerical values and prefix each
 245                         status item with its size in bytes.
 246                 [/help]
 247
 248 [subcommand stop]
 249         purpose = stop playback
 250         aux_info = VSS_READ | VSS_WRITE
 251         [description]
 252                 Clear the 'P' (playing) bit and set the 'N' (next audio file) bit of
 253                 the vss status flags, effectively stopping playback.
 254         [/description]
 255
 256 [subcommand tasks]
 257         purpose = list active server tasks
 258         aux_info = NO_PERMISSION_REQUIRED
 259         [description]
 260                 For each task, print ID, status and name. This is mostly useful
 261                 for debugging.
 262         [/description]
 263
 264 [subcommand term]
 265         purpose = ask the server to terminate
 266         aux_info = VSS_READ | VSS_WRITE
 267         [description]
 268                 Shut down the server. Instead of this command, you can also send
 269                 SIGINT or SIGTERM to the para_server process. It should never be
 270                 necessary to send SIGKILL.
 271         [/description]
 272
 273 [subcommand version]
 274         purpose = print the git version string of para_server
 275         aux_info = NO_PERMISSION_REQUIRED
 276         [option verbose]
 277                 short_opt = v
 278                 summary = print detailed (multi-line) version text
 279