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