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 addatt]
  56         purpose = add new attribute(s)
  57         non-opts-name = attribute...
  58         aux_info = AFS_READ | AFS_WRITE
  59         [description]
  60                 This adds new attributes to the attribute table. At most 64 attributes
  61                 may be defined.
  62         [/description]
  63
  64 [subcommand check]
  65         purpose = run integrity checks on database tables
  66         aux_info = AFS_READ
  67         [description]
  68                 If no options are given, all checks are run.
  69         [/description]
  70         [option aft]
  71                 short_opt = a
  72                 summary = run audio file table checks
  73                 [help]
  74                         Report stale paths and invalid image and lyrics ids of the audio
  75                         file table.
  76                 [/help]
  77         [option attribute]
  78                 short_opt = A
  79                 summary = check for invalid attributes
  80                 [help]
  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.
  83                 [/help]
  84         [option mood]
  85                 short_opt = m
  86                 summary = check for invalid mood definitions
  87                 [help]
  88                         Run syntax checks on all moods of the mood table.
  89                 [/help]
  90         [option playlist]
  91                 short_opt = p
  92                 summary = find invalid paths in playlists
  93                 [help]
  94                         Check all playlists for paths not contained in the audio file table.
  95                 [/help]
  96
  97 [subcommand cpsi]
  98         purpose = copy selected parts of the audio file selector info
  99         non-opts-name = source pattern...
 100         aux_info = AFS_READ | AFS_WRITE
 101         [description]
 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.
 106         [/description]
 107         [option attribute-bitmap]
 108                 short_opt = a
 109                 summary = copy the attribute bitmap
 110         [option image-id]
 111                 short_opt = i
 112                 summary = copy the image id
 113         [option lyrics-id]
 114                 short_opt = y
 115                 summary = copy the lyrics id
 116         [option lastplayed]
 117                 short_opt = l
 118                 summary = copy the lastplayed timestamp
 119         [option numplayed]
 120                 short_opt = n
 121                 summary = copy the numplayed counter
 122         [option verbose]
 123                 short_opt = v
 124                 summary = enable verbose mode
 125
 126 [subcommand ff]
 127         purpose = jump N seconds forward or backward
 128         synopsis = n[-]
 129         aux_info = VSS_READ | VSS_WRITE
 130         [description]
 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.
 133
 134                 Example:
 135
 136                      para_client ff 30-
 137
 138                 jumps 30 seconds backwards.
 139
 140         [/description]
 141
 142 [subcommand help]
 143         purpose = list available commands or print command-specific help
 144         non-opts-name = [command]
 145         aux_info = NO_PERMISSION_REQUIRED
 146         [description]
 147                 Without any arguments, help prints a list of available commands. When
 148                 called with a command name as first argument, it prints the description
 149                 of this command.
 150         [/description]
 151
 152 [subcommand hup]
 153         purpose = reload config file, log file and user list
 154         aux_info = VSS_WRITE
 155         [description]
 156                 Reread the config file and the user list file, close and reopen the log
 157                 file, and ask the afs process to do the same. Sending the HUP signal
 158                 to the server process has the same effect as running this command.
 159         [/description]
 160
 161 [subcommand init]
 162         purpose = initialize the database tables for the audio file selector
 163         synopsis = [table_name...]
 164         aux_info = AFS_READ | AFS_WRITE
 165         [description]
 166                 When invoked without arguments, this command creates all
 167                 tables: audio_files, attributes, scores, moods, lyrics, images,
 168                 playlists. Otherwise only the given tables are created.
 169         [/description]
 170
 171 [subcommand jmp]
 172         purpose = reposition the current stream
 173         non-opts-name = n
 174         aux_info = VSS_READ | VSS_WRITE
 175         [description]
 176                 Set the 'R' (reposition request) bit of the vss status flags and
 177                 enqueue a request to jump to n% of the current audio file, where 0 <=
 178                 n <= 100.
 179         [/description]
 180
 181 [subcommand lsatt]
 182         purpose = list attributes
 183         aux_info = AFS_READ
 184         [description]
 185                 Print the list of all defined attributes which match the given
 186                 pattern. If no pattern is given, the full list is printed.
 187         [/description]
 188
 189         [option id-sort]
 190                 short_opt = i
 191                 summary = sort attributes by id
 192                 [help]
 193                         The default is to sort alphabetically by name.
 194
 195                         Attributes are internally represented as an 64 bit array. The attribute
 196                         id is the bit number in this array.
 197                 [/help]
 198         [option long]
 199                 short_opt = l
 200                 summary = print long listing
 201                 [help]
 202                         The long listing prints the attribute id in addition to the name of
 203                         the attribute. The id is printed as a decimal number and is separated
 204                         from the name by a tab character.
 205                 [/help]
 206         [option reverse]
 207                 short_opt = r
 208                 summary = reverse sort order
 209
 210 [subcommand mvatt]
 211         purpose = rename an attribute
 212         synopsis = source dest
 213         aux_info = AFS_READ | AFS_WRITE
 214         [description]
 215                 Rename the attribute given by the first argument to the destination
 216                 given by the second argument. It is an error if the destination
 217                 attribute exists.
 218         [/description]
 219
 220 [subcommand next]
 221         purpose = close the stream and start to stream the next audio file
 222         aux_info = VSS_READ | VSS_WRITE
 223         [description]
 224                 Set the 'N' (next audio file) bit of the vss status flags. This
 225                 instructs the server to close the current stream, if any. The 'P'
 226                 (playing) bit is not modified by this command. If it is on, playing
 227                 continues with the next audio file.
 228
 229                 This command is equivalent to stop if paused, and has no effect
 230                 if stopped.
 231         [/description]
 232
 233 [subcommand nomore]
 234         purpose = stop playing after current audio file
 235         aux_info = VSS_READ | VSS_WRITE
 236         [description]
 237                 Set the 'O' (no more) bit of the vss status flags which asks
 238                 para_server to clear the 'P' (playing) bit after the 'N' (next audio
 239                 file) bit transitions from off to on (because the end of the current
 240                 audio file is reached). Use this command instead of stop if you don't
 241                 like sudden endings.
 242         [/description]
 243
 244 [subcommand pause]
 245         purpose = suspend the current stream
 246         aux_info = VSS_READ | VSS_WRITE
 247         [description]
 248                 Clear the 'P' (playing) bit of the vss status flags.
 249         [/description]
 250
 251 [subcommand play]
 252         purpose = start or resume playback
 253         aux_info = VSS_READ | VSS_WRITE
 254         [description]
 255                 Set the 'P' (playing) bit of the vss status flags.
 256         [/description]
 257
 258 [subcommand rm]
 259         purpose = remove rows from the audio file table
 260         non-opts-name = pattern...
 261         aux_info = AFS_READ | AFS_WRITE
 262         [description]
 263                 Remove all rows of the audio file table which match any of the given
 264                 patterns. Note that this affects only the database table; the command
 265                 won't touch your audio files on disk.
 266         [/description]
 267         [option verbose]
 268                 short_opt = v
 269                 summary = print paths of deleted rows
 270         [option force]
 271                 short_opt = f
 272                 summary = don't complain if nothing was removed
 273         [option pathname-match]
 274                 short_opt = p
 275                 summary = modify matching behaviour
 276                 [help]
 277                         Match a slash in the path only with a slash in pattern and not by an
 278                         asterisk (*) or a question mark (?) metacharacter, nor by a bracket
 279                         expression ([]) containing a slash (see fnmatch(3)).
 280                 [/help]
 281
 282 [subcommand rmatt]
 283         purpose = remove attribute(s)
 284         non-opts-name = pattern...
 285         aux_info = AFS_READ | AFS_WRITE
 286         [description]
 287                 Remove all attributes which match any given pattern. All information
 288                 about the removed attributes in the audio file table is lost.
 289         [/description]
 290
 291 [subcommand select]
 292         purpose = activate a mood or a playlist
 293         non-opts-name = specifier/name
 294         aux_info = AFS_READ | AFS_WRITE
 295         [description]
 296                 The specifier is either 'm' or 'p' to indicate whether a playlist or
 297                 a mood should be activated. Example:
 298
 299                         select m/foo
 300
 301                 activates the mood named 'foo'.
 302         [/description]
 303
 304 [subcommand sender]
 305         purpose = control paraslash senders
 306         synopsis = [sender cmd [arguments]]
 307         aux_info = VSS_READ | VSS_WRITE
 308         [description]
 309                 Send a command to a specific sender. The following commands are
 310                 available, but not all senders support every command.
 311
 312                        help, on, off, add, delete, allow, deny, status.
 313
 314                 The help command prints the help text of the given sender. If no
 315                 command is given the list of available senders is shown.
 316
 317                 Example:
 318
 319                         para_client sender http help
 320
 321         [/description]
 322
 323 [subcommand setatt]
 324         purpose = set or unset attributes
 325         synopsis = attribute{+|-}... pattern...
 326         aux_info = AFS_READ | AFS_WRITE
 327         [description]
 328                 Set ('+') or unset ('-') the given attributes for all audio files
 329                 matching the given pattern. Example:
 330
 331                         setatt rock+ punk+ pop- '*foo.mp3'
 332
 333                 sets the 'rock' and the 'punk' attribute and unsets the 'pop' attribute
 334                 of all files ending with 'foo.mp3'.
 335         [/description]
 336
 337 [subcommand si]
 338         purpose = print server info
 339         aux_info = NO_PERMISSION_REQUIRED
 340         [description]
 341                 Show server and afs PID, number of connections, uptime and more.
 342         [/description]
 343
 344 [subcommand stat]
 345         purpose = print information about the current audio file
 346         aux_info = VSS_READ
 347         [option num]
 348                 short_opt = n
 349                 summary = number of times to show the status info
 350                 arg_info = required_arg
 351                 arg_type = uint32
 352                 typestr = num
 353                 [help]
 354                         Exit after the status information has been shown num times. If this
 355                         option is not given, the command runs in an endless loop.
 356                 [/help]
 357         [option parser-friendly]
 358                 short_opt = p
 359                 summary = enable parser-friendly output
 360                 [help]
 361                         Show status item identifiers as numerical values and prefix each
 362                         status item with its size in bytes.
 363                 [/help]
 364
 365 [subcommand stop]
 366         purpose = stop playback
 367         aux_info = VSS_READ | VSS_WRITE
 368         [description]
 369                 Clear the 'P' (playing) bit and set the 'N' (next audio file) bit of
 370                 the vss status flags, effectively stopping playback.
 371         [/description]
 372
 373 [subcommand tasks]
 374         purpose = list active server tasks
 375         aux_info = NO_PERMISSION_REQUIRED
 376         [description]
 377                 For each task, print ID, status and name. This is mostly useful
 378                 for debugging.
 379         [/description]
 380
 381 [subcommand term]
 382         purpose = ask the server to terminate
 383         aux_info = VSS_READ | VSS_WRITE
 384         [description]
 385                 Shut down the server. Instead of this command, you can also send
 386                 SIGINT or SIGTERM to the para_server process. It should never be
 387                 necessary to send SIGKILL.
 388         [/description]
 389
 390 [subcommand touch]
 391         purpose = manipulate the afs information of audio files
 392         non-opts-name = pattern...
 393         aux_info = AFS_READ | AFS_WRITE
 394         [description]
 395                 This command modifies the afs info structure of all rows of the audio
 396                 file table whose path matches at least one of the given patters.
 397
 398                 If at least one option is given which takes a number as its argument,
 399                 only those fields of the afs info structure are updated which
 400                 correspond to the given options while all other fields stay unmodified.
 401
 402                 If no such option is given, the lastplayed field is set to the current
 403                 time and the value of the numplayed field is increased by one while
 404                 all other fields are left unchanged. This mimics what happens when
 405                 the virtual streaming system selects the file for streaming.
 406
 407                 If the file is admissible for the current mood (or contained in the
 408                 current playlist), its score is recomputed according to the changed
 409                 values.
 410         [/description]
 411         [option numplayed]
 412                 short_opt = n
 413                 summary = set the numplayed count manually
 414                 arg_type = uint32
 415                 arg_info = required_arg
 416                 typestr = num
 417                 [help]
 418                         The numplayed count of an audio file is the number of times the file
 419                         was selected for streaming. It is one of the inputs to the scoring
 420                         function which determines the order in which admissible files are
 421                         streamed.
 422
 423                         The virtual streaming system increases this number automatically each
 424                         time it opens the file for streaming.
 425                 [/help]
 426         [option lastplayed]
 427                 short_opt = l
 428                 summary = set the lastplayed time manually
 429                 arg_type = uint64
 430                 arg_info = required_arg
 431                 typestr = num
 432                 [help]
 433                         The lastplayed time of an audio file is the time when the file was
 434                         last opened for streaming.
 435
 436                         Like the numplayed count, it is an input for the scoring function
 437                         and is updated automatically by the virtual streaming system.
 438
 439                         The argument must be a number of seconds since the epoch. Example:
 440
 441                                 touch -l=$(date +%s) file
 442
 443                         sets the lastplayed time of 'file' to the current time.
 444                 [/help]
 445         [option image-id]
 446                 short_opt = i
 447                 summary = set the image id
 448                 arg_type = uint32
 449                 arg_info = required_arg
 450                 typestr = num
 451                 [help]
 452                         The afs info structure of each row of the audio file table contains
 453                         a slot for the image id of the audio file that corresponds to the
 454                         row. The image id stored in this slot refers to the key in the image
 455                         table that identifies the blob.
 456
 457                         When a new audio file is added to the audio file table, its image
 458                         id starts out as zero, indicating that there is no image associated
 459                         with the file. Setting the image id to a non-zero number associates
 460                         the file with a particular blob of the image table, for example the
 461                         cover art of the album in jpg format.
 462                 [/help]
 463         [option lyrics-id]
 464                 short_opt = y
 465                 summary = set the lyrics id
 466                 arg_type = uint32
 467                 arg_info = required_arg
 468                 typestr = num
 469                 [help]
 470                         This option works just like --image-id, but sets the lyrics ID rather
 471                         than the image id.
 472                 [/help]
 473         [option amp]
 474                 short_opt = a
 475                 summary = set the amplification value (0-255)
 476                 arg_type = uint32
 477                 arg_info = required_arg
 478                 typestr = num
 479                 [help]
 480                         The amplification value of an audio file is a number which is stored
 481                         in the afs info structure.
 482
 483                         The value determines the scaling factor by which the amplitude of
 484                         the decoded samples should be multiplied in order to normalize the
 485                         volume. A value of zero means no amplification, 64 means the amplitude
 486                         should be multiplied by a factor of two, 128 by three and so on.
 487
 488                         The amp filter of para_audiod amplifies the volume according to
 489                         this value.
 490                 [/help]
 491         [option verbose]
 492                 short_opt = v
 493                 summary = explain what is being done
 494         [option pathname-match]
 495                 short_opt = p
 496                 summary = modify matching behaviour
 497                 [help]
 498                         Match a slash in the path only with a slash in pattern and not by an
 499                         asterisk (*) or a question mark (?) metacharacter, nor by a bracket
 500                         expression ([]) containing a slash (see fnmatch(3)).
 501                 [/help]
 502
 503 [subcommand version]
 504         purpose = print the git version string of para_server
 505         aux_info = NO_PERMISSION_REQUIRED
 506         [option verbose]
 507                 short_opt = v
 508                 summary = print detailed (multi-line) version text
 509
 510 m4_define(`BLOB_COMMANDS', `
 511 [subcommand rm`$2']
 512         purpose = remove `$1' blob(s)
 513         non-opts-name = pattern...
 514         aux_info = AFS_READ | AFS_WRITE
 515         [description]
 516                 Remove all `$1' blobs which match any of the given patterns.
 517         [/description]
 518
 519 [subcommand mv`$2']
 520         purpose = rename `$1' blob(s)
 521         non-opts-name = source dest
 522         aux_info = AFS_READ | AFS_WRITE
 523         [description]
 524                 Rename `$1' source to dest. The command fails if the source `$1'
 525                 does not exist or if the destination `$1' already exists.
 526         [/description]
 527
 528 [subcommand add`$2']
 529         purpose = add a blob to the `$1' table
 530         non-opts-name = `$1'_name
 531         aux_info = AFS_READ | AFS_WRITE
 532         [description]
 533                 Read from stdin and ask the audio file selector to create a blob in
 534                 the `$1' table. If the named blob already exists, it gets replaced
 535                 with the new data.
 536         [/description]
 537
 538 [subcommand cat`$2']
 539         purpose = dump a `$1' blob to stdout
 540         non-opts-name = `$1'_name
 541         aux_info = AFS_READ
 542
 543 [subcommand ls`$2']
 544         purpose = list blobs of type `$1' which match a pattern
 545         non-opts-name = [pattern...]
 546         aux_info = AFS_READ
 547         [description]
 548                 Print the list of all blobs which match the given pattern. If no
 549                 pattern is given, the full list is printed.
 550         [/description]
 551         [option id-sort]
 552                 short_opt = i
 553                 summary = sort by identifier
 554                 [help]
 555                         The default is to sort alphabetically by name.
 556                 [/help]
 557         [option long]
 558                 short_opt = l
 559                 summary = long listing
 560                 [help]
 561                         Print identifier and name. The default is to print only the name.
 562                 [/help]
 563         [option reverse]
 564                 short_opt = r
 565                 summary = reverse sort order
 566 ')
 567
 568 BLOB_COMMANDS(`moods', `mood')
 569 BLOB_COMMANDS(`playlist', `pl')
 570 BLOB_COMMANDS(`image', `img')
 571 BLOB_COMMANDS(`lyrics', `lyr')