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