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 cpsi]
  89         purpose = copy selected parts of the audio file selector info
  90         non-opts-name = source pattern...
  91         aux_info = AFS_READ | AFS_WRITE
  92         [description]
  93                 If no option, or only --verbose is given, all fields of the audio
  94                 file selector info structure are copied to each row of the audio file
  95                 table whose path matches at least one of the given patterns. Otherwise,
  96                 only those fields which correspond to the given options are copied.
  97         [/description]
  98         [option attribute-bitmap]
  99                 short_opt = a
 100                 summary = copy the attribute bitmap
 101         [option image-id]
 102                 short_opt = i
 103                 summary = copy the image id
 104         [option lyrics-id]
 105                 short_opt = y
 106                 summary = copy the lyrics id
 107         [option lastplayed]
 108                 short_opt = l
 109                 summary = copy the lastplayed timestamp
 110         [option numplayed]
 111                 short_opt = n
 112                 summary = copy the numplayed counter
 113         [option verbose]
 114                 short_opt = v
 115                 summary = enable verbose mode
 116
 117 [subcommand ff]
 118         purpose = jump N seconds forward or backward
 119         synopsis = n[-]
 120         aux_info = VSS_READ | VSS_WRITE
 121         [description]
 122                 This sets the 'R' (reposition request) bit of the vss status flags
 123                 which enqueues a request to jump n seconds forwards or backwards.
 124
 125                 Example:
 126
 127                      para_client ff 30-
 128
 129                 jumps 30 seconds backwards.
 130
 131         [/description]
 132
 133 [subcommand help]
 134         purpose = list available commands or print command-specific help
 135         non-opts-name = [command]
 136         aux_info = NO_PERMISSION_REQUIRED
 137         [description]
 138                 Without any arguments, help prints a list of available commands. When
 139                 called with a command name as first argument, it prints the description
 140                 of this command.
 141         [/description]
 142
 143 [subcommand hup]
 144         purpose = reload config file, log file and user list
 145         aux_info = VSS_WRITE
 146         [description]
 147                 Reread the config file and the user list file, close and reopen the log
 148                 file, and ask the afs process to do the same. Sending the HUP signal
 149                 to the server process has the same effect as running this command.
 150         [/description]
 151
 152 [subcommand init]
 153         purpose = initialize the database tables for the audio file selector
 154         synopsis = [table_name...]
 155         aux_info = AFS_READ | AFS_WRITE
 156         [description]
 157                 When invoked without arguments, this command creates all
 158                 tables: audio_files, attributes, scores, moods, lyrics, images,
 159                 playlists. Otherwise only the given tables are created.
 160         [/description]
 161
 162 [subcommand jmp]
 163         purpose = reposition the current stream
 164         non-opts-name = n
 165         aux_info = VSS_READ | VSS_WRITE
 166         [description]
 167                 Set the 'R' (reposition request) bit of the vss status flags and
 168                 enqueue a request to jump to n% of the current audio file, where 0 <=
 169                 n <= 100.
 170         [/description]
 171
 172 [subcommand lsatt]
 173         purpose = list attributes
 174         aux_info = AFS_READ
 175         [description]
 176                 Print the list of all defined attributes which match the given
 177                 pattern. If no pattern is given, the full list is printed.
 178         [/description]
 179
 180         [option id-sort]
 181                 short_opt = i
 182                 summary = sort attributes by id
 183                 [help]
 184                         The default is to sort alphabetically by name.
 185
 186                         Attributes are internally represented as an 64 bit array. The attribute
 187                         id is the bit number in this array.
 188                 [/help]
 189         [option long]
 190                 short_opt = l
 191                 summary = print long listing
 192                 [help]
 193                         The long listing prints the attribute id in addition to the name of
 194                         the attribute. The id is printed as a decimal number and is separated
 195                         from the name by a tab character.
 196                 [/help]
 197         [option reverse]
 198                 short_opt = r
 199                 summary = reverse sort order
 200
 201 [subcommand mvatt]
 202         purpose = rename an attribute
 203         synopsis = source dest
 204         aux_info = AFS_READ | AFS_WRITE
 205         [description]
 206                 Rename the attribute given by the first argument to the destination
 207                 given by the second argument. It is an error if the destination
 208                 attribute exists.
 209         [/description]
 210
 211 [subcommand next]
 212         purpose = close the stream and start to stream the next audio file
 213         aux_info = VSS_READ | VSS_WRITE
 214         [description]
 215                 Set the 'N' (next audio file) bit of the vss status flags. This
 216                 instructs the server to close the current stream, if any. The 'P'
 217                 (playing) bit is not modified by this command. If it is on, playing
 218                 continues with the next audio file.
 219
 220                 This command is equivalent to stop if paused, and has no effect
 221                 if stopped.
 222         [/description]
 223
 224 [subcommand nomore]
 225         purpose = stop playing after current audio file
 226         aux_info = VSS_READ | VSS_WRITE
 227         [description]
 228                 Set the 'O' (no more) bit of the vss status flags which asks
 229                 para_server to clear the 'P' (playing) bit after the 'N' (next audio
 230                 file) bit transitions from off to on (because the end of the current
 231                 audio file is reached). Use this command instead of stop if you don't
 232                 like sudden endings.
 233         [/description]
 234
 235 [subcommand pause]
 236         purpose = suspend the current stream
 237         aux_info = VSS_READ | VSS_WRITE
 238         [description]
 239                 Clear the 'P' (playing) bit of the vss status flags.
 240         [/description]
 241
 242 [subcommand play]
 243         purpose = start or resume playback
 244         aux_info = VSS_READ | VSS_WRITE
 245         [description]
 246                 Set the 'P' (playing) bit of the vss status flags.
 247         [/description]
 248
 249 [subcommand rm]
 250         purpose = remove rows from the audio file table
 251         non-opts-name = pattern...
 252         aux_info = AFS_READ | AFS_WRITE
 253         [description]
 254                 Remove all rows of the audio file table which match any of the given
 255                 patterns. Note that this affects only the database table; the command
 256                 won't touch your audio files on disk.
 257         [/description]
 258         [option verbose]
 259                 short_opt = v
 260                 summary = print paths of deleted rows
 261         [option force]
 262                 short_opt = f
 263                 summary = don't complain if nothing was removed
 264         [option pathname-match]
 265                 short_opt = p
 266                 summary = modify matching behaviour
 267                 [help]
 268                         Match a slash in the path only with a slash in pattern and not by an
 269                         asterisk (*) or a question mark (?) metacharacter, nor by a bracket
 270                         expression ([]) containing a slash (see fnmatch(3)).
 271                 [/help]
 272
 273 [subcommand rmatt]
 274         purpose = remove attribute(s)
 275         non-opts-name = pattern...
 276         aux_info = AFS_READ | AFS_WRITE
 277         [description]
 278                 Remove all attributes which match any given pattern. All information
 279                 about the removed attributes in the audio file table is lost.
 280         [/description]
 281
 282 [subcommand sender]
 283         purpose = control paraslash senders
 284         synopsis = [sender cmd [arguments]]
 285         aux_info = VSS_READ | VSS_WRITE
 286         [description]
 287                 Send a command to a specific sender. The following commands are
 288                 available, but not all senders support every command.
 289
 290                        help, on, off, add, delete, allow, deny, status.
 291
 292                 The help command prints the help text of the given sender. If no
 293                 command is given the list of available senders is shown.
 294
 295                 Example:
 296
 297                         para_client sender http help
 298
 299         [/description]
 300
 301 [subcommand setatt]
 302         purpose = set or unset attributes
 303         synopsis = attribute{+|-}... pattern...
 304         aux_info = AFS_READ | AFS_WRITE
 305         [description]
 306                 Set ('+') or unset ('-') the given attributes for all audio files
 307                 matching the given pattern. Example:
 308
 309                         setatt rock+ punk+ pop- '*foo.mp3'
 310
 311                 sets the 'rock' and the 'punk' attribute and unsets the 'pop' attribute
 312                 of all files ending with 'foo.mp3'.
 313         [/description]
 314
 315 [subcommand si]
 316         purpose = print server info
 317         aux_info = NO_PERMISSION_REQUIRED
 318         [description]
 319                 Show server and afs PID, number of connections, uptime and more.
 320         [/description]
 321
 322 [subcommand stat]
 323         purpose = print information about the current audio file
 324         aux_info = VSS_READ
 325         [option num]
 326                 short_opt = n
 327                 summary = number of times to show the status info
 328                 arg_info = required_arg
 329                 arg_type = uint32
 330                 typestr = num
 331                 [help]
 332                         Exit after the status information has been shown num times. If this
 333                         option is not given, the command runs in an endless loop.
 334                 [/help]
 335         [option parser-friendly]
 336                 short_opt = p
 337                 summary = enable parser-friendly output
 338                 [help]
 339                         Show status item identifiers as numerical values and prefix each
 340                         status item with its size in bytes.
 341                 [/help]
 342
 343 [subcommand stop]
 344         purpose = stop playback
 345         aux_info = VSS_READ | VSS_WRITE
 346         [description]
 347                 Clear the 'P' (playing) bit and set the 'N' (next audio file) bit of
 348                 the vss status flags, effectively stopping playback.
 349         [/description]
 350
 351 [subcommand tasks]
 352         purpose = list active server tasks
 353         aux_info = NO_PERMISSION_REQUIRED
 354         [description]
 355                 For each task, print ID, status and name. This is mostly useful
 356                 for debugging.
 357         [/description]
 358
 359 [subcommand term]
 360         purpose = ask the server to terminate
 361         aux_info = VSS_READ | VSS_WRITE
 362         [description]
 363                 Shut down the server. Instead of this command, you can also send
 364                 SIGINT or SIGTERM to the para_server process. It should never be
 365                 necessary to send SIGKILL.
 366         [/description]
 367
 368 [subcommand version]
 369         purpose = print the git version string of para_server
 370         aux_info = NO_PERMISSION_REQUIRED
 371         [option verbose]
 372                 short_opt = v
 373                 summary = print detailed (multi-line) version text
 374