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 ls]
 182         purpose = list audio files which match a pattern
 183         non-opts-name = [pattern...]
 184         aux_info = AFS_READ
 185         [description]
 186                 If no pattern is given, all files are listed.  Otherwise, the command
 187                 lists all files of the audio file table whose path matches at least
 188                 one of the given patterns.
 189         [/description]
 190         [option listing-mode]
 191                 short_opt = l
 192                 summary = use alternative output format
 193                 arg_type = string
 194                 arg_info = optional_arg
 195                 typestr = mode
 196                 default_val = long
 197                 [help]
 198                         The optional mode argument is either a single character or a word
 199                         according to the following list.
 200
 201                         short (s). List only the path or basename (last component of the path),
 202                         depending on whether -p is also given. This listing mode acts as if
 203                         --listing-mode had not been given.
 204
 205                         long (l). Show detailed information. This is the default if no argument
 206                         to --listing-mode is supplied.
 207
 208                         verbose (v). Multi-line output, one row per data field stored in the
 209                         audio file table.
 210
 211                         parser-friendly (p). Like verbose listing mode, but use numerical
 212                         values for the names of the output fields and prefix each line with
 213                         a length field.
 214
 215                         mbox (m). Generate output suitable to be viewed with a mail
 216                         program. One "mail" per matching audio file.
 217
 218                         chunk-table (c). Print path (or basename, depending on whether -p is
 219                         also given), chunk time and chunk offsets.
 220
 221                 [/help]
 222         [option full-path]
 223                 short_opt = F
 224                 summary = list full paths, match full paths against patterns
 225                 [help]
 226                         This option is the default, so it does nothing. Deprecated as of
 227                         v0.6.0, scheduled for removal in v0.6.1.
 228                 [/help]
 229         [option basename]
 230                 short_opt = b
 231                 summary = list and match basenames only
 232                 [help]
 233                         Print only the basename of each matching file and match only the
 234                         basenames of the paths stored in the audio file table against the
 235                         given patterns. The default is to print and match the full path.
 236                 [/help]
 237         [option admissible]
 238                 short_opt = a
 239                 summary = list only admissible files
 240                 [help]
 241                         List only files which are admissible with respect to the current mood
 242                         or playlist.
 243                 [/help]
 244         [option reverse]
 245                 short_opt = r
 246                 summary = reverse sort order
 247         [option unix-date]
 248                 short_opt = d
 249                 summary = print dates as seconds after the epoch
 250         [option sort]
 251                 short_opt = s
 252                 summary = change sort order
 253                 arg_type = string
 254                 arg_info = required_arg
 255                 typestr = order
 256                 default_val = path
 257                 [help]
 258                         The sort order must be given as an required argument. Like for
 259                         --listing-mode, this argument may either be a single character or a
 260                         word, according to the following list.
 261
 262                         path (p). Sort alphabetically by path or basename, depending on
 263                         whether -b is given. This is the default if --sort is not given.
 264
 265                         score (s). Iterate over the entries of the score table, rather than
 266                         the audio file table. This sort order implies --admissible, since
 267                         the score table contains only admissible files.
 268
 269                         lastplayed (l)
 270
 271                         numplayed (n)
 272
 273                         frequency (f)
 274
 275                         channels (c)
 276
 277                         image-id (i)
 278
 279                         lyrics-id (y)
 280
 281                         bitrate (b)
 282
 283                         duration (d)
 284
 285                         audio-format (a)
 286
 287                         hash (h)
 288
 289                         If --sort is not given, path sort is implied.
 290                 [/help]
 291
 292 [subcommand lsatt]
 293         purpose = list attributes
 294         aux_info = AFS_READ
 295         [description]
 296                 Print the list of all defined attributes which match the given
 297                 pattern. If no pattern is given, the full list is printed.
 298         [/description]
 299
 300         [option id-sort]
 301                 short_opt = i
 302                 summary = sort attributes by id
 303                 [help]
 304                         The default is to sort alphabetically by name.
 305
 306                         Attributes are internally represented as an 64 bit array. The attribute
 307                         id is the bit number in this array.
 308                 [/help]
 309         [option long]
 310                 short_opt = l
 311                 summary = print long listing
 312                 [help]
 313                         The long listing prints the attribute id in addition to the name of
 314                         the attribute. The id is printed as a decimal number and is separated
 315                         from the name by a tab character.
 316                 [/help]
 317         [option reverse]
 318                 short_opt = r
 319                 summary = reverse sort order
 320
 321 [subcommand mvatt]
 322         purpose = rename an attribute
 323         synopsis = source dest
 324         aux_info = AFS_READ | AFS_WRITE
 325         [description]
 326                 Rename the attribute given by the first argument to the destination
 327                 given by the second argument. It is an error if the destination
 328                 attribute exists.
 329         [/description]
 330
 331 [subcommand next]
 332         purpose = close the stream and start to stream the next audio file
 333         aux_info = VSS_READ | VSS_WRITE
 334         [description]
 335                 Set the 'N' (next audio file) bit of the vss status flags. This
 336                 instructs the server to close the current stream, if any. The 'P'
 337                 (playing) bit is not modified by this command. If it is on, playing
 338                 continues with the next audio file.
 339
 340                 This command is equivalent to stop if paused, and has no effect
 341                 if stopped.
 342         [/description]
 343
 344 [subcommand nomore]
 345         purpose = stop playing after current audio file
 346         aux_info = VSS_READ | VSS_WRITE
 347         [description]
 348                 Set the 'O' (no more) bit of the vss status flags which asks
 349                 para_server to clear the 'P' (playing) bit after the 'N' (next audio
 350                 file) bit transitions from off to on (because the end of the current
 351                 audio file is reached). Use this command instead of stop if you don't
 352                 like sudden endings.
 353         [/description]
 354
 355 [subcommand pause]
 356         purpose = suspend the current stream
 357         aux_info = VSS_READ | VSS_WRITE
 358         [description]
 359                 Clear the 'P' (playing) bit of the vss status flags.
 360         [/description]
 361
 362 [subcommand play]
 363         purpose = start or resume playback
 364         aux_info = VSS_READ | VSS_WRITE
 365         [description]
 366                 Set the 'P' (playing) bit of the vss status flags.
 367         [/description]
 368
 369 [subcommand rm]
 370         purpose = remove rows from the audio file table
 371         non-opts-name = pattern...
 372         aux_info = AFS_READ | AFS_WRITE
 373         [description]
 374                 Remove all rows of the audio file table which match any of the given
 375                 patterns. Note that this affects only the database table; the command
 376                 won't touch your audio files on disk.
 377         [/description]
 378         [option verbose]
 379                 short_opt = v
 380                 summary = print paths of deleted rows
 381         [option force]
 382                 short_opt = f
 383                 summary = don't complain if nothing was removed
 384         [option pathname-match]
 385                 short_opt = p
 386                 summary = modify matching behaviour
 387                 [help]
 388                         Match a slash in the path only with a slash in pattern and not by an
 389                         asterisk (*) or a question mark (?) metacharacter, nor by a bracket
 390                         expression ([]) containing a slash (see fnmatch(3)).
 391                 [/help]
 392
 393 [subcommand rmatt]
 394         purpose = remove attribute(s)
 395         non-opts-name = pattern...
 396         aux_info = AFS_READ | AFS_WRITE
 397         [description]
 398                 Remove all attributes which match any given pattern. All information
 399                 about the removed attributes in the audio file table is lost.
 400         [/description]
 401
 402 [subcommand select]
 403         purpose = activate a mood or a playlist
 404         non-opts-name = specifier/name
 405         aux_info = AFS_READ | AFS_WRITE
 406         [description]
 407                 The specifier is either 'm' or 'p' to indicate whether a playlist or
 408                 a mood should be activated. Example:
 409
 410                         select m/foo
 411
 412                 activates the mood named 'foo'.
 413         [/description]
 414
 415 [subcommand sender]
 416         purpose = control paraslash senders
 417         synopsis = [sender cmd [arguments]]
 418         aux_info = VSS_READ | VSS_WRITE
 419         [description]
 420                 Send a command to a specific sender. The following commands are
 421                 available, but not all senders support every command.
 422
 423                        help, on, off, add, delete, allow, deny, status.
 424
 425                 The help command prints the help text of the given sender. If no
 426                 command is given the list of available senders is shown.
 427
 428                 Example:
 429
 430                         para_client sender http help
 431
 432         [/description]
 433
 434 [subcommand setatt]
 435         purpose = set or unset attributes
 436         synopsis = attribute{+|-}... pattern...
 437         aux_info = AFS_READ | AFS_WRITE
 438         [description]
 439                 Set ('+') or unset ('-') the given attributes for all audio files
 440                 matching the given pattern. Example:
 441
 442                         setatt rock+ punk+ pop- '*foo.mp3'
 443
 444                 sets the 'rock' and the 'punk' attribute and unsets the 'pop' attribute
 445                 of all files ending with 'foo.mp3'.
 446         [/description]
 447
 448 [subcommand si]
 449         purpose = print server info
 450         aux_info = NO_PERMISSION_REQUIRED
 451         [description]
 452                 Show server and afs PID, number of connections, uptime and more.
 453         [/description]
 454
 455 [subcommand stat]
 456         purpose = print information about the current audio file
 457         aux_info = VSS_READ
 458         [option num]
 459                 short_opt = n
 460                 summary = number of times to show the status info
 461                 arg_info = required_arg
 462                 arg_type = uint32
 463                 typestr = num
 464                 [help]
 465                         Exit after the status information has been shown num times. If this
 466                         option is not given, the command runs in an endless loop.
 467                 [/help]
 468         [option parser-friendly]
 469                 short_opt = p
 470                 summary = enable parser-friendly output
 471                 [help]
 472                         Show status item identifiers as numerical values and prefix each
 473                         status item with its size in bytes.
 474                 [/help]
 475
 476 [subcommand stop]
 477         purpose = stop playback
 478         aux_info = VSS_READ | VSS_WRITE
 479         [description]
 480                 Clear the 'P' (playing) bit and set the 'N' (next audio file) bit of
 481                 the vss status flags, effectively stopping playback.
 482         [/description]
 483
 484 [subcommand tasks]
 485         purpose = list active server tasks
 486         aux_info = NO_PERMISSION_REQUIRED
 487         [description]
 488                 For each task, print ID, status and name. This is mostly useful
 489                 for debugging.
 490         [/description]
 491
 492 [subcommand term]
 493         purpose = ask the server to terminate
 494         aux_info = VSS_READ | VSS_WRITE
 495         [description]
 496                 Shut down the server. Instead of this command, you can also send
 497                 SIGINT or SIGTERM to the para_server process. It should never be
 498                 necessary to send SIGKILL.
 499         [/description]
 500
 501 [subcommand touch]
 502         purpose = manipulate the afs information of audio files
 503         non-opts-name = pattern...
 504         aux_info = AFS_READ | AFS_WRITE
 505         [description]
 506                 This command modifies the afs info structure of all rows of the audio
 507                 file table whose path matches at least one of the given patters.
 508
 509                 If at least one option is given which takes a number as its argument,
 510                 only those fields of the afs info structure are updated which
 511                 correspond to the given options while all other fields stay unmodified.
 512
 513                 If no such option is given, the lastplayed field is set to the current
 514                 time and the value of the numplayed field is increased by one while
 515                 all other fields are left unchanged. This mimics what happens when
 516                 the virtual streaming system selects the file for streaming.
 517
 518                 If the file is admissible for the current mood (or contained in the
 519                 current playlist), its score is recomputed according to the changed
 520                 values.
 521         [/description]
 522         [option numplayed]
 523                 short_opt = n
 524                 summary = set the numplayed count manually
 525                 arg_type = uint32
 526                 arg_info = required_arg
 527                 typestr = num
 528                 [help]
 529                         The numplayed count of an audio file is the number of times the file
 530                         was selected for streaming. It is one of the inputs to the scoring
 531                         function which determines the order in which admissible files are
 532                         streamed.
 533
 534                         The virtual streaming system increases this number automatically each
 535                         time it opens the file for streaming.
 536                 [/help]
 537         [option lastplayed]
 538                 short_opt = l
 539                 summary = set the lastplayed time manually
 540                 arg_type = uint64
 541                 arg_info = required_arg
 542                 typestr = num
 543                 [help]
 544                         The lastplayed time of an audio file is the time when the file was
 545                         last opened for streaming.
 546
 547                         Like the numplayed count, it is an input for the scoring function
 548                         and is updated automatically by the virtual streaming system.
 549
 550                         The argument must be a number of seconds since the epoch. Example:
 551
 552                                 touch -l=$(date +%s) file
 553
 554                         sets the lastplayed time of 'file' to the current time.
 555                 [/help]
 556         [option image-id]
 557                 short_opt = i
 558                 summary = set the image id
 559                 arg_type = uint32
 560                 arg_info = required_arg
 561                 typestr = num
 562                 [help]
 563                         The afs info structure of each row of the audio file table contains
 564                         a slot for the image id of the audio file that corresponds to the
 565                         row. The image id stored in this slot refers to the key in the image
 566                         table that identifies the blob.
 567
 568                         When a new audio file is added to the audio file table, its image
 569                         id starts out as zero, indicating that there is no image associated
 570                         with the file. Setting the image id to a non-zero number associates
 571                         the file with a particular blob of the image table, for example the
 572                         cover art of the album in jpg format.
 573                 [/help]
 574         [option lyrics-id]
 575                 short_opt = y
 576                 summary = set the lyrics id
 577                 arg_type = uint32
 578                 arg_info = required_arg
 579                 typestr = num
 580                 [help]
 581                         This option works just like --image-id, but sets the lyrics ID rather
 582                         than the image id.
 583                 [/help]
 584         [option amp]
 585                 short_opt = a
 586                 summary = set the amplification value (0-255)
 587                 arg_type = uint32
 588                 arg_info = required_arg
 589                 typestr = num
 590                 [help]
 591                         The amplification value of an audio file is a number which is stored
 592                         in the afs info structure.
 593
 594                         The value determines the scaling factor by which the amplitude of
 595                         the decoded samples should be multiplied in order to normalize the
 596                         volume. A value of zero means no amplification, 64 means the amplitude
 597                         should be multiplied by a factor of two, 128 by three and so on.
 598
 599                         The amp filter of para_audiod amplifies the volume according to
 600                         this value.
 601                 [/help]
 602         [option verbose]
 603                 short_opt = v
 604                 summary = explain what is being done
 605         [option pathname-match]
 606                 short_opt = p
 607                 summary = modify matching behaviour
 608                 [help]
 609                         Match a slash in the path only with a slash in pattern and not by an
 610                         asterisk (*) or a question mark (?) metacharacter, nor by a bracket
 611                         expression ([]) containing a slash (see fnmatch(3)).
 612                 [/help]
 613
 614 [subcommand version]
 615         purpose = print the git version string of para_server
 616         aux_info = NO_PERMISSION_REQUIRED
 617         [option verbose]
 618                 short_opt = v
 619                 summary = print detailed (multi-line) version text
 620
 621 m4_define(`BLOB_COMMANDS', `
 622 [subcommand rm`$2']
 623         purpose = remove `$1' blob(s)
 624         non-opts-name = pattern...
 625         aux_info = AFS_READ | AFS_WRITE
 626         [description]
 627                 Remove all `$1' blobs which match any of the given patterns.
 628         [/description]
 629
 630 [subcommand mv`$2']
 631         purpose = rename `$1' blob(s)
 632         non-opts-name = source dest
 633         aux_info = AFS_READ | AFS_WRITE
 634         [description]
 635                 Rename `$1' source to dest. The command fails if the source `$1'
 636                 does not exist or if the destination `$1' already exists.
 637         [/description]
 638
 639 [subcommand add`$2']
 640         purpose = add a blob to the `$1' table
 641         non-opts-name = `$1'_name
 642         aux_info = AFS_READ | AFS_WRITE
 643         [description]
 644                 Read from stdin and ask the audio file selector to create a blob in
 645                 the `$1' table. If the named blob already exists, it gets replaced
 646                 with the new data.
 647         [/description]
 648
 649 [subcommand cat`$2']
 650         purpose = dump a `$1' blob to stdout
 651         non-opts-name = `$1'_name
 652         aux_info = AFS_READ
 653
 654 [subcommand ls`$2']
 655         purpose = list blobs of type `$1' which match a pattern
 656         non-opts-name = [pattern...]
 657         aux_info = AFS_READ
 658         [description]
 659                 Print the list of all blobs which match the given pattern. If no
 660                 pattern is given, the full list is printed.
 661         [/description]
 662         [option id-sort]
 663                 short_opt = i
 664                 summary = sort by identifier
 665                 [help]
 666                         The default is to sort alphabetically by name.
 667                 [/help]
 668         [option long]
 669                 short_opt = l
 670                 summary = long listing
 671                 [help]
 672                         Print identifier and name. The default is to print only the name.
 673                 [/help]
 674         [option reverse]
 675                 short_opt = r
 676                 summary = reverse sort order
 677 ')
 678
 679 BLOB_COMMANDS(`moods', `mood')
 680 BLOB_COMMANDS(`playlist', `pl')
 681 BLOB_COMMANDS(`image', `img')
 682 BLOB_COMMANDS(`lyrics', `lyr')