+[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]
+