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