+m4_define(PROGRAM, para_server)
+m4_define(DEFAULT_CONFIG_FILE, ~/.paraslash/server.conf)
+[suite server]
+version-string = GIT_VERSION()
+[supercommand para_server]
+ purpose = manage and stream audio files
+ [description]
+ para_server streams audio files over a local or remote network. It
+ is controlled by para_client(1), which connects para_server through
+ the paraslash control service.
+
+ On startup the server spawns a second process, the audio file selector,
+ which maintains the database of all known audio files. This database
+ contains file format, duration and tag information of each known file
+ and statistics such as last-played time, and the number of times each
+ file was streamed. Lyrics and cover art may be added to the database
+ and associated with one or more audio files.
+
+ Besides ordinary playlists the audio file selector supports so-called
+ moods. Moods instruct the server to determine the files to be streamed
+ and their order in terms of properties stored in the database.
+ [/description]
+ m4_include(common-option-section.m4)
+ m4_include(help.m4)
+ m4_include(detailed-help.m4)
+ m4_include(version.m4)
+ m4_include(config-file.m4)
+ m4_include(priority.m4)
+ m4_include(daemon.m4)
+ m4_include(logfile.m4)
+ m4_include(user.m4)
+ m4_include(group.m4)
+ m4_include(loglevel.m4)
+ m4_include(log-timing.m4)
+ m4_include(color.m4)
+ m4_include(per-command-options-section.m4)
+ [option port]
+ short_opt = p
+ summary = listening port of the paraslash control service
+ arg_info = required_arg
+ arg_type = uint32
+ typestr = portnumber
+ default_val = 2990
+ [help]
+ para_server listens on this TCP port for incoming connections
+ from clients such as para_client. If the default port is changed,
+ the corresponding option of para_client must be used to connect
+ to para_server.
+ [/help]
+ [option user-list]
+ summary = file which contains user names and credentials
+ arg_info = required_arg
+ arg_type = string
+ typestr = path
+ [help]
+ This file contains one line per user of the form
+
+ user <username> <key> <perms>
+
+ See the manual for more information.
+ [/help]
+ [option vss]
+ summary = Options for the virtual streaming system
+ flag ignored
+ [option autoplay]
+ summary = start streaming on startup
+ short_opt = a
+ [help]
+ The default is to defer streaming until para_client connects and
+ executes the "play" command.
+ [/help]
+ [option autoplay-delay]
+ summary = time to wait before streaming
+ arg_info = required_arg
+ arg_type = uint32
+ typestr = milliseconds
+ default_val = 0
+ [help]
+ This option is ignored if --autplay is not given. Otherwise, its
+ argument defines for how long streaming is delayed at startup.
+
+ This is useful in init scripts to set the delay large enough to make
+ sure para_audiod is up when para_server starts to stream.
+ [/help]
+ [option announce-time]
+ short_opt = A
+ summary = grace time for data connections
+ arg_info = required_arg
+ arg_type = uint32
+ typestr = milliseconds
+ default_val = 300
+ [help]
+ para_server tells para_audiod through the control service connection
+ whether an audio stream is currently available. This option defines
+ the delay between announcing the stream and sending the first chunk
+ of audio data.
+ [/help]
+ [option afs]
+ summary = Options for the audio file selector
+ flag ignored
+ [option afs-database-dir]
+ summary = location of the afs database
+ short_opt = D
+ arg_info = required_arg
+ arg_type = string
+ typestr = directory
+ [help]
+ The directory which contains the database for the audio file
+ selector. The default is ~/.paraslash/afs_database-0.4.
+
+ If no database was found, the "init" command must be executed to
+ initialize the database. Once initialized, audio files may added with
+ the "add" command.
+ [/help]
+ [option afs-socket]
+ summary = socket for afs connections
+ short_opt = s
+ arg_info = required_arg
+ arg_type = string
+ typestr = path
+ default_val = /var/paraslash/afs_command_socket-0.4
+ [help]
+ Server commands communicate with the audio file selector, via a
+ local socket. This option specifies the location of the socket in
+ the file system.
+ [/help]
+ [option afs-initial-mode]
+ summary = mood or playlist to load on startup
+ short_opt = i
+ arg_info = required_arg
+ arg_type = string
+ typestr = specifier/name
+ [help]
+ The argument of this option consists of a prefix, either 'm/' or
+ 'p/', to indicate whether a mood or a playlist should be loaded,
+ followed by the name of the mood or playlist. Example:
+
+ --afs-initial-mode p/foo
+
+ loads the playlist named "foo".
+
+ If this option is not given, the dummy mood is loaded at startup.
+ [/help]
+ [option http]
+ summary = Options for the http sender
+ flag ignored
+ [option http-port]
+ summary = TCP port for http streaming
+ arg_info = required_arg
+ arg_type = uint32
+ typestr = portnumber
+ default_val = 8000
+ [help]
+ The http sender of para_server listens on this port for incoming
+ connections. Clients are expected to send the usual http request
+ message such as 'GET / HTTP/'.
+ [/help]
+ [option http-default-deny]
+ summary = make the http access control list a whitelist
+ [help]
+ The default is to use blacklists, i.e. connections to the http sender
+ are allowed unless the connecting host matches a pattern given by a
+ http-access option. This allows to use access control the other way
+ round: Connections are denied from hosts which are not explicitly
+ allowed by one or more http-access options.
+ [/help]
+ [option http-access]
+ summary = add an entry to the http access control list
+ arg_info = required_arg
+ arg_type = string
+ typestr = a.b.c.d/n
+ flag multiple
+ [help]
+ Add the given host/network to access control list (whitelist if
+ http-default-deny was given, blacklist otherwise) before opening
+ the tcp port. This option can be given multiple times. Example:
+
+ --http-access 192.168.0.0/24
+
+ whitelists/blacklists the 256 hosts 192.168.0.x.
+
+ This option may be given multiple times to blacklist/whitelist any
+ number of hosts or networks.
+ [/help]
+ [option http-no-autostart]
+ summary = do not open TCP port for http streaming on startup
+ [help]
+ If this option is given, the http sender does not listen on its TCP
+ port until the "sender" command is executed to open the port.
+ [/help]
+ [option http-max-clients]
+ summary = maximal number of simultaneous http connections
+ arg_info = required_arg
+ arg_type = int32
+ typestr = number
+ default_val = -1
+ [help]
+ The http sender will refuse connections if already that number of
+ clients are currently connected. A non-positive value (the default)
+ allows for an unlimited number of simultaneous connections.
+ [/help]
+ [option dccp]
+ summary = Options for the dccp sender
+ flag ignored
+ [option dccp-port]
+ summary = port for dccp streaming
+ arg_info = required_arg
+ arg_type = uint32
+ typestr = portnumber
+ default_val = 8000
+ [help]
+ See --http-port for details.
+ [/help]
+ [option dccp-default-deny]
+ summary = make the dccp access control list a whitelist
+ [help]
+ See http-default-deny for details.
+ [/help]
+ [option dccp-access]
+ summary = add an entry to the dccp access control list
+ arg_info = required_arg
+ arg_type = string
+ typestr = a.b.c.d/n
+ flag multiple
+ [help]
+ See --http-access for details.
+ [/help]
+ [option dccp-max-clients]
+ summary = maximal number of simultaneous dccp connections
+ arg_info = required_arg
+ arg_type = int32
+ typestr = number
+ default_val = -1
+ [help]
+ See --http-max-clients for details.
+ [/help]
+ [option dccp-max-slice-size]
+ summary = upper bound for the FEC slice size
+ arg_info = required_arg
+ arg_type = uint32
+ typestr = bytes
+ default_val = 0
+ [help]
+ If this value is zero (the default) the dccp sender uses the maximum
+ packet size (MPS) of the connection as the slice size. The MPS is a
+ network parameter and depends on the path maximum transmission unit
+ (path MTU) of an incoming connection, i.e. on the largest packet size
+ that can be transmitted without causing fragmentation.
+
+ This option allows to use a value less than the MPS in order to
+ fine-tune application performance. Values greater than the MPS of an
+ incoming connection can not be set.
+ [/help]
+ [option dccp-data-slices-per-group]
+ summary = the number of non-redundant slices per FEC group
+ arg_info = required_arg
+ arg_type = uint32
+ typestr = count
+ default_val = 3
+ [help]
+ This determines the number of slices in each FEC group which are
+ necessary to decode the group. The given number must be smaller than
+ the argument to the --dccp-slices-per-group option below.
+
+ Note that the duration of a FEC group is proportional to the
+ product dccp-max-slice-size * dccp-data-slices-per-group.
+ [/help]
+ [option dccp-slices-per-group]
+ summary = the total number of slices per FEC group
+ arg_info = required_arg
+ arg_type = uint32
+ typestr = count
+ default_val = 4
+ [help]
+ This value must be larger than the value of the argument to
+ --dccp-data-slices-per-group. The difference of the two values is
+ the number of redundant slices, that is, the number of slices which
+ may be lost without causing interruptions in the audio stream.
+
+ Increase this value if you are on a lossy network.
+ [/help]
+ [option udp]
+ summary = Options for the udp sender
+ flag ignored
+ [option udp-target]
+ summary = add udp target with optional port
+ arg_info = required_arg
+ arg_type = string
+ typestr = host[:port]
+ flag multiple
+ [help]
+ Add the given host/port to the list of targets. The "host" argument
+ can be either an IPv4/v6 address or hostname (RFC 3986 syntax). The
+ "port" argument is an optional port number. If the "port" part is
+ absent, the "--udp-default-port" value (see below) is used.
+
+ The following examples are possible targets: "10.10.1.2:8000"
+ (host:port); "10.10.1.2" (with default port); "224.0.1.38:1500"
+ (IPv4 multicast); "localhost:8001" (hostname with port); "[::1]:8001"
+ (IPv6 localhost); "[badc0de::1]" (IPv6 host with default port);
+ "[FF00::beef]:1500" (IPv6 multicast).
+
+ This option can be given multiple times, for multiple targets.
+ [/help]
+ [option udp-default-port]
+ summary = default port for udp targets
+ arg_info = required_arg
+ arg_type = uint32
+ typestr = portnumber
+ default_val = 8000
+ [option udp-no-autostart]
+ summary = do not send the audio stream to UDP targets
+ [help]
+ If this option is given, udp streaming may be activated at a later
+ time by executing the "sender" command.
+ [/help]
+ [option udp-mcast-iface]
+ summary = outgoing udp multicast interface
+ arg_info = required_arg
+ arg_type = string
+ typestr = interface
+ [option udp-header-interval]
+ short_opt = H
+ summary = duration for sending header
+ arg_info = required_arg
+ arg_type = uint32
+ typestr = milliseconds
+ default_val = 2000
+ [help]
+ As the udp sender has no idea about connected clients it sends the
+ audio file header periodically if necessary. This option specifies the
+ duration between subsequent headers are sent. Smaller values decrease
+ the average time clients have to wait before starting playback,
+ larger values decrease network traffic.
+
+ Note that this affects only ogg/* and wma streams. Other audio formats,
+ including mp3, don't need an audio file header.
+ [/help]
+ [option udp-ttl]
+ short_opt = t
+ summary = set time to live value
+ arg_info = required_arg
+ arg_type = int32
+ typestr = num
+ default_val = -1
+ [help]
+ This option applies exclusively to multicast UDPv4/v6 streaming.
+
+ For the sending UDPv4 socket it sets the multicast Time-To-Live value
+ to "num". Traditional TTL scope values are: 0=host, 1=network, 32=same
+ site, 64=same region, 128=same continent, 255=unrestricted. Please
+ note however that this scoping is not a good solution: RFC 2365
+ e.g. presents a better alternative.
+
+ When using UDPv6 multicasting, the option sets the number of multicast
+ hops (as described in RFC 3493); a value of -1 allows the kernel to
+ auto-select the hop value.
+ [/help]