server: Convert com_setatt() 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 ff]
56 purpose = jump N seconds forward or backward
57 synopsis = n[-]
58 aux_info = VSS_READ | VSS_WRITE
59 [description]
60 This sets the 'R' (reposition request) bit of the vss status flags
61 which enqueues a request to jump n seconds forwards or backwards.
62
63 Example:
64
65 para_client ff 30-
66
67 jumps 30 seconds backwards.
68
69 [/description]
70
71 [subcommand help]
72 purpose = list available commands or print command-specific help
73 non-opts-name = [command]
74 aux_info = NO_PERMISSION_REQUIRED
75 [description]
76 Without any arguments, help prints a list of available commands. When
77 called with a command name as first argument, it prints the description
78 of this command.
79 [/description]
80
81 [subcommand hup]
82 purpose = reload config file, log file and user list
83 aux_info = VSS_WRITE
84 [description]
85 Reread the config file and the user list file, close and reopen the log
86 file, and ask the afs process to do the same. Sending the HUP signal
87 to the server process has the same effect as running this command.
88 [/description]
89
90 [subcommand init]
91 purpose = initialize the database tables for the audio file selector
92 synopsis = [table_name...]
93 aux_info = AFS_READ | AFS_WRITE
94 [description]
95 When invoked without arguments, this command creates all
96 tables: audio_files, attributes, scores, moods, lyrics, images,
97 playlists. Otherwise only the given tables are created.
98 [/description]
99
100 [subcommand jmp]
101 purpose = reposition the current stream
102 non-opts-name = n
103 aux_info = VSS_READ | VSS_WRITE
104 [description]
105 Set the 'R' (reposition request) bit of the vss status flags and
106 enqueue a request to jump to n% of the current audio file, where 0 <=
107 n <= 100.
108 [/description]
109
110 [subcommand lsatt]
111 purpose = list attributes
112 aux_info = AFS_READ
113 [description]
114 Print the list of all defined attributes which match the given
115 pattern. If no pattern is given, the full list is printed.
116 [/description]
117
118 [option id-sort]
119 short_opt = i
120 summary = sort attributes by id
121 [help]
122 The default is to sort alphabetically by name.
123
124 Attributes are internally represented as an 64 bit array. The attribute
125 id is the bit number in this array.
126 [/help]
127 [option long]
128 short_opt = l
129 summary = print long listing
130 [help]
131 The long listing prints the attribute id in addition to the name of
132 the attribute. The id is printed as a decimal number and is separated
133 from the name by a tab character.
134 [/help]
135 [option reverse]
136 short_opt = r
137 summary = reverse sort order
138
139 [subcommand next]
140 purpose = close the stream and start to stream the next audio file
141 aux_info = VSS_READ | VSS_WRITE
142 [description]
143 Set the 'N' (next audio file) bit of the vss status flags. This
144 instructs the server to close the current stream, if any. The 'P'
145 (playing) bit is not modified by this command. If it is on, playing
146 continues with the next audio file.
147
148 This command is equivalent to stop if paused, and has no effect
149 if stopped.
150 [/description]
151
152 [subcommand nomore]
153 purpose = stop playing after current audio file
154 aux_info = VSS_READ | VSS_WRITE
155 [description]
156 Set the 'O' (no more) bit of the vss status flags which asks
157 para_server to clear the 'P' (playing) bit after the 'N' (next audio
158 file) bit transitions from off to on (because the end of the current
159 audio file is reached). Use this command instead of stop if you don't
160 like sudden endings.
161 [/description]
162
163 [subcommand pause]
164 purpose = suspend the current stream
165 aux_info = VSS_READ | VSS_WRITE
166 [description]
167 Clear the 'P' (playing) bit of the vss status flags.
168 [/description]
169
170 [subcommand play]
171 purpose = start or resume playback
172 aux_info = VSS_READ | VSS_WRITE
173 [description]
174 Set the 'P' (playing) bit of the vss status flags.
175 [/description]
176
177 [subcommand sender]
178 purpose = control paraslash senders
179 synopsis = [sender cmd [arguments]]
180 aux_info = VSS_READ | VSS_WRITE
181 [description]
182 Send a command to a specific sender. The following commands are
183 available, but not all senders support every command.
184
185 help, on, off, add, delete, allow, deny, status.
186
187 The help command prints the help text of the given sender. If no
188 command is given the list of available senders is shown.
189
190 Example:
191
192 para_client sender http help
193
194 [/description]
195
196 [subcommand setatt]
197 purpose = set or unset attributes
198 synopsis = attribute{+|-}... pattern...
199 aux_info = AFS_READ | AFS_WRITE
200 [description]
201 Set ('+') or unset ('-') the given attributes for all audio files
202 matching the given pattern. Example:
203
204 setatt rock+ punk+ pop- '*foo.mp3'
205
206 sets the 'rock' and the 'punk' attribute and unsets the 'pop' attribute
207 of all files ending with 'foo.mp3'.
208 [/description]
209
210 [subcommand si]
211 purpose = print server info
212 aux_info = NO_PERMISSION_REQUIRED
213 [description]
214 Show server and afs PID, number of connections, uptime and more.
215 [/description]
216
217 [subcommand stat]
218 purpose = print information about the current audio file
219 aux_info = VSS_READ
220 [option num]
221 short_opt = n
222 summary = number of times to show the status info
223 arg_info = required_arg
224 arg_type = uint32
225 typestr = num
226 [help]
227 Exit after the status information has been shown num times. If this
228 option is not given, the command runs in an endless loop.
229 [/help]
230 [option parser-friendly]
231 short_opt = p
232 summary = enable parser-friendly output
233 [help]
234 Show status item identifiers as numerical values and prefix each
235 status item with its size in bytes.
236 [/help]
237
238 [subcommand stop]
239 purpose = stop playback
240 aux_info = VSS_READ | VSS_WRITE
241 [description]
242 Clear the 'P' (playing) bit and set the 'N' (next audio file) bit of
243 the vss status flags, effectively stopping playback.
244 [/description]
245
246 [subcommand tasks]
247 purpose = list active server tasks
248 aux_info = NO_PERMISSION_REQUIRED
249 [description]
250 For each task, print ID, status and name. This is mostly useful
251 for debugging.
252 [/description]
253
254 [subcommand term]
255 purpose = ask the server to terminate
256 aux_info = VSS_READ | VSS_WRITE
257 [description]
258 Shut down the server. Instead of this command, you can also send
259 SIGINT or SIGTERM to the para_server process. It should never be
260 necessary to send SIGKILL.
261 [/description]
262
263 [subcommand version]
264 purpose = print the git version string of para_server
265 aux_info = NO_PERMISSION_REQUIRED
266 [option verbose]
267 short_opt = v
268 summary = print detailed (multi-line) version text
269