server: Convert com_addatt() to lopsub.
[paraslash.git] / 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 lsatt]
182 purpose = list attributes
183 aux_info = AFS_READ
184 [description]
185 Print the list of all defined attributes which match the given
186 pattern. If no pattern is given, the full list is printed.
187 [/description]
188
189 [option id-sort]
190 short_opt = i
191 summary = sort attributes by id
192 [help]
193 The default is to sort alphabetically by name.
194
195 Attributes are internally represented as an 64 bit array. The attribute
196 id is the bit number in this array.
197 [/help]
198 [option long]
199 short_opt = l
200 summary = print long listing
201 [help]
202 The long listing prints the attribute id in addition to the name of
203 the attribute. The id is printed as a decimal number and is separated
204 from the name by a tab character.
205 [/help]
206 [option reverse]
207 short_opt = r
208 summary = reverse sort order
209
210 [subcommand mvatt]
211 purpose = rename an attribute
212 synopsis = source dest
213 aux_info = AFS_READ | AFS_WRITE
214 [description]
215 Rename the attribute given by the first argument to the destination
216 given by the second argument. It is an error if the destination
217 attribute exists.
218 [/description]
219
220 [subcommand next]
221 purpose = close the stream and start to stream the next audio file
222 aux_info = VSS_READ | VSS_WRITE
223 [description]
224 Set the 'N' (next audio file) bit of the vss status flags. This
225 instructs the server to close the current stream, if any. The 'P'
226 (playing) bit is not modified by this command. If it is on, playing
227 continues with the next audio file.
228
229 This command is equivalent to stop if paused, and has no effect
230 if stopped.
231 [/description]
232
233 [subcommand nomore]
234 purpose = stop playing after current audio file
235 aux_info = VSS_READ | VSS_WRITE
236 [description]
237 Set the 'O' (no more) bit of the vss status flags which asks
238 para_server to clear the 'P' (playing) bit after the 'N' (next audio
239 file) bit transitions from off to on (because the end of the current
240 audio file is reached). Use this command instead of stop if you don't
241 like sudden endings.
242 [/description]
243
244 [subcommand pause]
245 purpose = suspend the current stream
246 aux_info = VSS_READ | VSS_WRITE
247 [description]
248 Clear the 'P' (playing) bit of the vss status flags.
249 [/description]
250
251 [subcommand play]
252 purpose = start or resume playback
253 aux_info = VSS_READ | VSS_WRITE
254 [description]
255 Set the 'P' (playing) bit of the vss status flags.
256 [/description]
257
258 [subcommand rm]
259 purpose = remove rows from the audio file table
260 non-opts-name = pattern...
261 aux_info = AFS_READ | AFS_WRITE
262 [description]
263 Remove all rows of the audio file table which match any of the given
264 patterns. Note that this affects only the database table; the command
265 won't touch your audio files on disk.
266 [/description]
267 [option verbose]
268 short_opt = v
269 summary = print paths of deleted rows
270 [option force]
271 short_opt = f
272 summary = don't complain if nothing was removed
273 [option pathname-match]
274 short_opt = p
275 summary = modify matching behaviour
276 [help]
277 Match a slash in the path only with a slash in pattern and not by an
278 asterisk (*) or a question mark (?) metacharacter, nor by a bracket
279 expression ([]) containing a slash (see fnmatch(3)).
280 [/help]
281
282 [subcommand rmatt]
283 purpose = remove attribute(s)
284 non-opts-name = pattern...
285 aux_info = AFS_READ | AFS_WRITE
286 [description]
287 Remove all attributes which match any given pattern. All information
288 about the removed attributes in the audio file table is lost.
289 [/description]
290
291 [subcommand select]
292 purpose = activate a mood or a playlist
293 non-opts-name = specifier/name
294 aux_info = AFS_READ | AFS_WRITE
295 [description]
296 The specifier is either 'm' or 'p' to indicate whether a playlist or
297 a mood should be activated. Example:
298
299 select m/foo
300
301 activates the mood named 'foo'.
302 [/description]
303
304 [subcommand sender]
305 purpose = control paraslash senders
306 synopsis = [sender cmd [arguments]]
307 aux_info = VSS_READ | VSS_WRITE
308 [description]
309 Send a command to a specific sender. The following commands are
310 available, but not all senders support every command.
311
312 help, on, off, add, delete, allow, deny, status.
313
314 The help command prints the help text of the given sender. If no
315 command is given the list of available senders is shown.
316
317 Example:
318
319 para_client sender http help
320
321 [/description]
322
323 [subcommand setatt]
324 purpose = set or unset attributes
325 synopsis = attribute{+|-}... pattern...
326 aux_info = AFS_READ | AFS_WRITE
327 [description]
328 Set ('+') or unset ('-') the given attributes for all audio files
329 matching the given pattern. Example:
330
331 setatt rock+ punk+ pop- '*foo.mp3'
332
333 sets the 'rock' and the 'punk' attribute and unsets the 'pop' attribute
334 of all files ending with 'foo.mp3'.
335 [/description]
336
337 [subcommand si]
338 purpose = print server info
339 aux_info = NO_PERMISSION_REQUIRED
340 [description]
341 Show server and afs PID, number of connections, uptime and more.
342 [/description]
343
344 [subcommand stat]
345 purpose = print information about the current audio file
346 aux_info = VSS_READ
347 [option num]
348 short_opt = n
349 summary = number of times to show the status info
350 arg_info = required_arg
351 arg_type = uint32
352 typestr = num
353 [help]
354 Exit after the status information has been shown num times. If this
355 option is not given, the command runs in an endless loop.
356 [/help]
357 [option parser-friendly]
358 short_opt = p
359 summary = enable parser-friendly output
360 [help]
361 Show status item identifiers as numerical values and prefix each
362 status item with its size in bytes.
363 [/help]
364
365 [subcommand stop]
366 purpose = stop playback
367 aux_info = VSS_READ | VSS_WRITE
368 [description]
369 Clear the 'P' (playing) bit and set the 'N' (next audio file) bit of
370 the vss status flags, effectively stopping playback.
371 [/description]
372
373 [subcommand tasks]
374 purpose = list active server tasks
375 aux_info = NO_PERMISSION_REQUIRED
376 [description]
377 For each task, print ID, status and name. This is mostly useful
378 for debugging.
379 [/description]
380
381 [subcommand term]
382 purpose = ask the server to terminate
383 aux_info = VSS_READ | VSS_WRITE
384 [description]
385 Shut down the server. Instead of this command, you can also send
386 SIGINT or SIGTERM to the para_server process. It should never be
387 necessary to send SIGKILL.
388 [/description]
389
390 [subcommand touch]
391 purpose = manipulate the afs information of audio files
392 non-opts-name = pattern...
393 aux_info = AFS_READ | AFS_WRITE
394 [description]
395 This command modifies the afs info structure of all rows of the audio
396 file table whose path matches at least one of the given patters.
397
398 If at least one option is given which takes a number as its argument,
399 only those fields of the afs info structure are updated which
400 correspond to the given options while all other fields stay unmodified.
401
402 If no such option is given, the lastplayed field is set to the current
403 time and the value of the numplayed field is increased by one while
404 all other fields are left unchanged. This mimics what happens when
405 the virtual streaming system selects the file for streaming.
406
407 If the file is admissible for the current mood (or contained in the
408 current playlist), its score is recomputed according to the changed
409 values.
410 [/description]
411 [option numplayed]
412 short_opt = n
413 summary = set the numplayed count manually
414 arg_type = uint32
415 arg_info = required_arg
416 typestr = num
417 [help]
418 The numplayed count of an audio file is the number of times the file
419 was selected for streaming. It is one of the inputs to the scoring
420 function which determines the order in which admissible files are
421 streamed.
422
423 The virtual streaming system increases this number automatically each
424 time it opens the file for streaming.
425 [/help]
426 [option lastplayed]
427 short_opt = l
428 summary = set the lastplayed time manually
429 arg_type = uint64
430 arg_info = required_arg
431 typestr = num
432 [help]
433 The lastplayed time of an audio file is the time when the file was
434 last opened for streaming.
435
436 Like the numplayed count, it is an input for the scoring function
437 and is updated automatically by the virtual streaming system.
438
439 The argument must be a number of seconds since the epoch. Example:
440
441 touch -l=$(date +%s) file
442
443 sets the lastplayed time of 'file' to the current time.
444 [/help]
445 [option image-id]
446 short_opt = i
447 summary = set the image id
448 arg_type = uint32
449 arg_info = required_arg
450 typestr = num
451 [help]
452 The afs info structure of each row of the audio file table contains
453 a slot for the image id of the audio file that corresponds to the
454 row. The image id stored in this slot refers to the key in the image
455 table that identifies the blob.
456
457 When a new audio file is added to the audio file table, its image
458 id starts out as zero, indicating that there is no image associated
459 with the file. Setting the image id to a non-zero number associates
460 the file with a particular blob of the image table, for example the
461 cover art of the album in jpg format.
462 [/help]
463 [option lyrics-id]
464 short_opt = y
465 summary = set the lyrics id
466 arg_type = uint32
467 arg_info = required_arg
468 typestr = num
469 [help]
470 This option works just like --image-id, but sets the lyrics ID rather
471 than the image id.
472 [/help]
473 [option amp]
474 short_opt = a
475 summary = set the amplification value (0-255)
476 arg_type = uint32
477 arg_info = required_arg
478 typestr = num
479 [help]
480 The amplification value of an audio file is a number which is stored
481 in the afs info structure.
482
483 The value determines the scaling factor by which the amplitude of
484 the decoded samples should be multiplied in order to normalize the
485 volume. A value of zero means no amplification, 64 means the amplitude
486 should be multiplied by a factor of two, 128 by three and so on.
487
488 The amp filter of para_audiod amplifies the volume according to
489 this value.
490 [/help]
491 [option verbose]
492 short_opt = v
493 summary = explain what is being done
494 [option pathname-match]
495 short_opt = p
496 summary = modify matching behaviour
497 [help]
498 Match a slash in the path only with a slash in pattern and not by an
499 asterisk (*) or a question mark (?) metacharacter, nor by a bracket
500 expression ([]) containing a slash (see fnmatch(3)).
501 [/help]
502
503 [subcommand version]
504 purpose = print the git version string of para_server
505 aux_info = NO_PERMISSION_REQUIRED
506 [option verbose]
507 short_opt = v
508 summary = print detailed (multi-line) version text
509