server: Convert com_touch() to lopsub.

[paraslash.git] / m4 / lls / server_cmd.suite.m4

diff --git a/m4/lls/server_cmd.suite.m4 b/m4/lls/server_cmd.suite.m4
index eda1ba6123178310bf6ac688df8b6bf05f491034..2ddc53dcba134073fab6081c9365d608c3dc2856 100644 (file)
--- a/m4/lls/server_cmd.suite.m4
+++ b/m4/lls/server_cmd.suite.m4
@@ -378,6 +378,119 @@ aux_info_prefix = Permissions:
                necessary to send SIGKILL.
        [/description]
 
+[subcommand touch]
+       purpose = manipulate the afs information of audio files
+       non-opts-name = pattern...
+       aux_info = AFS_READ | AFS_WRITE
+       [description]
+               This command modifies the afs info structure of all rows of the audio
+               file table whose path matches at least one of the given patters.
+
+               If at least one option is given which takes a number as its argument,
+               only those fields of the afs info structure are updated which
+               correspond to the given options while all other fields stay unmodified.
+
+               If no such option is given, the lastplayed field is set to the current
+               time and the value of the numplayed field is increased by one while
+               all other fields are left unchanged. This mimics what happens when
+               the virtual streaming system selects the file for streaming.
+
+               If the file is admissible for the current mood (or contained in the
+               current playlist), its score is recomputed according to the changed
+               values.
+       [/description]
+       [option numplayed]
+               short_opt = n
+               summary = set the numplayed count manually
+               arg_type = uint32
+               arg_info = required_arg
+               typestr = num
+               [help]
+                       The numplayed count of an audio file is the number of times the file
+                       was selected for streaming. It is one of the inputs to the scoring
+                       function which determines the order in which admissible files are
+                       streamed.
+
+                       The virtual streaming system increases this number automatically each
+                       time it opens the file for streaming.
+               [/help]
+       [option lastplayed]
+               short_opt = l
+               summary = set the lastplayed time manually
+               arg_type = uint64
+               arg_info = required_arg
+               typestr = num
+               [help]
+                       The lastplayed time of an audio file is the time when the file was
+                       last opened for streaming.
+
+                       Like the numplayed count, it is an input for the scoring function
+                       and is updated automatically by the virtual streaming system.
+
+                       The argument must be a number of seconds since the epoch. Example:
+
+                               touch -l=$(date +%s) file
+
+                       sets the lastplayed time of 'file' to the current time.
+               [/help]
+       [option image-id]
+               short_opt = i
+               summary = set the image id
+               arg_type = uint32
+               arg_info = required_arg
+               typestr = num
+               [help]
+                       The afs info structure of each row of the audio file table contains
+                       a slot for the image id of the audio file that corresponds to the
+                       row. The image id stored in this slot refers to the key in the image
+                       table that identifies the blob.
+
+                       When a new audio file is added to the audio file table, its image
+                       id starts out as zero, indicating that there is no image associated
+                       with the file. Setting the image id to a non-zero number associates
+                       the file with a particular blob of the image table, for example the
+                       cover art of the album in jpg format.
+               [/help]
+       [option lyrics-id]
+               short_opt = y
+               summary = set the lyrics id
+               arg_type = uint32
+               arg_info = required_arg
+               typestr = num
+               [help]
+                       This option works just like --image-id, but sets the lyrics ID rather
+                       than the image id.
+               [/help]
+       [option amp]
+               short_opt = a
+               summary = set the amplification value (0-255)
+               arg_type = uint32
+               arg_info = required_arg
+               typestr = num
+               [help]
+                       The amplification value of an audio file is a number which is stored
+                       in the afs info structure.
+
+                       The value determines the scaling factor by which the amplitude of
+                       the decoded samples should be multiplied in order to normalize the
+                       volume. A value of zero means no amplification, 64 means the amplitude
+                       should be multiplied by a factor of two, 128 by three and so on.
+
+                       The amp filter of para_audiod amplifies the volume according to
+                       this value.
+               [/help]
+       [option verbose]
+               short_opt = v
+               summary = explain what is being done
+       [option pathname-match]
+               short_opt = p
+               summary = modify matching behaviour
+               [help]
+                       Match a slash in the path only with a slash in pattern and not by an
+                       asterisk (*) or a question mark (?) metacharacter, nor by a bracket
+                       expression ([]) containing a slash (see fnmatch(3)).
+               [/help]
+
 [subcommand version]
        purpose = print the git version string of para_server
        aux_info = NO_PERMISSION_REQUIRED