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 option allows using access control lists
			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 values 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]