1 m4_define(PROGRAM, para_server)
2 m4_define(DEFAULT_CONFIG_FILE, ~/.paraslash/server.conf)
4 version-string = GIT_VERSION()
5 [supercommand para_server]
6 purpose = manage and stream audio files
8 para_server streams audio files over a local or remote network. It
9 is controlled by para_client(1), which connects para_server through
10 the paraslash control service.
12 On startup the server spawns a second process, the audio file selector,
13 which maintains the database of all known audio files. This database
14 contains file format, duration and tag information of each known file
15 and statistics such as last-played time, and the number of times each
16 file was streamed. Lyrics and cover art may be added to the database
17 and associated with one or more audio files.
19 Besides ordinary playlists the audio file selector supports so-called
20 moods. Moods instruct the server to determine the files to be streamed
21 and their order in terms of properties stored in the database.
23 m4_include(common-option-section.m4)
25 m4_include(detailed-help.m4)
26 m4_include(version.m4)
27 m4_include(config-file.m4)
28 m4_include(priority.m4)
30 m4_include(logfile.m4)
33 m4_include(loglevel.m4)
34 m4_include(log-timing.m4)
36 m4_include(per-command-options-section.m4)
39 summary = listening port of the paraslash control service
40 arg_info = required_arg
45 para_server listens on this TCP port for incoming connections
46 from clients such as para_client. If the default port is changed,
47 the corresponding option of para_client must be used to connect
51 summary = file which contains user names and credentials
52 arg_info = required_arg
56 This file contains one line per user of the form
58 user <username> <key> <perms>
60 See the manual for more information.
63 summary = Options for the virtual streaming system
66 summary = start streaming on startup
69 The default is to defer streaming until para_client connects and
70 executes the "play" command.
72 [option autoplay-delay]
73 summary = time to wait before streaming
74 arg_info = required_arg
76 typestr = milliseconds
79 This option is ignored if --autplay is not given. Otherwise, its
80 argument defines for how long streaming is delayed at startup.
82 This is useful in init scripts to set the delay large enough to make
83 sure para_audiod is up when para_server starts to stream.
85 [option announce-time]
87 summary = grace time for data connections
88 arg_info = required_arg
90 typestr = milliseconds
93 para_server tells para_audiod through the control service connection
94 whether an audio stream is currently available. This option defines
95 the delay between announcing the stream and sending the first chunk
99 summary = Options for the audio file selector
101 [option afs-database-dir]
102 summary = location of the afs database
104 arg_info = required_arg
108 The directory which contains the database for the audio file
109 selector. The default is ~/.paraslash/afs_database-0.4.
111 If no database was found, the "init" command must be executed to
112 initialize the database. Once initialized, audio files may added with
116 summary = socket for afs connections
118 arg_info = required_arg
121 default_val = /var/paraslash/afs_command_socket-0.4
123 Server commands communicate with the audio file selector, via a
124 local socket. This option specifies the location of the socket in
127 [option afs-initial-mode]
128 summary = mood or playlist to load on startup
130 arg_info = required_arg
132 typestr = specifier/name
134 The argument of this option consists of a prefix, either 'm/' or
135 'p/', to indicate whether a mood or a playlist should be loaded,
136 followed by the name of the mood or playlist. Example:
138 --afs-initial-mode p/foo
140 loads the playlist named "foo".
142 If this option is not given, the dummy mood is loaded at startup.
145 summary = Options for the http sender
148 summary = TCP port for http streaming
149 arg_info = required_arg
154 The http sender of para_server listens on this port for incoming
155 connections. Clients are expected to send the usual http request
156 message such as 'GET / HTTP/'.
158 [option http-default-deny]
159 summary = make the http access control list a whitelist
161 The default is to use blacklists, i.e. connections to the http sender
162 are allowed unless the connecting host matches a pattern given by a
163 http-access option. This allows to use access control the other way
164 round: Connections are denied from hosts which are not explicitly
165 allowed by one or more http-access options.
168 summary = add an entry to the http access control list
169 arg_info = required_arg
174 Add the given host/network to access control list (whitelist if
175 http-default-deny was given, blacklist otherwise) before opening
176 the tcp port. This option can be given multiple times. Example:
178 --http-access 192.168.0.0/24
180 whitelists/blacklists the 256 hosts 192.168.0.x.
182 This option may be given multiple times to blacklist/whitelist any
183 number of hosts or networks.
185 [option http-no-autostart]
186 summary = do not open TCP port for http streaming on startup
188 If this option is given, the http sender does not listen on its TCP
189 port until the "sender" command is executed to open the port.
191 [option http-max-clients]
192 summary = maximal number of simultaneous http connections
193 arg_info = required_arg
198 The http sender will refuse connections if already that number of
199 clients are currently connected. A non-positive value (the default)
200 allows for an unlimited number of simultaneous connections.
203 summary = Options for the dccp sender
206 summary = port for dccp streaming
207 arg_info = required_arg
212 See --http-port for details.
214 [option dccp-default-deny]
215 summary = make the dccp access control list a whitelist
217 See http-default-deny for details.
220 summary = add an entry to the dccp access control list
221 arg_info = required_arg
226 See --http-access for details.
228 [option dccp-max-clients]
229 summary = maximal number of simultaneous dccp connections
230 arg_info = required_arg
235 See --http-max-clients for details.
237 [option dccp-max-slice-size]
238 summary = upper bound for the FEC slice size
239 arg_info = required_arg
244 If this value is zero (the default) the dccp sender uses the maximum
245 packet size (MPS) of the connection as the slice size. The MPS is a
246 network parameter and depends on the path maximum transmission unit
247 (path MTU) of an incoming connection, i.e. on the largest packet size
248 that can be transmitted without causing fragmentation.
250 This option allows to use a value less than the MPS in order to
251 fine-tune application performance. Values greater than the MPS of an
252 incoming connection can not be set.
254 [option dccp-data-slices-per-group]
255 summary = the number of non-redundant slices per FEC group
256 arg_info = required_arg
261 This determines the number of slices in each FEC group which are
262 necessary to decode the group. The given number must be smaller than
263 the argument to the --dccp-slices-per-group option below.
265 Note that the duration of a FEC group is proportional to the
266 product dccp-max-slice-size * dccp-data-slices-per-group.
268 [option dccp-slices-per-group]
269 summary = the total number of slices per FEC group
270 arg_info = required_arg
275 This value must be larger than the value of the argument to
276 --dccp-data-slices-per-group. The difference of the two values is
277 the number of redundant slices, that is, the number of slices which
278 may be lost without causing interruptions in the audio stream.
280 Increase this value if you are on a lossy network.
283 summary = Options for the udp sender
286 summary = add udp target with optional port
287 arg_info = required_arg
289 typestr = host[:port]
292 Add the given host/port to the list of targets. The "host" argument
293 can be either an IPv4/v6 address or hostname (RFC 3986 syntax). The
294 "port" argument is an optional port number. If the "port" part is
295 absent, the "--udp-default-port" value (see below) is used.
297 The following examples are possible targets: "10.10.1.2:8000"
298 (host:port); "10.10.1.2" (with default port); "224.0.1.38:1500"
299 (IPv4 multicast); "localhost:8001" (hostname with port); "[::1]:8001"
300 (IPv6 localhost); "[badc0de::1]" (IPv6 host with default port);
301 "[FF00::beef]:1500" (IPv6 multicast).
303 This option can be given multiple times, for multiple targets.
305 [option udp-default-port]
306 summary = default port for udp targets
307 arg_info = required_arg
311 [option udp-no-autostart]
312 summary = do not send the audio stream to UDP targets
314 If this option is given, udp streaming may be activated at a later
315 time by executing the "sender" command.
317 [option udp-mcast-iface]
318 summary = outgoing udp multicast interface
319 arg_info = required_arg
322 [option udp-header-interval]
324 summary = duration for sending header
325 arg_info = required_arg
327 typestr = milliseconds
330 As the udp sender has no idea about connected clients it sends the
331 audio file header periodically if necessary. This option specifies the
332 duration between subsequent headers are sent. Smaller values decrease
333 the average time clients have to wait before starting playback,
334 larger values decrease network traffic.
336 Note that this affects only ogg/* and wma streams. Other audio formats,
337 including mp3, don't need an audio file header.
341 summary = set time to live value
342 arg_info = required_arg
347 This option applies exclusively to multicast UDPv4/v6 streaming.
349 For the sending UDPv4 socket it sets the multicast Time-To-Live value
350 to "num". Traditional TTL scope values are: 0=host, 1=network, 32=same
351 site, 64=same region, 128=same continent, 255=unrestricted. Please
352 note however that this scoping is not a good solution: RFC 2365
353 e.g. presents a better alternative.
355 When using UDPv6 multicasting, the option sets the number of multicast
356 hops (as described in RFC 3493); a value of -1 allows the kernel to
357 auto-select the hop value.